From a491befb052b310d22746949bb4d7153b01887f9 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 23 Jul 2026 12:27:44 +0200
Subject: [PATCH 01/77] CSS API: Add CSS token processor foundations

---
 .../css-api/class-wp-css-builder.php          |  261 +
 .../css-api/class-wp-css-token-processor.php  | 1863 ++++++
 src/wp-settings.php                           |    2 +
 .../phpunit/data/css-api/css-test-cases.json  | 4988 +++++++++++++++++
 tests/phpunit/tests/css-api/wpCssBuilder.php  |  150 +
 .../tests/css-api/wpCssTokenProcessor.php     | 2809 ++++++++++
 6 files changed, 10073 insertions(+)
 create mode 100644 src/wp-includes/css-api/class-wp-css-builder.php
 create mode 100644 src/wp-includes/css-api/class-wp-css-token-processor.php
 create mode 100644 tests/phpunit/data/css-api/css-test-cases.json
 create mode 100644 tests/phpunit/tests/css-api/wpCssBuilder.php
 create mode 100644 tests/phpunit/tests/css-api/wpCssTokenProcessor.php

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
new file mode 100644
index 0000000000000..35250335da661
--- /dev/null
+++ b/src/wp-includes/css-api/class-wp-css-builder.php
@@ -0,0 +1,261 @@
+<?php
+
+abstract class WP_CSS_Builder {
+	/**
+	 * Create a CSS ident token from a plain PHP string value.
+	 *
+	 * Characters not valid in CSS identifiers are hex-escaped. This uses
+	 * the same safety escaping as {@see WP_CSS_Builder::string()} for HTML
+	 * and CSS-sensitive characters, plus escaping of whitespace and other
+	 * characters not permitted in idents.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 *
+	 * @param string $value Decoded string value to encode as a CSS ident.
+	 * @return string CSS ident token text.
+	 */
+	public static function ident( string $value ): string {
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			// NULL → U+FFFD REPLACEMENT CHARACTER.
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
+			if ( $byte >= 0x80 ) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// ASCII letters and underscore: always valid in idents.
+			if (
+				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
+				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
+				0x5F === $byte                         // _
+			) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// Hyphen: valid in idents, but check for hyphen-digit at start.
+			if ( 0x2D === $byte ) {
+				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
+				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
+					$result .= '-';
+					++$i;
+					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
+					continue;
+				}
+				$result .= '-';
+				continue;
+			}
+
+			// Digits: valid except at position 0.
+			if ( $byte >= 0x30 && $byte <= 0x39 ) {
+				if ( 0 === $i ) {
+					$result .= sprintf( '\\%X ', $byte );
+				} else {
+					$result .= $value[ $i ];
+				}
+				continue;
+			}
+
+			// Everything else: hex-escape.
+			$result .= sprintf( '\\%X ', $byte );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Create a quoted CSS string from a plain PHP string value.
+	 *
+	 * Example:
+	 *     $value = 'CSS & a "<style>" tag\'s strings';
+	 *     $css_string = WP_CSS_Builder::string( $value );
+	 *     echo "<style>*::before { content: {$css_string}; }</style>";
+	 *
+	 * CSS strings are quoted many characters that are problematic in HTML
+	 * or may be complicated for rudimentary CSS or HTML processors to handle
+	 * are encoded using Unicode escape sequences.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 */
+	public static function string( string $value ): string {
+		$value   = wp_scrub_utf8( $value );
+		$escaped = strtr(
+			$value,
+			array(
+				// Escape existing backslashes to prevent unintentional escapes in result.
+				'\\'   => '\\5C ',
+
+				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
+				"\0"   => "\u{FFFD}",
+
+				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+				"\r\n" => '\\A ',
+				"\r"   => '\\A ',
+				"\f"   => '\\A ',
+
+				// Newlines must be escaped in CSS strings.
+				"\n"   => '\\A ',
+
+				// Arbitrary characters for Unicode escaping:
+
+				// HTML syntax may be problematic.
+				'<'    => '\\3C ',
+				'>'    => '\\3E ',
+				'&'    => '\\26 ',
+
+				// CSS syntax may be problematic.
+				','    => '\\2C ',
+				';'    => '\\3B ',
+				'{'    => '\\7B ',
+				'}'    => '\\7D ',
+				'"'    => '\\22 ',
+				"'"    => '\\27 ',
+			)
+		);
+		return "\"{$escaped}\"";
+	}
+
+	public static function normalize_and_escape_css( string $css ): string {
+		$css       = wp_scrub_utf8( $css );
+		$processor = WP_CSS_Token_Processor::create( $css );
+		if ( null === $processor ) {
+			return '';
+		}
+
+		$normalized_css = '';
+
+		while ( $processor->next_token() ) {
+			switch ( $processor->get_token_type() ) {
+
+				// Basic punctuation:
+				case WP_CSS_Token_Processor::TOKEN_SEMICOLON:
+					$normalized_css .= ';';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_COMMA:
+					$normalized_css .= ',';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_WHITESPACE:
+					$normalized_css .= ' ';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_COLON:
+					$normalized_css .= ':';
+					break;
+
+				// Paired punctuation:
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACE:
+					$normalized_css .= '{';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE:
+					$normalized_css .= '}';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_LEFT_PAREN:
+					$normalized_css .= '(';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN:
+					$normalized_css .= ')';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET:
+					$normalized_css .= '[';
+					break;
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET:
+					$normalized_css .= ']';
+					break;
+
+				// "@" + ident
+				case WP_CSS_Token_Processor::TOKEN_AT_KEYWORD:
+					$normalized_css .= '@' . self::ident( $processor->get_token_value() );
+					break;
+
+				// ident + "("
+				case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+					$normalized_css .= self::ident( $processor->get_token_value() ) . '(';
+					break;
+
+				/*
+				 * Hash tokens are not idents but their value can be escaped as such.
+				 *
+				 *     ‖→ "#" →─┐   ┌──────────────────────────────┐   ┌─→‖
+				 *              ├─→─┤ a-z A-Z 0-9 _ - or non-ASCII ├─→─┤
+				 *              │   └──────────────────────────────┘   │
+				 *              │   ┌──────────────────────────────┐   │
+				 *              ├─→─┤            escape            ├─→─┤
+				 *              │   └──────────────────────────────┘   │
+				 *              └──────────────────←───────────────────┘
+				 */
+				case WP_CSS_Token_Processor::TOKEN_HASH:
+					$normalized_css .= '#' . self::ident( $processor->get_token_value() );
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_DIMENSION:
+					$normalized_css .= $processor->get_token_value() . $processor->get_token_unit();
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_PERCENTAGE:
+					$normalized_css .= "%{$processor->get_token_value()}";
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_NUMBER:
+					$normalized_css .= $processor->get_token_value();
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_DELIM:
+					$normalized_css .= $processor->get_token_value();
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_IDENT:
+					$normalized_css .= self::ident( $processor->get_token_value() );
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_STRING:
+					var_dump( $processor->get_token_value() );
+					$normalized_css .= self::string( $processor->get_token_value() );
+					break;
+
+				// Keep or strip comments?
+				case WP_CSS_Token_Processor::TOKEN_COMMENT:
+					$normalized_css .= substr( $css, $processor->get_token_start(), $processor->get_token_length() );
+					break;
+
+				/**
+				 * A <bad-string-token> is an open string that reaches a newline.
+				 *
+				 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+				 *
+				 * @see https://www.w3.org/TR/css-syntax-3/#preserved-tokens
+				 * > Note: The tokens <}-token>s, <)-token>s, <]-token>, <bad-string-token>, and <bad-url-token> are always parse errors, but they are preserved in the token stream by this specification to allow other specs, such as Media Queries, to define more fine-grained error-handling than just dropping an entire declaration or block.
+				 */
+				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
+					$normalized_css .= substr( $css, $processor->get_token_start(), $processor->get_token_length() ) . "\n";
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_URL:
+				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
+				case WP_CSS_Token_Processor::TOKEN_CDC:
+				case WP_CSS_Token_Processor::TOKEN_CDO:
+				default:
+					throw new Error( 'unhandled token type ' . $processor->get_token_type() . ' with value ' . var_export( $processor->get_token_value(), true ) );
+			}
+		}
+
+		return strtr(
+			$normalized_css,
+			array(
+				' '  => '␠',
+				"\t" => "␉\t",
+				"\n" => "␊\n",
+			)
+		);
+	}
+}
diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
new file mode 100644
index 0000000000000..74c548dc1ec3a
--- /dev/null
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -0,0 +1,1863 @@
+<?php
+
+/**
+ * Tokenizes CSS according to the CSS Syntax Level 3 specification.
+ *
+ * This class follows the algorithm in https://www.w3.org/TR/css-syntax-3/ and
+ * exposes a pull-based API so callers can stream over large stylesheets without
+ * allocating every token up front. Each call to next_token() advances the cursor
+ * and fills in metadata (type, value, raw slice, byte offsets) that you can read
+ * through the getter methods.
+ *
+ * ## Design choices
+ *
+ * ### On-the-fly normalization
+ *
+ * The CSS Spec requires the following normalization step:
+ *
+ * > Replace any U+000D CARRIAGE RETURN (CR) code points, U+000C FORM FEED (FF)
+ * > code points, or pairs of U+000D CARRIAGE RETURN (CR) followed by U+000A LINE
+ * > FEED (LF) in input by a single U+000A LINE FEED (LF) code point.
+ * > Replace any U+0000 NULL or surrogate code points in input with U+FFFD REPLACEMENT
+ * > CHARACTER (�).
+ *
+ * This processor delays normalization as much as possible. That keeps the raw byte
+ * positions intact for accurate rewrites while still letting consumers ask for a
+ * normalized token when they need one.
+ *
+ * ### No EOF token
+ *
+ * The EOF token is a CSS parsing concept, not CSS tokenization concept. Therefore,
+ * this processor does not produce it.
+ *
+ * ### UTF-8 handling
+ *
+ * Only UTF-8 strings are supported. Invalid sequences are replaced with U+FFFD (�)
+ * using the maximal subpart approach described in
+ * https://www.unicode.org/versions/Unicode9.0.0/ch03.pdf, section 3.9 Best Practices
+ * for Using U+FFFD.
+ *
+ * ## Usage
+ *
+ * Basic iteration:
+ *
+ *     $css = 'width: 10px;';
+ *     $processor = WP_CSS_Token_Processor::create( $css );
+ *     while ( $processor->next_token() ) {
+ *         echo $processor->get_normalized_token();
+ *     }
+ *     // Outputs:
+ *     // width: 10px;
+ *
+ * Rewriting a URL while keeping the rest of the stylesheet intact:
+ *
+ *     $css = 'background: url(old.jpg) center / cover;';
+ *     $processor = WP_CSS_Token_Processor::create( $css );
+ *     while ( $processor->next_token() ) {
+ *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+ *             $processor->set_value( 'uploads/new.jpg' );
+ *         }
+ *     }
+ *     $result = $processor->get_updated_css();
+ *     // background: url(uploads/new.jpg) center / cover;
+ *
+ * Gathering diagnostics with byte offsets:
+ *
+ *     $css = "color: red;\ncolor: re\nd;";
+ *     $processor = WP_CSS_Token_Processor::create( $css );
+ *     $bad_strings = array();
+ *     while ( $processor->next_token() ) {
+ *         if ( WP_CSS_Token_Processor::TOKEN_BAD_STRING === $processor->get_token_type() ) {
+ *             $bad_strings[] = array(
+ *                 'start'  => $processor->get_token_start(),
+ *                 'length' => $processor->get_token_length(),
+ *                 'value'  => $processor->get_unnormalized_token(),
+ *             );
+ *         }
+ *     }
+ *
+ * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+ */
+class WP_CSS_Token_Processor {
+	/**
+	 * Token type constants matching the CSS Syntax Level 3 specification.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+	 */
+	public const TOKEN_WHITESPACE = 'whitespace-token';
+	public const TOKEN_COMMENT    = 'comment';
+	public const TOKEN_STRING     = 'string-token';
+
+	/**
+	 * BAD-STRING tokens occur when a string contains an unescaped newline.
+	 *
+	 * Valid strings: "hello", 'world', "line1\Aline2" (escaped newline)
+	 * Invalid (produces bad-string): "hello
+	 *                                 world"  (literal newline breaks the string)
+	 *
+	 * The processor stops at the newline and produces a bad-string token for error recovery.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-bad-string-token
+	 */
+	public const TOKEN_BAD_STRING        = 'bad-string-token';
+	public const TOKEN_HASH              = 'hash-token';
+	public const HASH_TOKEN_ID           = 'id';
+	public const HASH_TOKEN_UNRESTRICTED = 'unrestricted';
+	public const TOKEN_DELIM             = 'delim-token';
+	public const TOKEN_NUMBER            = 'number-token';
+	public const TOKEN_PERCENTAGE        = 'percentage-token';
+	public const TOKEN_DIMENSION         = 'dimension-token';
+	public const TOKEN_AT_KEYWORD        = 'at-keyword-token';
+	public const TOKEN_COLON             = 'colon-token';
+	public const TOKEN_SEMICOLON         = 'semicolon-token';
+	public const TOKEN_COMMA             = 'comma-token';
+	public const TOKEN_LEFT_PAREN        = '(-token';
+	public const TOKEN_RIGHT_PAREN       = ')-token';
+	public const TOKEN_LEFT_BRACKET      = '[-token';
+	public const TOKEN_RIGHT_BRACKET     = ']-token';
+	public const TOKEN_LEFT_BRACE        = '{-token';
+	public const TOKEN_RIGHT_BRACE       = '}-token';
+	public const TOKEN_FUNCTION          = 'function-token';
+
+	/**
+	 * URL tokens represent unquoted URLs in url() notation.
+	 *
+	 * For example, `url(image.jpg)` is a URL token.
+	 *
+	 * Quoted URLs like `url( "https://example.com" )` are handled as a function
+	 * token, _not_ a URL token.
+	 *
+	 * Bad URL tokens are created when invalid characters are encountered in
+	 * a URL token.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-url-token
+	 */
+	public const TOKEN_URL = 'url-token';
+
+	/**
+	 * BAD-URL tokens occur when a URL contains invalid characters.
+	 *
+	 * Invalid characters: quotes ("), apostrophes ('), parentheses (()
+	 * Example invalid: url(image(.jpg) or url(image".jpg)
+	 *
+	 * When detected, the processor consumes everything up to ) or EOF.
+	 * This prevents the bad URL from breaking subsequent tokens.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-bad-url-token
+	 */
+	public const TOKEN_BAD_URL = 'bad-url-token';
+
+	/**
+	 * Identifier tokens, such as `color`, `margin-top`, `red`,
+	 * `inherit`, `--my-var`, `\x-escaped`, `über` (Unicode), etc.
+	 *
+	 * There are restrictions on the codepoints that start or are contained in
+	 * an identifier, and identifiers may contain escape sequences.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-ident-token
+	 */
+	public const TOKEN_IDENT = 'ident-token';
+
+	/**
+	 * CDC (Comment Delimiter Close) token: -->
+	 *
+	 * Legacy token from when CSS was embedded in HTML <style> tags
+	 * and needed to be hidden from old browsers using HTML comments:
+	 *
+	 *   <style>
+	 *   <!--
+	 *   body { color: red; }
+	 *   -->
+	 *   </style>
+	 *
+	 * Modern CSS no longer needs these, but they're preserved for compatibility.
+	 * In stylesheets, they're typically treated like whitespace.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-CDC-token
+	 */
+	public const TOKEN_CDC = 'CDC-token';
+
+	/**
+	 * CDO (Comment Delimiter Open) token: <!--
+	 *
+	 * Legacy token from when CSS was embedded in HTML <style> tags.
+	 * See TOKEN_CDC for full explanation of HTML comment compatibility.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-CDO-token
+	 */
+	public const TOKEN_CDO = 'CDO-token';
+
+	/**
+	 * @var string
+	 */
+	private $css;
+
+	/**
+	 * @var int
+	 */
+	private $length = 0;
+
+	/**
+	 * @var int
+	 */
+	private $at = 0;
+
+	/**
+	 * The type of the current token. One of the self::TOKEN_* constants.
+	 *
+	 * @var string|null
+	 * @phpstan-var self::TOKEN_*|null
+	 */
+	private $token_type = null;
+
+	/**
+	 * The type flag for the current token, if any.
+	 *
+	 * Hash tokens carry an "id" or "unrestricted" flag. Per CSS Syntax Level 3,
+	 * <number-token> and <dimension-token> have a type flag indicating whether
+	 * the number was written as an integer or a number (with decimal point or
+	 * exponent). <percentage-token> does not have a type flag.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 *
+	 * @var string|null
+	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
+	 */
+	private $token_type_flag = null;
+
+	/**
+	 * The byte offset at which the current token starts.
+	 *
+	 * Example:
+	 *
+	 * background-image: url(https://example.com/image.jpg);
+	 *                   ^ token_starts_at
+	 *
+	 * @var int|null
+	 */
+	private $token_starts_at = null;
+
+	/**
+	 * The byte length of the current token.
+	 *
+	 * Example:
+	 *
+	 * background-image: url(https://example.com/image.jpg);
+	 *                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+	 *                             token_length
+	 *
+	 * @var int|null
+	 */
+	private $token_length = null;
+
+	/**
+	 * The byte offset at which the value of the current token starts.
+	 *
+	 * It is used for STRING and URL tokens. For example:
+	 *
+	 * background-image: url(https://example.com/image.jpg);
+	 *                       ^ token_value_starts_at
+	 *
+	 * @var int|null
+	 */
+	private $token_value_starts_at = null;
+
+	/**
+	 * The byte offset at which the value of the current token starts.
+	 *
+	 * It is relevant for STRING and URL tokens. For example:
+	 *
+	 * background-image: url(https://example.com/image.jpg);
+	 *                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+	 *                             token_value_length
+	 *
+	 * @var int|null
+	 */
+	private $token_value_length = null;
+
+	/**
+	 * A cache for the decoded and normalized token value.
+	 *
+	 * - `false` indicates that the value has not been computed.
+	 * - `null` is used for token types without an associated value: whitespace,
+	 *   bad-url, comment, punctuation, etc.
+	 * - `string` is used for token types with an associated value: ident, string,
+	 *   function, url, etc.
+	 *
+	 * @var string|null|false
+	 */
+	private $token_value = false;
+
+	/**
+	 * The unit of the current token, e.g. "px", "em", "deg", etc.
+	 *
+	 * @var string|null
+	 */
+	private $token_unit = null;
+
+	/**
+	 * Lexical replacements to apply to input CSS document.
+	 *
+	 * Tracks modifications to be applied to the CSS, such as changing URL values.
+	 * Each entry is an associative array with 'start', 'length', and 'text' keys.
+	 *
+	 * @var array[]
+	 */
+	private $lexical_updates = array();
+
+	/**
+	 * Constructor for the CSS processor.
+	 *
+	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
+	 *
+	 * @param string $css         CSS source to tokenize.
+	 */
+	private function __construct( string $css ) {
+		$this->css    = $css;
+		$this->length = strlen( $css );
+	}
+
+	/**
+	 * Creates a CSS processor for the given CSS string.
+	 *
+	 * Use this method to create a CSS processor instance.
+	 *
+	 * ## Current Support
+	 *
+	 * - The only supported document encoding is `UTF-8`, which is the default value.
+	 *
+	 * @param string $css      CSS source to tokenize.
+	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
+	 * @return static|null The created processor if successful, otherwise null.
+	 */
+	public static function create( string $css, string $encoding = 'UTF-8' ) {
+		if ( 'UTF-8' !== $encoding ) {
+			return null;
+		}
+
+		return new static( $css );
+	}
+
+	/**
+	 * Moves to the next token in the CSS stream.
+	 *
+	 * Implements the main tokenization loop, consuming the next token from the input stream.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+	 *
+	 * @return bool Whether a token was found.
+	 */
+	public function next_token(): bool {
+		$this->after_token();
+
+		// Bale out once we reach the end.
+		if ( $this->at >= $this->length ) {
+			return false;
+		}
+
+		/*
+		 * CSS comments. They are not preserved as tokens in the specification, but we
+		 * still track them.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#consume-comment
+		 */
+		if (
+			$this->at + 1 < $this->length &&
+			'/' === $this->css[ $this->at ] &&
+			'*' === $this->css[ $this->at + 1 ]
+		) {
+			$this->token_type            = self::TOKEN_COMMENT;
+			$this->token_starts_at       = $this->at;
+			$this->token_value_starts_at = $this->at;
+
+			$end                      = strpos( $this->css, '*/', $this->at + 2 );
+			$this->at                 = false !== $end ? $end + 2 : $this->length;
+			$this->token_length       = $this->at - $this->token_starts_at;
+			$this->token_value_length = $this->token_length - 4;
+			return true;
+		}
+
+		/*
+		 * Whitespace tokens.
+		 *
+		 * We consider U+000A LINE FEED, U+0009 CHARACTER TABULATION, and U+0020 SPACE bytes covered by the spec.
+		 * In addition, we also capture U+000D CARRIAGE RETURN and U+000C FORM FEED that are normally converted to
+		 * U+000A LINE FEED during the preprocessing phase.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#newline
+		 * @see https://www.w3.org/TR/css-syntax-3/#whitespace
+		 */
+		$whitespace_length = strspn( $this->css, "\t\n\f\r ", $this->at );
+		if ( $whitespace_length > 0 ) {
+			$this->token_type      = self::TOKEN_WHITESPACE;
+			$this->token_length    = $whitespace_length;
+			$this->token_starts_at = $this->at;
+			$this->at             += $whitespace_length;
+			return true;
+		}
+
+		/*
+		 * String tokens with either " or ' as delimiters.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+		 */
+		if ( '"' === $this->css[ $this->at ] || "'" === $this->css[ $this->at ] ) {
+			return $this->consume_string();
+		}
+
+		$char                  = $this->css[ $this->at ];
+		$this->token_starts_at = $this->at;
+
+		/*
+		 * U+0023 NUMBER SIGN (#)
+		 *
+		 * A hash token is created when # is followed by an ident code point or valid escape.
+		 * This is commonly used for hex colors (#fff) or ID selectors (#header).
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+		 */
+		if ( '#' === $char ) {
+			if ( $this->at + 1 < $this->length ) {
+				if (
+					$this->consume_ident_codepoint( $this->at + 1 ) > 0 ||
+					// The next two input code points are a valid escape.
+					$this->is_valid_escape( $this->at + 1 )
+				) {
+					// Create a <hash-token>.
+					++$this->at;
+
+					// > If the next 3 input code points would start an ident sequence,
+					// > set the <hash-token>'s type flag to "id".
+					$this->token_type_flag = $this->check_if_3_code_points_start_an_ident_sequence( $this->at )
+						? self::HASH_TOKEN_ID
+						: self::HASH_TOKEN_UNRESTRICTED;
+
+					// Consume an ident sequence, and set the <hash-token>'s value to the returned string.
+					$this->consume_ident_sequence();
+					$this->token_type   = self::TOKEN_HASH;
+					$this->token_length = $this->at - $this->token_starts_at;
+					return true;
+				}
+			}
+			// Otherwise, return a <delim-token> with its value set to the current input code point.
+			++$this->at;
+			$this->token_type   = self::TOKEN_DELIM;
+			$this->token_length = 1;
+			return true;
+		}
+
+		/*
+		 * Simple single-byte tokens
+		 *
+		 * These characters form their own tokens when encountered.
+		 * Note: ( tokens here are not function tokens - those are handled
+		 * in consume_ident_like() when ( follows an identifier.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+		 */
+		$simple = array(
+			'(' => self::TOKEN_LEFT_PAREN,
+			')' => self::TOKEN_RIGHT_PAREN,
+			',' => self::TOKEN_COMMA,
+			':' => self::TOKEN_COLON,
+			';' => self::TOKEN_SEMICOLON,
+			'[' => self::TOKEN_LEFT_BRACKET,
+			']' => self::TOKEN_RIGHT_BRACKET,
+			'{' => self::TOKEN_LEFT_BRACE,
+			'}' => self::TOKEN_RIGHT_BRACE,
+		);
+		if ( isset( $simple[ $char ] ) ) {
+			++$this->at;
+			$this->token_type   = $simple[ $char ];
+			$this->token_length = 1;
+			return true;
+		}
+
+		/*
+		 * U+0040 COMMERCIAL AT (@)
+		 *
+		 * An at-keyword is @ followed by an identifier, used for at-rules like
+		 * @media, @import, @keyframes, etc.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+		 */
+		if ( '@' === $char ) {
+			++$this->at;
+			// If the next 3 input code points after the @ would start an ident sequence,
+			// consume an ident sequence, create an <at-keyword-token> with its value set to the returned value,
+			// and return it.
+			if ( $this->check_if_3_code_points_start_an_ident_sequence( $this->at ) ) {
+				$this->consume_ident_sequence();
+				$this->token_type   = self::TOKEN_AT_KEYWORD;
+				$this->token_length = $this->at - $this->token_starts_at;
+				return true;
+			} else {
+				// Otherwise, return a <delim-token> with its value set to the current input code point.
+				$this->token_type   = self::TOKEN_DELIM;
+				$this->token_length = 1;
+				return true;
+			}
+		}
+
+		/*
+		 * Numbers start with digits, the plus sign, minus sign, and decimal point.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
+		 */
+		if ( $this->would_next_3_code_points_start_a_number() ) {
+			return $this->consume_numeric();
+		}
+
+		/*
+		 * U+002D HYPHEN-MINUS (-)
+		 */
+		if ( '-' === $char ) {
+			// This case is covered above:
+			// > If the input stream starts with a number.
+
+			/*
+			 * If followed by another hyphen and >, this is a CDC token (-->)
+			 *
+			 * Comment Delimiter Close - legacy HTML comment syntax in CSS.
+			 *
+			 * @see https://www.w3.org/TR/css-syntax-3/#CDC-token-diagram
+			 */
+			if (
+				$this->at + 2 < $this->length &&
+				'-' === $this->css[ $this->at + 1 ] &&
+				'>' === $this->css[ $this->at + 2 ]
+			) {
+				// Consume them and return a <CDC-token>.
+				$this->at          += 3;
+				$this->token_type   = self::TOKEN_CDC;
+				$this->token_length = 3;
+				return true;
+			}
+
+			// Otherwise, if the input stream starts with an ident sequence,
+			// reconsume the current input code point, consume an ident-like
+			// token, and return it.
+			if ( $this->check_if_3_code_points_start_an_ident_sequence( $this->at ) ) {
+				return $this->consume_ident_like();
+			}
+
+			// Otherwise, return a <delim-token> with its value set to the current input code point.
+			++$this->at;
+			$this->token_type   = self::TOKEN_DELIM;
+			$this->token_length = 1;
+			return true;
+		}
+
+		/*
+		 * U+003C LESS-THAN SIGN (<)
+		 * If followed by !--, this is a CDO token (<!--)
+		 *
+		 * Comment Delimiter Open - legacy HTML comment syntax in CSS.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#CDO-token-diagram
+		 */
+		if ( '<' === $char && $this->at + 3 < $this->length &&
+			'!' === $this->css[ $this->at + 1 ] &&
+			'-' === $this->css[ $this->at + 2 ] &&
+			'-' === $this->css[ $this->at + 3 ] ) {
+			// Consume them and return a <CDO-token>.
+			$this->at          += 4;
+			$this->token_type   = self::TOKEN_CDO;
+			$this->token_length = 4;
+			return true;
+		}
+
+		/*
+		 * Ident-start code point
+		 *
+		 * If the input stream starts with an ident sequence, reconsume the current
+		 * input code point, consume an ident-like token, and return it.
+		 *
+		 * Could be an identifier, function, or url() token.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
+		 */
+		if ( $this->check_if_3_code_points_start_an_ident_sequence( $this->at ) ) {
+			return $this->consume_ident_like();
+		}
+
+		/*
+		 * Delim token (delimiter)
+		 *
+		 * Any code point that doesn't match above rules becomes a delim token.
+		 * Handle multi-byte UTF-8 characters properly.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#delim-token-diagram
+		 */
+		if ( ord( $char ) >= 0x80 ) {
+			$new_at         = $this->at;
+			$invalid_length = 0;
+			if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
+				/**
+				 * Trouble ahead!
+				 * Bytes at $at are not a valid UTF-8 sequence.
+				 *
+				 * We'll move forward by $invalid_length bytes and continue processing.
+				 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
+				 * via maximal subpart”replacement.
+				 */
+				$matched_bytes = $invalid_length;
+			} else {
+				$matched_bytes = $new_at - $this->at;
+			}
+
+			$this->at          += $matched_bytes;
+			$this->token_type   = self::TOKEN_DELIM;
+			$this->token_length = $matched_bytes;
+			return true;
+		}
+
+		// Single ASCII delim.
+		++$this->at;
+		$this->token_type   = self::TOKEN_DELIM;
+		$this->token_length = 1;
+		return true;
+	}
+
+	/**
+	 * Gets the current token type.
+	 *
+	 * @return string|null
+	 * @phpstan-return self::TOKEN_*|null
+	 */
+	public function get_token_type(): ?string {
+		return $this->token_type;
+	}
+
+	/**
+	 * Gets the current token's type flag, if it has one.
+	 *
+	 * Some token types have an additional flag:
+	 * - Hash tokens have an "id" or "unrestricted" flag.
+	 * - Number and dimension tokens have an "integer" flag when the number was
+	 *   written without a decimal point or exponent, and a "number" flag otherwise.
+	 * - Percentage tokens do not have a type flag.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 *
+	 * @return string|null
+	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
+	 */
+	public function get_token_type_flag(): ?string {
+		return $this->token_type_flag;
+	}
+
+	/**
+	 * Gets the normalized token text from the CSS source.
+	 *
+	 * Returns the token with CSS normalization and escape decoding applied:
+	 * - CSS escapes decoded (e.g., \6c → l, \2f → /, \A → newline)
+	 * - \r\n, \r, \f → \n
+	 * - \x00 → U+FFFD (�)
+	 *
+	 * This is different from get_token_value() which returns the semantic value
+	 * (e.g., for strings: content without quotes; for numbers: numeric value).
+	 *
+	 * @return string|null
+	 */
+	public function get_normalized_token(): ?string {
+		if ( null === $this->token_starts_at || null === $this->token_length ) {
+			return null;
+		}
+
+		return $this->decode_range(
+			$this->token_starts_at,
+			$this->token_length,
+			self::TOKEN_STRING === $this->token_type
+		);
+	}
+
+	/**
+	 * Gets the raw, unnormalized token text from the CSS source.
+	 *
+	 * Returns the exact bytes from the source without any normalization.
+	 * This preserves original line endings (\r\n, \r, \f) and null bytes.
+	 *
+	 * @return string|null
+	 */
+	public function get_unnormalized_token(): ?string {
+		if ( null === $this->token_starts_at || null === $this->token_length ) {
+			return null;
+		}
+		return substr( $this->css, $this->token_starts_at, $this->token_length );
+	}
+
+	/**
+	 * Gets the current token value as a normalized and decoded string. This is
+	 * a slight divergence from the CSS Syntax Level 3 spec, where all the numberic
+	 * values are parsed as numbers. This processor is only concerned with their
+	 * textual representation.
+	 *
+	 * Returns the semantic value of the token per CSS Syntax Level 3 spec:
+	 *
+	 * - For delimiters: the single code point
+	 * - For numbers/percentages: the string representation of the number
+	 * - For dimensions: the string representation of the number (use get_token_unit() for the unit)
+	 * - For identifiers/functions/hash/at-keywords: the decoded identifier string
+	 * - For strings/URLs: the decoded string value
+	 * - For other tokens: null
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#token-value
+	 * @return string|null
+	 */
+	public function get_token_value(): ?string {
+		if ( false === $this->token_value ) {
+			if ( null === $this->token_starts_at || null === $this->token_length ) {
+				return null;
+			}
+
+			switch ( $this->token_type ) {
+				case self::TOKEN_HASH:
+					// Hash value starts after the # character.
+					$this->token_value = $this->decode_range( $this->token_starts_at + 1, $this->token_length - 1 );
+					break;
+
+				case self::TOKEN_AT_KEYWORD:
+					// At-keyword value starts after the @ character.
+					$this->token_value = $this->decode_range( $this->token_starts_at + 1, $this->token_length - 1 );
+					break;
+
+				case self::TOKEN_FUNCTION:
+					// Function name is everything except the final (.
+					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length - 1 );
+					break;
+
+				case self::TOKEN_IDENT:
+					// Identifier is the entire token.
+					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length );
+					break;
+
+				case self::TOKEN_BAD_STRING:
+					$this->token_value = null;
+					break;
+
+				case self::TOKEN_STRING:
+					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
+						$this->token_value = $this->decode_range(
+							$this->token_value_starts_at,
+							$this->token_value_length,
+							true
+						);
+					} else {
+						$this->token_value = null;
+					}
+					break;
+
+				case self::TOKEN_URL:
+					// Decode and cache the URL value.
+					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
+						$this->token_value = $this->decode_range(
+							$this->token_value_starts_at,
+							$this->token_value_length
+						);
+					} else {
+						$this->token_value = null;
+					}
+					break;
+
+				case self::TOKEN_DELIM:
+					// Delim value is the single code point.
+					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length );
+					break;
+
+				case self::TOKEN_NUMBER:
+					// Return the string representation of the number (not parsed to float).
+					$this->token_value = substr( $this->css, $this->token_starts_at, $this->token_length );
+					break;
+
+				case self::TOKEN_PERCENTAGE:
+					// Return the string representation of the number (without the %).
+					$this->token_value = substr( $this->css, $this->token_starts_at, $this->token_length - 1 );
+					break;
+
+				case self::TOKEN_DIMENSION:
+					// Return the string representation of the number (without the unit).
+					$this->token_value = substr( $this->get_normalized_token(), 0, -strlen( $this->token_unit ) );
+					break;
+
+				default:
+					$this->token_value = null;
+					break;
+			}
+		}
+
+		return $this->token_value;
+	}
+
+	/**
+	 * Determines whether the current token is a data URI.
+	 *
+	 * Only meaningful for URL and STRING tokens. Returns false for all other token types.
+	 *
+	 * @return bool Whether the current token value starts with "data:" (case-insensitive).
+	 */
+	public function is_data_uri(): bool {
+		if ( null === $this->token_value_starts_at || null === $this->token_value_length ) {
+			return false;
+		}
+
+		if ( $this->token_value_length < 5 ) {
+			return false;
+		}
+
+		$offset = $this->token_value_starts_at;
+		return (
+			( 'd' === $this->css[ $offset ] || 'D' === $this->css[ $offset ] ) &&
+			( 'a' === $this->css[ $offset + 1 ] || 'A' === $this->css[ $offset + 1 ] ) &&
+			( 't' === $this->css[ $offset + 2 ] || 'T' === $this->css[ $offset + 2 ] ) &&
+			( 'a' === $this->css[ $offset + 3 ] || 'A' === $this->css[ $offset + 3 ] ) &&
+			':' === $this->css[ $offset + 4 ]
+		);
+	}
+
+	/**
+	 * Gets the token start at.
+	 *
+	 * @return int|null
+	 */
+	public function get_token_start(): ?int {
+		return $this->token_starts_at;
+	}
+
+	/**
+	 * Gets the token length.
+	 *
+	 * @return int|null
+	 */
+	public function get_token_length(): ?int {
+		return $this->token_length;
+	}
+
+	/**
+	 * Gets the unit for dimension tokens.
+	 *
+	 * @return string|null
+	 */
+	public function get_token_unit(): ?string {
+		return $this->token_unit;
+	}
+
+	/**
+	 * Gets the byte at where the token value starts (for STRING and URL tokens).
+	 *
+	 * @return int|null
+	 */
+	public function get_token_value_start(): ?int {
+		return $this->token_value_starts_at;
+	}
+
+	/**
+	 * Gets the byte length of the token value (for STRING and URL tokens).
+	 *
+	 * @return int|null
+	 */
+	public function get_token_value_length(): ?int {
+		return $this->token_value_length;
+	}
+
+	/**
+	 * Sets the value of the current URL token.
+	 *
+	 * This method allows modifying the URL value in url() tokens. The new value
+	 * will be properly escaped according to CSS URL syntax rules.
+	 *
+	 * Currently only URL tokens are supported. Attempting to set the value on
+	 * other token types will return false.
+	 *
+	 * Example:
+	 *
+	 *     $css = 'background: url(old.jpg);';
+	 *     $processor = WP_CSS_Token_Processor::create( $css );
+	 *     while ( $processor->next_token() ) {
+	 *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+	 *             $processor->set_token_value( 'new.jpg' );
+	 *         }
+	 *     }
+	 *     echo $processor->get_updated_css();
+	 *     // Outputs: background: url(new.jpg);
+	 *
+	 * @param string $new_value The new URL value (should not include url() wrapper).
+	 * @return bool Whether the value was successfully updated.
+	 */
+	public function set_token_value( string $new_value ): bool {
+		// Only URL and string tokens are currently supported.
+		switch ( $this->token_type ) {
+			case self::TOKEN_URL:
+				$this->lexical_updates[] = array(
+					'start'  => $this->token_value_starts_at,
+					'length' => $this->token_value_length,
+					'text'   => WP_CSS_Builder::string( $new_value ),
+				);
+				return true;
+			case self::TOKEN_STRING:
+				$this->lexical_updates[] = array(
+					'start'  => $this->token_starts_at,
+					'length' => $this->token_length,
+					'text'   => WP_CSS_Builder::string( $new_value ),
+				);
+				return true;
+			default:
+				_doing_it_wrong( __METHOD__, 'set_token_value() only supports URL and string tokens. Got token type: ' . $this->token_type, '1.0.0' );
+				return false;
+		}
+	}
+
+	/**
+	 * Returns the CSS with all modifications applied.
+	 *
+	 * This method applies all queued lexical updates and returns the modified CSS.
+	 * If no modifications were made, returns the original CSS.
+	 *
+	 * Example:
+	 *
+	 *     $css = 'background: url(old.jpg);';
+	 *     $processor = WP_CSS_Token_Processor::create( $css );
+	 *     while ( $processor->next_token() ) {
+	 *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+	 *             $processor->set_token_value( 'new.jpg' );
+	 *         }
+	 *     }
+	 *     echo $processor->get_updated_css();
+	 *     // Outputs: background: url(new.jpg);
+	 *
+	 * @return string The modified CSS.
+	 */
+	public function get_updated_css(): string {
+		if ( empty( $this->lexical_updates ) ) {
+			return $this->css;
+		}
+
+		// Sort updates by start position in ascending order.
+		usort(
+			$this->lexical_updates,
+			function ( $a, $b ) {
+				return $a['start'] - $b['start'];
+			}
+		);
+
+		// Build the output by concatenating original CSS fragments with replacements.
+		$bytes_already_copied = 0;
+		$output               = '';
+
+		foreach ( $this->lexical_updates as $update ) {
+			$output              .= substr( $this->css, $bytes_already_copied, $update['start'] - $bytes_already_copied );
+			$output              .= $update['text'];
+			$bytes_already_copied = $update['start'] + $update['length'];
+		}
+
+		// Copy remaining CSS after last update.
+		$output .= substr( $this->css, $bytes_already_copied );
+
+		return $output;
+	}
+
+	/**
+	 * Clears token state between tokens.
+	 */
+	private function after_token(): void {
+		$this->token_type            = null;
+		$this->token_type_flag       = null;
+		$this->token_starts_at       = null;
+		$this->token_length          = null;
+		$this->token_value           = false;
+		$this->token_unit            = null;
+		$this->token_value_starts_at = null;
+		$this->token_value_length    = null;
+	}
+
+	/**
+	 * Consumes a string token.
+	 *
+	 * Strings are quoted with either " or ' and can contain escape sequences.
+	 * Newlines inside strings (without escaping) make the string invalid.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+	 *
+	 * @return bool
+	 */
+	private function consume_string(): bool {
+		// Initially create a <string-token> with its value set to the empty string.
+		$this->token_starts_at = $this->at;
+		$ending_char           = $this->css[ $this->at ];
+
+		// Skip past the opening quote.
+		++$this->at;
+		$value_starts_at = $this->at;
+
+		// Characters that need special handling: the ending quote, newlines, backslashes.
+		$special_chars = "'" === $ending_char ? "'\n\f\r\\" : "\"\n\f\r\\";
+
+		while ( $this->at < $this->length ) {
+			// Consume normal characters until we hit a special character.
+			$normal_len = strcspn( $this->css, $special_chars, $this->at );
+			if ( $normal_len > 0 ) {
+				$this->at += $normal_len;
+			}
+
+			if ( $this->at >= $this->length ) {
+				break; // EOF.
+			}
+
+			$char = $this->css[ $this->at ];
+			switch ( $char ) {
+				case $ending_char:
+					// Ending quote.
+					// Return the <string-token>.
+					++$this->at;
+					$this->token_type            = self::TOKEN_STRING;
+					$this->token_length          = $this->at - $this->token_starts_at;
+					$this->token_value_starts_at = $value_starts_at;
+					$this->token_value_length    = $this->at - $value_starts_at - 1;
+					return true;
+
+				case "\n":
+				case "\f":
+				case "\r":
+					/*
+					 * Newline.
+					 *
+					 * This is a parse error. Reconsume the current input code point,
+					 * create a <bad-string-token>, and return it.
+					 *
+					 * Unescaped newlines are not allowed in strings. To include a newline,
+					 * it must be escaped as \A or the string must end and a new one begin.
+					 *
+					 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+					 */
+					$this->token_type            = self::TOKEN_BAD_STRING;
+					$this->token_length          = $this->at - $this->token_starts_at;
+					$this->token_value_starts_at = $value_starts_at;
+					$this->token_value_length    = $this->at - $value_starts_at;
+					return true;
+
+				case '\\':
+					// U+005C REVERSE SOLIDUS (\)
+					// If the next input code point is EOF, do nothing.
+					++$this->at;
+					if ( $this->at >= $this->length ) {
+						// Backslash-EOF: do nothing, just consume the backslash.
+						continue 2;
+					}
+
+					// Otherwise, if the next input code point is a newline, consume it.
+					$next = $this->css[ $this->at ];
+					if ( "\n" === $next || "\f" === $next ) {
+						++$this->at;
+						continue 2;
+					} elseif ( "\r" === $next ) {
+						++$this->at;
+						// Handle \r\n as a single newline.
+						if ( $this->at < $this->length && "\n" === $this->css[ $this->at ] ) {
+							++$this->at;
+						}
+						continue 2;
+					}
+
+					// Otherwise, (the stream starts with a valid escape) consume an escaped
+					// code point (just to advance position, don't store the result).
+					$this->decode_escape_at( $this->at, $matched_bytes );
+					$this->at += $matched_bytes;
+					continue 2;
+
+				default:
+					_doing_it_wrong( __METHOD__, 'Unexpected character in string: ' . $char, '1.0.0' );
+					break;
+			}
+		}
+
+		// EOF
+		// This is a parse error. Return the <string-token>.
+		$this->token_type            = self::TOKEN_STRING;
+		$this->token_length          = $this->at - $this->token_starts_at;
+		$this->token_value_starts_at = $value_starts_at;
+		$this->token_value_length    = $this->at - $value_starts_at;
+		return true;
+	}
+
+	/**
+	 * Consumes a numeric token (number, percentage, dimension).
+	 *
+	 * Numbers can be integers or decimals, with optional sign and exponent.
+	 * They can be followed by % (percentage) or an identifier (dimension).
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 *
+	 * @return bool
+	 */
+	private function consume_numeric(): bool {
+		// Consume a number and let number be the result.
+		// The type flag defaults to "integer".
+		$number_type = 'integer';
+
+		// If the next input code point is U+002B PLUS SIGN (+) or U+002D HYPHEN-MINUS (-),
+		// consume it and append it to repr.
+		if ( '+' === $this->css[ $this->at ] || '-' === $this->css[ $this->at ] ) {
+			++$this->at;
+		}
+
+		// While the next input code point is a digit, consume it and append it to repr.
+		$digits = strspn( $this->css, '0123456789', $this->at );
+		if ( $digits > 0 ) {
+			$this->at += $digits;
+		}
+
+		// If the next 2 input code points are U+002E FULL STOP (.) followed by a digit, then.
+		if (
+			$this->at + 1 < $this->length &&
+			'.' === $this->css[ $this->at ] &&
+			$this->css[ $this->at + 1 ] >= '0' &&
+			$this->css[ $this->at + 1 ] <= '9'
+		) {
+			// Consume them.
+			++$this->at;
+			// Set type to "number".
+			$number_type = 'number';
+			// While the next input code point is a digit, consume it and append it to repr.
+			$digits = strspn( $this->css, '0123456789', $this->at );
+			if ( $digits > 0 ) {
+				$this->at += $digits;
+			}
+		}
+
+		// If the next 2 or 3 input code points are U+0045 LATIN CAPITAL LETTER E (E)
+		// or U+0065 LATIN SMALL LETTER E (e), optionally followed by U+002D HYPHEN-MINUS (-)
+		// or U+002B PLUS SIGN (+), followed by a digit, then.
+		if ( $this->at < $this->length ) {
+			$e = $this->css[ $this->at ];
+			if ( 'e' === $e || 'E' === $e ) {
+				$save_pos = $this->at;
+				++$this->at;
+				$has_exp = false;
+
+				if ( $this->at < $this->length ) {
+					$next = $this->css[ $this->at ];
+					if ( ( '+' === $next || '-' === $next ) && $this->at + 1 < $this->length &&
+						$this->css[ $this->at + 1 ] >= '0' && $this->css[ $this->at + 1 ] <= '9' ) {
+						// Consume them.
+						++$this->at;
+						$has_exp = true;
+					} elseif ( $next >= '0' && $next <= '9' ) {
+						$has_exp = true;
+					}
+				}
+
+				if ( $has_exp ) {
+					// Set type to "number".
+					$number_type = 'number';
+					// While the next input code point is a digit, consume it and append it to repr.
+					$digits = strspn( $this->css, '0123456789', $this->at );
+					if ( $digits > 0 ) {
+						$this->at += $digits;
+					}
+				} else {
+					$this->at = $save_pos;
+				}
+			}
+		}
+
+		/**
+		 * This is the end of spec section 4.3.12. Consume a number.
+		 * We still have some work to do as specified in section 4.3.3. Consume a numeric token:
+		 * https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
+		 */
+
+		// If the next 3 input code points would start an ident sequence, then.
+		if ( $this->check_if_3_code_points_start_an_ident_sequence( $this->at ) ) {
+			// Create a <dimension-token> with the same value and type flag as number,
+			// and a unit set initially to the empty string.
+			// Consume an ident sequence. Set the <dimension-token>'s unit to the returned value.
+			$unit_starts_at = $this->at;
+			$this->consume_ident_sequence();
+			$this->token_unit      = $this->decode_range( $unit_starts_at, $this->at - $unit_starts_at );
+			$this->token_type      = self::TOKEN_DIMENSION;
+			$this->token_type_flag = $number_type;
+			$this->token_length    = $this->at - $this->token_starts_at;
+			return true;
+		}
+
+		// Otherwise, if the next input code point is U+0025 PERCENTAGE SIGN (%), consume it.
+		// Create a <percentage-token> with the same value as number, and return it.
+		// Note: percentage tokens do not have a type flag per spec.
+		if ( $this->at < $this->length && '%' === $this->css[ $this->at ] ) {
+			++$this->at;
+			$this->token_type   = self::TOKEN_PERCENTAGE;
+			$this->token_length = $this->at - $this->token_starts_at;
+			return true;
+		}
+
+		// Otherwise, create a <number-token> with the same value and type flag as number, and return it.
+		$this->token_type      = self::TOKEN_NUMBER;
+		$this->token_type_flag = $number_type;
+		$this->token_length    = $this->at - $this->token_starts_at;
+		return true;
+	}
+
+	/**
+	 * Consumes an ident-like token (function, url, ident).
+	 *
+	 * After consuming an identifier, checks if it's followed by '(' to determine
+	 * if it's a function or url() token, otherwise it's a plain identifier.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
+	 *
+	 * @return bool
+	 */
+	private function consume_ident_like(): bool {
+		// Consume an ident sequence, and let string be the result.
+		$ident_start = $this->at;
+		$decoded     = $this->consume_ident_sequence();
+		$string      = $decoded ?? $this->decode_range( $ident_start, $this->at - $ident_start );
+
+		// If string's value is an ASCII case-insensitive match for "url",
+		// and the next input code point is U+0028 LEFT PARENTHESIS (().
+		if ( 0 === strcasecmp( $string, 'url' ) && $this->at < $this->length && '(' === $this->css[ $this->at ] ) {
+			// Consume it.
+			++$this->at;
+
+			// While the next two input code points are whitespace, consume the next input code point.
+			$ws_len = strspn( $this->css, "\t\n\f\r ", $this->at );
+
+			// If the next one or two input code points are U+0022 QUOTATION MARK ("),
+			// U+0027 APOSTROPHE ('), or whitespace followed by U+0022 QUOTATION MARK (")
+			// or U+0027 APOSTROPHE (').
+			if ( $this->at + $ws_len < $this->length ) {
+				$next = $this->css[ $this->at + $ws_len ];
+				if ( '"' === $next || "'" === $next ) {
+					// then create a <function-token> with its value set to string and return it.
+					if ( null !== $decoded ) {
+						$this->token_value = $decoded;
+					}
+					$this->token_type   = self::TOKEN_FUNCTION;
+					$this->token_length = $this->at - $this->token_starts_at;
+					return true;
+				}
+			}
+
+			// Otherwise, consume a url token, and return it.
+			$this->at += $ws_len;
+			return $this->consume_url();
+		}
+
+		// Otherwise, if the next input code point is U+0028 LEFT PARENTHESIS (().
+		if ( $this->at < $this->length && '(' === $this->css[ $this->at ] ) {
+			// Consume it.
+			++$this->at;
+			// Create a <function-token> with its value set to string and return it.
+			if ( null !== $decoded ) {
+				$this->token_value = $decoded;
+			}
+			$this->token_type   = self::TOKEN_FUNCTION;
+			$this->token_length = $this->at - $this->token_starts_at;
+			return true;
+		}
+
+		// Otherwise, create an <ident-token> with its value set to string and return it.
+		if ( null !== $decoded ) {
+			$this->token_value = $decoded;
+		}
+		$this->token_type   = self::TOKEN_IDENT;
+		$this->token_length = $this->at - $this->token_starts_at;
+		return true;
+	}
+
+	/**
+	 * Consumes a url token.
+	 *
+	 * URL tokens can contain unquoted URLs with escape sequences but not quotes,
+	 * parentheses, or certain control characters. Invalid characters create a
+	 * bad-url token.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 *
+	 * @return bool
+	 */
+	private function consume_url(): bool {
+		// Initially create a <url-token> with its value set to the empty string.
+		// Consume as much whitespace as possible.
+		$this->at += strspn( $this->css, "\t\n\f\r ", $this->at );
+
+		$value_starts_at = $this->at;
+
+		// Repeatedly consume the next input code point from the stream.
+		while ( $this->at < $this->length ) {
+			// U+0029 RIGHT PARENTHESIS ())
+			// Return the <url-token>.
+			if ( ')' === $this->css[ $this->at ] ) {
+				++$this->at;
+				$this->token_type            = self::TOKEN_URL;
+				$this->token_length          = $this->at - $this->token_starts_at;
+				$this->token_value_starts_at = $value_starts_at;
+				$this->token_value_length    = $this->at - $value_starts_at - 1;
+				return true;
+			}
+
+			// whitespace
+			// Consume as much whitespace as possible. If the next input code point is
+			// U+0029 RIGHT PARENTHESIS ()) or EOF, consume it and return the <url-token>
+			// (if EOF was encountered, this is a parse error); otherwise, consume the
+			// remnants of a bad url, create a <bad-url-token>, and return it.
+			$ws_len = strspn( $this->css, "\t\n\f\r ", $this->at );
+			if ( $ws_len > 0 ) {
+				$value_ends_at = $this->at;
+				$this->at     += $ws_len;
+				// Accept either ) or EOF after whitespace.
+				if ( $this->at >= $this->length ) {
+					// EOF is a parse error, but we return the <url-token> anyway.
+					$this->token_type            = self::TOKEN_URL;
+					$this->token_length          = $this->at - $this->token_starts_at;
+					$this->token_value_starts_at = $value_starts_at;
+					$this->token_value_length    = $value_ends_at - $value_starts_at;
+					return true;
+				}
+
+				if ( ')' === $this->css[ $this->at ] ) {
+					// Skip the closing parenthesis and return the <url-token>.
+					++$this->at;
+					$this->token_type            = self::TOKEN_URL;
+					$this->token_length          = $this->at - $this->token_starts_at;
+					$this->token_value_starts_at = $value_starts_at;
+					$this->token_value_length    = $value_ends_at - $value_starts_at;
+					return true;
+				}
+
+				return $this->consume_remnants_of_bad_url();
+			}
+
+			// These codepoints trigger a parse error.
+			$byte = ord( $this->css[ $this->at ] );
+			if (
+				'"' === $this->css[ $this->at ] ||
+				"'" === $this->css[ $this->at ] ||
+				'(' === $this->css[ $this->at ] ||
+
+				// Non-printable code point.
+				$byte <= 0x08 ||
+
+				// Line Tabulation.
+				0x0B === $byte ||
+
+				// Control characters.
+				( $byte >= 0x000E && $byte <= 0x001F ) ||
+
+				// Delete.
+				0x7F === $byte
+			) {
+				// Consume the remnants of a bad url,
+				// create a <bad-url-token>, and return it.
+				return $this->consume_remnants_of_bad_url();
+			}
+
+			// U+005C REVERSE SOLIDUS (\)
+			// If the stream starts with a valid escape, consume an escaped code point.
+			if ( '\\' === $this->css[ $this->at ] ) {
+				if ( $this->is_valid_escape( $this->at ) ) {
+					++$this->at;
+					$this->decode_escape_at( $this->at, $matched_bytes );
+					$this->at += $matched_bytes;
+					continue;
+				}
+				// Otherwise, this is a parse error. Consume the remnants of a bad url,
+				// create a <bad-url-token>, and return it.
+				return $this->consume_remnants_of_bad_url();
+			}
+
+			$at             = $this->at;
+			$invalid_length = 0;
+			if ( 1 !== _wp_scan_utf8( $this->css, $at, $invalid_length, null, 1 ) ) {
+				/**
+				 * Trouble ahead!
+				 * Bytes at $at are not a valid UTF-8 sequence.
+				 *
+				 * We'll move forward by $invalid_length bytes and continue processing.
+				 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
+				 * via maximal subpart”replacement.
+				 */
+				$this->at += $invalid_length;
+			} else {
+				$this->at = $at;
+			}
+		}
+
+		// EOF
+		// This is a parse error. Return the <url-token>.
+		$this->token_type            = self::TOKEN_URL;
+		$this->token_length          = $this->at - $this->token_starts_at;
+		$this->token_value_starts_at = $value_starts_at;
+		$this->token_value_length    = $this->at - $value_starts_at;
+		return true;
+	}
+
+	/**
+	 * Finishes a bad url token by consuming remnants.
+	 *
+	 * When an invalid character is encountered in a URL, we must consume
+	 * the remainder of the URL up to the closing ) or EOF.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-remnants-of-bad-url
+	 *
+	 * @return bool
+	 */
+	private function consume_remnants_of_bad_url(): bool {
+		while ( $this->at < $this->length ) {
+			$this->at += strcspn( $this->css, ')\\', $this->at );
+
+			if ( $this->at >= $this->length ) {
+				break;
+			}
+
+			if ( '\\' === $this->css[ $this->at ] ) {
+				++$this->at;
+				if ( $this->is_valid_escape( $this->at - 1 ) ) {
+					$this->decode_escape_at( $this->at, $matched_bytes );
+					$this->at += $matched_bytes;
+					continue;
+				}
+			} elseif ( ')' === $this->css[ $this->at ] ) {
+				++$this->at;
+				break;
+			}
+		}
+
+		$this->token_type   = self::TOKEN_BAD_URL;
+		$this->token_length = $this->at - $this->token_starts_at;
+		return true;
+	}
+
+	/**
+	 * Consumes an identifier sequence.
+	 *
+	 * Identifiers can contain letters, digits, hyphens, underscores, non-ASCII
+	 * characters, and escape sequences. Null bytes are replaced with U+FFFD.
+	 *
+	 * Returns the decoded identifier string if escapes were encountered,
+	 * or null if no decoding was needed (can use raw substring).
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-name
+	 */
+	private function consume_ident_sequence() {
+		while ( $this->at < $this->length ) {
+			$codepoint_bytes = $this->consume_ident_codepoint( $this->at );
+			if ( $codepoint_bytes > 0 ) {
+				$this->at += $codepoint_bytes;
+				continue;
+			}
+
+			if ( $this->is_valid_escape( $this->at ) ) {
+				++$this->at;
+
+				$this->decode_escape_at( $this->at, $matched_bytes );
+				$this->at += $matched_bytes;
+				continue;
+			}
+
+			break;
+		}
+	}
+
+	/**
+	 * Ident-start code point
+	 *     A letter, a non-ASCII code point, or U+005F LOW LINE (_).
+	 *
+	 * Ident code point
+	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 * @return int The number of bytes consumed.
+	 */
+	private function consume_ident_codepoint( $at ): int {
+		// ident code points.
+		if ( ( $this->css[ $at ] >= '0' && $this->css[ $at ] <= '9' ) ||
+			'-' === $this->css[ $at ] ) {
+			return 1;
+		}
+
+		return $this->consume_ident_start_codepoint( $at );
+	}
+
+
+	/**
+	 * Ident-start code point
+	 *     A letter, a non-ASCII code point, or U+005F LOW LINE (_).
+	 *
+	 * Ident code point
+	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 * @return int The number of bytes consumed.
+	 */
+	private function consume_ident_start_codepoint( $at ): int {
+		if ( $at >= $this->length ) {
+			return 0;
+		}
+
+		// ASCII codepoints.
+		if ( ( $this->css[ $at ] >= 'A' && $this->css[ $at ] <= 'Z' ) ||
+			( $this->css[ $at ] >= 'a' && $this->css[ $at ] <= 'z' ) ||
+			'_' === $this->css[ $at ] ) {
+			return 1;
+		}
+
+		// Special case for null bytes – they are replaced with U+FFFD during preprocessing.
+		if ( "\x00" === $this->css[ $at ] ) {
+			return 1;
+		}
+
+		$new_at         = $at;
+		$invalid_length = 0;
+		if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
+			/**
+			 * Trouble ahead!
+			 * Bytes at $at are not a valid UTF-8 sequence.
+			 *
+			 * We'll move forward by $invalid_length bytes and continue processing.
+			 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
+			 * via maximal subpart”replacement.
+			 */
+			return $invalid_length;
+		}
+
+		$codepoint_byte_length = $new_at - $at;
+		$codepoint             = self::utf8_ord( substr( $this->css, $at, $codepoint_byte_length ) );
+		if ( null !== $codepoint && $codepoint >= 0x80 ) {
+			return $codepoint_byte_length;
+		}
+		return 0;
+	}
+
+	/**
+	 * Decodes and normalizes ident-like or string CSS values from a byte range.
+	 *
+	 * @param int  $start          Start byte offset.
+	 * @param int  $length         Length of the substring to decode.
+	 * @param bool $string_escapes Optional, default false. When true, apply additional escape
+	 *                             rules that apply only to string tokens.
+	 * @return string Decoded and normalized string.
+	 */
+	private function decode_range( int $start, int $length, bool $string_escapes = false ): string {
+		// Fast path: check if any processing is needed.
+		$slice         = wp_scrub_utf8( substr( $this->css, $start, $length ) );
+		$special_chars = "\\\r\f\x00";
+		if ( false === strpbrk( $slice, $special_chars ) ) {
+			// No special chars - return raw substring (almost zero allocations).
+			return $slice;
+		}
+
+		// Slow path: build decoded string (one allocation).
+		$decoded = '';
+		$at      = $start;
+		$end     = $start + $length;
+
+		while ( $at < $end ) {
+			// Find next special character within the token boundary.
+			$normal_len = strcspn( $this->css, $special_chars, $at, $end - $at );
+			if ( $normal_len > 0 ) {
+				$decoded .= wp_scrub_utf8( substr( $this->css, $at, $normal_len ) );
+				$at      += $normal_len;
+			}
+
+			if ( $at >= $end ) {
+				break;
+			}
+
+			$char = $this->css[ $at ];
+
+			// Handle escapes (if enabled).
+			if ( '\\' === $char ) {
+				if ( $string_escapes ) {
+					if ( $at + 1 >= $end ) {
+						// Backslash-EOF: consume the backslash and stop.
+						++$at;
+						continue;
+					}
+
+					$next = $this->css[ $at + 1 ];
+					if ( "\n" === $next || "\f" === $next ) {
+						// Backslash followed by LF or FF is a string line continuation.
+						$at += 2;
+						continue;
+					}
+
+					if ( "\r" === $next ) {
+						// Backslash followed by CR or CRLF is a string line continuation.
+						$at += 2;
+						if ( $at < $end && "\n" === $this->css[ $at ] ) {
+							++$at;
+						}
+						continue;
+					}
+				}
+
+				if ( $this->is_valid_escape( $at ) ) {
+					++$at;
+					$decoded .= $this->decode_escape_at( $at, $bytes_consumed );
+					$at      += $bytes_consumed;
+					continue;
+				}
+				// Invalid escape - consume the backslash and keep going.
+				$decoded .= '\\';
+				++$at;
+				continue;
+			}
+
+			// CSS normalization: \r\n, \r, and \f all become \n.
+			if ( "\r" === $char ) {
+				$decoded .= "\n";
+				++$at;
+				// Handle \r\n as single newline.
+				if ( $at < $end && "\n" === $this->css[ $at ] ) {
+					++$at;
+				}
+				continue;
+			}
+
+			if ( "\f" === $char ) {
+				$decoded .= "\n";
+				++$at;
+				continue;
+			}
+
+			// Null bytes become U+FFFD.
+			if ( "\x00" === $char ) {
+				$decoded .= "\u{FFFD}";
+				++$at;
+				continue;
+			}
+		}
+
+		return $decoded;
+	}
+
+	/**
+	 * Decodes an escape sequence starting at the given offset without
+	 * modifying $this->at.
+	 *
+	 * Escape sequences are backslash followed by 1-6 hex digits (with optional
+	 * trailing whitespace) or any other character. Invalid code points are
+	 * replaced with U+FFFD.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
+	 *
+	 * @param int $offset Byte offset (should point to the character after the backslash).
+	 * @param int &$bytes_consumed Output parameter: number of bytes consumed.
+	 * @return string The decoded character(s).
+	 */
+	private function decode_escape_at( int $offset, &$bytes_consumed ): string {
+		// This method assumes the U+005C REVERSE SOLIDUS (\) has already been consumed
+		// and the next input code point has already been verified to be part of a valid
+		// escape sequence.
+		$at = $offset;
+
+		// EOF.
+		if ( $at >= $this->length ) {
+			// This is a parse error. Return U+FFFD REPLACEMENT CHARACTER (�).
+			$bytes_consumed = 0;
+			return "\u{FFFD}";
+		}
+
+		// Hex digits (CSS spec allows at most 6).
+		$hex_len = strspn( $this->css, '0123456789ABCDEFabcdef', $at, 6 );
+		if ( $hex_len > 0 ) {
+			$hex = substr( $this->css, $at, $hex_len );
+			$at += $hex_len;
+
+			// If the next input code point is whitespace, consume it as well.
+			if ( $at < $this->length ) {
+				$next = $this->css[ $at ];
+				if ( "\t" === $next || "\n" === $next || "\f" === $next || ' ' === $next ) {
+					++$at;
+				} elseif ( "\r" === $next ) {
+					++$at;
+					// Handle \r\n as a single whitespace – the preprocessing phase would replace \r\n with \n.
+					if ( $at < $this->length && "\n" === $this->css[ $at ] ) {
+						++$at;
+					}
+				}
+			}
+
+			$bytes_consumed = $at - $offset;
+			$code_point     = hexdec( $hex );
+			if (
+				$code_point <= 0 ||
+				( $code_point >= 0xD800 && $code_point <= 0xDFFF ) ||
+				$code_point > 0x10FFFF
+			) {
+				return "\u{FFFD}";
+			}
+
+			// Convert the hex digits to a UTF-8 string.
+			return WP_HTML_Decoder::code_point_to_utf8_bytes( $code_point );
+		}
+
+		// Anything else.
+		// Return the current input code point.
+		// Null bytes are replaced with U+FFFD during preprocessing.
+		if ( "\x00" === $this->css[ $at ] ) {
+			$bytes_consumed = 1;
+			return "\u{FFFD}";
+		}
+
+		$new_at         = $at;
+		$invalid_length = 0;
+		if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
+			// Consume the invalid subpart and return U+FFFD.
+			$bytes_consumed = $invalid_length;
+			return "\u{FFFD}";
+		}
+
+		$bytes_consumed = $new_at - $at;
+		return substr( $this->css, $at, $bytes_consumed );
+	}
+
+	/**
+	 * Checks if current position starts a valid escape sequence.
+	 *
+	 * A valid escape is a backslash not followed by a newline or EOF.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
+	 *
+	 * @param int $offset Byte offset.
+	 * @return bool
+	 */
+	private function is_valid_escape( int $offset ): bool {
+		// If the first code point is not U+005C REVERSE SOLIDUS (\), return false.
+		if ( $offset >= $this->length || '\\' !== $this->css[ $offset ] ) {
+			return false;
+		}
+		// Otherwise, if the second code point is a newline, return false.
+		if ( $offset + 1 >= $this->length ) {
+			// Second code point is EOF - this is a valid escape per spec (weird!)
+			// Are we sure we're interpreting the spec correctly?
+			return true;
+		}
+
+		// Otherwise, if the second code point is not a newline, return true.
+		return (
+			"\n" !== $this->css[ $offset + 1 ] &&
+
+			// Form feed is normalized to newline during preprocessing.
+			"\f" !== $this->css[ $offset + 1 ] &&
+
+			// Carriage return is normalized to newline during preprocessing.
+			"\r" !== $this->css[ $offset + 1 ]
+
+			// We don't need to check for \r\n separately here. The \r check alone covers
+			// that scenario.
+		);
+	}
+
+	/**
+	 * Checks if the next 3 code points would start a number.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
+	 *
+	 * @return bool
+	 */
+	private function would_next_3_code_points_start_a_number(): bool {
+		if ( $this->at >= $this->length ) {
+			return false;
+		}
+
+		// Look at the first code point.
+
+		// U+002B PLUS SIGN (+) or U+002D HYPHEN-MINUS (-).
+		if ( '+' === $this->css[ $this->at ] || '-' === $this->css[ $this->at ] ) {
+			if ( $this->at + 1 >= $this->length ) {
+				return false;
+			}
+			// If the second code point is a digit, return true.
+			if ( $this->css[ $this->at + 1 ] >= '0' && $this->css[ $this->at + 1 ] <= '9' ) {
+				return true;
+			}
+			// Otherwise, the second code point must be a full stop (.) and the third code point must be a digit.
+			if ( '.' === $this->css[ $this->at + 1 ] && $this->at + 2 < $this->length ) {
+				return $this->css[ $this->at + 2 ] >= '0' && $this->css[ $this->at + 2 ] <= '9';
+			}
+
+			// Otherwise, return false.
+			return false;
+		}
+
+		// U+002E FULL STOP (.).
+		if ( '.' === $this->css[ $this->at ] ) {
+			if ( $this->at + 1 >= $this->length ) {
+				return false;
+			}
+			return $this->css[ $this->at + 1 ] >= '0' && $this->css[ $this->at + 1 ] <= '9';
+		}
+
+		// Digit.
+		if ( $this->css[ $this->at ] >= '0' && $this->css[ $this->at ] <= '9' ) {
+			return true;
+		}
+
+		// Anything else – return false.
+		return false;
+	}
+
+	/**
+	 * Checks if three code points would start an identifier sequence.
+	 *
+	 * This implements the CSS spec's "Check if three code points would start an ident sequence"
+	 * algorithm, which checks the code point at $offset and the following two code points.
+	 *
+	 * NOTE: "Three code points" means three Unicode code points, not three bytes.
+	 * Multi-byte UTF-8 sequences count as single code points.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 *
+	 * @param int $offset Byte offset of the first code point to check.
+	 * @return bool
+	 */
+	private function check_if_3_code_points_start_an_ident_sequence( int $offset ): bool {
+		if ( $offset >= $this->length ) {
+			return false;
+		}
+
+		if ( '-' === $this->css[ $offset ] ) {
+			// If the second code point is a U+002D HYPHEN-MINUS (-), return true.
+			// e.g. --custom-property.
+			if ( $offset + 1 < $this->length && '-' === $this->css[ $offset + 1 ] ) {
+				return true;
+			}
+			// Otherwise, check if the second code point is an ident-START code point or valid escape.
+			// Note: After a hyphen, only ident-START code points are valid, NOT digits or hyphens.
+			++$offset;
+		}
+
+		return $this->consume_ident_start_codepoint( $offset ) > 0 || $this->is_valid_escape( $offset );
+	}
+
+	/**
+	 * Convert a UTF-8 byte sequence to its Unicode codepoint.
+	 *
+	 * @param  string $character  UTF-8 encoded byte sequence representing a single Unicode character.
+	 *
+	 * @return int Unicode codepoint.
+	 */
+	private static function utf8_ord( string $character ): int {
+		// Convert the byte sequence to its binary representation.
+		$bytes = unpack( 'C*', $character );
+
+		// Initialize the codepoint.
+		$codepoint = 0;
+
+		// Calculate the codepoint based on the number of bytes.
+		if ( 1 === count( $bytes ) ) {
+			$codepoint = $bytes[1];
+		} elseif ( 2 === count( $bytes ) ) {
+			$codepoint = ( ( $bytes[1] & 0x1F ) << 6 ) | ( $bytes[2] & 0x3F );
+		} elseif ( 3 === count( $bytes ) ) {
+			$codepoint = ( ( $bytes[1] & 0x0F ) << 12 ) | ( ( $bytes[2] & 0x3F ) << 6 ) | ( $bytes[3] & 0x3F );
+		} elseif ( 4 === count( $bytes ) ) {
+			$codepoint = ( ( $bytes[1] & 0x07 ) << 18 ) | ( ( $bytes[2] & 0x3F ) << 12 ) | ( ( $bytes[3] & 0x3F ) << 6 ) | ( $bytes[4] & 0x3F );
+		}
+
+		return $codepoint;
+	}
+}
diff --git a/src/wp-settings.php b/src/wp-settings.php
index 1d55db83e2d85..c811424dc25a2 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -278,6 +278,8 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-stack-event.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
+require ABSPATH . WPINC . '/css-api/class-wp-css-builder.php';
+require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';
diff --git a/tests/phpunit/data/css-api/css-test-cases.json b/tests/phpunit/data/css-api/css-test-cases.json
new file mode 100644
index 0000000000000..bb9c919b4ec64
--- /dev/null
+++ b/tests/phpunit/data/css-api/css-test-cases.json
@@ -0,0 +1,4988 @@
+{
+	"tests/at-keyword/0001": {
+		"css": "@foo\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@foo",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "@foo",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0002": {
+		"css": "@--\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@--",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "@--",
+				"value": "--"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0003": {
+		"css": "@-1\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "@",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "@",
+				"value": "@"
+			},
+			{
+				"type": "number-token",
+				"raw": "-1",
+				"startIndex": 1,
+				"endIndex": 3,
+				"normalized": "-1",
+				"value": "-1",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0004": {
+		"css": "@--1\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@--1",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "@--1",
+				"value": "--1"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0005": {
+		"css": "@\\@\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@\\@",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "@@",
+				"value": "@"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0006": {
+		"css": "@_\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@_",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "@_",
+				"value": "_"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0007": {
+		"css": "@\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "@",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "@",
+				"value": "@"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0008": {
+		"css": "pvA3@\\\neBnP\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "pvA3",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "pvA3",
+				"value": "pvA3"
+			},
+			{
+				"type": "delim-token",
+				"raw": "@",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "@",
+				"value": "@"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\\",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\\",
+				"value": "\\"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "eBnP",
+				"startIndex": 7,
+				"endIndex": 11,
+				"normalized": "eBnP",
+				"value": "eBnP"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/at-keyword/0009": {
+		"css": "@aa𐀀\n",
+		"tokens": [
+			{
+				"type": "at-keyword-token",
+				"raw": "@aa𐀀",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "@aa𐀀",
+				"value": "aa𐀀"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-string/0001": {
+		"css": "\"foo\n\"\n",
+		"tokens": [
+			{
+				"type": "bad-string-token",
+				"raw": "\"foo",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "\"foo",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "bad-string-token",
+				"raw": "\"",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\"",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-string/0002": {
+		"css": "\"foo\\\n\"\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"foo\\\n\"",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "\"foo\"",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-string/0003": {
+		"css": "\"foo\r\n\"\n",
+		"tokens": [
+			{
+				"type": "bad-string-token",
+				"raw": "\"foo",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "\"foo",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\r\n",
+				"startIndex": 4,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "bad-string-token",
+				"raw": "\"",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\"",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-string/0004": {
+		"css": "\"foo\\\r\n\"\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"foo\\\r\n\"",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "\"foo\"",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-string/0005": {
+		"css": "\"aa𐀀\n",
+		"tokens": [
+			{
+				"type": "bad-string-token",
+				"raw": "\"aa𐀀",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "\"aa𐀀",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0001": {
+		"css": "url(\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(\n",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "url(\n",
+				"value": ""
+			}
+		]
+	},
+	"tests/bad-url/0002": {
+		"css": "url( a\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( a\n",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "url( a\n",
+				"value": "a"
+			}
+		]
+	},
+	"tests/bad-url/0003": {
+		"css": "url( a a\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url( a a\n",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "url( a a\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0004": {
+		"css": "url( a a)\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url( a a)",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "url( a a)",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0005": {
+		"css": "url( a a\\)\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url( a a\\)\n",
+				"startIndex": 0,
+				"endIndex": 11,
+				"normalized": "url( a a)\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0006": {
+		"css": "url( \\\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url( \\\n",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "url( \\\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0007": {
+		"css": "url(a'')\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url(a'')",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "url(a'')",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/bad-url/0008": {
+		"css": "url(a\")\n",
+		"tokens": [
+			{
+				"type": "bad-url-token",
+				"raw": "url(a\")",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "url(a\")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/colon/0001": {
+		"css": ":\n",
+		"tokens": [
+			{
+				"type": "colon-token",
+				"raw": ":",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ":",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/comma/0001": {
+		"css": ",\n",
+		"tokens": [
+			{
+				"type": "comma-token",
+				"raw": ",",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ",",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0001": {
+		"css": "/* a comment */\n",
+		"tokens": [
+			{
+				"type": "comment",
+				"raw": "/* a comment */",
+				"startIndex": 0,
+				"endIndex": 15,
+				"normalized": "/* a comment */",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 15,
+				"endIndex": 16,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0002": {
+		"css": "/* a comment ",
+		"tokens": [
+			{
+				"type": "comment",
+				"raw": "/* a comment ",
+				"startIndex": 0,
+				"endIndex": 13,
+				"normalized": "/* a comment ",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0003": {
+		"css": "a/**/b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "a",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": "comment",
+				"raw": "/**/",
+				"startIndex": 1,
+				"endIndex": 5,
+				"normalized": "/**/",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "b",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "b",
+				"value": "b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0004": {
+		"css": "/*\\*/*/\n",
+		"tokens": [
+			{
+				"type": "comment",
+				"raw": "/*\\*/",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "/**/",
+				"value": null
+			},
+			{
+				"type": "delim-token",
+				"raw": "*",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "*",
+				"value": "*"
+			},
+			{
+				"type": "delim-token",
+				"raw": "/",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "/",
+				"value": "/"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0005": {
+		"css": "/* a comment *",
+		"tokens": [
+			{
+				"type": "comment",
+				"raw": "/* a comment *",
+				"startIndex": 0,
+				"endIndex": 14,
+				"normalized": "/* a comment *",
+				"value": null
+			}
+		]
+	},
+	"tests/comment/0006": {
+		"css": "/*a𐀀*/\n",
+		"tokens": [
+			{
+				"type": "comment",
+				"raw": "/*a𐀀*/",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "/*a𐀀*/",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/digit/0001": {
+		"css": "0\n1\n2\n3\n4\n5\n6\n7\n8\n9\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "0",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "0",
+				"value": "0",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "1",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "1",
+				"value": "1",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "2",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "2",
+				"value": "2",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "3",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "3",
+				"value": "3",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "4",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "4",
+				"value": "4",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "5",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": "5",
+				"value": "5",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "6",
+				"startIndex": 12,
+				"endIndex": 13,
+				"normalized": "6",
+				"value": "6",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 13,
+				"endIndex": 14,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "7",
+				"startIndex": 14,
+				"endIndex": 15,
+				"normalized": "7",
+				"value": "7",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 15,
+				"endIndex": 16,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "8",
+				"startIndex": 16,
+				"endIndex": 17,
+				"normalized": "8",
+				"value": "8",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 17,
+				"endIndex": 18,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "9",
+				"startIndex": 18,
+				"endIndex": 19,
+				"normalized": "9",
+				"value": "9",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 19,
+				"endIndex": 20,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0001": {
+		"css": "10px\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10px",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "10px",
+				"value": "10",
+				"unit": "px",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0002": {
+		"css": "10\\70 x\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10\\70 x",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "10px",
+				"value": "10",
+				"unit": "px",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0003": {
+		"css": "10--custom-px\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10--custom-px",
+				"startIndex": 0,
+				"endIndex": 13,
+				"normalized": "10--custom-px",
+				"value": "10",
+				"unit": "--custom-px",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 13,
+				"endIndex": 14,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0004": {
+		"css": "10e2px\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10e2px",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "10e2px",
+				"value": "10e2",
+				"unit": "px",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0005": {
+		"css": "10E2PX\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10E2PX",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "10E2PX",
+				"value": "10E2",
+				"unit": "PX",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0006": {
+		"css": "10\\0\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10\\0\n",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "10�",
+				"value": "10",
+				"unit": "�",
+				"numberType": "integer"
+			}
+		]
+	},
+	"tests/dimension/0007": {
+		"css": "10a𐀀\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10a𐀀",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "10a𐀀",
+				"value": "10",
+				"unit": "a𐀀",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/dimension/0008": {
+		"css": "10a\u0000",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "10a\u0000",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "10a�",
+				"value": "10",
+				"unit": "a�",
+				"numberType": "integer"
+			}
+		]
+	},
+	"tests/escaped-code-point/0001": {
+		"css": "\\",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/escaped-code-point/0002": {
+		"css": "\\0",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\0",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/escaped-code-point/0003": {
+		"css": "\\\\",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\\\",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "\\",
+				"value": "\\"
+			}
+		]
+	},
+	"tests/escaped-code-point/0004": {
+		"css": "\\0a b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\0a b",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "\nb",
+				"value": "\nb"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0005": {
+		"css": "\\0ab \n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\0ab ",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "«",
+				"value": "«"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0006": {
+		"css": "\\0ab (foo)\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "\\0ab (",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "«(",
+				"value": "«"
+			},
+			{
+				"type": "ident-token",
+				"raw": "foo",
+				"startIndex": 6,
+				"endIndex": 9,
+				"normalized": "foo",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0007": {
+		"css": "\\0ab  (foo)\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\0ab ",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "«",
+				"value": "«"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "(-token",
+				"raw": "(",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "(",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "foo",
+				"startIndex": 7,
+				"endIndex": 10,
+				"normalized": "foo",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0008": {
+		"css": "\\0000ab\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\0000ab\n",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "«",
+				"value": "«"
+			}
+		]
+	},
+	"tests/escaped-code-point/0009": {
+		"css": "\\00000ab\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\00000ab",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "\nb",
+				"value": "\nb"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0010": {
+		"css": "\\110000\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\110000\n",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/escaped-code-point/0011": {
+		"css": "\\00D800\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\00D800\n",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/escaped-code-point/0012": {
+		"css": "\\00DFFF\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\00DFFF\n",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/escaped-code-point/0013": {
+		"css": "\\\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "\\",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "\\",
+				"value": "\\"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0014": {
+		"css": "\\\u0000\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\\u0000",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "�",
+				"value": "�"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0015": {
+		"css": "\\\u0000\b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\\u0000",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "�",
+				"value": "�"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\b",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\b",
+				"value": "\b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/escaped-code-point/0016": {
+		"css": "\"a\\12\r\nb\"",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"a\\12\r\nb\"",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "\"a\u0012b\"",
+				"value": "a\u0012b"
+			}
+		]
+	},
+	"tests/full-stop/0001": {
+		"css": ".\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": ".",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ".",
+				"value": "."
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/full-stop/0002": {
+		"css": ".a\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": ".",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ".",
+				"value": "."
+			},
+			{
+				"type": "ident-token",
+				"raw": "a",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/full-stop/0003": {
+		"css": ".1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": ".1",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": ".1",
+				"value": ".1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/fuzz/01a166c0-ca20-43a5-9ab0-0984e4a5362b": {
+		"css": "4waPtwEEGH\\\u0000jV3zM6hh6w30N0PC 7m8KM0HcWGOPw28Gt(r19",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "4waPtwEEGH\\\u0000jV3zM6hh6w30N0PC",
+				"startIndex": 0,
+				"endIndex": 28,
+				"normalized": "4waPtwEEGH�jV3zM6hh6w30N0PC",
+				"value": "4",
+				"unit": "waPtwEEGH�jV3zM6hh6w30N0PC",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 28,
+				"endIndex": 29,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "dimension-token",
+				"raw": "7m8KM0HcWGOPw28Gt",
+				"startIndex": 29,
+				"endIndex": 46,
+				"normalized": "7m8KM0HcWGOPw28Gt",
+				"value": "7",
+				"unit": "m8KM0HcWGOPw28Gt",
+				"numberType": "integer"
+			},
+			{
+				"type": "(-token",
+				"raw": "(",
+				"startIndex": 46,
+				"endIndex": 47,
+				"normalized": "(",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "r19",
+				"startIndex": 47,
+				"endIndex": 50,
+				"normalized": "r19",
+				"value": "r19"
+			}
+		]
+	},
+	"tests/fuzz/2abe9406-c063-4e9a-85ac-b13660671553": {
+		"css": "ak]P0A}808G\"lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5J\\\r\nBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9\"\"c34Q\"iiC0e45Da5f\"F5X3\"o(",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "ak",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "ak",
+				"value": "ak"
+			},
+			{
+				"type": "]-token",
+				"raw": "]",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "]",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "P0A",
+				"startIndex": 3,
+				"endIndex": 6,
+				"normalized": "P0A",
+				"value": "P0A"
+			},
+			{
+				"type": "}-token",
+				"raw": "}",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "}",
+				"value": null
+			},
+			{
+				"type": "dimension-token",
+				"raw": "808G",
+				"startIndex": 7,
+				"endIndex": 11,
+				"normalized": "808G",
+				"value": "808",
+				"unit": "G",
+				"numberType": "integer"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5J\\\r\nBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9\"",
+				"startIndex": 11,
+				"endIndex": 102,
+				"normalized": "\"lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5JBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9\"",
+				"value": "lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5JBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"c34Q\"",
+				"startIndex": 102,
+				"endIndex": 108,
+				"normalized": "\"c34Q\"",
+				"value": "c34Q"
+			},
+			{
+				"type": "ident-token",
+				"raw": "iiC0e45Da5f",
+				"startIndex": 108,
+				"endIndex": 119,
+				"normalized": "iiC0e45Da5f",
+				"value": "iiC0e45Da5f"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"F5X3\"",
+				"startIndex": 119,
+				"endIndex": 125,
+				"normalized": "\"F5X3\"",
+				"value": "F5X3"
+			},
+			{
+				"type": "function-token",
+				"raw": "o(",
+				"startIndex": 125,
+				"endIndex": 127,
+				"normalized": "o(",
+				"value": "o"
+			}
+		]
+	},
+	"tests/fuzz/4e630a47-507b-4b79-b00f-57f7dc1cc79d": {
+		"css": "\u000e7rSD6I5L1lglVRlL2X7BbEk\\3HCd\r94 \\\u0000skoW25d4%l64UUskN\"pHun\"!",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "\u000e",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "\u000e",
+				"value": "\u000e"
+			},
+			{
+				"type": "dimension-token",
+				"raw": "7rSD6I5L1lglVRlL2X7BbEk\\3HCd",
+				"startIndex": 1,
+				"endIndex": 29,
+				"normalized": "7rSD6I5L1lglVRlL2X7BbEk\u0003HCd",
+				"value": "7",
+				"unit": "rSD6I5L1lglVRlL2X7BbEk\u0003HCd",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\r",
+				"startIndex": 29,
+				"endIndex": 30,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "number-token",
+				"raw": "94",
+				"startIndex": 30,
+				"endIndex": 32,
+				"normalized": "94",
+				"value": "94",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 32,
+				"endIndex": 33,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "\\\u0000skoW25d4",
+				"startIndex": 33,
+				"endIndex": 43,
+				"normalized": "�skoW25d4",
+				"value": "�skoW25d4"
+			},
+			{
+				"type": "delim-token",
+				"raw": "%",
+				"startIndex": 43,
+				"endIndex": 44,
+				"normalized": "%",
+				"value": "%"
+			},
+			{
+				"type": "ident-token",
+				"raw": "l64UUskN",
+				"startIndex": 44,
+				"endIndex": 52,
+				"normalized": "l64UUskN",
+				"value": "l64UUskN"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"pHun\"",
+				"startIndex": 52,
+				"endIndex": 58,
+				"normalized": "\"pHun\"",
+				"value": "pHun"
+			},
+			{
+				"type": "delim-token",
+				"raw": "!",
+				"startIndex": 58,
+				"endIndex": 59,
+				"normalized": "!",
+				"value": "!"
+			}
+		]
+	},
+	"tests/fuzz/4f865903-e4dd-4a0b-83ed-e630cfa9dcca": {
+		"css": "gzO0{(p{DzQ7\u0000(a1;r1iN7w)",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "gzO0",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "gzO0",
+				"value": "gzO0"
+			},
+			{
+				"type": "{-token",
+				"raw": "{",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "{",
+				"value": null
+			},
+			{
+				"type": "(-token",
+				"raw": "(",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "(",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "p",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "p",
+				"value": "p"
+			},
+			{
+				"type": "{-token",
+				"raw": "{",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "{",
+				"value": null
+			},
+			{
+				"type": "function-token",
+				"raw": "DzQ7\u0000(",
+				"startIndex": 8,
+				"endIndex": 14,
+				"normalized": "DzQ7�(",
+				"value": "DzQ7�"
+			},
+			{
+				"type": "ident-token",
+				"raw": "a1",
+				"startIndex": 14,
+				"endIndex": 16,
+				"normalized": "a1",
+				"value": "a1"
+			},
+			{
+				"type": "semicolon-token",
+				"raw": ";",
+				"startIndex": 16,
+				"endIndex": 17,
+				"normalized": ";",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "r1iN7w",
+				"startIndex": 17,
+				"endIndex": 23,
+				"normalized": "r1iN7w",
+				"value": "r1iN7w"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 23,
+				"endIndex": 24,
+				"normalized": ")",
+				"value": null
+			}
+		]
+	},
+	"tests/fuzz/5181013c-60ab-483b-9c06-fb32c7e1e7e8": {
+		"css": "565'E{z\u0000U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1\\\r\nrey\thg7[5%rBK8RUC64Lu␌17O{E\\90873u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G'vK\ndhCEs3tValX ",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "565",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "565",
+				"value": "565",
+				"numberType": "integer"
+			},
+			{
+				"type": "string-token",
+				"raw": "'E{z\u0000U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1\\\r\nrey\thg7[5%rBK8RUC64Lu␌17O{E\\90873u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G'",
+				"startIndex": 3,
+				"endIndex": 263,
+				"normalized": "'E{z�U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1rey\thg7[5%rBK8RUC64Lu␌17O{E򐡳u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G'",
+				"value": "E{z�U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1rey\thg7[5%rBK8RUC64Lu␌17O{E򐡳u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G"
+			},
+			{
+				"type": "ident-token",
+				"raw": "vK",
+				"startIndex": 263,
+				"endIndex": 265,
+				"normalized": "vK",
+				"value": "vK"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 265,
+				"endIndex": 266,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "dhCEs3tValX",
+				"startIndex": 266,
+				"endIndex": 277,
+				"normalized": "dhCEs3tValX",
+				"value": "dhCEs3tValX"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 277,
+				"endIndex": 278,
+				"normalized": " ",
+				"value": null
+			}
+		]
+	},
+	"tests/fuzz/6d07fc79-586f-4efa-a0a2-37d4dd3beb09": {
+		"css": "FWUNqr7uv8300nz\b,8lU0j6B186kh \u00009 \u000eGZafxf2GIhL9%",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "FWUNqr7uv8300nz",
+				"startIndex": 0,
+				"endIndex": 15,
+				"normalized": "FWUNqr7uv8300nz",
+				"value": "FWUNqr7uv8300nz"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\b",
+				"startIndex": 15,
+				"endIndex": 16,
+				"normalized": "\b",
+				"value": "\b"
+			},
+			{
+				"type": "comma-token",
+				"raw": ",",
+				"startIndex": 16,
+				"endIndex": 17,
+				"normalized": ",",
+				"value": null
+			},
+			{
+				"type": "dimension-token",
+				"raw": "8lU0j6B186kh",
+				"startIndex": 17,
+				"endIndex": 29,
+				"normalized": "8lU0j6B186kh",
+				"value": "8",
+				"unit": "lU0j6B186kh",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 29,
+				"endIndex": 30,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "\u00009",
+				"startIndex": 30,
+				"endIndex": 32,
+				"normalized": "�9",
+				"value": "�9"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 32,
+				"endIndex": 33,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "delim-token",
+				"raw": "\u000e",
+				"startIndex": 33,
+				"endIndex": 34,
+				"normalized": "\u000e",
+				"value": "\u000e"
+			},
+			{
+				"type": "ident-token",
+				"raw": "GZafxf2GIhL9",
+				"startIndex": 34,
+				"endIndex": 46,
+				"normalized": "GZafxf2GIhL9",
+				"value": "GZafxf2GIhL9"
+			},
+			{
+				"type": "delim-token",
+				"raw": "%",
+				"startIndex": 46,
+				"endIndex": 47,
+				"normalized": "%",
+				"value": "%"
+			}
+		]
+	},
+	"tests/fuzz/7f49c8fc-8292-4a3e-828b-b5d028a80d5f": {
+		"css": "FZ 0B120h5QUbNbmTD2K8mAD傿i+Yv9V0KS14Ng18ag'\\\r\n{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\\BgK48qgu9'jVRS䎟ROYRbe0m5508k,O0C\u001f",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "FZ",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "FZ",
+				"value": "FZ"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "dimension-token",
+				"raw": "0B120h5QUbNbmTD2K8mAD傿i",
+				"startIndex": 3,
+				"endIndex": 28,
+				"normalized": "0B120h5QUbNbmTD2K8mAD傿i",
+				"value": "0",
+				"unit": "B120h5QUbNbmTD2K8mAD傿i",
+				"numberType": "integer"
+			},
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 28,
+				"endIndex": 29,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "ident-token",
+				"raw": "Yv9V0KS14Ng18ag",
+				"startIndex": 29,
+				"endIndex": 44,
+				"normalized": "Yv9V0KS14Ng18ag",
+				"value": "Yv9V0KS14Ng18ag"
+			},
+			{
+				"type": "string-token",
+				"raw": "'\\\r\n{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\\BgK48qgu9'",
+				"startIndex": 44,
+				"endIndex": 126,
+				"normalized": "'{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\u000bgK48qgu9'",
+				"value": "{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\u000bgK48qgu9"
+			},
+			{
+				"type": "ident-token",
+				"raw": "jVRS䎟ROYRbe0m5508k",
+				"startIndex": 126,
+				"endIndex": 146,
+				"normalized": "jVRS䎟ROYRbe0m5508k",
+				"value": "jVRS䎟ROYRbe0m5508k"
+			},
+			{
+				"type": "comma-token",
+				"raw": ",",
+				"startIndex": 146,
+				"endIndex": 147,
+				"normalized": ",",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "O0C",
+				"startIndex": 147,
+				"endIndex": 150,
+				"normalized": "O0C",
+				"value": "O0C"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\u001f",
+				"startIndex": 150,
+				"endIndex": 151,
+				"normalized": "\u001f",
+				"value": "\u001f"
+			}
+		]
+	},
+	"tests/fuzz/864d7812-b82f-47c2-94e4-8402ba6ba94a": {
+		"css": "'TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1\u0000rV7P'5528LZ14)䓑gqcRX\"aiu� \"z3i74FJ3\u00004x8F-V5b1f(U\u000b bUc",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "'TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1\u0000rV7P'",
+				"startIndex": 0,
+				"endIndex": 156,
+				"normalized": "'TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1�rV7P'",
+				"value": "TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1�rV7P"
+			},
+			{
+				"type": "dimension-token",
+				"raw": "5528LZ14",
+				"startIndex": 156,
+				"endIndex": 164,
+				"normalized": "5528LZ14",
+				"value": "5528",
+				"unit": "LZ14",
+				"numberType": "integer"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 164,
+				"endIndex": 165,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "䓑gqcRX",
+				"startIndex": 165,
+				"endIndex": 173,
+				"normalized": "䓑gqcRX",
+				"value": "䓑gqcRX"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"aiu� \"",
+				"startIndex": 173,
+				"endIndex": 182,
+				"normalized": "\"aiu� \"",
+				"value": "aiu� "
+			},
+			{
+				"type": "function-token",
+				"raw": "z3i74FJ3\u00004x8F-V5b1f(",
+				"startIndex": 182,
+				"endIndex": 202,
+				"normalized": "z3i74FJ3�4x8F-V5b1f(",
+				"value": "z3i74FJ3�4x8F-V5b1f"
+			},
+			{
+				"type": "ident-token",
+				"raw": "U",
+				"startIndex": 202,
+				"endIndex": 203,
+				"normalized": "U",
+				"value": "U"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\u000b",
+				"startIndex": 203,
+				"endIndex": 204,
+				"normalized": "\u000b",
+				"value": "\u000b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 204,
+				"endIndex": 205,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "bUc",
+				"startIndex": 205,
+				"endIndex": 208,
+				"normalized": "bUc",
+				"value": "bUc"
+			}
+		]
+	},
+	"tests/fuzz/91de56d3-d1c7-41c9-93e2-4b0770e36e79": {
+		"css": "\tb6SUejoqAEDa\u000e9,kYO\\",
+		"tokens": [
+			{
+				"type": "whitespace-token",
+				"raw": "\t",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "\t",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "b6SUejoqAEDa",
+				"startIndex": 1,
+				"endIndex": 13,
+				"normalized": "b6SUejoqAEDa",
+				"value": "b6SUejoqAEDa"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\u000e",
+				"startIndex": 13,
+				"endIndex": 14,
+				"normalized": "\u000e",
+				"value": "\u000e"
+			},
+			{
+				"type": "number-token",
+				"raw": "9",
+				"startIndex": 14,
+				"endIndex": 15,
+				"normalized": "9",
+				"value": "9",
+				"numberType": "integer"
+			},
+			{
+				"type": "comma-token",
+				"raw": ",",
+				"startIndex": 15,
+				"endIndex": 16,
+				"normalized": ",",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "kYO\\",
+				"startIndex": 16,
+				"endIndex": 20,
+				"normalized": "kYO�",
+				"value": "kYO�"
+			}
+		]
+	},
+	"tests/fuzz/b69ece36-057f-4450-9423-a1661787bce6": {
+		"css": "Iv1\u0000B}1E+X9oO\u001fN3G",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "Iv1\u0000B",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "Iv1�B",
+				"value": "Iv1�B"
+			},
+			{
+				"type": "}-token",
+				"raw": "}",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "}",
+				"value": null
+			},
+			{
+				"type": "dimension-token",
+				"raw": "1E",
+				"startIndex": 9,
+				"endIndex": 11,
+				"normalized": "1E",
+				"value": "1",
+				"unit": "E",
+				"numberType": "integer"
+			},
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "ident-token",
+				"raw": "X9oO",
+				"startIndex": 12,
+				"endIndex": 16,
+				"normalized": "X9oO",
+				"value": "X9oO"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\u001f",
+				"startIndex": 16,
+				"endIndex": 17,
+				"normalized": "\u001f",
+				"value": "\u001f"
+			},
+			{
+				"type": "ident-token",
+				"raw": "N3G",
+				"startIndex": 17,
+				"endIndex": 20,
+				"normalized": "N3G",
+				"value": "N3G"
+			}
+		]
+	},
+	"tests/fuzz/ccfaf86d-7471-465b-bbc8-5b65be03e9cf": {
+		"css": "H%7Zkc0P17 m2cqKMI5Cz34YPit.2.7,oP ",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "H",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "H",
+				"value": "H"
+			},
+			{
+				"type": "delim-token",
+				"raw": "%",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "%",
+				"value": "%"
+			},
+			{
+				"type": "dimension-token",
+				"raw": "7Zkc0P17",
+				"startIndex": 2,
+				"endIndex": 10,
+				"normalized": "7Zkc0P17",
+				"value": "7",
+				"unit": "Zkc0P17",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "m2cqKMI5Cz34YPit",
+				"startIndex": 11,
+				"endIndex": 27,
+				"normalized": "m2cqKMI5Cz34YPit",
+				"value": "m2cqKMI5Cz34YPit"
+			},
+			{
+				"type": "number-token",
+				"raw": ".2",
+				"startIndex": 27,
+				"endIndex": 29,
+				"normalized": ".2",
+				"value": ".2",
+				"numberType": "number"
+			},
+			{
+				"type": "number-token",
+				"raw": ".7",
+				"startIndex": 29,
+				"endIndex": 31,
+				"normalized": ".7",
+				"value": ".7",
+				"numberType": "number"
+			},
+			{
+				"type": "comma-token",
+				"raw": ",",
+				"startIndex": 31,
+				"endIndex": 32,
+				"normalized": ",",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "oP",
+				"startIndex": 32,
+				"endIndex": 34,
+				"normalized": "oP",
+				"value": "oP"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 34,
+				"endIndex": 35,
+				"normalized": " ",
+				"value": null
+			}
+		]
+	},
+	"tests/fuzz/eb11f9d4-f8ef-4e11-88dc-2cbf7f56e537": {
+		"css": ">u)k2a76}y4\\6fb9ONI\\",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": ">",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ">",
+				"value": ">"
+			},
+			{
+				"type": "ident-token",
+				"raw": "u",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "u",
+				"value": "u"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "k2a76",
+				"startIndex": 3,
+				"endIndex": 8,
+				"normalized": "k2a76",
+				"value": "k2a76"
+			},
+			{
+				"type": "}-token",
+				"raw": "}",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "}",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "y4\\6fb9ONI\\",
+				"startIndex": 9,
+				"endIndex": 20,
+				"normalized": "y4澹ONI�",
+				"value": "y4澹ONI�"
+			}
+		]
+	},
+	"tests/hash/0001": {
+		"css": "#1\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#1",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "#1",
+				"value": "1"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0002": {
+		"css": "#-2\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#-2",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "#-2",
+				"value": "-2"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0003": {
+		"css": "#--3\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#--3",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "#--3",
+				"value": "--3"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0004": {
+		"css": "#---4\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#---4",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "#---4",
+				"value": "---4"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0005": {
+		"css": "#a\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#a",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "#a",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0006": {
+		"css": "#-b\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#-b",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "#-b",
+				"value": "-b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0007": {
+		"css": "#--c\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#--c",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "#--c",
+				"value": "--c"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0008": {
+		"css": "#---d\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#---d",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "#---d",
+				"value": "---d"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0009": {
+		"css": "#_\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#_",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "#_",
+				"value": "_"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0010": {
+		"css": "#_1\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#_1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "#_1",
+				"value": "_1"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0011": {
+		"css": "#-\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#-",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "#-",
+				"value": "-"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0012": {
+		"css": "#+\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "#",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "#",
+				"value": "#"
+			},
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0013": {
+		"css": "##\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "#",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "#",
+				"value": "#"
+			},
+			{
+				"type": "delim-token",
+				"raw": "#",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "#",
+				"value": "#"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hash/0014": {
+		"css": "#",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "#",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "#",
+				"value": "#"
+			}
+		]
+	},
+	"tests/hash/0015": {
+		"css": "#aa𐀀\n",
+		"tokens": [
+			{
+				"type": "hash-token",
+				"raw": "#aa𐀀",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "#aa𐀀",
+				"value": "aa𐀀"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0001": {
+		"css": "-\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "-",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "-",
+				"value": "-"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0002": {
+		"css": "-1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-1",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "-1",
+				"value": "-1",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0003": {
+		"css": "-.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-.1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-.1",
+				"value": "-.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0004": {
+		"css": "--1\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "--1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "--1",
+				"value": "--1"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0005": {
+		"css": "-0\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-0",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "-0",
+				"value": "-0",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/hyphen-minus/0006": {
+		"css": "-->\n",
+		"tokens": [
+			{
+				"type": "CDC-token",
+				"raw": "-->",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-->",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0001": {
+		"css": "foo\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "foo",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "foo",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0002": {
+		"css": "--\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "--",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "--",
+				"value": "--"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0003": {
+		"css": "--0\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "--0",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "--0",
+				"value": "--0"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0004": {
+		"css": "-\\\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "-",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "-",
+				"value": "-"
+			},
+			{
+				"type": "delim-token",
+				"raw": "\\",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\\",
+				"value": "\\"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0005": {
+		"css": "-\\ \n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "-\\ ",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "- ",
+				"value": "- "
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0006": {
+		"css": "--💅\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "--💅",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "--💅",
+				"value": "--💅"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0007": {
+		"css": "-§\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "-§",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-§",
+				"value": "-§"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0008": {
+		"css": "-×\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "-×",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-×",
+				"value": "-×"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident/0009": {
+		"css": "--a𐀀\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "--a𐀀",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "--a𐀀",
+				"value": "--a𐀀"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0001": {
+		"css": "url(foo)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(foo)",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "url(foo)",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0002": {
+		"css": "\\75 Rl(foo)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "\\75 Rl(foo)",
+				"startIndex": 0,
+				"endIndex": 11,
+				"normalized": "uRl(foo)",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0003": {
+		"css": "uR\\6c (foo)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "uR\\6c (foo)",
+				"startIndex": 0,
+				"endIndex": 11,
+				"normalized": "uRl(foo)",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0004": {
+		"css": "url('foo')\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "url(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "url(",
+				"value": "url"
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 4,
+				"endIndex": 9,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0005": {
+		"css": "url( 'foo')\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "url(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "url(",
+				"value": "url"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 5,
+				"endIndex": 10,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 10,
+				"endIndex": 11,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0006": {
+		"css": "url(  'foo')\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "url(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "url(",
+				"value": "url"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "  ",
+				"startIndex": 4,
+				"endIndex": 6,
+				"normalized": "  ",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 6,
+				"endIndex": 11,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 12,
+				"endIndex": 13,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0007": {
+		"css": "url(   'foo')\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "url(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "url(",
+				"value": "url"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "   ",
+				"startIndex": 4,
+				"endIndex": 7,
+				"normalized": "   ",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 7,
+				"endIndex": 12,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 12,
+				"endIndex": 13,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 13,
+				"endIndex": 14,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0008": {
+		"css": "not-url(   'foo')\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "not-url(",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "not-url(",
+				"value": "not-url"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "   ",
+				"startIndex": 8,
+				"endIndex": 11,
+				"normalized": "   ",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 11,
+				"endIndex": 16,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 16,
+				"endIndex": 17,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 17,
+				"endIndex": 18,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/ident-like/0009": {
+		"css": "url(   foo)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(   foo)",
+				"startIndex": 0,
+				"endIndex": 11,
+				"normalized": "url(   foo)",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/left-curly-bracket/0001": {
+		"css": "{\n",
+		"tokens": [
+			{
+				"type": "{-token",
+				"raw": "{",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "{",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/left-parenthesis/0001": {
+		"css": "(\n",
+		"tokens": [
+			{
+				"type": "(-token",
+				"raw": "(",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "(",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/left-square-bracket/0001": {
+		"css": "[\n",
+		"tokens": [
+			{
+				"type": "[-token",
+				"raw": "[",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "[",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/less-than/0001": {
+		"css": "<\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "<",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "<",
+				"value": "<"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/less-than/0002": {
+		"css": "<!--\n",
+		"tokens": [
+			{
+				"type": "CDO-token",
+				"raw": "<!--",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "<!--",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/less-than/0003": {
+		"css": "<--\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "<",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "<",
+				"value": "<"
+			},
+			{
+				"type": "ident-token",
+				"raw": "--",
+				"startIndex": 1,
+				"endIndex": 3,
+				"normalized": "--",
+				"value": "--"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/less-than/0004": {
+		"css": "<!-\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "<",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "<",
+				"value": "<"
+			},
+			{
+				"type": "delim-token",
+				"raw": "!",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "!",
+				"value": "!"
+			},
+			{
+				"type": "delim-token",
+				"raw": "-",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "-",
+				"value": "-"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0001": {
+		"css": "10\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "10",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "10",
+				"value": "10",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0002": {
+		"css": "+10\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+10",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "+10",
+				"value": "+10",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0003": {
+		"css": "-10\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-10",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-10",
+				"value": "-10",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0004": {
+		"css": "0\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "0",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "0",
+				"value": "0",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0005": {
+		"css": "+0\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+0",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "+0",
+				"value": "+0",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0006": {
+		"css": "-0\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-0",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "-0",
+				"value": "-0",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0007": {
+		"css": ".0\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": ".0",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": ".0",
+				"value": ".0",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0008": {
+		"css": ".1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": ".1",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": ".1",
+				"value": ".1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0009": {
+		"css": "+.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+.1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "+.1",
+				"value": "+.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0010": {
+		"css": "-.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-.1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "-.1",
+				"value": "-.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0011": {
+		"css": "1.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "1.1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "1.1",
+				"value": "1.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0012": {
+		"css": "+1.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+1.1",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "+1.1",
+				"value": "+1.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0013": {
+		"css": "-1.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-1.1",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "-1.1",
+				"value": "-1.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0014": {
+		"css": "1.1e2\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "1.1e2",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "1.1e2",
+				"value": "1.1e2",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0015": {
+		"css": "+1.1e+2\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+1.1e+2",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "+1.1e+2",
+				"value": "+1.1e+2",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0016": {
+		"css": "-1.1e-2\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-1.1e-2",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "-1.1e-2",
+				"value": "-1.1e-2",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0017": {
+		"css": "-1.1e-22\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-1.1e-22",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "-1.1e-22",
+				"value": "-1.1e-22",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0018": {
+		"css": "-1.1e-22e\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "-1.1e-22e",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "-1.1e-22e",
+				"value": "-1.1e-22",
+				"unit": "e",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0019": {
+		"css": "1e+\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "1e",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "1e",
+				"value": "1",
+				"unit": "e",
+				"numberType": "integer"
+			},
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/number/0020": {
+		"css": ".2.7\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": ".2",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": ".2",
+				"value": ".2",
+				"numberType": "number"
+			},
+			{
+				"type": "number-token",
+				"raw": ".7",
+				"startIndex": 2,
+				"endIndex": 4,
+				"normalized": ".7",
+				"value": ".7",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/numeric/0001": {
+		"css": "-123.753e-2\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "-123.753e-2",
+				"startIndex": 0,
+				"endIndex": 11,
+				"normalized": "-123.753e-2",
+				"value": "-123.753e-2",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/numeric/0002": {
+		"css": "-123.753e-2px\n",
+		"tokens": [
+			{
+				"type": "dimension-token",
+				"raw": "-123.753e-2px",
+				"startIndex": 0,
+				"endIndex": 13,
+				"normalized": "-123.753e-2px",
+				"value": "-123.753e-2",
+				"unit": "px",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 13,
+				"endIndex": 14,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/numeric/0003": {
+		"css": "-123.753e-2%\n",
+		"tokens": [
+			{
+				"type": "percentage-token",
+				"raw": "-123.753e-2%",
+				"startIndex": 0,
+				"endIndex": 12,
+				"normalized": "-123.753e-2%",
+				"value": "-123.753e-2"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 12,
+				"endIndex": 13,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/numeric/0004": {
+		"css": "1.2.3\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "1.2",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "1.2",
+				"value": "1.2",
+				"numberType": "number"
+			},
+			{
+				"type": "number-token",
+				"raw": ".3",
+				"startIndex": 3,
+				"endIndex": 5,
+				"normalized": ".3",
+				"value": ".3",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/plus/0001": {
+		"css": "+\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/plus/0002": {
+		"css": "+1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+1",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "+1",
+				"value": "+1",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/plus/0003": {
+		"css": "+.1\n",
+		"tokens": [
+			{
+				"type": "number-token",
+				"raw": "+.1",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "+.1",
+				"value": "+.1",
+				"numberType": "number"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/plus/0004": {
+		"css": "++1\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "+",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "+",
+				"value": "+"
+			},
+			{
+				"type": "number-token",
+				"raw": "+1",
+				"startIndex": 1,
+				"endIndex": 3,
+				"normalized": "+1",
+				"value": "+1",
+				"numberType": "integer"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/reverse-solidus/0001": {
+		"css": "\\\n",
+		"tokens": [
+			{
+				"type": "delim-token",
+				"raw": "\\",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "\\",
+				"value": "\\"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/reverse-solidus/0002": {
+		"css": "\\#\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\#",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "#",
+				"value": "#"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/reverse-solidus/0003": {
+		"css": "\\ \n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\ ",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": " ",
+				"value": " "
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 2,
+				"endIndex": 3,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/reverse-solidus/0004": {
+		"css": "\\61 b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\61 b",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "ab",
+				"value": "ab"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/reverse-solidus/0005": {
+		"css": "\\",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "�",
+				"value": "�"
+			}
+		]
+	},
+	"tests/right-curly-bracket/0001": {
+		"css": "}\n",
+		"tokens": [
+			{
+				"type": "}-token",
+				"raw": "}",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "}",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/right-parenthesis/0001": {
+		"css": ")\n",
+		"tokens": [
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/right-square-bracket/0001": {
+		"css": "]\n",
+		"tokens": [
+			{
+				"type": "]-token",
+				"raw": "]",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "]",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/semi-colon/0001": {
+		"css": ";\n",
+		"tokens": [
+			{
+				"type": "semicolon-token",
+				"raw": ";",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": ";",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 1,
+				"endIndex": 2,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/string/0001": {
+		"css": "\"foo\"\n'foo'\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"foo\"",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "\"foo\"",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'foo'",
+				"startIndex": 6,
+				"endIndex": 11,
+				"normalized": "'foo'",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 11,
+				"endIndex": 12,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/string/0002": {
+		"css": "\"foo",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"foo",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "\"foo",
+				"value": "foo"
+			}
+		]
+	},
+	"tests/string/0003": {
+		"css": "\"fo\no\"",
+		"tokens": [
+			{
+				"type": "bad-string-token",
+				"raw": "\"fo",
+				"startIndex": 0,
+				"endIndex": 3,
+				"normalized": "\"fo",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "o",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "o",
+				"value": "o"
+			},
+			{
+				"type": "string-token",
+				"raw": "\"",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\"",
+				"value": ""
+			}
+		]
+	},
+	"tests/string/0004": {
+		"css": "\"fo\\\no\"\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"fo\\\no\"",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "\"foo\"",
+				"value": "foo"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/string/0005": {
+		"css": "\"fo\\",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"fo\\",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "\"fo",
+				"value": "fo"
+			}
+		]
+	},
+	"tests/string/0006": {
+		"css": "\"esc\\61 ped\"\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"esc\\61 ped\"",
+				"startIndex": 0,
+				"endIndex": 12,
+				"normalized": "\"escaped\"",
+				"value": "escaped"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 12,
+				"endIndex": 13,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/string/0007": {
+		"css": "\"foo\\\"",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"foo\\\"",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "\"foo\"",
+				"value": "foo\""
+			}
+		]
+	},
+	"tests/string/0008": {
+		"css": "\"'foo'\"\n'\"foo\"'\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"'foo'\"",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "\"'foo'\"",
+				"value": "'foo'"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'\"foo\"'",
+				"startIndex": 8,
+				"endIndex": 15,
+				"normalized": "'\"foo\"'",
+				"value": "\"foo\""
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 15,
+				"endIndex": 16,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/string/0009": {
+		"css": "\"\\\"foo\\\"\"\n'\\'foo\\''\n",
+		"tokens": [
+			{
+				"type": "string-token",
+				"raw": "\"\\\"foo\\\"\"",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "\"\"foo\"\"",
+				"value": "\"foo\""
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			},
+			{
+				"type": "string-token",
+				"raw": "'\\'foo\\''",
+				"startIndex": 10,
+				"endIndex": 19,
+				"normalized": "''foo''",
+				"value": "'foo'"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 19,
+				"endIndex": 20,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0001": {
+		"css": "url(\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(\n",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "url(\n",
+				"value": ""
+			}
+		]
+	},
+	"tests/url/0002": {
+		"css": "url(a\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(a\n",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "url(a\n",
+				"value": "a"
+			}
+		]
+	},
+	"tests/url/0003": {
+		"css": "url( a\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( a\n",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "url( a\n",
+				"value": "a"
+			}
+		]
+	},
+	"tests/url/0004": {
+		"css": "url()\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url()",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "url()",
+				"value": ""
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0005": {
+		"css": "url( )\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( )",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "url( )",
+				"value": ""
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0006": {
+		"css": "url( a)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( a)",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "url( a)",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0007": {
+		"css": "url( a )\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( a )",
+				"startIndex": 0,
+				"endIndex": 8,
+				"normalized": "url( a )",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 8,
+				"endIndex": 9,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0008": {
+		"css": "url( \\) )\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url( \\) )",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "url( ) )",
+				"value": ")"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0009": {
+		"css": "url(https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org)",
+				"startIndex": 0,
+				"endIndex": 212,
+				"normalized": "url(https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org)",
+				"value": "https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 212,
+				"endIndex": 213,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0010": {
+		"css": "url(https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_\\)\\(*&^#top)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "url(https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_\\)\\(*&^#top)",
+				"startIndex": 0,
+				"endIndex": 94,
+				"normalized": "url(https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_)(*&^#top)",
+				"value": "https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_)(*&^#top"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 94,
+				"endIndex": 95,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0011": {
+		"css": "Url(a)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "Url(a)",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "Url(a)",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0012": {
+		"css": "uRl(a)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "uRl(a)",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "uRl(a)",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0013": {
+		"css": "urL(a)\n",
+		"tokens": [
+			{
+				"type": "url-token",
+				"raw": "urL(a)",
+				"startIndex": 0,
+				"endIndex": 6,
+				"normalized": "urL(a)",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0014": {
+		"css": "uri(a)\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "uri(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "uri(",
+				"value": "uri"
+			},
+			{
+				"type": "ident-token",
+				"raw": "a",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/url/0015": {
+		"css": "uul(a)\n",
+		"tokens": [
+			{
+				"type": "function-token",
+				"raw": "uul(",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "uul(",
+				"value": "uul"
+			},
+			{
+				"type": "ident-token",
+				"raw": "a",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": ")-token",
+				"raw": ")",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": ")",
+				"value": null
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0001": {
+		"css": "\n",
+		"tokens": [
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0002": {
+		"css": " \n",
+		"tokens": [
+			{
+				"type": "whitespace-token",
+				"raw": " \n",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": " \n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0003": {
+		"css": "a  b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "a",
+				"startIndex": 0,
+				"endIndex": 1,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "  ",
+				"startIndex": 1,
+				"endIndex": 3,
+				"normalized": "  ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "b",
+				"startIndex": 3,
+				"endIndex": 4,
+				"normalized": "b",
+				"value": "b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0004": {
+		"css": "\\61 b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\61 b",
+				"startIndex": 0,
+				"endIndex": 5,
+				"normalized": "ab",
+				"value": "ab"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0005": {
+		"css": "\\000061 b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\000061 b",
+				"startIndex": 0,
+				"endIndex": 9,
+				"normalized": "ab",
+				"value": "ab"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 9,
+				"endIndex": 10,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0006": {
+		"css": "\\61  b\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "\\61 ",
+				"startIndex": 0,
+				"endIndex": 4,
+				"normalized": "a",
+				"value": "a"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": " ",
+				"startIndex": 4,
+				"endIndex": 5,
+				"normalized": " ",
+				"value": null
+			},
+			{
+				"type": "ident-token",
+				"raw": "b",
+				"startIndex": 5,
+				"endIndex": 6,
+				"normalized": "b",
+				"value": "b"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 6,
+				"endIndex": 7,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0007": {
+		"css": "\t\n",
+		"tokens": [
+			{
+				"type": "whitespace-token",
+				"raw": "\t\n",
+				"startIndex": 0,
+				"endIndex": 2,
+				"normalized": "\t\n",
+				"value": null
+			}
+		]
+	},
+	"tests/whitespace/0008": {
+		"css": "f\\ o\\\to\n",
+		"tokens": [
+			{
+				"type": "ident-token",
+				"raw": "f\\ o\\\to",
+				"startIndex": 0,
+				"endIndex": 7,
+				"normalized": "f o\to",
+				"value": "f o\to"
+			},
+			{
+				"type": "whitespace-token",
+				"raw": "\n",
+				"startIndex": 7,
+				"endIndex": 8,
+				"normalized": "\n",
+				"value": null
+			}
+		]
+	}
+}
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssBuilder.php
new file mode 100644
index 0000000000000..91bae79b0bec7
--- /dev/null
+++ b/tests/phpunit/tests/css-api/wpCssBuilder.php
@@ -0,0 +1,150 @@
+<?php
+
+/**
+ * Tests for the WP_CSS_Builder class.
+ *
+ * @group css-api
+ *
+ * @coversDefaultClass WP_CSS_Builder
+ */
+class Tests_CssApi_WpCssBuilder extends WP_UnitTestCase {
+	/**
+	 * @dataProvider data_string_escaping
+	 *
+	 * @covers ::string
+	 */
+	public function test_string_escaping( string $input, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Builder::string( $input ) );
+
+		/**
+		 * Ensure that a single, equivalent CSS string is produced.
+		 *
+		 * CSS pre-processing normalization is applied to the input to ensure
+		 * a match can be found.
+		 *
+		 * @see https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+		 */
+		$processor = WP_CSS_Token_Processor::create( WP_CSS_Builder::string( $input ) );
+		$processor->next_token();
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
+		$expected_decoded_value = strtr(
+			$input,
+			array(
+				"\r\n" => "\n",
+				"\r"   => "\n",
+				"\f"   => "\n",
+				"\0"   => '�',
+			)
+		);
+		$this->assertSame( $expected_decoded_value, $processor->get_token_value() );
+		$this->assertFalse( $processor->next_token() );
+	}
+
+	/**
+	 * Data provider for string escaping cases.
+	 *
+	 * @return array
+	 */
+	public static function data_string_escaping(): array {
+		return array(
+			// Passthrough — no escaping needed, only quoting.
+			'empty string'            => array( '', '""' ),
+			'simple ASCII'            => array( 'Arial', '"Arial"' ),
+			'spaces preserved'        => array( 'Exo 2', '"Exo 2"' ),
+			'leading/trailing spaces' => array( '  Arial  ', '"  Arial  "' ),
+			'whitespace-only'         => array( '   ', '"   "' ),
+			'numbers pass through'    => array( '12345', '"12345"' ),
+			'non-ASCII passthrough'   => array( 'café', '"café"' ),
+
+			// Backslash escaping — must happen first to prevent double-escaping.
+			'backslash'               => array( 'Back\\Slash', '"Back\5C Slash"' ),
+			'double backslash'        => array( '\\\\', '"\5C \5C "' ),
+			'backslash before quote'  => array( "a\\'b", '"a\5C \27 b"' ),
+
+			// NULL byte → U+FFFD replacement character.
+			'null byte'               => array( "a\0b", '"a�b"' ),
+
+			// Newline normalization — all variants become \A escape.
+			'LF'                      => array( "a\nb", '"a\A b"' ),
+			'CR'                      => array( "a\rb", '"a\A b"' ),
+			'CRLF as single escape'   => array( "a\r\nb", '"a\A b"' ),
+			'form feed'               => array( "a\fb", '"a\A b"' ),
+
+			// HTML-problematic characters.
+			'HTML characters < > &'   => array( 'a<b>c&d', '"a\3C b\3E c\26 d"' ),
+
+			// CSS-problematic characters.
+			'CSS syntax , ; { }'      => array( 'a,b;c{d}', '"a\2C b\3B c\7B d\7D "' ),
+			'single quote'            => array( "CSS's strings", '"CSS\27 s strings"' ),
+			'double quote'            => array( 'Say "Hi"', '"Say \22 Hi\22 "' ),
+		);
+	}
+
+	/**
+	 * Tests the example from the class docblock.
+	 *
+	 * @covers ::string
+	 */
+	public function test_docblock_example(): void {
+		$value    = 'CSS & a "<style>" tag\'s strings';
+		$expected = '"CSS \26  a \22 \3C style\3E \22  tag\27 s strings"';
+
+		$this->assertSame( $expected, WP_CSS_Builder::string( $value ) );
+	}
+
+	/**
+	 * Tests a string containing mixed newline types.
+	 *
+	 * @covers ::string
+	 */
+	public function test_mixed_newlines(): void {
+		$input    = "line1\nline2\rline3\r\nline4\fline5";
+		$expected = '"line1\A line2\A line3\A line4\A line5"';
+
+		$this->assertSame( $expected, WP_CSS_Builder::string( $input ) );
+	}
+
+	/**
+	 * Tests WP_CSS_Builder::ident() produces valid CSS ident tokens.
+	 *
+	 * @ticket TBD
+	 *
+	 * @dataProvider data_ident
+	 *
+	 * @covers ::ident
+	 */
+	public function test_ident( string $input, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Builder::ident( $input ) );
+	}
+
+	/**
+	 * Data provider for ident() tests.
+	 */
+	public static function data_ident(): Generator {
+		// Simple idents — no escaping needed.
+		yield 'Simple alpha ident' => array( 'serif', 'serif' );
+		yield 'Hyphenated ident' => array( 'sans-serif', 'sans-serif' );
+		yield 'Underscore prefix' => array( '_foo', '_foo' );
+		yield 'Single char' => array( 'a', 'a' );
+		yield 'Custom property prefix' => array( '--custom', '--custom' );
+
+		// Invalid ident starts — must be escaped.
+		yield 'Leading digits' => array( '123', '\\31 23' );
+		yield 'Leading digit with alpha' => array( '5foo', '\\35 foo' );
+		yield 'Hyphen then digit' => array( '-5px', '-\\35 px' );
+		yield 'Leading space' => array( ' leading-space', '\\20 leading-space' );
+		yield 'Leading tab' => array( "\tleading-tab", '\\9 leading-tab' );
+
+		// Whitespace within ident.
+		yield 'Space within' => array( 'My Font', 'My\\20 Font' );
+		yield 'Multiple spaces within' => array( 'a b c', 'a\\20 b\\20 c' );
+		yield 'Tab within' => array( "has\ttab", 'has\\9 tab' );
+		yield 'Newline within' => array( "has\nnewline", 'has\\A newline' );
+
+		// Special characters.
+		yield 'Apostrophe' => array( "Font's", 'Font\\27 s' );
+		yield 'Angle brackets' => array( '<html>', '\\3C html\\3E ' );
+		yield 'Comma' => array( 'a,b', 'a\\2C b' );
+		yield 'Semicolon' => array( 'a;b', 'a\\3B b' );
+	}
+}
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
new file mode 100644
index 0000000000000..3df3a78b23760
--- /dev/null
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -0,0 +1,2809 @@
+<?php
+
+/**
+ * Comprehensive CSS processor tests based on the CSS Syntax Level 3 specification.
+ *
+ * @group css-api
+ */
+class Tests_CssApi_WpCssTokenProcessor extends WP_UnitTestCase {
+	/**
+	 * Tests that the processor produces the expected tokens for all test cases.
+	 *
+	 * @dataProvider corpus_provider
+	 */
+	public function test_processor_matches_spec( string $css, array $expected_tokens ): void {
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor );
+		$this->assertSame( $expected_tokens, $actual_tokens );
+	}
+
+	/**
+	 * Provides the test cases from the @rmenke/css-processor-test test corpus.
+	 *
+	 * @see https://github.com/romainmenke/css-processor-tests/
+	 * @return array
+	 */
+	public static function corpus_provider(): array {
+		return json_decode( file_get_contents( DIR_TESTDATA . '/css-api/css-test-cases.json' ), true );
+	}
+
+	/**
+	 * Collects all tokens from a CSS processor into an array.
+	 *
+	 * @param WP_CSS_Token_Processor $processor The CSS processor.
+	 * @return array Array of tokens with type, raw, startIndex, endIndex, structured.
+	 */
+	public static function collect_tokens( WP_CSS_Token_Processor $processor, $keys = null ): array {
+		$tokens = array();
+
+		while ( $processor->next_token() ) {
+			$type = $processor->get_token_type();
+
+			$byte_start = $processor->get_token_start();
+			$byte_end   = $byte_start + $processor->get_token_length();
+
+			$token = array(
+				'type'       => $type,
+				'raw'        => $processor->get_unnormalized_token(),
+				'startIndex' => $byte_start,
+				'endIndex'   => $byte_end,
+				'normalized' => $processor->get_normalized_token(),
+				'value'      => $processor->get_token_value(),
+			);
+			if ( null !== $processor->get_token_unit() ) {
+				$token['unit'] = $processor->get_token_unit();
+			}
+			if (
+				WP_CSS_Token_Processor::TOKEN_NUMBER === $type ||
+				WP_CSS_Token_Processor::TOKEN_DIMENSION === $type
+			) {
+				$token['numberType'] = $processor->get_token_type_flag();
+			}
+
+			if ( null !== $keys ) {
+				$token = array_intersect_key( $token, array_flip( $keys ) );
+			}
+
+			$tokens[] = $token;
+		}
+
+		return $tokens;
+	}
+
+	/**
+	 * Tests that backslash-newline in a string token contributes nothing to the value.
+	 *
+	 * @ticket 62653
+	 * @dataProvider data_string_backslash_newline
+	 */
+	public function test_string_backslash_newline( string $css, string $expected_value ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
+		$this->assertSame( $expected_value, $processor->get_token_value() );
+	}
+
+	/**
+	 * Data provider for test_string_backslash_newline().
+	 *
+	 * @return array[]
+	 */
+	public static function data_string_backslash_newline(): array {
+		return array(
+			'backslash-LF'   => array( "'str\\\ning'", 'string' ),
+			'backslash-FF'   => array( "'str\\\fing'", 'string' ),
+			'backslash-CR'   => array( "'str\\\ring'", 'string' ),
+			'backslash-CRLF' => array( "'str\\\r\ning'", 'string' ),
+		);
+	}
+
+	/**
+	 * Tests that backslash-EOF in a string token contributes nothing to the value.
+	 *
+	 * @ticket 62653
+	 */
+	public function test_string_backslash_eof(): void {
+		$processor = WP_CSS_Token_Processor::create( "'string\\" );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
+		$this->assertSame( 'string', $processor->get_token_value() );
+	}
+
+	/**
+	 * Tests that backslash-newline in an unquoted URL produces a bad-url token.
+	 *
+	 * @ticket 62653
+	 * @dataProvider data_url_backslash_newline
+	 */
+	public function test_url_backslash_newline( string $css ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_URL, $processor->get_token_type() );
+	}
+
+	/**
+	 * Data provider for test_url_backslash_newline().
+	 *
+	 * @return array[]
+	 */
+	public static function data_url_backslash_newline(): array {
+		return array(
+			'backslash-LF'   => array( "url(ab\\\ncd)" ),
+			'backslash-FF'   => array( "url(ab\\\fcd)" ),
+			'backslash-CR'   => array( "url(ab\\\rcd)" ),
+			'backslash-CRLF' => array( "url(ab\\\r\ncd)" ),
+		);
+	}
+
+	/**
+	 * Tests that backslash-EOF in an unquoted URL produces U+FFFD in the value.
+	 *
+	 * @ticket 62653
+	 */
+	public function test_url_backslash_eof(): void {
+		$processor = WP_CSS_Token_Processor::create( 'url(string\\' );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_URL, $processor->get_token_type() );
+		$this->assertSame( "string\u{FFFD}", $processor->get_token_value() );
+	}
+
+	/**
+	 * Tests that backslash-newline stops an ident sequence.
+	 *
+	 * @ticket 62653
+	 * @dataProvider data_ident_backslash_newline
+	 */
+	public function test_ident_backslash_newline( string $css ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
+		$this->assertSame( 'abc', $processor->get_token_value() );
+	}
+
+	/**
+	 * Data provider for test_ident_backslash_newline().
+	 *
+	 * @return array[]
+	 */
+	public static function data_ident_backslash_newline(): array {
+		return array(
+			'backslash-LF'   => array( "abc\\\n" ),
+			'backslash-FF'   => array( "abc\\\f" ),
+			'backslash-CR'   => array( "abc\\\r" ),
+			'backslash-CRLF' => array( "abc\\\r\n" ),
+		);
+	}
+
+	/**
+	 * Tests that backslash-EOF in an ident produces U+FFFD in the value.
+	 *
+	 * @ticket 62653
+	 */
+	public function test_ident_backslash_eof(): void {
+		$processor = WP_CSS_Token_Processor::create( 'abc\\' );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
+		$this->assertSame( "abc\u{FFFD}", $processor->get_token_value() );
+	}
+
+	/**
+	 * Bad string tokens have no associated value.
+	 *
+	 * @ticket 62653
+	 */
+	public function test_bad_string_token_value_is_null(): void {
+		$processor = WP_CSS_Token_Processor::create( "'str\ning'" );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
+		$this->assertNull( $processor->get_token_value() );
+	}
+
+	/**
+	 * Tests that hash tokens expose the proper type flag.
+	 *
+	 * @ticket 62653
+	 * @dataProvider data_hash_tokens_expose_type_flags
+	 */
+	public function test_hash_tokens_expose_type_flags( string $css, array $expected_tokens ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		foreach ( $expected_tokens as $expected_token ) {
+			$this->assertTrue( $processor->next_token() );
+			$this->assertSame( $expected_token['type'], $processor->get_token_type() );
+			$this->assertSame( $expected_token['raw'], $processor->get_unnormalized_token() );
+			$this->assertSame( $expected_token['type_flag'], $processor->get_token_type_flag() );
+		}
+
+		$this->assertFalse( $processor->next_token() );
+		$this->assertNull( $processor->get_token_type_flag() );
+	}
+
+	/**
+	 * Data provider for test_hash_tokens_expose_type_flags().
+	 *
+	 * @return array[]
+	 */
+	public static function data_hash_tokens_expose_type_flags(): array {
+		return array(
+			'id hash'                           => array(
+				'#id',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#id',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_ID,
+					),
+				),
+			),
+			'unrestricted hash starting digit'  => array(
+				'#1id',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#1id',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED,
+					),
+				),
+			),
+			'id hash starting hyphen ident'     => array(
+				'#-id',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#-id',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_ID,
+					),
+				),
+			),
+			'unrestricted hash starting hyphen' => array(
+				'#-1id',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#-1id',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED,
+					),
+				),
+			),
+			'id hash starting escape'           => array(
+				'#\\@special',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#\\@special',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_ID,
+					),
+				),
+			),
+			'hash delimiter has no type flag'   => array(
+				'#',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_DELIM,
+						'raw'       => '#',
+						'type_flag' => null,
+					),
+				),
+			),
+			'following token clears type flag'  => array(
+				'#id .',
+				array(
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_HASH,
+						'raw'       => '#id',
+						'type_flag' => WP_CSS_Token_Processor::HASH_TOKEN_ID,
+					),
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+						'raw'       => ' ',
+						'type_flag' => null,
+					),
+					array(
+						'type'      => WP_CSS_Token_Processor::TOKEN_DELIM,
+						'raw'       => '.',
+						'type_flag' => null,
+					),
+				),
+			),
+		);
+	}
+
+	/**
+	 * Tests token type flags for numeric and non-numeric tokens.
+	 *
+	 * @dataProvider data_token_type_flag
+	 */
+	public function test_token_type_flag( string $css, ?string $expected_type ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( $expected_type, $processor->get_token_type_flag() );
+	}
+
+	/**
+	 * Data provider for test_token_type_flag().
+	 *
+	 * @return array[]
+	 */
+	public static function data_token_type_flag(): array {
+		return array(
+			'integer'               => array( '42', 'integer' ),
+			'positive integer'      => array( '+42', 'integer' ),
+			'negative integer'      => array( '-42', 'integer' ),
+			'zero'                  => array( '0', 'integer' ),
+			'decimal'               => array( '42.0', 'number' ),
+			'decimal with fraction' => array( '42.5', 'number' ),
+			'leading decimal point' => array( '.5', 'number' ),
+			'exponent lowercase'    => array( '1e2', 'number' ),
+			'exponent uppercase'    => array( '1E2', 'number' ),
+			'exponent with plus'    => array( '1E+2', 'number' ),
+			'exponent with minus'   => array( '1e-2', 'number' ),
+			'dimension integer'     => array( '10px', 'integer' ),
+			'dimension decimal'     => array( '10.5px', 'number' ),
+			'dimension exponent'    => array( '1e2px', 'number' ),
+			'percentage integer'    => array( '20%', null ),
+			'percentage decimal'    => array( '20.0%', null ),
+			'ident token'           => array( 'red', null ),
+			'string token'          => array( '"hello"', null ),
+		);
+	}
+
+	/**
+	 * Tests handling of non-UTF-8 byte sequences in identifiers.
+	 *
+	 * Invalid UTF-8 sequences should be replaced with U+FFFD replacement characters
+	 * during tokenization, allowing the CSS to continue processing.
+	 */
+	public function test_non_utf8_sequences_in_identifiers(): void {
+		// Invalid UTF-8 sequence 0xC0 0x80 (overlong encoding).
+		$css = ".class\xF1name";
+
+		$expected = array(
+			// .class�name (0xF1 replaced with U+FFFD).
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => "class\xF1name",
+				'normalized' => 'class�name',
+				'value'      => 'class�name',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value', 'unit' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	public function test_invalid_utf8_in_normal_segment_combined_with_escape(): void {
+		$css = ".test\xF1\\41name";
+
+		$expected = array(
+			array(
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
+			),
+			array(
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => "test\xF1\\41name",
+				'value' => "test\u{FFFD}Aname",
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	public function test_invalid_utf8_as_escaped_character(): void {
+		$css = ".a\\\xF1b";
+
+		$expected = array(
+			array(
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
+			),
+			array(
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => "a\\\xF1b",
+				'value' => "a\u{FFFD}b",
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	public function test_invalid_utf8_with_valid_prefix_in_identifiers(): void {
+		// Invalid 2-byte prefix is replaced with a single U+FFFD.
+		$css = ".test\xE2\x80name";
+
+		$expected = array(
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => "test\xE2\x80name",
+				'normalized' => 'test�name',
+				'value'      => 'test�name',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	public function test_invalid_utf8_with_two_single_byte_invalid_sequences(): void {
+		// Two distinct single byte invalid sequences are replaced with
+		// two separate U+FFFD replacement characters.
+		$css = ".test\xE2\xE2name";
+
+		$expected = array(
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => "test\xE2\xE2name",
+				'normalized' => 'test��name',
+				'value'      => 'test��name',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	/**
+	 * Legacy test to ensure basic tokenization still works.
+	 */
+	public function test_tokenize_labels_core_tokens(): void {
+		$css = <<<CSS
+@media screen and (min-width: 10px) {
+	background: url("/images/a.png");
+}
+CSS;
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
+				'raw'  => '@media',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'screen',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'and',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_PAREN,
+				'raw'  => '(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'min-width',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '10px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => "\n\t",
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'background',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'url(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'  => '"/images/a.png"',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => "\n",
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of complex selectors with pseudo-classes.
+	 */
+	public function test_complex_selector_with_pseudo_classes(): void {
+		$css = 'a:hover::before, div.class#id:not(.disabled)';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'a',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'hover',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'before',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'div',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '.',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'class',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'  => '#id',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'not(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '.',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'disabled',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of CSS comments.
+	 */
+	public function test_css_comments(): void {
+		$css = '/* This is a comment */ .class { color: red; /* Another comment */ }';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMENT,
+				'raw'  => '/* This is a comment */',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '.',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'class',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'red',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMENT,
+				'raw'  => '/* Another comment */',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of media queries.
+	 */
+	public function test_media_query(): void {
+		$css = '@media screen and (min-width: 768px) and (max-width: 1024px)';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
+				'raw'  => '@media',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'screen',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'and',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_PAREN,
+				'raw'  => '(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'min-width',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '768px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'and',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_PAREN,
+				'raw'  => '(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'max-width',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '1024px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of keyframes animation.
+	 */
+	public function test_keyframes_animation(): void {
+		$css = '@keyframes slide-in { 0% { opacity: 0; } 100% { opacity: 1; } }';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
+				'raw'  => '@keyframes',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'slide-in',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'  => '0%',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'opacity',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'  => '100%',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'opacity',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '1',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of vendor-prefixed properties.
+	 */
+	public function test_vendor_prefixed_properties(): void {
+		$css = '-webkit-transform: rotate(45deg); -moz-border-radius: 5px;';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => '-webkit-transform',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'rotate(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '45deg',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => '-moz-border-radius',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '5px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of attribute selectors.
+	 */
+	public function test_attribute_selectors(): void {
+		$css = 'input[type="text"][required], a[href^="https://"]';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'input',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET,
+				'raw'  => '[',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'type',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '=',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'  => '"text"',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET,
+				'raw'  => ']',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET,
+				'raw'  => '[',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'required',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET,
+				'raw'  => ']',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'a',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET,
+				'raw'  => '[',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'href',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '^',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '=',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'  => '"https://"',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET,
+				'raw'  => ']',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of calc() function with complex expressions.
+	 */
+	public function test_calc_function(): void {
+		$css = 'width: calc(100% - 20px * 2 + 5em);';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'width',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'calc(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'  => '100%',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '-',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '20px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '*',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '2',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '+',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '5em',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of RGB/RGBA color functions.
+	 */
+	public function test_color_functions(): void {
+		$css = 'color: rgb(255, 128, 0); background: rgba(0, 0, 0, 0.5);';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'rgb(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '255',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '128',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'background',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'rgba(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '0.5',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of CSS custom properties (variables).
+	 */
+	public function test_css_variables(): void {
+		$css = '--main-color: #ff0000; color: var(--main-color);';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => '--main-color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'  => '#ff0000',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'var(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => '--main-color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of gradient functions.
+	 */
+	public function test_gradient_functions(): void {
+		$css = 'background: linear-gradient(to right, red 0%, blue 100%);';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'background',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'linear-gradient(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'to',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'right',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'red',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'  => '0%',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'blue',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'  => '100%',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of grid layout properties.
+	 */
+	public function test_grid_layout(): void {
+		$css = 'grid-template-columns: repeat(3, 1fr); gap: 10px 20px;';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'grid-template-columns',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'repeat(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_NUMBER,
+				'raw'  => '3',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '1fr',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'gap',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '10px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '20px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of URL functions with various formats.
+	 */
+	public function test_url_formats(): void {
+		$css = 'background: url("image.png"), url(\'font.woff\'), url(https://example.com/bg.jpg);';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'background',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'url(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'  => '"image.png"',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'  => 'url(',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'  => "'font.woff'",
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'  => ')',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_URL,
+				'raw'  => 'url(https://example.com/bg.jpg)',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of !important declarations.
+	 */
+	public function test_important_declarations(): void {
+		$css = 'color: red !important; margin: 0px !important;';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'red',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '!',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'important',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'margin',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'  => '0px',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '!',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'important',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of multiple selectors with combinators.
+	 */
+	public function test_complex_combinators(): void {
+		$css = 'div > p + span ~ a.link';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'div',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '>',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'p',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '+',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'span',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '~',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'a',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '.',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'link',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests tokenization of escaped characters in identifiers.
+	 */
+	public function test_escaped_identifiers(): void {
+		$css = '.class\\:name, #id\\@special { color: blue; }';
+
+		$expected = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '.',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'class\\:name',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COMMA,
+				'raw'  => ',',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'  => '#id\\@special',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'  => '{',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'color',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'  => ':',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'  => 'blue',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'  => ';',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'  => ' ',
+			),
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'  => '}',
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$this->assertSame( $actual_tokens, $expected );
+	}
+
+	/**
+	 * Tests that get_normalized_token() applies CSS normalization.
+	 *
+	 * Uses a comprehensive CSS selector with rules that includes:
+	 * - CSS escapes in class names and IDs
+	 * - URLs with escape sequences
+	 * - String values with escapes and line endings
+	 * - Comments with various line ending characters
+	 * - Null bytes in identifiers
+	 * - Mixed line endings (\r\n, \r, \f) that need normalization
+	 */
+	public function test_get_normalized_token_applies_normalization(): void {
+		// Comprehensive CSS with normalization requirements.
+		$css = "/* Comment\r\nwith\flines */\r\n" .
+				".c\\6c ass.n\\61 me\r#id\\@value\r\n{\r\n" .
+				"\tbackground:\furl(path\\2f to\\2f image.png);\r\n" .
+				"\tcontent:\r\"text\\A string\";\r\n" .
+				'}';
+
+		$expected = array(
+			// Comment with \r\n and \f.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COMMENT,
+				'raw'        => "/* Comment\r\nwith\flines */",
+				'normalized' => "/* Comment\nwith\nlines */",
+				'value'      => null,
+			),
+			// Whitespace with \r\n.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r\n",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// Class selector delimiter.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			// Class name with escape (\6c = 'l'), space gets consumed by escape.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'c\\6c ass',
+				'normalized' => 'class', // Escapes decoded.
+				'value'      => 'class', // Decoded: \6c → l, space consumed.
+			),
+			// Delimiter.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			// Identifier with escape (\61 = 'a'), space gets consumed.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'n\\61 me',
+				'normalized' => 'name', // Escapes decoded.
+				'value'      => 'name', // Decoded: \61 → a, space consumed.
+			),
+			// Whitespace with \r.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// ID selector with escape.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'        => '#id\\@value',
+				'normalized' => '#id@value', // Escapes decoded.
+				'value'      => 'id@value', // Decoded value.
+			),
+			// Whitespace with \r\n.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r\n",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// Opening brace.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'        => '{',
+				'normalized' => '{',
+				'value'      => null,
+			),
+			// Whitespace with \r\n and tab (consumed together).
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r\n\t",
+				'normalized' => "\n\t",
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'background',
+				'normalized' => 'background',
+				'value'      => 'background',
+			),
+			// Colon.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			// Whitespace with \f.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\f",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// URL token with escapes (entire url(...) is one token).
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_URL,
+				'raw'        => 'url(path\\2f to\\2f image.png)',
+				'normalized' => 'url(path/to/image.png)', // Escapes decoded.
+				'value'      => 'path/to/image.png', // Decoded: \2f → /, spaces consumed.
+			),
+			// Semicolon.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			// Whitespace with \r\n and tab (consumed together).
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r\n\t",
+				'normalized' => "\n\t",
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'content',
+				'normalized' => 'content',
+				'value'      => 'content',
+			),
+			// Colon.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			// Whitespace with \r.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// String with escape (\A = newline, space consumed).
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'        => '"text\\A string"',
+				'normalized' => "\"text\nstring\"", // Escapes decoded, quotes preserved.
+				'value'      => "text\nstring", // \A → \n, space consumed.
+			),
+			// Semicolon.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			// Whitespace with \r\n.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => "\r\n",
+				'normalized' => "\n",
+				'value'      => null,
+			),
+			// Closing brace.
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'        => '}',
+				'normalized' => '}',
+				'value'      => null,
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	public function test_dimension_token_value(): void {
+		$css           = '10px;15em;20%;30pt;40pc;50vw;';
+		$expected      = array(
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '10px',
+				'normalized' => '10px',
+				'value'      => '10',
+				'unit'       => 'px',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '15em',
+				'normalized' => '15em',
+				'value'      => '15',
+				'unit'       => 'em',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'        => '20%',
+				'normalized' => '20%',
+				'value'      => '20',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '30pt',
+				'normalized' => '30pt',
+				'value'      => '30',
+				'unit'       => 'pt',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '40pc',
+				'normalized' => '40pc',
+				'value'      => '40',
+				'unit'       => 'pc',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '50vw',
+				'normalized' => '50vw',
+				'value'      => '50',
+				'unit'       => 'vw',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+		);
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value', 'unit' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	/**
+	 * Tests that create() validates encoding and only accepts UTF-8.
+	 */
+	public function test_create_validates_encoding(): void {
+		// UTF-8 encoding should work (default).
+		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }' );
+		$this->assertInstanceOf( WP_CSS_Token_Processor::class, $processor );
+
+		// UTF-8 encoding should work (explicit).
+		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'UTF-8' );
+		$this->assertInstanceOf( WP_CSS_Token_Processor::class, $processor );
+
+		// Other encodings should return null.
+		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'ISO-8859-1' );
+		$this->assertNull( $processor );
+
+		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'Windows-1252' );
+		$this->assertNull( $processor );
+	}
+
+	/**
+	 * Tests escape sequences in unusual and edge-case positions.
+	 *
+	 * Covers:
+	 * - Multiple consecutive escapes
+	 * - Escapes in function names
+	 * - Escapes in at-keywords
+	 * - Escapes in dimension units
+	 * - Null byte escapes (\0)
+	 * - Escaped special characters (@, #, !, etc.)
+	 * - Escaped whitespace that gets consumed by the escape
+	 * - Unicode escapes for various characters
+	 */
+	public function test_escape_sequences_in_unusual_places() {
+		// Complex CSS with escapes in many unusual but valid positions
+		$css = '@\\6D edia ' . // @media with \6D (m) and space consumed
+				'\\73 creen ' . // screen with \73 (s) and space consumed
+				'{' .
+				' .\\63 l\\61 ss\\5F name ' . // .class_name with escapes and spaces consumed
+				"#\\69 d\\5C 0test\x00 " . // #id\0test with null byte escape (should be preserved)
+														// AND an actual null byte (should be replaced with a U+FFFD REPLACEMENT CHARACTER)
+				'{' .
+				' c\\6F lor: ' . // color: with \6F (o) and space consumed
+				'r\\65 d ' . // red with escape
+				'\\21 important;' . // !important with escaped !
+				' w\\69 dth: ' . // width:
+				'10\\70 x;' . // 10px (dimension with escaped unit)
+				' background: ' .
+				'\\75 rl(' . // url( with escaped u
+				'"p\\61 th\\2F img\\2E png"' . // "path/img.png" with escapes
+				');' .
+				' content: "\\5C \\5C ";' . // "\\ \\" - escaped backslashes
+				' font-family: \\22 Arial\\22 ;' . // "Arial" with escaped quotes
+				' }' .
+				'}';
+
+		$expected = array(
+			// @\6D edia -> @media
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
+				'raw'        => '@\\6D edia',
+				'normalized' => '@media',
+				'value'      => 'media',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// \73 creen -> screen
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => '\\73 creen',
+				'normalized' => 'screen',
+				'value'      => 'screen',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'        => '{',
+				'normalized' => '{',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// Delimiter .
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'        => '.',
+				'normalized' => '.',
+				'value'      => '.',
+			),
+			// \63 l\61 ss\5F name -> class_name
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => '\\63 l\\61 ss\\5F name',
+				'normalized' => 'class_name',
+				'value'      => 'class_name',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// #\69 d\5C 0test -> #id\0test (with encoded null byte)
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'        => "#\\69 d\\5C 0test\x00",
+				'normalized' => "#id\\0test�",
+				// Ensure the value is normalized.
+				'value'      => "id\\0test�",
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'        => '{',
+				'normalized' => '{',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// c\6F lor -> color
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'c\\6F lor',
+				'normalized' => 'color',
+				'value'      => 'color',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// r\65 d -> red
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'r\\65 d',
+				'normalized' => 'red',
+				'value'      => 'red',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// \21 important -> !important (single identifier with escaped !)
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => '\\21 important',
+				'normalized' => '!important',
+				'value'      => '!important',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// w\69 dth -> width
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'w\\69 dth',
+				'normalized' => 'width',
+				'value'      => 'width',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// 10\70 x -> 10px (dimension with escaped unit)
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'        => '10\\70 x',
+				'normalized' => '10px',
+				'value'      => '10',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'background',
+				'normalized' => 'background',
+				'value'      => 'background',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// \75 rl( -> url( (escaped function name)
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'        => '\\75 rl(',
+				'normalized' => 'url(',
+				'value'      => 'url',
+			),
+			// String with escapes: "p\61 th\2F img\2E png"
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'        => '"p\\61 th\\2F img\\2E png"',
+				'normalized' => '"path/img.png"',
+				'value'      => 'path/img.png',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'        => ')',
+				'normalized' => ')',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'content',
+				'normalized' => 'content',
+				'value'      => 'content',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// String with escaped backslashes: "\5C \5C " -> "\\"
+			// Each \5C sequence (with trailing space consumed) becomes one backslash
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'        => '"\\5C \\5C "',
+				'normalized' => '"\\\\"',
+				'value'      => '\\\\',  // Two backslashes total
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => 'font-family',
+				'normalized' => 'font-family',
+				'value'      => 'font-family',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'        => ':',
+				'normalized' => ':',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			// \22 Arial\22 -> "Arial" (escaped quotes make it an ident)
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'        => '\\22 Arial\\22 ',
+				'normalized' => '"Arial"',
+				'value'      => '"Arial"',
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'        => ';',
+				'normalized' => ';',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'        => ' ',
+				'normalized' => ' ',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'        => '}',
+				'normalized' => '}',
+				'value'      => null,
+			),
+			array(
+				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'        => '}',
+				'normalized' => '}',
+				'value'      => null,
+			),
+		);
+
+		$processor     = WP_CSS_Token_Processor::create( $css );
+		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$this->assertSame( $expected, $actual_tokens );
+	}
+
+	/**
+	 * Tests that set_token_value() only works on URL tokens.
+	 */
+	public function test_set_token_value_only_works_on_url_tokens(): void {
+		$css       = 'color: red; background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->setExpectedIncorrectUsage( 'WP_CSS_Token_Processor::set_token_value' );
+
+		while ( $processor->next_token() ) {
+			$token_type = $processor->get_token_type();
+
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $token_type ) {
+				// Should succeed on URL tokens.
+				$this->assertTrue( $processor->set_token_value( 'new.jpg' ) );
+			} else {
+				// Should fail on non-URL tokens.
+				$this->assertFalse( $processor->set_token_value( 'test' ) );
+			}
+		}
+
+		// Verify the update was applied.
+		$updated = $processor->get_updated_css();
+		$this->assertSame( 'color: red; background: url("new.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that set_token_value() properly escapes special characters in quoted URLs.
+	 */
+	public function test_set_token_value_escapes_special_characters(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				// URL with spaces, quotes, and parentheses.
+				$processor->set_token_value( 'path with spaces("special").jpg' );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		$this->assertSame( 'background: url("path with spaces(\\22 special\\22 ).jpg");', $updated );
+	}
+
+	/**
+	 * Tests that set_token_value() preserves Unicode characters in quoted URLs.
+	 */
+	public function test_set_token_value_encodes_unicode(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				// URL with Unicode characters: "测试.jpg" (Chinese characters).
+				$processor->set_token_value( '测试.jpg' );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		$this->assertSame( 'background: url("测试.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that set_token_value() preserves emoji in quoted URLs.
+	 */
+	public function test_set_token_value_handles_emoji(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				// URL with emoji: "image😀.jpg".
+				$processor->set_token_value( 'image😀.jpg' );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		$this->assertSame( 'background: url("image😀.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that multiple URL values can be updated in the same CSS.
+	 */
+	public function test_set_token_value_multiple_urls(): void {
+		$css       = 'background: url(old1.jpg); border-image: url(old2.png);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$url_count = 0;
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				++$url_count;
+				if ( 1 === $url_count ) {
+					$processor->set_token_value( 'new1.jpg' );
+				} elseif ( 2 === $url_count ) {
+					$processor->set_token_value( 'new2.png' );
+				}
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		// Verify both URLs were updated.
+		$this->assertSame( 'background: url("new1.jpg"); border-image: url("new2.png");', $updated );
+	}
+
+	/**
+	 * Tests that newlines are properly escaped in quoted URLs.
+	 */
+	public function test_set_token_value_escapes_control_characters(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				// URL with newlines and carriage returns.
+				$processor->set_token_value( "path\nwith\rnewlines\ftest.jpg" );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		$this->assertSame( 'background: url("path\\A with\\A newlines\\A test.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that backslashes are properly escaped in quoted URLs.
+	 */
+	public function test_set_token_value_escapes_backslashes(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				$processor->set_token_value( 'path\\with\\backslashes.jpg' );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		// Verify backslashes are escaped as \\.
+		$this->assertSame( 'background: url("path\\5C with\\5C backslashes.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that get_updated_css() returns original CSS when no changes are made.
+	 */
+	public function test_get_updated_css_returns_original_when_unchanged(): void {
+		$css       = 'background: url(image.jpg); color: red;';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		// Iterate through tokens without making changes.
+		while ( $processor->next_token() ) {
+			// Do nothing.
+		}
+
+		$updated = $processor->get_updated_css();
+
+		// Should return original CSS.
+		$this->assertSame( $css, $updated );
+	}
+
+	/**
+	 * Tests that safe ASCII characters are preserved in quoted URLs.
+	 */
+	public function test_set_token_value_preserves_safe_characters(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				// URL with safe characters: letters, digits, hyphens, underscores, dots, slashes.
+				$processor->set_token_value( 'path/to/my-image_2024.jpg' );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		// Verify safe characters are preserved as-is in quoted URL.
+		$this->assertSame( 'background: url("path/to/my-image_2024.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that invalid UTF-8 sequences are replaced in quoted URLs.
+	 */
+	public function test_set_token_with_invalid_utf8_sequence(): void {
+		$css       = 'background: url(old.jpg);';
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
+				$processor->set_token_value( "\xC0.jpg" );
+			}
+		}
+
+		$updated = $processor->get_updated_css();
+
+		$this->assertSame( 'background: url("�.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that decode_range() respects the token's length boundary.
+	 *
+	 * The escape sequence \41 (= "A") triggers the slow path. The CSS after
+	 * the closing quote must not appear in the token value.
+	 */
+	public function test_decode_range_respects_length_boundary(): void {
+		$processor = WP_CSS_Token_Processor::create( '"hello\\41 world"; color: red;' );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
+		$this->assertSame( 'helloAworld', $processor->get_token_value() );
+		$this->assertSame( '"helloAworld"', $processor->get_normalized_token() );
+	}
+
+	/**
+	 * Tests that decode_escape_at() consumes at most six hex digits.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
+	 */
+	public function test_decode_escape_at_hex_limit_is_six_digits(): void {
+		$processor = WP_CSS_Token_Processor::create( '"\\0000411rest"' );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
+		$this->assertSame( 'A1rest', $processor->get_token_value() );
+	}
+
+	/**
+	 * Test bounds check when consuming and ident start token.
+	 */
+	public function test_ident_start_codepoint_bounds_check(): void {
+		$processor       = WP_CSS_Token_Processor::create( '-' );
+		$actual_tokens   = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$expected_tokens = array(
+			array(
+				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'  => '-',
+			),
+		);
+		$this->assertSame( $expected_tokens, $actual_tokens );
+	}
+}

From a80bd985f207cf45994b4773e7965a1bf4a039fd Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 26 Aug 2026 14:34:12 +0400
Subject: [PATCH 02/77] Harden CSS builder identifier serialization

---
 .../css-api/class-wp-css-builder.php          | 149 ++----------------
 tests/phpunit/tests/css-api/wpCssBuilder.php  |  36 ++++-
 2 files changed, 46 insertions(+), 139 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
index 35250335da661..85c6b29707367 100644
--- a/src/wp-includes/css-api/class-wp-css-builder.php
+++ b/src/wp-includes/css-api/class-wp-css-builder.php
@@ -2,7 +2,7 @@
 
 abstract class WP_CSS_Builder {
 	/**
-	 * Create a CSS ident token from a plain PHP string value.
+	 * Serialize a plain PHP string as CSS identifier text.
 	 *
 	 * Characters not valid in CSS identifiers are hex-escaped. This uses
 	 * the same safety escaping as {@see WP_CSS_Builder::string()} for HTML
@@ -12,8 +12,11 @@ abstract class WP_CSS_Builder {
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
-	 * @param string $value Decoded string value to encode as a CSS ident.
-	 * @return string CSS ident token text.
+	 * An empty string serializes to an empty string. Callers that require an
+	 * ident token must reject an empty value.
+	 *
+	 * @param string $value Decoded string value to encode as a CSS identifier.
+	 * @return string Serialized CSS identifier text.
 	 */
 	public static function ident( string $value ): string {
 		$value  = wp_scrub_utf8( $value );
@@ -47,6 +50,12 @@ public static function ident( string $value ): string {
 
 			// Hyphen: valid in idents, but check for hyphen-digit at start.
 			if ( 0x2D === $byte ) {
+				// A hyphen standing alone must be escaped to form an ident token.
+				if ( 0 === $i && 1 === $length ) {
+					$result .= '\\2D ';
+					continue;
+				}
+
 				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
 				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
 					$result .= '-';
@@ -83,7 +92,7 @@ public static function ident( string $value ): string {
 	 *     $css_string = WP_CSS_Builder::string( $value );
 	 *     echo "<style>*::before { content: {$css_string}; }</style>";
 	 *
-	 * CSS strings are quoted many characters that are problematic in HTML
+	 * CSS strings are quoted, and many characters that are problematic in HTML
 	 * or may be complicated for rudimentary CSS or HTML processors to handle
 	 * are encoded using Unicode escape sequences.
 	 *
@@ -126,136 +135,4 @@ public static function string( string $value ): string {
 		);
 		return "\"{$escaped}\"";
 	}
-
-	public static function normalize_and_escape_css( string $css ): string {
-		$css       = wp_scrub_utf8( $css );
-		$processor = WP_CSS_Token_Processor::create( $css );
-		if ( null === $processor ) {
-			return '';
-		}
-
-		$normalized_css = '';
-
-		while ( $processor->next_token() ) {
-			switch ( $processor->get_token_type() ) {
-
-				// Basic punctuation:
-				case WP_CSS_Token_Processor::TOKEN_SEMICOLON:
-					$normalized_css .= ';';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_COMMA:
-					$normalized_css .= ',';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_WHITESPACE:
-					$normalized_css .= ' ';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_COLON:
-					$normalized_css .= ':';
-					break;
-
-				// Paired punctuation:
-				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACE:
-					$normalized_css .= '{';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE:
-					$normalized_css .= '}';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_LEFT_PAREN:
-					$normalized_css .= '(';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN:
-					$normalized_css .= ')';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET:
-					$normalized_css .= '[';
-					break;
-				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET:
-					$normalized_css .= ']';
-					break;
-
-				// "@" + ident
-				case WP_CSS_Token_Processor::TOKEN_AT_KEYWORD:
-					$normalized_css .= '@' . self::ident( $processor->get_token_value() );
-					break;
-
-				// ident + "("
-				case WP_CSS_Token_Processor::TOKEN_FUNCTION:
-					$normalized_css .= self::ident( $processor->get_token_value() ) . '(';
-					break;
-
-				/*
-				 * Hash tokens are not idents but their value can be escaped as such.
-				 *
-				 *     ‖→ "#" →─┐   ┌──────────────────────────────┐   ┌─→‖
-				 *              ├─→─┤ a-z A-Z 0-9 _ - or non-ASCII ├─→─┤
-				 *              │   └──────────────────────────────┘   │
-				 *              │   ┌──────────────────────────────┐   │
-				 *              ├─→─┤            escape            ├─→─┤
-				 *              │   └──────────────────────────────┘   │
-				 *              └──────────────────←───────────────────┘
-				 */
-				case WP_CSS_Token_Processor::TOKEN_HASH:
-					$normalized_css .= '#' . self::ident( $processor->get_token_value() );
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_DIMENSION:
-					$normalized_css .= $processor->get_token_value() . $processor->get_token_unit();
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_PERCENTAGE:
-					$normalized_css .= "%{$processor->get_token_value()}";
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_NUMBER:
-					$normalized_css .= $processor->get_token_value();
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_DELIM:
-					$normalized_css .= $processor->get_token_value();
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_IDENT:
-					$normalized_css .= self::ident( $processor->get_token_value() );
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_STRING:
-					var_dump( $processor->get_token_value() );
-					$normalized_css .= self::string( $processor->get_token_value() );
-					break;
-
-				// Keep or strip comments?
-				case WP_CSS_Token_Processor::TOKEN_COMMENT:
-					$normalized_css .= substr( $css, $processor->get_token_start(), $processor->get_token_length() );
-					break;
-
-				/**
-				 * A <bad-string-token> is an open string that reaches a newline.
-				 *
-				 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
-				 *
-				 * @see https://www.w3.org/TR/css-syntax-3/#preserved-tokens
-				 * > Note: The tokens <}-token>s, <)-token>s, <]-token>, <bad-string-token>, and <bad-url-token> are always parse errors, but they are preserved in the token stream by this specification to allow other specs, such as Media Queries, to define more fine-grained error-handling than just dropping an entire declaration or block.
-				 */
-				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
-					$normalized_css .= substr( $css, $processor->get_token_start(), $processor->get_token_length() ) . "\n";
-					break;
-
-				case WP_CSS_Token_Processor::TOKEN_URL:
-				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
-				case WP_CSS_Token_Processor::TOKEN_CDC:
-				case WP_CSS_Token_Processor::TOKEN_CDO:
-				default:
-					throw new Error( 'unhandled token type ' . $processor->get_token_type() . ' with value ' . var_export( $processor->get_token_value(), true ) );
-			}
-		}
-
-		return strtr(
-			$normalized_css,
-			array(
-				' '  => '␠',
-				"\t" => "␉\t",
-				"\n" => "␊\n",
-			)
-		);
-	}
 }
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssBuilder.php
index 91bae79b0bec7..b3f0c52501414 100644
--- a/tests/phpunit/tests/css-api/wpCssBuilder.php
+++ b/tests/phpunit/tests/css-api/wpCssBuilder.php
@@ -105,28 +105,54 @@ public function test_mixed_newlines(): void {
 	}
 
 	/**
-	 * Tests WP_CSS_Builder::ident() produces valid CSS ident tokens.
+	 * Tests WP_CSS_Builder::ident() serializes CSS identifiers.
 	 *
-	 * @ticket TBD
+	 * @ticket 62653
 	 *
 	 * @dataProvider data_ident
 	 *
 	 * @covers ::ident
 	 */
 	public function test_ident( string $input, string $expected ): void {
-		$this->assertSame( $expected, WP_CSS_Builder::ident( $input ) );
+		$serialized = WP_CSS_Builder::ident( $input );
+		$this->assertSame( $expected, $serialized );
+
+		$processor = WP_CSS_Token_Processor::create( $serialized );
+		if ( '' === $input ) {
+			$this->assertFalse( $processor->next_token() );
+			return;
+		}
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
+
+		$expected_decoded_value = strtr(
+			$input,
+			array(
+				"\r\n" => "\n",
+				"\r"   => "\n",
+				"\f"   => "\n",
+				"\0"   => '�',
+			)
+		);
+		$this->assertSame( $expected_decoded_value, $processor->get_token_value() );
+		$this->assertFalse( $processor->next_token() );
 	}
 
 	/**
 	 * Data provider for ident() tests.
 	 */
 	public static function data_ident(): Generator {
+		yield 'Empty identifier' => array( '', '' );
+
 		// Simple idents — no escaping needed.
 		yield 'Simple alpha ident' => array( 'serif', 'serif' );
 		yield 'Hyphenated ident' => array( 'sans-serif', 'sans-serif' );
 		yield 'Underscore prefix' => array( '_foo', '_foo' );
 		yield 'Single char' => array( 'a', 'a' );
+		yield 'Single hyphen' => array( '-', '\\2D ' );
 		yield 'Custom property prefix' => array( '--custom', '--custom' );
+		yield 'Non-ASCII' => array( 'café', 'café' );
 
 		// Invalid ident starts — must be escaped.
 		yield 'Leading digits' => array( '123', '\\31 23' );
@@ -134,17 +160,21 @@ public static function data_ident(): Generator {
 		yield 'Hyphen then digit' => array( '-5px', '-\\35 px' );
 		yield 'Leading space' => array( ' leading-space', '\\20 leading-space' );
 		yield 'Leading tab' => array( "\tleading-tab", '\\9 leading-tab' );
+		yield 'Leading control character' => array( "\x01foo", '\\1 foo' );
 
 		// Whitespace within ident.
 		yield 'Space within' => array( 'My Font', 'My\\20 Font' );
 		yield 'Multiple spaces within' => array( 'a b c', 'a\\20 b\\20 c' );
 		yield 'Tab within' => array( "has\ttab", 'has\\9 tab' );
 		yield 'Newline within' => array( "has\nnewline", 'has\\A newline' );
+		yield 'NULL byte within' => array( "has\0null", 'has�null' );
+		yield 'DEL within' => array( "has\x7Fdelete", 'has\\7F delete' );
 
 		// Special characters.
 		yield 'Apostrophe' => array( "Font's", 'Font\\27 s' );
 		yield 'Angle brackets' => array( '<html>', '\\3C html\\3E ' );
 		yield 'Comma' => array( 'a,b', 'a\\2C b' );
 		yield 'Semicolon' => array( 'a;b', 'a\\3B b' );
+		yield 'Backslash' => array( 'a\\b', 'a\\5C b' );
 	}
 }

From db896db7f97b9550ea960c75275b1e5f09e5b00f Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 26 Aug 2026 14:42:34 +0400
Subject: [PATCH 03/77] Harden CSS token value updates

---
 .../css-api/class-wp-css-builder.php          | 21 +++-
 .../css-api/class-wp-css-token-processor.php  | 99 +++++++++++++++----
 .../tests/css-api/wpCssTokenProcessor.php     | 49 +++++++--
 3 files changed, 144 insertions(+), 25 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
index 85c6b29707367..1d2e27b06a901 100644
--- a/src/wp-includes/css-api/class-wp-css-builder.php
+++ b/src/wp-includes/css-api/class-wp-css-builder.php
@@ -1,5 +1,17 @@
 <?php
-
+/**
+ * CSS API: WP_CSS_Builder class
+ *
+ * @package WordPress
+ * @subpackage CSS-API
+ * @since {WP_VERSION}
+ */
+
+/**
+ * Serializes decoded values for safe interpolation into CSS source.
+ *
+ * @since {WP_VERSION}
+ */
 abstract class WP_CSS_Builder {
 	/**
 	 * Serialize a plain PHP string as CSS identifier text.
@@ -12,6 +24,8 @@ abstract class WP_CSS_Builder {
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * An empty string serializes to an empty string. Callers that require an
 	 * ident token must reject an empty value.
 	 *
@@ -97,6 +111,11 @@ public static function ident( string $value ): string {
 	 * are encoded using Unicode escape sequences.
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 *
+	 * @since {WP_VERSION}
+	 *
+	 * @param string $value Decoded string value to encode as a quoted CSS string.
+	 * @return string Serialized quoted CSS string text.
 	 */
 	public static function string( string $value ): string {
 		$value   = wp_scrub_utf8( $value );
diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 74c548dc1ec3a..abc5a9fd63ac8 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * CSS API: WP_CSS_Token_Processor class
+ *
+ * @package WordPress
+ * @subpackage CSS-API
+ * @since {WP_VERSION}
+ */
 
 /**
  * Tokenizes CSS according to the CSS Syntax Level 3 specification.
@@ -59,7 +66,7 @@
  *         }
  *     }
  *     $result = $processor->get_updated_css();
- *     // background: url(uploads/new.jpg) center / cover;
+ *     // background: url("uploads/new.jpg") center / cover;
  *
  * Gathering diagnostics with byte offsets:
  *
@@ -76,6 +83,8 @@
  *         }
  *     }
  *
+ * @since {WP_VERSION}
+ *
  * @see https://www.w3.org/TR/css-syntax-3/#tokenization
  */
 class WP_CSS_Token_Processor {
@@ -310,6 +319,8 @@ class WP_CSS_Token_Processor {
 	 *
 	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string $css         CSS source to tokenize.
 	 */
 	private function __construct( string $css ) {
@@ -326,6 +337,8 @@ private function __construct( string $css ) {
 	 *
 	 * - The only supported document encoding is `UTF-8`, which is the default value.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string $css      CSS source to tokenize.
 	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
 	 * @return static|null The created processor if successful, otherwise null.
@@ -345,6 +358,8 @@ public static function create( string $css, string $encoding = 'UTF-8' ) {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return bool Whether a token was found.
 	 */
 	public function next_token(): bool {
@@ -622,6 +637,8 @@ public function next_token(): bool {
 	/**
 	 * Gets the current token type.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null
 	 * @phpstan-return self::TOKEN_*|null
 	 */
@@ -640,6 +657,8 @@ public function get_token_type(): ?string {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null
 	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
 	 */
@@ -658,6 +677,8 @@ public function get_token_type_flag(): ?string {
 	 * This is different from get_token_value() which returns the semantic value
 	 * (e.g., for strings: content without quotes; for numbers: numeric value).
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null
 	 */
 	public function get_normalized_token(): ?string {
@@ -678,6 +699,8 @@ public function get_normalized_token(): ?string {
 	 * Returns the exact bytes from the source without any normalization.
 	 * This preserves original line endings (\r\n, \r, \f) and null bytes.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null
 	 */
 	public function get_unnormalized_token(): ?string {
@@ -702,6 +725,8 @@ public function get_unnormalized_token(): ?string {
 	 * - For strings/URLs: the decoded string value
 	 * - For other tokens: null
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#token-value
 	 * @return string|null
 	 */
@@ -794,6 +819,8 @@ public function get_token_value(): ?string {
 	 *
 	 * Only meaningful for URL and STRING tokens. Returns false for all other token types.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return bool Whether the current token value starts with "data:" (case-insensitive).
 	 */
 	public function is_data_uri(): bool {
@@ -818,6 +845,8 @@ public function is_data_uri(): bool {
 	/**
 	 * Gets the token start at.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return int|null
 	 */
 	public function get_token_start(): ?int {
@@ -827,6 +856,8 @@ public function get_token_start(): ?int {
 	/**
 	 * Gets the token length.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return int|null
 	 */
 	public function get_token_length(): ?int {
@@ -836,6 +867,8 @@ public function get_token_length(): ?int {
 	/**
 	 * Gets the unit for dimension tokens.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null
 	 */
 	public function get_token_unit(): ?string {
@@ -845,6 +878,8 @@ public function get_token_unit(): ?string {
 	/**
 	 * Gets the byte at where the token value starts (for STRING and URL tokens).
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return int|null
 	 */
 	public function get_token_value_start(): ?int {
@@ -854,6 +889,8 @@ public function get_token_value_start(): ?int {
 	/**
 	 * Gets the byte length of the token value (for STRING and URL tokens).
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return int|null
 	 */
 	public function get_token_value_length(): ?int {
@@ -861,13 +898,14 @@ public function get_token_value_length(): ?int {
 	}
 
 	/**
-	 * Sets the value of the current URL token.
+	 * Sets the value of the current URL or string token.
 	 *
-	 * This method allows modifying the URL value in url() tokens. The new value
-	 * will be properly escaped according to CSS URL syntax rules.
+	 * The new decoded value is serialized as a quoted CSS string. For a URL
+	 * token, only the value inside `url()` is replaced, converting an unquoted
+	 * URL such as `url(old.jpg)` to `url("new.jpg")`.
 	 *
-	 * Currently only URL tokens are supported. Attempting to set the value on
-	 * other token types will return false.
+	 * Repeated calls for the same current token supersede the previous update.
+	 * Attempting to set the value on another token type returns false.
 	 *
 	 * Example:
 	 *
@@ -879,26 +917,28 @@ public function get_token_value_length(): ?int {
 	 *         }
 	 *     }
 	 *     echo $processor->get_updated_css();
-	 *     // Outputs: background: url(new.jpg);
+	 *     // Outputs: background: url("new.jpg");
+	 *
+	 * @since {WP_VERSION}
 	 *
-	 * @param string $new_value The new URL value (should not include url() wrapper).
+	 * @param string $new_value New decoded URL or string value.
 	 * @return bool Whether the value was successfully updated.
 	 */
 	public function set_token_value( string $new_value ): bool {
 		// Only URL and string tokens are currently supported.
 		switch ( $this->token_type ) {
 			case self::TOKEN_URL:
-				$this->lexical_updates[] = array(
-					'start'  => $this->token_value_starts_at,
-					'length' => $this->token_value_length,
-					'text'   => WP_CSS_Builder::string( $new_value ),
+				$this->queue_lexical_update(
+					$this->token_value_starts_at,
+					$this->token_value_length,
+					WP_CSS_Builder::string( $new_value )
 				);
 				return true;
 			case self::TOKEN_STRING:
-				$this->lexical_updates[] = array(
-					'start'  => $this->token_starts_at,
-					'length' => $this->token_length,
-					'text'   => WP_CSS_Builder::string( $new_value ),
+				$this->queue_lexical_update(
+					$this->token_starts_at,
+					$this->token_length,
+					WP_CSS_Builder::string( $new_value )
 				);
 				return true;
 			default:
@@ -907,6 +947,29 @@ public function set_token_value( string $new_value ): bool {
 		}
 	}
 
+	/**
+	 * Queues a lexical update, replacing an earlier update for the same range.
+	 *
+	 * @since {WP_VERSION}
+	 *
+	 * @param int    $start  Byte offset at which to start the replacement.
+	 * @param int    $length Number of bytes to replace.
+	 * @param string $text   Replacement text.
+	 */
+	private function queue_lexical_update( int $start, int $length, string $text ): void {
+		foreach ( $this->lexical_updates as $index => $update ) {
+			if ( $update['start'] === $start && $update['length'] === $length ) {
+				unset( $this->lexical_updates[ $index ] );
+			}
+		}
+
+		$this->lexical_updates[] = array(
+			'start'  => $start,
+			'length' => $length,
+			'text'   => $text,
+		);
+	}
+
 	/**
 	 * Returns the CSS with all modifications applied.
 	 *
@@ -923,7 +986,9 @@ public function set_token_value( string $new_value ): bool {
 	 *         }
 	 *     }
 	 *     echo $processor->get_updated_css();
-	 *     // Outputs: background: url(new.jpg);
+	 *     // Outputs: background: url("new.jpg");
+	 *
+	 * @since {WP_VERSION}
 	 *
 	 * @return string The modified CSS.
 	 */
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 3df3a78b23760..ad403886a681b 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -2563,10 +2563,10 @@ public function test_escape_sequences_in_unusual_places() {
 	}
 
 	/**
-	 * Tests that set_token_value() only works on URL tokens.
+	 * Tests that set_token_value() only works on URL and string tokens.
 	 */
-	public function test_set_token_value_only_works_on_url_tokens(): void {
-		$css       = 'color: red; background: url(old.jpg);';
+	public function test_set_token_value_only_works_on_url_and_string_tokens(): void {
+		$css       = 'content: "old"; color: red; background: url(old.jpg);';
 		$processor = WP_CSS_Token_Processor::create( $css );
 
 		$this->setExpectedIncorrectUsage( 'WP_CSS_Token_Processor::set_token_value' );
@@ -2574,18 +2574,53 @@ public function test_set_token_value_only_works_on_url_tokens(): void {
 		while ( $processor->next_token() ) {
 			$token_type = $processor->get_token_type();
 
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $token_type ) {
-				// Should succeed on URL tokens.
+			if ( WP_CSS_Token_Processor::TOKEN_URL === $token_type || WP_CSS_Token_Processor::TOKEN_STRING === $token_type ) {
+				// Should succeed on URL and string tokens.
 				$this->assertTrue( $processor->set_token_value( 'new.jpg' ) );
 			} else {
-				// Should fail on non-URL tokens.
+				// Should fail on other token types.
 				$this->assertFalse( $processor->set_token_value( 'test' ) );
 			}
 		}
 
 		// Verify the update was applied.
 		$updated = $processor->get_updated_css();
-		$this->assertSame( 'color: red; background: url("new.jpg");', $updated );
+		$this->assertSame( 'content: "new.jpg"; color: red; background: url("new.jpg");', $updated );
+	}
+
+	/**
+	 * Tests that repeated updates to one token keep only the latest value.
+	 *
+	 * @ticket 62653
+	 *
+	 * @dataProvider data_repeated_token_value_updates
+	 */
+	public function test_set_token_value_supersedes_an_earlier_update_to_the_same_token( string $css, string $expected ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		while ( $processor->next_token() ) {
+			if (
+				WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ||
+				WP_CSS_Token_Processor::TOKEN_STRING === $processor->get_token_type()
+			) {
+				$this->assertTrue( $processor->set_token_value( 'first value' ) );
+				$this->assertTrue( $processor->set_token_value( 'final value' ) );
+			}
+		}
+
+		$this->assertSame( $expected, $processor->get_updated_css() );
+	}
+
+	/**
+	 * Data provider for repeated token value updates.
+	 *
+	 * @return array<string,array{string,string}>
+	 */
+	public static function data_repeated_token_value_updates(): array {
+		return array(
+			'URL token'    => array( 'background: url(old.jpg);', 'background: url("final value");' ),
+			'string token' => array( 'content: "old";', 'content: "final value";' ),
+		);
 	}
 
 	/**

From b2e6400cc781f309a2c834ed939147f3dbd51a85 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:10:15 +0400
Subject: [PATCH 04/77] Point CSS API tests at Trac #65738 and set @since 7.2.0

The corpus docblock now names @rmenke/css-tokenizer-tests, the package the test cases derive from.
---
 .../css-api/class-wp-css-builder.php          |  8 ++--
 .../css-api/class-wp-css-token-processor.php  | 38 +++++++++----------
 tests/phpunit/tests/css-api/wpCssBuilder.php  |  2 +-
 .../tests/css-api/wpCssTokenProcessor.php     | 22 +++++------
 4 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
index 1d2e27b06a901..76a8827d2f07e 100644
--- a/src/wp-includes/css-api/class-wp-css-builder.php
+++ b/src/wp-includes/css-api/class-wp-css-builder.php
@@ -4,13 +4,13 @@
  *
  * @package WordPress
  * @subpackage CSS-API
- * @since {WP_VERSION}
+ * @since 7.2.0
  */
 
 /**
  * Serializes decoded values for safe interpolation into CSS source.
  *
- * @since {WP_VERSION}
+ * @since 7.2.0
  */
 abstract class WP_CSS_Builder {
 	/**
@@ -24,7 +24,7 @@ abstract class WP_CSS_Builder {
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * An empty string serializes to an empty string. Callers that require an
 	 * ident token must reject an empty value.
@@ -112,7 +112,7 @@ public static function ident( string $value ): string {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $value Decoded string value to encode as a quoted CSS string.
 	 * @return string Serialized quoted CSS string text.
diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index abc5a9fd63ac8..5b0fd7d3bdcb2 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage CSS-API
- * @since {WP_VERSION}
+ * @since 7.2.0
  */
 
 /**
@@ -83,7 +83,7 @@
  *         }
  *     }
  *
- * @since {WP_VERSION}
+ * @since 7.2.0
  *
  * @see https://www.w3.org/TR/css-syntax-3/#tokenization
  */
@@ -319,7 +319,7 @@ class WP_CSS_Token_Processor {
 	 *
 	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $css         CSS source to tokenize.
 	 */
@@ -337,7 +337,7 @@ private function __construct( string $css ) {
 	 *
 	 * - The only supported document encoding is `UTF-8`, which is the default value.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $css      CSS source to tokenize.
 	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
@@ -358,7 +358,7 @@ public static function create( string $css, string $encoding = 'UTF-8' ) {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return bool Whether a token was found.
 	 */
@@ -637,7 +637,7 @@ public function next_token(): bool {
 	/**
 	 * Gets the current token type.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null
 	 * @phpstan-return self::TOKEN_*|null
@@ -657,7 +657,7 @@ public function get_token_type(): ?string {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null
 	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
@@ -677,7 +677,7 @@ public function get_token_type_flag(): ?string {
 	 * This is different from get_token_value() which returns the semantic value
 	 * (e.g., for strings: content without quotes; for numbers: numeric value).
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null
 	 */
@@ -699,7 +699,7 @@ public function get_normalized_token(): ?string {
 	 * Returns the exact bytes from the source without any normalization.
 	 * This preserves original line endings (\r\n, \r, \f) and null bytes.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null
 	 */
@@ -725,7 +725,7 @@ public function get_unnormalized_token(): ?string {
 	 * - For strings/URLs: the decoded string value
 	 * - For other tokens: null
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#token-value
 	 * @return string|null
@@ -819,7 +819,7 @@ public function get_token_value(): ?string {
 	 *
 	 * Only meaningful for URL and STRING tokens. Returns false for all other token types.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return bool Whether the current token value starts with "data:" (case-insensitive).
 	 */
@@ -845,7 +845,7 @@ public function is_data_uri(): bool {
 	/**
 	 * Gets the token start at.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return int|null
 	 */
@@ -856,7 +856,7 @@ public function get_token_start(): ?int {
 	/**
 	 * Gets the token length.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return int|null
 	 */
@@ -867,7 +867,7 @@ public function get_token_length(): ?int {
 	/**
 	 * Gets the unit for dimension tokens.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null
 	 */
@@ -878,7 +878,7 @@ public function get_token_unit(): ?string {
 	/**
 	 * Gets the byte at where the token value starts (for STRING and URL tokens).
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return int|null
 	 */
@@ -889,7 +889,7 @@ public function get_token_value_start(): ?int {
 	/**
 	 * Gets the byte length of the token value (for STRING and URL tokens).
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return int|null
 	 */
@@ -919,7 +919,7 @@ public function get_token_value_length(): ?int {
 	 *     echo $processor->get_updated_css();
 	 *     // Outputs: background: url("new.jpg");
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $new_value New decoded URL or string value.
 	 * @return bool Whether the value was successfully updated.
@@ -950,7 +950,7 @@ public function set_token_value( string $new_value ): bool {
 	/**
 	 * Queues a lexical update, replacing an earlier update for the same range.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param int    $start  Byte offset at which to start the replacement.
 	 * @param int    $length Number of bytes to replace.
@@ -988,7 +988,7 @@ private function queue_lexical_update( int $start, int $length, string $text ):
 	 *     echo $processor->get_updated_css();
 	 *     // Outputs: background: url("new.jpg");
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string The modified CSS.
 	 */
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssBuilder.php
index b3f0c52501414..265d8e327bb75 100644
--- a/tests/phpunit/tests/css-api/wpCssBuilder.php
+++ b/tests/phpunit/tests/css-api/wpCssBuilder.php
@@ -107,7 +107,7 @@ public function test_mixed_newlines(): void {
 	/**
 	 * Tests WP_CSS_Builder::ident() serializes CSS identifiers.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 *
 	 * @dataProvider data_ident
 	 *
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index ad403886a681b..75a06c6625352 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -18,9 +18,9 @@ public function test_processor_matches_spec( string $css, array $expected_tokens
 	}
 
 	/**
-	 * Provides the test cases from the @rmenke/css-processor-test test corpus.
+	 * Provides the test cases derived from the @rmenke/css-tokenizer-tests corpus (MIT).
 	 *
-	 * @see https://github.com/romainmenke/css-processor-tests/
+	 * @see https://github.com/romainmenke/css-tokenizer-tests/
 	 * @return array
 	 */
 	public static function corpus_provider(): array {
@@ -73,7 +73,7 @@ public static function collect_tokens( WP_CSS_Token_Processor $processor, $keys
 	/**
 	 * Tests that backslash-newline in a string token contributes nothing to the value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 * @dataProvider data_string_backslash_newline
 	 */
 	public function test_string_backslash_newline( string $css, string $expected_value ): void {
@@ -101,7 +101,7 @@ public static function data_string_backslash_newline(): array {
 	/**
 	 * Tests that backslash-EOF in a string token contributes nothing to the value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 */
 	public function test_string_backslash_eof(): void {
 		$processor = WP_CSS_Token_Processor::create( "'string\\" );
@@ -114,7 +114,7 @@ public function test_string_backslash_eof(): void {
 	/**
 	 * Tests that backslash-newline in an unquoted URL produces a bad-url token.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 * @dataProvider data_url_backslash_newline
 	 */
 	public function test_url_backslash_newline( string $css ): void {
@@ -141,7 +141,7 @@ public static function data_url_backslash_newline(): array {
 	/**
 	 * Tests that backslash-EOF in an unquoted URL produces U+FFFD in the value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 */
 	public function test_url_backslash_eof(): void {
 		$processor = WP_CSS_Token_Processor::create( 'url(string\\' );
@@ -154,7 +154,7 @@ public function test_url_backslash_eof(): void {
 	/**
 	 * Tests that backslash-newline stops an ident sequence.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 * @dataProvider data_ident_backslash_newline
 	 */
 	public function test_ident_backslash_newline( string $css ): void {
@@ -182,7 +182,7 @@ public static function data_ident_backslash_newline(): array {
 	/**
 	 * Tests that backslash-EOF in an ident produces U+FFFD in the value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 */
 	public function test_ident_backslash_eof(): void {
 		$processor = WP_CSS_Token_Processor::create( 'abc\\' );
@@ -195,7 +195,7 @@ public function test_ident_backslash_eof(): void {
 	/**
 	 * Bad string tokens have no associated value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 */
 	public function test_bad_string_token_value_is_null(): void {
 		$processor = WP_CSS_Token_Processor::create( "'str\ning'" );
@@ -208,7 +208,7 @@ public function test_bad_string_token_value_is_null(): void {
 	/**
 	 * Tests that hash tokens expose the proper type flag.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 * @dataProvider data_hash_tokens_expose_type_flags
 	 */
 	public function test_hash_tokens_expose_type_flags( string $css, array $expected_tokens ): void {
@@ -2591,7 +2591,7 @@ public function test_set_token_value_only_works_on_url_and_string_tokens(): void
 	/**
 	 * Tests that repeated updates to one token keep only the latest value.
 	 *
-	 * @ticket 62653
+	 * @ticket 65738
 	 *
 	 * @dataProvider data_repeated_token_value_updates
 	 */

From 6804231e0904f497c61aefa97ebfda7ccdc43480 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 18:47:05 +0400
Subject: [PATCH 05/77] Move string and ident serialization onto the token
 processor

---
 .../css-api/class-wp-css-builder.php          | 157 ------------------
 .../css-api/class-wp-css-token-processor.php  | 146 +++++++++++++++-
 src/wp-settings.php                           |   1 -
 ....php => wpCssTokenProcessor-serialize.php} |  28 ++--
 4 files changed, 158 insertions(+), 174 deletions(-)
 delete mode 100644 src/wp-includes/css-api/class-wp-css-builder.php
 rename tests/phpunit/tests/css-api/{wpCssBuilder.php => wpCssTokenProcessor-serialize.php} (86%)

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
deleted file mode 100644
index 76a8827d2f07e..0000000000000
--- a/src/wp-includes/css-api/class-wp-css-builder.php
+++ /dev/null
@@ -1,157 +0,0 @@
-<?php
-/**
- * CSS API: WP_CSS_Builder class
- *
- * @package WordPress
- * @subpackage CSS-API
- * @since 7.2.0
- */
-
-/**
- * Serializes decoded values for safe interpolation into CSS source.
- *
- * @since 7.2.0
- */
-abstract class WP_CSS_Builder {
-	/**
-	 * Serialize a plain PHP string as CSS identifier text.
-	 *
-	 * Characters not valid in CSS identifiers are hex-escaped. This uses
-	 * the same safety escaping as {@see WP_CSS_Builder::string()} for HTML
-	 * and CSS-sensitive characters, plus escaping of whitespace and other
-	 * characters not permitted in idents.
-	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
-	 *
-	 * @since 7.2.0
-	 *
-	 * An empty string serializes to an empty string. Callers that require an
-	 * ident token must reject an empty value.
-	 *
-	 * @param string $value Decoded string value to encode as a CSS identifier.
-	 * @return string Serialized CSS identifier text.
-	 */
-	public static function ident( string $value ): string {
-		$value  = wp_scrub_utf8( $value );
-		$result = '';
-		$length = strlen( $value );
-
-		for ( $i = 0; $i < $length; $i++ ) {
-			$byte = ord( $value[ $i ] );
-
-			// NULL → U+FFFD REPLACEMENT CHARACTER.
-			if ( 0x00 === $byte ) {
-				$result .= "\u{FFFD}";
-				continue;
-			}
-
-			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
-			if ( $byte >= 0x80 ) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// ASCII letters and underscore: always valid in idents.
-			if (
-				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
-				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
-				0x5F === $byte                         // _
-			) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// Hyphen: valid in idents, but check for hyphen-digit at start.
-			if ( 0x2D === $byte ) {
-				// A hyphen standing alone must be escaped to form an ident token.
-				if ( 0 === $i && 1 === $length ) {
-					$result .= '\\2D ';
-					continue;
-				}
-
-				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
-				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
-					$result .= '-';
-					++$i;
-					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
-					continue;
-				}
-				$result .= '-';
-				continue;
-			}
-
-			// Digits: valid except at position 0.
-			if ( $byte >= 0x30 && $byte <= 0x39 ) {
-				if ( 0 === $i ) {
-					$result .= sprintf( '\\%X ', $byte );
-				} else {
-					$result .= $value[ $i ];
-				}
-				continue;
-			}
-
-			// Everything else: hex-escape.
-			$result .= sprintf( '\\%X ', $byte );
-		}
-
-		return $result;
-	}
-
-	/**
-	 * Create a quoted CSS string from a plain PHP string value.
-	 *
-	 * Example:
-	 *     $value = 'CSS & a "<style>" tag\'s strings';
-	 *     $css_string = WP_CSS_Builder::string( $value );
-	 *     echo "<style>*::before { content: {$css_string}; }</style>";
-	 *
-	 * CSS strings are quoted, and many characters that are problematic in HTML
-	 * or may be complicated for rudimentary CSS or HTML processors to handle
-	 * are encoded using Unicode escape sequences.
-	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param string $value Decoded string value to encode as a quoted CSS string.
-	 * @return string Serialized quoted CSS string text.
-	 */
-	public static function string( string $value ): string {
-		$value   = wp_scrub_utf8( $value );
-		$escaped = strtr(
-			$value,
-			array(
-				// Escape existing backslashes to prevent unintentional escapes in result.
-				'\\'   => '\\5C ',
-
-				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
-				"\0"   => "\u{FFFD}",
-
-				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
-				"\r\n" => '\\A ',
-				"\r"   => '\\A ',
-				"\f"   => '\\A ',
-
-				// Newlines must be escaped in CSS strings.
-				"\n"   => '\\A ',
-
-				// Arbitrary characters for Unicode escaping:
-
-				// HTML syntax may be problematic.
-				'<'    => '\\3C ',
-				'>'    => '\\3E ',
-				'&'    => '\\26 ',
-
-				// CSS syntax may be problematic.
-				','    => '\\2C ',
-				';'    => '\\3B ',
-				'{'    => '\\7B ',
-				'}'    => '\\7D ',
-				'"'    => '\\22 ',
-				"'"    => '\\27 ',
-			)
-		);
-		return "\"{$escaped}\"";
-	}
-}
diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 5b0fd7d3bdcb2..08278e54237bf 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -897,6 +897,148 @@ public function get_token_value_length(): ?int {
 		return $this->token_value_length;
 	}
 
+	/**
+	 * Serializes a plain PHP string as CSS identifier text.
+	 *
+	 * Characters not valid in CSS identifiers are hex-escaped. This uses
+	 * the same safety escaping as {@see WP_CSS_Token_Processor::serialize_string()} for HTML
+	 * and CSS-sensitive characters, plus escaping of whitespace and other
+	 * characters not permitted in idents.
+	 *
+	 * An empty string serializes to an empty string. Callers that require an
+	 * ident token must reject an empty value.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded string value to encode as a CSS identifier.
+	 * @return string Serialized CSS identifier text.
+	 */
+	public static function serialize_ident( string $value ): string {
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			// NULL → U+FFFD REPLACEMENT CHARACTER.
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
+			if ( $byte >= 0x80 ) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// ASCII letters and underscore: always valid in idents.
+			if (
+				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
+				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
+				0x5F === $byte                         // _
+			) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// Hyphen: valid in idents, but check for hyphen-digit at start.
+			if ( 0x2D === $byte ) {
+				// A hyphen standing alone must be escaped to form an ident token.
+				if ( 0 === $i && 1 === $length ) {
+					$result .= '\\2D ';
+					continue;
+				}
+
+				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
+				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
+					$result .= '-';
+					++$i;
+					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
+					continue;
+				}
+				$result .= '-';
+				continue;
+			}
+
+			// Digits: valid except at position 0.
+			if ( $byte >= 0x30 && $byte <= 0x39 ) {
+				if ( 0 === $i ) {
+					$result .= sprintf( '\\%X ', $byte );
+				} else {
+					$result .= $value[ $i ];
+				}
+				continue;
+			}
+
+			// Everything else: hex-escape.
+			$result .= sprintf( '\\%X ', $byte );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Creates a quoted CSS string from a plain PHP string value.
+	 *
+	 * Example:
+	 *     $value = 'CSS & a "<style>" tag\'s strings';
+	 *     $css_string = WP_CSS_Token_Processor::serialize_string( $value );
+	 *     echo "<style>*::before { content: {$css_string}; }</style>";
+	 *
+	 * CSS strings are quoted, and many characters that are problematic in HTML
+	 * or may be complicated for rudimentary CSS or HTML processors to handle
+	 * are encoded using Unicode escape sequences.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded string value to encode as a quoted CSS string.
+	 * @return string Serialized quoted CSS string text.
+	 */
+	public static function serialize_string( string $value ): string {
+		$value   = wp_scrub_utf8( $value );
+		$escaped = strtr(
+			$value,
+			array(
+				// Escape existing backslashes to prevent unintentional escapes in result.
+				'\\'   => '\\5C ',
+
+				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
+				"\0"   => "\u{FFFD}",
+
+				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+				"\r\n" => '\\A ',
+				"\r"   => '\\A ',
+				"\f"   => '\\A ',
+
+				// Newlines must be escaped in CSS strings.
+				"\n"   => '\\A ',
+
+				// Arbitrary characters for Unicode escaping:
+
+				// HTML syntax may be problematic.
+				'<'    => '\\3C ',
+				'>'    => '\\3E ',
+				'&'    => '\\26 ',
+
+				// CSS syntax may be problematic.
+				','    => '\\2C ',
+				';'    => '\\3B ',
+				'{'    => '\\7B ',
+				'}'    => '\\7D ',
+				'"'    => '\\22 ',
+				"'"    => '\\27 ',
+			)
+		);
+		return "\"{$escaped}\"";
+	}
+
 	/**
 	 * Sets the value of the current URL or string token.
 	 *
@@ -931,14 +1073,14 @@ public function set_token_value( string $new_value ): bool {
 				$this->queue_lexical_update(
 					$this->token_value_starts_at,
 					$this->token_value_length,
-					WP_CSS_Builder::string( $new_value )
+					self::serialize_string( $new_value )
 				);
 				return true;
 			case self::TOKEN_STRING:
 				$this->queue_lexical_update(
 					$this->token_starts_at,
 					$this->token_length,
-					WP_CSS_Builder::string( $new_value )
+					self::serialize_string( $new_value )
 				);
 				return true;
 			default:
diff --git a/src/wp-settings.php b/src/wp-settings.php
index c811424dc25a2..670f5507d1a97 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -278,7 +278,6 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-stack-event.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
-require ABSPATH . WPINC . '/css-api/class-wp-css-builder.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php
similarity index 86%
rename from tests/phpunit/tests/css-api/wpCssBuilder.php
rename to tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php
index 265d8e327bb75..caabc0fc948ac 100644
--- a/tests/phpunit/tests/css-api/wpCssBuilder.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php
@@ -1,20 +1,20 @@
 <?php
 
 /**
- * Tests for the WP_CSS_Builder class.
+ * Tests for WP_CSS_Token_Processor string and identifier serialization.
  *
  * @group css-api
  *
- * @coversDefaultClass WP_CSS_Builder
+ * @coversDefaultClass WP_CSS_Token_Processor
  */
-class Tests_CssApi_WpCssBuilder extends WP_UnitTestCase {
+class Tests_CssApi_WpCssTokenProcessor_Serialize extends WP_UnitTestCase {
 	/**
 	 * @dataProvider data_string_escaping
 	 *
-	 * @covers ::string
+	 * @covers ::serialize_string
 	 */
 	public function test_string_escaping( string $input, string $expected ): void {
-		$this->assertSame( $expected, WP_CSS_Builder::string( $input ) );
+		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $input ) );
 
 		/**
 		 * Ensure that a single, equivalent CSS string is produced.
@@ -24,7 +24,7 @@ public function test_string_escaping( string $input, string $expected ): void {
 		 *
 		 * @see https://www.w3.org/TR/css-syntax-3/#input-preprocessing
 		 */
-		$processor = WP_CSS_Token_Processor::create( WP_CSS_Builder::string( $input ) );
+		$processor = WP_CSS_Token_Processor::create( WP_CSS_Token_Processor::serialize_string( $input ) );
 		$processor->next_token();
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
 		$expected_decoded_value = strtr(
@@ -83,38 +83,38 @@ public static function data_string_escaping(): array {
 	/**
 	 * Tests the example from the class docblock.
 	 *
-	 * @covers ::string
+	 * @covers ::serialize_string
 	 */
 	public function test_docblock_example(): void {
 		$value    = 'CSS & a "<style>" tag\'s strings';
 		$expected = '"CSS \26  a \22 \3C style\3E \22  tag\27 s strings"';
 
-		$this->assertSame( $expected, WP_CSS_Builder::string( $value ) );
+		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $value ) );
 	}
 
 	/**
 	 * Tests a string containing mixed newline types.
 	 *
-	 * @covers ::string
+	 * @covers ::serialize_string
 	 */
 	public function test_mixed_newlines(): void {
 		$input    = "line1\nline2\rline3\r\nline4\fline5";
 		$expected = '"line1\A line2\A line3\A line4\A line5"';
 
-		$this->assertSame( $expected, WP_CSS_Builder::string( $input ) );
+		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $input ) );
 	}
 
 	/**
-	 * Tests WP_CSS_Builder::ident() serializes CSS identifiers.
+	 * Tests WP_CSS_Token_Processor::serialize_ident() serializes CSS identifiers.
 	 *
 	 * @ticket 65738
 	 *
 	 * @dataProvider data_ident
 	 *
-	 * @covers ::ident
+	 * @covers ::serialize_ident
 	 */
 	public function test_ident( string $input, string $expected ): void {
-		$serialized = WP_CSS_Builder::ident( $input );
+		$serialized = WP_CSS_Token_Processor::serialize_ident( $input );
 		$this->assertSame( $expected, $serialized );
 
 		$processor = WP_CSS_Token_Processor::create( $serialized );
@@ -140,7 +140,7 @@ public function test_ident( string $input, string $expected ): void {
 	}
 
 	/**
-	 * Data provider for ident() tests.
+	 * Data provider for serialize_ident() tests.
 	 */
 	public static function data_ident(): Generator {
 		yield 'Empty identifier' => array( '', '' );

From c64ca4700478329d42bc825bc9fe2d50c1530103 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 18:47:50 +0400
Subject: [PATCH 06/77] Drop the token mutation API

---
 .../css-api/class-wp-css-token-processor.php  | 146 -----------
 .../tests/css-api/wpCssTokenProcessor.php     | 237 ------------------
 2 files changed, 383 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 08278e54237bf..86946d404bb53 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -56,18 +56,6 @@
  *     // Outputs:
  *     // width: 10px;
  *
- * Rewriting a URL while keeping the rest of the stylesheet intact:
- *
- *     $css = 'background: url(old.jpg) center / cover;';
- *     $processor = WP_CSS_Token_Processor::create( $css );
- *     while ( $processor->next_token() ) {
- *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
- *             $processor->set_value( 'uploads/new.jpg' );
- *         }
- *     }
- *     $result = $processor->get_updated_css();
- *     // background: url("uploads/new.jpg") center / cover;
- *
  * Gathering diagnostics with byte offsets:
  *
  *     $css = "color: red;\ncolor: re\nd;";
@@ -304,16 +292,6 @@ class WP_CSS_Token_Processor {
 	 */
 	private $token_unit = null;
 
-	/**
-	 * Lexical replacements to apply to input CSS document.
-	 *
-	 * Tracks modifications to be applied to the CSS, such as changing URL values.
-	 * Each entry is an associative array with 'start', 'length', and 'text' keys.
-	 *
-	 * @var array[]
-	 */
-	private $lexical_updates = array();
-
 	/**
 	 * Constructor for the CSS processor.
 	 *
@@ -1039,130 +1017,6 @@ public static function serialize_string( string $value ): string {
 		return "\"{$escaped}\"";
 	}
 
-	/**
-	 * Sets the value of the current URL or string token.
-	 *
-	 * The new decoded value is serialized as a quoted CSS string. For a URL
-	 * token, only the value inside `url()` is replaced, converting an unquoted
-	 * URL such as `url(old.jpg)` to `url("new.jpg")`.
-	 *
-	 * Repeated calls for the same current token supersede the previous update.
-	 * Attempting to set the value on another token type returns false.
-	 *
-	 * Example:
-	 *
-	 *     $css = 'background: url(old.jpg);';
-	 *     $processor = WP_CSS_Token_Processor::create( $css );
-	 *     while ( $processor->next_token() ) {
-	 *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-	 *             $processor->set_token_value( 'new.jpg' );
-	 *         }
-	 *     }
-	 *     echo $processor->get_updated_css();
-	 *     // Outputs: background: url("new.jpg");
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param string $new_value New decoded URL or string value.
-	 * @return bool Whether the value was successfully updated.
-	 */
-	public function set_token_value( string $new_value ): bool {
-		// Only URL and string tokens are currently supported.
-		switch ( $this->token_type ) {
-			case self::TOKEN_URL:
-				$this->queue_lexical_update(
-					$this->token_value_starts_at,
-					$this->token_value_length,
-					self::serialize_string( $new_value )
-				);
-				return true;
-			case self::TOKEN_STRING:
-				$this->queue_lexical_update(
-					$this->token_starts_at,
-					$this->token_length,
-					self::serialize_string( $new_value )
-				);
-				return true;
-			default:
-				_doing_it_wrong( __METHOD__, 'set_token_value() only supports URL and string tokens. Got token type: ' . $this->token_type, '1.0.0' );
-				return false;
-		}
-	}
-
-	/**
-	 * Queues a lexical update, replacing an earlier update for the same range.
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param int    $start  Byte offset at which to start the replacement.
-	 * @param int    $length Number of bytes to replace.
-	 * @param string $text   Replacement text.
-	 */
-	private function queue_lexical_update( int $start, int $length, string $text ): void {
-		foreach ( $this->lexical_updates as $index => $update ) {
-			if ( $update['start'] === $start && $update['length'] === $length ) {
-				unset( $this->lexical_updates[ $index ] );
-			}
-		}
-
-		$this->lexical_updates[] = array(
-			'start'  => $start,
-			'length' => $length,
-			'text'   => $text,
-		);
-	}
-
-	/**
-	 * Returns the CSS with all modifications applied.
-	 *
-	 * This method applies all queued lexical updates and returns the modified CSS.
-	 * If no modifications were made, returns the original CSS.
-	 *
-	 * Example:
-	 *
-	 *     $css = 'background: url(old.jpg);';
-	 *     $processor = WP_CSS_Token_Processor::create( $css );
-	 *     while ( $processor->next_token() ) {
-	 *         if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-	 *             $processor->set_token_value( 'new.jpg' );
-	 *         }
-	 *     }
-	 *     echo $processor->get_updated_css();
-	 *     // Outputs: background: url("new.jpg");
-	 *
-	 * @since 7.2.0
-	 *
-	 * @return string The modified CSS.
-	 */
-	public function get_updated_css(): string {
-		if ( empty( $this->lexical_updates ) ) {
-			return $this->css;
-		}
-
-		// Sort updates by start position in ascending order.
-		usort(
-			$this->lexical_updates,
-			function ( $a, $b ) {
-				return $a['start'] - $b['start'];
-			}
-		);
-
-		// Build the output by concatenating original CSS fragments with replacements.
-		$bytes_already_copied = 0;
-		$output               = '';
-
-		foreach ( $this->lexical_updates as $update ) {
-			$output              .= substr( $this->css, $bytes_already_copied, $update['start'] - $bytes_already_copied );
-			$output              .= $update['text'];
-			$bytes_already_copied = $update['start'] + $update['length'];
-		}
-
-		// Copy remaining CSS after last update.
-		$output .= substr( $this->css, $bytes_already_copied );
-
-		return $output;
-	}
-
 	/**
 	 * Clears token state between tokens.
 	 */
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 75a06c6625352..ada8e3d64d204 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -2562,243 +2562,6 @@ public function test_escape_sequences_in_unusual_places() {
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
-	/**
-	 * Tests that set_token_value() only works on URL and string tokens.
-	 */
-	public function test_set_token_value_only_works_on_url_and_string_tokens(): void {
-		$css       = 'content: "old"; color: red; background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		$this->setExpectedIncorrectUsage( 'WP_CSS_Token_Processor::set_token_value' );
-
-		while ( $processor->next_token() ) {
-			$token_type = $processor->get_token_type();
-
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $token_type || WP_CSS_Token_Processor::TOKEN_STRING === $token_type ) {
-				// Should succeed on URL and string tokens.
-				$this->assertTrue( $processor->set_token_value( 'new.jpg' ) );
-			} else {
-				// Should fail on other token types.
-				$this->assertFalse( $processor->set_token_value( 'test' ) );
-			}
-		}
-
-		// Verify the update was applied.
-		$updated = $processor->get_updated_css();
-		$this->assertSame( 'content: "new.jpg"; color: red; background: url("new.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that repeated updates to one token keep only the latest value.
-	 *
-	 * @ticket 65738
-	 *
-	 * @dataProvider data_repeated_token_value_updates
-	 */
-	public function test_set_token_value_supersedes_an_earlier_update_to_the_same_token( string $css, string $expected ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if (
-				WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ||
-				WP_CSS_Token_Processor::TOKEN_STRING === $processor->get_token_type()
-			) {
-				$this->assertTrue( $processor->set_token_value( 'first value' ) );
-				$this->assertTrue( $processor->set_token_value( 'final value' ) );
-			}
-		}
-
-		$this->assertSame( $expected, $processor->get_updated_css() );
-	}
-
-	/**
-	 * Data provider for repeated token value updates.
-	 *
-	 * @return array<string,array{string,string}>
-	 */
-	public static function data_repeated_token_value_updates(): array {
-		return array(
-			'URL token'    => array( 'background: url(old.jpg);', 'background: url("final value");' ),
-			'string token' => array( 'content: "old";', 'content: "final value";' ),
-		);
-	}
-
-	/**
-	 * Tests that set_token_value() properly escapes special characters in quoted URLs.
-	 */
-	public function test_set_token_value_escapes_special_characters(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				// URL with spaces, quotes, and parentheses.
-				$processor->set_token_value( 'path with spaces("special").jpg' );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		$this->assertSame( 'background: url("path with spaces(\\22 special\\22 ).jpg");', $updated );
-	}
-
-	/**
-	 * Tests that set_token_value() preserves Unicode characters in quoted URLs.
-	 */
-	public function test_set_token_value_encodes_unicode(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				// URL with Unicode characters: "测试.jpg" (Chinese characters).
-				$processor->set_token_value( '测试.jpg' );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		$this->assertSame( 'background: url("测试.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that set_token_value() preserves emoji in quoted URLs.
-	 */
-	public function test_set_token_value_handles_emoji(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				// URL with emoji: "image😀.jpg".
-				$processor->set_token_value( 'image😀.jpg' );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		$this->assertSame( 'background: url("image😀.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that multiple URL values can be updated in the same CSS.
-	 */
-	public function test_set_token_value_multiple_urls(): void {
-		$css       = 'background: url(old1.jpg); border-image: url(old2.png);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		$url_count = 0;
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				++$url_count;
-				if ( 1 === $url_count ) {
-					$processor->set_token_value( 'new1.jpg' );
-				} elseif ( 2 === $url_count ) {
-					$processor->set_token_value( 'new2.png' );
-				}
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		// Verify both URLs were updated.
-		$this->assertSame( 'background: url("new1.jpg"); border-image: url("new2.png");', $updated );
-	}
-
-	/**
-	 * Tests that newlines are properly escaped in quoted URLs.
-	 */
-	public function test_set_token_value_escapes_control_characters(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				// URL with newlines and carriage returns.
-				$processor->set_token_value( "path\nwith\rnewlines\ftest.jpg" );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		$this->assertSame( 'background: url("path\\A with\\A newlines\\A test.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that backslashes are properly escaped in quoted URLs.
-	 */
-	public function test_set_token_value_escapes_backslashes(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				$processor->set_token_value( 'path\\with\\backslashes.jpg' );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		// Verify backslashes are escaped as \\.
-		$this->assertSame( 'background: url("path\\5C with\\5C backslashes.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that get_updated_css() returns original CSS when no changes are made.
-	 */
-	public function test_get_updated_css_returns_original_when_unchanged(): void {
-		$css       = 'background: url(image.jpg); color: red;';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		// Iterate through tokens without making changes.
-		while ( $processor->next_token() ) {
-			// Do nothing.
-		}
-
-		$updated = $processor->get_updated_css();
-
-		// Should return original CSS.
-		$this->assertSame( $css, $updated );
-	}
-
-	/**
-	 * Tests that safe ASCII characters are preserved in quoted URLs.
-	 */
-	public function test_set_token_value_preserves_safe_characters(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				// URL with safe characters: letters, digits, hyphens, underscores, dots, slashes.
-				$processor->set_token_value( 'path/to/my-image_2024.jpg' );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		// Verify safe characters are preserved as-is in quoted URL.
-		$this->assertSame( 'background: url("path/to/my-image_2024.jpg");', $updated );
-	}
-
-	/**
-	 * Tests that invalid UTF-8 sequences are replaced in quoted URLs.
-	 */
-	public function test_set_token_with_invalid_utf8_sequence(): void {
-		$css       = 'background: url(old.jpg);';
-		$processor = WP_CSS_Token_Processor::create( $css );
-
-		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_URL === $processor->get_token_type() ) {
-				$processor->set_token_value( "\xC0.jpg" );
-			}
-		}
-
-		$updated = $processor->get_updated_css();
-
-		$this->assertSame( 'background: url("�.jpg");', $updated );
-	}
-
 	/**
 	 * Tests that decode_range() respects the token's length boundary.
 	 *

From 59eece40f41cef4895aeab2cd3578e815ab5bc5d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 18:48:38 +0400
Subject: [PATCH 07/77] Drop untested token value getters

---
 .../css-api/class-wp-css-token-processor.php  | 50 -------------------
 1 file changed, 50 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 86946d404bb53..8acc594593433 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -792,34 +792,6 @@ public function get_token_value(): ?string {
 		return $this->token_value;
 	}
 
-	/**
-	 * Determines whether the current token is a data URI.
-	 *
-	 * Only meaningful for URL and STRING tokens. Returns false for all other token types.
-	 *
-	 * @since 7.2.0
-	 *
-	 * @return bool Whether the current token value starts with "data:" (case-insensitive).
-	 */
-	public function is_data_uri(): bool {
-		if ( null === $this->token_value_starts_at || null === $this->token_value_length ) {
-			return false;
-		}
-
-		if ( $this->token_value_length < 5 ) {
-			return false;
-		}
-
-		$offset = $this->token_value_starts_at;
-		return (
-			( 'd' === $this->css[ $offset ] || 'D' === $this->css[ $offset ] ) &&
-			( 'a' === $this->css[ $offset + 1 ] || 'A' === $this->css[ $offset + 1 ] ) &&
-			( 't' === $this->css[ $offset + 2 ] || 'T' === $this->css[ $offset + 2 ] ) &&
-			( 'a' === $this->css[ $offset + 3 ] || 'A' === $this->css[ $offset + 3 ] ) &&
-			':' === $this->css[ $offset + 4 ]
-		);
-	}
-
 	/**
 	 * Gets the token start at.
 	 *
@@ -853,28 +825,6 @@ public function get_token_unit(): ?string {
 		return $this->token_unit;
 	}
 
-	/**
-	 * Gets the byte at where the token value starts (for STRING and URL tokens).
-	 *
-	 * @since 7.2.0
-	 *
-	 * @return int|null
-	 */
-	public function get_token_value_start(): ?int {
-		return $this->token_value_starts_at;
-	}
-
-	/**
-	 * Gets the byte length of the token value (for STRING and URL tokens).
-	 *
-	 * @since 7.2.0
-	 *
-	 * @return int|null
-	 */
-	public function get_token_value_length(): ?int {
-		return $this->token_value_length;
-	}
-
 	/**
 	 * Serializes a plain PHP string as CSS identifier text.
 	 *

From 52576f1249fd74e1b8ca7355337cbd00af27d99b Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 18:48:38 +0400
Subject: [PATCH 08/77] Document corpus provenance

---
 tests/phpunit/data/css-api/LICENSE   | 21 +++++++++++++
 tests/phpunit/data/css-api/README.md | 44 ++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 tests/phpunit/data/css-api/LICENSE
 create mode 100644 tests/phpunit/data/css-api/README.md

diff --git a/tests/phpunit/data/css-api/LICENSE b/tests/phpunit/data/css-api/LICENSE
new file mode 100644
index 0000000000000..13b1ea364b27e
--- /dev/null
+++ b/tests/phpunit/data/css-api/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Romain Menke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/tests/phpunit/data/css-api/README.md b/tests/phpunit/data/css-api/README.md
new file mode 100644
index 0000000000000..5b17c602b72c4
--- /dev/null
+++ b/tests/phpunit/data/css-api/README.md
@@ -0,0 +1,44 @@
+# CSS tokenizer test corpus
+
+This directory contains a third-party test corpus used for testing the WordPress CSS API tokenizer.
+
+`css-test-cases.json` derives from the npm package
+[`@rmenke/css-tokenizer-tests`](https://www.npmjs.com/package/@rmenke/css-tokenizer-tests)
+by Romain Menke, MIT licensed (see `LICENSE`). The package source is on GitHub at
+[romainmenke/css-tokenizer-tests](https://github.com/romainmenke/css-tokenizer-tests).
+
+The 185 cases match version 1.3.0 of the package, whose test content is identical to
+version 1.2.0. Version 1.4.0 adds 102 cases that are not in this file.
+
+## Transform
+
+The upstream corpus maps a case name to `{ css, tokens }`. Each upstream token has
+`type`, `raw`, `startIndex`, `endIndex` and `structured`. This file keeps the case names,
+`css`, `type` and `raw` unchanged and transforms the rest:
+
+- `startIndex` and `endIndex` are byte offsets into the UTF-8 source. Upstream uses
+  JavaScript string indexes (UTF-16 code units).
+- `value` is `structured.value` flattened onto the token. Numeric values are the
+  number's source text as a string (`"10e2"`, not `1000`); for dimension and
+  percentage tokens the unit or `%` is removed. Tokens without structured data have
+  `value: null`.
+- `unit` is `structured.unit`, present on dimension tokens only.
+- `numberType` is `structured.type` on number and dimension tokens. The upstream
+  `structured.type` of hash tokens (`id` or `unrestricted`) and `signCharacter` are
+  not kept.
+- `normalized` is WordPress's expectation for `WP_CSS_Token_Processor::get_normalized_token()`:
+  the token text after input preprocessing and escape decoding. Upstream has no such
+  field.
+
+Three cases carry WordPress's token expectations where the upstream package contradicts
+CSS Syntax Level 3: `tests/ident/0007` (`-§`), `tests/ident/0008` (`-×`) and
+`tests/fuzz/b69ece36-057f-4450-9423-a1661787bce6`. In each, a non-ASCII code point or
+U+0000 (which preprocessing replaces with U+FFFD) is an ident code point, so the
+hyphen or identifier before it continues as one ident token. Upstream splits them into
+delim tokens.
+
+## Updating
+
+There is no conversion script. To update, take `testCorpus` from the package's
+`index.cjs`, apply the transform above, set `normalized` for each token per the
+specification, and update the version noted in this README.

From a9d4b5d47cac4f04da1e7cd2e5ee4fe0419512a4 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 23:12:58 +0400
Subject: [PATCH 09/77] Report whether a token ended at its delimiter

---
 .../css-api/class-wp-css-token-processor.php  | 57 +++++++++++++-
 .../tests/css-api/wpCssTokenProcessor.php     | 76 +++++++++++++++++++
 2 files changed, 131 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 8acc594593433..425f8a1ec63e3 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -292,6 +292,17 @@ class WP_CSS_Token_Processor {
 	 */
 	private $token_unit = null;
 
+	/**
+	 * Whether the current token ended at its closing delimiter.
+	 *
+	 * Comment, string, url and bad-url tokens end at `*\/`, the matching quote
+	 * or `)`. When the input ends first, the token is complete but this flag
+	 * is false. Every other token type is always terminated.
+	 *
+	 * @var bool
+	 */
+	private $token_is_terminated = true;
+
 	/**
 	 * Constructor for the CSS processor.
 	 *
@@ -363,8 +374,14 @@ public function next_token(): bool {
 			$this->token_starts_at       = $this->at;
 			$this->token_value_starts_at = $this->at;
 
-			$end                      = strpos( $this->css, '*/', $this->at + 2 );
-			$this->at                 = false !== $end ? $end + 2 : $this->length;
+			$end = strpos( $this->css, '*/', $this->at + 2 );
+			if ( false === $end ) {
+				// The comment runs to the end of the input.
+				$this->token_is_terminated = false;
+				$this->at                  = $this->length;
+			} else {
+				$this->at = $end + 2;
+			}
 			$this->token_length       = $this->at - $this->token_starts_at;
 			$this->token_value_length = $this->token_length - 4;
 			return true;
@@ -825,6 +842,34 @@ public function get_token_unit(): ?string {
 		return $this->token_unit;
 	}
 
+	/**
+	 * Reports whether the current token ended at its closing delimiter.
+	 *
+	 * Comment, string, url and bad-url tokens have a closing delimiter: `*\/`,
+	 * the matching quote, or `)`. When the input ends before the delimiter,
+	 * the tokenizer still returns the token, and this method returns false.
+	 * It returns true for every other token type, which have no closing
+	 * delimiter, and false before the first call to next_token().
+	 *
+	 * Example:
+	 *
+	 *     $processor = WP_CSS_Token_Processor::create( '"abc' );
+	 *     $processor->next_token();
+	 *     $processor->get_token_type();      // 'string-token'
+	 *     $processor->is_token_terminated(); // false
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-comment
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return bool Whether the current token ended at its closing delimiter.
+	 */
+	public function is_token_terminated(): bool {
+		return null !== $this->token_type && $this->token_is_terminated;
+	}
+
 	/**
 	 * Serializes a plain PHP string as CSS identifier text.
 	 *
@@ -977,6 +1022,7 @@ private function after_token(): void {
 		$this->token_length          = null;
 		$this->token_value           = false;
 		$this->token_unit            = null;
+		$this->token_is_terminated   = true;
 		$this->token_value_starts_at = null;
 		$this->token_value_length    = null;
 	}
@@ -1084,6 +1130,7 @@ private function consume_string(): bool {
 		// EOF
 		// This is a parse error. Return the <string-token>.
 		$this->token_type            = self::TOKEN_STRING;
+		$this->token_is_terminated   = false;
 		$this->token_length          = $this->at - $this->token_starts_at;
 		$this->token_value_starts_at = $value_starts_at;
 		$this->token_value_length    = $this->at - $value_starts_at;
@@ -1321,6 +1368,7 @@ private function consume_url(): bool {
 				if ( $this->at >= $this->length ) {
 					// EOF is a parse error, but we return the <url-token> anyway.
 					$this->token_type            = self::TOKEN_URL;
+					$this->token_is_terminated   = false;
 					$this->token_length          = $this->at - $this->token_starts_at;
 					$this->token_value_starts_at = $value_starts_at;
 					$this->token_value_length    = $value_ends_at - $value_starts_at;
@@ -1398,6 +1446,7 @@ private function consume_url(): bool {
 		// EOF
 		// This is a parse error. Return the <url-token>.
 		$this->token_type            = self::TOKEN_URL;
+		$this->token_is_terminated   = false;
 		$this->token_length          = $this->at - $this->token_starts_at;
 		$this->token_value_starts_at = $value_starts_at;
 		$this->token_value_length    = $this->at - $value_starts_at;
@@ -1415,6 +1464,9 @@ private function consume_url(): bool {
 	 * @return bool
 	 */
 	private function consume_remnants_of_bad_url(): bool {
+		// Set to true when a `)` ends the token.
+		$this->token_is_terminated = false;
+
 		while ( $this->at < $this->length ) {
 			$this->at += strcspn( $this->css, ')\\', $this->at );
 
@@ -1431,6 +1483,7 @@ private function consume_remnants_of_bad_url(): bool {
 				}
 			} elseif ( ')' === $this->css[ $this->at ] ) {
 				++$this->at;
+				$this->token_is_terminated = true;
 				break;
 			}
 		}
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index ada8e3d64d204..5ca0f94d7ae51 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -205,6 +205,82 @@ public function test_bad_string_token_value_is_null(): void {
 		$this->assertNull( $processor->get_token_value() );
 	}
 
+	/**
+	 * Tests that is_token_terminated() reports whether the last token ended at its closing delimiter.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_is_token_terminated
+	 */
+	public function test_is_token_terminated( string $css, string $expected_type, bool $expected ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertFalse( $processor->is_token_terminated(), 'Before the first token there is nothing to report.' );
+
+		$type = null;
+		while ( $processor->next_token() ) {
+			$type       = $processor->get_token_type();
+			$terminated = $processor->is_token_terminated();
+		}
+
+		$this->assertSame( $expected_type, $type, 'The last token type did not match.' );
+		$this->assertSame( $expected, $terminated, 'The last token termination flag did not match.' );
+	}
+
+	/**
+	 * Data provider for test_is_token_terminated().
+	 *
+	 * @return array[]
+	 */
+	public static function data_is_token_terminated(): array {
+		return array(
+			'comment terminated'                 => array( '/* a */', WP_CSS_Token_Processor::TOKEN_COMMENT, true ),
+			'comment empty terminated'           => array( '/**/', WP_CSS_Token_Processor::TOKEN_COMMENT, true ),
+			'comment unterminated'               => array( '/* a', WP_CSS_Token_Processor::TOKEN_COMMENT, false ),
+			'comment "/*/" unterminated'         => array( '/*/', WP_CSS_Token_Processor::TOKEN_COMMENT, false ),
+			'comment terminated at end of input' => array( 'a /**/', WP_CSS_Token_Processor::TOKEN_COMMENT, true ),
+			'string terminated'                  => array( '"a"', WP_CSS_Token_Processor::TOKEN_STRING, true ),
+			'string escaped backslash'           => array( '"a\\\\"', WP_CSS_Token_Processor::TOKEN_STRING, true ),
+			'string unterminated'                => array( '"a', WP_CSS_Token_Processor::TOKEN_STRING, false ),
+			'string escape consumed the quote'   => array( '"a\\"', WP_CSS_Token_Processor::TOKEN_STRING, false ),
+			'string lone quote'                  => array( '"', WP_CSS_Token_Processor::TOKEN_STRING, false ),
+			'string single quoted terminated'    => array( "a 'b'", WP_CSS_Token_Processor::TOKEN_STRING, true ),
+			'string single quoted unterminated'  => array( "a 'b", WP_CSS_Token_Processor::TOKEN_STRING, false ),
+			'url terminated'                     => array( 'url(a)', WP_CSS_Token_Processor::TOKEN_URL, true ),
+			'url escaped backslash'              => array( 'url(a\\\\)', WP_CSS_Token_Processor::TOKEN_URL, true ),
+			'url unterminated'                   => array( 'url(a', WP_CSS_Token_Processor::TOKEN_URL, false ),
+			'url escape consumed the paren'      => array( 'url(a\\)', WP_CSS_Token_Processor::TOKEN_URL, false ),
+			'url trailing whitespace'            => array( 'url(a ', WP_CSS_Token_Processor::TOKEN_URL, false ),
+			'url whitespace then paren'          => array( 'url(a )', WP_CSS_Token_Processor::TOKEN_URL, true ),
+			'url empty unterminated'             => array( 'url(', WP_CSS_Token_Processor::TOKEN_URL, false ),
+			'bad url terminated'                 => array( 'url(a b)', WP_CSS_Token_Processor::TOKEN_BAD_URL, true ),
+			'bad url unterminated'               => array( 'url(a b', WP_CSS_Token_Processor::TOKEN_BAD_URL, false ),
+			'ident at end of input'              => array( 'color: red', WP_CSS_Token_Processor::TOKEN_IDENT, true ),
+			'ident backslash at end of input'    => array( 'abc\\', WP_CSS_Token_Processor::TOKEN_IDENT, true ),
+			'function at end of input'           => array( 'calc(', WP_CSS_Token_Processor::TOKEN_FUNCTION, true ),
+		);
+	}
+
+	/**
+	 * Tests that is_token_terminated() is reset for the token after an unterminated one.
+	 *
+	 * @ticket 65738
+	 */
+	public function test_is_token_terminated_resets_between_tokens(): void {
+		$processor = WP_CSS_Token_Processor::create( "'a\nb" );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
+		$this->assertTrue( $processor->is_token_terminated() );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_WHITESPACE, $processor->get_token_type() );
+		$this->assertTrue( $processor->is_token_terminated() );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
+		$this->assertTrue( $processor->is_token_terminated() );
+	}
+
 	/**
 	 * Tests that hash tokens expose the proper type flag.
 	 *

From 051e8f57c5014fbf45234481cb36ca59da2a5546 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:21:28 +0400
Subject: [PATCH 10/77] Accept NUL in an unquoted url

CSS preprocessing replaces NUL with U+FFFD before tokenization, so an unquoted url() containing NUL is a url-token, not a bad-url-token. The source byte stays in the token for offsets; the value decodes it.

Ported from WordPress/php-toolkit bb1c7069 with its CSSPreprocessingTest cases.
---
 .../css-api/class-wp-css-token-processor.php  |  9 +++-
 .../tests/css-api/wpCssTokenProcessor.php     | 51 +++++++++++++++++++
 2 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 425f8a1ec63e3..04e28c1b8f9fd 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -31,6 +31,9 @@
  * This processor delays normalization as much as possible. That keeps the raw byte
  * positions intact for accurate rewrites while still letting consumers ask for a
  * normalized token when they need one.
+ * For example, url(a<NUL>b) is a URL token whose value is a�b, where <NUL>
+ * means one zero byte in the source. That byte stays in the raw token, so later
+ * edits still use byte offsets from the original input.
  *
  * ### No EOF token
  *
@@ -1395,8 +1398,10 @@ private function consume_url(): bool {
 				"'" === $this->css[ $this->at ] ||
 				'(' === $this->css[ $this->at ] ||
 
-				// Non-printable code point.
-				$byte <= 0x08 ||
+				// NUL becomes U+FFFD during CSS preprocessing, so it is valid here.
+				// Keep its source byte for offsets; decode_range() replaces it when
+				// the caller reads the value. Other non-printable controls stay invalid.
+				( $byte >= 0x01 && $byte <= 0x08 ) ||
 
 				// Line Tabulation.
 				0x0B === $byte ||
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 5ca0f94d7ae51..09e0444427a72 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -151,6 +151,57 @@ public function test_url_backslash_eof(): void {
 		$this->assertSame( "string\u{FFFD}", $processor->get_token_value() );
 	}
 
+	/**
+	 * Tests that preprocessing replaces NUL in the token value and keeps the source bytes.
+	 *
+	 * NUL becomes U+FFFD before tokenization, so it is valid inside an unquoted
+	 * URL. Other control bytes still produce a bad-url token.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_preprocessed_token_keeps_source_bytes
+	 */
+	public function test_preprocessed_token_keeps_source_bytes( string $css, string $expected_type, ?string $expected_value ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( $expected_type, $processor->get_token_type() );
+		$this->assertSame( $expected_value, $processor->get_token_value() );
+		$this->assertSame( $css, $processor->get_unnormalized_token() );
+		$this->assertSame( 0, $processor->get_token_start() );
+		$this->assertSame( strlen( $css ), $processor->get_token_length() );
+		$this->assertFalse( $processor->next_token() );
+	}
+
+	/**
+	 * Data provider for test_preprocessed_token_keeps_source_bytes().
+	 *
+	 * @return Generator
+	 */
+	public static function data_preprocessed_token_keeps_source_bytes(): Generator {
+		yield 'NUL as the URL' => array( "url(\x00)", WP_CSS_Token_Processor::TOKEN_URL, "\u{FFFD}" );
+		yield 'NUL before text' => array( "url(\x00a)", WP_CSS_Token_Processor::TOKEN_URL, "\u{FFFD}a" );
+		yield 'NUL inside text' => array( "url(a\x00b)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}b" );
+		yield 'NUL before closing parenthesis' => array( "url(a\x00)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}" );
+		yield 'NUL before EOF' => array( "url(a\x00", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}" );
+		yield 'consecutive NUL bytes' => array( "url(a\x00\x00b)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}\u{FFFD}b" );
+		yield 'escaped literal NUL' => array( "url(a\\\x00b)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}b" );
+		yield 'zero escape' => array( 'url(a\0 b)', WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}b" );
+		yield 'zero escape followed by CRLF' => array( "url(a\\0\r\nb)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}b" );
+		yield 'NUL followed by trailing CRLF' => array( "url(a\x00\r\n)", WP_CSS_Token_Processor::TOKEN_URL, "a\u{FFFD}" );
+		yield 'NUL in a string' => array( "\"a\x00b\"", WP_CSS_Token_Processor::TOKEN_STRING, "a\u{FFFD}b" );
+		yield 'NUL in a name' => array( "a\x00b", WP_CSS_Token_Processor::TOKEN_IDENT, "a\u{FFFD}b" );
+		yield 'NUL after trailing whitespace' => array( "url(a \x00)", WP_CSS_Token_Processor::TOKEN_BAD_URL, null );
+		yield 'NUL after a forbidden control' => array( "url(a\x01\x00b)", WP_CSS_Token_Processor::TOKEN_BAD_URL, null );
+
+		foreach ( array( "\t", "\n", "\r", "\f", "\r\n" ) as $whitespace ) {
+			yield 'internal whitespace ' . bin2hex( $whitespace ) => array( "url(a{$whitespace}b)", WP_CSS_Token_Processor::TOKEN_BAD_URL, null );
+		}
+
+		foreach ( array_merge( range( 0x01, 0x08 ), array( 0x0B ), range( 0x0E, 0x1F ), array( 0x7F ) ) as $byte ) {
+			yield 'forbidden control ' . dechex( $byte ) => array( 'url(a' . chr( $byte ) . 'b)', WP_CSS_Token_Processor::TOKEN_BAD_URL, null );
+		}
+	}
+
 	/**
 	 * Tests that backslash-newline stops an ident sequence.
 	 *

From 27f45f18e48c8a4dd7399efc0ca923b50b1b71b7 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:21:54 +0400
Subject: [PATCH 11/77] Scan plain ASCII runs in idents and urls with strspn

Ident sequences and unquoted url values advance over runs of bytes that need no special handling with one strspn() call instead of one PHP loop iteration per byte. Tokenizing 2,000 copies of a three-declaration style string (url, dimension, custom property) drops from 54 ms to 14 ms.

Ported from WordPress/php-toolkit 8e411e7c.
---
 .../css-api/class-wp-css-token-processor.php  | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 04e28c1b8f9fd..0221c4dacf69e 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -1347,6 +1347,18 @@ private function consume_url(): bool {
 
 		// Repeatedly consume the next input code point from the stream.
 		while ( $this->at < $this->length ) {
+			// Scan runs such as https://example.com/photo.png in native code rather
+			// than one PHP iteration per byte. These ASCII bytes need no special
+			// handling in an unquoted URL. Quotes, parentheses, whitespace, escapes,
+			// and non-ASCII bytes fall through to the rules below.
+			// Only the cursor advances; source bytes stay unchanged.
+			// This set only selects the fast path; it does not validate the URL or
+			// reject other bytes, which still reach the CSS token rules below.
+			$plain = strspn( $this->css, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-._~:/?#[]@!$&*+,;=%', $this->at );
+			if ( $plain > 0 ) {
+				$this->at += $plain;
+				continue;
+			}
 			// U+0029 RIGHT PARENTHESIS ())
 			// Return the <url-token>.
 			if ( ')' === $this->css[ $this->at ] ) {
@@ -1511,6 +1523,17 @@ private function consume_remnants_of_bad_url(): bool {
 	 */
 	private function consume_ident_sequence() {
 		while ( $this->at < $this->length ) {
+			// Scan ASCII name characters, as in margin-top or item_2, in native
+			// code rather than one PHP iteration per byte. Letters, digits, "-",
+			// and "_" can continue a name; deciding whether an identifier may
+			// start here is a separate check, not the purpose of this byte list.
+			// Non-ASCII bytes, NULL, and escapes use the rules below. Advancing
+			// only the cursor preserves the source spelling for later decoding.
+			$plain = strspn( $this->css, 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_', $this->at );
+			if ( $plain > 0 ) {
+				$this->at += $plain;
+				continue;
+			}
 			$codepoint_bytes = $this->consume_ident_codepoint( $this->at );
 			if ( $codepoint_bytes > 0 ) {
 				$this->at += $codepoint_bytes;

From dabd8c5e2b91a1b078620eabc87ec6f04371b44d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:22:59 +0400
Subject: [PATCH 12/77] Decode token text with a static method

decode_range() and its escape helpers take the CSS source as an argument, so code that holds the source and a token's offsets can decode the token after the cursor has moved on.
---
 .../css-api/class-wp-css-token-processor.php  | 122 ++++++++++--------
 1 file changed, 68 insertions(+), 54 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 0221c4dacf69e..ee0ae8ff21158 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -434,7 +434,7 @@ public function next_token(): bool {
 				if (
 					$this->consume_ident_codepoint( $this->at + 1 ) > 0 ||
 					// The next two input code points are a valid escape.
-					$this->is_valid_escape( $this->at + 1 )
+					self::is_valid_escape( $this->css, $this->at + 1 )
 				) {
 					// Create a <hash-token>.
 					++$this->at;
@@ -684,7 +684,8 @@ public function get_normalized_token(): ?string {
 			return null;
 		}
 
-		return $this->decode_range(
+		return self::decode_range(
+			$this->css,
 			$this->token_starts_at,
 			$this->token_length,
 			self::TOKEN_STRING === $this->token_type
@@ -737,22 +738,22 @@ public function get_token_value(): ?string {
 			switch ( $this->token_type ) {
 				case self::TOKEN_HASH:
 					// Hash value starts after the # character.
-					$this->token_value = $this->decode_range( $this->token_starts_at + 1, $this->token_length - 1 );
+					$this->token_value = self::decode_range( $this->css, $this->token_starts_at + 1, $this->token_length - 1 );
 					break;
 
 				case self::TOKEN_AT_KEYWORD:
 					// At-keyword value starts after the @ character.
-					$this->token_value = $this->decode_range( $this->token_starts_at + 1, $this->token_length - 1 );
+					$this->token_value = self::decode_range( $this->css, $this->token_starts_at + 1, $this->token_length - 1 );
 					break;
 
 				case self::TOKEN_FUNCTION:
 					// Function name is everything except the final (.
-					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length - 1 );
+					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length - 1 );
 					break;
 
 				case self::TOKEN_IDENT:
 					// Identifier is the entire token.
-					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length );
+					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length );
 					break;
 
 				case self::TOKEN_BAD_STRING:
@@ -761,7 +762,8 @@ public function get_token_value(): ?string {
 
 				case self::TOKEN_STRING:
 					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
-						$this->token_value = $this->decode_range(
+						$this->token_value = self::decode_range(
+							$this->css,
 							$this->token_value_starts_at,
 							$this->token_value_length,
 							true
@@ -774,7 +776,8 @@ public function get_token_value(): ?string {
 				case self::TOKEN_URL:
 					// Decode and cache the URL value.
 					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
-						$this->token_value = $this->decode_range(
+						$this->token_value = self::decode_range(
+							$this->css,
 							$this->token_value_starts_at,
 							$this->token_value_length
 						);
@@ -785,7 +788,7 @@ public function get_token_value(): ?string {
 
 				case self::TOKEN_DELIM:
 					// Delim value is the single code point.
-					$this->token_value = $this->decode_range( $this->token_starts_at, $this->token_length );
+					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length );
 					break;
 
 				case self::TOKEN_NUMBER:
@@ -1120,7 +1123,7 @@ private function consume_string(): bool {
 
 					// Otherwise, (the stream starts with a valid escape) consume an escaped
 					// code point (just to advance position, don't store the result).
-					$this->decode_escape_at( $this->at, $matched_bytes );
+					self::decode_escape_at( $this->css, $this->at, $matched_bytes );
 					$this->at += $matched_bytes;
 					continue 2;
 
@@ -1235,7 +1238,7 @@ private function consume_numeric(): bool {
 			// Consume an ident sequence. Set the <dimension-token>'s unit to the returned value.
 			$unit_starts_at = $this->at;
 			$this->consume_ident_sequence();
-			$this->token_unit      = $this->decode_range( $unit_starts_at, $this->at - $unit_starts_at );
+			$this->token_unit      = self::decode_range( $this->css, $unit_starts_at, $this->at - $unit_starts_at );
 			$this->token_type      = self::TOKEN_DIMENSION;
 			$this->token_type_flag = $number_type;
 			$this->token_length    = $this->at - $this->token_starts_at;
@@ -1273,7 +1276,7 @@ private function consume_ident_like(): bool {
 		// Consume an ident sequence, and let string be the result.
 		$ident_start = $this->at;
 		$decoded     = $this->consume_ident_sequence();
-		$string      = $decoded ?? $this->decode_range( $ident_start, $this->at - $ident_start );
+		$string      = $decoded ?? self::decode_range( $this->css, $ident_start, $this->at - $ident_start );
 
 		// If string's value is an ASCII case-insensitive match for "url",
 		// and the next input code point is U+0028 LEFT PARENTHESIS (().
@@ -1432,9 +1435,9 @@ private function consume_url(): bool {
 			// U+005C REVERSE SOLIDUS (\)
 			// If the stream starts with a valid escape, consume an escaped code point.
 			if ( '\\' === $this->css[ $this->at ] ) {
-				if ( $this->is_valid_escape( $this->at ) ) {
+				if ( self::is_valid_escape( $this->css, $this->at ) ) {
 					++$this->at;
-					$this->decode_escape_at( $this->at, $matched_bytes );
+					self::decode_escape_at( $this->css, $this->at, $matched_bytes );
 					$this->at += $matched_bytes;
 					continue;
 				}
@@ -1493,8 +1496,8 @@ private function consume_remnants_of_bad_url(): bool {
 
 			if ( '\\' === $this->css[ $this->at ] ) {
 				++$this->at;
-				if ( $this->is_valid_escape( $this->at - 1 ) ) {
-					$this->decode_escape_at( $this->at, $matched_bytes );
+				if ( self::is_valid_escape( $this->css, $this->at - 1 ) ) {
+					self::decode_escape_at( $this->css, $this->at, $matched_bytes );
 					$this->at += $matched_bytes;
 					continue;
 				}
@@ -1540,10 +1543,10 @@ private function consume_ident_sequence() {
 				continue;
 			}
 
-			if ( $this->is_valid_escape( $this->at ) ) {
+			if ( self::is_valid_escape( $this->css, $this->at ) ) {
 				++$this->at;
 
-				$this->decode_escape_at( $this->at, $matched_bytes );
+				self::decode_escape_at( $this->css, $this->at, $matched_bytes );
 				$this->at += $matched_bytes;
 				continue;
 			}
@@ -1625,15 +1628,21 @@ private function consume_ident_start_codepoint( $at ): int {
 	/**
 	 * Decodes and normalizes ident-like or string CSS values from a byte range.
 	 *
-	 * @param int  $start          Start byte offset.
-	 * @param int  $length         Length of the substring to decode.
-	 * @param bool $string_escapes Optional, default false. When true, apply additional escape
-	 *                             rules that apply only to string tokens.
+	 * The cursor and WP_CSS_Token both decode with this method.
+	 *
+	 * @since 7.2.0
+	 * @access private
+	 *
+	 * @param string $css            CSS source the offsets index.
+	 * @param int    $start          Start byte offset.
+	 * @param int    $length         Length of the substring to decode.
+	 * @param bool   $string_escapes Optional, default false. When true, apply additional escape
+	 *                               rules that apply only to string tokens.
 	 * @return string Decoded and normalized string.
 	 */
-	private function decode_range( int $start, int $length, bool $string_escapes = false ): string {
+	public static function decode_range( string $css, int $start, int $length, bool $string_escapes = false ): string {
 		// Fast path: check if any processing is needed.
-		$slice         = wp_scrub_utf8( substr( $this->css, $start, $length ) );
+		$slice         = wp_scrub_utf8( substr( $css, $start, $length ) );
 		$special_chars = "\\\r\f\x00";
 		if ( false === strpbrk( $slice, $special_chars ) ) {
 			// No special chars - return raw substring (almost zero allocations).
@@ -1647,9 +1656,9 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 
 		while ( $at < $end ) {
 			// Find next special character within the token boundary.
-			$normal_len = strcspn( $this->css, $special_chars, $at, $end - $at );
+			$normal_len = strcspn( $css, $special_chars, $at, $end - $at );
 			if ( $normal_len > 0 ) {
-				$decoded .= wp_scrub_utf8( substr( $this->css, $at, $normal_len ) );
+				$decoded .= wp_scrub_utf8( substr( $css, $at, $normal_len ) );
 				$at      += $normal_len;
 			}
 
@@ -1657,7 +1666,7 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 				break;
 			}
 
-			$char = $this->css[ $at ];
+			$char = $css[ $at ];
 
 			// Handle escapes (if enabled).
 			if ( '\\' === $char ) {
@@ -1668,7 +1677,7 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 						continue;
 					}
 
-					$next = $this->css[ $at + 1 ];
+					$next = $css[ $at + 1 ];
 					if ( "\n" === $next || "\f" === $next ) {
 						// Backslash followed by LF or FF is a string line continuation.
 						$at += 2;
@@ -1678,16 +1687,16 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 					if ( "\r" === $next ) {
 						// Backslash followed by CR or CRLF is a string line continuation.
 						$at += 2;
-						if ( $at < $end && "\n" === $this->css[ $at ] ) {
+						if ( $at < $end && "\n" === $css[ $at ] ) {
 							++$at;
 						}
 						continue;
 					}
 				}
 
-				if ( $this->is_valid_escape( $at ) ) {
+				if ( self::is_valid_escape( $css, $at ) ) {
 					++$at;
-					$decoded .= $this->decode_escape_at( $at, $bytes_consumed );
+					$decoded .= self::decode_escape_at( $css, $at, $bytes_consumed );
 					$at      += $bytes_consumed;
 					continue;
 				}
@@ -1702,7 +1711,7 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 				$decoded .= "\n";
 				++$at;
 				// Handle \r\n as single newline.
-				if ( $at < $end && "\n" === $this->css[ $at ] ) {
+				if ( $at < $end && "\n" === $css[ $at ] ) {
 					++$at;
 				}
 				continue;
@@ -1726,8 +1735,7 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 	}
 
 	/**
-	 * Decodes an escape sequence starting at the given offset without
-	 * modifying $this->at.
+	 * Decodes an escape sequence starting at the given offset.
 	 *
 	 * Escape sequences are backslash followed by 1-6 hex digits (with optional
 	 * trailing whitespace) or any other character. Invalid code points are
@@ -1735,38 +1743,41 @@ private function decode_range( int $start, int $length, bool $string_escapes = f
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
 	 *
-	 * @param int $offset Byte offset (should point to the character after the backslash).
-	 * @param int &$bytes_consumed Output parameter: number of bytes consumed.
+	 * @param string $css             CSS source.
+	 * @param int    $offset          Byte offset (should point to the character after the backslash).
+	 * @param int    &$bytes_consumed Output parameter: number of bytes consumed.
 	 * @return string The decoded character(s).
 	 */
-	private function decode_escape_at( int $offset, &$bytes_consumed ): string {
+	private static function decode_escape_at( string $css, int $offset, &$bytes_consumed ): string {
+		$css_length = strlen( $css );
+
 		// This method assumes the U+005C REVERSE SOLIDUS (\) has already been consumed
 		// and the next input code point has already been verified to be part of a valid
 		// escape sequence.
 		$at = $offset;
 
 		// EOF.
-		if ( $at >= $this->length ) {
+		if ( $at >= $css_length ) {
 			// This is a parse error. Return U+FFFD REPLACEMENT CHARACTER (�).
 			$bytes_consumed = 0;
 			return "\u{FFFD}";
 		}
 
 		// Hex digits (CSS spec allows at most 6).
-		$hex_len = strspn( $this->css, '0123456789ABCDEFabcdef', $at, 6 );
+		$hex_len = strspn( $css, '0123456789ABCDEFabcdef', $at, 6 );
 		if ( $hex_len > 0 ) {
-			$hex = substr( $this->css, $at, $hex_len );
+			$hex = substr( $css, $at, $hex_len );
 			$at += $hex_len;
 
 			// If the next input code point is whitespace, consume it as well.
-			if ( $at < $this->length ) {
-				$next = $this->css[ $at ];
+			if ( $at < $css_length ) {
+				$next = $css[ $at ];
 				if ( "\t" === $next || "\n" === $next || "\f" === $next || ' ' === $next ) {
 					++$at;
 				} elseif ( "\r" === $next ) {
 					++$at;
 					// Handle \r\n as a single whitespace – the preprocessing phase would replace \r\n with \n.
-					if ( $at < $this->length && "\n" === $this->css[ $at ] ) {
+					if ( $at < $css_length && "\n" === $css[ $at ] ) {
 						++$at;
 					}
 				}
@@ -1789,21 +1800,21 @@ private function decode_escape_at( int $offset, &$bytes_consumed ): string {
 		// Anything else.
 		// Return the current input code point.
 		// Null bytes are replaced with U+FFFD during preprocessing.
-		if ( "\x00" === $this->css[ $at ] ) {
+		if ( "\x00" === $css[ $at ] ) {
 			$bytes_consumed = 1;
 			return "\u{FFFD}";
 		}
 
 		$new_at         = $at;
 		$invalid_length = 0;
-		if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
+		if ( 1 !== _wp_scan_utf8( $css, $new_at, $invalid_length, null, 1 ) ) {
 			// Consume the invalid subpart and return U+FFFD.
 			$bytes_consumed = $invalid_length;
 			return "\u{FFFD}";
 		}
 
 		$bytes_consumed = $new_at - $at;
-		return substr( $this->css, $at, $bytes_consumed );
+		return substr( $css, $at, $bytes_consumed );
 	}
 
 	/**
@@ -1813,16 +1824,19 @@ private function decode_escape_at( int $offset, &$bytes_consumed ): string {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
 	 *
-	 * @param int $offset Byte offset.
+	 * @param string $css    CSS source.
+	 * @param int    $offset Byte offset.
 	 * @return bool
 	 */
-	private function is_valid_escape( int $offset ): bool {
+	private static function is_valid_escape( string $css, int $offset ): bool {
+		$css_length = strlen( $css );
+
 		// If the first code point is not U+005C REVERSE SOLIDUS (\), return false.
-		if ( $offset >= $this->length || '\\' !== $this->css[ $offset ] ) {
+		if ( $offset >= $css_length || '\\' !== $css[ $offset ] ) {
 			return false;
 		}
 		// Otherwise, if the second code point is a newline, return false.
-		if ( $offset + 1 >= $this->length ) {
+		if ( $offset + 1 >= $css_length ) {
 			// Second code point is EOF - this is a valid escape per spec (weird!)
 			// Are we sure we're interpreting the spec correctly?
 			return true;
@@ -1830,13 +1844,13 @@ private function is_valid_escape( int $offset ): bool {
 
 		// Otherwise, if the second code point is not a newline, return true.
 		return (
-			"\n" !== $this->css[ $offset + 1 ] &&
+			"\n" !== $css[ $offset + 1 ] &&
 
 			// Form feed is normalized to newline during preprocessing.
-			"\f" !== $this->css[ $offset + 1 ] &&
+			"\f" !== $css[ $offset + 1 ] &&
 
 			// Carriage return is normalized to newline during preprocessing.
-			"\r" !== $this->css[ $offset + 1 ]
+			"\r" !== $css[ $offset + 1 ]
 
 			// We don't need to check for \r\n separately here. The \r check alone covers
 			// that scenario.
@@ -1922,7 +1936,7 @@ private function check_if_3_code_points_start_an_ident_sequence( int $offset ):
 			++$offset;
 		}
 
-		return $this->consume_ident_start_codepoint( $offset ) > 0 || $this->is_valid_escape( $offset );
+		return $this->consume_ident_start_codepoint( $offset ) > 0 || self::is_valid_escape( $this->css, $offset );
 	}
 
 	/**

From 2dcba339b4a7e06d40e0c9da994210abbd579dea Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:24:50 +0400
Subject: [PATCH 13/77] Add WP_CSS_Token and
 WP_CSS_Token_Processor::get_token()

get_token() returns the current token as an object that keeps its values after the processor moves on: type, flag, value, unit, start, length, and whether it ended at its closing delimiter. The value is decoded from the source on the first call to get_value(). The processor stays a cursor; get_token_value() reads the same object, so the value decoding is in one place.
---
 .../css-api/class-wp-css-token-processor.php  | 160 +++-------
 .../css-api/class-wp-css-token.php            | 302 ++++++++++++++++++
 src/wp-settings.php                           |   1 +
 tests/phpunit/tests/css-api/wpCssToken.php    | 189 +++++++++++
 4 files changed, 545 insertions(+), 107 deletions(-)
 create mode 100644 src/wp-includes/css-api/class-wp-css-token.php
 create mode 100644 tests/phpunit/tests/css-api/wpCssToken.php

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index ee0ae8ff21158..6b5cc4f7f6e52 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -276,17 +276,11 @@ class WP_CSS_Token_Processor {
 	private $token_value_length = null;
 
 	/**
-	 * A cache for the decoded and normalized token value.
+	 * The current token, created on the first call to get_token().
 	 *
-	 * - `false` indicates that the value has not been computed.
-	 * - `null` is used for token types without an associated value: whitespace,
-	 *   bad-url, comment, punctuation, etc.
-	 * - `string` is used for token types with an associated value: ident, string,
-	 *   function, url, etc.
-	 *
-	 * @var string|null|false
+	 * @var WP_CSS_Token|null
 	 */
-	private $token_value = false;
+	private $token = null;
 
 	/**
 	 * The unit of the current token, e.g. "px", "em", "deg", etc.
@@ -632,6 +626,49 @@ public function next_token(): bool {
 		return true;
 	}
 
+	/**
+	 * Gets the current token.
+	 *
+	 * The token keeps its values after the processor moves on, so callers can
+	 * collect tokens and read them later. Calls for the same token return the
+	 * same object.
+	 *
+	 * Example:
+	 *
+	 *     $processor = WP_CSS_Token_Processor::create( 'a "b"' );
+	 *     $tokens    = array();
+	 *     while ( $processor->next_token() ) {
+	 *         $tokens[] = $processor->get_token();
+	 *     }
+	 *     $tokens[2]->get_value(); // 'b'
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return WP_CSS_Token|null The current token, or null before the first
+	 *                           token and after the last.
+	 */
+	public function get_token(): ?WP_CSS_Token {
+		if ( null === $this->token_type ) {
+			return null;
+		}
+
+		if ( null === $this->token ) {
+			$this->token = new WP_CSS_Token(
+				$this->css,
+				$this->token_type,
+				$this->token_starts_at,
+				$this->token_length,
+				$this->token_type_flag,
+				$this->token_unit,
+				$this->token_value_starts_at,
+				$this->token_value_length,
+				$this->token_is_terminated
+			);
+		}
+
+		return $this->token;
+	}
+
 	/**
 	 * Gets the current token type.
 	 *
@@ -730,89 +767,8 @@ public function get_unnormalized_token(): ?string {
 	 * @return string|null
 	 */
 	public function get_token_value(): ?string {
-		if ( false === $this->token_value ) {
-			if ( null === $this->token_starts_at || null === $this->token_length ) {
-				return null;
-			}
-
-			switch ( $this->token_type ) {
-				case self::TOKEN_HASH:
-					// Hash value starts after the # character.
-					$this->token_value = self::decode_range( $this->css, $this->token_starts_at + 1, $this->token_length - 1 );
-					break;
-
-				case self::TOKEN_AT_KEYWORD:
-					// At-keyword value starts after the @ character.
-					$this->token_value = self::decode_range( $this->css, $this->token_starts_at + 1, $this->token_length - 1 );
-					break;
-
-				case self::TOKEN_FUNCTION:
-					// Function name is everything except the final (.
-					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length - 1 );
-					break;
-
-				case self::TOKEN_IDENT:
-					// Identifier is the entire token.
-					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length );
-					break;
-
-				case self::TOKEN_BAD_STRING:
-					$this->token_value = null;
-					break;
-
-				case self::TOKEN_STRING:
-					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
-						$this->token_value = self::decode_range(
-							$this->css,
-							$this->token_value_starts_at,
-							$this->token_value_length,
-							true
-						);
-					} else {
-						$this->token_value = null;
-					}
-					break;
-
-				case self::TOKEN_URL:
-					// Decode and cache the URL value.
-					if ( null !== $this->token_value_starts_at && null !== $this->token_value_length ) {
-						$this->token_value = self::decode_range(
-							$this->css,
-							$this->token_value_starts_at,
-							$this->token_value_length
-						);
-					} else {
-						$this->token_value = null;
-					}
-					break;
-
-				case self::TOKEN_DELIM:
-					// Delim value is the single code point.
-					$this->token_value = self::decode_range( $this->css, $this->token_starts_at, $this->token_length );
-					break;
-
-				case self::TOKEN_NUMBER:
-					// Return the string representation of the number (not parsed to float).
-					$this->token_value = substr( $this->css, $this->token_starts_at, $this->token_length );
-					break;
-
-				case self::TOKEN_PERCENTAGE:
-					// Return the string representation of the number (without the %).
-					$this->token_value = substr( $this->css, $this->token_starts_at, $this->token_length - 1 );
-					break;
-
-				case self::TOKEN_DIMENSION:
-					// Return the string representation of the number (without the unit).
-					$this->token_value = substr( $this->get_normalized_token(), 0, -strlen( $this->token_unit ) );
-					break;
-
-				default:
-					$this->token_value = null;
-					break;
-			}
-		}
-
-		return $this->token_value;
+		$token = $this->get_token();
+		return null === $token ? null : $token->get_value();
 	}
 
 	/**
@@ -1026,7 +982,7 @@ private function after_token(): void {
 		$this->token_type_flag       = null;
 		$this->token_starts_at       = null;
 		$this->token_length          = null;
-		$this->token_value           = false;
+		$this->token                 = null;
 		$this->token_unit            = null;
 		$this->token_is_terminated   = true;
 		$this->token_value_starts_at = null;
@@ -1275,8 +1231,8 @@ private function consume_numeric(): bool {
 	private function consume_ident_like(): bool {
 		// Consume an ident sequence, and let string be the result.
 		$ident_start = $this->at;
-		$decoded     = $this->consume_ident_sequence();
-		$string      = $decoded ?? self::decode_range( $this->css, $ident_start, $this->at - $ident_start );
+		$this->consume_ident_sequence();
+		$string = self::decode_range( $this->css, $ident_start, $this->at - $ident_start );
 
 		// If string's value is an ASCII case-insensitive match for "url",
 		// and the next input code point is U+0028 LEFT PARENTHESIS (().
@@ -1294,9 +1250,6 @@ private function consume_ident_like(): bool {
 				$next = $this->css[ $this->at + $ws_len ];
 				if ( '"' === $next || "'" === $next ) {
 					// then create a <function-token> with its value set to string and return it.
-					if ( null !== $decoded ) {
-						$this->token_value = $decoded;
-					}
 					$this->token_type   = self::TOKEN_FUNCTION;
 					$this->token_length = $this->at - $this->token_starts_at;
 					return true;
@@ -1313,18 +1266,12 @@ private function consume_ident_like(): bool {
 			// Consume it.
 			++$this->at;
 			// Create a <function-token> with its value set to string and return it.
-			if ( null !== $decoded ) {
-				$this->token_value = $decoded;
-			}
 			$this->token_type   = self::TOKEN_FUNCTION;
 			$this->token_length = $this->at - $this->token_starts_at;
 			return true;
 		}
 
 		// Otherwise, create an <ident-token> with its value set to string and return it.
-		if ( null !== $decoded ) {
-			$this->token_value = $decoded;
-		}
 		$this->token_type   = self::TOKEN_IDENT;
 		$this->token_length = $this->at - $this->token_starts_at;
 		return true;
@@ -1519,12 +1466,11 @@ private function consume_remnants_of_bad_url(): bool {
 	 * Identifiers can contain letters, digits, hyphens, underscores, non-ASCII
 	 * characters, and escape sequences. Null bytes are replaced with U+FFFD.
 	 *
-	 * Returns the decoded identifier string if escapes were encountered,
-	 * or null if no decoding was needed (can use raw substring).
+	 * Advances the cursor past the sequence; the caller decodes the bytes.
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-name
 	 */
-	private function consume_ident_sequence() {
+	private function consume_ident_sequence(): void {
 		while ( $this->at < $this->length ) {
 			// Scan ASCII name characters, as in margin-top or item_2, in native
 			// code rather than one PHP iteration per byte. Letters, digits, "-",
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
new file mode 100644
index 0000000000000..42a1f105ceb25
--- /dev/null
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -0,0 +1,302 @@
+<?php
+/**
+ * CSS API: WP_CSS_Token class
+ *
+ * @package WordPress
+ * @subpackage CSS-API
+ * @since 7.2.0
+ */
+
+/**
+ * A token read by WP_CSS_Token_Processor.
+ *
+ * A token keeps its values after the processor moves to the next token, so
+ * callers can collect tokens and read them later. The value is decoded from
+ * the CSS source on the first call to get_value().
+ *
+ * Example:
+ *
+ *     $processor = WP_CSS_Token_Processor::create( 'font-family: "Exo\20 2"' );
+ *     $tokens    = array();
+ *     while ( $processor->next_token() ) {
+ *         $tokens[] = $processor->get_token();
+ *     }
+ *     $tokens[3]->get_type();  // 'string-token'
+ *     $tokens[3]->get_value(); // 'Exo 2'
+ *
+ * @since 7.2.0
+ *
+ * @see WP_CSS_Token_Processor::get_token()
+ */
+final class WP_CSS_Token {
+	/**
+	 * CSS source the offsets index.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string
+	 */
+	private $css;
+
+	/**
+	 * Token type.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string
+	 * @phpstan-var WP_CSS_Token_Processor::TOKEN_*
+	 */
+	private $type;
+
+	/**
+	 * Byte offset at which the token starts.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var int
+	 */
+	private $start;
+
+	/**
+	 * Byte length of the token.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var int
+	 */
+	private $length;
+
+	/**
+	 * Type flag of a hash, number or dimension token.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string|null
+	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
+	 */
+	private $flag;
+
+	/**
+	 * Decoded unit of a dimension token.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string|null
+	 */
+	private $unit;
+
+	/**
+	 * Byte offset at which the value of a string or url token starts.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var int|null
+	 */
+	private $value_start;
+
+	/**
+	 * Byte length of the value of a string or url token.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var int|null
+	 */
+	private $value_length;
+
+	/**
+	 * Whether the token ended at its closing delimiter.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var bool
+	 */
+	private $is_terminated;
+
+	/**
+	 * Decoded value, or false before the first call to get_value().
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string|null|false
+	 */
+	private $value = false;
+
+	/**
+	 * Constructor.
+	 *
+	 * Use WP_CSS_Token_Processor::get_token() to create tokens.
+	 *
+	 * @since 7.2.0
+	 * @access private
+	 *
+	 * @param string      $css           CSS source the offsets index.
+	 * @param string      $type          Token type, one of the WP_CSS_Token_Processor::TOKEN_* constants.
+	 * @param int         $start         Byte offset at which the token starts.
+	 * @param int         $length        Byte length of the token.
+	 * @param string|null $flag          Type flag of a hash, number or dimension token.
+	 * @param string|null $unit          Decoded unit of a dimension token.
+	 * @param int|null    $value_start   Byte offset at which the value of a string or url token starts.
+	 * @param int|null    $value_length  Byte length of the value of a string or url token.
+	 * @param bool        $is_terminated Whether the token ended at its closing delimiter.
+	 */
+	public function __construct(
+		string $css,
+		string $type,
+		int $start,
+		int $length,
+		?string $flag,
+		?string $unit,
+		?int $value_start,
+		?int $value_length,
+		bool $is_terminated
+	) {
+		$this->css           = $css;
+		$this->type          = $type;
+		$this->start         = $start;
+		$this->length        = $length;
+		$this->flag          = $flag;
+		$this->unit          = $unit;
+		$this->value_start   = $value_start;
+		$this->value_length  = $value_length;
+		$this->is_terminated = $is_terminated;
+	}
+
+	/**
+	 * Gets the token type.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return string One of the WP_CSS_Token_Processor::TOKEN_* constants.
+	 * @phpstan-return WP_CSS_Token_Processor::TOKEN_*
+	 */
+	public function get_type(): string {
+		return $this->type;
+	}
+
+	/**
+	 * Gets the type flag.
+	 *
+	 * Hash tokens have an "id" or "unrestricted" flag. Number and dimension
+	 * tokens have an "integer" or "number" flag. Other tokens have none.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @see WP_CSS_Token_Processor::get_token_type_flag()
+	 *
+	 * @return string|null The type flag, or null.
+	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
+	 */
+	public function get_flag(): ?string {
+		return $this->flag;
+	}
+
+	/**
+	 * Gets the decoded value.
+	 *
+	 * The value is decoded on the first call and kept for later calls.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @see WP_CSS_Token_Processor::get_token_value()
+	 *
+	 * @return string|null The decoded value, or null for token types without a value.
+	 */
+	public function get_value(): ?string {
+		if ( false === $this->value ) {
+			$this->value = $this->decode_value();
+		}
+
+		return $this->value;
+	}
+
+	/**
+	 * Gets the decoded unit of a dimension token.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return string|null The unit, or null for other token types.
+	 */
+	public function get_unit(): ?string {
+		return $this->unit;
+	}
+
+	/**
+	 * Gets the byte offset at which the token starts in the CSS source.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return int Byte offset.
+	 */
+	public function get_start(): int {
+		return $this->start;
+	}
+
+	/**
+	 * Gets the byte length of the token in the CSS source.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return int Byte length.
+	 */
+	public function get_length(): int {
+		return $this->length;
+	}
+
+	/**
+	 * Reports whether the token ended at its closing delimiter.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @see WP_CSS_Token_Processor::is_token_terminated()
+	 *
+	 * @return bool Whether the token ended at its closing delimiter.
+	 */
+	public function is_terminated(): bool {
+		return $this->is_terminated;
+	}
+
+	/**
+	 * Decodes the value from the CSS source.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return string|null The decoded value, or null for token types without a value.
+	 */
+	private function decode_value(): ?string {
+		switch ( $this->type ) {
+			case WP_CSS_Token_Processor::TOKEN_HASH:
+			case WP_CSS_Token_Processor::TOKEN_AT_KEYWORD:
+				// The value starts after the `#` or `@`.
+				return WP_CSS_Token_Processor::decode_range( $this->css, $this->start + 1, $this->length - 1 );
+
+			case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+				// The value ends before the `(`.
+				return WP_CSS_Token_Processor::decode_range( $this->css, $this->start, $this->length - 1 );
+
+			case WP_CSS_Token_Processor::TOKEN_IDENT:
+			case WP_CSS_Token_Processor::TOKEN_DELIM:
+				return WP_CSS_Token_Processor::decode_range( $this->css, $this->start, $this->length );
+
+			case WP_CSS_Token_Processor::TOKEN_STRING:
+				return WP_CSS_Token_Processor::decode_range( $this->css, $this->value_start, $this->value_length, true );
+
+			case WP_CSS_Token_Processor::TOKEN_URL:
+				return WP_CSS_Token_Processor::decode_range( $this->css, $this->value_start, $this->value_length );
+
+			case WP_CSS_Token_Processor::TOKEN_NUMBER:
+				// Numbers are ASCII and have no escapes.
+				return substr( $this->css, $this->start, $this->length );
+
+			case WP_CSS_Token_Processor::TOKEN_PERCENTAGE:
+				// The value ends before the `%`.
+				return substr( $this->css, $this->start, $this->length - 1 );
+
+			case WP_CSS_Token_Processor::TOKEN_DIMENSION:
+				// The value ends before the unit.
+				return substr( WP_CSS_Token_Processor::decode_range( $this->css, $this->start, $this->length ), 0, -strlen( $this->unit ) );
+
+			default:
+				return null;
+		}
+	}
+}
diff --git a/src/wp-settings.php b/src/wp-settings.php
index 670f5507d1a97..ddf98c1437406 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -278,6 +278,7 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-stack-event.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor-state.php';
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
+require ABSPATH . WPINC . '/css-api/class-wp-css-token.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
diff --git a/tests/phpunit/tests/css-api/wpCssToken.php b/tests/phpunit/tests/css-api/wpCssToken.php
new file mode 100644
index 0000000000000..bcc59dd2cfad7
--- /dev/null
+++ b/tests/phpunit/tests/css-api/wpCssToken.php
@@ -0,0 +1,189 @@
+<?php
+
+/**
+ * Tests for WP_CSS_Token and WP_CSS_Token_Processor::get_token().
+ *
+ * @group css-api
+ *
+ * @coversDefaultClass WP_CSS_Token
+ */
+class Tests_CssApi_WpCssToken extends WP_UnitTestCase {
+	/**
+	 * Tests that tokens read with get_token() match the corpus.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_corpus
+	 *
+	 * @covers WP_CSS_Token_Processor::get_token
+	 */
+	public function test_get_token_matches_spec( string $css, array $expected_tokens ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$tokens    = array();
+		while ( $processor->next_token() ) {
+			$tokens[] = $processor->get_token();
+		}
+
+		$actual_tokens = array();
+		foreach ( $tokens as $token ) {
+			$actual_token = array(
+				'type'       => $token->get_type(),
+				'startIndex' => $token->get_start(),
+				'endIndex'   => $token->get_start() + $token->get_length(),
+				'value'      => $token->get_value(),
+			);
+			if ( null !== $token->get_unit() ) {
+				$actual_token['unit'] = $token->get_unit();
+			}
+			if (
+				WP_CSS_Token_Processor::TOKEN_NUMBER === $token->get_type() ||
+				WP_CSS_Token_Processor::TOKEN_DIMENSION === $token->get_type()
+			) {
+				$actual_token['numberType'] = $token->get_flag();
+			}
+			$actual_tokens[] = $actual_token;
+		}
+
+		$expected_tokens = array_map(
+			static function ( array $token ): array {
+				unset( $token['raw'], $token['normalized'] );
+				return $token;
+			},
+			$expected_tokens
+		);
+
+		$this->assertSame( $expected_tokens, $actual_tokens );
+	}
+
+	/**
+	 * Data provider for test_get_token_matches_spec().
+	 *
+	 * @return array[]
+	 */
+	public static function data_corpus(): array {
+		return json_decode( file_get_contents( DIR_TESTDATA . '/css-api/css-test-cases.json' ), true );
+	}
+
+	/**
+	 * Tests that get_token() returns null when the processor has no current token.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers WP_CSS_Token_Processor::get_token
+	 */
+	public function test_get_token_returns_null_without_a_current_token(): void {
+		$processor = WP_CSS_Token_Processor::create( 'a' );
+		$this->assertNull( $processor->get_token(), 'There is no token before next_token().' );
+
+		$this->assertTrue( $processor->next_token() );
+		$this->assertInstanceOf( WP_CSS_Token::class, $processor->get_token() );
+
+		$this->assertFalse( $processor->next_token() );
+		$this->assertNull( $processor->get_token(), 'There is no token after the last one.' );
+	}
+
+	/**
+	 * Tests that a token decodes its value after the processor has moved on.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value
+	 */
+	public function test_value_decodes_after_the_processor_moves_on(): void {
+		$processor = WP_CSS_Token_Processor::create( '\\66 oo "b\\61 r" url(b\\61 z) #\\31 a 1\\70 x' );
+		$tokens    = array();
+		while ( $processor->next_token() ) {
+			$tokens[] = $processor->get_token();
+		}
+
+		$values = array();
+		foreach ( $tokens as $token ) {
+			$values[] = array( $token->get_type(), $token->get_value() );
+		}
+
+		$this->assertSame(
+			array(
+				array( WP_CSS_Token_Processor::TOKEN_IDENT, 'foo' ),
+				array( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null ),
+				array( WP_CSS_Token_Processor::TOKEN_STRING, 'bar' ),
+				array( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null ),
+				array( WP_CSS_Token_Processor::TOKEN_URL, 'baz' ),
+				array( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null ),
+				array( WP_CSS_Token_Processor::TOKEN_HASH, '1a' ),
+				array( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null ),
+				array( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1' ),
+			),
+			$values
+		);
+		$this->assertSame( 'px', $tokens[8]->get_unit() );
+	}
+
+	/**
+	 * Tests that a token reports the type flag of the token it was read from.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_flag
+	 *
+	 * @covers ::get_flag
+	 */
+	public function test_flag( string $css, string $expected_type, ?string $expected_flag ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$this->assertTrue( $processor->next_token() );
+
+		$token = $processor->get_token();
+		$this->assertSame( $expected_type, $token->get_type() );
+		$this->assertSame( $expected_flag, $token->get_flag() );
+	}
+
+	/**
+	 * Data provider for test_flag().
+	 *
+	 * @return array[]
+	 */
+	public static function data_flag(): array {
+		return array(
+			'hash id'            => array( '#a1', WP_CSS_Token_Processor::TOKEN_HASH, WP_CSS_Token_Processor::HASH_TOKEN_ID ),
+			'hash escaped digit' => array( '#\\31 a', WP_CSS_Token_Processor::TOKEN_HASH, WP_CSS_Token_Processor::HASH_TOKEN_ID ),
+			'hash unrestricted'  => array( '#1a', WP_CSS_Token_Processor::TOKEN_HASH, WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED ),
+			'integer'            => array( '12', WP_CSS_Token_Processor::TOKEN_NUMBER, 'integer' ),
+			'number'             => array( '1.5', WP_CSS_Token_Processor::TOKEN_NUMBER, 'number' ),
+			'integer dimension'  => array( '1px', WP_CSS_Token_Processor::TOKEN_DIMENSION, 'integer' ),
+			'number dimension'   => array( '1e2px', WP_CSS_Token_Processor::TOKEN_DIMENSION, 'number' ),
+			'percentage'         => array( '50%', WP_CSS_Token_Processor::TOKEN_PERCENTAGE, null ),
+			'ident'              => array( 'a', WP_CSS_Token_Processor::TOKEN_IDENT, null ),
+		);
+	}
+
+	/**
+	 * Tests that a token reports whether it ended at its closing delimiter.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_is_terminated
+	 *
+	 * @covers ::is_terminated
+	 */
+	public function test_is_terminated( string $css, bool $expected ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$this->assertTrue( $processor->next_token() );
+
+		$token = $processor->get_token();
+		$processor->next_token();
+		$this->assertSame( $expected, $token->is_terminated(), 'The flag must not change when the processor moves on.' );
+	}
+
+	/**
+	 * Data provider for test_is_terminated().
+	 *
+	 * @return array[]
+	 */
+	public static function data_is_terminated(): array {
+		return array(
+			'string terminated'    => array( '"a" b', true ),
+			'string unterminated'  => array( '"a', false ),
+			'url terminated'       => array( 'url(a) b', true ),
+			'url unterminated'     => array( 'url(a', false ),
+			'comment terminated'   => array( '/* a */ b', true ),
+			'comment unterminated' => array( '/* a', false ),
+			'ident'                => array( 'a b', true ),
+		);
+	}
+}

From 892cd25930e3e4123e9519ba142236f7f599505d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:25:25 +0400
Subject: [PATCH 14/77] Move string and ident serialization into
 WP_CSS_Token_Serializer

The token processor reads CSS; the new class writes it. serialize_string() and serialize_ident() move unchanged, with their tests.
---
 .../css-api/class-wp-css-token-processor.php  | 142 ----------------
 .../css-api/class-wp-css-token-serializer.php | 157 ++++++++++++++++++
 src/wp-settings.php                           |   1 +
 ...serialize.php => wpCssTokenSerializer.php} |  18 +-
 4 files changed, 167 insertions(+), 151 deletions(-)
 create mode 100644 src/wp-includes/css-api/class-wp-css-token-serializer.php
 rename tests/phpunit/tests/css-api/{wpCssTokenProcessor-serialize.php => wpCssTokenSerializer.php} (88%)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 6b5cc4f7f6e52..87c8b022c74c9 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -832,148 +832,6 @@ public function is_token_terminated(): bool {
 		return null !== $this->token_type && $this->token_is_terminated;
 	}
 
-	/**
-	 * Serializes a plain PHP string as CSS identifier text.
-	 *
-	 * Characters not valid in CSS identifiers are hex-escaped. This uses
-	 * the same safety escaping as {@see WP_CSS_Token_Processor::serialize_string()} for HTML
-	 * and CSS-sensitive characters, plus escaping of whitespace and other
-	 * characters not permitted in idents.
-	 *
-	 * An empty string serializes to an empty string. Callers that require an
-	 * ident token must reject an empty value.
-	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param string $value Decoded string value to encode as a CSS identifier.
-	 * @return string Serialized CSS identifier text.
-	 */
-	public static function serialize_ident( string $value ): string {
-		$value  = wp_scrub_utf8( $value );
-		$result = '';
-		$length = strlen( $value );
-
-		for ( $i = 0; $i < $length; $i++ ) {
-			$byte = ord( $value[ $i ] );
-
-			// NULL → U+FFFD REPLACEMENT CHARACTER.
-			if ( 0x00 === $byte ) {
-				$result .= "\u{FFFD}";
-				continue;
-			}
-
-			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
-			if ( $byte >= 0x80 ) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// ASCII letters and underscore: always valid in idents.
-			if (
-				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
-				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
-				0x5F === $byte                         // _
-			) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// Hyphen: valid in idents, but check for hyphen-digit at start.
-			if ( 0x2D === $byte ) {
-				// A hyphen standing alone must be escaped to form an ident token.
-				if ( 0 === $i && 1 === $length ) {
-					$result .= '\\2D ';
-					continue;
-				}
-
-				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
-				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
-					$result .= '-';
-					++$i;
-					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
-					continue;
-				}
-				$result .= '-';
-				continue;
-			}
-
-			// Digits: valid except at position 0.
-			if ( $byte >= 0x30 && $byte <= 0x39 ) {
-				if ( 0 === $i ) {
-					$result .= sprintf( '\\%X ', $byte );
-				} else {
-					$result .= $value[ $i ];
-				}
-				continue;
-			}
-
-			// Everything else: hex-escape.
-			$result .= sprintf( '\\%X ', $byte );
-		}
-
-		return $result;
-	}
-
-	/**
-	 * Creates a quoted CSS string from a plain PHP string value.
-	 *
-	 * Example:
-	 *     $value = 'CSS & a "<style>" tag\'s strings';
-	 *     $css_string = WP_CSS_Token_Processor::serialize_string( $value );
-	 *     echo "<style>*::before { content: {$css_string}; }</style>";
-	 *
-	 * CSS strings are quoted, and many characters that are problematic in HTML
-	 * or may be complicated for rudimentary CSS or HTML processors to handle
-	 * are encoded using Unicode escape sequences.
-	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param string $value Decoded string value to encode as a quoted CSS string.
-	 * @return string Serialized quoted CSS string text.
-	 */
-	public static function serialize_string( string $value ): string {
-		$value   = wp_scrub_utf8( $value );
-		$escaped = strtr(
-			$value,
-			array(
-				// Escape existing backslashes to prevent unintentional escapes in result.
-				'\\'   => '\\5C ',
-
-				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
-				"\0"   => "\u{FFFD}",
-
-				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
-				"\r\n" => '\\A ',
-				"\r"   => '\\A ',
-				"\f"   => '\\A ',
-
-				// Newlines must be escaped in CSS strings.
-				"\n"   => '\\A ',
-
-				// Arbitrary characters for Unicode escaping:
-
-				// HTML syntax may be problematic.
-				'<'    => '\\3C ',
-				'>'    => '\\3E ',
-				'&'    => '\\26 ',
-
-				// CSS syntax may be problematic.
-				','    => '\\2C ',
-				';'    => '\\3B ',
-				'{'    => '\\7B ',
-				'}'    => '\\7D ',
-				'"'    => '\\22 ',
-				"'"    => '\\27 ',
-			)
-		);
-		return "\"{$escaped}\"";
-	}
-
 	/**
 	 * Clears token state between tokens.
 	 */
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
new file mode 100644
index 0000000000000..122b04fcb4006
--- /dev/null
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -0,0 +1,157 @@
+<?php
+/**
+ * CSS API: WP_CSS_Token_Serializer class
+ *
+ * @package WordPress
+ * @subpackage CSS-API
+ * @since 7.2.0
+ */
+
+/**
+ * Serializes CSS tokens and values as CSS text.
+ *
+ * @since 7.2.0
+ */
+class WP_CSS_Token_Serializer {
+	/**
+	 * Serializes a plain PHP string as CSS identifier text.
+	 *
+	 * Characters not valid in CSS identifiers are hex-escaped. This uses
+	 * the same safety escaping as {@see WP_CSS_Token_Serializer::serialize_string()} for HTML
+	 * and CSS-sensitive characters, plus escaping of whitespace and other
+	 * characters not permitted in idents.
+	 *
+	 * An empty string serializes to an empty string. Callers that require an
+	 * ident token must reject an empty value.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded string value to encode as a CSS identifier.
+	 * @return string Serialized CSS identifier text.
+	 */
+	public static function serialize_ident( string $value ): string {
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			// NULL → U+FFFD REPLACEMENT CHARACTER.
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
+			if ( $byte >= 0x80 ) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// ASCII letters and underscore: always valid in idents.
+			if (
+				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
+				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
+				0x5F === $byte                         // _
+			) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			// Hyphen: valid in idents, but check for hyphen-digit at start.
+			if ( 0x2D === $byte ) {
+				// A hyphen standing alone must be escaped to form an ident token.
+				if ( 0 === $i && 1 === $length ) {
+					$result .= '\\2D ';
+					continue;
+				}
+
+				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
+				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
+					$result .= '-';
+					++$i;
+					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
+					continue;
+				}
+				$result .= '-';
+				continue;
+			}
+
+			// Digits: valid except at position 0.
+			if ( $byte >= 0x30 && $byte <= 0x39 ) {
+				if ( 0 === $i ) {
+					$result .= sprintf( '\\%X ', $byte );
+				} else {
+					$result .= $value[ $i ];
+				}
+				continue;
+			}
+
+			// Everything else: hex-escape.
+			$result .= sprintf( '\\%X ', $byte );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Creates a quoted CSS string from a plain PHP string value.
+	 *
+	 * Example:
+	 *     $value = 'CSS & a "<style>" tag\'s strings';
+	 *     $css_string = WP_CSS_Token_Serializer::serialize_string( $value );
+	 *     echo "<style>*::before { content: {$css_string}; }</style>";
+	 *
+	 * CSS strings are quoted, and many characters that are problematic in HTML
+	 * or may be complicated for rudimentary CSS or HTML processors to handle
+	 * are encoded using Unicode escape sequences.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded string value to encode as a quoted CSS string.
+	 * @return string Serialized quoted CSS string text.
+	 */
+	public static function serialize_string( string $value ): string {
+		$value   = wp_scrub_utf8( $value );
+		$escaped = strtr(
+			$value,
+			array(
+				// Escape existing backslashes to prevent unintentional escapes in result.
+				'\\'   => '\\5C ',
+
+				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
+				"\0"   => "\u{FFFD}",
+
+				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+				"\r\n" => '\\A ',
+				"\r"   => '\\A ',
+				"\f"   => '\\A ',
+
+				// Newlines must be escaped in CSS strings.
+				"\n"   => '\\A ',
+
+				// Arbitrary characters for Unicode escaping:
+
+				// HTML syntax may be problematic.
+				'<'    => '\\3C ',
+				'>'    => '\\3E ',
+				'&'    => '\\26 ',
+
+				// CSS syntax may be problematic.
+				','    => '\\2C ',
+				';'    => '\\3B ',
+				'{'    => '\\7B ',
+				'}'    => '\\7D ',
+				'"'    => '\\22 ',
+				"'"    => '\\27 ',
+			)
+		);
+		return "\"{$escaped}\"";
+	}
+}
diff --git a/src/wp-settings.php b/src/wp-settings.php
index ddf98c1437406..6dac160973467 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -280,6 +280,7 @@
 require ABSPATH . WPINC . '/html-api/class-wp-html-processor.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
+require ABSPATH . WPINC . '/css-api/class-wp-css-token-serializer.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
similarity index 88%
rename from tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php
rename to tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index caabc0fc948ac..959d711df44af 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor-serialize.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -1,20 +1,20 @@
 <?php
 
 /**
- * Tests for WP_CSS_Token_Processor string and identifier serialization.
+ * Tests for WP_CSS_Token_Serializer.
  *
  * @group css-api
  *
- * @coversDefaultClass WP_CSS_Token_Processor
+ * @coversDefaultClass WP_CSS_Token_Serializer
  */
-class Tests_CssApi_WpCssTokenProcessor_Serialize extends WP_UnitTestCase {
+class Tests_CssApi_WpCssTokenSerializer extends WP_UnitTestCase {
 	/**
 	 * @dataProvider data_string_escaping
 	 *
 	 * @covers ::serialize_string
 	 */
 	public function test_string_escaping( string $input, string $expected ): void {
-		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $input ) );
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
 
 		/**
 		 * Ensure that a single, equivalent CSS string is produced.
@@ -24,7 +24,7 @@ public function test_string_escaping( string $input, string $expected ): void {
 		 *
 		 * @see https://www.w3.org/TR/css-syntax-3/#input-preprocessing
 		 */
-		$processor = WP_CSS_Token_Processor::create( WP_CSS_Token_Processor::serialize_string( $input ) );
+		$processor = WP_CSS_Token_Processor::create( WP_CSS_Token_Serializer::serialize_string( $input ) );
 		$processor->next_token();
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
 		$expected_decoded_value = strtr(
@@ -89,7 +89,7 @@ public function test_docblock_example(): void {
 		$value    = 'CSS & a "<style>" tag\'s strings';
 		$expected = '"CSS \26  a \22 \3C style\3E \22  tag\27 s strings"';
 
-		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $value ) );
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $value ) );
 	}
 
 	/**
@@ -101,11 +101,11 @@ public function test_mixed_newlines(): void {
 		$input    = "line1\nline2\rline3\r\nline4\fline5";
 		$expected = '"line1\A line2\A line3\A line4\A line5"';
 
-		$this->assertSame( $expected, WP_CSS_Token_Processor::serialize_string( $input ) );
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
 	}
 
 	/**
-	 * Tests WP_CSS_Token_Processor::serialize_ident() serializes CSS identifiers.
+	 * Tests WP_CSS_Token_Serializer::serialize_ident() serializes CSS identifiers.
 	 *
 	 * @ticket 65738
 	 *
@@ -114,7 +114,7 @@ public function test_mixed_newlines(): void {
 	 * @covers ::serialize_ident
 	 */
 	public function test_ident( string $input, string $expected ): void {
-		$serialized = WP_CSS_Token_Processor::serialize_ident( $input );
+		$serialized = WP_CSS_Token_Serializer::serialize_ident( $input );
 		$this->assertSame( $expected, $serialized );
 
 		$processor = WP_CSS_Token_Processor::create( $serialized );

From 8dbd3981d792c5b50d51e932fa466fde20b8fa8e Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:33:57 +0400
Subject: [PATCH 15/77] =?UTF-8?q?Serialize=20tokens=20following=20CSS=20Sy?=
 =?UTF-8?q?ntax=203=20=C2=A79?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

WP_CSS_Token_Serializer::serialize() writes tokens read by the processor as CSS that reads as the same tokens. Comments are dropped, and each whitespace run, including one broken by comments, becomes one space. An empty comment, /**/, separates each token pair the §9 table marks when no whitespace is between them. Tokens are escaped again from their decoded values: a `\` delim keeps its newline, a hash is escaped by its type flag, and a unit that reads as an exponent has its `e` escaped. Strings and urls cut off by the end of the input are written closed, and blocks still open at the end are closed in reverse order.

Bad-string and bad-url tokens have no value; they are written as a quote and a newline, and as `url(()`.

serialize_string() still normalizes newlines in its argument. Token values are quoted without that step, so an escaped CR or FF in a string keeps its code point.
---
 .../css-api/class-wp-css-token-serializer.php | 465 +++++++++++++++++-
 .../tests/css-api/wpCssTokenSerializer.php    | 352 +++++++++++++
 2 files changed, 799 insertions(+), 18 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index 122b04fcb4006..ac4f4d23dc870 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -10,9 +10,330 @@
 /**
  * Serializes CSS tokens and values as CSS text.
  *
+ * serialize() writes tokens read by WP_CSS_Token_Processor. serialize_ident()
+ * and serialize_string() write a plain PHP string as an identifier or as a
+ * quoted string.
+ *
+ * Output is valid CSS that reads as the same tokens. Which characters are
+ * escaped may change.
+ *
  * @since 7.2.0
+ *
+ * @see WP_CSS_Token_Processor
  */
 class WP_CSS_Token_Serializer {
+	/**
+	 * Token pairs that must be written with a comment between them.
+	 *
+	 * Keys are the first token and values list the second; a delim token is
+	 * named by its value, every other token by its type.
+	 *
+	 * @see WP_CSS_Token_Serializer::serialize()
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var array<string, string[]>
+	 */
+	private const MARKED_PAIRS = array(
+		WP_CSS_Token_Processor::TOKEN_IDENT      => array(
+			WP_CSS_Token_Processor::TOKEN_IDENT,
+			WP_CSS_Token_Processor::TOKEN_FUNCTION,
+			WP_CSS_Token_Processor::TOKEN_URL,
+			WP_CSS_Token_Processor::TOKEN_BAD_URL,
+			'-',
+			WP_CSS_Token_Processor::TOKEN_NUMBER,
+			WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+			WP_CSS_Token_Processor::TOKEN_DIMENSION,
+			WP_CSS_Token_Processor::TOKEN_CDC,
+			WP_CSS_Token_Processor::TOKEN_LEFT_PAREN,
+		),
+		WP_CSS_Token_Processor::TOKEN_AT_KEYWORD => self::IDENT_LIKE_FOLLOWERS,
+		WP_CSS_Token_Processor::TOKEN_HASH       => self::IDENT_LIKE_FOLLOWERS,
+		WP_CSS_Token_Processor::TOKEN_DIMENSION  => self::IDENT_LIKE_FOLLOWERS,
+		'#'                                      => self::IDENT_LIKE_FOLLOWERS,
+		'-'                                      => self::IDENT_LIKE_FOLLOWERS,
+		WP_CSS_Token_Processor::TOKEN_NUMBER     => array(
+			WP_CSS_Token_Processor::TOKEN_IDENT,
+			WP_CSS_Token_Processor::TOKEN_FUNCTION,
+			WP_CSS_Token_Processor::TOKEN_URL,
+			WP_CSS_Token_Processor::TOKEN_BAD_URL,
+			WP_CSS_Token_Processor::TOKEN_NUMBER,
+			WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+			WP_CSS_Token_Processor::TOKEN_DIMENSION,
+			WP_CSS_Token_Processor::TOKEN_CDC,
+			'%',
+		),
+		'@'                                      => array(
+			WP_CSS_Token_Processor::TOKEN_IDENT,
+			WP_CSS_Token_Processor::TOKEN_FUNCTION,
+			WP_CSS_Token_Processor::TOKEN_URL,
+			WP_CSS_Token_Processor::TOKEN_BAD_URL,
+			'-',
+			WP_CSS_Token_Processor::TOKEN_CDC,
+		),
+		'.'                                      => self::NUMERIC_TOKENS,
+		'+'                                      => self::NUMERIC_TOKENS,
+		'/'                                      => array( '*' ),
+	);
+
+	/**
+	 * Second tokens of the marked pairs shared by the at-keyword, hash,
+	 * dimension, `#` and `-` rows.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string[]
+	 */
+	private const IDENT_LIKE_FOLLOWERS = array(
+		WP_CSS_Token_Processor::TOKEN_IDENT,
+		WP_CSS_Token_Processor::TOKEN_FUNCTION,
+		WP_CSS_Token_Processor::TOKEN_URL,
+		WP_CSS_Token_Processor::TOKEN_BAD_URL,
+		'-',
+		WP_CSS_Token_Processor::TOKEN_NUMBER,
+		WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+		WP_CSS_Token_Processor::TOKEN_DIMENSION,
+		WP_CSS_Token_Processor::TOKEN_CDC,
+	);
+
+	/**
+	 * Second tokens of the marked pairs in the `.` and `+` rows.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var string[]
+	 */
+	private const NUMERIC_TOKENS = array(
+		WP_CSS_Token_Processor::TOKEN_NUMBER,
+		WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+		WP_CSS_Token_Processor::TOKEN_DIMENSION,
+	);
+
+	/**
+	 * Text of the token types that have no value.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var array<string, string>
+	 */
+	private const FIXED_TEXT = array(
+		WP_CSS_Token_Processor::TOKEN_COLON         => ':',
+		WP_CSS_Token_Processor::TOKEN_SEMICOLON     => ';',
+		WP_CSS_Token_Processor::TOKEN_COMMA         => ',',
+		WP_CSS_Token_Processor::TOKEN_LEFT_PAREN    => '(',
+		WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN   => ')',
+		WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET  => '[',
+		WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET => ']',
+		WP_CSS_Token_Processor::TOKEN_LEFT_BRACE    => '{',
+		WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE   => '}',
+		WP_CSS_Token_Processor::TOKEN_CDO           => '<!--',
+		WP_CSS_Token_Processor::TOKEN_CDC           => '-->',
+		WP_CSS_Token_Processor::TOKEN_BAD_STRING    => "\"\n",
+		WP_CSS_Token_Processor::TOKEN_BAD_URL       => 'url(()',
+	);
+
+	/**
+	 * Closing token type of each token type that opens a block.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @var array<string, string>
+	 */
+	private const BLOCK_CLOSERS = array(
+		WP_CSS_Token_Processor::TOKEN_FUNCTION     => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+		WP_CSS_Token_Processor::TOKEN_LEFT_PAREN   => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+		WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET,
+		WP_CSS_Token_Processor::TOKEN_LEFT_BRACE   => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+	);
+
+	/**
+	 * Serializes tokens as CSS text that reads as the same tokens.
+	 *
+	 * This follows CSS Syntax Level 3 §9 Serialization:
+	 *
+	 * > The only requirement for serialization is that it must "round-trip" with parsing,
+	 * > that is, parsing the stylesheet must produce the same data structures as
+	 * > parsing, serializing, and parsing again,
+	 * > except for consecutive <whitespace-token>s,
+	 * > which may be collapsed into a single token.
+	 *
+	 * Comment tokens are dropped. Each run of whitespace, including a run
+	 * broken by comments, is written as one space; a run is never removed.
+	 *
+	 * Tokens are written from their decoded values. Identifiers, function
+	 * names, at-keywords, hash names, dimension units, strings and url values
+	 * are escaped again, so `\66 oo` becomes `foo` and `"a&b"` becomes `"a\26 b"`.
+	 *
+	 * > A <delim-token> containing U+005C REVERSE SOLIDUS (\)
+	 * > must be serialized as U+005C REVERSE SOLIDUS
+	 * > followed by a newline.
+	 * > (The tokenizer only ever emits such a token followed by a <whitespace-token>
+	 * > that starts with a newline.)
+	 *
+	 * > A <hash-token> with the "unrestricted" type flag may not need
+	 * > as much escaping as the same token with the "id" type flag.
+	 *
+	 * A hash with the "id" flag is escaped as an identifier, so `#\31 a` stays
+	 * `#\31 a`. A hash with the "unrestricted" flag may start with a digit or
+	 * `-`, so `#1a` stays `#1a`.
+	 *
+	 * > The unit of a <dimension-token> may need escaping
+	 * > to disambiguate with scientific notation.
+	 *
+	 * A unit that starts with `e`, an optional `-`, and a digit has the `e`
+	 * escaped, so the unit `e3` is written `1\65 3`, not `1e3`.
+	 *
+	 * > For any consecutive pair of tokens,
+	 * > if the first token shows up in the row headings of the following table,
+	 * > and the second token shows up in the column headings,
+	 * > and there’s a ✗ in the cell denoted by the intersection of the chosen row and column,
+	 * > the pair of tokens must be serialized with a comment between them.
+	 * >
+	 * > Single characters in the row and column headings represent a <delim-token> with that value,
+	 * > except for "(",
+	 * > which represents a (-token.
+	 *
+	 *     ┌────────────┬───────┬──────────┬─────┬─────────┬───┬────────┬────────────┬───────────┬─────┬───┬───┬───┐
+	 *     │            │ ident │ function │ url │ bad url │ - │ number │ percentage │ dimension │ CDC │ ( │ * │ % │
+	 *     ├────────────┼───────┼──────────┼─────┼─────────┼───┼────────┼────────────┼───────────┼─────┼───┼───┼───┤
+	 *     │ ident      │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │ ✗ │   │   │
+	 *     │ at-keyword │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │   │   │   │
+	 *     │ hash       │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │   │   │   │
+	 *     │ dimension  │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │   │   │   │
+	 *     │ #          │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │   │   │   │
+	 *     │ -          │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │   ✗    │     ✗      │     ✗     │  ✗  │   │   │   │
+	 *     │ number     │   ✗   │    ✗     │  ✗  │    ✗    │   │   ✗    │     ✗      │     ✗     │  ✗  │   │   │ ✗ │
+	 *     │ @          │   ✗   │    ✗     │  ✗  │    ✗    │ ✗ │        │            │           │  ✗  │   │   │   │
+	 *     │ .          │       │          │     │         │   │   ✗    │     ✗      │     ✗     │     │   │   │   │
+	 *     │ +          │       │          │     │         │   │   ✗    │     ✗      │     ✗     │     │   │   │   │
+	 *     │ /          │       │          │     │         │   │        │            │           │     │   │ ✗ │   │
+	 *     └────────────┴───────┴──────────┴─────┴─────────┴───┴────────┴────────────┴───────────┴─────┴───┴───┴───┘
+	 *
+	 * Comments are not preserved, so an empty CSS comment is written between
+	 * the tokens of a marked pair when no whitespace is between them.
+	 *
+	 * Bad-string and bad-url tokens have no value. A bad string is written as
+	 * a quote followed by a newline, where the tokenizer ends one; a bad url is
+	 * written as `url(()`.
+	 *
+	 * Strings and urls cut off by the end of the input are written closed.
+	 * Blocks still open at the end are closed in reverse order, so `a(b[c` is
+	 * written `a(b[c])`.
+	 *
+	 * Example:
+	 *
+	 *     $processor = WP_CSS_Token_Processor::create( 'url( a&b ) calc(1px  +  2px' );
+	 *     $tokens    = array();
+	 *     while ( $processor->next_token() ) {
+	 *         $tokens[] = $processor->get_token();
+	 *     }
+	 *     WP_CSS_Token_Serializer::serialize( $tokens ); // 'url(a\26 b) calc(1px + 2px)'
+	 *
+	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param iterable<WP_CSS_Token> $tokens Tokens read by WP_CSS_Token_Processor::get_token().
+	 * @return string CSS text.
+	 */
+	public static function serialize( iterable $tokens ): string {
+		$output  = '';
+		$closers = array();
+
+		// Pair key of the last token written, or the whitespace type after a space.
+		$last = null;
+
+		foreach ( $tokens as $token ) {
+			$type = $token->get_type();
+
+			if ( WP_CSS_Token_Processor::TOKEN_COMMENT === $type ) {
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE === $type ) {
+				if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $last ) {
+					$output .= ' ';
+					$last    = WP_CSS_Token_Processor::TOKEN_WHITESPACE;
+				}
+				continue;
+			}
+
+			$key = WP_CSS_Token_Processor::TOKEN_DELIM === $type ? $token->get_value() : $type;
+			if ( null !== $last && isset( self::MARKED_PAIRS[ $last ] ) && in_array( $key, self::MARKED_PAIRS[ $last ], true ) ) {
+				$output .= '/**/';
+			}
+			$last = $key;
+
+			$output .= self::serialize_token( $token );
+
+			if ( isset( self::BLOCK_CLOSERS[ $type ] ) ) {
+				$closers[] = self::BLOCK_CLOSERS[ $type ];
+			} elseif ( end( $closers ) === $type ) {
+				array_pop( $closers );
+			}
+		}
+
+		while ( array() !== $closers ) {
+			$output .= self::FIXED_TEXT[ array_pop( $closers ) ];
+		}
+
+		return $output;
+	}
+
+	/**
+	 * Serializes one token other than whitespace or a comment.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param WP_CSS_Token $token Token.
+	 * @return string CSS text.
+	 */
+	private static function serialize_token( WP_CSS_Token $token ): string {
+		$value = $token->get_value();
+
+		switch ( $token->get_type() ) {
+			case WP_CSS_Token_Processor::TOKEN_IDENT:
+				return self::serialize_ident( $value );
+
+			case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+				return self::serialize_ident( $value ) . '(';
+
+			case WP_CSS_Token_Processor::TOKEN_AT_KEYWORD:
+				return '@' . self::serialize_ident( $value );
+
+			case WP_CSS_Token_Processor::TOKEN_HASH:
+				return WP_CSS_Token_Processor::HASH_TOKEN_ID === $token->get_flag()
+					? '#' . self::serialize_ident( $value )
+					: '#' . self::escape_name_code_points( $value );
+
+			case WP_CSS_Token_Processor::TOKEN_STRING:
+				return self::quote_string( $value );
+
+			case WP_CSS_Token_Processor::TOKEN_URL:
+				return 'url(' . self::serialize_url_value( $value ) . ')';
+
+			case WP_CSS_Token_Processor::TOKEN_NUMBER:
+				return $value;
+
+			case WP_CSS_Token_Processor::TOKEN_PERCENTAGE:
+				return $value . '%';
+
+			case WP_CSS_Token_Processor::TOKEN_DIMENSION:
+				$unit = self::serialize_ident( $token->get_unit() );
+				// A unit that starts with `e`, an optional `-`, and a digit would read as an exponent.
+				if ( 1 === preg_match( '/^[eE]-?[0-9]/', $unit ) ) {
+					$unit = sprintf( '\\%X ', ord( $unit[0] ) ) . substr( $unit, 1 );
+				}
+				return $value . $unit;
+
+			case WP_CSS_Token_Processor::TOKEN_DELIM:
+				return '\\' === $value ? "\\\n" : $value;
+
+			default:
+				return self::FIXED_TEXT[ $token->get_type() ];
+		}
+	}
+
 	/**
 	 * Serializes a plain PHP string as CSS identifier text.
 	 *
@@ -118,40 +439,148 @@ public static function serialize_ident( string $value ): string {
 	 * @return string Serialized quoted CSS string text.
 	 */
 	public static function serialize_string( string $value ): string {
+		// Normalize newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+		$value = strtr(
+			$value,
+			array(
+				"\r\n" => "\n",
+				"\r"   => "\n",
+				"\f"   => "\n",
+			)
+		);
+
+		return self::quote_string( $value );
+	}
+
+	/**
+	 * Creates a quoted CSS string from a decoded value without normalizing newlines.
+	 *
+	 * A CR or FF in a token value comes from an escape such as `\D `, so it is
+	 * escaped, not written as a newline.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded string value to encode as a quoted CSS string.
+	 * @return string Serialized quoted CSS string text.
+	 */
+	private static function quote_string( string $value ): string {
 		$value   = wp_scrub_utf8( $value );
 		$escaped = strtr(
 			$value,
 			array(
 				// Escape existing backslashes to prevent unintentional escapes in result.
-				'\\'   => '\\5C ',
+				'\\' => '\\5C ',
 
-				// Pre-processing replaces NULLs and some newlines. Replace and escape as necessary.
-				"\0"   => "\u{FFFD}",
-
-				// Normalize and replace newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
-				"\r\n" => '\\A ',
-				"\r"   => '\\A ',
-				"\f"   => '\\A ',
+				// Pre-processing replaces NULLs. Replace as necessary.
+				"\0" => "\u{FFFD}",
 
 				// Newlines must be escaped in CSS strings.
-				"\n"   => '\\A ',
+				"\n" => '\\A ',
+				"\r" => '\\D ',
+				"\f" => '\\C ',
 
 				// Arbitrary characters for Unicode escaping:
 
 				// HTML syntax may be problematic.
-				'<'    => '\\3C ',
-				'>'    => '\\3E ',
-				'&'    => '\\26 ',
+				'<'  => '\\3C ',
+				'>'  => '\\3E ',
+				'&'  => '\\26 ',
 
 				// CSS syntax may be problematic.
-				','    => '\\2C ',
-				';'    => '\\3B ',
-				'{'    => '\\7B ',
-				'}'    => '\\7D ',
-				'"'    => '\\22 ',
-				"'"    => '\\27 ',
+				','  => '\\2C ',
+				';'  => '\\3B ',
+				'{'  => '\\7B ',
+				'}'  => '\\7D ',
+				'"'  => '\\22 ',
+				"'"  => '\\27 ',
 			)
 		);
 		return "\"{$escaped}\"";
 	}
+
+	/**
+	 * Escapes every code point that cannot appear in an identifier.
+	 *
+	 * Letters, digits, `-`, `_` and code points U+0080 and above are written
+	 * as they are; every other code point is hex-escaped. Unlike
+	 * serialize_ident(), a leading digit or `-` is not escaped, as the name of
+	 * a hash token with the "unrestricted" flag requires.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded name.
+	 * @return string Escaped name.
+	 */
+	private static function escape_name_code_points( string $value ): string {
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			if (
+				$byte >= 0x80 ||
+				( $byte >= 0x30 && $byte <= 0x39 ) || // 0-9
+				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
+				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
+				0x5F === $byte || // _
+				0x2D === $byte // -
+			) {
+				$result .= $value[ $i ];
+				continue;
+			}
+
+			$result .= sprintf( '\\%X ', $byte );
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Escapes the value of a url token.
+	 *
+	 * The code points an unquoted url cannot contain are hex-escaped: quotes,
+	 * parentheses, `\`, whitespace and non-printable code points. So are the
+	 * code points serialize_string() escapes for HTML and CSS: `< > & , ; { }`.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $value Decoded url value.
+	 * @return string Escaped url value, without `url(` and `)`.
+	 */
+	private static function serialize_url_value( string $value ): string {
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			if (
+				$byte <= 0x20 ||
+				0x7F === $byte ||
+				false !== strpos( '"\'()\\<>&,;{}', $value[ $i ] )
+			) {
+				$result .= sprintf( '\\%X ', $byte );
+				continue;
+			}
+
+			$result .= $value[ $i ];
+		}
+
+		return $result;
+	}
 }
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 959d711df44af..016d4626a5a2a 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -177,4 +177,356 @@ public static function data_ident(): Generator {
 		yield 'Semicolon' => array( 'a;b', 'a\\3B b' );
 		yield 'Backslash' => array( 'a\\b', 'a\\5C b' );
 	}
+
+	/**
+	 * Tests that serialize() writes an empty CSS comment between the tokens of a marked pair.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_marked_pairs
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_marked_pair_is_separated_by_an_empty_comment( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+		$this->assertSame( self::significant_tokens( $css ), self::significant_tokens( $expected ), 'The output must read as the same tokens.' );
+	}
+
+	/**
+	 * Data provider for test_marked_pair_is_separated_by_an_empty_comment().
+	 *
+	 * One case for each ✗ cell in the table in CSS Syntax Level 3 §9.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#serialization
+	 *
+	 * @return Generator
+	 */
+	public static function data_marked_pairs(): Generator {
+		// Source text for the first token, keyed by its row heading.
+		$rows = array(
+			'ident'      => 'a',
+			'at-keyword' => '@a',
+			'hash'       => '#a',
+			'dimension'  => '1px',
+			'#'          => '#',
+			'-'          => '-',
+			'number'     => '1',
+			'@'          => '@',
+			'.'          => '.',
+			'+'          => '+',
+			'/'          => '/',
+		);
+
+		// Source text and its serialization for the second token, keyed by its column heading.
+		$columns = array(
+			'ident'      => array( 'b', 'b' ),
+			'function'   => array( 'b()', 'b()' ),
+			'url'        => array( 'url(b)', 'url(b)' ),
+			'bad url'    => array( 'url(b c)', 'url(()' ),
+			'-'          => array( '-', '-' ),
+			'number'     => array( '2', '2' ),
+			'percentage' => array( '2%', '2%' ),
+			'dimension'  => array( '2px', '2px' ),
+			'CDC'        => array( '-->', '-->' ),
+			'('          => array( '()', '()' ),
+			'*'          => array( '*', '*' ),
+			'%'          => array( '%', '%' ),
+		);
+
+		$marked = array(
+			'ident'      => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC', '(' ),
+			'at-keyword' => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC' ),
+			'hash'       => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC' ),
+			'dimension'  => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC' ),
+			'#'          => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC' ),
+			'-'          => array( 'ident', 'function', 'url', 'bad url', '-', 'number', 'percentage', 'dimension', 'CDC' ),
+			'number'     => array( 'ident', 'function', 'url', 'bad url', 'number', 'percentage', 'dimension', 'CDC', '%' ),
+			'@'          => array( 'ident', 'function', 'url', 'bad url', '-', 'CDC' ),
+			'.'          => array( 'number', 'percentage', 'dimension' ),
+			'+'          => array( 'number', 'percentage', 'dimension' ),
+			'/'          => array( '*' ),
+		);
+
+		foreach ( $marked as $row => $row_columns ) {
+			foreach ( $row_columns as $column ) {
+				list( $column_css, $column_serialized ) = $columns[ $column ];
+				yield "{$row} followed by {$column}" => array(
+					"{$rows[ $row ]}/**/{$column_css}",
+					"{$rows[ $row ]}/**/{$column_serialized}",
+				);
+			}
+		}
+	}
+
+	/**
+	 * Tests that serialize() writes no comment between the tokens of an unmarked pair.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_unmarked_pairs
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_unmarked_pair_is_not_separated( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+		$this->assertSame( self::significant_tokens( $css ), self::significant_tokens( $expected ), 'The output must read as the same tokens.' );
+	}
+
+	/**
+	 * Data provider for test_unmarked_pair_is_not_separated().
+	 *
+	 * @return array[]
+	 */
+	public static function data_unmarked_pairs(): array {
+		return array(
+			'ident followed by *'          => array( 'a/**/*', 'a*' ),
+			'ident followed by %'          => array( 'a/**/%', 'a%' ),
+			'ident followed by colon'      => array( 'a/**/:', 'a:' ),
+			'at-keyword followed by ('     => array( '@a/**/()', '@a()' ),
+			'hash followed by *'           => array( '#a/**/*', '#a*' ),
+			'dimension followed by %'      => array( '1px/**/%', '1px%' ),
+			'# followed by %'              => array( '#/**/%', '#%' ),
+			'- followed by *'              => array( '-/**/*', '-*' ),
+			'number followed by -'         => array( '1/**/-', '1-' ),
+			'number followed by ('         => array( '1/**/()', '1()' ),
+			'@ followed by number'         => array( '@/**/1', '@1' ),
+			'. followed by ident'          => array( './**/a', '.a' ),
+			'+ followed by ident'          => array( '+/**/a', '+a' ),
+			'/ followed by ident'          => array( '//**/a', '/a' ),
+			'string followed by ident'     => array( '"a"/**/b', '"a"b' ),
+			'url followed by ident'        => array( 'url(a)/**/b', 'url(a)b' ),
+			'function followed by ident'   => array( 'a(/**/b)', 'a(b)' ),
+			') followed by ident'          => array( '(a)/**/b', '(a)b' ),
+			'CDC followed by ident'        => array( '-->/**/a', '-->a' ),
+			'percentage followed by ident' => array( '1%/**/a', '1%a' ),
+		);
+	}
+
+	/**
+	 * Tests that serialize() drops comments and writes each whitespace run as one space.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_whitespace_and_comments
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_whitespace_and_comments( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+	}
+
+	/**
+	 * Data provider for test_whitespace_and_comments().
+	 *
+	 * @return array[]
+	 */
+	public static function data_whitespace_and_comments(): array {
+		return array(
+			'empty input'               => array( '', '' ),
+			'one space'                 => array( 'a b', 'a b' ),
+			'mixed whitespace run'      => array( "a \t\r\n\f b", 'a b' ),
+			'run broken by a comment'   => array( 'a /* x */ b', 'a b' ),
+			'whitespace then a comment' => array( 'a /**/b', 'a b' ),
+			'a comment then whitespace' => array( 'a/**/ b', 'a b' ),
+			'leading whitespace'        => array( "\n a", ' a' ),
+			'trailing whitespace'       => array( "a \n", 'a ' ),
+			'only whitespace'           => array( "\t\n", ' ' ),
+			'only a comment'            => array( '/* x */', '' ),
+			'comment in unmarked pair'  => array( 'a/* x */,b', 'a,b' ),
+			'unterminated comment'      => array( 'a /* x', 'a ' ),
+		);
+	}
+
+	/**
+	 * Tests how serialize() writes each token type.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_token_serialization
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_token_serialization( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+		$this->assertSame( self::significant_tokens( $css ), self::significant_tokens( $expected ), 'The output must read as the same tokens.' );
+	}
+
+	/**
+	 * Data provider for test_token_serialization().
+	 *
+	 * @return array[]
+	 */
+	public static function data_token_serialization(): array {
+		return array(
+			'ident escapes decoded'                  => array( '\\66 oo', 'foo' ),
+			'ident escapes added'                    => array( 'a\\:b', 'a\\3A b' ),
+			'function'                               => array( '\\66 oo(1)', 'foo(1)' ),
+			'at-keyword'                             => array( '@\\66 oo', '@foo' ),
+			'hash id'                                => array( '#a\\:', '#a\\3A ' ),
+			'hash id escaped digit'                  => array( '#\\31 a', '#\\31 a' ),
+			'hash unrestricted'                      => array( '#1a', '#1a' ),
+			'hash unrestricted escape'               => array( '#1\\:', '#1\\3A ' ),
+			'hash unrestricted hyphen'               => array( '#-', '#-' ),
+			'string'                                 => array( "'a\"b'", '"a\\22 b"' ),
+			'string ampersand'                       => array( '"a&b"', '"a\\26 b"' ),
+			'string unterminated'                    => array( '"abc', '"abc"' ),
+			'string escaped newline'                 => array( '"a\\A b"', '"a\\A b"' ),
+			'string escaped carriage return'         => array( '"a\\D b"', '"a\\D b"' ),
+			'string escaped form feed'               => array( '"a\\C b"', '"a\\C b"' ),
+			'bad string'                             => array( "'a\nb", "\"\n b" ),
+			'url'                                    => array( 'url( a )', 'url(a)' ),
+			'url empty'                              => array( 'url()', 'url()' ),
+			'url escaped parenthesis'                => array( 'url(a\\29 b)', 'url(a\\29 b)' ),
+			'url escaped space'                      => array( 'url(a\\20 b)', 'url(a\\20 b)' ),
+			'url escaped quote'                      => array( 'url(a\\"b)', 'url(a\\22 b)' ),
+			'url escaped backslash'                  => array( 'url(a\\\\b)', 'url(a\\5C b)' ),
+			'url escaped control'                    => array( 'url(a\\1 b)', 'url(a\\1 b)' ),
+			'url escaped newline'                    => array( 'url(a\\A b)', 'url(a\\A b)' ),
+			'url ampersand'                          => array( 'url(a&b)', 'url(a\\26 b)' ),
+			'url NUL'                                => array( "url(a\x00b)", "url(a\u{FFFD}b)" ),
+			'url unterminated'                       => array( 'url(a', 'url(a)' ),
+			'url function with a string'             => array( "url( 'a')", 'url( "a")' ),
+			'bad url'                                => array( 'url(a b)', 'url(()' ),
+			'number'                                 => array( '+.5e-3', '+.5e-3' ),
+			'percentage'                             => array( '-1.5%', '-1.5%' ),
+			'dimension'                              => array( '1.5e3PX', '1.5e3PX' ),
+			'dimension unit escape'                  => array( '1\\2D ', '1\\2D ' ),
+			'dimension unit read as exponent'        => array( '1\\65 3', '1\\65 3' ),
+			'dimension unit read as signed exponent' => array( '1\\45 -3', '1\\45 -3' ),
+			'dimension unit e'                       => array( '1e', '1e' ),
+			'backslash delim keeps newline'          => array( "a\\\nb", "a\\\n b" ),
+			'delim'                                  => array( '!', '!' ),
+			'CDO and CDC'                            => array( '<!-- -->', '<!-- -->' ),
+			'punctuation'                            => array( 'a:b;c,d', 'a:b;c,d' ),
+		);
+	}
+
+	/**
+	 * Tests that serialize() closes blocks still open at the end, in reverse order.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_open_blocks
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_open_blocks_are_closed( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+	}
+
+	/**
+	 * Data provider for test_open_blocks_are_closed().
+	 *
+	 * @return array[]
+	 */
+	public static function data_open_blocks(): array {
+		return array(
+			'function'               => array( 'calc(1px', 'calc(1px)' ),
+			'nested blocks'          => array( 'a(b[c{d', 'a(b[c{d}])' ),
+			'closed block'           => array( '(a)', '(a)' ),
+			'mismatched closer'      => array( '(]', '(])' ),
+			'closer without a block' => array( ')', ')' ),
+			'brace'                  => array( '{', '{}' ),
+			'function with a string' => array( 'url("a"', 'url("a")' ),
+			'inner block closed'     => array( 'a((b)', 'a((b))' ),
+		);
+	}
+
+	/**
+	 * Tests that the hash type flag is preserved.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_hash_flag_round_trips(): void {
+		foreach ( array( '#\\31 a', '#1a', '#a1', '#-1', '#--' ) as $css ) {
+			$tokens     = self::tokenize( $css );
+			$serialized = WP_CSS_Token_Serializer::serialize( $tokens );
+			$reparsed   = self::tokenize( $serialized );
+
+			$this->assertCount( 1, $reparsed, "{$css} must serialize as one token." );
+			$this->assertSame( $tokens[0]->get_value(), $reparsed[0]->get_value(), "The value of {$css} changed." );
+			$this->assertSame( $tokens[0]->get_flag(), $reparsed[0]->get_flag(), "The type flag of {$css} changed." );
+		}
+	}
+
+	/**
+	 * Tests that serializing the corpus round-trips and is idempotent.
+	 *
+	 * The output must read as the input tokens, except that comments are dropped,
+	 * whitespace runs are collapsed, and blocks still open are closed.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_corpus
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_corpus_round_trips( string $css ): void {
+		$serialized = WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) );
+
+		$expected = self::significant_tokens( $css );
+		$actual   = self::significant_tokens( $serialized );
+		$closers  = array_splice( $actual, count( $expected ) );
+
+		$this->assertSame( $expected, $actual, 'The output must read as the same tokens.' );
+		foreach ( $closers as $closer ) {
+			$this->assertContains(
+				$closer[0],
+				array( WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE ),
+				'Only block closers may follow the input tokens.'
+			);
+		}
+		$this->assertSame( $serialized, WP_CSS_Token_Serializer::serialize( self::tokenize( $serialized ) ), 'Serialization must be idempotent.' );
+	}
+
+	/**
+	 * Data provider for test_corpus_round_trips().
+	 *
+	 * @return array[]
+	 */
+	public static function data_corpus(): array {
+		$cases = json_decode( file_get_contents( DIR_TESTDATA . '/css-api/css-test-cases.json' ), true );
+		return array_map(
+			static function ( array $test_case ): array {
+				return array( $test_case['css'] );
+			},
+			$cases
+		);
+	}
+
+	/**
+	 * Tokenizes CSS.
+	 *
+	 * @param string $css CSS text.
+	 * @return WP_CSS_Token[] Tokens.
+	 */
+	private static function tokenize( string $css ): array {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$tokens    = array();
+		while ( $processor->next_token() ) {
+			$tokens[] = $processor->get_token();
+		}
+		return $tokens;
+	}
+
+	/**
+	 * Tokenizes CSS for comparison: comments are dropped, and each run of
+	 * whitespace and comments that includes whitespace is one whitespace token.
+	 *
+	 * @param string $css CSS text.
+	 * @return array[] Type, flag, value and unit of each token.
+	 */
+	private static function significant_tokens( string $css ): array {
+		$tokens = array();
+		foreach ( self::tokenize( $css ) as $token ) {
+			$type = $token->get_type();
+			if ( WP_CSS_Token_Processor::TOKEN_COMMENT === $type ) {
+				continue;
+			}
+			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE === $type ) {
+				if ( array( $type ) !== end( $tokens ) ) {
+					$tokens[] = array( $type );
+				}
+				continue;
+			}
+			$tokens[] = array( $type, $token->get_flag(), $token->get_value(), $token->get_unit() );
+		}
+		return $tokens;
+	}
 }

From 34588608d023eb82abf16dbc14b4aa69c6414b61 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 20:34:10 +0400
Subject: [PATCH 16/77] Document why comment tokens are kept
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CSS Syntax 3 §9 allows a tokenizer to preserve comments when they have no effect on parsing. The processor emits them so callers can find comments by byte offset.
---
 .../css-api/class-wp-css-token-processor.php    | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 87c8b022c74c9..1d9e2ad7b4246 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -85,8 +85,21 @@ class WP_CSS_Token_Processor {
 	 * @see https://www.w3.org/TR/css-syntax-3/#tokenization
 	 */
 	public const TOKEN_WHITESPACE = 'whitespace-token';
-	public const TOKEN_COMMENT    = 'comment';
-	public const TOKEN_STRING     = 'string-token';
+
+	/**
+	 * Comment tokens, such as `/* a *\/`.
+	 *
+	 * The specification's tokenizer produces no comment tokens. This processor
+	 * does, so callers can find comments by their byte offsets. CSS Syntax
+	 * Level 3 §9 allows this:
+	 *
+	 * > Implementations may preserve the contents of comments and their location in the token stream.
+	 * > If they do, this preserved information must have no effect on the parsing step.
+	 *
+	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
+	 */
+	public const TOKEN_COMMENT = 'comment';
+	public const TOKEN_STRING  = 'string-token';
 
 	/**
 	 * BAD-STRING tokens occur when a string contains an unescaped newline.

From 47206d92f2f255db7a01c960e7f8e2a55ce2d973 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 21:06:49 +0400
Subject: [PATCH 17/77] Escape CR and FF in strings instead of normalizing them

serialize_string() replaced CR, CRLF and FF in its argument with LF, as if the argument were CSS source. Its output is escaped and never preprocessed, so the replacement changed the value: a string token written from "a\D b" read back with a newline. CR and FF are now written as \D and \C, so the string reads back as the same value; NULL still becomes U+FFFD. A caller that wants normalized line endings normalizes before calling.

serialize() writes string tokens with serialize_string() again, and the private quote_string() is removed.
---
 .../css-api/class-wp-css-token-serializer.php | 32 +++-----------
 .../tests/css-api/wpCssTokenSerializer.php    | 43 +++++--------------
 2 files changed, 16 insertions(+), 59 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index ac4f4d23dc870..a49c7dac836c3 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -307,7 +307,7 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 					: '#' . self::escape_name_code_points( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_STRING:
-				return self::quote_string( $value );
+				return self::serialize_string( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_URL:
 				return 'url(' . self::serialize_url_value( $value ) . ')';
@@ -431,6 +431,9 @@ public static function serialize_ident( string $value ): string {
 	 * or may be complicated for rudimentary CSS or HTML processors to handle
 	 * are encoded using Unicode escape sequences.
 	 *
+	 * The string reads back as the same value, except that NULL becomes U+FFFD.
+	 * Line endings are not normalized: CR and FF are escaped as `\D ` and `\C `.
+	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 *
 	 * @since 7.2.0
@@ -439,31 +442,6 @@ public static function serialize_ident( string $value ): string {
 	 * @return string Serialized quoted CSS string text.
 	 */
 	public static function serialize_string( string $value ): string {
-		// Normalize newlines. https://www.w3.org/TR/css-syntax-3/#input-preprocessing
-		$value = strtr(
-			$value,
-			array(
-				"\r\n" => "\n",
-				"\r"   => "\n",
-				"\f"   => "\n",
-			)
-		);
-
-		return self::quote_string( $value );
-	}
-
-	/**
-	 * Creates a quoted CSS string from a decoded value without normalizing newlines.
-	 *
-	 * A CR or FF in a token value comes from an escape such as `\D `, so it is
-	 * escaped, not written as a newline.
-	 *
-	 * @since 7.2.0
-	 *
-	 * @param string $value Decoded string value to encode as a quoted CSS string.
-	 * @return string Serialized quoted CSS string text.
-	 */
-	private static function quote_string( string $value ): string {
 		$value   = wp_scrub_utf8( $value );
 		$escaped = strtr(
 			$value,
@@ -471,7 +449,7 @@ private static function quote_string( string $value ): string {
 				// Escape existing backslashes to prevent unintentional escapes in result.
 				'\\' => '\\5C ',
 
-				// Pre-processing replaces NULLs. Replace as necessary.
+				// CSS cannot represent NULL; preprocessing replaces it with U+FFFD.
 				"\0" => "\u{FFFD}",
 
 				// Newlines must be escaped in CSS strings.
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 016d4626a5a2a..1bc1bd758cee0 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -16,27 +16,14 @@ class Tests_CssApi_WpCssTokenSerializer extends WP_UnitTestCase {
 	public function test_string_escaping( string $input, string $expected ): void {
 		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
 
-		/**
-		 * Ensure that a single, equivalent CSS string is produced.
-		 *
-		 * CSS pre-processing normalization is applied to the input to ensure
-		 * a match can be found.
-		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+		/*
+		 * Ensure that a single CSS string with the same value is produced.
+		 * CSS cannot represent NULL, which becomes U+FFFD.
 		 */
 		$processor = WP_CSS_Token_Processor::create( WP_CSS_Token_Serializer::serialize_string( $input ) );
 		$processor->next_token();
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$expected_decoded_value = strtr(
-			$input,
-			array(
-				"\r\n" => "\n",
-				"\r"   => "\n",
-				"\f"   => "\n",
-				"\0"   => '�',
-			)
-		);
-		$this->assertSame( $expected_decoded_value, $processor->get_token_value() );
+		$this->assertSame( str_replace( "\0", '�', $input ), $processor->get_token_value() );
 		$this->assertFalse( $processor->next_token() );
 	}
 
@@ -64,11 +51,11 @@ public static function data_string_escaping(): array {
 			// NULL byte → U+FFFD replacement character.
 			'null byte'               => array( "a\0b", '"a�b"' ),
 
-			// Newline normalization — all variants become \A escape.
+			// Newlines are escaped as they are; CR and FF are not normalized to LF.
 			'LF'                      => array( "a\nb", '"a\A b"' ),
-			'CR'                      => array( "a\rb", '"a\A b"' ),
-			'CRLF as single escape'   => array( "a\r\nb", '"a\A b"' ),
-			'form feed'               => array( "a\fb", '"a\A b"' ),
+			'CR'                      => array( "a\rb", '"a\D b"' ),
+			'CRLF'                    => array( "a\r\nb", '"a\D \A b"' ),
+			'form feed'               => array( "a\fb", '"a\C b"' ),
 
 			// HTML-problematic characters.
 			'HTML characters < > &'   => array( 'a<b>c&d', '"a\3C b\3E c\26 d"' ),
@@ -99,7 +86,7 @@ public function test_docblock_example(): void {
 	 */
 	public function test_mixed_newlines(): void {
 		$input    = "line1\nline2\rline3\r\nline4\fline5";
-		$expected = '"line1\A line2\A line3\A line4\A line5"';
+		$expected = '"line1\A line2\D line3\D \A line4\C line5"';
 
 		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
 	}
@@ -126,16 +113,7 @@ public function test_ident( string $input, string $expected ): void {
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
 
-		$expected_decoded_value = strtr(
-			$input,
-			array(
-				"\r\n" => "\n",
-				"\r"   => "\n",
-				"\f"   => "\n",
-				"\0"   => '�',
-			)
-		);
-		$this->assertSame( $expected_decoded_value, $processor->get_token_value() );
+		$this->assertSame( str_replace( "\0", '�', $input ), $processor->get_token_value() );
 		$this->assertFalse( $processor->next_token() );
 	}
 
@@ -167,6 +145,7 @@ public static function data_ident(): Generator {
 		yield 'Multiple spaces within' => array( 'a b c', 'a\\20 b\\20 c' );
 		yield 'Tab within' => array( "has\ttab", 'has\\9 tab' );
 		yield 'Newline within' => array( "has\nnewline", 'has\\A newline' );
+		yield 'Carriage return within' => array( "has\rreturn", 'has\\D return' );
 		yield 'NULL byte within' => array( "has\0null", 'has�null' );
 		yield 'DEL within' => array( "has\x7Fdelete", 'has\\7F delete' );
 

From 2626801d0766b35eeefd4332d1865b65c5f772e8 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 21:07:32 +0400
Subject: [PATCH 18/77] Do not spell CDO or CDC from other tokens when
 serializing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CSS Syntax 3 §9 table compares token types in pairs. It misses two sequences that the tokenizer reads as a CDO or CDC token: `<`, `!` and a token that starts with `--` spell `<!--`, and an ident `--` followed by `>` spells `-->`. So `<!/**/--x` was written as `<!--x` (CDO, ident `x`) and `--/**/>` as `-->`. An empty comment is now written before the last token of each, so the output reads as the same tokens.
---
 .../css-api/class-wp-css-token-serializer.php | 33 ++++++++++++++---
 .../tests/css-api/wpCssTokenSerializer.php    | 37 +++++++++++++++++++
 2 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index a49c7dac836c3..c4d4c780ba440 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -212,6 +212,12 @@ class WP_CSS_Token_Serializer {
 	 * Comments are not preserved, so an empty CSS comment is written between
 	 * the tokens of a marked pair when no whitespace is between them.
 	 *
+	 * The table compares token types in pairs, so it misses two sequences that
+	 * the tokenizer reads as a CDO or CDC token: `<`, `!` and a token that
+	 * starts with `--`, which spell `<!--`, and an ident `--` followed by `>`,
+	 * which spell `-->`. An empty CSS comment is written before the last token
+	 * of each.
+	 *
 	 * Bad-string and bad-url tokens have no value. A bad string is written as
 	 * a quote followed by a newline, where the tokenizer ends one; a bad url is
 	 * written as `url(()`.
@@ -243,6 +249,10 @@ public static function serialize( iterable $tokens ): string {
 		// Pair key of the last token written, or the whitespace type after a space.
 		$last = null;
 
+		// Text of the last two tokens written, or a space after whitespace.
+		$last_text        = '';
+		$before_last_text = '';
+
 		foreach ( $tokens as $token ) {
 			$type = $token->get_type();
 
@@ -252,19 +262,30 @@ public static function serialize( iterable $tokens ): string {
 
 			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE === $type ) {
 				if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $last ) {
-					$output .= ' ';
-					$last    = WP_CSS_Token_Processor::TOKEN_WHITESPACE;
+					$output          .= ' ';
+					$last             = WP_CSS_Token_Processor::TOKEN_WHITESPACE;
+					$before_last_text = $last_text;
+					$last_text        = ' ';
 				}
 				continue;
 			}
 
-			$key = WP_CSS_Token_Processor::TOKEN_DELIM === $type ? $token->get_value() : $type;
-			if ( null !== $last && isset( self::MARKED_PAIRS[ $last ] ) && in_array( $key, self::MARKED_PAIRS[ $last ], true ) ) {
+			$key  = WP_CSS_Token_Processor::TOKEN_DELIM === $type ? $token->get_value() : $type;
+			$text = self::serialize_token( $token );
+
+			if (
+				( null !== $last && isset( self::MARKED_PAIRS[ $last ] ) && in_array( $key, self::MARKED_PAIRS[ $last ], true ) ) ||
+				// The table misses `<`, `!`, `--x`, which reads as `<!--`, and `--`, `>`, which reads as `-->`.
+				( '<' === $before_last_text && '!' === $last_text && 0 === strncmp( $text, '--', 2 ) ) ||
+				( '--' === $last_text && '>' === $text )
+			) {
 				$output .= '/**/';
 			}
-			$last = $key;
 
-			$output .= self::serialize_token( $token );
+			$output          .= $text;
+			$last             = $key;
+			$before_last_text = $last_text;
+			$last_text        = $text;
 
 			if ( isset( self::BLOCK_CLOSERS[ $type ] ) ) {
 				$closers[] = self::BLOCK_CLOSERS[ $type ];
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 1bc1bd758cee0..f4ce9281c9081 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -376,6 +376,43 @@ public static function data_token_serialization(): array {
 		);
 	}
 
+	/**
+	 * Tests that serialize() does not spell a CDO or CDC token from other tokens.
+	 *
+	 * The table in CSS Syntax Level 3 §9 compares token pairs by type. It does
+	 * not cover `<`, `!` and a token that starts with `--`, which spell `<!--`,
+	 * or an ident `--` followed by `>`, which spell `-->`.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_cdo_and_cdc_sequences
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_cdo_and_cdc_are_not_spelled( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+		$this->assertSame( self::significant_tokens( $css ), self::significant_tokens( $expected ), 'The output must read as the same tokens.' );
+	}
+
+	/**
+	 * Data provider for test_cdo_and_cdc_are_not_spelled().
+	 *
+	 * @return array[]
+	 */
+	public static function data_cdo_and_cdc_sequences(): array {
+		return array(
+			'< ! ident'                 => array( '<!/**/--x', '<!/**/--x' ),
+			'< ! ident --'              => array( '<!/**/--', '<!/**/--' ),
+			'< ! function'              => array( '<!/**/--x()', '<!/**/--x()' ),
+			'< ! CDC'                   => array( '<!/**/-->', '<!/**/-->' ),
+			'ident -- >'                => array( '--/**/>', '--/**/>' ),
+			'< space ! ident'           => array( '< !/**/--x', '< !--x' ),
+			'! ident without <'         => array( 'a!/**/--x', 'a!--x' ),
+			'< ! ident without --'      => array( '<!/**/x', '<!x' ),
+			'ident ending in -- then >' => array( 'a--/**/>', 'a-->' ),
+			'ident -- space >'          => array( '-- >', '-- >' ),
+		);
+	}
+
 	/**
 	 * Tests that serialize() closes blocks still open at the end, in reverse order.
 	 *

From 08f3485b3bbae147b3894d57d074c6ee559e9423 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 22:07:54 +0400
Subject: [PATCH 19/77] Make the token serializer internal

A token list can hold tokens that have no valid CSS form, so the public way to write CSS will be at the declaration level, where the style attribute processor exposes only valid declarations. WP_CSS_Token_Serializer is marked @access private; its methods stay public so other core classes can call them.

serialize_ident() and serialize_string() had no caller outside the serializer. They become escape_ident(), public for property names, and the private escape_string(); url values use the private escape_url(), which now returns the whole url token. CSSOM defines "serialize an identifier" and "serialize a string" with a different escape set, so the new names avoid suggesting those algorithms.

The string escaping tests now run through serialize(). The class documentation states what the output guarantees: it parses to the same CSS as the tokens. It is not always valid CSS: bad-string and bad-url tokens are written as the same bad tokens.
---
 .../css-api/class-wp-css-token-serializer.php |  86 +++++++-------
 .../tests/css-api/wpCssTokenSerializer.php    | 105 +++++++-----------
 2 files changed, 84 insertions(+), 107 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index c4d4c780ba440..2c451c42d75aa 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -8,16 +8,16 @@
  */
 
 /**
- * Serializes CSS tokens and values as CSS text.
+ * Writes tokens read by WP_CSS_Token_Processor as CSS text.
  *
- * serialize() writes tokens read by WP_CSS_Token_Processor. serialize_ident()
- * and serialize_string() write a plain PHP string as an identifier or as a
- * quoted string.
+ * This class is not a public API. Its methods are public so other core
+ * classes can call them.
  *
- * Output is valid CSS that reads as the same tokens. Which characters are
+ * The output parses to the same CSS as the tokens. Which characters are
  * escaped may change.
  *
  * @since 7.2.0
+ * @access private
  *
  * @see WP_CSS_Token_Processor
  */
@@ -147,7 +147,7 @@ class WP_CSS_Token_Serializer {
 	);
 
 	/**
-	 * Serializes tokens as CSS text that reads as the same tokens.
+	 * Serializes tokens as CSS text that parses to the same CSS.
 	 *
 	 * This follows CSS Syntax Level 3 §9 Serialization:
 	 *
@@ -220,7 +220,9 @@ class WP_CSS_Token_Serializer {
 	 *
 	 * Bad-string and bad-url tokens have no value. A bad string is written as
 	 * a quote followed by a newline, where the tokenizer ends one; a bad url is
-	 * written as `url(()`.
+	 * written as `url(()`. Both re-tokenize as the same bad token. If a later
+	 * step replaces the newline after a bad string with a space, the quote
+	 * starts a string that includes the text after it.
 	 *
 	 * Strings and urls cut off by the end of the input are written closed.
 	 * Blocks still open at the end are closed in reverse order, so `a(b[c` is
@@ -314,24 +316,24 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 
 		switch ( $token->get_type() ) {
 			case WP_CSS_Token_Processor::TOKEN_IDENT:
-				return self::serialize_ident( $value );
+				return self::escape_ident( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_FUNCTION:
-				return self::serialize_ident( $value ) . '(';
+				return self::escape_ident( $value ) . '(';
 
 			case WP_CSS_Token_Processor::TOKEN_AT_KEYWORD:
-				return '@' . self::serialize_ident( $value );
+				return '@' . self::escape_ident( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_HASH:
 				return WP_CSS_Token_Processor::HASH_TOKEN_ID === $token->get_flag()
-					? '#' . self::serialize_ident( $value )
-					: '#' . self::escape_name_code_points( $value );
+					? '#' . self::escape_ident( $value )
+					: '#' . self::escape_name( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_STRING:
-				return self::serialize_string( $value );
+				return self::escape_string( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_URL:
-				return 'url(' . self::serialize_url_value( $value ) . ')';
+				return self::escape_url( $value );
 
 			case WP_CSS_Token_Processor::TOKEN_NUMBER:
 				return $value;
@@ -340,7 +342,7 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 				return $value . '%';
 
 			case WP_CSS_Token_Processor::TOKEN_DIMENSION:
-				$unit = self::serialize_ident( $token->get_unit() );
+				$unit = self::escape_ident( $token->get_unit() );
 				// A unit that starts with `e`, an optional `-`, and a digit would read as an exponent.
 				if ( 1 === preg_match( '/^[eE]-?[0-9]/', $unit ) ) {
 					$unit = sprintf( '\\%X ', ord( $unit[0] ) ) . substr( $unit, 1 );
@@ -356,25 +358,24 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	}
 
 	/**
-	 * Serializes a plain PHP string as CSS identifier text.
+	 * Escapes a decoded value as identifier text.
 	 *
-	 * Characters not valid in CSS identifiers are hex-escaped. This uses
-	 * the same safety escaping as {@see WP_CSS_Token_Serializer::serialize_string()} for HTML
-	 * and CSS-sensitive characters, plus escaping of whitespace and other
-	 * characters not permitted in idents.
+	 * Characters not valid in CSS identifiers are hex-escaped, as are the
+	 * characters escape_string() escapes for HTML and CSS.
 	 *
-	 * An empty string serializes to an empty string. Callers that require an
-	 * ident token must reject an empty value.
+	 * An empty value returns an empty string. Callers that require an ident
+	 * token must reject an empty value.
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
 	 * @since 7.2.0
+	 * @access private
 	 *
-	 * @param string $value Decoded string value to encode as a CSS identifier.
-	 * @return string Serialized CSS identifier text.
+	 * @param string $value Decoded value.
+	 * @return string Identifier text.
 	 */
-	public static function serialize_ident( string $value ): string {
+	public static function escape_ident( string $value ): string {
 		$value  = wp_scrub_utf8( $value );
 		$result = '';
 		$length = strlen( $value );
@@ -441,16 +442,11 @@ public static function serialize_ident( string $value ): string {
 	}
 
 	/**
-	 * Creates a quoted CSS string from a plain PHP string value.
+	 * Escapes a decoded value as a quoted string.
 	 *
-	 * Example:
-	 *     $value = 'CSS & a "<style>" tag\'s strings';
-	 *     $css_string = WP_CSS_Token_Serializer::serialize_string( $value );
-	 *     echo "<style>*::before { content: {$css_string}; }</style>";
-	 *
-	 * CSS strings are quoted, and many characters that are problematic in HTML
-	 * or may be complicated for rudimentary CSS or HTML processors to handle
-	 * are encoded using Unicode escape sequences.
+	 * Many characters that are problematic in HTML or may be complicated for
+	 * rudimentary CSS or HTML processors to handle are encoded using Unicode
+	 * escape sequences.
 	 *
 	 * The string reads back as the same value, except that NULL becomes U+FFFD.
 	 * Line endings are not normalized: CR and FF are escaped as `\D ` and `\C `.
@@ -459,10 +455,10 @@ public static function serialize_ident( string $value ): string {
 	 *
 	 * @since 7.2.0
 	 *
-	 * @param string $value Decoded string value to encode as a quoted CSS string.
-	 * @return string Serialized quoted CSS string text.
+	 * @param string $value Decoded value.
+	 * @return string Quoted string text.
 	 */
-	public static function serialize_string( string $value ): string {
+	private static function escape_string( string $value ): string {
 		$value   = wp_scrub_utf8( $value );
 		$escaped = strtr(
 			$value,
@@ -502,7 +498,7 @@ public static function serialize_string( string $value ): string {
 	 *
 	 * Letters, digits, `-`, `_` and code points U+0080 and above are written
 	 * as they are; every other code point is hex-escaped. Unlike
-	 * serialize_ident(), a leading digit or `-` is not escaped, as the name of
+	 * escape_ident(), a leading digit or `-` is not escaped, as the name of
 	 * a hash token with the "unrestricted" flag requires.
 	 *
 	 * @since 7.2.0
@@ -510,7 +506,7 @@ public static function serialize_string( string $value ): string {
 	 * @param string $value Decoded name.
 	 * @return string Escaped name.
 	 */
-	private static function escape_name_code_points( string $value ): string {
+	private static function escape_name( string $value ): string {
 		$value  = wp_scrub_utf8( $value );
 		$result = '';
 		$length = strlen( $value );
@@ -542,20 +538,20 @@ private static function escape_name_code_points( string $value ): string {
 	}
 
 	/**
-	 * Escapes the value of a url token.
+	 * Escapes a decoded value as an unquoted url.
 	 *
 	 * The code points an unquoted url cannot contain are hex-escaped: quotes,
 	 * parentheses, `\`, whitespace and non-printable code points. So are the
-	 * code points serialize_string() escapes for HTML and CSS: `< > & , ; { }`.
+	 * code points escape_string() escapes for HTML and CSS: `< > & , ; { }`.
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @since 7.2.0
 	 *
-	 * @param string $value Decoded url value.
-	 * @return string Escaped url value, without `url(` and `)`.
+	 * @param string $value Decoded value.
+	 * @return string Url text, including `url(` and `)`.
 	 */
-	private static function serialize_url_value( string $value ): string {
+	private static function escape_url( string $value ): string {
 		$value  = wp_scrub_utf8( $value );
 		$result = '';
 		$length = strlen( $value );
@@ -580,6 +576,6 @@ private static function serialize_url_value( string $value ): string {
 			$result .= $value[ $i ];
 		}
 
-		return $result;
+		return "url({$result})";
 	}
 }
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index f4ce9281c9081..084d339f407f3 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -9,99 +9,84 @@
  */
 class Tests_CssApi_WpCssTokenSerializer extends WP_UnitTestCase {
 	/**
+	 * Tests that serialize() escapes a string token again from its decoded value.
+	 *
+	 * @ticket 65738
 	 * @dataProvider data_string_escaping
 	 *
-	 * @covers ::serialize_string
+	 * @covers ::serialize
 	 */
-	public function test_string_escaping( string $input, string $expected ): void {
-		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
-
-		/*
-		 * Ensure that a single CSS string with the same value is produced.
-		 * CSS cannot represent NULL, which becomes U+FFFD.
-		 */
-		$processor = WP_CSS_Token_Processor::create( WP_CSS_Token_Serializer::serialize_string( $input ) );
-		$processor->next_token();
-		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$this->assertSame( str_replace( "\0", '�', $input ), $processor->get_token_value() );
-		$this->assertFalse( $processor->next_token() );
+	public function test_string_escaping( string $css, string $expected ): void {
+		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize( self::tokenize( $css ) ) );
+		$this->assertSame( self::significant_tokens( $css ), self::significant_tokens( $expected ), 'The output must read as the same tokens.' );
 	}
 
 	/**
-	 * Data provider for string escaping cases.
+	 * Data provider for test_string_escaping().
 	 *
-	 * @return array
+	 * @return array[]
 	 */
 	public static function data_string_escaping(): array {
 		return array(
 			// Passthrough — no escaping needed, only quoting.
-			'empty string'            => array( '', '""' ),
-			'simple ASCII'            => array( 'Arial', '"Arial"' ),
-			'spaces preserved'        => array( 'Exo 2', '"Exo 2"' ),
-			'leading/trailing spaces' => array( '  Arial  ', '"  Arial  "' ),
-			'whitespace-only'         => array( '   ', '"   "' ),
-			'numbers pass through'    => array( '12345', '"12345"' ),
-			'non-ASCII passthrough'   => array( 'café', '"café"' ),
+			'empty string'            => array( "''", '""' ),
+			'simple ASCII'            => array( "'Arial'", '"Arial"' ),
+			'spaces preserved'        => array( "'Exo 2'", '"Exo 2"' ),
+			'leading/trailing spaces' => array( "'  Arial  '", '"  Arial  "' ),
+			'whitespace-only'         => array( "'   '", '"   "' ),
+			'numbers pass through'    => array( "'12345'", '"12345"' ),
+			'non-ASCII passthrough'   => array( "'café'", '"café"' ),
 
 			// Backslash escaping — must happen first to prevent double-escaping.
-			'backslash'               => array( 'Back\\Slash', '"Back\5C Slash"' ),
-			'double backslash'        => array( '\\\\', '"\5C \5C "' ),
-			'backslash before quote'  => array( "a\\'b", '"a\5C \27 b"' ),
+			'backslash'               => array( '"Back\\\\Slash"', '"Back\\5C Slash"' ),
+			'double backslash'        => array( '"\\\\\\\\"', '"\\5C \\5C "' ),
+			'backslash before quote'  => array( '"a\\\\\'b"', '"a\\5C \\27 b"' ),
 
-			// NULL byte → U+FFFD replacement character.
-			'null byte'               => array( "a\0b", '"a�b"' ),
+			// NULL → U+FFFD replacement character.
+			'null byte'               => array( "\"a\x00b\"", '"a�b"' ),
+			'zero escape'             => array( '"a\\0 b"', '"a�b"' ),
 
-			// Newlines are escaped as they are; CR and FF are not normalized to LF.
-			'LF'                      => array( "a\nb", '"a\A b"' ),
-			'CR'                      => array( "a\rb", '"a\D b"' ),
-			'CRLF'                    => array( "a\r\nb", '"a\D \A b"' ),
-			'form feed'               => array( "a\fb", '"a\C b"' ),
+			// Escaped newlines keep their code points; CR and FF are not normalized to LF.
+			'LF'                      => array( '"a\\A b"', '"a\\A b"' ),
+			'CR'                      => array( '"a\\D b"', '"a\\D b"' ),
+			'CRLF'                    => array( '"a\\D \\A b"', '"a\\D \\A b"' ),
+			'form feed'               => array( '"a\\C b"', '"a\\C b"' ),
 
 			// HTML-problematic characters.
-			'HTML characters < > &'   => array( 'a<b>c&d', '"a\3C b\3E c\26 d"' ),
+			'HTML characters < > &'   => array( '"a<b>c&d"', '"a\\3C b\\3E c\\26 d"' ),
 
 			// CSS-problematic characters.
-			'CSS syntax , ; { }'      => array( 'a,b;c{d}', '"a\2C b\3B c\7B d\7D "' ),
-			'single quote'            => array( "CSS's strings", '"CSS\27 s strings"' ),
-			'double quote'            => array( 'Say "Hi"', '"Say \22 Hi\22 "' ),
+			'CSS syntax , ; { }'      => array( '"a,b;c{d}"', '"a\\2C b\\3B c\\7B d\\7D "' ),
+			'single quote'            => array( '"CSS\'s strings"', '"CSS\\27 s strings"' ),
+			'double quote'            => array( '\'Say "Hi"\'', '"Say \\22 Hi\\22 "' ),
 		);
 	}
 
 	/**
-	 * Tests the example from the class docblock.
+	 * Tests the example in the serialize() docblock.
 	 *
-	 * @covers ::serialize_string
-	 */
-	public function test_docblock_example(): void {
-		$value    = 'CSS & a "<style>" tag\'s strings';
-		$expected = '"CSS \26  a \22 \3C style\3E \22  tag\27 s strings"';
-
-		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $value ) );
-	}
-
-	/**
-	 * Tests a string containing mixed newline types.
+	 * @ticket 65738
 	 *
-	 * @covers ::serialize_string
+	 * @covers ::serialize
 	 */
-	public function test_mixed_newlines(): void {
-		$input    = "line1\nline2\rline3\r\nline4\fline5";
-		$expected = '"line1\A line2\D line3\D \A line4\C line5"';
-
-		$this->assertSame( $expected, WP_CSS_Token_Serializer::serialize_string( $input ) );
+	public function test_docblock_example(): void {
+		$this->assertSame(
+			'url(a\\26 b) calc(1px + 2px)',
+			WP_CSS_Token_Serializer::serialize( self::tokenize( 'url( a&b ) calc(1px  +  2px' ) )
+		);
 	}
 
 	/**
-	 * Tests WP_CSS_Token_Serializer::serialize_ident() serializes CSS identifiers.
+	 * Tests WP_CSS_Token_Serializer::escape_ident() escapes CSS identifiers.
 	 *
 	 * @ticket 65738
 	 *
 	 * @dataProvider data_ident
 	 *
-	 * @covers ::serialize_ident
+	 * @covers ::escape_ident
 	 */
 	public function test_ident( string $input, string $expected ): void {
-		$serialized = WP_CSS_Token_Serializer::serialize_ident( $input );
+		$serialized = WP_CSS_Token_Serializer::escape_ident( $input );
 		$this->assertSame( $expected, $serialized );
 
 		$processor = WP_CSS_Token_Processor::create( $serialized );
@@ -118,7 +103,7 @@ public function test_ident( string $input, string $expected ): void {
 	}
 
 	/**
-	 * Data provider for serialize_ident() tests.
+	 * Data provider for test_ident().
 	 */
 	public static function data_ident(): Generator {
 		yield 'Empty identifier' => array( '', '' );
@@ -343,11 +328,7 @@ public static function data_token_serialization(): array {
 			'hash unrestricted escape'               => array( '#1\\:', '#1\\3A ' ),
 			'hash unrestricted hyphen'               => array( '#-', '#-' ),
 			'string'                                 => array( "'a\"b'", '"a\\22 b"' ),
-			'string ampersand'                       => array( '"a&b"', '"a\\26 b"' ),
 			'string unterminated'                    => array( '"abc', '"abc"' ),
-			'string escaped newline'                 => array( '"a\\A b"', '"a\\A b"' ),
-			'string escaped carriage return'         => array( '"a\\D b"', '"a\\D b"' ),
-			'string escaped form feed'               => array( '"a\\C b"', '"a\\C b"' ),
 			'bad string'                             => array( "'a\nb", "\"\n b" ),
 			'url'                                    => array( 'url( a )', 'url(a)' ),
 			'url empty'                              => array( 'url()', 'url()' ),

From c17769445b0c941b16c8cb64b18fe2f32fdd9049 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 22:08:20 +0400
Subject: [PATCH 20/77] Build identifier escaping on name escaping

escape_ident() repeated escape_name()'s loop with three changes for the first code point. It now handles a lone `-` and a leading digit, or `-` and a digit, and escapes the rest with escape_name(). Output is unchanged: 80,565 generated values of up to five code points escape the same as before.
---
 .../css-api/class-wp-css-token-serializer.php | 69 +++----------------
 1 file changed, 9 insertions(+), 60 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index 2c451c42d75aa..8955f3cfc2799 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -376,69 +376,18 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	 * @return string Identifier text.
 	 */
 	public static function escape_ident( string $value ): string {
-		$value  = wp_scrub_utf8( $value );
-		$result = '';
-		$length = strlen( $value );
-
-		for ( $i = 0; $i < $length; $i++ ) {
-			$byte = ord( $value[ $i ] );
-
-			// NULL → U+FFFD REPLACEMENT CHARACTER.
-			if ( 0x00 === $byte ) {
-				$result .= "\u{FFFD}";
-				continue;
-			}
-
-			// Non-ASCII bytes (≥ 0x80): valid in idents, pass through.
-			if ( $byte >= 0x80 ) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// ASCII letters and underscore: always valid in idents.
-			if (
-				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
-				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
-				0x5F === $byte                         // _
-			) {
-				$result .= $value[ $i ];
-				continue;
-			}
-
-			// Hyphen: valid in idents, but check for hyphen-digit at start.
-			if ( 0x2D === $byte ) {
-				// A hyphen standing alone must be escaped to form an ident token.
-				if ( 0 === $i && 1 === $length ) {
-					$result .= '\\2D ';
-					continue;
-				}
-
-				// Hyphen at position 0 followed by a digit at position 1: escape the digit.
-				if ( 0 === $i && $i + 1 < $length && ord( $value[ $i + 1 ] ) >= 0x30 && ord( $value[ $i + 1 ] ) <= 0x39 ) {
-					$result .= '-';
-					++$i;
-					$result .= sprintf( '\\%X ', ord( $value[ $i ] ) );
-					continue;
-				}
-				$result .= '-';
-				continue;
-			}
-
-			// Digits: valid except at position 0.
-			if ( $byte >= 0x30 && $byte <= 0x39 ) {
-				if ( 0 === $i ) {
-					$result .= sprintf( '\\%X ', $byte );
-				} else {
-					$result .= $value[ $i ];
-				}
-				continue;
-			}
+		// A lone `-` cannot start an identifier.
+		if ( '-' === $value ) {
+			return '\\2D ';
+		}
 
-			// Everything else: hex-escape.
-			$result .= sprintf( '\\%X ', $byte );
+		// Neither can a digit or a `-` followed by a digit, so the digit is escaped.
+		$digit_at = ( isset( $value[0] ) && '-' === $value[0] ) ? 1 : 0;
+		if ( isset( $value[ $digit_at ] ) && $value[ $digit_at ] >= '0' && $value[ $digit_at ] <= '9' ) {
+			return substr( $value, 0, $digit_at ) . sprintf( '\\%X ', ord( $value[ $digit_at ] ) ) . self::escape_name( substr( $value, $digit_at + 1 ) );
 		}
 
-		return $result;
+		return self::escape_name( $value );
 	}
 
 	/**

From 06c6e5d1d62d215db54b78b2da223cd7b91021c5 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Fri, 9 Oct 2026 22:08:46 +0400
Subject: [PATCH 21/77] Fill serializer test gaps

Hash flag round-trips get a data provider, with the expected flag of each input checked on both sides. serialize() is tested with a generator, since it accepts any iterable, and with a DEL delim.
---
 .../tests/css-api/wpCssTokenSerializer.php    | 55 +++++++++++++++----
 1 file changed, 45 insertions(+), 10 deletions(-)

diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 084d339f407f3..ef5e3ab1cfddd 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -352,6 +352,7 @@ public static function data_token_serialization(): array {
 			'dimension unit e'                       => array( '1e', '1e' ),
 			'backslash delim keeps newline'          => array( "a\\\nb", "a\\\n b" ),
 			'delim'                                  => array( '!', '!' ),
+			'DEL delim'                              => array( "a\x7Fb", "a\x7Fb" ),
 			'CDO and CDC'                            => array( '<!-- -->', '<!-- -->' ),
 			'punctuation'                            => array( 'a:b;c,d', 'a:b;c,d' ),
 		);
@@ -428,19 +429,53 @@ public static function data_open_blocks(): array {
 	 * Tests that the hash type flag is preserved.
 	 *
 	 * @ticket 65738
+	 * @dataProvider data_hash_flag_round_trips
 	 *
 	 * @covers ::serialize
 	 */
-	public function test_hash_flag_round_trips(): void {
-		foreach ( array( '#\\31 a', '#1a', '#a1', '#-1', '#--' ) as $css ) {
-			$tokens     = self::tokenize( $css );
-			$serialized = WP_CSS_Token_Serializer::serialize( $tokens );
-			$reparsed   = self::tokenize( $serialized );
-
-			$this->assertCount( 1, $reparsed, "{$css} must serialize as one token." );
-			$this->assertSame( $tokens[0]->get_value(), $reparsed[0]->get_value(), "The value of {$css} changed." );
-			$this->assertSame( $tokens[0]->get_flag(), $reparsed[0]->get_flag(), "The type flag of {$css} changed." );
-		}
+	public function test_hash_flag_round_trips( string $css, string $expected_flag ): void {
+		$tokens     = self::tokenize( $css );
+		$serialized = WP_CSS_Token_Serializer::serialize( $tokens );
+		$reparsed   = self::tokenize( $serialized );
+
+		$this->assertSame( $expected_flag, $tokens[0]->get_flag(), 'The input has the wrong type flag.' );
+		$this->assertCount( 1, $reparsed, 'The hash must serialize as one token.' );
+		$this->assertSame( $tokens[0]->get_value(), $reparsed[0]->get_value(), 'The value changed.' );
+		$this->assertSame( $expected_flag, $reparsed[0]->get_flag(), 'The type flag changed.' );
+	}
+
+	/**
+	 * Data provider for test_hash_flag_round_trips().
+	 *
+	 * @return array[]
+	 */
+	public static function data_hash_flag_round_trips(): array {
+		return array(
+			'id with an escaped digit' => array( '#\\31 a', WP_CSS_Token_Processor::HASH_TOKEN_ID ),
+			'id'                       => array( '#a1', WP_CSS_Token_Processor::HASH_TOKEN_ID ),
+			'id starting with --'      => array( '#--', WP_CSS_Token_Processor::HASH_TOKEN_ID ),
+			'unrestricted digit'       => array( '#1a', WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED ),
+			'unrestricted - and digit' => array( '#-1', WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED ),
+			'unrestricted lone -'      => array( '#-', WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED ),
+		);
+	}
+
+	/**
+	 * Tests that serialize() accepts any iterable, such as a generator.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize
+	 */
+	public function test_serialize_accepts_a_generator(): void {
+		$generator = ( static function ( string $css ): Generator {
+			$processor = WP_CSS_Token_Processor::create( $css );
+			while ( $processor->next_token() ) {
+				yield $processor->get_token();
+			}
+		} )( 'a /* x */ b(' );
+
+		$this->assertSame( 'a b()', WP_CSS_Token_Serializer::serialize( $generator ) );
 	}
 
 	/**

From 74f331034baf15a80962af7dfe7e05ea62687474 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 16:44:38 +0400
Subject: [PATCH 22/77] Escape control characters in strings

String tokens wrote U+0001 to U+001F and U+007F raw, except LF, CR and FF. They now escape every code point in that range, as CSSOM's "serialize a string" does, so a raw tab is written `\9 `. Identifiers, hash names and urls already escaped these code points.
---
 .../css-api/class-wp-css-token-serializer.php | 69 +++++++++----------
 .../tests/css-api/wpCssTokenSerializer.php    |  8 ++-
 2 files changed, 38 insertions(+), 39 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index 8955f3cfc2799..2c195aad2d086 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -393,14 +393,13 @@ public static function escape_ident( string $value ): string {
 	/**
 	 * Escapes a decoded value as a quoted string.
 	 *
-	 * Many characters that are problematic in HTML or may be complicated for
-	 * rudimentary CSS or HTML processors to handle are encoded using Unicode
-	 * escape sequences.
-	 *
-	 * The string reads back as the same value, except that NULL becomes U+FFFD.
-	 * Line endings are not normalized: CR and FF are escaped as `\D ` and `\C `.
+	 * Quotes, `\` and the control characters U+0001 to U+001F and U+007F are
+	 * hex-escaped. So are `< > & , ; { }`, which may be problematic in HTML or
+	 * for rudimentary CSS processors. The string reads back as the same value,
+	 * except that NULL becomes U+FFFD.
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @see https://drafts.csswg.org/cssom/#serialize-a-string
 	 *
 	 * @since 7.2.0
 	 *
@@ -408,38 +407,32 @@ public static function escape_ident( string $value ): string {
 	 * @return string Quoted string text.
 	 */
 	private static function escape_string( string $value ): string {
-		$value   = wp_scrub_utf8( $value );
-		$escaped = strtr(
-			$value,
-			array(
-				// Escape existing backslashes to prevent unintentional escapes in result.
-				'\\' => '\\5C ',
-
-				// CSS cannot represent NULL; preprocessing replaces it with U+FFFD.
-				"\0" => "\u{FFFD}",
-
-				// Newlines must be escaped in CSS strings.
-				"\n" => '\\A ',
-				"\r" => '\\D ',
-				"\f" => '\\C ',
-
-				// Arbitrary characters for Unicode escaping:
-
-				// HTML syntax may be problematic.
-				'<'  => '\\3C ',
-				'>'  => '\\3E ',
-				'&'  => '\\26 ',
-
-				// CSS syntax may be problematic.
-				','  => '\\2C ',
-				';'  => '\\3B ',
-				'{'  => '\\7B ',
-				'}'  => '\\7D ',
-				'"'  => '\\22 ',
-				"'"  => '\\27 ',
-			)
-		);
-		return "\"{$escaped}\"";
+		$value  = wp_scrub_utf8( $value );
+		$result = '';
+		$length = strlen( $value );
+
+		for ( $i = 0; $i < $length; $i++ ) {
+			$byte = ord( $value[ $i ] );
+
+			// CSS cannot represent NULL; preprocessing replaces it with U+FFFD.
+			if ( 0x00 === $byte ) {
+				$result .= "\u{FFFD}";
+				continue;
+			}
+
+			if (
+				$byte < 0x20 ||
+				0x7F === $byte ||
+				false !== strpos( '"\'\\<>&,;{}', $value[ $i ] )
+			) {
+				$result .= sprintf( '\\%X ', $byte );
+				continue;
+			}
+
+			$result .= $value[ $i ];
+		}
+
+		return "\"{$result}\"";
 	}
 
 	/**
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index ef5e3ab1cfddd..9ce2d4e103dc5 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -46,11 +46,17 @@ public static function data_string_escaping(): array {
 			'null byte'               => array( "\"a\x00b\"", '"a�b"' ),
 			'zero escape'             => array( '"a\\0 b"', '"a�b"' ),
 
-			// Escaped newlines keep their code points; CR and FF are not normalized to LF.
+			// Control characters are escaped as code points; CR and FF are not normalized to LF.
 			'LF'                      => array( '"a\\A b"', '"a\\A b"' ),
 			'CR'                      => array( '"a\\D b"', '"a\\D b"' ),
 			'CRLF'                    => array( '"a\\D \\A b"', '"a\\D \\A b"' ),
 			'form feed'               => array( '"a\\C b"', '"a\\C b"' ),
+			'tab'                     => array( "\"a\tb\"", '"a\\9 b"' ),
+			'escaped tab'             => array( '"a\\9 b"', '"a\\9 b"' ),
+			'U+0001'                  => array( "\"a\x01b\"", '"a\\1 b"' ),
+			'U+001F'                  => array( '"a\\1F b"', '"a\\1F b"' ),
+			'delete'                  => array( "\"a\x7Fb\"", '"a\\7F b"' ),
+			'U+0080 is not escaped'   => array( '"a\\80 b"', "\"a\u{80}b\"" ),
 
 			// HTML-problematic characters.
 			'HTML characters < > &'   => array( '"a<b>c&d"', '"a\\3C b\\3E c\\26 d"' ),

From 52216bc98d7e6b2fd40609a321640aede5880356 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 16:45:31 +0400
Subject: [PATCH 23/77] Write hex escapes in lowercase

CSSOM's "escape a character as code point" writes the hex digits in lowercase, so `<` is written `\3c ` instead of `\3C `. CSS reads either case, so the output parses as before.
---
 .../css-api/class-wp-css-token-serializer.php | 12 ++---
 .../tests/css-api/wpCssTokenSerializer.php    | 50 +++++++++----------
 2 files changed, 31 insertions(+), 31 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index 2c195aad2d086..b6d3f8bae2857 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -345,7 +345,7 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 				$unit = self::escape_ident( $token->get_unit() );
 				// A unit that starts with `e`, an optional `-`, and a digit would read as an exponent.
 				if ( 1 === preg_match( '/^[eE]-?[0-9]/', $unit ) ) {
-					$unit = sprintf( '\\%X ', ord( $unit[0] ) ) . substr( $unit, 1 );
+					$unit = sprintf( '\\%x ', ord( $unit[0] ) ) . substr( $unit, 1 );
 				}
 				return $value . $unit;
 
@@ -378,13 +378,13 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	public static function escape_ident( string $value ): string {
 		// A lone `-` cannot start an identifier.
 		if ( '-' === $value ) {
-			return '\\2D ';
+			return '\\2d ';
 		}
 
 		// Neither can a digit or a `-` followed by a digit, so the digit is escaped.
 		$digit_at = ( isset( $value[0] ) && '-' === $value[0] ) ? 1 : 0;
 		if ( isset( $value[ $digit_at ] ) && $value[ $digit_at ] >= '0' && $value[ $digit_at ] <= '9' ) {
-			return substr( $value, 0, $digit_at ) . sprintf( '\\%X ', ord( $value[ $digit_at ] ) ) . self::escape_name( substr( $value, $digit_at + 1 ) );
+			return substr( $value, 0, $digit_at ) . sprintf( '\\%x ', ord( $value[ $digit_at ] ) ) . self::escape_name( substr( $value, $digit_at + 1 ) );
 		}
 
 		return self::escape_name( $value );
@@ -425,7 +425,7 @@ private static function escape_string( string $value ): string {
 				0x7F === $byte ||
 				false !== strpos( '"\'\\<>&,;{}', $value[ $i ] )
 			) {
-				$result .= sprintf( '\\%X ', $byte );
+				$result .= sprintf( '\\%x ', $byte );
 				continue;
 			}
 
@@ -473,7 +473,7 @@ private static function escape_name( string $value ): string {
 				continue;
 			}
 
-			$result .= sprintf( '\\%X ', $byte );
+			$result .= sprintf( '\\%x ', $byte );
 		}
 
 		return $result;
@@ -511,7 +511,7 @@ private static function escape_url( string $value ): string {
 				0x7F === $byte ||
 				false !== strpos( '"\'()\\<>&,;{}', $value[ $i ] )
 			) {
-				$result .= sprintf( '\\%X ', $byte );
+				$result .= sprintf( '\\%x ', $byte );
 				continue;
 			}
 
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 9ce2d4e103dc5..6e4536c158366 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -38,31 +38,31 @@ public static function data_string_escaping(): array {
 			'non-ASCII passthrough'   => array( "'café'", '"café"' ),
 
 			// Backslash escaping — must happen first to prevent double-escaping.
-			'backslash'               => array( '"Back\\\\Slash"', '"Back\\5C Slash"' ),
-			'double backslash'        => array( '"\\\\\\\\"', '"\\5C \\5C "' ),
-			'backslash before quote'  => array( '"a\\\\\'b"', '"a\\5C \\27 b"' ),
+			'backslash'               => array( '"Back\\\\Slash"', '"Back\\5c Slash"' ),
+			'double backslash'        => array( '"\\\\\\\\"', '"\\5c \\5c "' ),
+			'backslash before quote'  => array( '"a\\\\\'b"', '"a\\5c \\27 b"' ),
 
 			// NULL → U+FFFD replacement character.
 			'null byte'               => array( "\"a\x00b\"", '"a�b"' ),
 			'zero escape'             => array( '"a\\0 b"', '"a�b"' ),
 
 			// Control characters are escaped as code points; CR and FF are not normalized to LF.
-			'LF'                      => array( '"a\\A b"', '"a\\A b"' ),
-			'CR'                      => array( '"a\\D b"', '"a\\D b"' ),
-			'CRLF'                    => array( '"a\\D \\A b"', '"a\\D \\A b"' ),
-			'form feed'               => array( '"a\\C b"', '"a\\C b"' ),
+			'LF'                      => array( '"a\\A b"', '"a\\a b"' ),
+			'CR'                      => array( '"a\\D b"', '"a\\d b"' ),
+			'CRLF'                    => array( '"a\\D \\A b"', '"a\\d \\a b"' ),
+			'form feed'               => array( '"a\\C b"', '"a\\c b"' ),
 			'tab'                     => array( "\"a\tb\"", '"a\\9 b"' ),
 			'escaped tab'             => array( '"a\\9 b"', '"a\\9 b"' ),
 			'U+0001'                  => array( "\"a\x01b\"", '"a\\1 b"' ),
-			'U+001F'                  => array( '"a\\1F b"', '"a\\1F b"' ),
-			'delete'                  => array( "\"a\x7Fb\"", '"a\\7F b"' ),
+			'U+001F'                  => array( '"a\\1F b"', '"a\\1f b"' ),
+			'delete'                  => array( "\"a\x7Fb\"", '"a\\7f b"' ),
 			'U+0080 is not escaped'   => array( '"a\\80 b"', "\"a\u{80}b\"" ),
 
 			// HTML-problematic characters.
-			'HTML characters < > &'   => array( '"a<b>c&d"', '"a\\3C b\\3E c\\26 d"' ),
+			'HTML characters < > &'   => array( '"a<b>c&d"', '"a\\3c b\\3e c\\26 d"' ),
 
 			// CSS-problematic characters.
-			'CSS syntax , ; { }'      => array( '"a,b;c{d}"', '"a\\2C b\\3B c\\7B d\\7D "' ),
+			'CSS syntax , ; { }'      => array( '"a,b;c{d}"', '"a\\2c b\\3b c\\7b d\\7d "' ),
 			'single quote'            => array( '"CSS\'s strings"', '"CSS\\27 s strings"' ),
 			'double quote'            => array( '\'Say "Hi"\'', '"Say \\22 Hi\\22 "' ),
 		);
@@ -119,7 +119,7 @@ public static function data_ident(): Generator {
 		yield 'Hyphenated ident' => array( 'sans-serif', 'sans-serif' );
 		yield 'Underscore prefix' => array( '_foo', '_foo' );
 		yield 'Single char' => array( 'a', 'a' );
-		yield 'Single hyphen' => array( '-', '\\2D ' );
+		yield 'Single hyphen' => array( '-', '\\2d ' );
 		yield 'Custom property prefix' => array( '--custom', '--custom' );
 		yield 'Non-ASCII' => array( 'café', 'café' );
 
@@ -135,17 +135,17 @@ public static function data_ident(): Generator {
 		yield 'Space within' => array( 'My Font', 'My\\20 Font' );
 		yield 'Multiple spaces within' => array( 'a b c', 'a\\20 b\\20 c' );
 		yield 'Tab within' => array( "has\ttab", 'has\\9 tab' );
-		yield 'Newline within' => array( "has\nnewline", 'has\\A newline' );
-		yield 'Carriage return within' => array( "has\rreturn", 'has\\D return' );
+		yield 'Newline within' => array( "has\nnewline", 'has\\a newline' );
+		yield 'Carriage return within' => array( "has\rreturn", 'has\\d return' );
 		yield 'NULL byte within' => array( "has\0null", 'has�null' );
-		yield 'DEL within' => array( "has\x7Fdelete", 'has\\7F delete' );
+		yield 'DEL within' => array( "has\x7Fdelete", 'has\\7f delete' );
 
 		// Special characters.
 		yield 'Apostrophe' => array( "Font's", 'Font\\27 s' );
-		yield 'Angle brackets' => array( '<html>', '\\3C html\\3E ' );
-		yield 'Comma' => array( 'a,b', 'a\\2C b' );
-		yield 'Semicolon' => array( 'a;b', 'a\\3B b' );
-		yield 'Backslash' => array( 'a\\b', 'a\\5C b' );
+		yield 'Angle brackets' => array( '<html>', '\\3c html\\3e ' );
+		yield 'Comma' => array( 'a,b', 'a\\2c b' );
+		yield 'Semicolon' => array( 'a;b', 'a\\3b b' );
+		yield 'Backslash' => array( 'a\\b', 'a\\5c b' );
 	}
 
 	/**
@@ -325,13 +325,13 @@ public function test_token_serialization( string $css, string $expected ): void
 	public static function data_token_serialization(): array {
 		return array(
 			'ident escapes decoded'                  => array( '\\66 oo', 'foo' ),
-			'ident escapes added'                    => array( 'a\\:b', 'a\\3A b' ),
+			'ident escapes added'                    => array( 'a\\:b', 'a\\3a b' ),
 			'function'                               => array( '\\66 oo(1)', 'foo(1)' ),
 			'at-keyword'                             => array( '@\\66 oo', '@foo' ),
-			'hash id'                                => array( '#a\\:', '#a\\3A ' ),
+			'hash id'                                => array( '#a\\:', '#a\\3a ' ),
 			'hash id escaped digit'                  => array( '#\\31 a', '#\\31 a' ),
 			'hash unrestricted'                      => array( '#1a', '#1a' ),
-			'hash unrestricted escape'               => array( '#1\\:', '#1\\3A ' ),
+			'hash unrestricted escape'               => array( '#1\\:', '#1\\3a ' ),
 			'hash unrestricted hyphen'               => array( '#-', '#-' ),
 			'string'                                 => array( "'a\"b'", '"a\\22 b"' ),
 			'string unterminated'                    => array( '"abc', '"abc"' ),
@@ -341,9 +341,9 @@ public static function data_token_serialization(): array {
 			'url escaped parenthesis'                => array( 'url(a\\29 b)', 'url(a\\29 b)' ),
 			'url escaped space'                      => array( 'url(a\\20 b)', 'url(a\\20 b)' ),
 			'url escaped quote'                      => array( 'url(a\\"b)', 'url(a\\22 b)' ),
-			'url escaped backslash'                  => array( 'url(a\\\\b)', 'url(a\\5C b)' ),
+			'url escaped backslash'                  => array( 'url(a\\\\b)', 'url(a\\5c b)' ),
 			'url escaped control'                    => array( 'url(a\\1 b)', 'url(a\\1 b)' ),
-			'url escaped newline'                    => array( 'url(a\\A b)', 'url(a\\A b)' ),
+			'url escaped newline'                    => array( 'url(a\\A b)', 'url(a\\a b)' ),
 			'url ampersand'                          => array( 'url(a&b)', 'url(a\\26 b)' ),
 			'url NUL'                                => array( "url(a\x00b)", "url(a\u{FFFD}b)" ),
 			'url unterminated'                       => array( 'url(a', 'url(a)' ),
@@ -352,7 +352,7 @@ public static function data_token_serialization(): array {
 			'number'                                 => array( '+.5e-3', '+.5e-3' ),
 			'percentage'                             => array( '-1.5%', '-1.5%' ),
 			'dimension'                              => array( '1.5e3PX', '1.5e3PX' ),
-			'dimension unit escape'                  => array( '1\\2D ', '1\\2D ' ),
+			'dimension unit escape'                  => array( '1\\2D ', '1\\2d ' ),
 			'dimension unit read as exponent'        => array( '1\\65 3', '1\\65 3' ),
 			'dimension unit read as signed exponent' => array( '1\\45 -3', '1\\45 -3' ),
 			'dimension unit e'                       => array( '1e', '1e' ),

From 5d86e10231accbae580301e3bff1192fa64d8b56 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 17:26:31 +0400
Subject: [PATCH 24/77] Escape code points outside the non-ASCII ident code
 points

CSS Syntax limits the non-ASCII code points an identifier may contain to those HTML allows in custom element names. The tokenizer, like Chrome, still reads every code point above U+007F as an identifier code point, and escape_name() wrote them all raw: `a\a0 b` was written with a raw no-break space, which a tokenizer that follows the spec reads as an ident, a delim and an ident. escape_name() now hex-escapes the code points outside the set, so identifiers, hash names and dimension units read the same under both rules.
---
 .../css-api/class-wp-css-token-serializer.php | 56 ++++++++++++++++++-
 .../tests/css-api/wpCssTokenSerializer.php    | 15 +++++
 2 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index b6d3f8bae2857..a9d123156b380 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -438,11 +438,17 @@ private static function escape_string( string $value ): string {
 	/**
 	 * Escapes every code point that cannot appear in an identifier.
 	 *
-	 * Letters, digits, `-`, `_` and code points U+0080 and above are written
-	 * as they are; every other code point is hex-escaped. Unlike
+	 * Letters, digits, `-`, `_` and the non-ASCII ident code points are
+	 * written as they are; every other code point is hex-escaped. Unlike
 	 * escape_ident(), a leading digit or `-` is not escaped, as the name of
 	 * a hash token with the "unrestricted" flag requires.
 	 *
+	 * The tokenizer reads every code point above U+007F as an identifier code
+	 * point, as browsers do. CSS Syntax allows fewer, so the others are escaped
+	 * and the output reads the same under both rules.
+	 *
+	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
+	 *
 	 * @since 7.2.0
 	 *
 	 * @param string $value Decoded name.
@@ -461,8 +467,22 @@ private static function escape_name( string $value ): string {
 				continue;
 			}
 
+			if ( $byte >= 0x80 ) {
+				// The value is valid UTF-8, so the leading byte gives the sequence length.
+				$sequence_length = $byte >= 0xF0 ? 4 : ( $byte >= 0xE0 ? 3 : 2 );
+				$code_point      = $byte & ( 0xFF >> ( $sequence_length + 1 ) );
+				for ( $j = 1; $j < $sequence_length; $j++ ) {
+					$code_point = ( $code_point << 6 ) | ( ord( $value[ $i + $j ] ) & 0x3F );
+				}
+
+				$result .= self::is_non_ascii_ident_code_point( $code_point )
+					? substr( $value, $i, $sequence_length )
+					: sprintf( '\\%x ', $code_point );
+				$i      += $sequence_length - 1;
+				continue;
+			}
+
 			if (
-				$byte >= 0x80 ||
 				( $byte >= 0x30 && $byte <= 0x39 ) || // 0-9
 				( $byte >= 0x41 && $byte <= 0x5A ) || // A-Z
 				( $byte >= 0x61 && $byte <= 0x7A ) || // a-z
@@ -479,6 +499,36 @@ private static function escape_name( string $value ): string {
 		return $result;
 	}
 
+	/**
+	 * Reports whether a code point above U+007F is a non-ASCII ident code point.
+	 *
+	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param int $code_point Code point above U+007F.
+	 * @return bool Whether the code point may appear unescaped in an identifier.
+	 */
+	private static function is_non_ascii_ident_code_point( int $code_point ): bool {
+		return (
+			0xB7 === $code_point ||
+			( $code_point >= 0xC0 && $code_point <= 0xD6 ) ||
+			( $code_point >= 0xD8 && $code_point <= 0xF6 ) ||
+			( $code_point >= 0xF8 && $code_point <= 0x37D ) ||
+			( $code_point >= 0x37F && $code_point <= 0x1FFF ) ||
+			0x200C === $code_point ||
+			0x200D === $code_point ||
+			0x203F === $code_point ||
+			0x2040 === $code_point ||
+			( $code_point >= 0x2070 && $code_point <= 0x218F ) ||
+			( $code_point >= 0x2C00 && $code_point <= 0x2FEF ) ||
+			( $code_point >= 0x3001 && $code_point <= 0xD7FF ) ||
+			( $code_point >= 0xF900 && $code_point <= 0xFDCF ) ||
+			( $code_point >= 0xFDF0 && $code_point <= 0xFFFD ) ||
+			$code_point >= 0x10000
+		);
+	}
+
 	/**
 	 * Escapes a decoded value as an unquoted url.
 	 *
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 6e4536c158366..52c3839d5fec0 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -122,6 +122,18 @@ public static function data_ident(): Generator {
 		yield 'Single hyphen' => array( '-', '\\2d ' );
 		yield 'Custom property prefix' => array( '--custom', '--custom' );
 		yield 'Non-ASCII' => array( 'café', 'café' );
+		yield 'Middle dot' => array( "a\u{B7}b", "a\u{B7}b" );
+		yield 'Zero width joiner' => array( "a\u{200D}b", "a\u{200D}b" );
+		yield 'Replacement character' => array( "a\u{FFFD}b", "a\u{FFFD}b" );
+		yield 'Supplementary plane' => array( "a\u{1F600}b", "a\u{1F600}b" );
+
+		// Non-ASCII code points outside the identifier code points — must be escaped.
+		yield 'Leading C1 control' => array( "\u{80}a", '\\80 a' );
+		yield 'No-break space within' => array( "a\u{A0}b", 'a\\a0 b' );
+		yield 'Multiplication sign within' => array( "a\u{D7}b", 'a\\d7 b' );
+		yield 'Greek question mark within' => array( "a\u{37E}b", 'a\\37e b' );
+		yield 'Zero width space within' => array( "a\u{200B}b", 'a\\200b b' );
+		yield 'U+FFFE within' => array( "a\u{FFFE}b", 'a\\fffe b' );
 
 		// Invalid ident starts — must be escaped.
 		yield 'Leading digits' => array( '123', '\\31 23' );
@@ -333,6 +345,9 @@ public static function data_token_serialization(): array {
 			'hash unrestricted'                      => array( '#1a', '#1a' ),
 			'hash unrestricted escape'               => array( '#1\\:', '#1\\3a ' ),
 			'hash unrestricted hyphen'               => array( '#-', '#-' ),
+			'hash id non-ident code point'           => array( '#a\\d7 b', '#a\\d7 b' ),
+			'hash unrestricted non-ident code point' => array( '#1\\d7 b', '#1\\d7 b' ),
+			'dimension unit non-ident code point'    => array( '1\\a0 b', '1\\a0 b' ),
 			'string'                                 => array( "'a\"b'", '"a\\22 b"' ),
 			'string unterminated'                    => array( '"abc', '"abc"' ),
 			'bad string'                             => array( "'a\nb", "\"\n b" ),

From d9a0181f72aee5e7ae65a725f35b036c21da2d05 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:19:10 +0200
Subject: [PATCH 25/77] Add HTML style attribute processor

---
 ...lass-wp-html-style-attribute-processor.php | 938 ++++++++++++++++++
 src/wp-settings.php                           |   1 +
 .../wpHtmlStyleAttributeProcessor.php         | 274 +++++
 3 files changed, 1213 insertions(+)
 create mode 100644 src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
 create mode 100644 tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
new file mode 100644
index 0000000000000..8c76fca09c7dc
--- /dev/null
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -0,0 +1,938 @@
+<?php
+/**
+ * HTML API: WP_HTML_Style_Attribute_Processor class
+ *
+ * @package WordPress
+ * @subpackage HTML-API
+ * @since {WP_VERSION}
+ */
+
+/**
+ * Core class used to inspect and modify CSS declarations in an HTML style attribute.
+ *
+ * The processor operates on decoded style attribute values. Values read from
+ * {@see WP_HTML_Tag_Processor::get_attribute()} can be passed directly to this
+ * class, and values returned by {@see WP_HTML_Style_Attribute_Processor::get_updated_style()}
+ * can be passed back to {@see WP_HTML_Tag_Processor::set_attribute()}.
+ *
+ * Unlike associative-array based style helpers, this processor preserves the
+ * declaration list model of CSS. Multiple declarations with the same property
+ * name remain separate entries and can be inspected or changed individually.
+ *
+ * @since {WP_VERSION}
+ */
+class WP_HTML_Style_Attribute_Processor {
+	/**
+	 * CSS whitespace characters.
+	 *
+	 * @var string
+	 */
+	const WHITESPACE = " \t\n\r\f";
+
+	/**
+	 * Decoded style attribute value.
+	 *
+	 * @var string
+	 */
+	private $style;
+
+	/**
+	 * CSS token metadata.
+	 *
+	 * @var array<int, array{type:string, value:string|null, start:int, length:int, end:int}>
+	 */
+	private $tokens = array();
+
+	/**
+	 * Parsed declarations.
+	 *
+	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}>
+	 */
+	private $declarations = array();
+
+	/**
+	 * Index of the current declaration, or -1 before the first declaration.
+	 *
+	 * @var int
+	 */
+	private $current_declaration = -1;
+
+	/**
+	 * Lexical updates to apply to the original style attribute value.
+	 *
+	 * @var array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}>
+	 */
+	private $lexical_updates = array();
+
+	/**
+	 * Sequence counter used to keep lexical updates in queue order.
+	 *
+	 * @var int
+	 */
+	private $lexical_update_order = 0;
+
+	/**
+	 * Constructor.
+	 *
+	 * @param string $style Decoded style attribute value.
+	 */
+	public function __construct( string $style ) {
+		$this->style = $style;
+		$this->parse();
+	}
+
+	/**
+	 * Moves to the next declaration in the style attribute value.
+	 *
+	 * When a property name is provided, normal CSS properties are matched
+	 * ASCII-case-insensitively while custom properties are matched exactly.
+	 *
+	 * @param string|null $property_name Optional property name to match.
+	 * @return bool Whether a matching declaration was found.
+	 */
+	public function next_declaration( ?string $property_name = null ): bool {
+		for ( $i = $this->current_declaration + 1; $i < count( $this->declarations ); $i++ ) {
+			if (
+				null === $property_name ||
+				$this->matches_property_name( $this->declarations[ $i ]['name'], $property_name )
+			) {
+				$this->current_declaration = $i;
+				return true;
+			}
+		}
+
+		$this->current_declaration = count( $this->declarations );
+		return false;
+	}
+
+	/**
+	 * Gets the current declaration's property name.
+	 *
+	 * @return string|null Property name, or null when not on a declaration.
+	 */
+	public function get_property_name(): ?string {
+		$declaration = $this->get_current_declaration();
+		return null === $declaration ? null : $declaration['name'];
+	}
+
+	/**
+	 * Gets the current declaration's CSS value.
+	 *
+	 * The returned value does not include a trailing !important priority.
+	 *
+	 * @return string|null CSS value, or null when not on a declaration.
+	 */
+	public function get_value(): ?string {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration ) {
+			return null;
+		}
+
+		return trim(
+			substr( $this->style, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
+			self::WHITESPACE
+		);
+	}
+
+	/**
+	 * Indicates whether the current declaration has an !important priority.
+	 *
+	 * @return bool Whether the current declaration has an !important priority.
+	 */
+	public function is_important(): bool {
+		$declaration = $this->get_current_declaration();
+		return null !== $declaration && $declaration['important'];
+	}
+
+	/**
+	 * Sets the value of the current declaration.
+	 *
+	 * @param string    $value     CSS declaration value, without the property name.
+	 * @param bool|null $important Optional. Whether the declaration should be important.
+	 *                             Defaults to preserving the current priority.
+	 * @return bool Whether the current declaration was updated.
+	 */
+	public function set_value( string $value, ?bool $important = null ): bool {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration || ! $this->is_valid_declaration_value( $value ) ) {
+			return false;
+		}
+
+		$is_important = null === $important ? $declaration['important'] : $important;
+		$text         = $this->serialize_declaration( $declaration['raw_name'], $value, $is_important );
+
+		$this->queue_lexical_update(
+			$declaration['start'],
+			$declaration['after'] - $declaration['start'],
+			$text,
+			$this->current_declaration
+		);
+
+		return true;
+	}
+
+	/**
+	 * Removes the current declaration from the style attribute value.
+	 *
+	 * Only the current declaration is removed. Other declarations with the same
+	 * property name remain in place.
+	 *
+	 * @return bool Whether the current declaration was removed.
+	 */
+	public function remove_declaration(): bool {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration ) {
+			return false;
+		}
+
+		if ( '' === trim( substr( $this->style, 0, $declaration['leading_start'] ), self::WHITESPACE ) ) {
+			$remove_start = $declaration['leading_start'];
+			$remove_end   = $declaration['trailing_end'];
+		} else {
+			$remove_start = $declaration['leading_start'];
+			$remove_end   = $declaration['after'];
+		}
+
+		$this->queue_lexical_update(
+			$remove_start,
+			$remove_end - $remove_start,
+			'',
+			$this->current_declaration
+		);
+
+		return true;
+	}
+
+	/**
+	 * Appends a declaration to the style attribute value.
+	 *
+	 * Appending does not remove or replace existing declarations with the same
+	 * property name.
+	 *
+	 * @param string $property_name CSS property name.
+	 * @param string $value         CSS declaration value, without the property name.
+	 * @param bool   $important     Optional. Whether the declaration should be important. Default false.
+	 * @return bool Whether the declaration was appended.
+	 */
+	public function append_declaration( string $property_name, string $value, bool $important = false ): bool {
+		if ( ! $this->is_valid_property_name( $property_name ) || ! $this->is_valid_declaration_value( $value ) ) {
+			return false;
+		}
+
+		$trimmed_style = rtrim( $this->style, self::WHITESPACE );
+		$insert_at     = strlen( $trimmed_style );
+		$separator     = $this->has_queued_append_at( $insert_at ) ? ' ' : '';
+
+		if ( '' === $separator && '' !== trim( $trimmed_style, self::WHITESPACE ) ) {
+			$separator = ( ';' === substr( $trimmed_style, -1 ) ) ? ' ' : '; ';
+		}
+
+		$this->queue_lexical_update(
+			$insert_at,
+			0,
+			$separator . $this->serialize_declaration( $property_name, $value, $important ),
+			null
+		);
+
+		return true;
+	}
+
+	/**
+	 * Returns the updated style attribute value.
+	 *
+	 * @return string Updated style attribute value.
+	 */
+	public function get_updated_style(): string {
+		if ( empty( $this->lexical_updates ) ) {
+			return $this->style;
+		}
+
+		usort(
+			$this->lexical_updates,
+			static function ( $a, $b ) {
+				if ( $a['start'] !== $b['start'] ) {
+					return $a['start'] - $b['start'];
+				}
+
+				return $a['order'] - $b['order'];
+			}
+		);
+
+		$updates = $this->merge_overlapping_lexical_updates( $this->lexical_updates );
+
+		$bytes_already_copied = 0;
+		$output               = '';
+
+		foreach ( $updates as $update ) {
+			$output              .= substr( $this->style, $bytes_already_copied, $update['start'] - $bytes_already_copied );
+			$output              .= $update['text'];
+			$bytes_already_copied = $update['start'] + $update['length'];
+		}
+
+		$output .= substr( $this->style, $bytes_already_copied );
+
+		return $output;
+	}
+
+	/**
+	 * Parses CSS tokens and declarations from the style attribute value.
+	 */
+	private function parse(): void {
+		$processor = WP_CSS_Token_Processor::create( $this->style );
+		if ( null === $processor ) {
+			return;
+		}
+
+		while ( $processor->next_token() ) {
+			$start          = $processor->get_token_start();
+			$length         = $processor->get_token_length();
+			$this->tokens[] = array(
+				'type'   => $processor->get_token_type(),
+				'value'  => $processor->get_token_value(),
+				'start'  => $start,
+				'length' => $length,
+				'end'    => $start + $length,
+			);
+		}
+
+		$this->parse_declaration_list();
+	}
+
+	/**
+	 * Parses the token list according to the CSS declaration-list shape.
+	 */
+	private function parse_declaration_list(): void {
+		$index                 = 0;
+		$count                 = count( $this->tokens );
+		$previous_item_ends_at = 0;
+
+		while ( $index < $count ) {
+			$leading_start = $previous_item_ends_at;
+			$index         = $this->skip_ignored_tokens( $index );
+
+			while ( $index < $count && WP_CSS_Token_Processor::TOKEN_SEMICOLON === $this->tokens[ $index ]['type'] ) {
+				$previous_item_ends_at = $this->tokens[ $index ]['end'];
+				$leading_start         = $previous_item_ends_at;
+				++$index;
+				$index = $this->skip_ignored_tokens( $index );
+			}
+
+			if ( $index >= $count ) {
+				break;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_AT_KEYWORD === $this->tokens[ $index ]['type'] ) {
+				list( $index, $previous_item_ends_at ) = $this->consume_at_rule( $index );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE === $this->tokens[ $index ]['type'] ) {
+				$previous_item_ends_at = $this->tokens[ $index ]['end'];
+				++$index;
+				continue;
+			}
+
+			list( $declaration_end, $after_declaration, $has_semicolon ) = $this->consume_declaration_segment( $index );
+			$declaration = $this->parse_declaration_segment( $leading_start, $index, $declaration_end, $after_declaration );
+
+			if ( null !== $declaration ) {
+				$declaration['trailing_end'] = $this->get_trailing_ignored_end( $declaration_end + ( $has_semicolon ? 1 : 0 ) );
+				$this->declarations[]        = $declaration;
+			}
+
+			$index                 = $declaration_end + ( $has_semicolon ? 1 : 0 );
+			$previous_item_ends_at = $after_declaration;
+		}
+	}
+
+	/**
+	 * Consumes an at-rule and returns the token index and byte offset after it.
+	 *
+	 * @param int $index At-keyword token index.
+	 * @return array{int,int} Token index and byte offset after the at-rule.
+	 */
+	private function consume_at_rule( int $index ): array {
+		$count = count( $this->tokens );
+		++$index;
+
+		while ( $index < $count ) {
+			$token = $this->tokens[ $index ];
+
+			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token['type'] ) {
+				return array( $index + 1, $token['end'] );
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+				return $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				continue;
+			}
+
+			++$index;
+		}
+
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		return array( $count, $after );
+	}
+
+	/**
+	 * Consumes a simple block.
+	 *
+	 * @param int    $index        Token index for the opening token.
+	 * @param string $closing_type Expected closing token type.
+	 * @return array{int,int} Token index and byte offset after the block.
+	 */
+	private function consume_simple_block( int $index, string $closing_type ): array {
+		$count = count( $this->tokens );
+		++$index;
+
+		while ( $index < $count ) {
+			$token = $this->tokens[ $index ];
+
+			if ( $closing_type === $token['type'] ) {
+				return array( $index + 1, $token['end'] );
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				continue;
+			}
+
+			++$index;
+		}
+
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		return array( $count, $after );
+	}
+
+	/**
+	 * Consumes a declaration candidate up to the next top-level semicolon or EOF.
+	 *
+	 * @param int $index Starting token index.
+	 * @return array{int,int,bool} End token index, byte offset after candidate, and whether it ended in a semicolon.
+	 */
+	private function consume_declaration_segment( int $index ): array {
+		$count = count( $this->tokens );
+
+		while ( $index < $count ) {
+			$token = $this->tokens[ $index ];
+
+			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token['type'] ) {
+				return array( $index, $token['end'], true );
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				continue;
+			}
+
+			++$index;
+		}
+
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		return array( $count, $after, false );
+	}
+
+	/**
+	 * Parses a declaration from a token segment.
+	 *
+	 * @param int $leading_start Byte offset before leading trivia.
+	 * @param int $start_index   First token index in the segment.
+	 * @param int $end_index     Token index after the segment.
+	 * @param int $after         Byte offset after the declaration.
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}|null
+	 */
+	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
+		$index = $this->skip_ignored_tokens( $start_index, $end_index );
+		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_IDENT !== $this->tokens[ $index ]['type'] ) {
+			return null;
+		}
+
+		$name_token = $this->tokens[ $index ];
+		$name       = $name_token['value'];
+		if ( null === $name ) {
+			return null;
+		}
+
+		++$index;
+		$index = $this->skip_ignored_tokens( $index, $end_index );
+
+		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_COLON !== $this->tokens[ $index ]['type'] ) {
+			return null;
+		}
+
+		$colon_token       = $this->tokens[ $index ];
+		$value_start_index = $this->skip_ignored_tokens( $index + 1, $end_index );
+		$value_end_index   = $this->trim_ignored_tokens( $value_start_index, $end_index );
+		$important         = false;
+		$top_level_tokens  = $this->get_top_level_non_ignored_token_indexes( $value_start_index, $value_end_index );
+		$top_level_count   = count( $top_level_tokens );
+		$last_value_index  = $top_level_count > 0 ? $top_level_tokens[ $top_level_count - 1 ] : null;
+		$before_last_index = $top_level_count > 1 ? $top_level_tokens[ $top_level_count - 2 ] : null;
+
+		if (
+			null !== $last_value_index &&
+			null !== $before_last_index &&
+			WP_CSS_Token_Processor::TOKEN_IDENT === $this->tokens[ $last_value_index ]['type'] &&
+			0 === strcasecmp( 'important', (string) $this->tokens[ $last_value_index ]['value'] ) &&
+			WP_CSS_Token_Processor::TOKEN_DELIM === $this->tokens[ $before_last_index ]['type'] &&
+			'!' === $this->tokens[ $before_last_index ]['value']
+		) {
+			$important       = true;
+			$value_end_index = $this->trim_ignored_tokens( $value_start_index, $before_last_index );
+		}
+
+		if ( $value_start_index >= $value_end_index ) {
+			$value_start = $colon_token['end'];
+			$value_end   = $colon_token['end'];
+		} else {
+			$value_start = $this->tokens[ $value_start_index ]['start'];
+			$value_end   = $this->tokens[ $value_end_index - 1 ]['end'];
+		}
+
+		return array(
+			'name'          => $name,
+			'raw_name'      => substr( $this->style, $name_token['start'], $name_token['length'] ),
+			'leading_start' => $leading_start,
+			'start'         => $name_token['start'],
+			'after'         => $after,
+			'trailing_end'  => $after,
+			'value_start'   => $value_start,
+			'value_end'     => $value_end,
+			'important'     => $important,
+		);
+	}
+
+	/**
+	 * Gets top-level non-ignored token indexes from a token range.
+	 *
+	 * @param int $start Start token index.
+	 * @param int $end   End token index.
+	 * @return int[] Top-level non-ignored token indexes.
+	 */
+	private function get_top_level_non_ignored_token_indexes( int $start, int $end ): array {
+		$top_level_tokens = array();
+		$index            = $start;
+
+		while ( $index < $end ) {
+			$token = $this->tokens[ $index ];
+
+			if ( $this->is_ignored_token( $token ) ) {
+				++$index;
+				continue;
+			}
+
+			$top_level_tokens[] = $index;
+
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				continue;
+			}
+
+			++$index;
+		}
+
+		return $top_level_tokens;
+	}
+
+	/**
+	 * Skips ignored CSS tokens.
+	 *
+	 * @param int      $index Token index.
+	 * @param int|null $end   Optional token index at which to stop.
+	 * @return int Token index after ignored tokens.
+	 */
+	private function skip_ignored_tokens( int $index, ?int $end = null ): int {
+		$end = null === $end ? count( $this->tokens ) : $end;
+
+		while ( $index < $end && $this->is_ignored_token( $this->tokens[ $index ] ) ) {
+			++$index;
+		}
+
+		return $index;
+	}
+
+	/**
+	 * Trims ignored CSS tokens from the end of a token range.
+	 *
+	 * @param int $start Start token index.
+	 * @param int $end   End token index.
+	 * @return int Trimmed end token index.
+	 */
+	private function trim_ignored_tokens( int $start, int $end ): int {
+		while ( $end > $start && $this->is_ignored_token( $this->tokens[ $end - 1 ] ) ) {
+			--$end;
+		}
+
+		return $end;
+	}
+
+	/**
+	 * Gets the byte offset after ignored tokens beginning at a token index.
+	 *
+	 * @param int $index Token index.
+	 * @return int Byte offset after ignored tokens.
+	 */
+	private function get_trailing_ignored_end( int $index ): int {
+		$end   = $index > 0 && isset( $this->tokens[ $index - 1 ] ) ? $this->tokens[ $index - 1 ]['end'] : 0;
+		$count = count( $this->tokens );
+
+		while ( $index < $count && $this->is_ignored_token( $this->tokens[ $index ] ) ) {
+			$end = $this->tokens[ $index ]['end'];
+			++$index;
+		}
+
+		return $end;
+	}
+
+	/**
+	 * Checks whether a token is ignored by declaration-list grammar.
+	 *
+	 * @param array{type:string, value:string|null, start:int, length:int, end:int} $token Token metadata.
+	 * @return bool Whether the token is ignored.
+	 */
+	private function is_ignored_token( array $token ): bool {
+		return (
+			WP_CSS_Token_Processor::TOKEN_WHITESPACE === $token['type'] ||
+			WP_CSS_Token_Processor::TOKEN_COMMENT === $token['type']
+		);
+	}
+
+	/**
+	 * Gets the current declaration metadata.
+	 *
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}|null
+	 */
+	private function get_current_declaration(): ?array {
+		if ( $this->current_declaration < 0 || ! isset( $this->declarations[ $this->current_declaration ] ) ) {
+			return null;
+		}
+
+		return $this->declarations[ $this->current_declaration ];
+	}
+
+	/**
+	 * Queues a lexical update, replacing any earlier update for the same declaration.
+	 *
+	 * @param int      $start       Byte offset at which to start the update.
+	 * @param int      $length      Number of bytes to replace.
+	 * @param string   $text        Replacement text.
+	 * @param int|null $declaration Declaration index associated with the update.
+	 */
+	private function queue_lexical_update( int $start, int $length, string $text, ?int $declaration ): void {
+		if ( null !== $declaration ) {
+			foreach ( $this->lexical_updates as $index => $update ) {
+				if ( $update['declaration'] === $declaration ) {
+					unset( $this->lexical_updates[ $index ] );
+				}
+			}
+		}
+
+		$this->lexical_updates[] = array(
+			'start'       => $start,
+			'length'      => $length,
+			'text'        => $text,
+			'declaration' => $declaration,
+			'order'       => $this->lexical_update_order++,
+		);
+	}
+
+	/**
+	 * Checks whether an append has already been queued at a byte offset.
+	 *
+	 * @param int $insert_at Byte offset.
+	 * @return bool Whether an append has already been queued at the offset.
+	 */
+	private function has_queued_append_at( int $insert_at ): bool {
+		foreach ( $this->lexical_updates as $update ) {
+			if ( null === $update['declaration'] && $insert_at === $update['start'] && 0 === $update['length'] ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Merges overlapping lexical updates into non-overlapping replacements.
+	 *
+	 * Adjacent declaration removals may share separator whitespace, and appends
+	 * may be queued inside a range removed from the original style. This method
+	 * collapses those updates while preserving the requested replacement text.
+	 *
+	 * @param array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> $updates Lexical updates.
+	 * @return array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> Merged updates.
+	 */
+	private function merge_overlapping_lexical_updates( array $updates ): array {
+		$merged = array();
+
+		foreach ( $updates as $update ) {
+			if ( empty( $merged ) ) {
+				$merged[] = $update;
+				continue;
+			}
+
+			$last_index = count( $merged ) - 1;
+			$last       = $merged[ $last_index ];
+			$last_end   = $last['start'] + $last['length'];
+			$update_end = $update['start'] + $update['length'];
+
+			if ( $update['start'] > $last_end ) {
+				$merged[] = $update;
+				continue;
+			}
+
+			$text = $update['text'];
+			if ( 0 === $last['start'] && '' === $last['text'] && 0 === $update['length'] ) {
+				$text = ltrim( $text, ';' . self::WHITESPACE );
+			}
+
+			$merged[ $last_index ]['length'] = max( $last_end, $update_end ) - $last['start'];
+			$merged[ $last_index ]['text']   = $last['text'] . $text;
+		}
+
+		foreach ( $merged as $index => $update ) {
+			if ( 0 !== $update['start'] || '' !== $update['text'] ) {
+				continue;
+			}
+
+			$end = $update['length'];
+			while ( $end < strlen( $this->style ) && false !== strpos( self::WHITESPACE, $this->style[ $end ] ) ) {
+				++$end;
+			}
+
+			$merged[ $index ]['length'] = $end;
+		}
+
+		return $merged;
+	}
+
+	/**
+	 * Serializes a declaration.
+	 *
+	 * @param string $property_name CSS property name.
+	 * @param string $value         CSS declaration value.
+	 * @param bool   $important     Whether to append !important.
+	 * @return string Serialized declaration.
+	 */
+	private function serialize_declaration( string $property_name, string $value, bool $important ): string {
+		$value = trim( $value, self::WHITESPACE );
+		return $property_name . ': ' . $value . ( $important ? ' !important' : '' ) . ';';
+	}
+
+	/**
+	 * Checks whether two property names match.
+	 *
+	 * @param string $actual Property name from a declaration.
+	 * @param string $query  Queried property name.
+	 * @return bool Whether the property names match.
+	 */
+	private function matches_property_name( string $actual, string $query ): bool {
+		if ( $this->is_custom_property_name( $actual ) || $this->is_custom_property_name( $query ) ) {
+			return $actual === $query;
+		}
+
+		return 0 === strcasecmp( $actual, $query );
+	}
+
+	/**
+	 * Checks whether a property name is a custom property.
+	 *
+	 * @param string $property_name Property name.
+	 * @return bool Whether this is a custom property name.
+	 */
+	private function is_custom_property_name( string $property_name ): bool {
+		return strlen( $property_name ) >= 2 && '--' === substr( $property_name, 0, 2 );
+	}
+
+	/**
+	 * Checks whether a CSS property name is syntactically valid.
+	 *
+	 * @param string $property_name CSS property name.
+	 * @return bool Whether the property name is valid.
+	 */
+	private function is_valid_property_name( string $property_name ): bool {
+		$processor = WP_CSS_Token_Processor::create( $property_name );
+		if ( null === $processor || ! $processor->next_token() ) {
+			return false;
+		}
+
+		if (
+			WP_CSS_Token_Processor::TOKEN_IDENT !== $processor->get_token_type() ||
+			$processor->get_token_start() !== 0 ||
+			$processor->get_token_length() !== strlen( $property_name )
+		) {
+			return false;
+		}
+
+		if ( $processor->next_token() ) {
+			return false;
+		}
+
+		$sentinel_processor = WP_CSS_Token_Processor::create( $property_name . ': sentinel' );
+		if ( null === $sentinel_processor || ! $sentinel_processor->next_token() ) {
+			return false;
+		}
+
+		if (
+			WP_CSS_Token_Processor::TOKEN_IDENT !== $sentinel_processor->get_token_type() ||
+			$sentinel_processor->get_token_start() !== 0 ||
+			$sentinel_processor->get_token_length() !== strlen( $property_name )
+		) {
+			return false;
+		}
+
+		return (
+			$sentinel_processor->next_token() &&
+			WP_CSS_Token_Processor::TOKEN_COLON === $sentinel_processor->get_token_type()
+		);
+	}
+
+	/**
+	 * Checks whether a CSS declaration value is syntactically safe to insert.
+	 *
+	 * @param string $value CSS declaration value.
+	 * @return bool Whether the value is valid.
+	 */
+	private function is_valid_declaration_value( string $value ): bool {
+		$sentinel_property = '--wp-style-attribute-processor-sentinel';
+		$processor         = WP_CSS_Token_Processor::create( $value . ';' . $sentinel_property . ':1' );
+		if ( null === $processor ) {
+			return false;
+		}
+
+		$stack            = array();
+		$top_level_tokens = array();
+		$found_sentinel   = false;
+
+		while ( $processor->next_token() ) {
+			$type = $processor->get_token_type();
+
+			if ( empty( $stack ) && WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $type && WP_CSS_Token_Processor::TOKEN_COMMENT !== $type ) {
+				if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $type ) {
+					if ( strlen( $value ) !== $processor->get_token_start() ) {
+						return false;
+					}
+
+					$found_sentinel = true;
+					break;
+				}
+
+				$top_level_tokens[] = array(
+					'type'  => $type,
+					'value' => $processor->get_token_value(),
+				);
+			}
+
+			switch ( $type ) {
+				case WP_CSS_Token_Processor::TOKEN_SEMICOLON:
+					if ( empty( $stack ) ) {
+						return false;
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
+				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
+					return false;
+
+				case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+				case WP_CSS_Token_Processor::TOKEN_LEFT_PAREN:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACE:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN:
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET:
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE:
+					if ( empty( $stack ) || array_pop( $stack ) !== $processor->get_token_type() ) {
+						return false;
+					}
+					break;
+			}
+		}
+
+		if ( ! $found_sentinel || ! empty( $stack ) ) {
+			return false;
+		}
+
+		$top_level_count = count( $top_level_tokens );
+		if ( $top_level_count < 2 ) {
+			return true;
+		}
+
+		$last_value_token  = $top_level_tokens[ $top_level_count - 1 ];
+		$before_last_token = $top_level_tokens[ $top_level_count - 2 ];
+
+		return ! (
+			WP_CSS_Token_Processor::TOKEN_IDENT === $last_value_token['type'] &&
+			0 === strcasecmp( 'important', (string) $last_value_token['value'] ) &&
+			WP_CSS_Token_Processor::TOKEN_DELIM === $before_last_token['type'] &&
+			'!' === $before_last_token['value']
+		);
+	}
+}
diff --git a/src/wp-settings.php b/src/wp-settings.php
index 6dac160973467..d4bbf317eb22b 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -281,6 +281,7 @@
 require ABSPATH . WPINC . '/css-api/class-wp-css-token.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-serializer.php';
+require ABSPATH . WPINC . '/html-api/class-wp-html-style-attribute-processor.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
new file mode 100644
index 0000000000000..e6f5fcdef0372
--- /dev/null
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -0,0 +1,274 @@
+<?php
+/**
+ * Unit tests covering WP_HTML_Style_Attribute_Processor functionality.
+ *
+ * @package WordPress
+ * @subpackage HTML-API
+ *
+ * @since {WP_VERSION}
+ *
+ * @group html-api
+ *
+ * @coversDefaultClass WP_HTML_Style_Attribute_Processor
+ */
+class Tests_HtmlApi_WpHtmlStyleAttributeProcessor extends WP_UnitTestCase {
+	/**
+	 * @covers ::next_declaration
+	 * @covers ::get_property_name
+	 * @covers ::get_value
+	 */
+	public function test_next_declaration_reads_properties_in_order_and_preserves_duplicates() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: color(display-p3 1 0 0); background: blue' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertSame( 'red', $processor->get_value() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertSame( 'color(display-p3 1 0 0)', $processor->get_value() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'blue', $processor->get_value() );
+
+		$this->assertFalse( $processor->next_declaration() );
+	}
+
+	/**
+	 * @covers ::next_declaration
+	 */
+	public function test_next_declaration_query_visits_matching_duplicate_properties() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white; COLOR: blue;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertSame( 'red', $processor->get_value() );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertSame( 'blue', $processor->get_value() );
+
+		$this->assertFalse( $processor->next_declaration( 'color' ) );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( '--Tone: warm; --tone: cool;' );
+
+		$this->assertTrue( $processor->next_declaration( '--tone' ) );
+		$this->assertSame( 'cool', $processor->get_value() );
+
+		$this->assertFalse( $processor->next_declaration( '--tone' ) );
+	}
+
+	/**
+	 * @covers ::is_important
+	 * @covers ::get_value
+	 */
+	public function test_important_priority_is_inspected_separately_from_value() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; --tone: blue !IMPORTANT; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'red', $processor->get_value() );
+		$this->assertTrue( $processor->is_important() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'blue', $processor->get_value() );
+		$this->assertTrue( $processor->is_important() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'white', $processor->get_value() );
+		$this->assertFalse( $processor->is_important() );
+	}
+
+	/**
+	 * @covers ::set_value
+	 * @covers ::get_updated_style
+	 */
+	public function test_set_value_updates_current_declaration_without_collapsing_duplicates() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; color: color(display-p3 1 0 0);' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( 'green', false ) );
+
+		$this->assertSame( 'color: green; color: color(display-p3 1 0 0);', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_remove_declaration_removes_only_current_duplicate() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+
+		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_remove_declaration_removes_adjacent_duplicate_declarations() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
+
+		while ( $processor->next_declaration( 'color' ) ) {
+			$this->assertTrue( $processor->remove_declaration() );
+		}
+
+		$this->assertSame( 'background: white;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_adds_duplicate_declaration() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'color(display-p3 1 0 0)', true ) );
+
+		$this->assertSame( 'color: red; color: color(display-p3 1 0 0) !important;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_preserves_multiple_appends_in_order() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+
+		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_after_removing_only_declaration() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;   ' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+
+		$this->assertSame( 'background: white;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::next_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_invalid_fragments_are_skipped_and_preserved() {
+		$style     = 'color red; @media (min-width: 1px) { color: green; } background: white;';
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'white', $processor->get_value() );
+		$this->assertFalse( $processor->next_declaration() );
+		$this->assertSame( $style, $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::is_important
+	 * @covers ::get_value
+	 */
+	public function test_important_inside_unclosed_function_is_not_declaration_priority() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x, red !important' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'var(--x, red !important', $processor->get_value() );
+		$this->assertFalse( $processor->is_important() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_declaration_values_reject_top_level_semicolons() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+
+		$this->assertFalse( $processor->append_declaration( 'background', 'blue; color: green' ) );
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::set_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_declaration_values_reject_top_level_important_priority() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertFalse( $processor->set_value( 'green ! important', false ) );
+		$this->assertFalse( $processor->append_declaration( 'background', 'white !important' ) );
+
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_malformed_declaration_values
+	 *
+	 * @param string $value Malformed CSS declaration value.
+	 */
+	public function test_declaration_values_reject_malformed_eof_tokens( string $value ) {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+
+		$this->assertFalse( $processor->append_declaration( 'background', $value ) );
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::get_updated_style
+	 */
+	public function test_updated_style_can_be_set_on_html_tag_processor() {
+		$tags = new WP_HTML_Tag_Processor( '<div style="color: red; color: color(display-p3 1 0 0)">Text</div>' );
+		$this->assertTrue( $tags->next_tag( 'div' ) );
+
+		$styles = new WP_HTML_Style_Attribute_Processor( $tags->get_attribute( 'style' ) );
+		$this->assertTrue( $styles->append_declaration( 'background', 'white' ) );
+		$this->assertTrue( $tags->set_attribute( 'style', $styles->get_updated_style() ) );
+
+		$this->assertSame(
+			'<div style="color: red; color: color(display-p3 1 0 0); background: white;">Text</div>',
+			$tags->get_updated_html()
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function data_malformed_declaration_values(): array {
+		return array(
+			'eof string'                      => array( '"unterminated' ),
+			'eof string escaped end'          => array( '"unterminated\\' ),
+			'eof string apparent end escaped' => array( '"unterminated\\"' ),
+			'eof comment'                     => array( '/*' ),
+			'eof url'                         => array( 'url(foo' ),
+			'eof url escaped end'             => array( 'url(foo\\' ),
+			'eof url apparent end escaped'    => array( 'url(foo\\)' ),
+			'eof escape'                      => array( 'red\\' ),
+		);
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_property_names_reject_eof_escapes() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
+
+		$this->assertFalse( $processor->append_declaration( 'color\\', 'red' ) );
+		$this->assertSame( '', $processor->get_updated_style() );
+	}
+}

From 787ce336fd478e7d3e77a0971ab375943e322e1c Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:34:12 +0200
Subject: [PATCH 26/77] Harden style attribute parsing

---
 ...lass-wp-html-style-attribute-processor.php |  16 +--
 .../wpHtmlStyleAttributeProcessor.php         | 106 ++++++++++++++++++
 2 files changed, 114 insertions(+), 8 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 8c76fca09c7dc..28fe974678040 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -74,9 +74,15 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Constructor.
 	 *
-	 * @param string $style Decoded style attribute value.
+	 * @param string|bool|null $style Decoded style attribute value.
 	 */
-	public function __construct( string $style ) {
+	public function __construct( $style = '' ) {
+		if ( null === $style || true === $style ) {
+			$style = '';
+		} elseif ( ! is_string( $style ) ) {
+			$style = '';
+		}
+
 		$this->style = $style;
 		$this->parse();
 	}
@@ -326,12 +332,6 @@ private function parse_declaration_list(): void {
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE === $this->tokens[ $index ]['type'] ) {
-				$previous_item_ends_at = $this->tokens[ $index ]['end'];
-				++$index;
-				continue;
-			}
-
 			list( $declaration_end, $after_declaration, $has_semicolon ) = $this->consume_declaration_segment( $index );
 			$declaration = $this->parse_declaration_segment( $leading_start, $index, $declaration_end, $after_declaration );
 
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index e6f5fcdef0372..327fac293a60a 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -12,6 +12,33 @@
  * @coversDefaultClass WP_HTML_Style_Attribute_Processor
  */
 class Tests_HtmlApi_WpHtmlStyleAttributeProcessor extends WP_UnitTestCase {
+	/**
+	 * @covers ::__construct
+	 * @covers ::next_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_html_style_attribute_values
+	 *
+	 * @param string      $html           HTML containing a first div.
+	 * @param string      $expected_style Expected normalized style input.
+	 * @param string|null $property_name  Expected first property name.
+	 */
+	public function test_constructor_accepts_html_tag_processor_style_attribute_values( string $html, string $expected_style, ?string $property_name ) {
+		$tags = new WP_HTML_Tag_Processor( $html );
+		$this->assertTrue( $tags->next_tag( 'div' ) );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( $tags->get_attribute( 'style' ) );
+
+		$this->assertSame( $expected_style, $processor->get_updated_style() );
+
+		if ( null === $property_name ) {
+			$this->assertFalse( $processor->next_declaration() );
+		} else {
+			$this->assertTrue( $processor->next_declaration() );
+			$this->assertSame( $property_name, $processor->get_property_name() );
+		}
+	}
+
 	/**
 	 * @covers ::next_declaration
 	 * @covers ::get_property_name
@@ -173,6 +200,38 @@ public function test_invalid_fragments_are_skipped_and_preserved() {
 		$this->assertSame( $style, $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::next_declaration
+	 */
+	public function test_stray_right_brace_consumes_bad_declaration_until_semicolon() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '} color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'white', $processor->get_value() );
+		$this->assertFalse( $processor->next_declaration() );
+	}
+
+	/**
+	 * @covers ::next_declaration
+	 * @covers ::set_value
+	 * @covers ::get_updated_style
+	 */
+	public function test_escaped_property_names_match_decoded_names_and_preserve_raw_spelling() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertTrue( $processor->set_value( 'green' ) );
+		$this->assertSame( 'c\\6f lor: green; --t\\6f ne: cool; --Tone: warm;', $processor->get_updated_style() );
+
+		$this->assertTrue( $processor->next_declaration( '--tone' ) );
+		$this->assertSame( '--tone', $processor->get_property_name() );
+		$this->assertSame( 'cool', $processor->get_value() );
+
+		$this->assertFalse( $processor->next_declaration( '--tone' ) );
+	}
+
 	/**
 	 * @covers ::is_important
 	 * @covers ::get_value
@@ -185,6 +244,24 @@ public function test_important_inside_unclosed_function_is_not_declaration_prior
 		$this->assertFalse( $processor->is_important() );
 	}
 
+	/**
+	 * @covers ::is_important
+	 * @covers ::get_value
+	 *
+	 * @dataProvider data_important_priority_syntax
+	 *
+	 * @param string $style     Style attribute value.
+	 * @param string $value     Expected declaration value.
+	 * @param bool   $important Expected importance.
+	 */
+	public function test_important_priority_syntax_variants( string $style, string $value, bool $important ) {
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( $value, $processor->get_value() );
+		$this->assertSame( $important, $processor->is_important() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
@@ -243,6 +320,35 @@ public function test_updated_style_can_be_set_on_html_tag_processor() {
 		);
 	}
 
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string,string,string|null}>
+	 */
+	public static function data_html_style_attribute_values(): array {
+		return array(
+			'missing style attribute' => array( '<div>Text</div>', '', null ),
+			'boolean style attribute' => array( '<div style>Text</div>', '', null ),
+			'empty style attribute'   => array( '<div style="">Text</div>', '', null ),
+			'valued style attribute'  => array( '<div style="color: red">Text</div>', 'color: red', 'color' ),
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string,string,bool}>
+	 */
+	public static function data_important_priority_syntax(): array {
+		return array(
+			'no whitespace'         => array( 'color: red!important;', 'red', true ),
+			'whitespace after bang' => array( 'color: red ! important;', 'red', true ),
+			'comment after bang'    => array( 'color: red ! /*x*/ important;', 'red', true ),
+			'escaped important'     => array( 'color: red !\\69mportant;', 'red', true ),
+			'extra trailing token'  => array( 'color: red ! important foo;', 'red ! important foo', false ),
+		);
+	}
+
 	/**
 	 * Data provider.
 	 *

From a91b7e499a4b9a9f528bf5c80451b61cc92fd70e Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 13:49:50 +0200
Subject: [PATCH 27/77] Refresh style declarations after mutation

---
 ...lass-wp-html-style-attribute-processor.php | 63 ++++++++++++++--
 .../wpHtmlStyleAttributeProcessor.php         | 74 +++++++++++++++++++
 2 files changed, 131 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 28fe974678040..803fc431799c5 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -57,6 +57,13 @@ class WP_HTML_Style_Attribute_Processor {
 	 */
 	private $current_declaration = -1;
 
+	/**
+	 * Whether the current declaration was removed and no new declaration has been selected.
+	 *
+	 * @var bool
+	 */
+	private $current_declaration_removed = false;
+
 	/**
 	 * Lexical updates to apply to the original style attribute value.
 	 *
@@ -102,12 +109,14 @@ public function next_declaration( ?string $property_name = null ): bool {
 				null === $property_name ||
 				$this->matches_property_name( $this->declarations[ $i ]['name'], $property_name )
 			) {
-				$this->current_declaration = $i;
+				$this->current_declaration         = $i;
+				$this->current_declaration_removed = false;
 				return true;
 			}
 		}
 
-		$this->current_declaration = count( $this->declarations );
+		$this->current_declaration         = count( $this->declarations );
+		$this->current_declaration_removed = false;
 		return false;
 	}
 
@@ -174,6 +183,8 @@ public function set_value( string $value, ?bool $important = null ): bool {
 			$this->current_declaration
 		);
 
+		$this->apply_lexical_updates( $this->current_declaration );
+
 		return true;
 	}
 
@@ -206,6 +217,8 @@ public function remove_declaration(): bool {
 			$this->current_declaration
 		);
 
+		$this->apply_lexical_updates( $this->current_declaration - 1, true );
+
 		return true;
 	}
 
@@ -225,9 +238,10 @@ public function append_declaration( string $property_name, string $value, bool $
 			return false;
 		}
 
-		$trimmed_style = rtrim( $this->style, self::WHITESPACE );
-		$insert_at     = strlen( $trimmed_style );
-		$separator     = $this->has_queued_append_at( $insert_at ) ? ' ' : '';
+		$old_declaration_count = count( $this->declarations );
+		$trimmed_style         = rtrim( $this->style, self::WHITESPACE );
+		$insert_at             = strlen( $trimmed_style );
+		$separator             = $this->has_queued_append_at( $insert_at ) ? ' ' : '';
 
 		if ( '' === $separator && '' !== trim( $trimmed_style, self::WHITESPACE ) ) {
 			$separator = ( ';' === substr( $trimmed_style, -1 ) ) ? ' ' : '; ';
@@ -240,6 +254,16 @@ public function append_declaration( string $property_name, string $value, bool $
 			null
 		);
 
+		$append_after_exhausted_cursor = $this->current_declaration >= $old_declaration_count;
+		$current_after_append          = $append_after_exhausted_cursor
+			? $old_declaration_count - 1
+			: $this->current_declaration;
+
+		$this->apply_lexical_updates(
+			$current_after_append,
+			$this->current_declaration_removed || $append_after_exhausted_cursor
+		);
+
 		return true;
 	}
 
@@ -662,13 +686,40 @@ private function is_ignored_token( array $token ): bool {
 	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}|null
 	 */
 	private function get_current_declaration(): ?array {
-		if ( $this->current_declaration < 0 || ! isset( $this->declarations[ $this->current_declaration ] ) ) {
+		if (
+			$this->current_declaration_removed ||
+			$this->current_declaration < 0 ||
+			! isset( $this->declarations[ $this->current_declaration ] )
+		) {
 			return null;
 		}
 
 		return $this->declarations[ $this->current_declaration ];
 	}
 
+	/**
+	 * Applies queued lexical updates and reparses the updated style attribute value.
+	 *
+	 * @param int  $current_declaration         Declaration index to keep before the next cursor advance.
+	 * @param bool $current_declaration_removed Optional. Whether the current declaration was removed.
+	 */
+	private function apply_lexical_updates( int $current_declaration, bool $current_declaration_removed = false ): void {
+		$this->style = $this->get_updated_style();
+
+		$this->tokens                      = array();
+		$this->declarations                = array();
+		$this->lexical_updates             = array();
+		$this->lexical_update_order        = 0;
+		$this->current_declaration         = $current_declaration;
+		$this->current_declaration_removed = $current_declaration_removed;
+
+		$this->parse();
+
+		if ( $this->current_declaration >= count( $this->declarations ) ) {
+			$this->current_declaration = count( $this->declarations );
+		}
+	}
+
 	/**
 	 * Queues a lexical update, replacing any earlier update for the same declaration.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 327fac293a60a..b7d825d5fd1b6 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -117,6 +117,25 @@ public function test_set_value_updates_current_declaration_without_collapsing_du
 		$this->assertSame( 'color: green; color: color(display-p3 1 0 0);', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::set_value
+	 * @covers ::get_value
+	 * @covers ::is_important
+	 */
+	public function test_getters_reflect_current_declaration_after_set_value() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( 'green', true ) );
+
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertSame( 'green', $processor->get_value() );
+		$this->assertTrue( $processor->is_important() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+	}
+
 	/**
 	 * @covers ::remove_declaration
 	 * @covers ::get_updated_style
@@ -131,6 +150,25 @@ public function test_remove_declaration_removes_only_current_duplicate() {
 		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_property_name
+	 * @covers ::get_value
+	 */
+	public function test_getters_return_null_after_removing_current_declaration_until_cursor_advances() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertNull( $processor->get_value() );
+		$this->assertFalse( $processor->is_important() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+	}
+
 	/**
 	 * @covers ::remove_declaration
 	 * @covers ::get_updated_style
@@ -170,6 +208,42 @@ public function test_append_declaration_preserves_multiple_appends_in_order() {
 		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::next_declaration
+	 */
+	public function test_appended_declarations_can_be_inspected_by_the_cursor() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertSame( 'red', $processor->get_value() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::next_declaration
+	 * @covers ::get_property_name
+	 */
+	public function test_append_declaration_preserves_exhausted_cursor_until_it_advances() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertFalse( $processor->next_declaration() );
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertNull( $processor->get_value() );
+		$this->assertFalse( $processor->set_value( 'green' ) );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'white', $processor->get_value() );
+		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::remove_declaration
 	 * @covers ::append_declaration

From 02ccb51f70cf720ab531cbc02d4eaacfbdbb7544 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 14:14:51 +0200
Subject: [PATCH 28/77] Respect comments when appending style declarations

---
 ...lass-wp-html-style-attribute-processor.php | 115 +++++++++++++++++-
 .../wpHtmlStyleAttributeProcessor.php         |  33 +++++
 2 files changed, 144 insertions(+), 4 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 803fc431799c5..ef7bc3a064f49 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -241,16 +241,17 @@ public function append_declaration( string $property_name, string $value, bool $
 		$old_declaration_count = count( $this->declarations );
 		$trimmed_style         = rtrim( $this->style, self::WHITESPACE );
 		$insert_at             = strlen( $trimmed_style );
-		$separator             = $this->has_queued_append_at( $insert_at ) ? ' ' : '';
+		$separator             = $this->get_append_separator( $insert_at );
+		$declaration_text      = $this->serialize_declaration( $property_name, $value, $important );
 
-		if ( '' === $separator && '' !== trim( $trimmed_style, self::WHITESPACE ) ) {
-			$separator = ( ';' === substr( $trimmed_style, -1 ) ) ? ' ' : '; ';
+		if ( ! $this->is_parseable_append( $insert_at, $separator, $declaration_text, $old_declaration_count ) ) {
+			return false;
 		}
 
 		$this->queue_lexical_update(
 			$insert_at,
 			0,
-			$separator . $this->serialize_declaration( $property_name, $value, $important ),
+			$separator . $declaration_text,
 			null
 		);
 
@@ -762,6 +763,112 @@ private function has_queued_append_at( int $insert_at ): bool {
 		return false;
 	}
 
+	/**
+	 * Gets the separator to use before an appended declaration.
+	 *
+	 * Comments and whitespace are CSS parser trivia. They do not determine
+	 * whether the existing declaration list needs a semicolon before appending.
+	 *
+	 * @param int $insert_at Byte offset at which the declaration will be inserted.
+	 * @return string Separator text.
+	 */
+	private function get_append_separator( int $insert_at ): string {
+		if ( $this->has_queued_append_at( $insert_at ) ) {
+			return ' ';
+		}
+
+		$last_token = $this->get_last_top_level_non_ignored_token_before( $insert_at );
+
+		if ( null === $last_token ) {
+			return $insert_at > 0 ? ' ' : '';
+		}
+
+		return WP_CSS_Token_Processor::TOKEN_SEMICOLON === $last_token['type'] ? ' ' : '; ';
+	}
+
+	/**
+	 * Gets the last top-level non-ignored token before a byte offset.
+	 *
+	 * @param int $insert_at Byte offset before which to scan.
+	 * @return array{type:string, value:string|null, start:int, length:int, end:int}|null Token metadata.
+	 */
+	private function get_last_top_level_non_ignored_token_before( int $insert_at ): ?array {
+		$count      = count( $this->tokens );
+		$index      = 0;
+		$last_token = null;
+
+		while ( $index < $count ) {
+			$token = $this->tokens[ $index ];
+
+			if ( $token['start'] >= $insert_at ) {
+				break;
+			}
+
+			if ( $this->is_ignored_token( $token ) ) {
+				++$index;
+				continue;
+			}
+
+			$last_token = $token;
+
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				continue;
+			}
+
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				continue;
+			}
+
+			++$index;
+		}
+
+		return $last_token;
+	}
+
+	/**
+	 * Checks whether an appended declaration will parse as a new declaration.
+	 *
+	 * Malformed existing declarations can leave the append point inside an
+	 * unclosed component value. In that case preserving the original text and
+	 * appending a top-level declaration are incompatible.
+	 *
+	 * @param int    $insert_at             Byte offset at which the declaration will be inserted.
+	 * @param string $separator             Separator text.
+	 * @param string $declaration_text      Serialized declaration text.
+	 * @param int    $old_declaration_count Number of declarations before appending.
+	 * @return bool Whether the appended declaration is parseable.
+	 */
+	private function is_parseable_append( int $insert_at, string $separator, string $declaration_text, int $old_declaration_count ): bool {
+		$expected_start  = $insert_at + strlen( $separator );
+		$expected_after  = $expected_start + strlen( $declaration_text );
+		$candidate_style = substr( $this->style, 0, $insert_at ) . $separator . $declaration_text . substr( $this->style, $insert_at );
+		$candidate       = new self( $candidate_style );
+
+		if ( count( $candidate->declarations ) !== $old_declaration_count + 1 ) {
+			return false;
+		}
+
+		foreach ( $candidate->declarations as $declaration ) {
+			if ( $expected_start === $declaration['start'] && $expected_after === $declaration['after'] ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 	/**
 	 * Merges overlapping lexical updates into non-overlapping replacements.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index b7d825d5fd1b6..7f4d108f6773f 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -208,6 +208,39 @@ public function test_append_declaration_preserves_multiple_appends_in_order() {
 		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_treats_comments_as_trivia_for_separators() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+		$this->assertSame( '/*keep*/ color: red;', $processor->get_updated_style() );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;/*keep*/' );
+
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( 'color: red;/*keep*/ background: white;', $processor->get_updated_style() );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x;/*keep*/);' );
+
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( 'color: var(--x;/*keep*/); background: white;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_rejects_unclosed_component_value_append_points() {
+		$style     = 'color: var(--x;/*keep*/';
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+
+		$this->assertFalse( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( $style, $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::next_declaration

From c5e8fcd55423e9816dfcf979b4db8853057863bf Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 14:22:43 +0200
Subject: [PATCH 29/77] Preserve comments when removing style declarations

---
 ...lass-wp-html-style-attribute-processor.php | 42 +++++++++++++++----
 .../wpHtmlStyleAttributeProcessor.php         | 24 +++++++++++
 2 files changed, 58 insertions(+), 8 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index ef7bc3a064f49..46e2158aee8e8 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -202,18 +202,14 @@ public function remove_declaration(): bool {
 			return false;
 		}
 
-		if ( '' === trim( substr( $this->style, 0, $declaration['leading_start'] ), self::WHITESPACE ) ) {
-			$remove_start = $declaration['leading_start'];
-			$remove_end   = $declaration['trailing_end'];
-		} else {
-			$remove_start = $declaration['leading_start'];
-			$remove_end   = $declaration['after'];
-		}
+		$remove_start = $this->get_offset_before_preceding_whitespace( $declaration['start'] );
+		$remove_end   = $this->get_offset_after_following_whitespace( $declaration['after'] );
+		$replacement  = ( $remove_start > 0 && $remove_end < strlen( $this->style ) ) ? ' ' : '';
 
 		$this->queue_lexical_update(
 			$remove_start,
 			$remove_end - $remove_start,
-			'',
+			$replacement,
 			$this->current_declaration
 		);
 
@@ -681,6 +677,36 @@ private function is_ignored_token( array $token ): bool {
 		);
 	}
 
+	/**
+	 * Gets the byte offset before contiguous whitespace ending at an offset.
+	 *
+	 * @param int $offset Byte offset.
+	 * @return int Offset before preceding whitespace.
+	 */
+	private function get_offset_before_preceding_whitespace( int $offset ): int {
+		while ( $offset > 0 && false !== strpos( self::WHITESPACE, $this->style[ $offset - 1 ] ) ) {
+			--$offset;
+		}
+
+		return $offset;
+	}
+
+	/**
+	 * Gets the byte offset after contiguous whitespace beginning at an offset.
+	 *
+	 * @param int $offset Byte offset.
+	 * @return int Offset after following whitespace.
+	 */
+	private function get_offset_after_following_whitespace( int $offset ): int {
+		$length = strlen( $this->style );
+
+		while ( $offset < $length && false !== strpos( self::WHITESPACE, $this->style[ $offset ] ) ) {
+			++$offset;
+		}
+
+		return $offset;
+	}
+
 	/**
 	 * Gets the current declaration metadata.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 7f4d108f6773f..c85105419eeaf 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -183,6 +183,30 @@ public function test_remove_declaration_removes_adjacent_duplicate_declarations(
 		$this->assertSame( 'background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_remove_declaration_preserves_surrounding_comments() {
+		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/ color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
+
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertSame( 'color: red; /*keep*/', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style

From 36da63ae06dd8c56ab50aa18bea6e3c6dafcdda7 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 29 Jun 2026 16:20:24 +0200
Subject: [PATCH 30/77] Lazily parse style attribute declarations

---
 ...lass-wp-html-style-attribute-processor.php | 53 +++++++++++++++----
 .../wpHtmlStyleAttributeProcessor.php         | 11 ++++
 2 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 46e2158aee8e8..868934202c8fb 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -10,10 +10,15 @@
 /**
  * Core class used to inspect and modify CSS declarations in an HTML style attribute.
  *
- * The processor operates on decoded style attribute values. Values read from
- * {@see WP_HTML_Tag_Processor::get_attribute()} can be passed directly to this
- * class, and values returned by {@see WP_HTML_Style_Attribute_Processor::get_updated_style()}
- * can be passed back to {@see WP_HTML_Tag_Processor::set_attribute()}.
+ * The processor operates on the decoded CSS text value of a style attribute:
+ * the CSS declaration-list contents of a declaration block, excluding the
+ * delimiting braces. It does not parse HTML attribute syntax, decode character
+ * references, or operate on raw HTML markup.
+ *
+ * Values read from {@see WP_HTML_Tag_Processor::get_attribute()} can be passed
+ * directly to this class, and values returned by
+ * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} can be passed
+ * back to {@see WP_HTML_Tag_Processor::set_attribute()}.
  *
  * Unlike associative-array based style helpers, this processor preserves the
  * declaration list model of CSS. Multiple declarations with the same property
@@ -50,6 +55,13 @@ class WP_HTML_Style_Attribute_Processor {
 	 */
 	private $declarations = array();
 
+	/**
+	 * Whether the style attribute value has been parsed.
+	 *
+	 * @var bool
+	 */
+	private $parsed = false;
+
 	/**
 	 * Index of the current declaration, or -1 before the first declaration.
 	 *
@@ -81,7 +93,7 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Constructor.
 	 *
-	 * @param string|bool|null $style Decoded style attribute value.
+	 * @param string|bool|null $style Decoded CSS text value from a style attribute.
 	 */
 	public function __construct( $style = '' ) {
 		if ( null === $style || true === $style ) {
@@ -91,7 +103,6 @@ public function __construct( $style = '' ) {
 		}
 
 		$this->style = $style;
-		$this->parse();
 	}
 
 	/**
@@ -100,10 +111,12 @@ public function __construct( $style = '' ) {
 	 * When a property name is provided, normal CSS properties are matched
 	 * ASCII-case-insensitively while custom properties are matched exactly.
 	 *
-	 * @param string|null $property_name Optional property name to match.
+	 * @param string|null $property_name Optional declaration property name to match.
 	 * @return bool Whether a matching declaration was found.
 	 */
 	public function next_declaration( ?string $property_name = null ): bool {
+		$this->ensure_parsed();
+
 		for ( $i = $this->current_declaration + 1; $i < count( $this->declarations ); $i++ ) {
 			if (
 				null === $property_name ||
@@ -234,6 +247,8 @@ public function append_declaration( string $property_name, string $value, bool $
 			return false;
 		}
 
+		$this->ensure_parsed();
+
 		$old_declaration_count = count( $this->declarations );
 		$trimmed_style         = rtrim( $this->style, self::WHITESPACE );
 		$insert_at             = strlen( $trimmed_style );
@@ -265,9 +280,9 @@ public function append_declaration( string $property_name, string $value, bool $
 	}
 
 	/**
-	 * Returns the updated style attribute value.
+	 * Returns the updated decoded CSS text value for the style attribute.
 	 *
-	 * @return string Updated style attribute value.
+	 * @return string Updated decoded CSS text value for the style attribute.
 	 */
 	public function get_updated_style(): string {
 		if ( empty( $this->lexical_updates ) ) {
@@ -305,8 +320,12 @@ static function ( $a, $b ) {
 	 * Parses CSS tokens and declarations from the style attribute value.
 	 */
 	private function parse(): void {
+		$this->tokens       = array();
+		$this->declarations = array();
+
 		$processor = WP_CSS_Token_Processor::create( $this->style );
 		if ( null === $processor ) {
+			$this->parsed = true;
 			return;
 		}
 
@@ -323,6 +342,18 @@ private function parse(): void {
 		}
 
 		$this->parse_declaration_list();
+		$this->parsed = true;
+	}
+
+	/**
+	 * Lazily parses the style attribute value when declaration access needs it.
+	 */
+	private function ensure_parsed(): void {
+		if ( $this->parsed ) {
+			return;
+		}
+
+		$this->parse();
 	}
 
 	/**
@@ -733,12 +764,11 @@ private function get_current_declaration(): ?array {
 	private function apply_lexical_updates( int $current_declaration, bool $current_declaration_removed = false ): void {
 		$this->style = $this->get_updated_style();
 
-		$this->tokens                      = array();
-		$this->declarations                = array();
 		$this->lexical_updates             = array();
 		$this->lexical_update_order        = 0;
 		$this->current_declaration         = $current_declaration;
 		$this->current_declaration_removed = $current_declaration_removed;
+		$this->parsed                      = false;
 
 		$this->parse();
 
@@ -881,6 +911,7 @@ private function is_parseable_append( int $insert_at, string $separator, string
 		$expected_after  = $expected_start + strlen( $declaration_text );
 		$candidate_style = substr( $this->style, 0, $insert_at ) . $separator . $declaration_text . substr( $this->style, $insert_at );
 		$candidate       = new self( $candidate_style );
+		$candidate->ensure_parsed();
 
 		if ( count( $candidate->declarations ) !== $old_declaration_count + 1 ) {
 			return false;
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index c85105419eeaf..40b986f326594 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -84,6 +84,17 @@ public function test_next_declaration_query_visits_matching_duplicate_properties
 		$this->assertFalse( $processor->next_declaration( '--tone' ) );
 	}
 
+	/**
+	 * @covers ::next_declaration
+	 */
+	public function test_next_declaration_accepts_named_property_name_argument() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( property_name: 'background' ) );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'white', $processor->get_value() );
+	}
+
 	/**
 	 * @covers ::is_important
 	 * @covers ::get_value

From b7c0f685a5bb1aa29c73fbacc00fe841d2dc6915 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 30 Jun 2026 00:42:51 +0200
Subject: [PATCH 31/77] Document style attribute processor contract

---
 .../wp-html-style-attribute-processor-spec.md | 281 ++++++++++++++++++
 1 file changed, 281 insertions(+)
 create mode 100644 docs/wp-html-style-attribute-processor-spec.md

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
new file mode 100644
index 0000000000000..c1d23cfe7c223
--- /dev/null
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -0,0 +1,281 @@
+# WP_HTML_Style_Attribute_Processor Specification
+
+## Purpose
+
+`WP_HTML_Style_Attribute_Processor` inspects and modifies decoded CSS text from an
+HTML `style` attribute. Its input is the declaration-list contents of the
+attribute, excluding HTML attribute syntax, entity decoding, and any surrounding
+declaration-block braces.
+
+The processor preserves the CSS declaration-list model. Duplicate declarations
+remain distinct. Invalid CSS fragments are skipped or preserved according to CSS
+parser semantics unless a requested mutation cannot be proven safe.
+
+The processor's north star is:
+
+1. preserve CSS structure;
+2. preserve user intent;
+3. preserve the semantic CSS value of any existing declaration it rewrites;
+4. make minimal edits when doing so does not compromise the first three goals.
+
+## Construction
+
+Creation uses:
+
+```php
+WP_HTML_Style_Attribute_Processor::create( string $decoded_css_text ): static
+```
+
+The constructor is private. `create()` always returns a processor instance for a
+string input.
+
+Callers must not pass raw `WP_HTML_Tag_Processor::get_attribute( 'style' )`
+results directly unless they have already checked that the result is a string.
+Missing or boolean attributes are an HTML-layer concern, not accepted CSS text.
+
+Parsing is lazy. Creating a processor does not scan the style text until cursor
+movement, mutation validation, or serialization requires it.
+
+## Declaration Model
+
+The processor models each CSS declaration as:
+
+```text
+property-name: component-value-list !important?
+```
+
+The internal declaration data consists of:
+
+- decoded property name;
+- authored property-name source when available;
+- value component list source range;
+- `!important` flag;
+- nullable source range for the parsed priority span;
+- source ranges needed for safe mutation and verification.
+
+`!important` is not part of the value, including for custom properties.
+
+## Public API
+
+Initial public methods:
+
+```php
+public static function create( string $decoded_css_text ): static;
+public function next_declaration( ?string $property_name = null ): bool;
+public function get_property_name(): ?string;
+public function is_important(): ?bool;
+public function set_value( string $value, ?bool $important = null ): bool;
+public function set_important( bool $important ): bool;
+public function remove_declaration(): bool;
+public function append_declaration( string $property_name, string $value, bool $important = false ): bool;
+public function get_updated_style(): string;
+```
+
+The first API does not expose `get_value()` or `get_raw_value()`. Raw CSS values
+are difficult for callers to use safely, and a higher-level value API needs a
+separate design.
+
+Bookmarks, seek, and rewind are out of scope. Callers that need to rescan should
+create a new processor from the updated style text.
+
+## Cursor Semantics
+
+`next_declaration()` advances a forward-only cursor over CSS declarations.
+
+All current-declaration getters return `null` when the cursor is not positioned
+on a valid declaration. This includes `is_important()`.
+
+After `remove_declaration()` succeeds, the cursor becomes invalid until
+`next_declaration()` advances it. A second removal on the same invalid cursor
+returns `false`.
+
+After `set_value()` or `set_important()` succeeds without removing the
+declaration, the cursor remains on the same logical declaration.
+
+`set_value( '' )` removes the current declaration. On success it has the same
+cursor semantics as `remove_declaration()`.
+
+`append_declaration()` does not move the cursor. If the cursor was exhausted, it
+remains invalid until a later `next_declaration()` advances to the appended
+declaration.
+
+`next_declaration()` flushes pending safe edits before advancing because
+advancement must reflect the updated declaration list.
+
+Current-position getters should reflect successful pending edits without forcing
+a full reparse where practical, following HTML API style.
+
+## Property Names
+
+All public property-name arguments are decoded/plaintext CSS property names, not
+CSS-escaped identifier source.
+
+Ordinary properties match ASCII case-insensitively. Custom properties match
+exactly because casing is semantic.
+
+`get_property_name()` exposes CSS semantics:
+
+- ordinary property names are returned lowercase;
+- custom property names preserve exact decoded casing.
+
+Edits preserve authored property-name spelling when the declaration already
+exists. Appended ordinary properties serialize lowercase because there is no
+authored spelling to preserve. Appended custom properties preserve exact casing.
+
+Appended property names must be valid plaintext CSS property names. The processor
+does not escape arbitrary strings into identifiers. Custom properties follow the
+same validity rule with the required `--` prefix.
+
+## Value Validation
+
+Mutation inputs accept CSS declaration values, not declaration-list text.
+
+The supplied value must fit safely in both of these declaration slots, depending
+on the property being changed:
+
+```css
+foo: <value>;
+--foo: <value>;
+```
+
+Validation checks structure and CSS syntax safety, not property-specific browser
+support. The processor should not maintain a browser-style matrix of supported
+properties and value grammars.
+
+Values must be complete and self-contained. Reject inputs that:
+
+- are empty after CSS whitespace trimming, except `set_value( '' )`, which
+  removes the current declaration;
+- contain top-level declaration separators such as semicolons;
+- contain a top-level `!important`, because priority is a separate argument;
+- contain bad strings or bad URLs;
+- contain unmatched delimiters or constructs that are valid only because CSS
+  closes them at EOF;
+- cannot be proven to occupy only the declaration value slot.
+
+Nested semicolons and `!important` text inside balanced blocks, functions,
+strings, or URLs are allowed when the tokenizer and parser say they are part of
+the value.
+
+## Importance
+
+`set_value( $value, null )` preserves the existing important flag.
+`set_value( $value, true )` sets it.
+`set_value( $value, false )` clears it.
+
+`append_declaration()` receives importance as a separate boolean and rejects a
+top-level `!important` in `$value`.
+
+`set_important()` changes only declaration priority.
+
+When clearing importance, the processor may remove only the parsed priority span
+when that is safe. If minimal removal is unsafe, it may normalize the current
+declaration as long as it preserves CSS structure and the existing value's
+semantics. If that cannot be proven, it returns `false`.
+
+When setting importance, the processor adds canonical ` !important` at the
+parsed value end or normalizes the declaration if necessary. It must verify that
+the updated declaration reparses as important.
+
+## Mutation Atomicity And Verification
+
+Invalid or inapplicable mutations return `false` without `_doing_it_wrong()`.
+
+Failed mutations are atomic: style text, cursor state, and previous successful
+edits are preserved.
+
+A mutation returning `true` guarantees that `get_updated_style()` includes it.
+
+Every successful mutation must preserve the expected declaration-list structure.
+`set_value()` must not let an input value merge, split, hide, or otherwise change
+declarations beyond the intended current declaration.
+
+The public contract describes guarantees, not the exact validation mechanism.
+Synthetic declarations, parser comparisons, token-level checks, and reparsing are
+implementation details.
+
+Multiple mutations to the same logical declaration collapse to the final
+intended state. Mutations to different declarations in one pass are allowed when
+each mutation can be independently verified against the updated declaration
+list.
+
+## Formatting And Normalization
+
+The processor preserves surrounding text, comments, ignored invalid fragments,
+and authored spelling when cheap and safe.
+
+Minimal edits are a lower priority than safety, correctness, preserved CSS
+structure, and semantic preservation. Any normalization required to satisfy
+those higher priorities is allowed, but normalization that rewrites an existing
+declaration value must be strict: it must serialize from parsed token/component
+data with equivalent CSS semantics. If equivalence cannot be proven, the
+mutation returns `false`.
+
+`set_value()` trims supplied values according to CSS whitespace.
+
+When possible, `set_value()` replaces the current declaration's value and
+priority portion rather than normalizing the whole declaration. Correctness wins
+over whitespace preservation.
+
+## Invalid Fragments
+
+Declaration discovery follows CSS semantics. If CSS would ignore text as a
+declaration in a style attribute declaration-list context, the processor does
+not expose it as a declaration.
+
+Ignored invalid fragments are preserved where possible. Mutations touching a
+style containing invalid chunks must verify that the declaration-list structure
+remains safe. If preservation and a requested mutation are incompatible, the
+mutation returns `false` or normalizes only the range necessary to preserve
+semantics and structure.
+
+## Append And EOF Repair
+
+`append_declaration()` may succeed even when trailing text is malformed, but only
+when the processor can preserve existing CSS semantics.
+
+When trailing declaration text is valid only because CSS closes an unclosed
+function or block at EOF, appending must materialize the missing closing
+delimiters before inserting the new declaration.
+
+Example:
+
+```css
+color: var(--x
+```
+
+Appending `background: white` should produce a structurally safe equivalent such
+as:
+
+```css
+color: var(--x); background: white;
+```
+
+EOF repair is part of a successful append and appears in `get_updated_style()`.
+Repair should insert only the specific missing delimiters discovered from parser
+or tokenizer state, plus the boundary needed before the appended declaration. If
+the processor cannot determine a precise repair, append returns `false`.
+
+EOF repair is essential for append. `set_value()` replacement values must be
+self-contained and do not receive EOF repair.
+
+## Test Requirements
+
+Tests should cover:
+
+- private construction and `create()` behavior;
+- decoded string input boundary;
+- declaration traversal, duplicate preservation, and property-name matching;
+- getter `null` behavior off-cursor;
+- absence of public raw value getter in the first API;
+- `set_value()` priority preservation, setting, clearing, and empty-value
+  removal;
+- `set_important()` setting, clearing, cursor behavior, and safe normalization;
+- rejection of unsafe values and property names with atomic failure;
+- append behavior, duplicate appends, exhausted cursor behavior, and empty-value
+  rejection;
+- EOF repair for append and failure when repair cannot be precise;
+- invalid fragments, comments, adjacent declarations, and removal ranges;
+- preservation of authored spelling where required;
+- integration with `WP_HTML_Tag_Processor::set_attribute()` after callers supply
+  decoded string input.

From 9ebe88df9dfacd142284b2b49c9088b6f48ecc46 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 30 Jun 2026 01:33:44 +0200
Subject: [PATCH 32/77] Clarify style processor factory contract

---
 docs/wp-html-style-attribute-processor-spec.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index c1d23cfe7c223..3728c39f520e0 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -23,11 +23,14 @@ The processor's north star is:
 Creation uses:
 
 ```php
-WP_HTML_Style_Attribute_Processor::create( string $decoded_css_text ): static
+WP_HTML_Style_Attribute_Processor::create( $decoded_css_text )
 ```
 
-The constructor is private. `create()` always returns a processor instance for a
-string input.
+The constructor is private. `create()` accepts only string input and returns a
+processor instance of the called class. The implementation must remain
+compatible with WordPress' supported PHP versions, so the runtime signature may
+use PHPDoc and explicit validation instead of PHP syntax unavailable in those
+versions.
 
 Callers must not pass raw `WP_HTML_Tag_Processor::get_attribute( 'style' )`
 results directly unless they have already checked that the result is a string.
@@ -60,7 +63,7 @@ The internal declaration data consists of:
 Initial public methods:
 
 ```php
-public static function create( string $decoded_css_text ): static;
+public static function create( $decoded_css_text );
 public function next_declaration( ?string $property_name = null ): bool;
 public function get_property_name(): ?string;
 public function is_important(): ?bool;

From 46ca9fa41a91cadd6735024e1ac136fb7307cbfa Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 30 Jun 2026 01:33:52 +0200
Subject: [PATCH 33/77] Implement style attribute processor contract

---
 ...lass-wp-html-style-attribute-processor.php | 520 +++++++++++++++---
 .../wpHtmlStyleAttributeProcessor.php         | 510 ++++++++++++-----
 2 files changed, 821 insertions(+), 209 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 868934202c8fb..fffd59060c9db 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -15,10 +15,12 @@
  * delimiting braces. It does not parse HTML attribute syntax, decode character
  * references, or operate on raw HTML markup.
  *
- * Values read from {@see WP_HTML_Tag_Processor::get_attribute()} can be passed
- * directly to this class, and values returned by
+ * String values read from {@see WP_HTML_Tag_Processor::get_attribute()} can be
+ * passed to this class, and values returned by
  * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} can be passed
- * back to {@see WP_HTML_Tag_Processor::set_attribute()}.
+ * back to {@see WP_HTML_Tag_Processor::set_attribute()}. Missing and boolean
+ * style attributes are an HTML concern and must be handled before creating this
+ * processor.
  *
  * Unlike associative-array based style helpers, this processor preserves the
  * declaration list model of CSS. Multiple declarations with the same property
@@ -32,7 +34,7 @@ class WP_HTML_Style_Attribute_Processor {
 	 *
 	 * @var string
 	 */
-	const WHITESPACE = " \t\n\r\f";
+	private const WHITESPACE = " \t\n\r\f";
 
 	/**
 	 * Decoded style attribute value.
@@ -51,7 +53,7 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Parsed declarations.
 	 *
-	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}>
+	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
 
@@ -93,16 +95,27 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Constructor.
 	 *
-	 * @param string|bool|null $style Decoded CSS text value from a style attribute.
+	 * Do not instantiate directly. Use
+	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
+	 *
+	 * @param string $style Decoded CSS text value from a style attribute.
+	 */
+	private function __construct( string $style ) {
+		$this->style = $style;
+	}
+
+	/**
+	 * Creates a processor for decoded CSS text from a style attribute.
+	 *
+	 * @param string $decoded_css_text Decoded CSS text value from a style attribute.
+	 * @return static Created processor.
 	 */
-	public function __construct( $style = '' ) {
-		if ( null === $style || true === $style ) {
-			$style = '';
-		} elseif ( ! is_string( $style ) ) {
-			$style = '';
+	public static function create( $decoded_css_text ) {
+		if ( ! is_string( $decoded_css_text ) ) {
+			throw new TypeError( __METHOD__ . '(): Argument #1 ($decoded_css_text) must be of type string' );
 		}
 
-		$this->style = $style;
+		return new static( $decoded_css_text );
 	}
 
 	/**
@@ -143,33 +156,15 @@ public function get_property_name(): ?string {
 		return null === $declaration ? null : $declaration['name'];
 	}
 
-	/**
-	 * Gets the current declaration's CSS value.
-	 *
-	 * The returned value does not include a trailing !important priority.
-	 *
-	 * @return string|null CSS value, or null when not on a declaration.
-	 */
-	public function get_value(): ?string {
-		$declaration = $this->get_current_declaration();
-		if ( null === $declaration ) {
-			return null;
-		}
-
-		return trim(
-			substr( $this->style, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
-			self::WHITESPACE
-		);
-	}
-
 	/**
 	 * Indicates whether the current declaration has an !important priority.
 	 *
-	 * @return bool Whether the current declaration has an !important priority.
+	 * @return bool|null Whether the current declaration has an !important priority,
+	 *                   or null when not on a declaration.
 	 */
-	public function is_important(): bool {
+	public function is_important(): ?bool {
 		$declaration = $this->get_current_declaration();
-		return null !== $declaration && $declaration['important'];
+		return null === $declaration ? null : $declaration['important'];
 	}
 
 	/**
@@ -182,12 +177,37 @@ public function is_important(): bool {
 	 */
 	public function set_value( string $value, ?bool $important = null ): bool {
 		$declaration = $this->get_current_declaration();
-		if ( null === $declaration || ! $this->is_valid_declaration_value( $value ) ) {
+		if ( null === $declaration ) {
+			return false;
+		}
+
+		if ( '' === $value ) {
+			return $this->remove_declaration();
+		}
+
+		if ( ! $this->is_valid_declaration_value( $value ) ) {
 			return false;
 		}
 
 		$is_important = null === $important ? $declaration['important'] : $important;
 		$text         = $this->serialize_declaration( $declaration['raw_name'], $value, $is_important );
+		$parsed_value = $this->get_parsed_declaration_value( $text );
+		if ( null === $parsed_value ) {
+			return false;
+		}
+
+		if (
+			! $this->is_current_declaration_replacement_safe(
+				$declaration,
+				$declaration['start'],
+				$declaration['after'] - $declaration['start'],
+				$text,
+				$is_important,
+				$parsed_value
+			)
+		) {
+			return false;
+		}
 
 		$this->queue_lexical_update(
 			$declaration['start'],
@@ -201,6 +221,98 @@ public function set_value( string $value, ?bool $important = null ): bool {
 		return true;
 	}
 
+	/**
+	 * Sets the !important priority of the current declaration.
+	 *
+	 * @param bool $important Whether the declaration should be important.
+	 * @return bool Whether the current declaration priority is set as requested.
+	 */
+	public function set_important( bool $important ): bool {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration ) {
+			return false;
+		}
+
+		if ( $important === $declaration['important'] ) {
+			return true;
+		}
+
+		if ( $important ) {
+			if ( $declaration['value_start'] >= $declaration['value_end'] ) {
+				return false;
+			}
+
+			$insert_at   = $declaration['value_end'];
+			$insert_text = ' !important';
+			if (
+				! $this->is_current_declaration_replacement_safe(
+					$declaration,
+					$declaration['value_end'],
+					0,
+					$insert_text,
+					true
+				)
+			) {
+				$eof_repair    = strlen( $this->style ) === $declaration['after']
+					? $this->get_eof_repair( $declaration['after'] )
+					: null;
+				$current_value = substr( $this->style, $declaration['value_start'], $declaration['after'] - $declaration['value_start'] );
+
+				if (
+					null === $eof_repair ||
+					'' === $eof_repair ||
+					! $this->is_current_declaration_replacement_safe(
+						$declaration,
+						$declaration['after'],
+						0,
+						$eof_repair . $insert_text,
+						true,
+						trim( $current_value . $eof_repair, self::WHITESPACE )
+					)
+				) {
+					return false;
+				}
+
+				$insert_at   = $declaration['after'];
+				$insert_text = $eof_repair . $insert_text;
+			}
+
+			$this->queue_lexical_update(
+				$insert_at,
+				0,
+				$insert_text,
+				$this->current_declaration
+			);
+		} else {
+			if ( null === $declaration['important_start'] || null === $declaration['important_end'] ) {
+				return false;
+			}
+
+			if (
+				! $this->is_current_declaration_replacement_safe(
+					$declaration,
+					$declaration['important_start'],
+					$declaration['important_end'] - $declaration['important_start'],
+					'',
+					false
+				)
+			) {
+				return false;
+			}
+
+			$this->queue_lexical_update(
+				$declaration['important_start'],
+				$declaration['important_end'] - $declaration['important_start'],
+				'',
+				$this->current_declaration
+			);
+		}
+
+		$this->apply_lexical_updates( $this->current_declaration );
+
+		return true;
+	}
+
 	/**
 	 * Removes the current declaration from the style attribute value.
 	 *
@@ -219,6 +331,10 @@ public function remove_declaration(): bool {
 		$remove_end   = $this->get_offset_after_following_whitespace( $declaration['after'] );
 		$replacement  = ( $remove_start > 0 && $remove_end < strlen( $this->style ) ) ? ' ' : '';
 
+		if ( ! $this->is_remove_declaration_safe( $this->current_declaration, $remove_start, $remove_end - $remove_start, $replacement ) ) {
+			return false;
+		}
+
 		$this->queue_lexical_update(
 			$remove_start,
 			$remove_end - $remove_start,
@@ -243,7 +359,11 @@ public function remove_declaration(): bool {
 	 * @return bool Whether the declaration was appended.
 	 */
 	public function append_declaration( string $property_name, string $value, bool $important = false ): bool {
-		if ( ! $this->is_valid_property_name( $property_name ) || ! $this->is_valid_declaration_value( $value ) ) {
+		if (
+			'' === trim( $value, self::WHITESPACE ) ||
+			! $this->is_valid_property_name( $property_name ) ||
+			! $this->is_valid_declaration_value( $value )
+		) {
 			return false;
 		}
 
@@ -252,17 +372,28 @@ public function append_declaration( string $property_name, string $value, bool $
 		$old_declaration_count = count( $this->declarations );
 		$trimmed_style         = rtrim( $this->style, self::WHITESPACE );
 		$insert_at             = strlen( $trimmed_style );
-		$separator             = $this->get_append_separator( $insert_at );
-		$declaration_text      = $this->serialize_declaration( $property_name, $value, $important );
+		$repair_at             = strlen( $this->style );
+		$eof_repair            = $this->get_eof_repair( $repair_at );
+		if ( null === $eof_repair ) {
+			return false;
+		}
+
+		$separator        = $this->get_append_separator( $insert_at );
+		$serialized_name  = $this->is_custom_property_name( $property_name ) ? $property_name : strtolower( $property_name );
+		$declaration_text = $this->serialize_declaration( $serialized_name, $value, $important );
+		$parsed_value     = $this->get_parsed_declaration_value( $declaration_text );
+		if ( null === $parsed_value ) {
+			return false;
+		}
 
-		if ( ! $this->is_parseable_append( $insert_at, $separator, $declaration_text, $old_declaration_count ) ) {
+		if ( ! $this->is_parseable_append( $repair_at, $eof_repair, $separator, $declaration_text, $old_declaration_count, $serialized_name, $parsed_value, $important ) ) {
 			return false;
 		}
 
 		$this->queue_lexical_update(
-			$insert_at,
+			$repair_at,
 			0,
-			$separator . $declaration_text,
+			$eof_repair . $separator . $declaration_text,
 			null
 		);
 
@@ -535,7 +666,7 @@ private function consume_declaration_segment( int $index ): array {
 	 * @param int $start_index   First token index in the segment.
 	 * @param int $end_index     Token index after the segment.
 	 * @param int $after         Byte offset after the declaration.
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}|null
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
 		$index = $this->skip_ignored_tokens( $start_index, $end_index );
@@ -549,6 +680,8 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 			return null;
 		}
 
+		$name = $this->is_custom_property_name( $name ) ? $name : strtolower( $name );
+
 		++$index;
 		$index = $this->skip_ignored_tokens( $index, $end_index );
 
@@ -560,6 +693,8 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 		$value_start_index = $this->skip_ignored_tokens( $index + 1, $end_index );
 		$value_end_index   = $this->trim_ignored_tokens( $value_start_index, $end_index );
 		$important         = false;
+		$important_start   = null;
+		$important_end     = null;
 		$top_level_tokens  = $this->get_top_level_non_ignored_token_indexes( $value_start_index, $value_end_index );
 		$top_level_count   = count( $top_level_tokens );
 		$last_value_index  = $top_level_count > 0 ? $top_level_tokens[ $top_level_count - 1 ] : null;
@@ -574,6 +709,8 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 			'!' === $this->tokens[ $before_last_index ]['value']
 		) {
 			$important       = true;
+			$important_start = $this->tokens[ $before_last_index ]['start'];
+			$important_end   = $this->tokens[ $last_value_index ]['end'];
 			$value_end_index = $this->trim_ignored_tokens( $value_start_index, $before_last_index );
 		}
 
@@ -586,15 +723,17 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 		}
 
 		return array(
-			'name'          => $name,
-			'raw_name'      => substr( $this->style, $name_token['start'], $name_token['length'] ),
-			'leading_start' => $leading_start,
-			'start'         => $name_token['start'],
-			'after'         => $after,
-			'trailing_end'  => $after,
-			'value_start'   => $value_start,
-			'value_end'     => $value_end,
-			'important'     => $important,
+			'name'            => $name,
+			'raw_name'        => substr( $this->style, $name_token['start'], $name_token['length'] ),
+			'leading_start'   => $leading_start,
+			'start'           => $name_token['start'],
+			'after'           => $after,
+			'trailing_end'    => $after,
+			'value_start'     => $value_start,
+			'value_end'       => $value_end,
+			'important'       => $important,
+			'important_start' => $important_start,
+			'important_end'   => $important_end,
 		);
 	}
 
@@ -741,7 +880,7 @@ private function get_offset_after_following_whitespace( int $offset ): int {
 	/**
 	 * Gets the current declaration metadata.
 	 *
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool}|null
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function get_current_declaration(): ?array {
 		if (
@@ -755,6 +894,122 @@ private function get_current_declaration(): ?array {
 		return $this->declarations[ $this->current_declaration ];
 	}
 
+	/**
+	 * Checks whether a replacement preserves the current declaration's structure.
+	 *
+	 * @param array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
+	 * @param int                                                                                                                                                                                   $start              Byte offset at which to start the replacement.
+	 * @param int                                                                                                                                                                                   $length             Number of bytes to replace.
+	 * @param string                                                                                                                                                                                $text               Replacement text.
+	 * @param bool                                                                                                                                                                                  $expected_important Expected important flag after replacement.
+	 * @param string|null                                                                                                                                                                           $expected_value     Optional expected value source after replacement.
+	 * @return bool Whether the replacement is safe.
+	 */
+	private function is_current_declaration_replacement_safe( array $declaration, int $start, int $length, string $text, bool $expected_important, ?string $expected_value = null ): bool {
+		$candidate_style = substr( $this->style, 0, $start ) . $text . substr( $this->style, $start + $length );
+		$candidate       = new self( $candidate_style );
+		$candidate->ensure_parsed();
+
+		if (
+			count( $candidate->declarations ) !== count( $this->declarations ) ||
+			! isset( $candidate->declarations[ $this->current_declaration ] )
+		) {
+			return false;
+		}
+
+		$updated_declaration = $candidate->declarations[ $this->current_declaration ];
+		if (
+			$updated_declaration['name'] !== $declaration['name'] ||
+			$updated_declaration['important'] !== $expected_important
+		) {
+			return false;
+		}
+
+		$old_value = trim(
+			substr( $this->style, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
+			self::WHITESPACE
+		);
+		$new_value = trim(
+			substr( $candidate_style, $updated_declaration['value_start'], $updated_declaration['value_end'] - $updated_declaration['value_start'] ),
+			self::WHITESPACE
+		);
+
+		return null === $expected_value ? $old_value === $new_value : $expected_value === $new_value;
+	}
+
+	/**
+	 * Checks whether removing a declaration preserves remaining structure.
+	 *
+	 * @param int    $removed_declaration Removed declaration index.
+	 * @param int    $start               Byte offset at which to start the replacement.
+	 * @param int    $length              Number of bytes to replace.
+	 * @param string $text                Replacement text.
+	 * @return bool Whether the removal is safe.
+	 */
+	private function is_remove_declaration_safe( int $removed_declaration, int $start, int $length, string $text ): bool {
+		$candidate_style = substr( $this->style, 0, $start ) . $text . substr( $this->style, $start + $length );
+		$candidate       = new self( $candidate_style );
+		$candidate->ensure_parsed();
+
+		if ( count( $candidate->declarations ) !== count( $this->declarations ) - 1 ) {
+			return false;
+		}
+
+		$candidate_index = 0;
+		foreach ( $this->declarations as $index => $declaration ) {
+			if ( $removed_declaration === $index ) {
+				continue;
+			}
+
+			if ( ! isset( $candidate->declarations[ $candidate_index ] ) ) {
+				return false;
+			}
+
+			$candidate_declaration = $candidate->declarations[ $candidate_index ];
+			$value                 = trim(
+				substr( $this->style, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
+				self::WHITESPACE
+			);
+			$candidate_value       = trim(
+				substr( $candidate_style, $candidate_declaration['value_start'], $candidate_declaration['value_end'] - $candidate_declaration['value_start'] ),
+				self::WHITESPACE
+			);
+
+			if (
+				$candidate_declaration['name'] !== $declaration['name'] ||
+				$candidate_declaration['important'] !== $declaration['important'] ||
+				$candidate_value !== $value
+			) {
+				return false;
+			}
+
+			++$candidate_index;
+		}
+
+		return true;
+	}
+
+	/**
+	 * Gets the parsed value source from a serialized declaration.
+	 *
+	 * @param string $declaration_text Serialized declaration text.
+	 * @return string|null Parsed declaration value, or null if parsing failed.
+	 */
+	private function get_parsed_declaration_value( string $declaration_text ): ?string {
+		$processor = new self( $declaration_text );
+		$processor->ensure_parsed();
+
+		if ( 1 !== count( $processor->declarations ) ) {
+			return null;
+		}
+
+		$declaration = $processor->declarations[0];
+		return trim(
+			substr( $declaration_text, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
+			self::WHITESPACE
+		);
+	}
+
 	/**
 	 * Applies queued lexical updates and reparses the updated style attribute value.
 	 *
@@ -893,6 +1148,107 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 		return $last_token;
 	}
 
+	/**
+	 * Gets required closing delimiters before appending at EOF.
+	 *
+	 * CSS closes unterminated functions and simple blocks at EOF. Appending must
+	 * materialize those closers before adding a new declaration.
+	 *
+	 * @param int $insert_at Byte offset at which the declaration will be inserted.
+	 * @return string|null Closing delimiters, or null when repair cannot be precise.
+	 */
+	private function get_eof_repair( int $insert_at ): ?string {
+		$stack = array();
+
+		foreach ( $this->tokens as $token ) {
+			if ( $token['start'] >= $insert_at ) {
+				break;
+			}
+
+			if ( $token['end'] > $insert_at ) {
+				return null;
+			}
+
+			switch ( $token['type'] ) {
+				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
+				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
+					return null;
+
+				case WP_CSS_Token_Processor::TOKEN_COMMENT:
+					if (
+						strlen( $this->style ) === $token['end'] &&
+						'*/' !== substr( $this->style, -2 )
+					) {
+						return null;
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+				case WP_CSS_Token_Processor::TOKEN_LEFT_PAREN:
+					$stack[] = ')';
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_URL:
+					if ( ! $this->is_url_token_closed( $token ) ) {
+						$stack[] = ')';
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET:
+					$stack[] = ']';
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACE:
+					$stack[] = '}';
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN:
+					if ( ! empty( $stack ) && ')' === end( $stack ) ) {
+						array_pop( $stack );
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET:
+					if ( ! empty( $stack ) && ']' === end( $stack ) ) {
+						array_pop( $stack );
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE:
+					if ( ! empty( $stack ) && '}' === end( $stack ) ) {
+						array_pop( $stack );
+					}
+					break;
+			}
+		}
+
+		return implode( '', array_reverse( $stack ) );
+	}
+
+	/**
+	 * Checks whether a URL token source contains its real closing parenthesis.
+	 *
+	 * @param array{type:string, value:string|null, start:int, length:int, end:int} $token URL token metadata.
+	 * @return bool Whether the URL token was closed in source.
+	 */
+	private function is_url_token_closed( array $token ): bool {
+		$sentinel = ' !wp-style-attribute-processor-sentinel';
+		$source   = substr( $this->style, $token['start'], $token['length'] );
+		$scanner  = WP_CSS_Token_Processor::create( $source . $sentinel );
+		if ( null === $scanner || ! $scanner->next_token() ) {
+			return false;
+		}
+
+		if (
+			WP_CSS_Token_Processor::TOKEN_URL !== $scanner->get_token_type() ||
+			$scanner->get_token_length() > strlen( $source )
+		) {
+			return false;
+		}
+
+		return $scanner->next_token();
+	}
+
 	/**
 	 * Checks whether an appended declaration will parse as a new declaration.
 	 *
@@ -901,15 +1257,19 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 	 * appending a top-level declaration are incompatible.
 	 *
 	 * @param int    $insert_at             Byte offset at which the declaration will be inserted.
+	 * @param string $eof_repair            EOF repair text.
 	 * @param string $separator             Separator text.
 	 * @param string $declaration_text      Serialized declaration text.
 	 * @param int    $old_declaration_count Number of declarations before appending.
+	 * @param string $expected_name          Expected parsed property name.
+	 * @param string $expected_value         Expected parsed value source.
+	 * @param bool   $expected_important     Expected important flag.
 	 * @return bool Whether the appended declaration is parseable.
 	 */
-	private function is_parseable_append( int $insert_at, string $separator, string $declaration_text, int $old_declaration_count ): bool {
-		$expected_start  = $insert_at + strlen( $separator );
+	private function is_parseable_append( int $insert_at, string $eof_repair, string $separator, string $declaration_text, int $old_declaration_count, string $expected_name, string $expected_value, bool $expected_important ): bool {
+		$expected_start  = $insert_at + strlen( $eof_repair ) + strlen( $separator );
 		$expected_after  = $expected_start + strlen( $declaration_text );
-		$candidate_style = substr( $this->style, 0, $insert_at ) . $separator . $declaration_text . substr( $this->style, $insert_at );
+		$candidate_style = substr( $this->style, 0, $insert_at ) . $eof_repair . $separator . $declaration_text . substr( $this->style, $insert_at );
 		$candidate       = new self( $candidate_style );
 		$candidate->ensure_parsed();
 
@@ -919,7 +1279,16 @@ private function is_parseable_append( int $insert_at, string $separator, string
 
 		foreach ( $candidate->declarations as $declaration ) {
 			if ( $expected_start === $declaration['start'] && $expected_after === $declaration['after'] ) {
-				return true;
+				$parsed_value = trim(
+					substr( $candidate_style, $declaration['value_start'], $declaration['value_end'] - $declaration['value_start'] ),
+					self::WHITESPACE
+				);
+
+				return (
+					$expected_name === $declaration['name'] &&
+					$expected_value === $parsed_value &&
+					$expected_important === $declaration['important']
+				);
 			}
 		}
 
@@ -1025,6 +1394,14 @@ private function is_custom_property_name( string $property_name ): bool {
 	 * @return bool Whether the property name is valid.
 	 */
 	private function is_valid_property_name( string $property_name ): bool {
+		if (
+			'' === $property_name ||
+			false !== strpos( $property_name, '\\' ) ||
+			'--' === $property_name
+		) {
+			return false;
+		}
+
 		$processor = WP_CSS_Token_Processor::create( $property_name );
 		if ( null === $processor || ! $processor->next_token() ) {
 			return false;
@@ -1068,6 +1445,10 @@ private function is_valid_property_name( string $property_name ): bool {
 	 * @return bool Whether the value is valid.
 	 */
 	private function is_valid_declaration_value( string $value ): bool {
+		if ( '' === trim( $value, self::WHITESPACE ) ) {
+			return false;
+		}
+
 		$sentinel_property = '--wp-style-attribute-processor-sentinel';
 		$processor         = WP_CSS_Token_Processor::create( $value . ';' . $sentinel_property . ':1' );
 		if ( null === $processor ) {
@@ -1135,19 +1516,24 @@ private function is_valid_declaration_value( string $value ): bool {
 			return false;
 		}
 
-		$top_level_count = count( $top_level_tokens );
-		if ( $top_level_count < 2 ) {
-			return true;
+		if ( empty( $top_level_tokens ) ) {
+			return false;
 		}
 
-		$last_value_token  = $top_level_tokens[ $top_level_count - 1 ];
-		$before_last_token = $top_level_tokens[ $top_level_count - 2 ];
+		for ( $i = 1; $i < count( $top_level_tokens ); $i++ ) {
+			$token        = $top_level_tokens[ $i ];
+			$before_token = $top_level_tokens[ $i - 1 ];
 
-		return ! (
-			WP_CSS_Token_Processor::TOKEN_IDENT === $last_value_token['type'] &&
-			0 === strcasecmp( 'important', (string) $last_value_token['value'] ) &&
-			WP_CSS_Token_Processor::TOKEN_DELIM === $before_last_token['type'] &&
-			'!' === $before_last_token['value']
-		);
+			if (
+				WP_CSS_Token_Processor::TOKEN_IDENT === $token['type'] &&
+				0 === strcasecmp( 'important', (string) $token['value'] ) &&
+				WP_CSS_Token_Processor::TOKEN_DELIM === $before_token['type'] &&
+				'!' === $before_token['value']
+			) {
+				return false;
+			}
+		}
+
+		return true;
 	}
 }
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 40b986f326594..e6a22227b4a1b 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -13,73 +13,96 @@
  */
 class Tests_HtmlApi_WpHtmlStyleAttributeProcessor extends WP_UnitTestCase {
 	/**
-	 * @covers ::__construct
-	 * @covers ::next_declaration
+	 * @covers ::create
 	 * @covers ::get_updated_style
+	 */
+	public function test_create_accepts_decoded_css_text_strings() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red' );
+
+		$this->assertSame( 'color: red', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::create
 	 *
-	 * @dataProvider data_html_style_attribute_values
+	 * @dataProvider data_non_string_style_attribute_values
 	 *
-	 * @param string      $html           HTML containing a first div.
-	 * @param string      $expected_style Expected normalized style input.
-	 * @param string|null $property_name  Expected first property name.
+	 * @param mixed $style_attribute_value Non-string style attribute value.
 	 */
-	public function test_constructor_accepts_html_tag_processor_style_attribute_values( string $html, string $expected_style, ?string $property_name ) {
-		$tags = new WP_HTML_Tag_Processor( $html );
-		$this->assertTrue( $tags->next_tag( 'div' ) );
+	public function test_create_rejects_non_string_style_attribute_values( $style_attribute_value ) {
+		$this->expectException( TypeError::class );
+
+		WP_HTML_Style_Attribute_Processor::create( $style_attribute_value );
+	}
 
-		$processor = new WP_HTML_Style_Attribute_Processor( $tags->get_attribute( 'style' ) );
+	/**
+	 * @coversNothing
+	 */
+	public function test_constructor_is_not_public() {
+		$reflection  = new ReflectionClass( WP_HTML_Style_Attribute_Processor::class );
+		$constructor = $reflection->getConstructor();
 
-		$this->assertSame( $expected_style, $processor->get_updated_style() );
+		$this->assertNotNull( $constructor );
+		$this->assertFalse( $constructor->isPublic() );
+	}
 
-		if ( null === $property_name ) {
-			$this->assertFalse( $processor->next_declaration() );
-		} else {
-			$this->assertTrue( $processor->next_declaration() );
-			$this->assertSame( $property_name, $processor->get_property_name() );
-		}
+	/**
+	 * @coversNothing
+	 */
+	public function test_raw_value_getter_is_not_public_api() {
+		$this->assertFalse( method_exists( WP_HTML_Style_Attribute_Processor::class, 'get_value' ) );
+		$this->assertFalse( method_exists( WP_HTML_Style_Attribute_Processor::class, 'get_raw_value' ) );
 	}
 
 	/**
 	 * @covers ::next_declaration
 	 * @covers ::get_property_name
-	 * @covers ::get_value
+	 * @covers ::is_important
 	 */
 	public function test_next_declaration_reads_properties_in_order_and_preserves_duplicates() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: color(display-p3 1 0 0); background: blue' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'COLOR: red; color: blue !important; background: white' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'color', $processor->get_property_name() );
-		$this->assertSame( 'red', $processor->get_value() );
+		$this->assertFalse( $processor->is_important() );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'color', $processor->get_property_name() );
-		$this->assertSame( 'color(display-p3 1 0 0)', $processor->get_value() );
+		$this->assertTrue( $processor->is_important() );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'blue', $processor->get_value() );
 
 		$this->assertFalse( $processor->next_declaration() );
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertNull( $processor->is_important() );
 	}
 
 	/**
 	 * @covers ::next_declaration
+	 * @covers ::get_property_name
 	 */
 	public function test_next_declaration_query_visits_matching_duplicate_properties() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white; COLOR: blue;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white; COLOR: blue;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertSame( 'red', $processor->get_value() );
+		$this->assertSame( 'color', $processor->get_property_name() );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertSame( 'blue', $processor->get_value() );
+		$this->assertSame( 'color', $processor->get_property_name() );
 
 		$this->assertFalse( $processor->next_declaration( 'color' ) );
+	}
 
-		$processor = new WP_HTML_Style_Attribute_Processor( '--Tone: warm; --tone: cool;' );
+	/**
+	 * @covers ::next_declaration
+	 * @covers ::get_property_name
+	 */
+	public function test_custom_property_queries_match_exact_decoded_casing() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '--Tone: warm; --tone: cool;' );
 
 		$this->assertTrue( $processor->next_declaration( '--tone' ) );
-		$this->assertSame( 'cool', $processor->get_value() );
+		$this->assertSame( '--tone', $processor->get_property_name() );
 
 		$this->assertFalse( $processor->next_declaration( '--tone' ) );
 	}
@@ -88,31 +111,25 @@ public function test_next_declaration_query_visits_matching_duplicate_properties
 	 * @covers ::next_declaration
 	 */
 	public function test_next_declaration_accepts_named_property_name_argument() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
 
-		$this->assertTrue( $processor->next_declaration( property_name: 'background' ) );
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'white', $processor->get_value() );
 	}
 
 	/**
 	 * @covers ::is_important
-	 * @covers ::get_value
+	 *
+	 * @dataProvider data_important_priority_syntax
+	 *
+	 * @param string $style     Style attribute value.
+	 * @param bool   $important Expected importance.
 	 */
-	public function test_important_priority_is_inspected_separately_from_value() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; --tone: blue !IMPORTANT; background: white;' );
-
-		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'red', $processor->get_value() );
-		$this->assertTrue( $processor->is_important() );
-
-		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'blue', $processor->get_value() );
-		$this->assertTrue( $processor->is_important() );
+	public function test_important_priority_syntax_variants( string $style, bool $important ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'white', $processor->get_value() );
-		$this->assertFalse( $processor->is_important() );
+		$this->assertSame( $important, $processor->is_important() );
 	}
 
 	/**
@@ -120,7 +137,7 @@ public function test_important_priority_is_inspected_separately_from_value() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_value_updates_current_declaration_without_collapsing_duplicates() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; color: color(display-p3 1 0 0);' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red !important; color: color(display-p3 1 0 0);' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( 'green', false ) );
@@ -130,54 +147,174 @@ public function test_set_value_updates_current_declaration_without_collapsing_du
 
 	/**
 	 * @covers ::set_value
-	 * @covers ::get_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_declaration_values_allow_leading_and_trailing_comments_as_trivia() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( '/* before */ green /* after */' ) );
+		$this->assertTrue( $processor->append_declaration( 'background', '/* before */ white /* after */' ) );
+
+		$this->assertSame( 'color: /* before */ green /* after */; background: /* before */ white /* after */;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::set_value
 	 * @covers ::is_important
 	 */
-	public function test_getters_reflect_current_declaration_after_set_value() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+	public function test_set_value_preserves_sets_and_clears_importance() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red !important; background: white; border-color: black;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertTrue( $processor->set_value( 'green', true ) );
+		$this->assertTrue( $processor->set_value( 'green' ) );
+		$this->assertTrue( $processor->is_important() );
 
-		$this->assertSame( 'color', $processor->get_property_name() );
-		$this->assertSame( 'green', $processor->get_value() );
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->set_value( 'blue', true ) );
 		$this->assertTrue( $processor->is_important() );
 
+		$this->assertTrue( $processor->next_declaration( 'border-color' ) );
+		$this->assertTrue( $processor->set_value( 'currentColor', false ) );
+		$this->assertFalse( $processor->is_important() );
+
+		$this->assertSame(
+			'color: green !important; background: blue !important; border-color: currentColor;',
+			$processor->get_updated_style()
+		);
+	}
+
+	/**
+	 * @covers ::set_value
+	 * @covers ::remove_declaration
+	 * @covers ::get_property_name
+	 * @covers ::is_important
+	 */
+	public function test_set_value_with_empty_string_removes_current_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( '' ) );
+
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertNull( $processor->is_important() );
+		$this->assertFalse( $processor->set_value( 'green' ) );
+		$this->assertFalse( $processor->remove_declaration() );
+
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'background: white;', $processor->get_updated_style() );
 	}
 
 	/**
-	 * @covers ::remove_declaration
+	 * @covers ::set_value
 	 * @covers ::get_updated_style
 	 */
-	public function test_remove_declaration_removes_only_current_duplicate() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
+	public function test_set_value_rejects_css_whitespace_only_values_without_removing_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertFalse( $processor->set_value( " \t\n\r\f" ) );
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+	}
+
+	/**
+	 * @covers ::set_important
+	 * @covers ::is_important
+	 * @covers ::get_updated_style
+	 */
+	public function test_set_important_sets_and_clears_priority() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white ! /*x*/ important;' );
+
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
 
-		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->set_important( false ) );
+		$this->assertFalse( $processor->is_important() );
+
+		$this->assertSame( 'color: red !important; background: white ;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::set_important
+	 * @covers ::get_updated_style
+	 */
+	public function test_set_important_can_repair_unclosed_eof_component_values() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'color: var(--x) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x /*c*/' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'color: var(--x /*c*/) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo' );
+
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'background: url(foo) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x ' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'color: var(--x ) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x /*c*/ ' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'color: var(--x /*c*/ ) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo ' );
+
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'background: url(foo ) !important', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo\\)' );
+
+		$this->assertTrue( $processor->next_declaration( 'background' ) );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'background: url(foo\\)) !important', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::set_important
+	 */
+	public function test_set_important_returns_false_without_current_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+
+		$this->assertFalse( $processor->set_important( true ) );
 	}
 
 	/**
 	 * @covers ::remove_declaration
-	 * @covers ::get_property_name
-	 * @covers ::get_value
+	 * @covers ::get_updated_style
 	 */
-	public function test_getters_return_null_after_removing_current_declaration_until_cursor_advances() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
+	public function test_remove_declaration_removes_only_current_duplicate() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; color: blue; background: white;' );
 
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 
-		$this->assertNull( $processor->get_property_name() );
-		$this->assertNull( $processor->get_value() );
-		$this->assertFalse( $processor->is_important() );
-
-		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
 	/**
@@ -185,7 +322,7 @@ public function test_getters_return_null_after_removing_current_declaration_unti
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_removes_adjacent_duplicate_declarations() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; color: blue; background: white;' );
 
 		while ( $processor->next_declaration( 'color' ) ) {
 			$this->assertTrue( $processor->remove_declaration() );
@@ -194,36 +331,70 @@ public function test_remove_declaration_removes_adjacent_duplicate_declarations(
 		$this->assertSame( 'background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_property_name
+	 * @covers ::is_important
+	 */
+	public function test_getters_return_null_after_removing_current_declaration_until_cursor_advances() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertNull( $processor->is_important() );
+		$this->assertFalse( $processor->remove_declaration() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+	}
+
 	/**
 	 * @covers ::remove_declaration
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_preserves_surrounding_comments() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/ color: red; background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( '/*keep*/ color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; /*keep*/ background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; /*keep*/ background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 		$this->assertSame( 'color: red; /*keep*/', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::remove_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_remove_declaration_with_invalid_fragments_preserves_remaining_structure() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; invalid; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertSame( 'invalid; background: white;', $processor->get_updated_style() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_adds_duplicate_declaration() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'color(display-p3 1 0 0)', true ) );
 
@@ -235,7 +406,7 @@ public function test_append_declaration_adds_duplicate_declaration() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_preserves_multiple_appends_in_order() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
@@ -248,17 +419,17 @@ public function test_append_declaration_preserves_multiple_appends_in_order() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_treats_comments_as_trivia_for_separators() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( '/*keep*/' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertSame( '/*keep*/ color: red;', $processor->get_updated_style() );
 
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;/*keep*/' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;/*keep*/' );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( 'color: red;/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x;/*keep*/);' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x;/*keep*/);' );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( 'color: var(--x;/*keep*/); background: white;', $processor->get_updated_style() );
@@ -268,47 +439,48 @@ public function test_append_declaration_treats_comments_as_trivia_for_separators
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 */
-	public function test_append_declaration_rejects_unclosed_component_value_append_points() {
-		$style     = 'color: var(--x;/*keep*/';
-		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+	public function test_append_declaration_lowercases_ordinary_properties_and_preserves_custom_properties() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
 
-		$this->assertFalse( $processor->append_declaration( 'background', 'white' ) );
-		$this->assertSame( $style, $processor->get_updated_style() );
+		$this->assertTrue( $processor->append_declaration( 'BackgroundColor', 'red' ) );
+		$this->assertTrue( $processor->append_declaration( '--Tone', 'warm' ) );
+
+		$this->assertSame( 'backgroundcolor: red; --Tone: warm;', $processor->get_updated_style() );
 	}
 
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::next_declaration
+	 * @covers ::get_property_name
 	 */
 	public function test_appended_declarations_can_be_inspected_by_the_cursor() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'color', $processor->get_property_name() );
-		$this->assertSame( 'red', $processor->get_value() );
 	}
 
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::next_declaration
 	 * @covers ::get_property_name
+	 * @covers ::set_value
 	 */
 	public function test_append_declaration_preserves_exhausted_cursor_until_it_advances() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertFalse( $processor->next_declaration() );
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 
 		$this->assertNull( $processor->get_property_name() );
-		$this->assertNull( $processor->get_value() );
+		$this->assertNull( $processor->is_important() );
 		$this->assertFalse( $processor->set_value( 'green' ) );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'white', $processor->get_value() );
 		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
@@ -318,7 +490,7 @@ public function test_append_declaration_preserves_exhausted_cursor_until_it_adva
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_after_removing_only_declaration() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;   ' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;   ' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
@@ -327,17 +499,59 @@ public function test_append_declaration_after_removing_only_declaration() {
 		$this->assertSame( 'background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_repairs_unclosed_eof_component_values() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x' );
+
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( 'color: var(--x); background: white;', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: calc(1px + var(--gap' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+		$this->assertSame( 'width: calc(1px + var(--gap)); color: red;', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo' );
+
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+		$this->assertSame( 'background: url(foo); color: red;', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo ' );
+
+		$this->assertTrue( $processor->append_declaration( 'border', '0' ) );
+		$this->assertSame( 'background: url(foo ); border: 0;', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo\\)' );
+
+		$this->assertTrue( $processor->append_declaration( 'border', '0' ) );
+		$this->assertSame( 'background: url(foo\\)); border: 0;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_append_declaration_rejects_eof_repairs_that_cannot_be_precise() {
+		$style     = 'color: var(--x;/*keep';
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertFalse( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( $style, $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::next_declaration
 	 * @covers ::get_updated_style
 	 */
 	public function test_invalid_fragments_are_skipped_and_preserved() {
 		$style     = 'color red; @media (min-width: 1px) { color: green; } background: white;';
-		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'white', $processor->get_value() );
 		$this->assertFalse( $processor->next_declaration() );
 		$this->assertSame( $style, $processor->get_updated_style() );
 	}
@@ -346,11 +560,10 @@ public function test_invalid_fragments_are_skipped_and_preserved() {
 	 * @covers ::next_declaration
 	 */
 	public function test_stray_right_brace_consumes_bad_declaration_until_semicolon() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '} color: red; background: white;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( '} color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'white', $processor->get_value() );
 		$this->assertFalse( $processor->next_declaration() );
 	}
 
@@ -360,7 +573,7 @@ public function test_stray_right_brace_consumes_bad_declaration_until_semicolon(
 	 * @covers ::get_updated_style
 	 */
 	public function test_escaped_property_names_match_decoded_names_and_preserve_raw_spelling() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertSame( 'color', $processor->get_property_name() );
@@ -369,69 +582,69 @@ public function test_escaped_property_names_match_decoded_names_and_preserve_raw
 
 		$this->assertTrue( $processor->next_declaration( '--tone' ) );
 		$this->assertSame( '--tone', $processor->get_property_name() );
-		$this->assertSame( 'cool', $processor->get_value() );
+		$this->assertTrue( $processor->set_value( 'cold' ) );
+		$this->assertSame( 'c\\6f lor: green; --t\\6f ne: cold; --Tone: warm;', $processor->get_updated_style() );
 
 		$this->assertFalse( $processor->next_declaration( '--tone' ) );
 	}
 
 	/**
 	 * @covers ::is_important
-	 * @covers ::get_value
 	 */
 	public function test_important_inside_unclosed_function_is_not_declaration_priority() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x, red !important' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x, red !important' );
 
 		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'var(--x, red !important', $processor->get_value() );
 		$this->assertFalse( $processor->is_important() );
 	}
 
 	/**
-	 * @covers ::is_important
-	 * @covers ::get_value
-	 *
-	 * @dataProvider data_important_priority_syntax
-	 *
-	 * @param string $style     Style attribute value.
-	 * @param string $value     Expected declaration value.
-	 * @param bool   $important Expected importance.
+	 * @covers ::set_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
 	 */
-	public function test_important_priority_syntax_variants( string $style, string $value, bool $important ) {
-		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+	public function test_declaration_values_reject_top_level_semicolons_and_important_priority() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
-		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( $value, $processor->get_value() );
-		$this->assertSame( $important, $processor->is_important() );
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertFalse( $processor->set_value( 'blue; color: green' ) );
+		$this->assertFalse( $processor->set_value( 'green ! important', false ) );
+		$this->assertFalse( $processor->set_value( 'green ! important foo', false ) );
+		$this->assertFalse( $processor->append_declaration( 'background', 'blue; color: green' ) );
+		$this->assertFalse( $processor->append_declaration( 'background', 'white !important' ) );
+		$this->assertFalse( $processor->append_declaration( 'background', 'white !important foo' ) );
+
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
 	}
 
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 */
-	public function test_declaration_values_reject_top_level_semicolons() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+	public function test_append_declaration_rejects_empty_values() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
-		$this->assertFalse( $processor->append_declaration( 'background', 'blue; color: green' ) );
+		$this->assertFalse( $processor->append_declaration( 'background', '' ) );
+		$this->assertFalse( $processor->append_declaration( 'background', '/* comment */' ) );
 		$this->assertSame( 'color: red;', $processor->get_updated_style() );
 	}
 
 	/**
 	 * @covers ::set_value
-	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 */
-	public function test_declaration_values_reject_top_level_important_priority() {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+	public function test_set_value_rejects_comment_only_values_without_removing_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertFalse( $processor->set_value( 'green ! important', false ) );
-		$this->assertFalse( $processor->append_declaration( 'background', 'white !important' ) );
-
+		$this->assertFalse( $processor->set_value( '/* comment */' ) );
 		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+		$this->assertSame( 'color', $processor->get_property_name() );
 	}
 
 	/**
 	 * @covers ::append_declaration
+	 * @covers ::set_value
 	 * @covers ::get_updated_style
 	 *
 	 * @dataProvider data_malformed_declaration_values
@@ -439,20 +652,46 @@ public function test_declaration_values_reject_top_level_important_priority() {
 	 * @param string $value Malformed CSS declaration value.
 	 */
 	public function test_declaration_values_reject_malformed_eof_tokens( string $value ) {
-		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
 
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertFalse( $processor->set_value( $value ) );
 		$this->assertFalse( $processor->append_declaration( 'background', $value ) );
 		$this->assertSame( 'color: red;', $processor->get_updated_style() );
 	}
 
 	/**
+	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 */
-	public function test_updated_style_can_be_set_on_html_tag_processor() {
+	public function test_property_names_reject_escaped_source_identifiers() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+
+		$this->assertFalse( $processor->append_declaration( 'color\\', 'red' ) );
+		$this->assertFalse( $processor->append_declaration( 'c\\6f lor', 'red' ) );
+		$this->assertSame( '', $processor->get_updated_style() );
+	}
+
+	/**
+	 * @coversNothing
+	 */
+	public function test_whitespace_constant_is_not_public_api() {
+		$reflection = new ReflectionClass( WP_HTML_Style_Attribute_Processor::class );
+
+		$this->assertFalse( $reflection->hasConstant( 'WHITESPACE' ) && $reflection->getReflectionConstant( 'WHITESPACE' )->isPublic() );
+	}
+
+	/**
+	 * @covers ::get_updated_style
+	 */
+	public function test_updated_style_can_be_set_on_html_tag_processor_after_string_check() {
 		$tags = new WP_HTML_Tag_Processor( '<div style="color: red; color: color(display-p3 1 0 0)">Text</div>' );
 		$this->assertTrue( $tags->next_tag( 'div' ) );
 
-		$styles = new WP_HTML_Style_Attribute_Processor( $tags->get_attribute( 'style' ) );
+		$style = $tags->get_attribute( 'style' );
+		$this->assertIsString( $style );
+
+		$styles = WP_HTML_Style_Attribute_Processor::create( $style );
 		$this->assertTrue( $styles->append_declaration( 'background', 'white' ) );
 		$this->assertTrue( $tags->set_attribute( 'style', $styles->get_updated_style() ) );
 
@@ -465,29 +704,27 @@ public function test_updated_style_can_be_set_on_html_tag_processor() {
 	/**
 	 * Data provider.
 	 *
-	 * @return array<string, array{string,string,string|null}>
+	 * @return array<string, array{mixed}>
 	 */
-	public static function data_html_style_attribute_values(): array {
+	public static function data_non_string_style_attribute_values(): array {
 		return array(
-			'missing style attribute' => array( '<div>Text</div>', '', null ),
-			'boolean style attribute' => array( '<div style>Text</div>', '', null ),
-			'empty style attribute'   => array( '<div style="">Text</div>', '', null ),
-			'valued style attribute'  => array( '<div style="color: red">Text</div>', 'color: red', 'color' ),
+			'missing style attribute' => array( null ),
+			'boolean style attribute' => array( true ),
 		);
 	}
 
 	/**
 	 * Data provider.
 	 *
-	 * @return array<string, array{string,string,bool}>
+	 * @return array<string, array{string,bool}>
 	 */
 	public static function data_important_priority_syntax(): array {
 		return array(
-			'no whitespace'         => array( 'color: red!important;', 'red', true ),
-			'whitespace after bang' => array( 'color: red ! important;', 'red', true ),
-			'comment after bang'    => array( 'color: red ! /*x*/ important;', 'red', true ),
-			'escaped important'     => array( 'color: red !\\69mportant;', 'red', true ),
-			'extra trailing token'  => array( 'color: red ! important foo;', 'red ! important foo', false ),
+			'no whitespace'         => array( 'color: red!important;', true ),
+			'whitespace after bang' => array( 'color: red ! important;', true ),
+			'comment after bang'    => array( 'color: red ! /*x*/ important;', true ),
+			'escaped important'     => array( 'color: red !\\69mportant;', true ),
+			'extra trailing token'  => array( 'color: red ! important foo;', false ),
 		);
 	}
 
@@ -508,15 +745,4 @@ public static function data_malformed_declaration_values(): array {
 			'eof escape'                      => array( 'red\\' ),
 		);
 	}
-
-	/**
-	 * @covers ::append_declaration
-	 * @covers ::get_updated_style
-	 */
-	public function test_property_names_reject_eof_escapes() {
-		$processor = new WP_HTML_Style_Attribute_Processor( '' );
-
-		$this->assertFalse( $processor->append_declaration( 'color\\', 'red' ) );
-		$this->assertSame( '', $processor->get_updated_style() );
-	}
 }

From d3219771f10f862356d252efc7b60a5ba8abb828 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 26 Aug 2026 14:43:24 +0400
Subject: [PATCH 34/77] Pin style processor mutation sequencing

---
 ...lass-wp-html-style-attribute-processor.php | 20 +++++++++++
 .../wpHtmlStyleAttributeProcessor.php         | 33 +++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index fffd59060c9db..52b990ccee1f6 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -98,6 +98,8 @@ class WP_HTML_Style_Attribute_Processor {
 	 * Do not instantiate directly. Use
 	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string $style Decoded CSS text value from a style attribute.
 	 */
 	private function __construct( string $style ) {
@@ -107,6 +109,8 @@ private function __construct( string $style ) {
 	/**
 	 * Creates a processor for decoded CSS text from a style attribute.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string $decoded_css_text Decoded CSS text value from a style attribute.
 	 * @return static Created processor.
 	 */
@@ -124,6 +128,8 @@ public static function create( $decoded_css_text ) {
 	 * When a property name is provided, normal CSS properties are matched
 	 * ASCII-case-insensitively while custom properties are matched exactly.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string|null $property_name Optional declaration property name to match.
 	 * @return bool Whether a matching declaration was found.
 	 */
@@ -149,6 +155,8 @@ public function next_declaration( ?string $property_name = null ): bool {
 	/**
 	 * Gets the current declaration's property name.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string|null Property name, or null when not on a declaration.
 	 */
 	public function get_property_name(): ?string {
@@ -159,6 +167,8 @@ public function get_property_name(): ?string {
 	/**
 	 * Indicates whether the current declaration has an !important priority.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return bool|null Whether the current declaration has an !important priority,
 	 *                   or null when not on a declaration.
 	 */
@@ -170,6 +180,8 @@ public function is_important(): ?bool {
 	/**
 	 * Sets the value of the current declaration.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string    $value     CSS declaration value, without the property name.
 	 * @param bool|null $important Optional. Whether the declaration should be important.
 	 *                             Defaults to preserving the current priority.
@@ -224,6 +236,8 @@ public function set_value( string $value, ?bool $important = null ): bool {
 	/**
 	 * Sets the !important priority of the current declaration.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param bool $important Whether the declaration should be important.
 	 * @return bool Whether the current declaration priority is set as requested.
 	 */
@@ -319,6 +333,8 @@ public function set_important( bool $important ): bool {
 	 * Only the current declaration is removed. Other declarations with the same
 	 * property name remain in place.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return bool Whether the current declaration was removed.
 	 */
 	public function remove_declaration(): bool {
@@ -353,6 +369,8 @@ public function remove_declaration(): bool {
 	 * Appending does not remove or replace existing declarations with the same
 	 * property name.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @param string $property_name CSS property name.
 	 * @param string $value         CSS declaration value, without the property name.
 	 * @param bool   $important     Optional. Whether the declaration should be important. Default false.
@@ -413,6 +431,8 @@ public function append_declaration( string $property_name, string $value, bool $
 	/**
 	 * Returns the updated decoded CSS text value for the style attribute.
 	 *
+	 * @since {WP_VERSION}
+	 *
 	 * @return string Updated decoded CSS text value for the style attribute.
 	 */
 	public function get_updated_style(): string {
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index e6a22227b4a1b..1176ff701b959 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -414,6 +414,39 @@ public function test_append_declaration_preserves_multiple_appends_in_order() {
 		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @covers ::append_declaration
+	 * @covers ::get_property_name
+	 * @covers ::get_updated_style
+	 * @covers ::is_important
+	 * @covers ::next_declaration
+	 * @covers ::remove_declaration
+	 * @covers ::set_important
+	 * @covers ::set_value
+	 */
+	public function test_mixed_mutations_preserve_the_logical_cursor_and_declaration_order() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( 'green', true ) );
+		$this->assertTrue( $processor->set_important( false ) );
+		$this->assertTrue( $processor->append_declaration( 'border', '1px', true ) );
+
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertFalse( $processor->is_important() );
+		$this->assertTrue( $processor->set_value( 'blue' ) );
+		$this->assertSame( 'color: blue; background: white; border: 1px !important;', $processor->get_updated_style() );
+
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertNull( $processor->get_property_name() );
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background', $processor->get_property_name() );
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'border', $processor->get_property_name() );
+		$this->assertTrue( $processor->is_important() );
+		$this->assertSame( 'background: white; border: 1px !important;', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style

From 4cbb6300d1460f6880246435753d57de14efd7e5 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 6 Oct 2026 13:12:54 +0400
Subject: [PATCH 35/77] Reject declarations CSS drops at parse time

---
 .../wp-html-style-attribute-processor-spec.md | 18 ++++-
 ...lass-wp-html-style-attribute-processor.php | 69 +++++++++++++++++++
 .../wpHtmlStyleAttributeProcessor.php         | 54 ++++++++++++++-
 3 files changed, 139 insertions(+), 2 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 3728c39f520e0..3f9c40ad4631e 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -224,7 +224,23 @@ over whitespace preservation.
 
 Declaration discovery follows CSS semantics. If CSS would ignore text as a
 declaration in a style attribute declaration-list context, the processor does
-not expose it as a declaration.
+not expose it as a declaration. That includes a declaration whose value, apart
+from its priority, contains:
+
+- a bad string or a bad URL;
+- a closing `)`, `]`, or `}` that does not match the innermost open block;
+- a top-level `!`;
+- a top-level `{}` block alongside other tokens, unless the property is a custom
+  property.
+
+Blocks and functions left open at EOF are closed by CSS, so a value ending
+inside one is exposed.
+
+Splitting follows CSS Style Attributes and the published CSS Syntax Level 3
+"parse a list of declarations": a stray `}` is an invalid token, and the
+invalid declaration runs to the next top-level semicolon. The CSS Syntax editor's
+draft ends parsing at a top-level `}` instead; browsers and web-platform-tests do
+not, and csswg-drafts#11113 tracks the conflict.
 
 Ignored invalid fragments are preserved where possible. Mutations touching a
 style containing invalid chunks must verify that the declaration-list structure
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 52b990ccee1f6..77a3c429cb2bc 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -742,6 +742,10 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 			$value_end   = $this->tokens[ $value_end_index - 1 ]['end'];
 		}
 
+		if ( ! $this->is_parsed_value_valid( $value_start_index, $value_end_index, $this->is_custom_property_name( $name ) ) ) {
+			return null;
+		}
+
 		return array(
 			'name'            => $name,
 			'raw_name'        => substr( $this->style, $name_token['start'], $name_token['length'] ),
@@ -1397,6 +1401,71 @@ private function matches_property_name( string $actual, string $query ): bool {
 		return 0 === strcasecmp( $actual, $query );
 	}
 
+	/**
+	 * Checks whether CSS keeps a parsed declaration value, excluding its priority.
+	 *
+	 * CSS ignores a declaration whose value contains a bad string, a bad URL, an
+	 * unmatched closing token, or a top-level `!`. A `{}` block must be the whole
+	 * value unless the property is a custom property. Blocks left open at EOF are
+	 * closed by CSS and are valid.
+	 *
+	 * @param int  $start              First value token index.
+	 * @param int  $end                Token index after the value.
+	 * @param bool $is_custom_property Whether the declaration is a custom property.
+	 * @return bool Whether CSS keeps the value.
+	 */
+	private function is_parsed_value_valid( int $start, int $end, bool $is_custom_property ): bool {
+		$stack               = array();
+		$has_top_level_block = false;
+		$has_other_top_level = false;
+
+		for ( $index = $start; $index < $end; $index++ ) {
+			$token = $this->tokens[ $index ];
+			$type  = $token['type'];
+
+			if ( empty( $stack ) && ! $this->is_ignored_token( $token ) ) {
+				if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $type ) {
+					$has_top_level_block = true;
+				} else {
+					$has_other_top_level = true;
+				}
+
+				if ( WP_CSS_Token_Processor::TOKEN_DELIM === $type && '!' === $token['value'] ) {
+					return false;
+				}
+			}
+
+			switch ( $type ) {
+				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
+				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
+					return false;
+
+				case WP_CSS_Token_Processor::TOKEN_FUNCTION:
+				case WP_CSS_Token_Processor::TOKEN_LEFT_PAREN:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_LEFT_BRACE:
+					$stack[] = WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE;
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN:
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET:
+				case WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE:
+					if ( empty( $stack ) || array_pop( $stack ) !== $type ) {
+						return false;
+					}
+					break;
+			}
+		}
+
+		return $is_custom_property || ! ( $has_top_level_block && $has_other_top_level );
+	}
+
 	/**
 	 * Checks whether a property name is a custom property.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 1176ff701b959..ab45dbc91e541 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -600,6 +600,35 @@ public function test_stray_right_brace_consumes_bad_declaration_until_semicolon(
 		$this->assertFalse( $processor->next_declaration() );
 	}
 
+	/**
+	 * @covers ::next_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_declarations_with_values_css_ignores
+	 *
+	 * @param string $style Style attribute value whose first declaration CSS ignores.
+	 */
+	public function test_declarations_with_values_css_ignores_are_skipped_and_preserved( string $style ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertFalse( $processor->next_declaration() );
+		$this->assertSame( $style, $processor->get_updated_style() );
+	}
+
+	/**
+	 * @covers ::next_declaration
+	 */
+	public function test_custom_property_values_may_mix_blocks_with_other_tokens() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: { a } b; color: red;' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( '--x', $processor->get_property_name() );
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+	}
+
 	/**
 	 * @covers ::next_declaration
 	 * @covers ::set_value
@@ -757,7 +786,30 @@ public static function data_important_priority_syntax(): array {
 			'whitespace after bang' => array( 'color: red ! important;', true ),
 			'comment after bang'    => array( 'color: red ! /*x*/ important;', true ),
 			'escaped important'     => array( 'color: red !\\69mportant;', true ),
-			'extra trailing token'  => array( 'color: red ! important foo;', false ),
+			'nested important'      => array( 'color: var(--x, red !important);', false ),
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function data_declarations_with_values_css_ignores(): array {
+		return array(
+			'bad string'                      => array( "font-family: \"a\n; color: red;" ),
+			'bad url'                         => array( 'background: url(a b); color: red;' ),
+			'nested bad url'                  => array( 'background: image-set(url(a b) 1x); color: red;' ),
+			'unmatched right paren'           => array( 'width: 1px ); color: red;' ),
+			'unmatched right bracket'         => array( 'width: 1px ]; color: red;' ),
+			'unmatched right brace'           => array( 'width: 1px }; color: red;' ),
+			'mismatched closer in function'   => array( 'width: calc(1px } + 2px); color: red;' ),
+			'custom property unmatched brace' => array( '--x: a } b; color: red;' ),
+			'bang before important'           => array( 'padding: 0 ! 1px !important; color: red;' ),
+			'important before other tokens'   => array( 'padding: 0 !important 1px; color: red;' ),
+			'custom property bang'            => array( '--x: a ! b; color: red;' ),
+			'block mixed with other tokens'   => array( 'width: 1px { x }; color: red;' ),
+			'block before other tokens'       => array( 'width: { x } 1px; color: red;' ),
 		);
 	}
 

From 2625c51bcbb194d838b88c9c46e32504f6d348e4 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 6 Oct 2026 15:10:33 +0400
Subject: [PATCH 36/77] Set style attribute processor @since to 7.2.0

---
 ...lass-wp-html-style-attribute-processor.php | 24 +++++++++----------
 .../wpHtmlStyleAttributeProcessor.php         |  2 +-
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 77a3c429cb2bc..1ee0bc79dc6f9 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage HTML-API
- * @since {WP_VERSION}
+ * @since 7.2.0
  */
 
 /**
@@ -26,7 +26,7 @@
  * declaration list model of CSS. Multiple declarations with the same property
  * name remain separate entries and can be inspected or changed individually.
  *
- * @since {WP_VERSION}
+ * @since 7.2.0
  */
 class WP_HTML_Style_Attribute_Processor {
 	/**
@@ -98,7 +98,7 @@ class WP_HTML_Style_Attribute_Processor {
 	 * Do not instantiate directly. Use
 	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $style Decoded CSS text value from a style attribute.
 	 */
@@ -109,7 +109,7 @@ private function __construct( string $style ) {
 	/**
 	 * Creates a processor for decoded CSS text from a style attribute.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $decoded_css_text Decoded CSS text value from a style attribute.
 	 * @return static Created processor.
@@ -128,7 +128,7 @@ public static function create( $decoded_css_text ) {
 	 * When a property name is provided, normal CSS properties are matched
 	 * ASCII-case-insensitively while custom properties are matched exactly.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string|null $property_name Optional declaration property name to match.
 	 * @return bool Whether a matching declaration was found.
@@ -155,7 +155,7 @@ public function next_declaration( ?string $property_name = null ): bool {
 	/**
 	 * Gets the current declaration's property name.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string|null Property name, or null when not on a declaration.
 	 */
@@ -167,7 +167,7 @@ public function get_property_name(): ?string {
 	/**
 	 * Indicates whether the current declaration has an !important priority.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return bool|null Whether the current declaration has an !important priority,
 	 *                   or null when not on a declaration.
@@ -180,7 +180,7 @@ public function is_important(): ?bool {
 	/**
 	 * Sets the value of the current declaration.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string    $value     CSS declaration value, without the property name.
 	 * @param bool|null $important Optional. Whether the declaration should be important.
@@ -236,7 +236,7 @@ public function set_value( string $value, ?bool $important = null ): bool {
 	/**
 	 * Sets the !important priority of the current declaration.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param bool $important Whether the declaration should be important.
 	 * @return bool Whether the current declaration priority is set as requested.
@@ -333,7 +333,7 @@ public function set_important( bool $important ): bool {
 	 * Only the current declaration is removed. Other declarations with the same
 	 * property name remain in place.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return bool Whether the current declaration was removed.
 	 */
@@ -369,7 +369,7 @@ public function remove_declaration(): bool {
 	 * Appending does not remove or replace existing declarations with the same
 	 * property name.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @param string $property_name CSS property name.
 	 * @param string $value         CSS declaration value, without the property name.
@@ -431,7 +431,7 @@ public function append_declaration( string $property_name, string $value, bool $
 	/**
 	 * Returns the updated decoded CSS text value for the style attribute.
 	 *
-	 * @since {WP_VERSION}
+	 * @since 7.2.0
 	 *
 	 * @return string Updated decoded CSS text value for the style attribute.
 	 */
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index ab45dbc91e541..43d9cb9af9dd2 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -5,7 +5,7 @@
  * @package WordPress
  * @subpackage HTML-API
  *
- * @since {WP_VERSION}
+ * @since 7.2.0
  *
  * @group html-api
  *

From 00f4b82982fdb2a506a4de97a0c16c47b5aaf695 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 19:01:49 +0400
Subject: [PATCH 37/77] Expose declaration values as a token view

---
 .../wp-html-style-attribute-processor-spec.md |  46 +++-
 ...lass-wp-html-style-attribute-processor.php |  57 ++++-
 .../wpHtmlStyleAttributeProcessor.php         | 224 ++++++++++++++++++
 3 files changed, 313 insertions(+), 14 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 3f9c40ad4631e..a22468b6f543e 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -51,7 +51,7 @@ The internal declaration data consists of:
 
 - decoded property name;
 - authored property-name source when available;
-- value component list source range;
+- value component list source range and token index range;
 - `!important` flag;
 - nullable source range for the parsed priority span;
 - source ranges needed for safe mutation and verification.
@@ -67,6 +67,7 @@ public static function create( $decoded_css_text );
 public function next_declaration( ?string $property_name = null ): bool;
 public function get_property_name(): ?string;
 public function is_important(): ?bool;
+public function get_value_tokens(): ?array;
 public function set_value( string $value, ?bool $important = null ): bool;
 public function set_important( bool $important ): bool;
 public function remove_declaration(): bool;
@@ -74,9 +75,10 @@ public function append_declaration( string $property_name, string $value, bool $
 public function get_updated_style(): string;
 ```
 
-The first API does not expose `get_value()` or `get_raw_value()`. Raw CSS values
-are difficult for callers to use safely, and a higher-level value API needs a
-separate design.
+The processor exposes a declaration value as tokens, through
+`get_value_tokens()`, and not as a string: there is no `get_value()` or
+`get_raw_value()`. Consumers that check or re-serialize values need tokens; a
+string would be re-tokenized by every consumer.
 
 Bookmarks, seek, and rewind are out of scope. Callers that need to rescan should
 create a new processor from the updated style text.
@@ -86,7 +88,7 @@ create a new processor from the updated style text.
 `next_declaration()` advances a forward-only cursor over CSS declarations.
 
 All current-declaration getters return `null` when the cursor is not positioned
-on a valid declaration. This includes `is_important()`.
+on a valid declaration. This includes `is_important()` and `get_value_tokens()`.
 
 After `remove_declaration()` succeeds, the cursor becomes invalid until
 `next_declaration()` advances it. A second removal on the same invalid cursor
@@ -129,6 +131,38 @@ Appended property names must be valid plaintext CSS property names. The processo
 does not escape arbitrary strings into identifiers. Custom properties follow the
 same validity rule with the required `--` prefix.
 
+## Value Tokens
+
+`get_value_tokens()` returns the current declaration's value as a list of CSS
+tokens, or `null` when the cursor is not on a declaration. Each token is an
+array with the keys `type`, `value`, `start`, `length`, and `end`:
+
+- `type` is a `WP_CSS_Token_Processor` `TOKEN_*` constant;
+- `value` is the token value as `WP_CSS_Token_Processor::get_token_value()`
+  returns it: decoded, a dimension's number without its unit, a hash's name
+  without `#`, and `null` for tokens without a value;
+- `start` and `length` are the token's byte offset and byte length in the
+  style text, and `end` is `start + length`.
+
+The list covers the value only. Leading and trailing whitespace and comments
+and the `!important` priority are excluded; whitespace and comments between
+value tokens are included. A declaration with no value tokens, such as
+`color:;`, returns an empty list.
+
+Offsets index the current style text, which `get_updated_style()` returns.
+Before any mutation that is the text passed to `create()`. A successful
+mutation reparses the updated text, and the offsets follow it.
+
+Re-tokenizing the source slice from the first token's `start` to the last
+token's `end` with `WP_CSS_Token_Processor` yields the same `type` and `value`
+sequence. Consumers may rely on this to re-serialize a value or to hand the
+slice to another tokenizer-based check.
+
+Two alternatives were considered. A `WP_CSS_Token_Processor` positioned over the
+value's range would need range support in the tokenizer and give consumers a
+forward-only cursor over tokens the processor already holds. A raw string would
+be re-tokenized by every consumer.
+
 ## Value Validation
 
 Mutation inputs accept CSS declaration values, not declaration-list text.
@@ -287,6 +321,8 @@ Tests should cover:
 - declaration traversal, duplicate preservation, and property-name matching;
 - getter `null` behavior off-cursor;
 - absence of public raw value getter in the first API;
+- value token view: `null` off-cursor, trivia and priority exclusion, offsets
+  into the style text, and the re-tokenization invariant;
 - `set_value()` priority preservation, setting, clearing, and empty-value
   removal;
 - `set_important()` setting, clearing, cursor behavior, and safe normalization;
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 1ee0bc79dc6f9..22b6ea40ef711 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -53,7 +53,7 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Parsed declarations.
 	 *
-	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}>
+	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
 
@@ -177,6 +177,44 @@ public function is_important(): ?bool {
 		return null === $declaration ? null : $declaration['important'];
 	}
 
+	/**
+	 * Gets the current declaration's value as a list of CSS tokens.
+	 *
+	 * The list covers the declaration value only. Leading and trailing
+	 * whitespace and comments and the `!important` priority are excluded;
+	 * whitespace and comments between value tokens are included. The list is
+	 * empty when the declaration has no value tokens, as in `color:;`.
+	 *
+	 * Each token is an array with these keys:
+	 *
+	 *  - `type`: a {@see WP_CSS_Token_Processor} `TOKEN_*` constant.
+	 *  - `value`: the token value as {@see WP_CSS_Token_Processor::get_token_value()}
+	 *    returns it: a dimension's number without its unit, a hash's name
+	 *    without `#`, a string's decoded contents, and null for tokens
+	 *    without a value.
+	 *  - `start`: byte offset of the token in the style text.
+	 *  - `length`: byte length of the token in the style text.
+	 *  - `end`: byte offset after the token, `start + length`.
+	 *
+	 * Offsets index the current style text, which
+	 * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} returns.
+	 * Before any mutation that is the text passed to `create()`.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @return array<int, array{type:string, value:string|null, start:int, length:int, end:int}>|null
+	 *               Value tokens, or null when not on a declaration.
+	 */
+	public function get_value_tokens(): ?array {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration ) {
+			return null;
+		}
+
+		list( $start, $end ) = $declaration['value_tokens'];
+		return array_slice( $this->tokens, $start, $end - $start );
+	}
+
 	/**
 	 * Sets the value of the current declaration.
 	 *
@@ -686,7 +724,7 @@ private function consume_declaration_segment( int $index ): array {
 	 * @param int $start_index   First token index in the segment.
 	 * @param int $end_index     Token index after the segment.
 	 * @param int $after         Byte offset after the declaration.
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
 		$index = $this->skip_ignored_tokens( $start_index, $end_index );
@@ -755,6 +793,7 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 			'trailing_end'    => $after,
 			'value_start'     => $value_start,
 			'value_end'       => $value_end,
+			'value_tokens'    => array( $value_start_index, $value_end_index ),
 			'important'       => $important,
 			'important_start' => $important_start,
 			'important_end'   => $important_end,
@@ -904,7 +943,7 @@ private function get_offset_after_following_whitespace( int $offset ): int {
 	/**
 	 * Gets the current declaration metadata.
 	 *
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function get_current_declaration(): ?array {
 		if (
@@ -921,12 +960,12 @@ private function get_current_declaration(): ?array {
 	/**
 	 * Checks whether a replacement preserves the current declaration's structure.
 	 *
-	 * @param array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
-	 * @param int                                                                                                                                                                                   $start              Byte offset at which to start the replacement.
-	 * @param int                                                                                                                                                                                   $length             Number of bytes to replace.
-	 * @param string                                                                                                                                                                                $text               Replacement text.
-	 * @param bool                                                                                                                                                                                  $expected_important Expected important flag after replacement.
-	 * @param string|null                                                                                                                                                                           $expected_value     Optional expected value source after replacement.
+	 * @param array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
+	 * @param int                                                                                                                                                                                                                           $start              Byte offset at which to start the replacement.
+	 * @param int                                                                                                                                                                                                                           $length             Number of bytes to replace.
+	 * @param string                                                                                                                                                                                                                        $text               Replacement text.
+	 * @param bool                                                                                                                                                                                                                          $expected_important Expected important flag after replacement.
+	 * @param string|null                                                                                                                                                                                                                   $expected_value     Optional expected value source after replacement.
 	 * @return bool Whether the replacement is safe.
 	 */
 	private function is_current_declaration_replacement_safe( array $declaration, int $start, int $length, string $text, bool $expected_important, ?string $expected_value = null ): bool {
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 43d9cb9af9dd2..87d61aa70cd3c 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -52,6 +52,7 @@ public function test_constructor_is_not_public() {
 	public function test_raw_value_getter_is_not_public_api() {
 		$this->assertFalse( method_exists( WP_HTML_Style_Attribute_Processor::class, 'get_value' ) );
 		$this->assertFalse( method_exists( WP_HTML_Style_Attribute_Processor::class, 'get_raw_value' ) );
+		$this->assertFalse( method_exists( WP_HTML_Style_Attribute_Processor::class, 'get_value_source' ) );
 	}
 
 	/**
@@ -132,6 +133,124 @@ public function test_important_priority_syntax_variants( string $style, bool $im
 		$this->assertSame( $important, $processor->is_important() );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value_tokens
+	 */
+	public function test_get_value_tokens_returns_null_when_not_on_a_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+
+		$this->assertNull( $processor->get_value_tokens(), 'Expected null before the first declaration.' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertNotNull( $processor->get_value_tokens() );
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertFalse( $processor->next_declaration() );
+
+		$this->assertNull( $processor->get_value_tokens(), 'Expected null after the last declaration.' );
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value_tokens
+	 *
+	 * @dataProvider data_value_tokens
+	 *
+	 * @param string $style           Style text.
+	 * @param array  $expected_tokens Expected value tokens.
+	 */
+	public function test_get_value_tokens_covers_only_the_declaration_value( string $style, array $expected_tokens ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( $expected_tokens, $processor->get_value_tokens() );
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value_tokens
+	 */
+	public function test_get_value_tokens_decodes_values_and_keeps_source_offsets() {
+		$style     = 'content: "a\\"b"';
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$tokens = $processor->get_value_tokens();
+
+		$this->assertCount( 1, $tokens );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $tokens[0]['type'] );
+		$this->assertSame( 'a"b', $tokens[0]['value'] );
+		$this->assertSame( '"a\\"b"', substr( $style, $tokens[0]['start'], $tokens[0]['length'] ) );
+		$this->assertSame( $tokens[0]['start'] + $tokens[0]['length'], $tokens[0]['end'] );
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value_tokens
+	 * @covers ::set_value
+	 * @covers ::remove_declaration
+	 */
+	public function test_get_value_tokens_follow_the_updated_style_after_mutations() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+
+		$this->assertTrue( $processor->next_declaration( 'color' ) );
+		$this->assertTrue( $processor->set_value( 'green' ) );
+		$this->assertSame(
+			array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'green', 7, 5 ) ),
+			$processor->get_value_tokens()
+		);
+
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertNull( $processor->get_value_tokens() );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( 'background: white', $processor->get_updated_style() );
+		$this->assertSame(
+			array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'white', 12, 5 ) ),
+			$processor->get_value_tokens()
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::get_value_tokens
+	 *
+	 * @dataProvider data_value_tokens_source_slices
+	 *
+	 * @param string $style Style text.
+	 */
+	public function test_get_value_tokens_match_the_retokenized_source_slice( string $style ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$tokens = $processor->get_value_tokens();
+		$this->assertNotEmpty( $tokens );
+
+		$first = $tokens[0];
+		$last  = $tokens[ count( $tokens ) - 1 ];
+		$slice = substr( $style, $first['start'], $last['end'] - $first['start'] );
+
+		$expected  = array();
+		$tokenizer = WP_CSS_Token_Processor::create( $slice );
+		while ( $tokenizer->next_token() ) {
+			$expected[] = array( $tokenizer->get_token_type(), $tokenizer->get_token_value() );
+		}
+
+		$actual = array_map(
+			static function ( array $token ): array {
+				return array( $token['type'], $token['value'] );
+			},
+			$tokens
+		);
+
+		$this->assertSame( $expected, $actual );
+	}
+
 	/**
 	 * @covers ::set_value
 	 * @covers ::get_updated_style
@@ -335,6 +454,7 @@ public function test_remove_declaration_removes_adjacent_duplicate_declarations(
 	 * @covers ::remove_declaration
 	 * @covers ::get_property_name
 	 * @covers ::is_important
+	 * @covers ::get_value_tokens
 	 */
 	public function test_getters_return_null_after_removing_current_declaration_until_cursor_advances() {
 		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
@@ -344,6 +464,7 @@ public function test_getters_return_null_after_removing_current_declaration_unti
 
 		$this->assertNull( $processor->get_property_name() );
 		$this->assertNull( $processor->is_important() );
+		$this->assertNull( $processor->get_value_tokens() );
 		$this->assertFalse( $processor->remove_declaration() );
 
 		$this->assertTrue( $processor->next_declaration() );
@@ -763,6 +884,109 @@ public function test_updated_style_can_be_set_on_html_tag_processor_after_string
 		);
 	}
 
+	/**
+	 * Builds a value token array.
+	 *
+	 * @param string      $type   Token type.
+	 * @param string|null $value  Token value.
+	 * @param int         $start  Byte offset of the token.
+	 * @param int         $length Byte length of the token.
+	 * @return array{type:string, value:string|null, start:int, length:int, end:int}
+	 */
+	private static function token( string $type, ?string $value, int $start, int $length ): array {
+		return array(
+			'type'   => $type,
+			'value'  => $value,
+			'start'  => $start,
+			'length' => $length,
+			'end'    => $start + $length,
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string,array}>
+	 */
+	public static function data_value_tokens(): array {
+		return array(
+			'single ident'                     => array(
+				'color: red',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'red', 7, 3 ) ),
+			),
+			'function with nested tokens'      => array(
+				'width: calc(1px + 2%)',
+				array(
+					self::token( WP_CSS_Token_Processor::TOKEN_FUNCTION, 'calc', 7, 5 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 12, 3 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 15, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DELIM, '+', 16, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 17, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_PERCENTAGE, '2', 18, 2 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN, null, 20, 1 ),
+				),
+			),
+			'hash without number sign'         => array(
+				'color: #fff',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_HASH, 'fff', 7, 4 ) ),
+			),
+			'important excluded'               => array(
+				'color: red !important',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'red', 7, 3 ) ),
+			),
+			'important without space excluded' => array(
+				'color: red!important;',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'red', 7, 3 ) ),
+			),
+			'leading and trailing trivia'      => array(
+				"color: /* a */ \t red /* b */ ;",
+				array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'red', 17, 3 ) ),
+			),
+			'trivia inside the value kept'     => array(
+				'margin: 1px /* a */ 2px',
+				array(
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 8, 3 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 11, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_COMMENT, null, 12, 7 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 19, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '2', 20, 3 ),
+				),
+			),
+			'custom property'                  => array(
+				'--x: 1 2 3',
+				array(
+					self::token( WP_CSS_Token_Processor::TOKEN_NUMBER, '1', 5, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 6, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_NUMBER, '2', 7, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 8, 1 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_NUMBER, '3', 9, 1 ),
+				),
+			),
+			'empty value'                      => array( 'color:;', array() ),
+			'only important'                   => array( 'color: !important', array() ),
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function data_value_tokens_source_slices(): array {
+		return array(
+			'single ident'          => array( 'color: red' ),
+			'function'              => array( 'width: calc(1px + 2%)' ),
+			'string with escape'    => array( 'content: "a\\"b"' ),
+			'trivia and important'  => array( 'color: /* a */ red /* b */ !important;' ),
+			'custom property'       => array( '--x: 1 2 3' ),
+			'custom property block' => array( '--x: { a } b' ),
+			'comma list'            => array( 'font: 12px/1.5 "Foo Bar", sans-serif' ),
+			'urls'                  => array( 'background: url(a.png) no-repeat, image-set("b.png" 2x)' ),
+			'unclosed function'     => array( 'color: var(--x' ),
+			'eof escape'            => array( 'color: red\\' ),
+		);
+	}
+
 	/**
 	 * Data provider.
 	 *

From cf1b73cbe32517ba681e2eae3a5404556db27588 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 7 Oct 2026 23:31:52 +0400
Subject: [PATCH 38/77] Include the dimension unit in the value token view

---
 .../wp-html-style-attribute-processor-spec.md |  9 ++++--
 ...lass-wp-html-style-attribute-processor.php |  8 +++--
 .../wpHtmlStyleAttributeProcessor.php         | 31 ++++++++++++++-----
 3 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index a22468b6f543e..f0e800b625337 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -135,12 +135,15 @@ same validity rule with the required `--` prefix.
 
 `get_value_tokens()` returns the current declaration's value as a list of CSS
 tokens, or `null` when the cursor is not on a declaration. Each token is an
-array with the keys `type`, `value`, `start`, `length`, and `end`:
+array with the keys `type`, `value`, `unit`, `start`, `length`, and `end`:
 
 - `type` is a `WP_CSS_Token_Processor` `TOKEN_*` constant;
 - `value` is the token value as `WP_CSS_Token_Processor::get_token_value()`
   returns it: decoded, a dimension's number without its unit, a hash's name
   without `#`, and `null` for tokens without a value;
+- `unit` is the decoded unit of a dimension token, as
+  `WP_CSS_Token_Processor::get_token_unit()` returns it, and `null` for every
+  other token type;
 - `start` and `length` are the token's byte offset and byte length in the
   style text, and `end` is `start + length`.
 
@@ -154,8 +157,8 @@ Before any mutation that is the text passed to `create()`. A successful
 mutation reparses the updated text, and the offsets follow it.
 
 Re-tokenizing the source slice from the first token's `start` to the last
-token's `end` with `WP_CSS_Token_Processor` yields the same `type` and `value`
-sequence. Consumers may rely on this to re-serialize a value or to hand the
+token's `end` with `WP_CSS_Token_Processor` yields the same `type`, `value` and
+`unit` sequence. Consumers may rely on this to re-serialize a value or to hand the
 slice to another tokenizer-based check.
 
 Two alternatives were considered. A `WP_CSS_Token_Processor` positioned over the
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 22b6ea40ef711..b7bf65dd6ee46 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -46,7 +46,7 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * CSS token metadata.
 	 *
-	 * @var array<int, array{type:string, value:string|null, start:int, length:int, end:int}>
+	 * @var array<int, array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}>
 	 */
 	private $tokens = array();
 
@@ -192,6 +192,9 @@ public function is_important(): ?bool {
 	 *    returns it: a dimension's number without its unit, a hash's name
 	 *    without `#`, a string's decoded contents, and null for tokens
 	 *    without a value.
+	 *  - `unit`: the decoded unit of a dimension token, as
+	 *    {@see WP_CSS_Token_Processor::get_token_unit()} returns it, and null
+	 *    for every other token type.
 	 *  - `start`: byte offset of the token in the style text.
 	 *  - `length`: byte length of the token in the style text.
 	 *  - `end`: byte offset after the token, `start + length`.
@@ -202,7 +205,7 @@ public function is_important(): ?bool {
 	 *
 	 * @since 7.2.0
 	 *
-	 * @return array<int, array{type:string, value:string|null, start:int, length:int, end:int}>|null
+	 * @return array<int, array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}>|null
 	 *               Value tokens, or null when not on a declaration.
 	 */
 	public function get_value_tokens(): ?array {
@@ -524,6 +527,7 @@ private function parse(): void {
 			$this->tokens[] = array(
 				'type'   => $processor->get_token_type(),
 				'value'  => $processor->get_token_value(),
+				'unit'   => $processor->get_token_unit(),
 				'start'  => $start,
 				'length' => $length,
 				'end'    => $start + $length,
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 87d61aa70cd3c..526228e63f07c 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -238,12 +238,12 @@ public function test_get_value_tokens_match_the_retokenized_source_slice( string
 		$expected  = array();
 		$tokenizer = WP_CSS_Token_Processor::create( $slice );
 		while ( $tokenizer->next_token() ) {
-			$expected[] = array( $tokenizer->get_token_type(), $tokenizer->get_token_value() );
+			$expected[] = array( $tokenizer->get_token_type(), $tokenizer->get_token_value(), $tokenizer->get_token_unit() );
 		}
 
 		$actual = array_map(
 			static function ( array $token ): array {
-				return array( $token['type'], $token['value'] );
+				return array( $token['type'], $token['value'], $token['unit'] );
 			},
 			$tokens
 		);
@@ -891,12 +891,13 @@ public function test_updated_style_can_be_set_on_html_tag_processor_after_string
 	 * @param string|null $value  Token value.
 	 * @param int         $start  Byte offset of the token.
 	 * @param int         $length Byte length of the token.
-	 * @return array{type:string, value:string|null, start:int, length:int, end:int}
+	 * @return array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}
 	 */
-	private static function token( string $type, ?string $value, int $start, int $length ): array {
+	private static function token( string $type, ?string $value, int $start, int $length, ?string $unit = null ): array {
 		return array(
 			'type'   => $type,
 			'value'  => $value,
+			'unit'   => $unit,
 			'start'  => $start,
 			'length' => $length,
 			'end'    => $start + $length,
@@ -918,7 +919,7 @@ public static function data_value_tokens(): array {
 				'width: calc(1px + 2%)',
 				array(
 					self::token( WP_CSS_Token_Processor::TOKEN_FUNCTION, 'calc', 7, 5 ),
-					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 12, 3 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 12, 3, 'px' ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 15, 1 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_DELIM, '+', 16, 1 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 17, 1 ),
@@ -945,11 +946,11 @@ public static function data_value_tokens(): array {
 			'trivia inside the value kept'     => array(
 				'margin: 1px /* a */ 2px',
 				array(
-					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 8, 3 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 8, 3, 'px' ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 11, 1 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_COMMENT, null, 12, 7 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 19, 1 ),
-					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '2', 20, 3 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '2', 20, 3, 'px' ),
 				),
 			),
 			'custom property'                  => array(
@@ -962,6 +963,22 @@ public static function data_value_tokens(): array {
 					self::token( WP_CSS_Token_Processor::TOKEN_NUMBER, '3', 9, 1 ),
 				),
 			),
+			'dimension unit'                   => array(
+				'width: 10px',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '10', 7, 4, 'px' ) ),
+			),
+			'dimension unit decoded'           => array(
+				'width: 1p\\78',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 7, 5, 'px' ) ),
+			),
+			'number has no unit'               => array(
+				'--x: 10',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_NUMBER, '10', 5, 2 ) ),
+			),
+			'percentage has no unit'           => array(
+				'width: 10%',
+				array( self::token( WP_CSS_Token_Processor::TOKEN_PERCENTAGE, '10', 7, 3 ) ),
+			),
 			'empty value'                      => array( 'color:;', array() ),
 			'only important'                   => array( 'color: !important', array() ),
 		);

From a2ea2a4c93d1950e3911c5b444ee6aad23f6d5b6 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 12 Oct 2026 12:28:32 +0400
Subject: [PATCH 39/77] Trim declaration values by token, not by byte

set_value() and append_declaration() trimmed CSS whitespace bytes from the
end of the value. When the last token is an escape of a space or tab, or a
backslash delimiter followed by a newline, the trim removed the byte that
completed it, so the `;` written after the value became part of an escape:
append_declaration( '--x', "a\\ " ) wrote `--x: a\;`, whose value is the
ident `a;`. set_value() rejected the same values because its replacement
check saw the declaration absorb the next one.

Trim only whitespace tokens, and keep one newline after a final backslash
delimiter.
---
 ...lass-wp-html-style-attribute-processor.php | 30 +++++++++++--
 .../wpHtmlStyleAttributeProcessor.php         | 42 +++++++++++++++++++
 2 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index b7bf65dd6ee46..849c45fdbbff1 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -243,7 +243,7 @@ public function set_value( string $value, ?bool $important = null ): bool {
 		}
 
 		$is_important = null === $important ? $declaration['important'] : $important;
-		$text         = $this->serialize_declaration( $declaration['raw_name'], $value, $is_important );
+		$text         = $this->serialize_declaration( $declaration['raw_name'], $this->trim_value( $value ), $is_important );
 		$parsed_value = $this->get_parsed_declaration_value( $text );
 		if ( null === $parsed_value ) {
 			return false;
@@ -439,7 +439,7 @@ public function append_declaration( string $property_name, string $value, bool $
 
 		$separator        = $this->get_append_separator( $insert_at );
 		$serialized_name  = $this->is_custom_property_name( $property_name ) ? $property_name : strtolower( $property_name );
-		$declaration_text = $this->serialize_declaration( $serialized_name, $value, $important );
+		$declaration_text = $this->serialize_declaration( $serialized_name, $this->trim_value( $value ), $important );
 		$parsed_value     = $this->get_parsed_declaration_value( $declaration_text );
 		if ( null === $parsed_value ) {
 			return false;
@@ -1425,10 +1425,34 @@ private function merge_overlapping_lexical_updates( array $updates ): array {
 	 * @return string Serialized declaration.
 	 */
 	private function serialize_declaration( string $property_name, string $value, bool $important ): string {
-		$value = trim( $value, self::WHITESPACE );
 		return $property_name . ': ' . $value . ( $important ? ' !important' : '' ) . ';';
 	}
 
+	/**
+	 * Removes the whitespace tokens before and after a declaration value.
+	 *
+	 * Whitespace consumed by an escape is part of the value, and a `\` before
+	 * a newline keeps one newline so that it does not escape the next byte.
+	 *
+	 * @param string $value CSS declaration value.
+	 * @return string Trimmed value.
+	 */
+	private function trim_value( string $value ): string {
+		$value     = ltrim( $value, self::WHITESPACE );
+		$processor = WP_CSS_Token_Processor::create( $value );
+		$end       = 0;
+		$is_delim  = false;
+
+		while ( $processor->next_token() ) {
+			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $processor->get_token_type() ) {
+				$end      = $processor->get_token_start() + $processor->get_token_length();
+				$is_delim = WP_CSS_Token_Processor::TOKEN_DELIM === $processor->get_token_type() && '\\' === $processor->get_token_value();
+			}
+		}
+
+		return substr( $value, 0, $end ) . ( $is_delim ? "\n" : '' );
+	}
+
 	/**
 	 * Checks whether two property names match.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 526228e63f07c..9d1a667f8a1e4 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -279,6 +279,48 @@ public function test_declaration_values_allow_leading_and_trailing_comments_as_t
 		$this->assertSame( 'color: /* before */ green /* after */; background: /* before */ white /* after */;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::set_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_values_ending_in_escaped_whitespace_or_a_backslash_delimiter
+	 *
+	 * @param string $value   Declaration value.
+	 * @param string $written Expected value text in the updated style.
+	 */
+	public function test_trimming_a_value_keeps_its_final_escape_or_backslash_delimiter( string $value, string $written ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: 1; width: 1px' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->set_value( $value ), 'Expected set_value() to succeed.' );
+		$this->assertSame( "--x: {$written}; width: 1px", $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: 1px' );
+
+		$this->assertTrue( $processor->append_declaration( '--x', $value ), 'Expected append_declaration() to succeed.' );
+		$this->assertSame( "width: 1px; --x: {$written};", $processor->get_updated_style() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public static function data_values_ending_in_escaped_whitespace_or_a_backslash_delimiter() {
+		return array(
+			'escaped space'                   => array( 'a\\ ', 'a\\ ' ),
+			'escaped space, then whitespace'  => array( "a\\  \t", 'a\\ ' ),
+			'escaped tab'                     => array( "a\\\t", "a\\\t" ),
+			'backslash before a newline'      => array( "a\\\n", "a\\\n" ),
+			'backslash, newline, then spaces' => array( "a\\\n  ", "a\\\n" ),
+			'escaped backslash'               => array( 'a\\\\ ', 'a\\\\' ),
+			'escaped backslash, then a delim' => array( "a\\\\\\\n", "a\\\\\\\n" ),
+		);
+	}
+
 	/**
 	 * @covers ::set_value
 	 * @covers ::is_important

From 02465b54f5fd7ad3b71822811a754ac888a94b32 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 12 Oct 2026 12:30:29 +0400
Subject: [PATCH 40/77] Store WP_CSS_Token objects for the style attribute

The processor kept an array per token with the type, the decoded value
and unit, and the offsets, and get_value_tokens() returned those arrays.
It now stores the WP_CSS_Token snapshots from
WP_CSS_Token_Processor::get_token() and returns them, so values are
decoded when read rather than for every token during parsing, and
consumers read the flag and termination that the arrays did not carry.

Declarations stay private arrays, and the processor uses the token
processor rather than extending it.
---
 .../wp-html-style-attribute-processor-spec.md |  26 +--
 ...lass-wp-html-style-attribute-processor.php | 176 ++++++++----------
 .../wpHtmlStyleAttributeProcessor.php         |  41 ++--
 3 files changed, 117 insertions(+), 126 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index f0e800b625337..3db6fc3f679cd 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -133,19 +133,11 @@ same validity rule with the required `--` prefix.
 
 ## Value Tokens
 
-`get_value_tokens()` returns the current declaration's value as a list of CSS
-tokens, or `null` when the cursor is not on a declaration. Each token is an
-array with the keys `type`, `value`, `unit`, `start`, `length`, and `end`:
-
-- `type` is a `WP_CSS_Token_Processor` `TOKEN_*` constant;
-- `value` is the token value as `WP_CSS_Token_Processor::get_token_value()`
-  returns it: decoded, a dimension's number without its unit, a hash's name
-  without `#`, and `null` for tokens without a value;
-- `unit` is the decoded unit of a dimension token, as
-  `WP_CSS_Token_Processor::get_token_unit()` returns it, and `null` for every
-  other token type;
-- `start` and `length` are the token's byte offset and byte length in the
-  style text, and `end` is `start + length`.
+`get_value_tokens()` returns the current declaration's value as a list of
+`WP_CSS_Token` objects, or `null` when the cursor is not on a declaration. A
+token's getters give its type (a `WP_CSS_Token_Processor` `TOKEN_*` constant),
+type flag, decoded value, decoded dimension unit, byte offset and byte length in
+the style text, and whether it ended at its closing delimiter.
 
 The list covers the value only. Leading and trailing whitespace and comments
 and the `!important` priority are excluded; whitespace and comments between
@@ -156,10 +148,10 @@ Offsets index the current style text, which `get_updated_style()` returns.
 Before any mutation that is the text passed to `create()`. A successful
 mutation reparses the updated text, and the offsets follow it.
 
-Re-tokenizing the source slice from the first token's `start` to the last
-token's `end` with `WP_CSS_Token_Processor` yields the same `type`, `value` and
-`unit` sequence. Consumers may rely on this to re-serialize a value or to hand the
-slice to another tokenizer-based check.
+Re-tokenizing the source slice from the first token's start to the end of the
+last token with `WP_CSS_Token_Processor` yields the same type, flag, value,
+unit and termination sequence. Consumers may rely on this to re-serialize a
+value or to hand the slice to another tokenizer-based check.
 
 Two alternatives were considered. A `WP_CSS_Token_Processor` positioned over the
 value's range would need range support in the tokenizer and give consumers a
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 849c45fdbbff1..bbebaea8aa1dd 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -44,9 +44,9 @@ class WP_HTML_Style_Attribute_Processor {
 	private $style;
 
 	/**
-	 * CSS token metadata.
+	 * CSS tokens of the style attribute value.
 	 *
-	 * @var array<int, array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}>
+	 * @var WP_CSS_Token[]
 	 */
 	private $tokens = array();
 
@@ -185,28 +185,13 @@ public function is_important(): ?bool {
 	 * whitespace and comments between value tokens are included. The list is
 	 * empty when the declaration has no value tokens, as in `color:;`.
 	 *
-	 * Each token is an array with these keys:
-	 *
-	 *  - `type`: a {@see WP_CSS_Token_Processor} `TOKEN_*` constant.
-	 *  - `value`: the token value as {@see WP_CSS_Token_Processor::get_token_value()}
-	 *    returns it: a dimension's number without its unit, a hash's name
-	 *    without `#`, a string's decoded contents, and null for tokens
-	 *    without a value.
-	 *  - `unit`: the decoded unit of a dimension token, as
-	 *    {@see WP_CSS_Token_Processor::get_token_unit()} returns it, and null
-	 *    for every other token type.
-	 *  - `start`: byte offset of the token in the style text.
-	 *  - `length`: byte length of the token in the style text.
-	 *  - `end`: byte offset after the token, `start + length`.
-	 *
-	 * Offsets index the current style text, which
+	 * Token offsets index the current style text, which
 	 * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} returns.
 	 * Before any mutation that is the text passed to `create()`.
 	 *
 	 * @since 7.2.0
 	 *
-	 * @return array<int, array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}>|null
-	 *               Value tokens, or null when not on a declaration.
+	 * @return WP_CSS_Token[]|null Value tokens, or null when not on a declaration.
 	 */
 	public function get_value_tokens(): ?array {
 		$declaration = $this->get_current_declaration();
@@ -522,16 +507,7 @@ private function parse(): void {
 		}
 
 		while ( $processor->next_token() ) {
-			$start          = $processor->get_token_start();
-			$length         = $processor->get_token_length();
-			$this->tokens[] = array(
-				'type'   => $processor->get_token_type(),
-				'value'  => $processor->get_token_value(),
-				'unit'   => $processor->get_token_unit(),
-				'start'  => $start,
-				'length' => $length,
-				'end'    => $start + $length,
-			);
+			$this->tokens[] = $processor->get_token();
 		}
 
 		$this->parse_declaration_list();
@@ -561,8 +537,8 @@ private function parse_declaration_list(): void {
 			$leading_start = $previous_item_ends_at;
 			$index         = $this->skip_ignored_tokens( $index );
 
-			while ( $index < $count && WP_CSS_Token_Processor::TOKEN_SEMICOLON === $this->tokens[ $index ]['type'] ) {
-				$previous_item_ends_at = $this->tokens[ $index ]['end'];
+			while ( $index < $count && WP_CSS_Token_Processor::TOKEN_SEMICOLON === $this->tokens[ $index ]->get_type() ) {
+				$previous_item_ends_at = self::get_token_end( $this->tokens[ $index ] );
 				$leading_start         = $previous_item_ends_at;
 				++$index;
 				$index = $this->skip_ignored_tokens( $index );
@@ -572,7 +548,7 @@ private function parse_declaration_list(): void {
 				break;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_AT_KEYWORD === $this->tokens[ $index ]['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_AT_KEYWORD === $this->tokens[ $index ]->get_type() ) {
 				list( $index, $previous_item_ends_at ) = $this->consume_at_rule( $index );
 				continue;
 			}
@@ -603,25 +579,25 @@ private function consume_at_rule( int $index ): array {
 		while ( $index < $count ) {
 			$token = $this->tokens[ $index ];
 
-			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token['type'] ) {
-				return array( $index + 1, $token['end'] );
+			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token->get_type() ) {
+				return array( $index + 1, self::get_token_end( $token ) );
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
 				return $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
@@ -629,7 +605,7 @@ private function consume_at_rule( int $index ): array {
 			++$index;
 		}
 
-		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : self::get_token_end( $this->tokens[ $count - 1 ] );
 		return array( $count, $after );
 	}
 
@@ -647,26 +623,26 @@ private function consume_simple_block( int $index, string $closing_type ): array
 		while ( $index < $count ) {
 			$token = $this->tokens[ $index ];
 
-			if ( $closing_type === $token['type'] ) {
-				return array( $index + 1, $token['end'] );
+			if ( $closing_type === $token->get_type() ) {
+				return array( $index + 1, self::get_token_end( $token ) );
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
@@ -674,7 +650,7 @@ private function consume_simple_block( int $index, string $closing_type ): array
 			++$index;
 		}
 
-		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : self::get_token_end( $this->tokens[ $count - 1 ] );
 		return array( $count, $after );
 	}
 
@@ -690,26 +666,26 @@ private function consume_declaration_segment( int $index ): array {
 		while ( $index < $count ) {
 			$token = $this->tokens[ $index ];
 
-			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token['type'] ) {
-				return array( $index, $token['end'], true );
+			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token->get_type() ) {
+				return array( $index, self::get_token_end( $token ), true );
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
@@ -717,7 +693,7 @@ private function consume_declaration_segment( int $index ): array {
 			++$index;
 		}
 
-		$after = empty( $this->tokens ) ? strlen( $this->style ) : $this->tokens[ $count - 1 ]['end'];
+		$after = empty( $this->tokens ) ? strlen( $this->style ) : self::get_token_end( $this->tokens[ $count - 1 ] );
 		return array( $count, $after, false );
 	}
 
@@ -732,12 +708,12 @@ private function consume_declaration_segment( int $index ): array {
 	 */
 	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
 		$index = $this->skip_ignored_tokens( $start_index, $end_index );
-		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_IDENT !== $this->tokens[ $index ]['type'] ) {
+		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_IDENT !== $this->tokens[ $index ]->get_type() ) {
 			return null;
 		}
 
 		$name_token = $this->tokens[ $index ];
-		$name       = $name_token['value'];
+		$name       = $name_token->get_value();
 		if ( null === $name ) {
 			return null;
 		}
@@ -747,7 +723,7 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 		++$index;
 		$index = $this->skip_ignored_tokens( $index, $end_index );
 
-		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_COLON !== $this->tokens[ $index ]['type'] ) {
+		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_COLON !== $this->tokens[ $index ]->get_type() ) {
 			return null;
 		}
 
@@ -765,23 +741,23 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 		if (
 			null !== $last_value_index &&
 			null !== $before_last_index &&
-			WP_CSS_Token_Processor::TOKEN_IDENT === $this->tokens[ $last_value_index ]['type'] &&
-			0 === strcasecmp( 'important', (string) $this->tokens[ $last_value_index ]['value'] ) &&
-			WP_CSS_Token_Processor::TOKEN_DELIM === $this->tokens[ $before_last_index ]['type'] &&
-			'!' === $this->tokens[ $before_last_index ]['value']
+			WP_CSS_Token_Processor::TOKEN_IDENT === $this->tokens[ $last_value_index ]->get_type() &&
+			0 === strcasecmp( 'important', (string) $this->tokens[ $last_value_index ]->get_value() ) &&
+			WP_CSS_Token_Processor::TOKEN_DELIM === $this->tokens[ $before_last_index ]->get_type() &&
+			'!' === $this->tokens[ $before_last_index ]->get_value()
 		) {
 			$important       = true;
-			$important_start = $this->tokens[ $before_last_index ]['start'];
-			$important_end   = $this->tokens[ $last_value_index ]['end'];
+			$important_start = $this->tokens[ $before_last_index ]->get_start();
+			$important_end   = self::get_token_end( $this->tokens[ $last_value_index ] );
 			$value_end_index = $this->trim_ignored_tokens( $value_start_index, $before_last_index );
 		}
 
 		if ( $value_start_index >= $value_end_index ) {
-			$value_start = $colon_token['end'];
-			$value_end   = $colon_token['end'];
+			$value_start = self::get_token_end( $colon_token );
+			$value_end   = self::get_token_end( $colon_token );
 		} else {
-			$value_start = $this->tokens[ $value_start_index ]['start'];
-			$value_end   = $this->tokens[ $value_end_index - 1 ]['end'];
+			$value_start = $this->tokens[ $value_start_index ]->get_start();
+			$value_end   = self::get_token_end( $this->tokens[ $value_end_index - 1 ] );
 		}
 
 		if ( ! $this->is_parsed_value_valid( $value_start_index, $value_end_index, $this->is_custom_property_name( $name ) ) ) {
@@ -790,9 +766,9 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 
 		return array(
 			'name'            => $name,
-			'raw_name'        => substr( $this->style, $name_token['start'], $name_token['length'] ),
+			'raw_name'        => substr( $this->style, $name_token->get_start(), $name_token->get_length() ),
 			'leading_start'   => $leading_start,
-			'start'           => $name_token['start'],
+			'start'           => $name_token->get_start(),
 			'after'           => $after,
 			'trailing_end'    => $after,
 			'value_start'     => $value_start,
@@ -825,22 +801,22 @@ private function get_top_level_non_ignored_token_indexes( int $start, int $end )
 
 			$top_level_tokens[] = $index;
 
-			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
@@ -890,11 +866,11 @@ private function trim_ignored_tokens( int $start, int $end ): int {
 	 * @return int Byte offset after ignored tokens.
 	 */
 	private function get_trailing_ignored_end( int $index ): int {
-		$end   = $index > 0 && isset( $this->tokens[ $index - 1 ] ) ? $this->tokens[ $index - 1 ]['end'] : 0;
+		$end   = $index > 0 && isset( $this->tokens[ $index - 1 ] ) ? self::get_token_end( $this->tokens[ $index - 1 ] ) : 0;
 		$count = count( $this->tokens );
 
 		while ( $index < $count && $this->is_ignored_token( $this->tokens[ $index ] ) ) {
-			$end = $this->tokens[ $index ]['end'];
+			$end = self::get_token_end( $this->tokens[ $index ] );
 			++$index;
 		}
 
@@ -904,16 +880,26 @@ private function get_trailing_ignored_end( int $index ): int {
 	/**
 	 * Checks whether a token is ignored by declaration-list grammar.
 	 *
-	 * @param array{type:string, value:string|null, start:int, length:int, end:int} $token Token metadata.
+	 * @param WP_CSS_Token $token Token.
 	 * @return bool Whether the token is ignored.
 	 */
-	private function is_ignored_token( array $token ): bool {
+	private function is_ignored_token( WP_CSS_Token $token ): bool {
 		return (
-			WP_CSS_Token_Processor::TOKEN_WHITESPACE === $token['type'] ||
-			WP_CSS_Token_Processor::TOKEN_COMMENT === $token['type']
+			WP_CSS_Token_Processor::TOKEN_WHITESPACE === $token->get_type() ||
+			WP_CSS_Token_Processor::TOKEN_COMMENT === $token->get_type()
 		);
 	}
 
+	/**
+	 * Gets the byte offset after a token.
+	 *
+	 * @param WP_CSS_Token $token Token.
+	 * @return int Byte offset after the token.
+	 */
+	private static function get_token_end( WP_CSS_Token $token ): int {
+		return $token->get_start() + $token->get_length();
+	}
+
 	/**
 	 * Gets the byte offset before contiguous whitespace ending at an offset.
 	 *
@@ -1161,16 +1147,16 @@ private function get_append_separator( int $insert_at ): string {
 			return $insert_at > 0 ? ' ' : '';
 		}
 
-		return WP_CSS_Token_Processor::TOKEN_SEMICOLON === $last_token['type'] ? ' ' : '; ';
+		return WP_CSS_Token_Processor::TOKEN_SEMICOLON === $last_token->get_type() ? ' ' : '; ';
 	}
 
 	/**
 	 * Gets the last top-level non-ignored token before a byte offset.
 	 *
 	 * @param int $insert_at Byte offset before which to scan.
-	 * @return array{type:string, value:string|null, start:int, length:int, end:int}|null Token metadata.
+	 * @return WP_CSS_Token|null Token, or null when there is none.
 	 */
-	private function get_last_top_level_non_ignored_token_before( int $insert_at ): ?array {
+	private function get_last_top_level_non_ignored_token_before( int $insert_at ): ?WP_CSS_Token {
 		$count      = count( $this->tokens );
 		$index      = 0;
 		$last_token = null;
@@ -1178,7 +1164,7 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 		while ( $index < $count ) {
 			$token = $this->tokens[ $index ];
 
-			if ( $token['start'] >= $insert_at ) {
+			if ( $token->get_start() >= $insert_at ) {
 				break;
 			}
 
@@ -1189,22 +1175,22 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 
 			$last_token = $token;
 
-			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
-			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token['type'] ) {
+			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
 				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
@@ -1228,22 +1214,22 @@ private function get_eof_repair( int $insert_at ): ?string {
 		$stack = array();
 
 		foreach ( $this->tokens as $token ) {
-			if ( $token['start'] >= $insert_at ) {
+			if ( $token->get_start() >= $insert_at ) {
 				break;
 			}
 
-			if ( $token['end'] > $insert_at ) {
+			if ( self::get_token_end( $token ) > $insert_at ) {
 				return null;
 			}
 
-			switch ( $token['type'] ) {
+			switch ( $token->get_type() ) {
 				case WP_CSS_Token_Processor::TOKEN_BAD_STRING:
 				case WP_CSS_Token_Processor::TOKEN_BAD_URL:
 					return null;
 
 				case WP_CSS_Token_Processor::TOKEN_COMMENT:
 					if (
-						strlen( $this->style ) === $token['end'] &&
+						strlen( $this->style ) === self::get_token_end( $token ) &&
 						'*/' !== substr( $this->style, -2 )
 					) {
 						return null;
@@ -1295,12 +1281,12 @@ private function get_eof_repair( int $insert_at ): ?string {
 	/**
 	 * Checks whether a URL token source contains its real closing parenthesis.
 	 *
-	 * @param array{type:string, value:string|null, start:int, length:int, end:int} $token URL token metadata.
+	 * @param WP_CSS_Token $token URL token.
 	 * @return bool Whether the URL token was closed in source.
 	 */
-	private function is_url_token_closed( array $token ): bool {
+	private function is_url_token_closed( WP_CSS_Token $token ): bool {
 		$sentinel = ' !wp-style-attribute-processor-sentinel';
-		$source   = substr( $this->style, $token['start'], $token['length'] );
+		$source   = substr( $this->style, $token->get_start(), $token->get_length() );
 		$scanner  = WP_CSS_Token_Processor::create( $source . $sentinel );
 		if ( null === $scanner || ! $scanner->next_token() ) {
 			return false;
@@ -1488,7 +1474,7 @@ private function is_parsed_value_valid( int $start, int $end, bool $is_custom_pr
 
 		for ( $index = $start; $index < $end; $index++ ) {
 			$token = $this->tokens[ $index ];
-			$type  = $token['type'];
+			$type  = $token->get_type();
 
 			if ( empty( $stack ) && ! $this->is_ignored_token( $token ) ) {
 				if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $type ) {
@@ -1497,7 +1483,7 @@ private function is_parsed_value_valid( int $start, int $end, bool $is_custom_pr
 					$has_other_top_level = true;
 				}
 
-				if ( WP_CSS_Token_Processor::TOKEN_DELIM === $type && '!' === $token['value'] ) {
+				if ( WP_CSS_Token_Processor::TOKEN_DELIM === $type && '!' === $token->get_value() ) {
 					return false;
 				}
 			}
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 9d1a667f8a1e4..81754d65cec75 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -165,7 +165,10 @@ public function test_get_value_tokens_covers_only_the_declaration_value( string
 		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( $expected_tokens, $processor->get_value_tokens() );
+		$tokens = $processor->get_value_tokens();
+
+		$this->assertContainsOnlyInstancesOf( WP_CSS_Token::class, $tokens );
+		$this->assertSame( $expected_tokens, array_map( array( self::class, 'token_fields' ), $tokens ) );
 	}
 
 	/**
@@ -181,10 +184,9 @@ public function test_get_value_tokens_decodes_values_and_keeps_source_offsets()
 		$tokens = $processor->get_value_tokens();
 
 		$this->assertCount( 1, $tokens );
-		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $tokens[0]['type'] );
-		$this->assertSame( 'a"b', $tokens[0]['value'] );
-		$this->assertSame( '"a\\"b"', substr( $style, $tokens[0]['start'], $tokens[0]['length'] ) );
-		$this->assertSame( $tokens[0]['start'] + $tokens[0]['length'], $tokens[0]['end'] );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $tokens[0]->get_type() );
+		$this->assertSame( 'a"b', $tokens[0]->get_value() );
+		$this->assertSame( '"a\\"b"', substr( $style, $tokens[0]->get_start(), $tokens[0]->get_length() ) );
 	}
 
 	/**
@@ -201,7 +203,7 @@ public function test_get_value_tokens_follow_the_updated_style_after_mutations()
 		$this->assertTrue( $processor->set_value( 'green' ) );
 		$this->assertSame(
 			array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'green', 7, 5 ) ),
-			$processor->get_value_tokens()
+			array_map( array( self::class, 'token_fields' ), $processor->get_value_tokens() )
 		);
 
 		$this->assertTrue( $processor->remove_declaration() );
@@ -211,7 +213,7 @@ public function test_get_value_tokens_follow_the_updated_style_after_mutations()
 		$this->assertSame( 'background: white', $processor->get_updated_style() );
 		$this->assertSame(
 			array( self::token( WP_CSS_Token_Processor::TOKEN_IDENT, 'white', 12, 5 ) ),
-			$processor->get_value_tokens()
+			array_map( array( self::class, 'token_fields' ), $processor->get_value_tokens() )
 		);
 	}
 
@@ -233,17 +235,18 @@ public function test_get_value_tokens_match_the_retokenized_source_slice( string
 
 		$first = $tokens[0];
 		$last  = $tokens[ count( $tokens ) - 1 ];
-		$slice = substr( $style, $first['start'], $last['end'] - $first['start'] );
+		$slice = substr( $style, $first->get_start(), $last->get_start() + $last->get_length() - $first->get_start() );
 
 		$expected  = array();
 		$tokenizer = WP_CSS_Token_Processor::create( $slice );
 		while ( $tokenizer->next_token() ) {
-			$expected[] = array( $tokenizer->get_token_type(), $tokenizer->get_token_value(), $tokenizer->get_token_unit() );
+			$token      = $tokenizer->get_token();
+			$expected[] = array( $token->get_type(), $token->get_flag(), $token->get_value(), $token->get_unit(), $token->is_terminated() );
 		}
 
 		$actual = array_map(
-			static function ( array $token ): array {
-				return array( $token['type'], $token['value'], $token['unit'] );
+			static function ( WP_CSS_Token $token ): array {
+				return array( $token->get_type(), $token->get_flag(), $token->get_value(), $token->get_unit(), $token->is_terminated() );
 			},
 			$tokens
 		);
@@ -927,13 +930,14 @@ public function test_updated_style_can_be_set_on_html_tag_processor_after_string
 	}
 
 	/**
-	 * Builds a value token array.
+	 * Builds the expected fields of a value token.
 	 *
 	 * @param string      $type   Token type.
 	 * @param string|null $value  Token value.
 	 * @param int         $start  Byte offset of the token.
 	 * @param int         $length Byte length of the token.
-	 * @return array{type:string, value:string|null, unit:string|null, start:int, length:int, end:int}
+	 * @param string|null $unit   Optional. Dimension unit. Default null.
+	 * @return array{type:string, value:string|null, unit:string|null, start:int, length:int}
 	 */
 	private static function token( string $type, ?string $value, int $start, int $length, ?string $unit = null ): array {
 		return array(
@@ -942,10 +946,19 @@ private static function token( string $type, ?string $value, int $start, int $le
 			'unit'   => $unit,
 			'start'  => $start,
 			'length' => $length,
-			'end'    => $start + $length,
 		);
 	}
 
+	/**
+	 * Reads the fields of a value token that the expectations compare.
+	 *
+	 * @param WP_CSS_Token $token Value token.
+	 * @return array{type:string, value:string|null, unit:string|null, start:int, length:int}
+	 */
+	private static function token_fields( WP_CSS_Token $token ): array {
+		return self::token( $token->get_type(), $token->get_value(), $token->get_start(), $token->get_length(), $token->get_unit() );
+	}
+
 	/**
 	 * Data provider.
 	 *

From b8bbf3a9fa2556c44a006beb51a8807ecb93bc0a Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 12 Oct 2026 12:40:00 +0400
Subject: [PATCH 41/77] Read token termination for the EOF repair

get_eof_repair() decided whether a comment or url token at the end of
the style was closed by reading bytes: a comment counted as closed when
the style ended in `*/`, and a url token was re-tokenized with a
sentinel appended. WP_CSS_Token::is_terminated() records the answer, so
use it and delete is_url_token_closed().

The byte check counted `/*/` as a closed comment. Appending after it
still failed, because the parse check rejects a declaration absorbed by
the comment; the new test pins that result, which is the same before
and after this change.
---
 ...lass-wp-html-style-attribute-processor.php | 31 ++-----------------
 .../wpHtmlStyleAttributeProcessor.php         | 20 ++++++++++--
 2 files changed, 20 insertions(+), 31 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index bbebaea8aa1dd..75a3df2edc43f 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -1228,10 +1228,7 @@ private function get_eof_repair( int $insert_at ): ?string {
 					return null;
 
 				case WP_CSS_Token_Processor::TOKEN_COMMENT:
-					if (
-						strlen( $this->style ) === self::get_token_end( $token ) &&
-						'*/' !== substr( $this->style, -2 )
-					) {
+					if ( ! $token->is_terminated() ) {
 						return null;
 					}
 					break;
@@ -1242,7 +1239,7 @@ private function get_eof_repair( int $insert_at ): ?string {
 					break;
 
 				case WP_CSS_Token_Processor::TOKEN_URL:
-					if ( ! $this->is_url_token_closed( $token ) ) {
+					if ( ! $token->is_terminated() ) {
 						$stack[] = ')';
 					}
 					break;
@@ -1278,30 +1275,6 @@ private function get_eof_repair( int $insert_at ): ?string {
 		return implode( '', array_reverse( $stack ) );
 	}
 
-	/**
-	 * Checks whether a URL token source contains its real closing parenthesis.
-	 *
-	 * @param WP_CSS_Token $token URL token.
-	 * @return bool Whether the URL token was closed in source.
-	 */
-	private function is_url_token_closed( WP_CSS_Token $token ): bool {
-		$sentinel = ' !wp-style-attribute-processor-sentinel';
-		$source   = substr( $this->style, $token->get_start(), $token->get_length() );
-		$scanner  = WP_CSS_Token_Processor::create( $source . $sentinel );
-		if ( null === $scanner || ! $scanner->next_token() ) {
-			return false;
-		}
-
-		if (
-			WP_CSS_Token_Processor::TOKEN_URL !== $scanner->get_token_type() ||
-			$scanner->get_token_length() > strlen( $source )
-		) {
-			return false;
-		}
-
-		return $scanner->next_token();
-	}
-
 	/**
 	 * Checks whether an appended declaration will parse as a new declaration.
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 81754d65cec75..e00f85b8e07c0 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -732,15 +732,31 @@ public function test_append_declaration_repairs_unclosed_eof_component_values()
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_styles_ending_inside_a_comment
+	 *
+	 * @param string $style Style text.
 	 */
-	public function test_append_declaration_rejects_eof_repairs_that_cannot_be_precise() {
-		$style     = 'color: var(--x;/*keep';
+	public function test_append_declaration_rejects_eof_repairs_that_cannot_be_precise( string $style ) {
 		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
 
 		$this->assertFalse( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( $style, $processor->get_updated_style() );
 	}
 
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function data_styles_ending_inside_a_comment(): array {
+		return array(
+			'comment inside an open function' => array( 'color: var(--x;/*keep' ),
+			'comment after a declaration'     => array( 'color: red /* keep' ),
+			'comment ending in a slash'       => array( 'color: red /*/' ),
+		);
+	}
+
 	/**
 	 * @covers ::next_declaration
 	 * @covers ::get_updated_style

From e87aecfad7dd5ae29e18caad1ca7a43c9ecc6f90 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 17:28:12 +0400
Subject: [PATCH 42/77] Add serialize_declaration() to the style attribute
 processor

Code that reads a declaration and needs to write it back, such as a
filter that keeps some declarations and drops others, had no public way
to do so: WP_CSS_Token_Serializer is internal, and the processor wrote
text only through mutations.

serialize_declaration() returns the declaration at the cursor as
`name: value;` or `name: value !important;`, as CSSOM writes a
declaration, or null when the cursor is not on a declaration, like the
other getters. The name is escaped as an identifier and the value is
written by WP_CSS_Token_Serializer, so comments are dropped, whitespace
runs become one space, and blocks left open at the end of the style are
closed. The name follows WP_HTML_Processor::serialize_token().

The private formatter it shares with set_value() and
append_declaration() is renamed format_declaration().
---
 .../wp-html-style-attribute-processor-spec.md |  14 ++
 ...lass-wp-html-style-attribute-processor.php |  42 +++++-
 .../wpHtmlStyleAttributeProcessor.php         | 140 ++++++++++++++++++
 3 files changed, 189 insertions(+), 7 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 3db6fc3f679cd..9e96a1f4eb374 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -68,6 +68,7 @@ public function next_declaration( ?string $property_name = null ): bool;
 public function get_property_name(): ?string;
 public function is_important(): ?bool;
 public function get_value_tokens(): ?array;
+public function serialize_declaration(): ?string;
 public function set_value( string $value, ?bool $important = null ): bool;
 public function set_important( bool $important ): bool;
 public function remove_declaration(): bool;
@@ -158,6 +159,19 @@ value's range would need range support in the tokenizer and give consumers a
 forward-only cursor over tokens the processor already holds. A raw string would
 be re-tokenized by every consumer.
 
+## Serializing A Declaration
+
+`serialize_declaration()` writes the current declaration from its parsed parts,
+or returns `null` when the cursor is not on a declaration. The property name is
+escaped as an identifier. The value is written from its tokens with
+`WP_CSS_Token_Serializer::serialize()`: comments are dropped, each whitespace run
+becomes one space, and blocks left open at the end of the style are closed. The
+result is `name: value;` or `name: value !important;`, and CSS reads it as the same
+declaration.
+
+This is the public way to write CSS from a parsed declaration. Token lists are
+not a public unit for writing CSS: `WP_CSS_Token_Serializer` is internal.
+
 ## Value Validation
 
 Mutation inputs accept CSS declaration values, not declaration-list text.
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 75a3df2edc43f..603f9f1cd2552 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -203,6 +203,34 @@ public function get_value_tokens(): ?array {
 		return array_slice( $this->tokens, $start, $end - $start );
 	}
 
+	/**
+	 * Serializes the current declaration.
+	 *
+	 * The property name is escaped as an identifier, and the value is written
+	 * from its tokens: comments are dropped, each whitespace run becomes one
+	 * space, and blocks left open at the end of the style are closed. The
+	 * result is `name: value;` or `name: value !important;`, as in CSSOM, and
+	 * CSS reads it as the same declaration.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @see WP_CSS_Token_Serializer::serialize()
+	 *
+	 * @return string|null Declaration text, or null when not on a declaration.
+	 */
+	public function serialize_declaration(): ?string {
+		$declaration = $this->get_current_declaration();
+		if ( null === $declaration ) {
+			return null;
+		}
+
+		return $this->format_declaration(
+			WP_CSS_Token_Serializer::escape_ident( $declaration['name'] ),
+			WP_CSS_Token_Serializer::serialize( $this->get_value_tokens() ),
+			$declaration['important']
+		);
+	}
+
 	/**
 	 * Sets the value of the current declaration.
 	 *
@@ -228,7 +256,7 @@ public function set_value( string $value, ?bool $important = null ): bool {
 		}
 
 		$is_important = null === $important ? $declaration['important'] : $important;
-		$text         = $this->serialize_declaration( $declaration['raw_name'], $this->trim_value( $value ), $is_important );
+		$text         = $this->format_declaration( $declaration['raw_name'], $this->trim_value( $value ), $is_important );
 		$parsed_value = $this->get_parsed_declaration_value( $text );
 		if ( null === $parsed_value ) {
 			return false;
@@ -424,7 +452,7 @@ public function append_declaration( string $property_name, string $value, bool $
 
 		$separator        = $this->get_append_separator( $insert_at );
 		$serialized_name  = $this->is_custom_property_name( $property_name ) ? $property_name : strtolower( $property_name );
-		$declaration_text = $this->serialize_declaration( $serialized_name, $this->trim_value( $value ), $important );
+		$declaration_text = $this->format_declaration( $serialized_name, $this->trim_value( $value ), $important );
 		$parsed_value     = $this->get_parsed_declaration_value( $declaration_text );
 		if ( null === $parsed_value ) {
 			return false;
@@ -1376,14 +1404,14 @@ private function merge_overlapping_lexical_updates( array $updates ): array {
 	}
 
 	/**
-	 * Serializes a declaration.
+	 * Formats a declaration as `name: value;` or `name: value !important;`.
 	 *
-	 * @param string $property_name CSS property name.
-	 * @param string $value         CSS declaration value.
+	 * @param string $property_name CSS property name text.
+	 * @param string $value         CSS declaration value text.
 	 * @param bool   $important     Whether to append !important.
-	 * @return string Serialized declaration.
+	 * @return string Declaration text.
 	 */
-	private function serialize_declaration( string $property_name, string $value, bool $important ): string {
+	private function format_declaration( string $property_name, string $value, bool $important ): string {
 		return $property_name . ': ' . $value . ( $important ? ' !important' : '' ) . ';';
 	}
 
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index e00f85b8e07c0..96274b54cc73f 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -254,6 +254,146 @@ static function ( WP_CSS_Token $token ): array {
 		$this->assertSame( $expected, $actual );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize_declaration
+	 * @covers ::remove_declaration
+	 */
+	public function test_serialize_declaration_returns_null_when_not_on_a_declaration() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+
+		$this->assertNull( $processor->serialize_declaration(), 'Expected null before the first declaration.' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->remove_declaration() );
+		$this->assertNull( $processor->serialize_declaration(), 'Expected null after removing the declaration.' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertFalse( $processor->next_declaration() );
+		$this->assertNull( $processor->serialize_declaration(), 'Expected null after the last declaration.' );
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize_declaration
+	 *
+	 * @dataProvider data_serialized_declarations
+	 *
+	 * @param string $style    Style text.
+	 * @param string $expected Expected text of the first declaration.
+	 */
+	public function test_serialize_declaration_writes_the_current_declaration( string $style, string $expected ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertSame( $expected, $processor->serialize_declaration() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string,string}>
+	 */
+	public static function data_serialized_declarations(): array {
+		return array(
+			'single ident'                     => array( 'color: red', 'color: red;' ),
+			'important'                        => array( 'color : red ! important ;', 'color: red !important;' ),
+			'important after a comment'        => array( 'color: red /* x */ !important', 'color: red !important;' ),
+			'lowercased name'                  => array( 'COLOR: Red', 'color: Red;' ),
+			'escaped name'                     => array( 'c\\6f lor: red', 'color: red;' ),
+			'custom property keeps its case'   => array( '--Foo: a b', '--Foo: a b;' ),
+			'custom property name escape'      => array( '--a\\ b: 1', '--a\\20 b: 1;' ),
+			'comments and whitespace runs'     => array( "margin: 1px /* a */ \t 2px", 'margin: 1px 2px;' ),
+			'comment between tokens'           => array( 'margin: 1px/**/2px', 'margin: 1px/**/2px;' ),
+			'empty value'                      => array( 'color:;', 'color: ;' ),
+			'string'                           => array( "font-family: 'a\"b'", 'font-family: "a\\22 b";' ),
+			'value ending in an escaped space' => array( '--x: a\\ ', '--x: a\\20 ;' ),
+			'backslash before a newline'       => array( "--x: a\\\n; width: 1px", "--x: a\\\n;" ),
+			'block open at the end'            => array( 'width: calc(1px + (2px', 'width: calc(1px + (2px));' ),
+			'url open at the end'              => array( 'background: url(a.png', 'background: url(a.png);' ),
+			'semicolon inside an open block'   => array( 'width: calc(1px; color: red', 'width: calc(1px; color: red);' ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize_declaration
+	 *
+	 * @dataProvider data_value_tokens_source_slices
+	 *
+	 * @param string $style Style text.
+	 */
+	public function test_serialize_declaration_reads_back_as_the_same_declaration( string $style ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$this->assertTrue( $processor->next_declaration() );
+
+		$reread = WP_HTML_Style_Attribute_Processor::create( $processor->serialize_declaration() );
+		$this->assertTrue( $reread->next_declaration() );
+
+		$this->assertSame( $processor->get_property_name(), $reread->get_property_name() );
+		$this->assertSame( $processor->is_important(), $reread->is_important() );
+		$this->assertSame(
+			self::significant_tokens( $processor->get_value_tokens() ),
+			self::significant_tokens( $reread->get_value_tokens() )
+		);
+		$this->assertFalse( $reread->next_declaration(), 'Expected exactly one declaration.' );
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::serialize_declaration
+	 * @covers ::set_value
+	 */
+	public function test_serialize_declaration_follows_mutations() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->set_value( 'green /* c */', true ) );
+		$this->assertSame( 'color: green !important;', $processor->serialize_declaration() );
+	}
+
+	/**
+	 * Reads the fields that give a value its meaning, closing blocks left open.
+	 *
+	 * @param WP_CSS_Token[] $tokens Value tokens.
+	 * @return array[] Type, flag, value and unit of each token except whitespace and comments.
+	 */
+	private static function significant_tokens( array $tokens ): array {
+		$closers = array(
+			WP_CSS_Token_Processor::TOKEN_FUNCTION     => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+			WP_CSS_Token_Processor::TOKEN_LEFT_PAREN   => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+			WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET,
+			WP_CSS_Token_Processor::TOKEN_LEFT_BRACE   => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+		);
+		$open    = array();
+		$fields  = array();
+
+		foreach ( $tokens as $token ) {
+			$type = $token->get_type();
+			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE === $type || WP_CSS_Token_Processor::TOKEN_COMMENT === $type ) {
+				continue;
+			}
+
+			if ( isset( $closers[ $type ] ) ) {
+				$open[] = $closers[ $type ];
+			} elseif ( in_array( $type, $closers, true ) ) {
+				array_pop( $open );
+			}
+
+			$fields[] = array( $type, $token->get_flag(), $token->get_value(), $token->get_unit() );
+		}
+
+		foreach ( array_reverse( $open ) as $type ) {
+			$fields[] = array( $type, null, null, null );
+		}
+
+		return $fields;
+	}
+
 	/**
 	 * @covers ::set_value
 	 * @covers ::get_updated_style

From 9907e3fc5b46c925914fab10b8ae8cf8c189dc9a Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Mon, 12 Oct 2026 12:44:12 +0400
Subject: [PATCH 43/77] Document the cost of remove_declaration()

Every successful mutation parses the whole style text again, so removing
declarations one at a time takes time that grows with the square of the
style's length. Measured on this branch, removing every declaration of a
style takes 12, 189 and 744 ms for 50, 200 and 400 declarations, while
reading them all and joining serialize_declaration() takes 0.3, 1.2 and
2.4 ms. Say so on remove_declaration() and in the spec, and point to the
alternative.
---
 docs/wp-html-style-attribute-processor-spec.md               | 5 +++++
 .../html-api/class-wp-html-style-attribute-processor.php     | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 9e96a1f4eb374..04d085e3af2e4 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -111,6 +111,11 @@ advancement must reflect the updated declaration list.
 Current-position getters should reflect successful pending edits without forcing
 a full reparse where practical, following HTML API style.
 
+Each successful mutation parses the whole style text again. Removing most of the
+declarations of a long style one at a time therefore takes time that grows with
+the square of its length. To keep some declarations, read them and join the
+`serialize_declaration()` output of the ones to keep.
+
 ## Property Names
 
 All public property-name arguments are decoded/plaintext CSS property names, not
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 603f9f1cd2552..91cef4bc3fdbe 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -387,6 +387,11 @@ public function set_important( bool $important ): bool {
 	 * Only the current declaration is removed. Other declarations with the same
 	 * property name remain in place.
 	 *
+	 * Each call parses the whole style text again, so removing most of the
+	 * declarations of a long style one at a time is slow. To keep some
+	 * declarations, join the {@see WP_HTML_Style_Attribute_Processor::serialize_declaration()}
+	 * output of the ones to keep instead.
+	 *
 	 * @since 7.2.0
 	 *
 	 * @return bool Whether the current declaration was removed.

From 190cd2ed9dfee874f376aa8cce9a66629e516c79 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 17:31:39 +0400
Subject: [PATCH 44/77] Write set_value() and append_declaration() from tokens

set_value() and append_declaration() checked that a supplied value parses
as one declaration value, then wrote the caller's bytes: comments,
whitespace runs, raw control characters inside strings and any escape
spelling reached the style. They now write the declaration as
serialize_declaration() does: the name is escaped as an identifier and
the value is written by WP_CSS_Token_Serializer from its tokens, with the
whitespace and comments around it removed. set_value() writes the
decoded name, so `c\6f lor` becomes `color`.

trim_value() and the raw_name field have no other use and are removed.
---
 .../wp-html-style-attribute-processor-spec.md | 18 +++--
 ...lass-wp-html-style-attribute-processor.php | 56 +++++++------
 .../wpHtmlStyleAttributeProcessor.php         | 80 ++++++++++++++++---
 3 files changed, 114 insertions(+), 40 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 04d085e3af2e4..84f8c9f1cbaff 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -129,9 +129,9 @@ exactly because casing is semantic.
 - ordinary property names are returned lowercase;
 - custom property names preserve exact decoded casing.
 
-Edits preserve authored property-name spelling when the declaration already
-exists. Appended ordinary properties serialize lowercase because there is no
-authored spelling to preserve. Appended custom properties preserve exact casing.
+Edits and appends write the property name as `get_property_name()` returns it,
+escaped as an identifier: ordinary properties lowercase, custom properties with
+their exact casing.
 
 Appended property names must be valid plaintext CSS property names. The processor
 does not escape arbitrary strings into identifiers. Custom properties follow the
@@ -262,11 +262,15 @@ declaration value must be strict: it must serialize from parsed token/component
 data with equivalent CSS semantics. If equivalence cannot be proven, the
 mutation returns `false`.
 
-`set_value()` trims supplied values according to CSS whitespace.
+`set_value()` and `append_declaration()` write a declaration as
+`serialize_declaration()` does: `name: value;` or `name: value !important;`, with
+the name escaped as an identifier and the value written from its tokens. Comments
+and whitespace before and after a supplied value are removed, comments inside it
+are dropped, and each whitespace run inside it becomes one space. Nothing is
+copied from the supplied text.
 
-When possible, `set_value()` replaces the current declaration's value and
-priority portion rather than normalizing the whole declaration. Correctness wins
-over whitespace preservation.
+`set_value()` rewrites the whole current declaration; text around it is
+unchanged.
 
 ## Invalid Fragments
 
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 91cef4bc3fdbe..ce796161df09d 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -53,7 +53,7 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Parsed declarations.
 	 *
-	 * @var array<int, array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
+	 * @var array<int, array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
 
@@ -234,6 +234,10 @@ public function serialize_declaration(): ?string {
 	/**
 	 * Sets the value of the current declaration.
 	 *
+	 * The declaration is written as serialize_declaration() writes it: the
+	 * name is escaped as an identifier and the value is written from its
+	 * tokens.
+	 *
 	 * @since 7.2.0
 	 *
 	 * @param string    $value     CSS declaration value, without the property name.
@@ -256,7 +260,7 @@ public function set_value( string $value, ?bool $important = null ): bool {
 		}
 
 		$is_important = null === $important ? $declaration['important'] : $important;
-		$text         = $this->format_declaration( $declaration['raw_name'], $this->trim_value( $value ), $is_important );
+		$text         = $this->format_declaration( WP_CSS_Token_Serializer::escape_ident( $declaration['name'] ), $this->serialize_value( $value ), $is_important );
 		$parsed_value = $this->get_parsed_declaration_value( $text );
 		if ( null === $parsed_value ) {
 			return false;
@@ -426,7 +430,9 @@ public function remove_declaration(): bool {
 	 * Appends a declaration to the style attribute value.
 	 *
 	 * Appending does not remove or replace existing declarations with the same
-	 * property name.
+	 * property name. The declaration is written as serialize_declaration()
+	 * writes it: the name is escaped as an identifier and the value is
+	 * written from its tokens.
 	 *
 	 * @since 7.2.0
 	 *
@@ -456,14 +462,14 @@ public function append_declaration( string $property_name, string $value, bool $
 		}
 
 		$separator        = $this->get_append_separator( $insert_at );
-		$serialized_name  = $this->is_custom_property_name( $property_name ) ? $property_name : strtolower( $property_name );
-		$declaration_text = $this->format_declaration( $serialized_name, $this->trim_value( $value ), $important );
+		$name             = $this->is_custom_property_name( $property_name ) ? $property_name : strtolower( $property_name );
+		$declaration_text = $this->format_declaration( WP_CSS_Token_Serializer::escape_ident( $name ), $this->serialize_value( $value ), $important );
 		$parsed_value     = $this->get_parsed_declaration_value( $declaration_text );
 		if ( null === $parsed_value ) {
 			return false;
 		}
 
-		if ( ! $this->is_parseable_append( $repair_at, $eof_repair, $separator, $declaration_text, $old_declaration_count, $serialized_name, $parsed_value, $important ) ) {
+		if ( ! $this->is_parseable_append( $repair_at, $eof_repair, $separator, $declaration_text, $old_declaration_count, $name, $parsed_value, $important ) ) {
 			return false;
 		}
 
@@ -737,7 +743,7 @@ private function consume_declaration_segment( int $index ): array {
 	 * @param int $start_index   First token index in the segment.
 	 * @param int $end_index     Token index after the segment.
 	 * @param int $after         Byte offset after the declaration.
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @return array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
 		$index = $this->skip_ignored_tokens( $start_index, $end_index );
@@ -799,7 +805,6 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 
 		return array(
 			'name'            => $name,
-			'raw_name'        => substr( $this->style, $name_token->get_start(), $name_token->get_length() ),
 			'leading_start'   => $leading_start,
 			'start'           => $name_token->get_start(),
 			'after'           => $after,
@@ -966,7 +971,7 @@ private function get_offset_after_following_whitespace( int $offset ): int {
 	/**
 	 * Gets the current declaration metadata.
 	 *
-	 * @return array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @return array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function get_current_declaration(): ?array {
 		if (
@@ -983,7 +988,7 @@ private function get_current_declaration(): ?array {
 	/**
 	 * Checks whether a replacement preserves the current declaration's structure.
 	 *
-	 * @param array{name:string, raw_name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
+	 * @param array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
 	 * @param int                                                                                                                                                                                                                           $start              Byte offset at which to start the replacement.
 	 * @param int                                                                                                                                                                                                                           $length             Number of bytes to replace.
 	 * @param string                                                                                                                                                                                                                        $text               Replacement text.
@@ -1421,28 +1426,31 @@ private function format_declaration( string $property_name, string $value, bool
 	}
 
 	/**
-	 * Removes the whitespace tokens before and after a declaration value.
+	 * Writes a declaration value from its tokens.
 	 *
-	 * Whitespace consumed by an escape is part of the value, and a `\` before
-	 * a newline keeps one newline so that it does not escape the next byte.
+	 * Whitespace and comments before and after the value are removed, and the
+	 * rest is written as serialize_declaration() writes a value.
 	 *
 	 * @param string $value CSS declaration value.
-	 * @return string Trimmed value.
+	 * @return string Value text.
 	 */
-	private function trim_value( string $value ): string {
-		$value     = ltrim( $value, self::WHITESPACE );
+	private function serialize_value( string $value ): string {
 		$processor = WP_CSS_Token_Processor::create( $value );
-		$end       = 0;
-		$is_delim  = false;
-
+		$tokens    = array();
 		while ( $processor->next_token() ) {
-			if ( WP_CSS_Token_Processor::TOKEN_WHITESPACE !== $processor->get_token_type() ) {
-				$end      = $processor->get_token_start() + $processor->get_token_length();
-				$is_delim = WP_CSS_Token_Processor::TOKEN_DELIM === $processor->get_token_type() && '\\' === $processor->get_token_value();
-			}
+			$tokens[] = $processor->get_token();
+		}
+
+		$start = 0;
+		$end   = count( $tokens );
+		while ( $start < $end && $this->is_ignored_token( $tokens[ $start ] ) ) {
+			++$start;
+		}
+		while ( $end > $start && $this->is_ignored_token( $tokens[ $end - 1 ] ) ) {
+			--$end;
 		}
 
-		return substr( $value, 0, $end ) . ( $is_delim ? "\n" : '' );
+		return WP_CSS_Token_Serializer::serialize( array_slice( $tokens, $start, $end - $start ) );
 	}
 
 	/**
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 96274b54cc73f..3051ee63da883 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -419,7 +419,7 @@ public function test_declaration_values_allow_leading_and_trailing_comments_as_t
 		$this->assertTrue( $processor->set_value( '/* before */ green /* after */' ) );
 		$this->assertTrue( $processor->append_declaration( 'background', '/* before */ white /* after */' ) );
 
-		$this->assertSame( 'color: /* before */ green /* after */; background: /* before */ white /* after */;', $processor->get_updated_style() );
+		$this->assertSame( 'color: green; background: white;', $processor->get_updated_style() );
 	}
 
 	/**
@@ -454,16 +454,78 @@ public function test_trimming_a_value_keeps_its_final_escape_or_backslash_delimi
 	 */
 	public static function data_values_ending_in_escaped_whitespace_or_a_backslash_delimiter() {
 		return array(
-			'escaped space'                   => array( 'a\\ ', 'a\\ ' ),
-			'escaped space, then whitespace'  => array( "a\\  \t", 'a\\ ' ),
-			'escaped tab'                     => array( "a\\\t", "a\\\t" ),
+			'escaped space'                   => array( 'a\\ ', 'a\\20 ' ),
+			'escaped space, then whitespace'  => array( "a\\  \t", 'a\\20 ' ),
+			'escaped tab'                     => array( "a\\\t", 'a\\9 ' ),
 			'backslash before a newline'      => array( "a\\\n", "a\\\n" ),
 			'backslash, newline, then spaces' => array( "a\\\n  ", "a\\\n" ),
-			'escaped backslash'               => array( 'a\\\\ ', 'a\\\\' ),
-			'escaped backslash, then a delim' => array( "a\\\\\\\n", "a\\\\\\\n" ),
+			'escaped backslash'               => array( 'a\\\\ ', 'a\\5c ' ),
+			'escaped backslash, then a delim' => array( "a\\\\\\\n", "a\\5c \\\n" ),
 		);
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::set_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_values_written_from_tokens
+	 *
+	 * @param string $value   Declaration value.
+	 * @param string $written Expected value text in the updated style.
+	 */
+	public function test_set_value_and_append_declaration_write_the_value_from_its_tokens( string $value, string $written ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: 1; width: 1px' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->set_value( $value ), 'Expected set_value() to succeed.' );
+		$this->assertSame( "--x: {$written}; width: 1px", $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: 1px' );
+
+		$this->assertTrue( $processor->append_declaration( '--x', $value ), 'Expected append_declaration() to succeed.' );
+		$this->assertSame( "width: 1px; --x: {$written};", $processor->get_updated_style() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public static function data_values_written_from_tokens() {
+		return array(
+			'comments and whitespace runs'  => array( " \t/* a */ a \t/* b */  b /* c */ ", 'a b' ),
+			'comment between tokens'        => array( 'a/**/b', 'a/**/b' ),
+			'escaped ident'                 => array( '\\66 oo', 'foo' ),
+			'single-quoted string'          => array( "'a'", '"a"' ),
+			'control character in a string' => array( "\"a\x01b\"", '"a\\1 b"' ),
+			'url with spaces and ampersand' => array( 'url( a&b )', 'url(a\\26 b)' ),
+			'non-ident code point in ident' => array( "a\u{A0}b", 'a\\a0 b' ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::set_value
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_set_value_and_append_declaration_write_the_name_as_an_identifier() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'C\\6f LOR: red' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->set_value( 'blue' ) );
+		$this->assertSame( 'color: blue;', $processor->get_updated_style() );
+
+		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+
+		$this->assertTrue( $processor->append_declaration( "--a\u{A0}b", '1' ) );
+		$this->assertSame( '--a\\a0 b: 1;', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::set_value
 	 * @covers ::is_important
@@ -956,18 +1018,18 @@ public function test_custom_property_values_may_mix_blocks_with_other_tokens() {
 	 * @covers ::set_value
 	 * @covers ::get_updated_style
 	 */
-	public function test_escaped_property_names_match_decoded_names_and_preserve_raw_spelling() {
+	public function test_escaped_property_names_match_decoded_names_and_are_written_as_identifiers() {
 		$processor = WP_HTML_Style_Attribute_Processor::create( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertSame( 'color', $processor->get_property_name() );
 		$this->assertTrue( $processor->set_value( 'green' ) );
-		$this->assertSame( 'c\\6f lor: green; --t\\6f ne: cool; --Tone: warm;', $processor->get_updated_style() );
+		$this->assertSame( 'color: green; --t\\6f ne: cool; --Tone: warm;', $processor->get_updated_style() );
 
 		$this->assertTrue( $processor->next_declaration( '--tone' ) );
 		$this->assertSame( '--tone', $processor->get_property_name() );
 		$this->assertTrue( $processor->set_value( 'cold' ) );
-		$this->assertSame( 'c\\6f lor: green; --t\\6f ne: cold; --Tone: warm;', $processor->get_updated_style() );
+		$this->assertSame( 'color: green; --tone: cold; --Tone: warm;', $processor->get_updated_style() );
 
 		$this->assertFalse( $processor->next_declaration( '--tone' ) );
 	}

From 755bff5e070ed2eb6f0786cd99031c98a6c3f068 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 13 Oct 2026 17:32:51 +0400
Subject: [PATCH 45/77] Close strings and comments left open before an append

CSS closes a string or a comment that the end of the input cuts off, and
so does WP_CSS_Token_Serializer::serialize(), but get_eof_repair()
closed only blocks and urls: append_declaration() and set_important()
returned false after `font-family: "a` or `color: red /* x`. The repair
now writes the string's own quote or `*/` before the block closers. A `\`
at the end of the style still makes the append fail, because no appended
text can end the escape it starts.
---
 .../wp-html-style-attribute-processor-spec.md |  6 +-
 ...lass-wp-html-style-attribute-processor.php | 19 ++++--
 .../wpHtmlStyleAttributeProcessor.php         | 58 +++++++++++++++++--
 3 files changed, 71 insertions(+), 12 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 84f8c9f1cbaff..d0060646e8262 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -306,8 +306,10 @@ semantics and structure.
 when the processor can preserve existing CSS semantics.
 
 When trailing declaration text is valid only because CSS closes an unclosed
-function or block at EOF, appending must materialize the missing closing
-delimiters before inserting the new declaration.
+string, comment, function or block at EOF, appending must materialize the
+missing closing delimiters before inserting the new declaration. A string is
+closed with the quote it starts with and a comment with `*/`. A `\` at EOF
+cannot be closed this way, so append returns `false`.
 
 Example:
 
diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index ce796161df09d..b3108d5ae8238 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -1242,14 +1242,16 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 	/**
 	 * Gets required closing delimiters before appending at EOF.
 	 *
-	 * CSS closes unterminated functions and simple blocks at EOF. Appending must
-	 * materialize those closers before adding a new declaration.
+	 * CSS closes unterminated strings, comments, functions and simple blocks at
+	 * EOF. Appending must materialize those closers before adding a new
+	 * declaration.
 	 *
 	 * @param int $insert_at Byte offset at which the declaration will be inserted.
 	 * @return string|null Closing delimiters, or null when repair cannot be precise.
 	 */
 	private function get_eof_repair( int $insert_at ): ?string {
-		$stack = array();
+		$stack        = array();
+		$token_closer = '';
 
 		foreach ( $this->tokens as $token ) {
 			if ( $token->get_start() >= $insert_at ) {
@@ -1267,7 +1269,14 @@ private function get_eof_repair( int $insert_at ): ?string {
 
 				case WP_CSS_Token_Processor::TOKEN_COMMENT:
 					if ( ! $token->is_terminated() ) {
-						return null;
+						$token_closer = '*/';
+					}
+					break;
+
+				case WP_CSS_Token_Processor::TOKEN_STRING:
+					if ( ! $token->is_terminated() ) {
+						// The string ends with the quote it starts with.
+						$token_closer = $this->style[ $token->get_start() ];
 					}
 					break;
 
@@ -1310,7 +1319,7 @@ private function get_eof_repair( int $insert_at ): ?string {
 			}
 		}
 
-		return implode( '', array_reverse( $stack ) );
+		return $token_closer . implode( '', array_reverse( $stack ) );
 	}
 
 	/**
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 3051ee63da883..ec67adccd5422 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -931,11 +931,60 @@ public function test_append_declaration_repairs_unclosed_eof_component_values()
 		$this->assertSame( 'background: url(foo\\)); border: 0;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_styles_ending_inside_a_string_or_comment
+	 *
+	 * @param string $style    Style text.
+	 * @param string $expected Updated style text.
+	 */
+	public function test_append_declaration_closes_strings_and_comments_left_open( string $style, string $expected ) {
+		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+
+		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
+		$this->assertSame( $expected, $processor->get_updated_style() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string, string}>
+	 */
+	public static function data_styles_ending_inside_a_string_or_comment(): array {
+		return array(
+			'comment inside an open function' => array( 'color: var(--x;/*keep', 'color: var(--x;/*keep*/); background: white;' ),
+			'comment after a declaration'     => array( 'color: red /* keep', 'color: red /* keep*/; background: white;' ),
+			'comment ending in a slash'       => array( 'color: red /*/', 'color: red /*/*/; background: white;' ),
+			'comment ending in a backslash'   => array( 'color: red /* \\', 'color: red /* \\*/; background: white;' ),
+			'double-quoted string'            => array( 'font-family: "a', 'font-family: "a"; background: white;' ),
+			'single-quoted string'            => array( "font-family: 'a", "font-family: 'a'; background: white;" ),
+			'string inside an open function'  => array( 'width: var(--x, "a', 'width: var(--x, "a"); background: white;' ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::set_important
+	 * @covers ::get_updated_style
+	 */
+	public function test_set_important_closes_a_string_left_open() {
+		$processor = WP_HTML_Style_Attribute_Processor::create( 'font-family: "a' );
+
+		$this->assertTrue( $processor->next_declaration() );
+		$this->assertTrue( $processor->set_important( true ) );
+		$this->assertSame( 'font-family: "a" !important', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style
 	 *
-	 * @dataProvider data_styles_ending_inside_a_comment
+	 * @dataProvider data_styles_ending_in_a_backslash
 	 *
 	 * @param string $style Style text.
 	 */
@@ -951,11 +1000,10 @@ public function test_append_declaration_rejects_eof_repairs_that_cannot_be_preci
 	 *
 	 * @return array<string, array{string}>
 	 */
-	public static function data_styles_ending_inside_a_comment(): array {
+	public static function data_styles_ending_in_a_backslash(): array {
 		return array(
-			'comment inside an open function' => array( 'color: var(--x;/*keep' ),
-			'comment after a declaration'     => array( 'color: red /* keep' ),
-			'comment ending in a slash'       => array( 'color: red /*/' ),
+			'backslash after an ident'  => array( 'color: x\\' ),
+			'backslash inside a string' => array( 'content: "a\\' ),
 		);
 	}
 

From 8f9a71ee79d87939fccbaed5650ecc813bd0ad69 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 14 Oct 2026 08:25:14 +0400
Subject: [PATCH 46/77] Compare style attributes by their declarations in
 build_visual_html_tree()

build_visual_html_tree() split a style attribute on every `;` and `:`, so
`url(https://example.com/a.png)` and `url(https://example.com/b.png)` both
became `url(https`, and a `;` or `:` inside a string or function cut the
value short. It also kept whitespace inside values, so `rgb(1, 2, 3)` and
`rgb(1,2,3)` differed.

build_style_attribute_declarations() lists the declarations that
WP_HTML_Style_Attribute_Processor reads, each written from its tokens
with whitespace and comments ignored. The tree writes that list, or the
value as it is when it has text that is not a declaration.
---
 tests/phpunit/includes/abstract-testcase.php  |  1 +
 .../build-style-attribute-declarations.php    | 74 +++++++++++++++++++
 .../includes/build-visual-html-tree.php       | 21 ++----
 .../build-style-attribute-declarations.php    | 52 +++++++++++++
 .../phpunit/tests/build-visual-html-tree.php  | 22 ++++--
 5 files changed, 151 insertions(+), 19 deletions(-)
 create mode 100644 tests/phpunit/includes/build-style-attribute-declarations.php
 create mode 100644 tests/phpunit/tests/build-style-attribute-declarations.php

diff --git a/tests/phpunit/includes/abstract-testcase.php b/tests/phpunit/includes/abstract-testcase.php
index aaf0c8aa57b5e..28fbe6f75c7f9 100644
--- a/tests/phpunit/includes/abstract-testcase.php
+++ b/tests/phpunit/includes/abstract-testcase.php
@@ -1,5 +1,6 @@
 <?php
 
+require_once __DIR__ . '/build-style-attribute-declarations.php';
 require_once __DIR__ . '/build-visual-html-tree.php';
 require_once __DIR__ . '/factory.php';
 require_once __DIR__ . '/trac.php';
diff --git a/tests/phpunit/includes/build-style-attribute-declarations.php b/tests/phpunit/includes/build-style-attribute-declarations.php
new file mode 100644
index 0000000000000..e6e1408e01203
--- /dev/null
+++ b/tests/phpunit/includes/build-style-attribute-declarations.php
@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * Lists the declarations of a style attribute value in a canonical form.
+ *
+ * Two values give the same list when they have the same declarations in the
+ * same order: the same property names, priorities and value tokens. Whitespace
+ * and comments are ignored, and blocks left open at the end are closed. Each
+ * declaration is written `name:value;` or `name:value !important;`, with a space
+ * only between value tokens that would otherwise read as one.
+ *
+ * For example, `COLOR: rgb(1, 2, 3); margin: 1px  2px` gives
+ * `array( 'color:rgb(1,2,3);', 'margin:1px 2px;' )`.
+ *
+ * @since 7.2.0
+ *
+ * @param string $style Decoded style attribute value.
+ * @return string[]|null Declarations, or null when the value has text that is
+ *                       not a declaration, a `;`, whitespace or a comment.
+ */
+function build_style_attribute_declarations( string $style ): ?array {
+	$is_ignored = static function ( WP_CSS_Token $token ): bool {
+		return (
+			WP_CSS_Token_Processor::TOKEN_WHITESPACE === $token->get_type() ||
+			WP_CSS_Token_Processor::TOKEN_COMMENT === $token->get_type()
+		);
+	};
+
+	$processor          = WP_HTML_Style_Attribute_Processor::create( $style );
+	$declarations       = array();
+	$declaration_tokens = 0;
+
+	while ( $processor->next_declaration() ) {
+		$tokens = array();
+		foreach ( $processor->get_value_tokens() as $token ) {
+			if ( ! $is_ignored( $token ) ) {
+				$tokens[] = $token;
+			}
+		}
+
+		// The name, the colon, the value tokens other than `;`, and `!` and `important`.
+		$declaration_tokens += 2 + ( $processor->is_important() ? 2 : 0 );
+		foreach ( $tokens as $token ) {
+			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON !== $token->get_type() ) {
+				++$declaration_tokens;
+			}
+		}
+
+		// The serializer separates tokens that would read as one with an empty comment.
+		$serialized = WP_CSS_Token_Serializer::serialize( $tokens );
+		$reader     = WP_CSS_Token_Processor::create( $serialized );
+		$value      = '';
+		while ( $reader->next_token() ) {
+			$token  = $reader->get_token();
+			$value .= WP_CSS_Token_Processor::TOKEN_COMMENT === $token->get_type()
+				? ' '
+				: substr( $serialized, $token->get_start(), $token->get_length() );
+		}
+
+		$name           = WP_CSS_Token_Serializer::escape_ident( $processor->get_property_name() );
+		$declarations[] = "{$name}:{$value}" . ( $processor->is_important() ? ' !important' : '' ) . ';';
+	}
+
+	// Any token not counted above, other than whitespace, a comment or a `;`, is not part of a declaration.
+	$reader = WP_CSS_Token_Processor::create( $style );
+	while ( $reader->next_token() ) {
+		$token = $reader->get_token();
+		if ( ! $is_ignored( $token ) && WP_CSS_Token_Processor::TOKEN_SEMICOLON !== $token->get_type() ) {
+			--$declaration_tokens;
+		}
+	}
+
+	return 0 === $declaration_tokens ? $declarations : null;
+}
diff --git a/tests/phpunit/includes/build-visual-html-tree.php b/tests/phpunit/includes/build-visual-html-tree.php
index d874e944ead0c..dd310c9fdb526 100644
--- a/tests/phpunit/includes/build-visual-html-tree.php
+++ b/tests/phpunit/includes/build-visual-html-tree.php
@@ -5,8 +5,9 @@
  *
  * This is inspired by the representation used by the HTML5lib tests. It's been extended here for
  * blocks to render the semantic structure of blocks and their attributes.
- * The order of attributes and class names is normalized both for HTML tags and blocks,
- * as is the whitespace in HTML tags' style attribute.
+ * The order of attributes and class names is normalized both for HTML tags and blocks.
+ * The declarations in HTML tags' style attribute are written as build_style_attribute_declarations()
+ * writes them.
  *
  * For example, consider the following block markup:
  *
@@ -166,19 +167,11 @@ static function ( $a, $b ) {
 							sort( $class_names, SORT_STRING );
 							$val = implode( ' ', $class_names );
 						} elseif ( 'style' === $attribute_name ) {
-							$normalized_style = '';
-							foreach ( explode( ';', $val ) as $style ) {
-								if ( empty( trim( $style ) ) ) {
-									continue;
-								}
-								list( $style_key, $style_val ) = explode( ':', $style );
-
-								$style_key = trim( $style_key );
-								$style_val = trim( $style_val );
-
-								$normalized_style .= "{$style_key}:{$style_val};";
+							// A value with text that is not a declaration is shown as it is.
+							$declarations = build_style_attribute_declarations( $val );
+							if ( null !== $declarations ) {
+								$val = implode( '', $declarations );
 							}
-							$val = $normalized_style;
 						}
 						$output .= str_repeat( $tree_indent, $tag_indent + 1 ) . "{$display_name}=\"{$val}\"\n";
 					}
diff --git a/tests/phpunit/tests/build-style-attribute-declarations.php b/tests/phpunit/tests/build-style-attribute-declarations.php
new file mode 100644
index 0000000000000..cc1d60e934eb4
--- /dev/null
+++ b/tests/phpunit/tests/build-style-attribute-declarations.php
@@ -0,0 +1,52 @@
+<?php
+
+/**
+ * Tests for build_style_attribute_declarations().
+ *
+ * @package WordPress
+ *
+ * @group testsuite
+ */
+class Tests_Build_Style_Attribute_Declarations extends WP_UnitTestCase {
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::build_style_attribute_declarations
+	 *
+	 * @dataProvider data_build_style_attribute_declarations
+	 *
+	 * @param string        $style    Decoded style attribute value.
+	 * @param string[]|null $expected Expected declarations.
+	 */
+	public function test_build_style_attribute_declarations( $style, $expected ) {
+		$this->assertSame( $expected, build_style_attribute_declarations( $style ) );
+	}
+
+	/**
+	 * Data provider for test_build_style_attribute_declarations().
+	 *
+	 * @return array<string, array{string, string[]|null}>
+	 */
+	public function data_build_style_attribute_declarations() {
+		return array(
+			'empty'                          => array( '', array() ),
+			'semicolons and whitespace'      => array( " ;\t; ", array() ),
+			'one declaration'                => array( 'color: red', array( 'color:red;' ) ),
+			'property name case'             => array( 'COLOR: red', array( 'color:red;' ) ),
+			'custom property name case'      => array( '--Foo: a', array( '--Foo:a;' ) ),
+			'priority'                       => array( 'color: red ! IMPORTANT', array( 'color:red !important;' ) ),
+			'whitespace and comments'        => array( "margin : 1px /* a */ \t 2px ;", array( 'margin:1px 2px;' ) ),
+			'whitespace between tokens'      => array( 'color: rgb(1, 2, 3)', array( 'color:rgb(1,2,3);' ) ),
+			'comment between tokens'         => array( 'margin: 1px/**/2px', array( 'margin:1px 2px;' ) ),
+			'escapes and quotes'             => array( "font-family: 'a\\62 c'", array( 'font-family:"abc";' ) ),
+			'url'                            => array( 'background-image: url( https://example.com/a.png )', array( 'background-image:url(https://example.com/a.png);' ) ),
+			'blocks left open'               => array( 'color: var(--x, rgb(1 2 3', array( 'color:var(--x,rgb(1 2 3));' ) ),
+			'repeated property'              => array( 'color: red; color: blue', array( 'color:red;', 'color:blue;' ) ),
+			'empty value'                    => array( 'color:;', array( 'color:;' ) ),
+			'stray closing brace'            => array( 'color: red; }', null ),
+			'at-rule'                        => array( '@media x; color: red', null ),
+			'declaration without a colon'    => array( 'color red; width: 1px', null ),
+			'priority without a declaration' => array( 'color: red; !important', null ),
+		);
+	}
+}
diff --git a/tests/phpunit/tests/build-visual-html-tree.php b/tests/phpunit/tests/build-visual-html-tree.php
index 528d95a61e256..02a4c408cd5fa 100644
--- a/tests/phpunit/tests/build-visual-html-tree.php
+++ b/tests/phpunit/tests/build-visual-html-tree.php
@@ -114,6 +114,10 @@ public function data_build_equivalent_html_semantic_tree_with_equivalent_html()
 				'<hr style="margin-top: 50px; margin-bottom: 50px;">',
 				'<hr style="margin-top:50px;margin-bottom: 50px">',
 			),
+			'Differences in style value whitespace, comments and escapes' => array(
+				'<hr style="color: rgb(1, 2, 3) /* gray */; font-family: \'a\'">',
+				'<hr style="color:rgb(1,2,3);font-family:&quot;\61&quot;">',
+			),
 			'Different block attribute order'          => array(
 				'<!-- wp:separator {"className":"is-style-default","backgroundColor":"accent-1"} -->',
 				'<!-- wp:separator {"backgroundColor":"accent-1","className":"is-style-default"} -->',
@@ -153,26 +157,34 @@ public function test_build_equivalent_html_semantic_tree_with_equivalent_html( $
 
 	public function data_build_equivalent_html_semantic_tree_with_non_equivalent_html() {
 		return array(
-			'Different attributes'             => array(
+			'Different attributes'                 => array(
 				'<img src="wp.png" alt="The WordPress logo">',
 				'<img alt="The WordPress logo" src="wp.png" title="WordPress">',
 			),
-			'Different class names'            => array(
+			'Different class names'                => array(
 				'<hr class="wp-block-separator is-style-default">',
 				'<hr class="is-style-default wp-block-hairline">',
 			),
-			'Different styles'                 => array(
+			'Different styles'                     => array(
 				'<hr style="margin-top: 50px; margin-bottom: 50px;">',
 				'<hr style="margin-top: 50px; margin-bottom: 100px">',
 			),
-			'Different comments'               => array(
+			'Different comments'                   => array(
 				'<!-- abc -->',
 				'<!-- xyz -->',
 			),
-			'Semantically relevant whitespace' => array(
+			'Semantically relevant whitespace'     => array(
 				'<div style="color: rgb(50 139 31)">Test</div>',
 				'<div style="color:rgb(5013931)">Test</div>',
 			),
+			'Different URLs in styles'             => array(
+				'<div style="background-image: url(https://example.com/a.png)">Test</div>',
+				'<div style="background-image: url(https://example.com/b.png)">Test</div>',
+			),
+			'Style text that is not a declaration' => array(
+				'<div style="color: red; }">Test</div>',
+				'<div style="color: red">Test</div>',
+			),
 		);
 	}
 

From 977555cadf60f87e6dc7cd5e3f6aae78e8c0b3bd Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 14 Oct 2026 08:55:59 +0400
Subject: [PATCH 47/77] Add assertEqualStyleAttribute()

Tests that check a style attribute value compare exact bytes, so a change
to how declarations are written, such as `name: value;` instead of
`name:value;`, changes every expectation even when the declarations are
the same.

assertEqualStyleAttribute() compares the declarations that
build_style_attribute_declarations() lists for each value: the same
property names, priorities and value tokens in the same order, with
whitespace and comments ignored. It fails when either value has text that
is not a declaration, since that text has no canonical form to compare.
---
 tests/phpunit/includes/abstract-testcase.php  | 34 +++++++-
 .../tests/assert-equal-style-attribute.php    | 87 +++++++++++++++++++
 2 files changed, 119 insertions(+), 2 deletions(-)
 create mode 100644 tests/phpunit/tests/assert-equal-style-attribute.php

diff --git a/tests/phpunit/includes/abstract-testcase.php b/tests/phpunit/includes/abstract-testcase.php
index 28fbe6f75c7f9..4bf1ba4c174b9 100644
--- a/tests/phpunit/includes/abstract-testcase.php
+++ b/tests/phpunit/includes/abstract-testcase.php
@@ -1330,8 +1330,9 @@ public function assertQueryTrue( ...$prop ) {
 	 *
 	 * Given two markup strings, assert that they translate to the same semantic HTML tree,
 	 * normalizing tag names, attribute names, and attribute order. Furthermore, attributes
-	 * and class names are sorted and deduplicated, and whitespace in style attributes
-	 * is normalized. Finally, block delimiter comments are recognized and normalized,
+	 * and class names are sorted and deduplicated, and style attributes are compared by
+	 * their declarations, as in assertEqualStyleAttribute(), when they have no other text.
+	 * Finally, block delimiter comments are recognized and normalized,
 	 * applying the same principles.
 	 *
 	 * @since 6.9.0
@@ -1363,6 +1364,35 @@ public function assertEqualHTML( string $expected, string $actual, ?string $frag
 		$this->assertSame( $tree_expected, $tree_actual, $message );
 	}
 
+	/**
+	 * Check style attribute values for the same declarations.
+	 *
+	 * Given two decoded style attribute values, assert that they have the same declarations
+	 * in the same order: the same property names, priorities and value tokens, as listed by
+	 * build_style_attribute_declarations(). Whitespace and comments are ignored. The assertion
+	 * fails when either value has text that is not a declaration, a `;`, whitespace or a comment.
+	 *
+	 * @since 7.2.0
+	 *
+	 * @param string $expected The expected style attribute value.
+	 * @param string $actual   The actual style attribute value.
+	 * @param string $message  Optional. The assertion error message.
+	 */
+	public function assertEqualStyleAttribute( string $expected, string $actual, string $message = 'Style attribute values were not equivalent.' ): void {
+		$declarations_expected = build_style_attribute_declarations( $expected );
+		$declarations_actual   = build_style_attribute_declarations( $actual );
+
+		if ( null === $declarations_expected ) {
+			$this->fail( "{$message}\nThe expected value has text that is not a declaration: {$expected}" );
+		}
+
+		if ( null === $declarations_actual ) {
+			$this->fail( "{$message}\nThe actual value has text that is not a declaration: {$actual}" );
+		}
+
+		$this->assertSame( implode( "\n", $declarations_expected ), implode( "\n", $declarations_actual ), $message );
+	}
+
 	/**
 	 * Helper function to convert a single-level array containing text strings to a named data provider.
 	 *
diff --git a/tests/phpunit/tests/assert-equal-style-attribute.php b/tests/phpunit/tests/assert-equal-style-attribute.php
new file mode 100644
index 0000000000000..88de9230e5b76
--- /dev/null
+++ b/tests/phpunit/tests/assert-equal-style-attribute.php
@@ -0,0 +1,87 @@
+<?php
+
+/**
+ * Tests for WP_UnitTestCase_Base::assertEqualStyleAttribute().
+ *
+ * @package WordPress
+ *
+ * @group testsuite
+ */
+class Tests_Assert_Equal_Style_Attribute extends WP_UnitTestCase {
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers WP_UnitTestCase_Base::assertEqualStyleAttribute
+	 *
+	 * @dataProvider data_equal_style_attributes
+	 *
+	 * @param string $expected Expected style attribute value.
+	 * @param string $actual   Actual style attribute value.
+	 */
+	public function test_equal_style_attributes( $expected, $actual ) {
+		$this->assertEqualStyleAttribute( $expected, $actual );
+	}
+
+	/**
+	 * Data provider for test_equal_style_attributes().
+	 *
+	 * @return array<string, array{string, string}>
+	 */
+	public function data_equal_style_attributes() {
+		return array(
+			'empty'                     => array( '', ' ; ' ),
+			'same bytes'                => array( 'color: red;', 'color: red;' ),
+			'whitespace and comments'   => array( 'color:red;margin:1px 2px', "color : red ; margin: 1px/* a */\t2px;" ),
+			'whitespace inside a value' => array( 'color: rgb(1,2,3)', 'color: rgb(1, 2, 3)' ),
+			'property name case'        => array( 'color: red', 'COLOR: red' ),
+			'priority case'             => array( 'color: red !important', 'color: red ! IMPORTANT' ),
+			'blocks left open'          => array( 'color: var(--x, red)', 'color: var(--x, red' ),
+			'quotes and escapes'        => array( 'font-family: "abc"', "font-family: 'a\\62 c'" ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers WP_UnitTestCase_Base::assertEqualStyleAttribute
+	 *
+	 * @dataProvider data_different_style_attributes
+	 *
+	 * @param string $expected Expected style attribute value.
+	 * @param string $actual   Actual style attribute value.
+	 */
+	public function test_different_style_attributes( $expected, $actual ) {
+		$this->expectException( PHPUnit\Framework\AssertionFailedError::class );
+		$this->assertEqualStyleAttribute( $expected, $actual );
+	}
+
+	/**
+	 * Data provider for test_different_style_attributes().
+	 *
+	 * @return array<string, array{string, string}>
+	 */
+	public function data_different_style_attributes() {
+		return array(
+			'value'                                 => array( 'color: red', 'color: blue' ),
+			'order'                                 => array( 'color: red; margin: 0', 'margin: 0; color: red' ),
+			'duplicate'                             => array( 'color: red', 'color: red; color: red' ),
+			'priority'                              => array( 'color: red', 'color: red !important' ),
+			'custom property name case'             => array( '--x: red', '--X: red' ),
+			'tokens that read as one when joined'   => array( 'margin: 1px 2px', 'margin: 1px2px' ),
+			'non-declaration text in expected'      => array( 'color: red; }', 'color: red' ),
+			'non-declaration text in actual'        => array( 'color: red', 'color: red; }' ),
+			'same non-declaration text, both sides' => array( 'color red', 'color red' ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers WP_UnitTestCase_Base::assertEqualStyleAttribute
+	 */
+	public function test_failure_message_includes_the_given_message() {
+		$this->expectException( PHPUnit\Framework\AssertionFailedError::class );
+		$this->expectExceptionMessage( 'Custom message.' );
+		$this->assertEqualStyleAttribute( 'color: red', 'color: blue', 'Custom message.' );
+	}
+}

From c29e0c9cb7df90a54e1f13a438573dcfd580ca23 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 15:54:34 +0400
Subject: [PATCH 48/77] Set CSS API @since to 7.3.0

The CSS API is not in 7.2.0. The `_doing_it_wrong()` call in consume_string() also names 7.3.0 instead of 1.0.0.
---
 .../css-api/class-wp-css-token-processor.php  | 34 +++++++--------
 .../css-api/class-wp-css-token-serializer.php | 28 ++++++-------
 .../css-api/class-wp-css-token.php            | 42 +++++++++----------
 3 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 1d9e2ad7b4246..c66da6ea8530f 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage CSS-API
- * @since 7.2.0
+ * @since 7.3.0
  */
 
 /**
@@ -74,7 +74,7 @@
  *         }
  *     }
  *
- * @since 7.2.0
+ * @since 7.3.0
  *
  * @see https://www.w3.org/TR/css-syntax-3/#tokenization
  */
@@ -318,7 +318,7 @@ class WP_CSS_Token_Processor {
 	 *
 	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $css         CSS source to tokenize.
 	 */
@@ -336,7 +336,7 @@ private function __construct( string $css ) {
 	 *
 	 * - The only supported document encoding is `UTF-8`, which is the default value.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $css      CSS source to tokenize.
 	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
@@ -357,7 +357,7 @@ public static function create( string $css, string $encoding = 'UTF-8' ) {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return bool Whether a token was found.
 	 */
@@ -655,7 +655,7 @@ public function next_token(): bool {
 	 *     }
 	 *     $tokens[2]->get_value(); // 'b'
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return WP_CSS_Token|null The current token, or null before the first
 	 *                           token and after the last.
@@ -685,7 +685,7 @@ public function get_token(): ?WP_CSS_Token {
 	/**
 	 * Gets the current token type.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null
 	 * @phpstan-return self::TOKEN_*|null
@@ -705,7 +705,7 @@ public function get_token_type(): ?string {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null
 	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
@@ -725,7 +725,7 @@ public function get_token_type_flag(): ?string {
 	 * This is different from get_token_value() which returns the semantic value
 	 * (e.g., for strings: content without quotes; for numbers: numeric value).
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null
 	 */
@@ -748,7 +748,7 @@ public function get_normalized_token(): ?string {
 	 * Returns the exact bytes from the source without any normalization.
 	 * This preserves original line endings (\r\n, \r, \f) and null bytes.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null
 	 */
@@ -774,7 +774,7 @@ public function get_unnormalized_token(): ?string {
 	 * - For strings/URLs: the decoded string value
 	 * - For other tokens: null
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#token-value
 	 * @return string|null
@@ -787,7 +787,7 @@ public function get_token_value(): ?string {
 	/**
 	 * Gets the token start at.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return int|null
 	 */
@@ -798,7 +798,7 @@ public function get_token_start(): ?int {
 	/**
 	 * Gets the token length.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return int|null
 	 */
@@ -809,7 +809,7 @@ public function get_token_length(): ?int {
 	/**
 	 * Gets the unit for dimension tokens.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null
 	 */
@@ -837,7 +837,7 @@ public function get_token_unit(): ?string {
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return bool Whether the current token ended at its closing delimiter.
 	 */
@@ -955,7 +955,7 @@ private function consume_string(): bool {
 					continue 2;
 
 				default:
-					_doing_it_wrong( __METHOD__, 'Unexpected character in string: ' . $char, '1.0.0' );
+					_doing_it_wrong( __METHOD__, 'Unexpected character in string: ' . $char, '7.3.0' );
 					break;
 			}
 		}
@@ -1447,7 +1447,7 @@ private function consume_ident_start_codepoint( $at ): int {
 	 *
 	 * The cursor and WP_CSS_Token both decode with this method.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 * @access private
 	 *
 	 * @param string $css            CSS source the offsets index.
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index a9d123156b380..a6b87d7e2ffc7 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage CSS-API
- * @since 7.2.0
+ * @since 7.3.0
  */
 
 /**
@@ -16,7 +16,7 @@
  * The output parses to the same CSS as the tokens. Which characters are
  * escaped may change.
  *
- * @since 7.2.0
+ * @since 7.3.0
  * @access private
  *
  * @see WP_CSS_Token_Processor
@@ -30,7 +30,7 @@ class WP_CSS_Token_Serializer {
 	 *
 	 * @see WP_CSS_Token_Serializer::serialize()
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var array<string, string[]>
 	 */
@@ -80,7 +80,7 @@ class WP_CSS_Token_Serializer {
 	 * Second tokens of the marked pairs shared by the at-keyword, hash,
 	 * dimension, `#` and `-` rows.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string[]
 	 */
@@ -99,7 +99,7 @@ class WP_CSS_Token_Serializer {
 	/**
 	 * Second tokens of the marked pairs in the `.` and `+` rows.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string[]
 	 */
@@ -112,7 +112,7 @@ class WP_CSS_Token_Serializer {
 	/**
 	 * Text of the token types that have no value.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var array<string, string>
 	 */
@@ -135,7 +135,7 @@ class WP_CSS_Token_Serializer {
 	/**
 	 * Closing token type of each token type that opens a block.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var array<string, string>
 	 */
@@ -239,7 +239,7 @@ class WP_CSS_Token_Serializer {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param iterable<WP_CSS_Token> $tokens Tokens read by WP_CSS_Token_Processor::get_token().
 	 * @return string CSS text.
@@ -306,7 +306,7 @@ public static function serialize( iterable $tokens ): string {
 	/**
 	 * Serializes one token other than whitespace or a comment.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param WP_CSS_Token $token Token.
 	 * @return string CSS text.
@@ -369,7 +369,7 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 * @access private
 	 *
 	 * @param string $value Decoded value.
@@ -401,7 +401,7 @@ public static function escape_ident( string $value ): string {
 	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
 	 * @see https://drafts.csswg.org/cssom/#serialize-a-string
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $value Decoded value.
 	 * @return string Quoted string text.
@@ -449,7 +449,7 @@ private static function escape_string( string $value ): string {
 	 *
 	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $value Decoded name.
 	 * @return string Escaped name.
@@ -504,7 +504,7 @@ private static function escape_name( string $value ): string {
 	 *
 	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param int $code_point Code point above U+007F.
 	 * @return bool Whether the code point may appear unescaped in an identifier.
@@ -538,7 +538,7 @@ private static function is_non_ascii_ident_code_point( int $code_point ): bool {
 	 *
 	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $value Decoded value.
 	 * @return string Url text, including `url(` and `)`.
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 42a1f105ceb25..3328fd63d9672 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage CSS-API
- * @since 7.2.0
+ * @since 7.3.0
  */
 
 /**
@@ -24,7 +24,7 @@
  *     $tokens[3]->get_type();  // 'string-token'
  *     $tokens[3]->get_value(); // 'Exo 2'
  *
- * @since 7.2.0
+ * @since 7.3.0
  *
  * @see WP_CSS_Token_Processor::get_token()
  */
@@ -32,7 +32,7 @@ final class WP_CSS_Token {
 	/**
 	 * CSS source the offsets index.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string
 	 */
@@ -41,7 +41,7 @@ final class WP_CSS_Token {
 	/**
 	 * Token type.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string
 	 * @phpstan-var WP_CSS_Token_Processor::TOKEN_*
@@ -51,7 +51,7 @@ final class WP_CSS_Token {
 	/**
 	 * Byte offset at which the token starts.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var int
 	 */
@@ -60,7 +60,7 @@ final class WP_CSS_Token {
 	/**
 	 * Byte length of the token.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var int
 	 */
@@ -69,7 +69,7 @@ final class WP_CSS_Token {
 	/**
 	 * Type flag of a hash, number or dimension token.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string|null
 	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
@@ -79,7 +79,7 @@ final class WP_CSS_Token {
 	/**
 	 * Decoded unit of a dimension token.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string|null
 	 */
@@ -88,7 +88,7 @@ final class WP_CSS_Token {
 	/**
 	 * Byte offset at which the value of a string or url token starts.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var int|null
 	 */
@@ -97,7 +97,7 @@ final class WP_CSS_Token {
 	/**
 	 * Byte length of the value of a string or url token.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var int|null
 	 */
@@ -106,7 +106,7 @@ final class WP_CSS_Token {
 	/**
 	 * Whether the token ended at its closing delimiter.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var bool
 	 */
@@ -115,7 +115,7 @@ final class WP_CSS_Token {
 	/**
 	 * Decoded value, or false before the first call to get_value().
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @var string|null|false
 	 */
@@ -126,7 +126,7 @@ final class WP_CSS_Token {
 	 *
 	 * Use WP_CSS_Token_Processor::get_token() to create tokens.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 * @access private
 	 *
 	 * @param string      $css           CSS source the offsets index.
@@ -164,7 +164,7 @@ public function __construct(
 	/**
 	 * Gets the token type.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string One of the WP_CSS_Token_Processor::TOKEN_* constants.
 	 * @phpstan-return WP_CSS_Token_Processor::TOKEN_*
@@ -179,7 +179,7 @@ public function get_type(): string {
 	 * Hash tokens have an "id" or "unrestricted" flag. Number and dimension
 	 * tokens have an "integer" or "number" flag. Other tokens have none.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @see WP_CSS_Token_Processor::get_token_type_flag()
 	 *
@@ -195,7 +195,7 @@ public function get_flag(): ?string {
 	 *
 	 * The value is decoded on the first call and kept for later calls.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @see WP_CSS_Token_Processor::get_token_value()
 	 *
@@ -212,7 +212,7 @@ public function get_value(): ?string {
 	/**
 	 * Gets the decoded unit of a dimension token.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null The unit, or null for other token types.
 	 */
@@ -223,7 +223,7 @@ public function get_unit(): ?string {
 	/**
 	 * Gets the byte offset at which the token starts in the CSS source.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return int Byte offset.
 	 */
@@ -234,7 +234,7 @@ public function get_start(): int {
 	/**
 	 * Gets the byte length of the token in the CSS source.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return int Byte length.
 	 */
@@ -245,7 +245,7 @@ public function get_length(): int {
 	/**
 	 * Reports whether the token ended at its closing delimiter.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @see WP_CSS_Token_Processor::is_token_terminated()
 	 *
@@ -258,7 +258,7 @@ public function is_terminated(): bool {
 	/**
 	 * Decodes the value from the CSS source.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null The decoded value, or null for token types without a value.
 	 */

From b34301b74e2b35f61489e984876ec59a43cecddd Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 15:55:15 +0400
Subject: [PATCH 49/77] Revise the CSS API inline documentation

- `@link` tags hold URLs and `@see` tags name code. Related constants name each other: string and bad-string, url and bad-url, CDC and CDO, the hash token and its type flags, and the serializer's follower lists and `MARKED_PAIRS`.
- Docblock examples are `php interactive` blocks that print their result. The class example that gathered bad strings had no string in its input and found none; it now has one.
- Box drawing shows the token and value spans of the offset properties.
- The UTF-8 note links the HTML chapter 3 of Unicode 18.0.0, section 3.9.6, U+FFFD Substitution of Maximal Subparts, instead of the Unicode 9.0.0 PDF.
- Four CSS Syntax anchors did not exist: `typedef-CDC-token` and `typedef-CDO-token` are lowercase, `delim-token-diagram` is `typedef-delim-token`, and token values are defined under `tokenization`.
- Comment closers are written as `*` `/`, CSS and HTML literals are in backticks, and comments use the impersonal voice.
---
 .../css-api/class-wp-css-token-processor.php  | 399 ++++++++++--------
 .../css-api/class-wp-css-token-serializer.php |  33 +-
 .../css-api/class-wp-css-token.php            |  19 +-
 .../tests/css-api/wpCssTokenProcessor.php     |   4 +-
 .../tests/css-api/wpCssTokenSerializer.php    |   2 +-
 5 files changed, 257 insertions(+), 200 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index c66da6ea8530f..9eec31b689dc5 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -13,8 +13,8 @@
  * This class follows the algorithm in https://www.w3.org/TR/css-syntax-3/ and
  * exposes a pull-based API so callers can stream over large stylesheets without
  * allocating every token up front. Each call to next_token() advances the cursor
- * and fills in metadata (type, value, raw slice, byte offsets) that you can read
- * through the getter methods.
+ * and fills in metadata (type, value, raw slice, byte offsets) that the getter
+ * methods read.
  *
  * ## Design choices
  *
@@ -31,7 +31,7 @@
  * This processor delays normalization as much as possible. That keeps the raw byte
  * positions intact for accurate rewrites while still letting consumers ask for a
  * normalized token when they need one.
- * For example, url(a<NUL>b) is a URL token whose value is a�b, where <NUL>
+ * For example, `url(a<NUL>b)` is a URL token whose value is `a�b`, where `<NUL>`
  * means one zero byte in the source. That byte stays in the raw token, so later
  * edits still use byte offsets from the original input.
  *
@@ -43,51 +43,49 @@
  * ### UTF-8 handling
  *
  * Only UTF-8 strings are supported. Invalid sequences are replaced with U+FFFD (�)
- * using the maximal subpart approach described in
- * https://www.unicode.org/versions/Unicode9.0.0/ch03.pdf, section 3.9 Best Practices
- * for Using U+FFFD.
+ * by the maximal subpart rule of the Unicode Standard, section 3.9.6, U+FFFD
+ * Substitution of Maximal Subparts.
  *
  * ## Usage
  *
  * Basic iteration:
  *
- *     $css = 'width: 10px;';
- *     $processor = WP_CSS_Token_Processor::create( $css );
- *     while ( $processor->next_token() ) {
- *         echo $processor->get_normalized_token();
- *     }
- *     // Outputs:
- *     // width: 10px;
+ * ```php interactive
+ * $processor = WP_CSS_Token_Processor::create( 'width: 10px;' );
+ * while ( $processor->next_token() ) {
+ *     echo $processor->get_normalized_token();
+ * }
+ * // Outputs: "width: 10px;"
+ * ```
  *
  * Gathering diagnostics with byte offsets:
  *
- *     $css = "color: red;\ncolor: re\nd;";
- *     $processor = WP_CSS_Token_Processor::create( $css );
- *     $bad_strings = array();
- *     while ( $processor->next_token() ) {
- *         if ( WP_CSS_Token_Processor::TOKEN_BAD_STRING === $processor->get_token_type() ) {
- *             $bad_strings[] = array(
- *                 'start'  => $processor->get_token_start(),
- *                 'length' => $processor->get_token_length(),
- *                 'value'  => $processor->get_unnormalized_token(),
- *             );
- *         }
+ * ```php interactive
+ * $css       = "color: red;\ncolor: \"re\nd\";";
+ * $processor = WP_CSS_Token_Processor::create( $css );
+ * while ( $processor->next_token() ) {
+ *     if ( WP_CSS_Token_Processor::TOKEN_BAD_STRING === $processor->get_token_type() ) {
+ *         echo "Bad string at byte {$processor->get_token_start()}, {$processor->get_token_length()} bytes long.\n";
  *     }
+ * }
+ * // Outputs: "Bad string at byte 19, 3 bytes long."
+ * ```
  *
  * @since 7.3.0
  *
- * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+ * @link https://www.w3.org/TR/css-syntax-3/#tokenization
+ * @link https://www.unicode.org/versions/Unicode18.0.0/core-spec/chapter-3/#G66453
  */
 class WP_CSS_Token_Processor {
 	/**
 	 * Token type constants matching the CSS Syntax Level 3 specification.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+	 * @link https://www.w3.org/TR/css-syntax-3/#tokenization
 	 */
 	public const TOKEN_WHITESPACE = 'whitespace-token';
 
 	/**
-	 * Comment tokens, such as `/* a *\/`.
+	 * Comment tokens, which open with `/` `*` and close with `*` `/`.
 	 *
 	 * The specification's tokenizer produces no comment tokens. This processor
 	 * does, so callers can find comments by their byte offsets. CSS Syntax
@@ -99,38 +97,74 @@ class WP_CSS_Token_Processor {
 	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
 	 */
 	public const TOKEN_COMMENT = 'comment';
-	public const TOKEN_STRING  = 'string-token';
+
+	/**
+	 * String tokens, such as `"hello"` and `'world'`.
+	 *
+	 * @see WP_CSS_Token_Processor::TOKEN_BAD_STRING
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-string-token
+	 */
+	public const TOKEN_STRING = 'string-token';
 
 	/**
 	 * BAD-STRING tokens occur when a string contains an unescaped newline.
 	 *
-	 * Valid strings: "hello", 'world', "line1\Aline2" (escaped newline)
-	 * Invalid (produces bad-string): "hello
-	 *                                 world"  (literal newline breaks the string)
+	 * These are valid strings; the last contains an escaped newline:
+	 *
+	 *     "hello" 'world' "line1\Aline2"
+	 *
+	 * This string produces a bad-string token, because a literal newline ends it:
+	 *
+	 *     "hello
+	 *     world"
 	 *
 	 * The processor stops at the newline and produces a bad-string token for error recovery.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-bad-string-token
+	 * @see WP_CSS_Token_Processor::TOKEN_STRING
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-bad-string-token
+	 */
+	public const TOKEN_BAD_STRING = 'bad-string-token';
+
+	/**
+	 * Hash tokens, such as `#fff` and `#header`.
+	 *
+	 * A hash token has an "id" or "unrestricted" type flag.
+	 *
+	 * @see WP_CSS_Token_Processor::HASH_TOKEN_ID
+	 * @see WP_CSS_Token_Processor::HASH_TOKEN_UNRESTRICTED
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-hash-token
+	 */
+	public const TOKEN_HASH = 'hash-token';
+
+	/**
+	 * Type flag of a hash token whose name would start an identifier, such as `#header`.
+	 *
+	 * @see WP_CSS_Token_Processor::TOKEN_HASH
+	 */
+	public const HASH_TOKEN_ID = 'id';
+
+	/**
+	 * Type flag of a hash token whose name would not start an identifier, such as `#123`.
+	 *
+	 * @see WP_CSS_Token_Processor::TOKEN_HASH
 	 */
-	public const TOKEN_BAD_STRING        = 'bad-string-token';
-	public const TOKEN_HASH              = 'hash-token';
-	public const HASH_TOKEN_ID           = 'id';
 	public const HASH_TOKEN_UNRESTRICTED = 'unrestricted';
-	public const TOKEN_DELIM             = 'delim-token';
-	public const TOKEN_NUMBER            = 'number-token';
-	public const TOKEN_PERCENTAGE        = 'percentage-token';
-	public const TOKEN_DIMENSION         = 'dimension-token';
-	public const TOKEN_AT_KEYWORD        = 'at-keyword-token';
-	public const TOKEN_COLON             = 'colon-token';
-	public const TOKEN_SEMICOLON         = 'semicolon-token';
-	public const TOKEN_COMMA             = 'comma-token';
-	public const TOKEN_LEFT_PAREN        = '(-token';
-	public const TOKEN_RIGHT_PAREN       = ')-token';
-	public const TOKEN_LEFT_BRACKET      = '[-token';
-	public const TOKEN_RIGHT_BRACKET     = ']-token';
-	public const TOKEN_LEFT_BRACE        = '{-token';
-	public const TOKEN_RIGHT_BRACE       = '}-token';
-	public const TOKEN_FUNCTION          = 'function-token';
+
+	public const TOKEN_DELIM         = 'delim-token';
+	public const TOKEN_NUMBER        = 'number-token';
+	public const TOKEN_PERCENTAGE    = 'percentage-token';
+	public const TOKEN_DIMENSION     = 'dimension-token';
+	public const TOKEN_AT_KEYWORD    = 'at-keyword-token';
+	public const TOKEN_COLON         = 'colon-token';
+	public const TOKEN_SEMICOLON     = 'semicolon-token';
+	public const TOKEN_COMMA         = 'comma-token';
+	public const TOKEN_LEFT_PAREN    = '(-token';
+	public const TOKEN_RIGHT_PAREN   = ')-token';
+	public const TOKEN_LEFT_BRACKET  = '[-token';
+	public const TOKEN_RIGHT_BRACKET = ']-token';
+	public const TOKEN_LEFT_BRACE    = '{-token';
+	public const TOKEN_RIGHT_BRACE   = '}-token';
+	public const TOKEN_FUNCTION      = 'function-token';
 
 	/**
 	 * URL tokens represent unquoted URLs in url() notation.
@@ -143,20 +177,23 @@ class WP_CSS_Token_Processor {
 	 * Bad URL tokens are created when invalid characters are encountered in
 	 * a URL token.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-url-token
+	 * @see WP_CSS_Token_Processor::TOKEN_BAD_URL
+	 * @see WP_CSS_Token_Processor::TOKEN_FUNCTION
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-url-token
 	 */
 	public const TOKEN_URL = 'url-token';
 
 	/**
 	 * BAD-URL tokens occur when a URL contains invalid characters.
 	 *
-	 * Invalid characters: quotes ("), apostrophes ('), parentheses (()
-	 * Example invalid: url(image(.jpg) or url(image".jpg)
+	 * Invalid characters include quotes (`"`), apostrophes (`'`) and opening
+	 * parentheses (`(`), as in `url(image(.jpg)` or `url(image".jpg)`.
 	 *
-	 * When detected, the processor consumes everything up to ) or EOF.
+	 * When detected, the processor consumes everything up to `)` or EOF.
 	 * This prevents the bad URL from breaking subsequent tokens.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-bad-url-token
+	 * @see WP_CSS_Token_Processor::TOKEN_URL
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-bad-url-token
 	 */
 	public const TOKEN_BAD_URL = 'bad-url-token';
 
@@ -167,36 +204,38 @@ class WP_CSS_Token_Processor {
 	 * There are restrictions on the codepoints that start or are contained in
 	 * an identifier, and identifiers may contain escape sequences.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-ident-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-ident-token
 	 */
 	public const TOKEN_IDENT = 'ident-token';
 
 	/**
-	 * CDC (Comment Delimiter Close) token: -->
+	 * CDC (Comment Delimiter Close) token: `-->`
 	 *
-	 * Legacy token from when CSS was embedded in HTML <style> tags
+	 * Legacy token from when CSS was embedded in HTML `<style>` tags
 	 * and needed to be hidden from old browsers using HTML comments:
 	 *
-	 *   <style>
-	 *   <!--
-	 *   body { color: red; }
-	 *   -->
-	 *   </style>
+	 *     <style>
+	 *     <!--
+	 *     body { color: red; }
+	 *     -->
+	 *     </style>
 	 *
 	 * Modern CSS no longer needs these, but they're preserved for compatibility.
 	 * In stylesheets, they're typically treated like whitespace.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-CDC-token
+	 * @see WP_CSS_Token_Processor::TOKEN_CDO
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-cdc-token
 	 */
 	public const TOKEN_CDC = 'CDC-token';
 
 	/**
-	 * CDO (Comment Delimiter Open) token: <!--
+	 * CDO (Comment Delimiter Open) token: `<!--`
 	 *
-	 * Legacy token from when CSS was embedded in HTML <style> tags.
-	 * See TOKEN_CDC for full explanation of HTML comment compatibility.
+	 * Legacy token from when CSS was embedded in HTML `<style>` tags.
+	 * TOKEN_CDC describes the HTML comment compatibility.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#typedef-CDO-token
+	 * @see WP_CSS_Token_Processor::TOKEN_CDC
+	 * @link https://www.w3.org/TR/css-syntax-3/#typedef-cdo-token
 	 */
 	public const TOKEN_CDO = 'CDO-token';
 
@@ -227,11 +266,11 @@ class WP_CSS_Token_Processor {
 	 * The type flag for the current token, if any.
 	 *
 	 * Hash tokens carry an "id" or "unrestricted" flag. Per CSS Syntax Level 3,
-	 * <number-token> and <dimension-token> have a type flag indicating whether
+	 * `<number-token>` and `<dimension-token>` have a type flag indicating whether
 	 * the number was written as an integer or a number (with decimal point or
-	 * exponent). <percentage-token> does not have a type flag.
+	 * exponent). `<percentage-token>` does not have a type flag.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
 	 * @var string|null
 	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
@@ -243,8 +282,9 @@ class WP_CSS_Token_Processor {
 	 *
 	 * Example:
 	 *
-	 * background-image: url(https://example.com/image.jpg);
-	 *                   ^ token_starts_at
+	 *     background: url( a.png );
+	 *                 ↑
+	 *     The url token starts at byte 12.
 	 *
 	 * @var int|null
 	 */
@@ -255,9 +295,9 @@ class WP_CSS_Token_Processor {
 	 *
 	 * Example:
 	 *
-	 * background-image: url(https://example.com/image.jpg);
-	 *                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-	 *                             token_length
+	 *     background: url( a.png );
+	 *                 ╰────┬─────╯
+	 *     The url token is 12 bytes long.
 	 *
 	 * @var int|null
 	 */
@@ -266,23 +306,26 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The byte offset at which the value of the current token starts.
 	 *
-	 * It is used for STRING and URL tokens. For example:
+	 * It is used for string and url tokens. The value of a string token
+	 * excludes its quotes; the value of a url token excludes `url(`, `)` and
+	 * the whitespace inside them. For example:
 	 *
-	 * background-image: url(https://example.com/image.jpg);
-	 *                       ^ token_value_starts_at
+	 *     background: url( a.png );
+	 *                      ↑
+	 *     The url value starts at byte 17.
 	 *
 	 * @var int|null
 	 */
 	private $token_value_starts_at = null;
 
 	/**
-	 * The byte offset at which the value of the current token starts.
+	 * The byte length of the value of the current token.
 	 *
-	 * It is relevant for STRING and URL tokens. For example:
+	 * It is used for string and url tokens. For example:
 	 *
-	 * background-image: url(https://example.com/image.jpg);
-	 *                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-	 *                             token_value_length
+	 *     background: url( a.png );
+	 *                      ╰─┬─╯
+	 *     The url value is 5 bytes long.
 	 *
 	 * @var int|null
 	 */
@@ -305,9 +348,13 @@ class WP_CSS_Token_Processor {
 	/**
 	 * Whether the current token ended at its closing delimiter.
 	 *
-	 * Comment, string, url and bad-url tokens end at `*\/`, the matching quote
-	 * or `)`. When the input ends first, the token is complete but this flag
-	 * is false. Every other token type is always terminated.
+	 * Comment, string, url and bad-url tokens end at `*` `/`, the matching
+	 * quote or `)`. When the input ends first, the token is complete but this
+	 * flag is false. Every other token type is always terminated.
+	 *
+	 *     color: "red
+	 *            ╰─┬╯
+	 *     The string token is not terminated: the input ends before the closing quote.
 	 *
 	 * @var bool
 	 */
@@ -355,7 +402,7 @@ public static function create( string $css, string $encoding = 'UTF-8' ) {
 	 *
 	 * Implements the main tokenization loop, consuming the next token from the input stream.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-token
 	 *
 	 * @since 7.3.0
 	 *
@@ -364,16 +411,16 @@ public static function create( string $css, string $encoding = 'UTF-8' ) {
 	public function next_token(): bool {
 		$this->after_token();
 
-		// Bale out once we reach the end.
+		// Stop at the end of the input.
 		if ( $this->at >= $this->length ) {
 			return false;
 		}
 
 		/*
-		 * CSS comments. They are not preserved as tokens in the specification, but we
-		 * still track them.
+		 * CSS comments. The specification does not produce comment tokens; this
+		 * processor does.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#consume-comment
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-comment
 		 */
 		if (
 			$this->at + 1 < $this->length &&
@@ -400,12 +447,12 @@ public function next_token(): bool {
 		/*
 		 * Whitespace tokens.
 		 *
-		 * We consider U+000A LINE FEED, U+0009 CHARACTER TABULATION, and U+0020 SPACE bytes covered by the spec.
-		 * In addition, we also capture U+000D CARRIAGE RETURN and U+000C FORM FEED that are normally converted to
-		 * U+000A LINE FEED during the preprocessing phase.
+		 * The spec defines U+000A LINE FEED, U+0009 CHARACTER TABULATION, and U+0020 SPACE as whitespace.
+		 * In addition, U+000D CARRIAGE RETURN and U+000C FORM FEED are handled here, which the preprocessing
+		 * phase would convert to U+000A LINE FEED.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#newline
-		 * @see https://www.w3.org/TR/css-syntax-3/#whitespace
+		 * @link https://www.w3.org/TR/css-syntax-3/#newline
+		 * @link https://www.w3.org/TR/css-syntax-3/#whitespace
 		 */
 		$whitespace_length = strspn( $this->css, "\t\n\f\r ", $this->at );
 		if ( $whitespace_length > 0 ) {
@@ -419,7 +466,7 @@ public function next_token(): bool {
 		/*
 		 * String tokens with either " or ' as delimiters.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
 		 */
 		if ( '"' === $this->css[ $this->at ] || "'" === $this->css[ $this->at ] ) {
 			return $this->consume_string();
@@ -434,7 +481,7 @@ public function next_token(): bool {
 		 * A hash token is created when # is followed by an ident code point or valid escape.
 		 * This is commonly used for hex colors (#fff) or ID selectors (#header).
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-token
 		 */
 		if ( '#' === $char ) {
 			if ( $this->at + 1 < $this->length ) {
@@ -473,7 +520,7 @@ public function next_token(): bool {
 		 * Note: ( tokens here are not function tokens - those are handled
 		 * in consume_ident_like() when ( follows an identifier.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#tokenization
+		 * @link https://www.w3.org/TR/css-syntax-3/#tokenization
 		 */
 		$simple = array(
 			'(' => self::TOKEN_LEFT_PAREN,
@@ -499,7 +546,7 @@ public function next_token(): bool {
 		 * An at-keyword is @ followed by an identifier, used for at-rules like
 		 * @media, @import, @keyframes, etc.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#consume-token
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-token
 		 */
 		if ( '@' === $char ) {
 			++$this->at;
@@ -522,7 +569,7 @@ public function next_token(): bool {
 		/*
 		 * Numbers start with digits, the plus sign, minus sign, and decimal point.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
+		 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
 		 */
 		if ( $this->would_next_3_code_points_start_a_number() ) {
 			return $this->consume_numeric();
@@ -536,11 +583,11 @@ public function next_token(): bool {
 			// > If the input stream starts with a number.
 
 			/*
-			 * If followed by another hyphen and >, this is a CDC token (-->)
+			 * If followed by another hyphen and `>`, this is a CDC token (`-->`).
 			 *
 			 * Comment Delimiter Close - legacy HTML comment syntax in CSS.
 			 *
-			 * @see https://www.w3.org/TR/css-syntax-3/#CDC-token-diagram
+			 * @link https://www.w3.org/TR/css-syntax-3/#CDC-token-diagram
 			 */
 			if (
 				$this->at + 2 < $this->length &&
@@ -570,11 +617,11 @@ public function next_token(): bool {
 
 		/*
 		 * U+003C LESS-THAN SIGN (<)
-		 * If followed by !--, this is a CDO token (<!--)
+		 * If followed by `!--`, this is a CDO token (`<!--`).
 		 *
 		 * Comment Delimiter Open - legacy HTML comment syntax in CSS.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#CDO-token-diagram
+		 * @link https://www.w3.org/TR/css-syntax-3/#CDO-token-diagram
 		 */
 		if ( '<' === $char && $this->at + 3 < $this->length &&
 			'!' === $this->css[ $this->at + 1 ] &&
@@ -595,7 +642,7 @@ public function next_token(): bool {
 		 *
 		 * Could be an identifier, function, or url() token.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
 		 */
 		if ( $this->check_if_3_code_points_start_an_ident_sequence( $this->at ) ) {
 			return $this->consume_ident_like();
@@ -607,19 +654,16 @@ public function next_token(): bool {
 		 * Any code point that doesn't match above rules becomes a delim token.
 		 * Handle multi-byte UTF-8 characters properly.
 		 *
-		 * @see https://www.w3.org/TR/css-syntax-3/#delim-token-diagram
+		 * @link https://www.w3.org/TR/css-syntax-3/#typedef-delim-token
 		 */
 		if ( ord( $char ) >= 0x80 ) {
 			$new_at         = $this->at;
 			$invalid_length = 0;
 			if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
-				/**
-				 * Trouble ahead!
-				 * Bytes at $at are not a valid UTF-8 sequence.
-				 *
-				 * We'll move forward by $invalid_length bytes and continue processing.
-				 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
-				 * via maximal subpart”replacement.
+				/*
+				 * The bytes at the cursor are not a valid UTF-8 sequence. Skip the
+				 * $invalid_length bytes of the maximal subpart; decoding replaces them
+				 * with U+FFFD.
 				 */
 				$matched_bytes = $invalid_length;
 			} else {
@@ -648,12 +692,15 @@ public function next_token(): bool {
 	 *
 	 * Example:
 	 *
-	 *     $processor = WP_CSS_Token_Processor::create( 'a "b"' );
-	 *     $tokens    = array();
-	 *     while ( $processor->next_token() ) {
-	 *         $tokens[] = $processor->get_token();
-	 *     }
-	 *     $tokens[2]->get_value(); // 'b'
+	 * ```php interactive
+	 * $processor = WP_CSS_Token_Processor::create( 'a "b"' );
+	 * $tokens    = array();
+	 * while ( $processor->next_token() ) {
+	 *     $tokens[] = $processor->get_token();
+	 * }
+	 * echo $tokens[2]->get_value();
+	 * // Outputs: "b"
+	 * ```
 	 *
 	 * @since 7.3.0
 	 *
@@ -703,7 +750,7 @@ public function get_token_type(): ?string {
 	 *   written without a decimal point or exponent, and a "number" flag otherwise.
 	 * - Percentage tokens do not have a type flag.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
 	 * @since 7.3.0
 	 *
@@ -718,9 +765,9 @@ public function get_token_type_flag(): ?string {
 	 * Gets the normalized token text from the CSS source.
 	 *
 	 * Returns the token with CSS normalization and escape decoding applied:
-	 * - CSS escapes decoded (e.g., \6c → l, \2f → /, \A → newline)
-	 * - \r\n, \r, \f → \n
-	 * - \x00 → U+FFFD (�)
+	 * - CSS escapes decoded (e.g., `\6c` → `l`, `\2f` → `/`, `\A` → newline)
+	 * - `\r\n`, `\r`, `\f` → `\n`
+	 * - `\x00` → U+FFFD (�)
 	 *
 	 * This is different from get_token_value() which returns the semantic value
 	 * (e.g., for strings: content without quotes; for numbers: numeric value).
@@ -746,7 +793,7 @@ public function get_normalized_token(): ?string {
 	 * Gets the raw, unnormalized token text from the CSS source.
 	 *
 	 * Returns the exact bytes from the source without any normalization.
-	 * This preserves original line endings (\r\n, \r, \f) and null bytes.
+	 * This preserves original line endings (`\r\n`, `\r`, `\f`) and null bytes.
 	 *
 	 * @since 7.3.0
 	 *
@@ -761,7 +808,7 @@ public function get_unnormalized_token(): ?string {
 
 	/**
 	 * Gets the current token value as a normalized and decoded string. This is
-	 * a slight divergence from the CSS Syntax Level 3 spec, where all the numberic
+	 * a slight divergence from the CSS Syntax Level 3 spec, where all the numeric
 	 * values are parsed as numbers. This processor is only concerned with their
 	 * textual representation.
 	 *
@@ -776,7 +823,7 @@ public function get_unnormalized_token(): ?string {
 	 *
 	 * @since 7.3.0
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#token-value
+	 * @link https://www.w3.org/TR/css-syntax-3/#tokenization
 	 * @return string|null
 	 */
 	public function get_token_value(): ?string {
@@ -785,7 +832,7 @@ public function get_token_value(): ?string {
 	}
 
 	/**
-	 * Gets the token start at.
+	 * Gets the byte offset at which the current token starts.
 	 *
 	 * @since 7.3.0
 	 *
@@ -796,7 +843,7 @@ public function get_token_start(): ?int {
 	}
 
 	/**
-	 * Gets the token length.
+	 * Gets the byte length of the current token.
 	 *
 	 * @since 7.3.0
 	 *
@@ -820,7 +867,7 @@ public function get_token_unit(): ?string {
 	/**
 	 * Reports whether the current token ended at its closing delimiter.
 	 *
-	 * Comment, string, url and bad-url tokens have a closing delimiter: `*\/`,
+	 * Comment, string, url and bad-url tokens have a closing delimiter: `*` `/`,
 	 * the matching quote, or `)`. When the input ends before the delimiter,
 	 * the tokenizer still returns the token, and this method returns false.
 	 * It returns true for every other token type, which have no closing
@@ -828,14 +875,19 @@ public function get_token_unit(): ?string {
 	 *
 	 * Example:
 	 *
-	 *     $processor = WP_CSS_Token_Processor::create( '"abc' );
-	 *     $processor->next_token();
-	 *     $processor->get_token_type();      // 'string-token'
-	 *     $processor->is_token_terminated(); // false
+	 * ```php interactive
+	 * $processor = WP_CSS_Token_Processor::create( '"abc' );
+	 * $processor->next_token();
+	 * echo $processor->get_token_type() . "\n";
+	 * var_dump( $processor->is_token_terminated() );
+	 * // Outputs:
+	 * // string-token
+	 * // bool(false)
+	 * ```
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-comment
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-comment
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @since 7.3.0
 	 *
@@ -866,7 +918,7 @@ private function after_token(): void {
 	 * Strings are quoted with either " or ' and can contain escape sequences.
 	 * Newlines inside strings (without escaping) make the string invalid.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
 	 *
 	 * @return bool
 	 */
@@ -883,7 +935,7 @@ private function consume_string(): bool {
 		$special_chars = "'" === $ending_char ? "'\n\f\r\\" : "\"\n\f\r\\";
 
 		while ( $this->at < $this->length ) {
-			// Consume normal characters until we hit a special character.
+			// Consume normal characters up to the next special character.
 			$normal_len = strcspn( $this->css, $special_chars, $this->at );
 			if ( $normal_len > 0 ) {
 				$this->at += $normal_len;
@@ -917,7 +969,7 @@ private function consume_string(): bool {
 					 * Unescaped newlines are not allowed in strings. To include a newline,
 					 * it must be escaped as \A or the string must end and a new one begin.
 					 *
-					 * @see https://www.w3.org/TR/css-syntax-3/#consume-string-token
+					 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
 					 */
 					$this->token_type            = self::TOKEN_BAD_STRING;
 					$this->token_length          = $this->at - $this->token_starts_at;
@@ -976,8 +1028,8 @@ private function consume_string(): bool {
 	 * Numbers can be integers or decimals, with optional sign and exponent.
 	 * They can be followed by % (percentage) or an identifier (dimension).
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-number
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
 	 * @return bool
 	 */
@@ -1052,10 +1104,11 @@ private function consume_numeric(): bool {
 			}
 		}
 
-		/**
+		/*
 		 * This is the end of spec section 4.3.12. Consume a number.
-		 * We still have some work to do as specified in section 4.3.3. Consume a numeric token:
-		 * https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
+		 * The rest follows section 4.3.3. Consume a numeric token.
+		 *
+		 * @link https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
 		 */
 
 		// If the next 3 input code points would start an ident sequence, then.
@@ -1095,7 +1148,7 @@ private function consume_numeric(): bool {
 	 * After consuming an identifier, checks if it's followed by '(' to determine
 	 * if it's a function or url() token, otherwise it's a plain identifier.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
 	 *
 	 * @return bool
 	 */
@@ -1155,7 +1208,7 @@ private function consume_ident_like(): bool {
 	 * parentheses, or certain control characters. Invalid characters create a
 	 * bad-url token.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @return bool
 	 */
@@ -1202,7 +1255,7 @@ private function consume_url(): bool {
 				$this->at     += $ws_len;
 				// Accept either ) or EOF after whitespace.
 				if ( $this->at >= $this->length ) {
-					// EOF is a parse error, but we return the <url-token> anyway.
+					// EOF is a parse error, but the <url-token> is still returned.
 					$this->token_type            = self::TOKEN_URL;
 					$this->token_is_terminated   = false;
 					$this->token_length          = $this->at - $this->token_starts_at;
@@ -1267,13 +1320,10 @@ private function consume_url(): bool {
 			$at             = $this->at;
 			$invalid_length = 0;
 			if ( 1 !== _wp_scan_utf8( $this->css, $at, $invalid_length, null, 1 ) ) {
-				/**
-				 * Trouble ahead!
-				 * Bytes at $at are not a valid UTF-8 sequence.
-				 *
-				 * We'll move forward by $invalid_length bytes and continue processing.
-				 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
-				 * via maximal subpart”replacement.
+				/*
+				 * The bytes at the cursor are not a valid UTF-8 sequence. Skip the
+				 * $invalid_length bytes of the maximal subpart; decoding replaces them
+				 * with U+FFFD.
 				 */
 				$this->at += $invalid_length;
 			} else {
@@ -1294,10 +1344,10 @@ private function consume_url(): bool {
 	/**
 	 * Finishes a bad url token by consuming remnants.
 	 *
-	 * When an invalid character is encountered in a URL, we must consume
-	 * the remainder of the URL up to the closing ) or EOF.
+	 * When an invalid character is encountered in a URL, the remainder of
+	 * the URL up to the closing `)` or EOF is consumed.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-remnants-of-bad-url
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-remnants-of-bad-url
 	 *
 	 * @return bool
 	 */
@@ -1339,7 +1389,7 @@ private function consume_remnants_of_bad_url(): bool {
 	 *
 	 * Advances the cursor past the sequence; the caller decodes the bytes.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-name
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-name
 	 */
 	private function consume_ident_sequence(): void {
 		while ( $this->at < $this->length ) {
@@ -1379,7 +1429,7 @@ private function consume_ident_sequence(): void {
 	 * Ident code point
 	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 * @link https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
 	 * @return int The number of bytes consumed.
 	 */
 	private function consume_ident_codepoint( $at ): int {
@@ -1400,7 +1450,7 @@ private function consume_ident_codepoint( $at ): int {
 	 * Ident code point
 	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 * @link https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
 	 * @return int The number of bytes consumed.
 	 */
 	private function consume_ident_start_codepoint( $at ): int {
@@ -1423,13 +1473,10 @@ private function consume_ident_start_codepoint( $at ): int {
 		$new_at         = $at;
 		$invalid_length = 0;
 		if ( 1 !== _wp_scan_utf8( $this->css, $new_at, $invalid_length, null, 1 ) ) {
-			/**
-			 * Trouble ahead!
-			 * Bytes at $at are not a valid UTF-8 sequence.
-			 *
-			 * We'll move forward by $invalid_length bytes and continue processing.
-			 * Later on, during the string decoding, we'll replace the invalid bytes with U+FFFD
-			 * via maximal subpart”replacement.
+			/*
+			 * The bytes at $at are not a valid UTF-8 sequence. Their maximal subpart
+			 * of $invalid_length bytes counts as one code point; decoding replaces it
+			 * with U+FFFD.
 			 */
 			return $invalid_length;
 		}
@@ -1558,7 +1605,7 @@ public static function decode_range( string $css, int $start, int $length, bool
 	 * trailing whitespace) or any other character. Invalid code points are
 	 * replaced with U+FFFD.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
 	 *
 	 * @param string $css             CSS source.
 	 * @param int    $offset          Byte offset (should point to the character after the backslash).
@@ -1639,7 +1686,7 @@ private static function decode_escape_at( string $css, int $offset, &$bytes_cons
 	 *
 	 * A valid escape is a backslash not followed by a newline or EOF.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
+	 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
 	 *
 	 * @param string $css    CSS source.
 	 * @param int    $offset Byte offset.
@@ -1654,8 +1701,7 @@ private static function is_valid_escape( string $css, int $offset ): bool {
 		}
 		// Otherwise, if the second code point is a newline, return false.
 		if ( $offset + 1 >= $css_length ) {
-			// Second code point is EOF - this is a valid escape per spec (weird!)
-			// Are we sure we're interpreting the spec correctly?
+			// The spec rejects only a newline as the second code point, so a `\` at EOF is a valid escape.
 			return true;
 		}
 
@@ -1669,15 +1715,14 @@ private static function is_valid_escape( string $css, int $offset ): bool {
 			// Carriage return is normalized to newline during preprocessing.
 			"\r" !== $css[ $offset + 1 ]
 
-			// We don't need to check for \r\n separately here. The \r check alone covers
-			// that scenario.
+			// The \r check also covers \r\n.
 		);
 	}
 
 	/**
 	 * Checks if the next 3 code points would start a number.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
+	 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
 	 *
 	 * @return bool
 	 */
@@ -1732,7 +1777,7 @@ private function would_next_3_code_points_start_a_number(): bool {
 	 * NOTE: "Three code points" means three Unicode code points, not three bytes.
 	 * Multi-byte UTF-8 sequences count as single code points.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 * @link https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
 	 * @param int $offset Byte offset of the first code point to check.
 	 * @return bool
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index a6b87d7e2ffc7..17071bfcf1dc9 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -80,6 +80,8 @@ class WP_CSS_Token_Serializer {
 	 * Second tokens of the marked pairs shared by the at-keyword, hash,
 	 * dimension, `#` and `-` rows.
 	 *
+	 * @see WP_CSS_Token_Serializer::MARKED_PAIRS
+	 *
 	 * @since 7.3.0
 	 *
 	 * @var string[]
@@ -99,6 +101,8 @@ class WP_CSS_Token_Serializer {
 	/**
 	 * Second tokens of the marked pairs in the `.` and `+` rows.
 	 *
+	 * @see WP_CSS_Token_Serializer::MARKED_PAIRS
+	 *
 	 * @since 7.3.0
 	 *
 	 * @var string[]
@@ -230,12 +234,15 @@ class WP_CSS_Token_Serializer {
 	 *
 	 * Example:
 	 *
-	 *     $processor = WP_CSS_Token_Processor::create( 'url( a&b ) calc(1px  +  2px' );
-	 *     $tokens    = array();
-	 *     while ( $processor->next_token() ) {
-	 *         $tokens[] = $processor->get_token();
-	 *     }
-	 *     WP_CSS_Token_Serializer::serialize( $tokens ); // 'url(a\26 b) calc(1px + 2px)'
+	 * ```php interactive
+	 * $processor = WP_CSS_Token_Processor::create( 'url( a&b ) calc(1px  +  2px' );
+	 * $tokens    = array();
+	 * while ( $processor->next_token() ) {
+	 *     $tokens[] = $processor->get_token();
+	 * }
+	 * echo WP_CSS_Token_Serializer::serialize( $tokens );
+	 * // Outputs: "url(a\26 b) calc(1px + 2px)"
+	 * ```
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
 	 *
@@ -366,8 +373,8 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	 * An empty value returns an empty string. Callers that require an ident
 	 * token must reject an empty value.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 * @see https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
+	 * @link https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @link https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
 	 * @since 7.3.0
 	 * @access private
@@ -398,8 +405,8 @@ public static function escape_ident( string $value ): string {
 	 * for rudimentary CSS processors. The string reads back as the same value,
 	 * except that NULL becomes U+FFFD.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#escaping
-	 * @see https://drafts.csswg.org/cssom/#serialize-a-string
+	 * @link https://www.w3.org/TR/css-syntax-3/#escaping
+	 * @link https://drafts.csswg.org/cssom/#serialize-a-string
 	 *
 	 * @since 7.3.0
 	 *
@@ -447,7 +454,7 @@ private static function escape_string( string $value ): string {
 	 * point, as browsers do. CSS Syntax allows fewer, so the others are escaped
 	 * and the output reads the same under both rules.
 	 *
-	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
+	 * @link https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
 	 * @since 7.3.0
 	 *
@@ -502,7 +509,7 @@ private static function escape_name( string $value ): string {
 	/**
 	 * Reports whether a code point above U+007F is a non-ASCII ident code point.
 	 *
-	 * @see https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
+	 * @link https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
 	 * @since 7.3.0
 	 *
@@ -536,7 +543,7 @@ private static function is_non_ascii_ident_code_point( int $code_point ): bool {
 	 * parentheses, `\`, whitespace and non-printable code points. So are the
 	 * code points escape_string() escapes for HTML and CSS: `< > & , ; { }`.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-url-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @since 7.3.0
 	 *
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 3328fd63d9672..194d862090838 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -16,13 +16,18 @@
  *
  * Example:
  *
- *     $processor = WP_CSS_Token_Processor::create( 'font-family: "Exo\20 2"' );
- *     $tokens    = array();
- *     while ( $processor->next_token() ) {
- *         $tokens[] = $processor->get_token();
- *     }
- *     $tokens[3]->get_type();  // 'string-token'
- *     $tokens[3]->get_value(); // 'Exo 2'
+ * ```php interactive
+ * $processor = WP_CSS_Token_Processor::create( 'font-family: "Exo\20 2"' );
+ * $tokens    = array();
+ * while ( $processor->next_token() ) {
+ *     $tokens[] = $processor->get_token();
+ * }
+ * echo $tokens[3]->get_type() . "\n";
+ * echo $tokens[3]->get_value();
+ * // Outputs:
+ * // string-token
+ * // Exo 2
+ * ```
  *
  * @since 7.3.0
  *
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 09e0444427a72..13facea9908e7 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -20,7 +20,7 @@ public function test_processor_matches_spec( string $css, array $expected_tokens
 	/**
 	 * Provides the test cases derived from the @rmenke/css-tokenizer-tests corpus (MIT).
 	 *
-	 * @see https://github.com/romainmenke/css-tokenizer-tests/
+	 * @link https://github.com/romainmenke/css-tokenizer-tests/
 	 * @return array
 	 */
 	public static function corpus_provider(): array {
@@ -2707,7 +2707,7 @@ public function test_decode_range_respects_length_boundary(): void {
 	/**
 	 * Tests that decode_escape_at() consumes at most six hex digits.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
 	 */
 	public function test_decode_escape_at_hex_limit_is_six_digits(): void {
 		$processor = WP_CSS_Token_Processor::create( '"\\0000411rest"' );
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 52c3839d5fec0..6db563924fcc1 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -178,7 +178,7 @@ public function test_marked_pair_is_separated_by_an_empty_comment( string $css,
 	 *
 	 * One case for each ✗ cell in the table in CSS Syntax Level 3 §9.
 	 *
-	 * @see https://www.w3.org/TR/css-syntax-3/#serialization
+	 * @link https://www.w3.org/TR/css-syntax-3/#serialization
 	 *
 	 * @return Generator
 	 */

From 3eef4554cf1575d446c47521b918b41a45a0a7ad Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 15:56:58 +0400
Subject: [PATCH 50/77] Set style attribute processor @since to 7.3.0

The style attribute processor is not in 7.2.0.
---
 ...lass-wp-html-style-attribute-processor.php | 28 +++++++++----------
 .../wpHtmlStyleAttributeProcessor.php         |  2 +-
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index b3108d5ae8238..7c3664a0093b4 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage HTML-API
- * @since 7.2.0
+ * @since 7.3.0
  */
 
 /**
@@ -26,7 +26,7 @@
  * declaration list model of CSS. Multiple declarations with the same property
  * name remain separate entries and can be inspected or changed individually.
  *
- * @since 7.2.0
+ * @since 7.3.0
  */
 class WP_HTML_Style_Attribute_Processor {
 	/**
@@ -98,7 +98,7 @@ class WP_HTML_Style_Attribute_Processor {
 	 * Do not instantiate directly. Use
 	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $style Decoded CSS text value from a style attribute.
 	 */
@@ -109,7 +109,7 @@ private function __construct( string $style ) {
 	/**
 	 * Creates a processor for decoded CSS text from a style attribute.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $decoded_css_text Decoded CSS text value from a style attribute.
 	 * @return static Created processor.
@@ -128,7 +128,7 @@ public static function create( $decoded_css_text ) {
 	 * When a property name is provided, normal CSS properties are matched
 	 * ASCII-case-insensitively while custom properties are matched exactly.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string|null $property_name Optional declaration property name to match.
 	 * @return bool Whether a matching declaration was found.
@@ -155,7 +155,7 @@ public function next_declaration( ?string $property_name = null ): bool {
 	/**
 	 * Gets the current declaration's property name.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string|null Property name, or null when not on a declaration.
 	 */
@@ -167,7 +167,7 @@ public function get_property_name(): ?string {
 	/**
 	 * Indicates whether the current declaration has an !important priority.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return bool|null Whether the current declaration has an !important priority,
 	 *                   or null when not on a declaration.
@@ -189,7 +189,7 @@ public function is_important(): ?bool {
 	 * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} returns.
 	 * Before any mutation that is the text passed to `create()`.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return WP_CSS_Token[]|null Value tokens, or null when not on a declaration.
 	 */
@@ -212,7 +212,7 @@ public function get_value_tokens(): ?array {
 	 * result is `name: value;` or `name: value !important;`, as in CSSOM, and
 	 * CSS reads it as the same declaration.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @see WP_CSS_Token_Serializer::serialize()
 	 *
@@ -238,7 +238,7 @@ public function serialize_declaration(): ?string {
 	 * name is escaped as an identifier and the value is written from its
 	 * tokens.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string    $value     CSS declaration value, without the property name.
 	 * @param bool|null $important Optional. Whether the declaration should be important.
@@ -294,7 +294,7 @@ public function set_value( string $value, ?bool $important = null ): bool {
 	/**
 	 * Sets the !important priority of the current declaration.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param bool $important Whether the declaration should be important.
 	 * @return bool Whether the current declaration priority is set as requested.
@@ -396,7 +396,7 @@ public function set_important( bool $important ): bool {
 	 * declarations, join the {@see WP_HTML_Style_Attribute_Processor::serialize_declaration()}
 	 * output of the ones to keep instead.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return bool Whether the current declaration was removed.
 	 */
@@ -434,7 +434,7 @@ public function remove_declaration(): bool {
 	 * writes it: the name is escaped as an identifier and the value is
 	 * written from its tokens.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $property_name CSS property name.
 	 * @param string $value         CSS declaration value, without the property name.
@@ -496,7 +496,7 @@ public function append_declaration( string $property_name, string $value, bool $
 	/**
 	 * Returns the updated decoded CSS text value for the style attribute.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @return string Updated decoded CSS text value for the style attribute.
 	 */
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index ec67adccd5422..b544e254ac1d5 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -5,7 +5,7 @@
  * @package WordPress
  * @subpackage HTML-API
  *
- * @since 7.2.0
+ * @since 7.3.0
  *
  * @group html-api
  *

From 2798c23f7ff122d8eaa5ffaab120dad225ba19ce Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 15:56:58 +0400
Subject: [PATCH 51/77] Draw the declaration offsets and value tokens

Box drawing shows which bytes each offset of a parsed declaration spans, and which tokens get_value_tokens() returns.
---
 .../class-wp-html-style-attribute-processor.php | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 7c3664a0093b4..458f12234cacb 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -53,6 +53,19 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Parsed declarations.
 	 *
+	 * Each declaration records byte offsets into the style text. The offsets
+	 * of the second declaration in this style are:
+	 *
+	 *     color: red;  width: 1px !important;  top: 0
+	 *                ╰────────────────────────╯   leading_start to trailing_end
+	 *                  ╰────────────────────╯     start to after
+	 *                         ╰─╯                 value_start to value_end
+	 *                             ╰────────╯      important_start to important_end
+	 *
+	 * `value_tokens` is the range of token indexes, end exclusive, of the
+	 * value. The `important_*` offsets are null when the declaration has no
+	 * `!important` priority.
+	 *
 	 * @var array<int, array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
@@ -185,6 +198,10 @@ public function is_important(): ?bool {
 	 * whitespace and comments between value tokens are included. The list is
 	 * empty when the declaration has no value tokens, as in `color:;`.
 	 *
+	 *     color:  red  blue !important;
+	 *             ╰───┬───╯
+	 *     The value tokens are `red`, a whitespace token and `blue`.
+	 *
 	 * Token offsets index the current style text, which
 	 * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} returns.
 	 * Before any mutation that is the text passed to `create()`.

From df5334f4aa9c07182d44ffd29b53d40261b1fc44 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 15:57:20 +0400
Subject: [PATCH 52/77] Set assertEqualStyleAttribute() @since to 7.3.0

The assertion and its helper are not in 7.2.0.
---
 tests/phpunit/includes/abstract-testcase.php                  | 2 +-
 tests/phpunit/includes/build-style-attribute-declarations.php | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/phpunit/includes/abstract-testcase.php b/tests/phpunit/includes/abstract-testcase.php
index 4bf1ba4c174b9..793fac4a09922 100644
--- a/tests/phpunit/includes/abstract-testcase.php
+++ b/tests/phpunit/includes/abstract-testcase.php
@@ -1372,7 +1372,7 @@ public function assertEqualHTML( string $expected, string $actual, ?string $frag
 	 * build_style_attribute_declarations(). Whitespace and comments are ignored. The assertion
 	 * fails when either value has text that is not a declaration, a `;`, whitespace or a comment.
 	 *
-	 * @since 7.2.0
+	 * @since 7.3.0
 	 *
 	 * @param string $expected The expected style attribute value.
 	 * @param string $actual   The actual style attribute value.
diff --git a/tests/phpunit/includes/build-style-attribute-declarations.php b/tests/phpunit/includes/build-style-attribute-declarations.php
index e6e1408e01203..53db21b0717e6 100644
--- a/tests/phpunit/includes/build-style-attribute-declarations.php
+++ b/tests/phpunit/includes/build-style-attribute-declarations.php
@@ -12,7 +12,7 @@
  * For example, `COLOR: rgb(1, 2, 3); margin: 1px  2px` gives
  * `array( 'color:rgb(1,2,3);', 'margin:1px 2px;' )`.
  *
- * @since 7.2.0
+ * @since 7.3.0
  *
  * @param string $style Decoded style attribute value.
  * @return string[]|null Declarations, or null when the value has text that is

From dcf3b566096c2e0a25960419a2c6f39ce51c4149 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 16:52:02 +0400
Subject: [PATCH 53/77] Give comment tokens their text as a value

The tokenizer stored value offsets for comment tokens that nothing read and that were wrong: the value started at the `/` of the opener, and its length was the token length minus 4 even when the input ended before the closer, so `/* a` had an empty value. The value now starts after `/*` and ends before `*/` or at the end of the input.

WP_CSS_Token::get_value() and get_token_value() return that text for a comment token instead of null. Comments contain no escapes, so `/*\41*/` has the value `\41`; only input preprocessing applies, as for other values: CR, CRLF and FF become LF, and NUL and invalid UTF-8 become U+FFFD.

The six comment tokens in the corpus and the normalization test now expect the text, and the corpus README describes the rule.
---
 .../css-api/class-wp-css-token-processor.php  | 19 +++++++-----
 .../css-api/class-wp-css-token.php            | 20 ++++++++++---
 tests/phpunit/data/css-api/README.md          |  5 ++--
 .../phpunit/data/css-api/css-test-cases.json  | 12 ++++----
 tests/phpunit/tests/css-api/wpCssToken.php    | 30 +++++++++++++++++++
 .../tests/css-api/wpCssTokenProcessor.php     |  2 +-
 6 files changed, 68 insertions(+), 20 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 9eec31b689dc5..492e13460f1b3 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -306,9 +306,10 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The byte offset at which the value of the current token starts.
 	 *
-	 * It is used for string and url tokens. The value of a string token
-	 * excludes its quotes; the value of a url token excludes `url(`, `)` and
-	 * the whitespace inside them. For example:
+	 * It is used for string, url and comment tokens. The value of a string
+	 * token excludes its quotes; the value of a url token excludes `url(`, `)`
+	 * and the whitespace inside them; the value of a comment excludes its
+	 * delimiters. For example:
 	 *
 	 *     background: url( a.png );
 	 *                      ↑
@@ -321,7 +322,7 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The byte length of the value of the current token.
 	 *
-	 * It is used for string and url tokens. For example:
+	 * It is used for string, url and comment tokens. For example:
 	 *
 	 *     background: url( a.png );
 	 *                      ╰─┬─╯
@@ -429,18 +430,20 @@ public function next_token(): bool {
 		) {
 			$this->token_type            = self::TOKEN_COMMENT;
 			$this->token_starts_at       = $this->at;
-			$this->token_value_starts_at = $this->at;
+			$this->token_value_starts_at = $this->at + 2;
 
 			$end = strpos( $this->css, '*/', $this->at + 2 );
 			if ( false === $end ) {
 				// The comment runs to the end of the input.
 				$this->token_is_terminated = false;
 				$this->at                  = $this->length;
+				$value_ends_at             = $this->length;
 			} else {
-				$this->at = $end + 2;
+				$this->at      = $end + 2;
+				$value_ends_at = $end;
 			}
 			$this->token_length       = $this->at - $this->token_starts_at;
-			$this->token_value_length = $this->token_length - 4;
+			$this->token_value_length = $value_ends_at - $this->token_value_starts_at;
 			return true;
 		}
 
@@ -819,6 +822,8 @@ public function get_unnormalized_token(): ?string {
 	 * - For dimensions: the string representation of the number (use get_token_unit() for the unit)
 	 * - For identifiers/functions/hash/at-keywords: the decoded identifier string
 	 * - For strings/URLs: the decoded string value
+	 * - For comments: the text between the delimiters, with newlines normalized;
+	 *   comments contain no escapes
 	 * - For other tokens: null
 	 *
 	 * @since 7.3.0
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 194d862090838..7169a69865a1b 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -91,7 +91,7 @@ final class WP_CSS_Token {
 	private $unit;
 
 	/**
-	 * Byte offset at which the value of a string or url token starts.
+	 * Byte offset at which the value of a string, url or comment token starts.
 	 *
 	 * @since 7.3.0
 	 *
@@ -100,7 +100,7 @@ final class WP_CSS_Token {
 	private $value_start;
 
 	/**
-	 * Byte length of the value of a string or url token.
+	 * Byte length of the value of a string, url or comment token.
 	 *
 	 * @since 7.3.0
 	 *
@@ -140,8 +140,8 @@ final class WP_CSS_Token {
 	 * @param int         $length        Byte length of the token.
 	 * @param string|null $flag          Type flag of a hash, number or dimension token.
 	 * @param string|null $unit          Decoded unit of a dimension token.
-	 * @param int|null    $value_start   Byte offset at which the value of a string or url token starts.
-	 * @param int|null    $value_length  Byte length of the value of a string or url token.
+	 * @param int|null    $value_start   Byte offset at which the value of a string, url or comment token starts.
+	 * @param int|null    $value_length  Byte length of the value of a string, url or comment token.
 	 * @param bool        $is_terminated Whether the token ended at its closing delimiter.
 	 */
 	public function __construct(
@@ -288,6 +288,18 @@ private function decode_value(): ?string {
 			case WP_CSS_Token_Processor::TOKEN_URL:
 				return WP_CSS_Token_Processor::decode_range( $this->css, $this->value_start, $this->value_length );
 
+			case WP_CSS_Token_Processor::TOKEN_COMMENT:
+				// Comments contain no escapes, so only input preprocessing applies.
+				return strtr(
+					wp_scrub_utf8( substr( $this->css, $this->value_start, $this->value_length ) ),
+					array(
+						"\r\n" => "\n",
+						"\r"   => "\n",
+						"\f"   => "\n",
+						"\0"   => "\u{FFFD}",
+					)
+				);
+
 			case WP_CSS_Token_Processor::TOKEN_NUMBER:
 				// Numbers are ASCII and have no escapes.
 				return substr( $this->css, $this->start, $this->length );
diff --git a/tests/phpunit/data/css-api/README.md b/tests/phpunit/data/css-api/README.md
index 5b17c602b72c4..25c0902648cb0 100644
--- a/tests/phpunit/data/css-api/README.md
+++ b/tests/phpunit/data/css-api/README.md
@@ -20,8 +20,9 @@ The upstream corpus maps a case name to `{ css, tokens }`. Each upstream token h
   JavaScript string indexes (UTF-16 code units).
 - `value` is `structured.value` flattened onto the token. Numeric values are the
   number's source text as a string (`"10e2"`, not `1000`); for dimension and
-  percentage tokens the unit or `%` is removed. Tokens without structured data have
-  `value: null`.
+  percentage tokens the unit or `%` is removed. A comment token, which has no
+  structured data upstream, has the text between its delimiters after input
+  preprocessing. Other tokens without structured data have `value: null`.
 - `unit` is `structured.unit`, present on dimension tokens only.
 - `numberType` is `structured.type` on number and dimension tokens. The upstream
   `structured.type` of hash tokens (`id` or `unrestricted`) and `signCharacter` are
diff --git a/tests/phpunit/data/css-api/css-test-cases.json b/tests/phpunit/data/css-api/css-test-cases.json
index bb9c919b4ec64..aa93e54c97adc 100644
--- a/tests/phpunit/data/css-api/css-test-cases.json
+++ b/tests/phpunit/data/css-api/css-test-cases.json
@@ -545,7 +545,7 @@
 				"startIndex": 0,
 				"endIndex": 15,
 				"normalized": "/* a comment */",
-				"value": null
+				"value": " a comment "
 			},
 			{
 				"type": "whitespace-token",
@@ -566,7 +566,7 @@
 				"startIndex": 0,
 				"endIndex": 13,
 				"normalized": "/* a comment ",
-				"value": null
+				"value": " a comment "
 			}
 		]
 	},
@@ -587,7 +587,7 @@
 				"startIndex": 1,
 				"endIndex": 5,
 				"normalized": "/**/",
-				"value": null
+				"value": ""
 			},
 			{
 				"type": "ident-token",
@@ -616,7 +616,7 @@
 				"startIndex": 0,
 				"endIndex": 5,
 				"normalized": "/**/",
-				"value": null
+				"value": "\\"
 			},
 			{
 				"type": "delim-token",
@@ -653,7 +653,7 @@
 				"startIndex": 0,
 				"endIndex": 14,
 				"normalized": "/* a comment *",
-				"value": null
+				"value": " a comment *"
 			}
 		]
 	},
@@ -666,7 +666,7 @@
 				"startIndex": 0,
 				"endIndex": 9,
 				"normalized": "/*a𐀀*/",
-				"value": null
+				"value": "a𐀀"
 			},
 			{
 				"type": "whitespace-token",
diff --git a/tests/phpunit/tests/css-api/wpCssToken.php b/tests/phpunit/tests/css-api/wpCssToken.php
index bcc59dd2cfad7..5f052cc6af272 100644
--- a/tests/phpunit/tests/css-api/wpCssToken.php
+++ b/tests/phpunit/tests/css-api/wpCssToken.php
@@ -186,4 +186,34 @@ public static function data_is_terminated(): array {
 			'ident'                => array( 'a b', true ),
 		);
 	}
+
+	/**
+	 * Tests that the value of a comment token is the text between its delimiters.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_comment_value
+	 *
+	 * @covers ::get_value
+	 */
+	public function test_comment_value( string $css, string $expected ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_COMMENT, $processor->get_token_type() );
+
+		$this->assertSame( $expected, $processor->get_token()->get_value() );
+	}
+
+	/**
+	 * Data provider for test_comment_value().
+	 *
+	 * @return array[]
+	 */
+	public static function data_comment_value(): array {
+		return array(
+			'terminated'                        => array( '/* a */', ' a ' ),
+			'unterminated'                      => array( '/* a', ' a' ),
+			'opener star does not close'        => array( '/*/', '/' ),
+			'no escapes, newlines preprocessed' => array( "/*\\41\r\n*/", "\\41\n" ),
+		);
+	}
 }
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 13facea9908e7..43d8bb6b78c28 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -2061,7 +2061,7 @@ public function test_get_normalized_token_applies_normalization(): void {
 				'type'       => WP_CSS_Token_Processor::TOKEN_COMMENT,
 				'raw'        => "/* Comment\r\nwith\flines */",
 				'normalized' => "/* Comment\nwith\nlines */",
-				'value'      => null,
+				'value'      => " Comment\nwith\nlines ",
 			),
 			// Whitespace with \r\n.
 			array(

From 2f8f3e6b9fa9539e1c0059b51988f16200b61e08 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 16:53:48 +0400
Subject: [PATCH 54/77] Remove the unused leading_start and trailing_end
 offsets

remove_declaration() once removed a declaration from leading_start to trailing_end, taking the comments around it. Since "Preserve comments when removing style declarations" it removes the declaration and the whitespace next to it, and nothing reads either offset. The spec does not name them.

With them go get_trailing_ignored_end(), the byte offset tracked before each declaration, and the byte offset that consume_at_rule() and consume_simple_block() returned only to compute leading_start; both now return the token index.
---
 ...lass-wp-html-style-attribute-processor.php | 116 +++++++-----------
 1 file changed, 43 insertions(+), 73 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 458f12234cacb..1031d0ab606ef 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -57,7 +57,6 @@ class WP_HTML_Style_Attribute_Processor {
 	 * of the second declaration in this style are:
 	 *
 	 *     color: red;  width: 1px !important;  top: 0
-	 *                ╰────────────────────────╯   leading_start to trailing_end
 	 *                  ╰────────────────────╯     start to after
 	 *                         ╰─╯                 value_start to value_end
 	 *                             ╰────────╯      important_start to important_end
@@ -66,7 +65,7 @@ class WP_HTML_Style_Attribute_Processor {
 	 * value. The `important_*` offsets are null when the declaration has no
 	 * `!important` priority.
 	 *
-	 * @var array<int, array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
+	 * @var array<int, array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
 
@@ -585,17 +584,13 @@ private function ensure_parsed(): void {
 	 * Parses the token list according to the CSS declaration-list shape.
 	 */
 	private function parse_declaration_list(): void {
-		$index                 = 0;
-		$count                 = count( $this->tokens );
-		$previous_item_ends_at = 0;
+		$index = 0;
+		$count = count( $this->tokens );
 
 		while ( $index < $count ) {
-			$leading_start = $previous_item_ends_at;
-			$index         = $this->skip_ignored_tokens( $index );
+			$index = $this->skip_ignored_tokens( $index );
 
 			while ( $index < $count && WP_CSS_Token_Processor::TOKEN_SEMICOLON === $this->tokens[ $index ]->get_type() ) {
-				$previous_item_ends_at = self::get_token_end( $this->tokens[ $index ] );
-				$leading_start         = $previous_item_ends_at;
 				++$index;
 				$index = $this->skip_ignored_tokens( $index );
 			}
@@ -605,30 +600,28 @@ private function parse_declaration_list(): void {
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_AT_KEYWORD === $this->tokens[ $index ]->get_type() ) {
-				list( $index, $previous_item_ends_at ) = $this->consume_at_rule( $index );
+				$index = $this->consume_at_rule( $index );
 				continue;
 			}
 
 			list( $declaration_end, $after_declaration, $has_semicolon ) = $this->consume_declaration_segment( $index );
-			$declaration = $this->parse_declaration_segment( $leading_start, $index, $declaration_end, $after_declaration );
+			$declaration = $this->parse_declaration_segment( $index, $declaration_end, $after_declaration );
 
 			if ( null !== $declaration ) {
-				$declaration['trailing_end'] = $this->get_trailing_ignored_end( $declaration_end + ( $has_semicolon ? 1 : 0 ) );
-				$this->declarations[]        = $declaration;
+				$this->declarations[] = $declaration;
 			}
 
-			$index                 = $declaration_end + ( $has_semicolon ? 1 : 0 );
-			$previous_item_ends_at = $after_declaration;
+			$index = $declaration_end + ( $has_semicolon ? 1 : 0 );
 		}
 	}
 
 	/**
-	 * Consumes an at-rule and returns the token index and byte offset after it.
+	 * Consumes an at-rule and returns the token index after it.
 	 *
 	 * @param int $index At-keyword token index.
-	 * @return array{int,int} Token index and byte offset after the at-rule.
+	 * @return int Token index after the at-rule.
 	 */
-	private function consume_at_rule( int $index ): array {
+	private function consume_at_rule( int $index ): int {
 		$count = count( $this->tokens );
 		++$index;
 
@@ -636,7 +629,7 @@ private function consume_at_rule( int $index ): array {
 			$token = $this->tokens[ $index ];
 
 			if ( WP_CSS_Token_Processor::TOKEN_SEMICOLON === $token->get_type() ) {
-				return array( $index + 1, self::get_token_end( $token ) );
+				return $index + 1;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
@@ -644,25 +637,24 @@ private function consume_at_rule( int $index ): array {
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
 			++$index;
 		}
 
-		$after = empty( $this->tokens ) ? strlen( $this->style ) : self::get_token_end( $this->tokens[ $count - 1 ] );
-		return array( $count, $after );
+		return $count;
 	}
 
 	/**
@@ -670,9 +662,9 @@ private function consume_at_rule( int $index ): array {
 	 *
 	 * @param int    $index        Token index for the opening token.
 	 * @param string $closing_type Expected closing token type.
-	 * @return array{int,int} Token index and byte offset after the block.
+	 * @return int Token index after the block.
 	 */
-	private function consume_simple_block( int $index, string $closing_type ): array {
+	private function consume_simple_block( int $index, string $closing_type ): int {
 		$count = count( $this->tokens );
 		++$index;
 
@@ -680,34 +672,33 @@ private function consume_simple_block( int $index, string $closing_type ): array
 			$token = $this->tokens[ $index ];
 
 			if ( $closing_type === $token->get_type() ) {
-				return array( $index + 1, self::get_token_end( $token ) );
+				return $index + 1;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
 
 			++$index;
 		}
 
-		$after = empty( $this->tokens ) ? strlen( $this->style ) : self::get_token_end( $this->tokens[ $count - 1 ] );
-		return array( $count, $after );
+		return $count;
 	}
 
 	/**
@@ -727,22 +718,22 @@ private function consume_declaration_segment( int $index ): array {
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
 
@@ -756,13 +747,12 @@ private function consume_declaration_segment( int $index ): array {
 	/**
 	 * Parses a declaration from a token segment.
 	 *
-	 * @param int $leading_start Byte offset before leading trivia.
-	 * @param int $start_index   First token index in the segment.
-	 * @param int $end_index     Token index after the segment.
-	 * @param int $after         Byte offset after the declaration.
-	 * @return array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @param int $start_index First token index in the segment.
+	 * @param int $end_index   Token index after the segment.
+	 * @param int $after       Byte offset after the declaration.
+	 * @return array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
-	private function parse_declaration_segment( int $leading_start, int $start_index, int $end_index, int $after ): ?array {
+	private function parse_declaration_segment( int $start_index, int $end_index, int $after ): ?array {
 		$index = $this->skip_ignored_tokens( $start_index, $end_index );
 		if ( $index >= $end_index || WP_CSS_Token_Processor::TOKEN_IDENT !== $this->tokens[ $index ]->get_type() ) {
 			return null;
@@ -822,10 +812,8 @@ private function parse_declaration_segment( int $leading_start, int $start_index
 
 		return array(
 			'name'            => $name,
-			'leading_start'   => $leading_start,
 			'start'           => $name_token->get_start(),
 			'after'           => $after,
-			'trailing_end'    => $after,
 			'value_start'     => $value_start,
 			'value_end'       => $value_end,
 			'value_tokens'    => array( $value_start_index, $value_end_index ),
@@ -857,22 +845,22 @@ private function get_top_level_non_ignored_token_indexes( int $start, int $end )
 			$top_level_tokens[] = $index;
 
 			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
 
@@ -914,24 +902,6 @@ private function trim_ignored_tokens( int $start, int $end ): int {
 		return $end;
 	}
 
-	/**
-	 * Gets the byte offset after ignored tokens beginning at a token index.
-	 *
-	 * @param int $index Token index.
-	 * @return int Byte offset after ignored tokens.
-	 */
-	private function get_trailing_ignored_end( int $index ): int {
-		$end   = $index > 0 && isset( $this->tokens[ $index - 1 ] ) ? self::get_token_end( $this->tokens[ $index - 1 ] ) : 0;
-		$count = count( $this->tokens );
-
-		while ( $index < $count && $this->is_ignored_token( $this->tokens[ $index ] ) ) {
-			$end = self::get_token_end( $this->tokens[ $index ] );
-			++$index;
-		}
-
-		return $end;
-	}
-
 	/**
 	 * Checks whether a token is ignored by declaration-list grammar.
 	 *
@@ -988,7 +958,7 @@ private function get_offset_after_following_whitespace( int $offset ): int {
 	/**
 	 * Gets the current declaration metadata.
 	 *
-	 * @return array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
+	 * @return array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function get_current_declaration(): ?array {
 		if (
@@ -1005,7 +975,7 @@ private function get_current_declaration(): ?array {
 	/**
 	 * Checks whether a replacement preserves the current declaration's structure.
 	 *
-	 * @param array{name:string, leading_start:int, start:int, after:int, trailing_end:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
+	 * @param array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
 	 * @param int                                                                                                                                                                                                                           $start              Byte offset at which to start the replacement.
 	 * @param int                                                                                                                                                                                                                           $length             Number of bytes to replace.
 	 * @param string                                                                                                                                                                                                                        $text               Replacement text.
@@ -1231,22 +1201,22 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 			$last_token = $token;
 
 			if ( WP_CSS_Token_Processor::TOKEN_FUNCTION === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_PAREN === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACKET === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACKET );
 				continue;
 			}
 
 			if ( WP_CSS_Token_Processor::TOKEN_LEFT_BRACE === $token->get_type() ) {
-				list( $index ) = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
+				$index = $this->consume_simple_block( $index, WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE );
 				continue;
 			}
 

From 2fa2211f192321fbf574ee10c298a516efe709b9 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 16:54:07 +0400
Subject: [PATCH 55/77] Expect the comment text in the value token view

Comment tokens now have the text between their delimiters as their value.
---
 tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index b544e254ac1d5..dbcabd5dec7ad 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -1269,7 +1269,7 @@ public static function data_value_tokens(): array {
 				array(
 					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '1', 8, 3, 'px' ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 11, 1 ),
-					self::token( WP_CSS_Token_Processor::TOKEN_COMMENT, null, 12, 7 ),
+					self::token( WP_CSS_Token_Processor::TOKEN_COMMENT, ' a ', 12, 7 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_WHITESPACE, null, 19, 1 ),
 					self::token( WP_CSS_Token_Processor::TOKEN_DIMENSION, '2', 20, 3, 'px' ),
 				),

From 394a9f16b1efcb5d215be7219532c22701265dd4 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 17:10:57 +0400
Subject: [PATCH 56/77] Match the is_valid_escape() comments to its code

The docblock said a `\` followed by the end of the input is not a valid escape, but the function returns true there, as CSS Syntax requires: only a newline rejects it. The spec step that rejects a newline was written above the end-of-input branch, which returns true, and the newline check was labeled with the step that returns true. Each comment now precedes the code it describes.
---
 .../css-api/class-wp-css-token-processor.php  | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 492e13460f1b3..b96ee8aab6b65 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -1689,7 +1689,8 @@ private static function decode_escape_at( string $css, int $offset, &$bytes_cons
 	/**
 	 * Checks if current position starts a valid escape sequence.
 	 *
-	 * A valid escape is a backslash not followed by a newline or EOF.
+	 * A valid escape is a `\` not followed by a newline. A `\` at the end of
+	 * the input is a valid escape; consuming it produces U+FFFD.
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
 	 *
@@ -1704,23 +1705,22 @@ private static function is_valid_escape( string $css, int $offset ): bool {
 		if ( $offset >= $css_length || '\\' !== $css[ $offset ] ) {
 			return false;
 		}
-		// Otherwise, if the second code point is a newline, return false.
+
+		// The end of the input is not a newline.
 		if ( $offset + 1 >= $css_length ) {
-			// The spec rejects only a newline as the second code point, so a `\` at EOF is a valid escape.
 			return true;
 		}
 
-		// Otherwise, if the second code point is not a newline, return true.
+		/*
+		 * Otherwise, if the second code point is a newline, return false.
+		 * Otherwise, return true.
+		 *
+		 * Preprocessing turns CR, FF and CRLF into a newline, so the CR check also covers CRLF.
+		 */
 		return (
 			"\n" !== $css[ $offset + 1 ] &&
-
-			// Form feed is normalized to newline during preprocessing.
 			"\f" !== $css[ $offset + 1 ] &&
-
-			// Carriage return is normalized to newline during preprocessing.
 			"\r" !== $css[ $offset + 1 ]
-
-			// The \r check also covers \r\n.
 		);
 	}
 

From e270ce24d9b079e9d677820e3023186498c726c7 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 17:12:06 +0400
Subject: [PATCH 57/77] Do not decode escapes in comment tokens

get_normalized_token() decoded escapes in every token, so `/* \41 */` was normalized to `/* A*/`. CSS comments contain no escapes. The new WP_CSS_Token_Processor::preprocess_range() applies input preprocessing only: CR, CRLF and FF become LF, and NUL and invalid UTF-8 become U+FFFD. get_normalized_token() uses it for comment tokens, and WP_CSS_Token::get_value() uses it for comment values instead of its own copy of the same rules.

Corpus case `tests/comment/0004` expected the decoding: `/*\*/` normalized to `/**/`. It now expects `/*\*/`, and the corpus README says escapes are decoded outside comments only.
---
 .../css-api/class-wp-css-token-processor.php  | 32 +++++++++++++++++++
 .../css-api/class-wp-css-token.php            | 11 +------
 tests/phpunit/data/css-api/README.md          |  4 +--
 .../phpunit/data/css-api/css-test-cases.json  |  2 +-
 .../tests/css-api/wpCssTokenProcessor.php     | 26 +++++++++++++++
 5 files changed, 62 insertions(+), 13 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index b96ee8aab6b65..0a0efa5e2aead 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -772,6 +772,8 @@ public function get_token_type_flag(): ?string {
 	 * - `\r\n`, `\r`, `\f` → `\n`
 	 * - `\x00` → U+FFFD (�)
 	 *
+	 * Comments contain no escapes, so only the normalization applies to them.
+	 *
 	 * This is different from get_token_value() which returns the semantic value
 	 * (e.g., for strings: content without quotes; for numbers: numeric value).
 	 *
@@ -784,6 +786,10 @@ public function get_normalized_token(): ?string {
 			return null;
 		}
 
+		if ( self::TOKEN_COMMENT === $this->token_type ) {
+			return self::preprocess_range( $this->css, $this->token_starts_at, $this->token_length );
+		}
+
 		return self::decode_range(
 			$this->css,
 			$this->token_starts_at,
@@ -1603,6 +1609,32 @@ public static function decode_range( string $css, int $start, int $length, bool
 		return $decoded;
 	}
 
+	/**
+	 * Applies CSS input preprocessing to a byte range without decoding escapes.
+	 *
+	 * CR, CRLF and FF become LF, and NUL and invalid UTF-8 become U+FFFD.
+	 * Comments are read with this method because they contain no escapes.
+	 *
+	 * @since 7.3.0
+	 * @access private
+	 *
+	 * @param string $css    CSS source the offsets index.
+	 * @param int    $start  Start byte offset.
+	 * @param int    $length Length of the substring to preprocess.
+	 * @return string Preprocessed string.
+	 */
+	public static function preprocess_range( string $css, int $start, int $length ): string {
+		return strtr(
+			wp_scrub_utf8( substr( $css, $start, $length ) ),
+			array(
+				"\r\n" => "\n",
+				"\r"   => "\n",
+				"\f"   => "\n",
+				"\0"   => "\u{FFFD}",
+			)
+		);
+	}
+
 	/**
 	 * Decodes an escape sequence starting at the given offset.
 	 *
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 7169a69865a1b..2d31a5d27f675 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -289,16 +289,7 @@ private function decode_value(): ?string {
 				return WP_CSS_Token_Processor::decode_range( $this->css, $this->value_start, $this->value_length );
 
 			case WP_CSS_Token_Processor::TOKEN_COMMENT:
-				// Comments contain no escapes, so only input preprocessing applies.
-				return strtr(
-					wp_scrub_utf8( substr( $this->css, $this->value_start, $this->value_length ) ),
-					array(
-						"\r\n" => "\n",
-						"\r"   => "\n",
-						"\f"   => "\n",
-						"\0"   => "\u{FFFD}",
-					)
-				);
+				return WP_CSS_Token_Processor::preprocess_range( $this->css, $this->value_start, $this->value_length );
 
 			case WP_CSS_Token_Processor::TOKEN_NUMBER:
 				// Numbers are ASCII and have no escapes.
diff --git a/tests/phpunit/data/css-api/README.md b/tests/phpunit/data/css-api/README.md
index 25c0902648cb0..cac0315a0608f 100644
--- a/tests/phpunit/data/css-api/README.md
+++ b/tests/phpunit/data/css-api/README.md
@@ -28,8 +28,8 @@ The upstream corpus maps a case name to `{ css, tokens }`. Each upstream token h
   `structured.type` of hash tokens (`id` or `unrestricted`) and `signCharacter` are
   not kept.
 - `normalized` is WordPress's expectation for `WP_CSS_Token_Processor::get_normalized_token()`:
-  the token text after input preprocessing and escape decoding. Upstream has no such
-  field.
+  the token text after input preprocessing and, outside comments, escape decoding.
+  Upstream has no such field.
 
 Three cases carry WordPress's token expectations where the upstream package contradicts
 CSS Syntax Level 3: `tests/ident/0007` (`-§`), `tests/ident/0008` (`-×`) and
diff --git a/tests/phpunit/data/css-api/css-test-cases.json b/tests/phpunit/data/css-api/css-test-cases.json
index aa93e54c97adc..81c59877c7a8e 100644
--- a/tests/phpunit/data/css-api/css-test-cases.json
+++ b/tests/phpunit/data/css-api/css-test-cases.json
@@ -615,7 +615,7 @@
 				"raw": "/*\\*/",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "/**/",
+				"normalized": "/*\\*/",
 				"value": "\\"
 			},
 			{
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 43d8bb6b78c28..f372a4f780ce5 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -2229,6 +2229,32 @@ public function test_get_normalized_token_applies_normalization(): void {
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
+	/**
+	 * Tests that get_normalized_token() does not decode escapes in a comment.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_normalized_comment
+	 */
+	public function test_get_normalized_token_keeps_comment_escapes( string $css, string $expected ): void {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$this->assertTrue( $processor->next_token() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_COMMENT, $processor->get_token_type() );
+
+		$this->assertSame( $expected, $processor->get_normalized_token() );
+	}
+
+	/**
+	 * Data provider for test_get_normalized_token_keeps_comment_escapes().
+	 *
+	 * @return array[]
+	 */
+	public static function data_normalized_comment(): array {
+		return array(
+			'escape'                => array( '/* \\41 */', '/* \\41 */' ),
+			'newlines preprocessed' => array( "/*\\41\r\n\f*/", "/*\\41\n\n*/" ),
+		);
+	}
+
 	public function test_dimension_token_value(): void {
 		$css           = '10px;15em;20%;30pt;40pc;50vw;';
 		$expected      = array(

From f236c542432a9e131f2ddcf4401ad7b4b93db78b Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 17:48:11 +0400
Subject: [PATCH 58/77] Remove the tokenizer cursor getters that WP_CSS_Token
 duplicates

The cursor keeps next_token(), get_token(), get_token_type(),
get_token_start() and get_token_length(): it says what the current token
is and where it is. WP_CSS_Token says what the token contains.

Removed: get_token_value(), get_token_type_flag(), get_token_unit() and
is_token_terminated(), each a copy of a WP_CSS_Token getter;
get_unnormalized_token(), a substr() of the source by the offsets the
cursor already exposes; and get_normalized_token(), the decoded text of
the whole token span, which no code in src reads.

The `normalized` column of the css-test-cases.json fixture existed only
to check get_normalized_token(), so it is removed with it. The
collect_tokens() test helper now takes the CSS source, since it needs
the source to slice each token's raw text.
---
 .../css-api/class-wp-css-token-processor.php  | 143 ---
 tests/phpunit/data/css-api/README.md          |   3 -
 .../phpunit/data/css-api/css-test-cases.json  | 497 -----------
 .../tests/css-api/wpCssTokenProcessor.php     | 820 ++++++++----------
 .../tests/css-api/wpCssTokenSerializer.php    |   2 +-
 5 files changed, 352 insertions(+), 1113 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 0a0efa5e2aead..23e97efcb4021 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -744,104 +744,6 @@ public function get_token_type(): ?string {
 		return $this->token_type;
 	}
 
-	/**
-	 * Gets the current token's type flag, if it has one.
-	 *
-	 * Some token types have an additional flag:
-	 * - Hash tokens have an "id" or "unrestricted" flag.
-	 * - Number and dimension tokens have an "integer" flag when the number was
-	 *   written without a decimal point or exponent, and a "number" flag otherwise.
-	 * - Percentage tokens do not have a type flag.
-	 *
-	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
-	 *
-	 * @since 7.3.0
-	 *
-	 * @return string|null
-	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
-	 */
-	public function get_token_type_flag(): ?string {
-		return $this->token_type_flag;
-	}
-
-	/**
-	 * Gets the normalized token text from the CSS source.
-	 *
-	 * Returns the token with CSS normalization and escape decoding applied:
-	 * - CSS escapes decoded (e.g., `\6c` → `l`, `\2f` → `/`, `\A` → newline)
-	 * - `\r\n`, `\r`, `\f` → `\n`
-	 * - `\x00` → U+FFFD (�)
-	 *
-	 * Comments contain no escapes, so only the normalization applies to them.
-	 *
-	 * This is different from get_token_value() which returns the semantic value
-	 * (e.g., for strings: content without quotes; for numbers: numeric value).
-	 *
-	 * @since 7.3.0
-	 *
-	 * @return string|null
-	 */
-	public function get_normalized_token(): ?string {
-		if ( null === $this->token_starts_at || null === $this->token_length ) {
-			return null;
-		}
-
-		if ( self::TOKEN_COMMENT === $this->token_type ) {
-			return self::preprocess_range( $this->css, $this->token_starts_at, $this->token_length );
-		}
-
-		return self::decode_range(
-			$this->css,
-			$this->token_starts_at,
-			$this->token_length,
-			self::TOKEN_STRING === $this->token_type
-		);
-	}
-
-	/**
-	 * Gets the raw, unnormalized token text from the CSS source.
-	 *
-	 * Returns the exact bytes from the source without any normalization.
-	 * This preserves original line endings (`\r\n`, `\r`, `\f`) and null bytes.
-	 *
-	 * @since 7.3.0
-	 *
-	 * @return string|null
-	 */
-	public function get_unnormalized_token(): ?string {
-		if ( null === $this->token_starts_at || null === $this->token_length ) {
-			return null;
-		}
-		return substr( $this->css, $this->token_starts_at, $this->token_length );
-	}
-
-	/**
-	 * Gets the current token value as a normalized and decoded string. This is
-	 * a slight divergence from the CSS Syntax Level 3 spec, where all the numeric
-	 * values are parsed as numbers. This processor is only concerned with their
-	 * textual representation.
-	 *
-	 * Returns the semantic value of the token per CSS Syntax Level 3 spec:
-	 *
-	 * - For delimiters: the single code point
-	 * - For numbers/percentages: the string representation of the number
-	 * - For dimensions: the string representation of the number (use get_token_unit() for the unit)
-	 * - For identifiers/functions/hash/at-keywords: the decoded identifier string
-	 * - For strings/URLs: the decoded string value
-	 * - For comments: the text between the delimiters, with newlines normalized;
-	 *   comments contain no escapes
-	 * - For other tokens: null
-	 *
-	 * @since 7.3.0
-	 *
-	 * @link https://www.w3.org/TR/css-syntax-3/#tokenization
-	 * @return string|null
-	 */
-	public function get_token_value(): ?string {
-		$token = $this->get_token();
-		return null === $token ? null : $token->get_value();
-	}
-
 	/**
 	 * Gets the byte offset at which the current token starts.
 	 *
@@ -864,50 +766,6 @@ public function get_token_length(): ?int {
 		return $this->token_length;
 	}
 
-	/**
-	 * Gets the unit for dimension tokens.
-	 *
-	 * @since 7.3.0
-	 *
-	 * @return string|null
-	 */
-	public function get_token_unit(): ?string {
-		return $this->token_unit;
-	}
-
-	/**
-	 * Reports whether the current token ended at its closing delimiter.
-	 *
-	 * Comment, string, url and bad-url tokens have a closing delimiter: `*` `/`,
-	 * the matching quote, or `)`. When the input ends before the delimiter,
-	 * the tokenizer still returns the token, and this method returns false.
-	 * It returns true for every other token type, which have no closing
-	 * delimiter, and false before the first call to next_token().
-	 *
-	 * Example:
-	 *
-	 * ```php interactive
-	 * $processor = WP_CSS_Token_Processor::create( '"abc' );
-	 * $processor->next_token();
-	 * echo $processor->get_token_type() . "\n";
-	 * var_dump( $processor->is_token_terminated() );
-	 * // Outputs:
-	 * // string-token
-	 * // bool(false)
-	 * ```
-	 *
-	 * @link https://www.w3.org/TR/css-syntax-3/#consume-comment
-	 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
-	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
-	 *
-	 * @since 7.3.0
-	 *
-	 * @return bool Whether the current token ended at its closing delimiter.
-	 */
-	public function is_token_terminated(): bool {
-		return null !== $this->token_type && $this->token_is_terminated;
-	}
-
 	/**
 	 * Clears token state between tokens.
 	 */
@@ -1453,7 +1311,6 @@ private function consume_ident_codepoint( $at ): int {
 		return $this->consume_ident_start_codepoint( $at );
 	}
 
-
 	/**
 	 * Ident-start code point
 	 *     A letter, a non-ASCII code point, or U+005F LOW LINE (_).
diff --git a/tests/phpunit/data/css-api/README.md b/tests/phpunit/data/css-api/README.md
index cac0315a0608f..93da314e4ef01 100644
--- a/tests/phpunit/data/css-api/README.md
+++ b/tests/phpunit/data/css-api/README.md
@@ -27,9 +27,6 @@ The upstream corpus maps a case name to `{ css, tokens }`. Each upstream token h
 - `numberType` is `structured.type` on number and dimension tokens. The upstream
   `structured.type` of hash tokens (`id` or `unrestricted`) and `signCharacter` are
   not kept.
-- `normalized` is WordPress's expectation for `WP_CSS_Token_Processor::get_normalized_token()`:
-  the token text after input preprocessing and, outside comments, escape decoding.
-  Upstream has no such field.
 
 Three cases carry WordPress's token expectations where the upstream package contradicts
 CSS Syntax Level 3: `tests/ident/0007` (`-§`), `tests/ident/0008` (`-×`) and
diff --git a/tests/phpunit/data/css-api/css-test-cases.json b/tests/phpunit/data/css-api/css-test-cases.json
index 81c59877c7a8e..30e0dc8cdcccd 100644
--- a/tests/phpunit/data/css-api/css-test-cases.json
+++ b/tests/phpunit/data/css-api/css-test-cases.json
@@ -7,7 +7,6 @@
 				"raw": "@foo",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "@foo",
 				"value": "foo"
 			},
 			{
@@ -15,7 +14,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -28,7 +26,6 @@
 				"raw": "@--",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "@--",
 				"value": "--"
 			},
 			{
@@ -36,7 +33,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -49,7 +45,6 @@
 				"raw": "@",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "@",
 				"value": "@"
 			},
 			{
@@ -57,7 +52,6 @@
 				"raw": "-1",
 				"startIndex": 1,
 				"endIndex": 3,
-				"normalized": "-1",
 				"value": "-1",
 				"numberType": "integer"
 			},
@@ -66,7 +60,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -79,7 +72,6 @@
 				"raw": "@--1",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "@--1",
 				"value": "--1"
 			},
 			{
@@ -87,7 +79,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -100,7 +91,6 @@
 				"raw": "@\\@",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "@@",
 				"value": "@"
 			},
 			{
@@ -108,7 +98,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -121,7 +110,6 @@
 				"raw": "@_",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "@_",
 				"value": "_"
 			},
 			{
@@ -129,7 +117,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -142,7 +129,6 @@
 				"raw": "@",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "@",
 				"value": "@"
 			},
 			{
@@ -150,7 +136,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -163,7 +148,6 @@
 				"raw": "pvA3",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "pvA3",
 				"value": "pvA3"
 			},
 			{
@@ -171,7 +155,6 @@
 				"raw": "@",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "@",
 				"value": "@"
 			},
 			{
@@ -179,7 +162,6 @@
 				"raw": "\\",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\\",
 				"value": "\\"
 			},
 			{
@@ -187,7 +169,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -195,7 +176,6 @@
 				"raw": "eBnP",
 				"startIndex": 7,
 				"endIndex": 11,
-				"normalized": "eBnP",
 				"value": "eBnP"
 			},
 			{
@@ -203,7 +183,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -216,7 +195,6 @@
 				"raw": "@aa𐀀",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "@aa𐀀",
 				"value": "aa𐀀"
 			},
 			{
@@ -224,7 +202,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -237,7 +214,6 @@
 				"raw": "\"foo",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "\"foo",
 				"value": null
 			},
 			{
@@ -245,7 +221,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -253,7 +228,6 @@
 				"raw": "\"",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\"",
 				"value": null
 			},
 			{
@@ -261,7 +235,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -274,7 +247,6 @@
 				"raw": "\"foo\\\n\"",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "\"foo\"",
 				"value": "foo"
 			},
 			{
@@ -282,7 +254,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -295,7 +266,6 @@
 				"raw": "\"foo",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "\"foo",
 				"value": null
 			},
 			{
@@ -303,7 +273,6 @@
 				"raw": "\r\n",
 				"startIndex": 4,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -311,7 +280,6 @@
 				"raw": "\"",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\"",
 				"value": null
 			},
 			{
@@ -319,7 +287,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -332,7 +299,6 @@
 				"raw": "\"foo\\\r\n\"",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "\"foo\"",
 				"value": "foo"
 			},
 			{
@@ -340,7 +306,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -353,7 +318,6 @@
 				"raw": "\"aa𐀀",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "\"aa𐀀",
 				"value": null
 			},
 			{
@@ -361,7 +325,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -374,7 +337,6 @@
 				"raw": "url(\n",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "url(\n",
 				"value": ""
 			}
 		]
@@ -387,7 +349,6 @@
 				"raw": "url( a\n",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "url( a\n",
 				"value": "a"
 			}
 		]
@@ -400,7 +361,6 @@
 				"raw": "url( a a\n",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "url( a a\n",
 				"value": null
 			}
 		]
@@ -413,7 +373,6 @@
 				"raw": "url( a a)",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "url( a a)",
 				"value": null
 			},
 			{
@@ -421,7 +380,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -434,7 +392,6 @@
 				"raw": "url( a a\\)\n",
 				"startIndex": 0,
 				"endIndex": 11,
-				"normalized": "url( a a)\n",
 				"value": null
 			}
 		]
@@ -447,7 +404,6 @@
 				"raw": "url( \\\n",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "url( \\\n",
 				"value": null
 			}
 		]
@@ -460,7 +416,6 @@
 				"raw": "url(a'')",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "url(a'')",
 				"value": null
 			},
 			{
@@ -468,7 +423,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -481,7 +435,6 @@
 				"raw": "url(a\")",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "url(a\")",
 				"value": null
 			},
 			{
@@ -489,7 +442,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -502,7 +454,6 @@
 				"raw": ":",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ":",
 				"value": null
 			},
 			{
@@ -510,7 +461,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -523,7 +473,6 @@
 				"raw": ",",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ",",
 				"value": null
 			},
 			{
@@ -531,7 +480,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -544,7 +492,6 @@
 				"raw": "/* a comment */",
 				"startIndex": 0,
 				"endIndex": 15,
-				"normalized": "/* a comment */",
 				"value": " a comment "
 			},
 			{
@@ -552,7 +499,6 @@
 				"raw": "\n",
 				"startIndex": 15,
 				"endIndex": 16,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -565,7 +511,6 @@
 				"raw": "/* a comment ",
 				"startIndex": 0,
 				"endIndex": 13,
-				"normalized": "/* a comment ",
 				"value": " a comment "
 			}
 		]
@@ -578,7 +523,6 @@
 				"raw": "a",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -586,7 +530,6 @@
 				"raw": "/**/",
 				"startIndex": 1,
 				"endIndex": 5,
-				"normalized": "/**/",
 				"value": ""
 			},
 			{
@@ -594,7 +537,6 @@
 				"raw": "b",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "b",
 				"value": "b"
 			},
 			{
@@ -602,7 +544,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -615,7 +556,6 @@
 				"raw": "/*\\*/",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "/*\\*/",
 				"value": "\\"
 			},
 			{
@@ -623,7 +563,6 @@
 				"raw": "*",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "*",
 				"value": "*"
 			},
 			{
@@ -631,7 +570,6 @@
 				"raw": "/",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "/",
 				"value": "/"
 			},
 			{
@@ -639,7 +577,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -652,7 +589,6 @@
 				"raw": "/* a comment *",
 				"startIndex": 0,
 				"endIndex": 14,
-				"normalized": "/* a comment *",
 				"value": " a comment *"
 			}
 		]
@@ -665,7 +601,6 @@
 				"raw": "/*a𐀀*/",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "/*a𐀀*/",
 				"value": "a𐀀"
 			},
 			{
@@ -673,7 +608,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -686,7 +620,6 @@
 				"raw": "0",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "0",
 				"value": "0",
 				"numberType": "integer"
 			},
@@ -695,7 +628,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -703,7 +635,6 @@
 				"raw": "1",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "1",
 				"value": "1",
 				"numberType": "integer"
 			},
@@ -712,7 +643,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -720,7 +650,6 @@
 				"raw": "2",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "2",
 				"value": "2",
 				"numberType": "integer"
 			},
@@ -729,7 +658,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -737,7 +665,6 @@
 				"raw": "3",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "3",
 				"value": "3",
 				"numberType": "integer"
 			},
@@ -746,7 +673,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -754,7 +680,6 @@
 				"raw": "4",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "4",
 				"value": "4",
 				"numberType": "integer"
 			},
@@ -763,7 +688,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -771,7 +695,6 @@
 				"raw": "5",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": "5",
 				"value": "5",
 				"numberType": "integer"
 			},
@@ -780,7 +703,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -788,7 +710,6 @@
 				"raw": "6",
 				"startIndex": 12,
 				"endIndex": 13,
-				"normalized": "6",
 				"value": "6",
 				"numberType": "integer"
 			},
@@ -797,7 +718,6 @@
 				"raw": "\n",
 				"startIndex": 13,
 				"endIndex": 14,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -805,7 +725,6 @@
 				"raw": "7",
 				"startIndex": 14,
 				"endIndex": 15,
-				"normalized": "7",
 				"value": "7",
 				"numberType": "integer"
 			},
@@ -814,7 +733,6 @@
 				"raw": "\n",
 				"startIndex": 15,
 				"endIndex": 16,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -822,7 +740,6 @@
 				"raw": "8",
 				"startIndex": 16,
 				"endIndex": 17,
-				"normalized": "8",
 				"value": "8",
 				"numberType": "integer"
 			},
@@ -831,7 +748,6 @@
 				"raw": "\n",
 				"startIndex": 17,
 				"endIndex": 18,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -839,7 +755,6 @@
 				"raw": "9",
 				"startIndex": 18,
 				"endIndex": 19,
-				"normalized": "9",
 				"value": "9",
 				"numberType": "integer"
 			},
@@ -848,7 +763,6 @@
 				"raw": "\n",
 				"startIndex": 19,
 				"endIndex": 20,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -861,7 +775,6 @@
 				"raw": "10px",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "10px",
 				"value": "10",
 				"unit": "px",
 				"numberType": "integer"
@@ -871,7 +784,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -884,7 +796,6 @@
 				"raw": "10\\70 x",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "10px",
 				"value": "10",
 				"unit": "px",
 				"numberType": "integer"
@@ -894,7 +805,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -907,7 +817,6 @@
 				"raw": "10--custom-px",
 				"startIndex": 0,
 				"endIndex": 13,
-				"normalized": "10--custom-px",
 				"value": "10",
 				"unit": "--custom-px",
 				"numberType": "integer"
@@ -917,7 +826,6 @@
 				"raw": "\n",
 				"startIndex": 13,
 				"endIndex": 14,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -930,7 +838,6 @@
 				"raw": "10e2px",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "10e2px",
 				"value": "10e2",
 				"unit": "px",
 				"numberType": "number"
@@ -940,7 +847,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -953,7 +859,6 @@
 				"raw": "10E2PX",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "10E2PX",
 				"value": "10E2",
 				"unit": "PX",
 				"numberType": "number"
@@ -963,7 +868,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -976,7 +880,6 @@
 				"raw": "10\\0\n",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "10�",
 				"value": "10",
 				"unit": "�",
 				"numberType": "integer"
@@ -991,7 +894,6 @@
 				"raw": "10a𐀀",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "10a𐀀",
 				"value": "10",
 				"unit": "a𐀀",
 				"numberType": "integer"
@@ -1001,7 +903,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1014,7 +915,6 @@
 				"raw": "10a\u0000",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "10a�",
 				"value": "10",
 				"unit": "a�",
 				"numberType": "integer"
@@ -1029,7 +929,6 @@
 				"raw": "\\",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -1042,7 +941,6 @@
 				"raw": "\\0",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -1055,7 +953,6 @@
 				"raw": "\\\\",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "\\",
 				"value": "\\"
 			}
 		]
@@ -1068,7 +965,6 @@
 				"raw": "\\0a b",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "\nb",
 				"value": "\nb"
 			},
 			{
@@ -1076,7 +972,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1089,7 +984,6 @@
 				"raw": "\\0ab ",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "«",
 				"value": "«"
 			},
 			{
@@ -1097,7 +991,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1110,7 +1003,6 @@
 				"raw": "\\0ab (",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "«(",
 				"value": "«"
 			},
 			{
@@ -1118,7 +1010,6 @@
 				"raw": "foo",
 				"startIndex": 6,
 				"endIndex": 9,
-				"normalized": "foo",
 				"value": "foo"
 			},
 			{
@@ -1126,7 +1017,6 @@
 				"raw": ")",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -1134,7 +1024,6 @@
 				"raw": "\n",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1147,7 +1036,6 @@
 				"raw": "\\0ab ",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "«",
 				"value": "«"
 			},
 			{
@@ -1155,7 +1043,6 @@
 				"raw": " ",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1163,7 +1050,6 @@
 				"raw": "(",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "(",
 				"value": null
 			},
 			{
@@ -1171,7 +1057,6 @@
 				"raw": "foo",
 				"startIndex": 7,
 				"endIndex": 10,
-				"normalized": "foo",
 				"value": "foo"
 			},
 			{
@@ -1179,7 +1064,6 @@
 				"raw": ")",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -1187,7 +1071,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1200,7 +1083,6 @@
 				"raw": "\\0000ab\n",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "«",
 				"value": "«"
 			}
 		]
@@ -1213,7 +1095,6 @@
 				"raw": "\\00000ab",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "\nb",
 				"value": "\nb"
 			},
 			{
@@ -1221,7 +1102,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1234,7 +1114,6 @@
 				"raw": "\\110000\n",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -1247,7 +1126,6 @@
 				"raw": "\\00D800\n",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -1260,7 +1138,6 @@
 				"raw": "\\00DFFF\n",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -1273,7 +1150,6 @@
 				"raw": "\\",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "\\",
 				"value": "\\"
 			},
 			{
@@ -1281,7 +1157,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1294,7 +1169,6 @@
 				"raw": "\\\u0000",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "�",
 				"value": "�"
 			},
 			{
@@ -1302,7 +1176,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1315,7 +1188,6 @@
 				"raw": "\\\u0000",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "�",
 				"value": "�"
 			},
 			{
@@ -1323,7 +1195,6 @@
 				"raw": "\b",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\b",
 				"value": "\b"
 			},
 			{
@@ -1331,7 +1202,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1344,7 +1214,6 @@
 				"raw": "\"a\\12\r\nb\"",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "\"a\u0012b\"",
 				"value": "a\u0012b"
 			}
 		]
@@ -1357,7 +1226,6 @@
 				"raw": ".",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ".",
 				"value": "."
 			},
 			{
@@ -1365,7 +1233,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1378,7 +1245,6 @@
 				"raw": ".",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ".",
 				"value": "."
 			},
 			{
@@ -1386,7 +1252,6 @@
 				"raw": "a",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -1394,7 +1259,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1407,7 +1271,6 @@
 				"raw": ".1",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": ".1",
 				"value": ".1",
 				"numberType": "number"
 			},
@@ -1416,7 +1279,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -1429,7 +1291,6 @@
 				"raw": "4waPtwEEGH\\\u0000jV3zM6hh6w30N0PC",
 				"startIndex": 0,
 				"endIndex": 28,
-				"normalized": "4waPtwEEGH�jV3zM6hh6w30N0PC",
 				"value": "4",
 				"unit": "waPtwEEGH�jV3zM6hh6w30N0PC",
 				"numberType": "integer"
@@ -1439,7 +1300,6 @@
 				"raw": " ",
 				"startIndex": 28,
 				"endIndex": 29,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1447,7 +1307,6 @@
 				"raw": "7m8KM0HcWGOPw28Gt",
 				"startIndex": 29,
 				"endIndex": 46,
-				"normalized": "7m8KM0HcWGOPw28Gt",
 				"value": "7",
 				"unit": "m8KM0HcWGOPw28Gt",
 				"numberType": "integer"
@@ -1457,7 +1316,6 @@
 				"raw": "(",
 				"startIndex": 46,
 				"endIndex": 47,
-				"normalized": "(",
 				"value": null
 			},
 			{
@@ -1465,7 +1323,6 @@
 				"raw": "r19",
 				"startIndex": 47,
 				"endIndex": 50,
-				"normalized": "r19",
 				"value": "r19"
 			}
 		]
@@ -1478,7 +1335,6 @@
 				"raw": "ak",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "ak",
 				"value": "ak"
 			},
 			{
@@ -1486,7 +1342,6 @@
 				"raw": "]",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "]",
 				"value": null
 			},
 			{
@@ -1494,7 +1349,6 @@
 				"raw": "P0A",
 				"startIndex": 3,
 				"endIndex": 6,
-				"normalized": "P0A",
 				"value": "P0A"
 			},
 			{
@@ -1502,7 +1356,6 @@
 				"raw": "}",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "}",
 				"value": null
 			},
 			{
@@ -1510,7 +1363,6 @@
 				"raw": "808G",
 				"startIndex": 7,
 				"endIndex": 11,
-				"normalized": "808G",
 				"value": "808",
 				"unit": "G",
 				"numberType": "integer"
@@ -1520,7 +1372,6 @@
 				"raw": "\"lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5J\\\r\nBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9\"",
 				"startIndex": 11,
 				"endIndex": 102,
-				"normalized": "\"lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5JBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9\"",
 				"value": "lQh{R5M!QyOWE}oC2{2K TIa9}zb2oXWREY]0aj5JBJ5CO-16W5H7noF 19䀹41H3e8Z9%tg[O5AHEY24xh'9"
 			},
 			{
@@ -1528,7 +1379,6 @@
 				"raw": "\"c34Q\"",
 				"startIndex": 102,
 				"endIndex": 108,
-				"normalized": "\"c34Q\"",
 				"value": "c34Q"
 			},
 			{
@@ -1536,7 +1386,6 @@
 				"raw": "iiC0e45Da5f",
 				"startIndex": 108,
 				"endIndex": 119,
-				"normalized": "iiC0e45Da5f",
 				"value": "iiC0e45Da5f"
 			},
 			{
@@ -1544,7 +1393,6 @@
 				"raw": "\"F5X3\"",
 				"startIndex": 119,
 				"endIndex": 125,
-				"normalized": "\"F5X3\"",
 				"value": "F5X3"
 			},
 			{
@@ -1552,7 +1400,6 @@
 				"raw": "o(",
 				"startIndex": 125,
 				"endIndex": 127,
-				"normalized": "o(",
 				"value": "o"
 			}
 		]
@@ -1565,7 +1412,6 @@
 				"raw": "\u000e",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "\u000e",
 				"value": "\u000e"
 			},
 			{
@@ -1573,7 +1419,6 @@
 				"raw": "7rSD6I5L1lglVRlL2X7BbEk\\3HCd",
 				"startIndex": 1,
 				"endIndex": 29,
-				"normalized": "7rSD6I5L1lglVRlL2X7BbEk\u0003HCd",
 				"value": "7",
 				"unit": "rSD6I5L1lglVRlL2X7BbEk\u0003HCd",
 				"numberType": "integer"
@@ -1583,7 +1428,6 @@
 				"raw": "\r",
 				"startIndex": 29,
 				"endIndex": 30,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -1591,7 +1435,6 @@
 				"raw": "94",
 				"startIndex": 30,
 				"endIndex": 32,
-				"normalized": "94",
 				"value": "94",
 				"numberType": "integer"
 			},
@@ -1600,7 +1443,6 @@
 				"raw": " ",
 				"startIndex": 32,
 				"endIndex": 33,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1608,7 +1450,6 @@
 				"raw": "\\\u0000skoW25d4",
 				"startIndex": 33,
 				"endIndex": 43,
-				"normalized": "�skoW25d4",
 				"value": "�skoW25d4"
 			},
 			{
@@ -1616,7 +1457,6 @@
 				"raw": "%",
 				"startIndex": 43,
 				"endIndex": 44,
-				"normalized": "%",
 				"value": "%"
 			},
 			{
@@ -1624,7 +1464,6 @@
 				"raw": "l64UUskN",
 				"startIndex": 44,
 				"endIndex": 52,
-				"normalized": "l64UUskN",
 				"value": "l64UUskN"
 			},
 			{
@@ -1632,7 +1471,6 @@
 				"raw": "\"pHun\"",
 				"startIndex": 52,
 				"endIndex": 58,
-				"normalized": "\"pHun\"",
 				"value": "pHun"
 			},
 			{
@@ -1640,7 +1478,6 @@
 				"raw": "!",
 				"startIndex": 58,
 				"endIndex": 59,
-				"normalized": "!",
 				"value": "!"
 			}
 		]
@@ -1653,7 +1490,6 @@
 				"raw": "gzO0",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "gzO0",
 				"value": "gzO0"
 			},
 			{
@@ -1661,7 +1497,6 @@
 				"raw": "{",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "{",
 				"value": null
 			},
 			{
@@ -1669,7 +1504,6 @@
 				"raw": "(",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "(",
 				"value": null
 			},
 			{
@@ -1677,7 +1511,6 @@
 				"raw": "p",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "p",
 				"value": "p"
 			},
 			{
@@ -1685,7 +1518,6 @@
 				"raw": "{",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "{",
 				"value": null
 			},
 			{
@@ -1693,7 +1525,6 @@
 				"raw": "DzQ7\u0000(",
 				"startIndex": 8,
 				"endIndex": 14,
-				"normalized": "DzQ7�(",
 				"value": "DzQ7�"
 			},
 			{
@@ -1701,7 +1532,6 @@
 				"raw": "a1",
 				"startIndex": 14,
 				"endIndex": 16,
-				"normalized": "a1",
 				"value": "a1"
 			},
 			{
@@ -1709,7 +1539,6 @@
 				"raw": ";",
 				"startIndex": 16,
 				"endIndex": 17,
-				"normalized": ";",
 				"value": null
 			},
 			{
@@ -1717,7 +1546,6 @@
 				"raw": "r1iN7w",
 				"startIndex": 17,
 				"endIndex": 23,
-				"normalized": "r1iN7w",
 				"value": "r1iN7w"
 			},
 			{
@@ -1725,7 +1553,6 @@
 				"raw": ")",
 				"startIndex": 23,
 				"endIndex": 24,
-				"normalized": ")",
 				"value": null
 			}
 		]
@@ -1738,7 +1565,6 @@
 				"raw": "565",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "565",
 				"value": "565",
 				"numberType": "integer"
 			},
@@ -1747,7 +1573,6 @@
 				"raw": "'E{z\u0000U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1\\\r\nrey\thg7[5%rBK8RUC64Lu␌17O{E\\90873u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G'",
 				"startIndex": 3,
 				"endIndex": 263,
-				"normalized": "'E{z�U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1rey\thg7[5%rBK8RUC64Lu␌17O{E򐡳u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G'",
 				"value": "E{z�U\u001fEG2}2Verb>nj3TVk3mu7wX1J\b.H\u000bi1Ga8f5 dserqydJ3\"xj398xy.W\" uHQbv7Bw1NtF;N3PwNY7Vx00BF o\"4CXzvP\"{594 6r}8QQKNQw135i1rey\thg7[5%rBK8RUC64Lu␌17O{E򐡳u}1O3vx4gHTC55Q9i4\"V3Vx4\"7r(34L]F\"ns2pPf\"V7b)EOBGH8rdC7\"\u000eVJ4OQ[ 9jtoMdINgS7o�206vo72kTcKkZR9wl30G"
 			},
 			{
@@ -1755,7 +1580,6 @@
 				"raw": "vK",
 				"startIndex": 263,
 				"endIndex": 265,
-				"normalized": "vK",
 				"value": "vK"
 			},
 			{
@@ -1763,7 +1587,6 @@
 				"raw": "\n",
 				"startIndex": 265,
 				"endIndex": 266,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -1771,7 +1594,6 @@
 				"raw": "dhCEs3tValX",
 				"startIndex": 266,
 				"endIndex": 277,
-				"normalized": "dhCEs3tValX",
 				"value": "dhCEs3tValX"
 			},
 			{
@@ -1779,7 +1601,6 @@
 				"raw": " ",
 				"startIndex": 277,
 				"endIndex": 278,
-				"normalized": " ",
 				"value": null
 			}
 		]
@@ -1792,7 +1613,6 @@
 				"raw": "FWUNqr7uv8300nz",
 				"startIndex": 0,
 				"endIndex": 15,
-				"normalized": "FWUNqr7uv8300nz",
 				"value": "FWUNqr7uv8300nz"
 			},
 			{
@@ -1800,7 +1620,6 @@
 				"raw": "\b",
 				"startIndex": 15,
 				"endIndex": 16,
-				"normalized": "\b",
 				"value": "\b"
 			},
 			{
@@ -1808,7 +1627,6 @@
 				"raw": ",",
 				"startIndex": 16,
 				"endIndex": 17,
-				"normalized": ",",
 				"value": null
 			},
 			{
@@ -1816,7 +1634,6 @@
 				"raw": "8lU0j6B186kh",
 				"startIndex": 17,
 				"endIndex": 29,
-				"normalized": "8lU0j6B186kh",
 				"value": "8",
 				"unit": "lU0j6B186kh",
 				"numberType": "integer"
@@ -1826,7 +1643,6 @@
 				"raw": " ",
 				"startIndex": 29,
 				"endIndex": 30,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1834,7 +1650,6 @@
 				"raw": "\u00009",
 				"startIndex": 30,
 				"endIndex": 32,
-				"normalized": "�9",
 				"value": "�9"
 			},
 			{
@@ -1842,7 +1657,6 @@
 				"raw": " ",
 				"startIndex": 32,
 				"endIndex": 33,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1850,7 +1664,6 @@
 				"raw": "\u000e",
 				"startIndex": 33,
 				"endIndex": 34,
-				"normalized": "\u000e",
 				"value": "\u000e"
 			},
 			{
@@ -1858,7 +1671,6 @@
 				"raw": "GZafxf2GIhL9",
 				"startIndex": 34,
 				"endIndex": 46,
-				"normalized": "GZafxf2GIhL9",
 				"value": "GZafxf2GIhL9"
 			},
 			{
@@ -1866,7 +1678,6 @@
 				"raw": "%",
 				"startIndex": 46,
 				"endIndex": 47,
-				"normalized": "%",
 				"value": "%"
 			}
 		]
@@ -1879,7 +1690,6 @@
 				"raw": "FZ",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "FZ",
 				"value": "FZ"
 			},
 			{
@@ -1887,7 +1697,6 @@
 				"raw": " ",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -1895,7 +1704,6 @@
 				"raw": "0B120h5QUbNbmTD2K8mAD傿i",
 				"startIndex": 3,
 				"endIndex": 28,
-				"normalized": "0B120h5QUbNbmTD2K8mAD傿i",
 				"value": "0",
 				"unit": "B120h5QUbNbmTD2K8mAD傿i",
 				"numberType": "integer"
@@ -1905,7 +1713,6 @@
 				"raw": "+",
 				"startIndex": 28,
 				"endIndex": 29,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -1913,7 +1720,6 @@
 				"raw": "Yv9V0KS14Ng18ag",
 				"startIndex": 29,
 				"endIndex": 44,
-				"normalized": "Yv9V0KS14Ng18ag",
 				"value": "Yv9V0KS14Ng18ag"
 			},
 			{
@@ -1921,7 +1727,6 @@
 				"raw": "'\\\r\n{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\\BgK48qgu9'",
 				"startIndex": 44,
 				"endIndex": 126,
-				"normalized": "'{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\u000bgK48qgu9'",
 				"value": "{X<E/9b}0nIa%eSz-vapw2GqeMsri#e1BQf3b\u001fPlEnFQg{ofB)L9b571J4!{mCN㐥a\u000bgK48qgu9"
 			},
 			{
@@ -1929,7 +1734,6 @@
 				"raw": "jVRS䎟ROYRbe0m5508k",
 				"startIndex": 126,
 				"endIndex": 146,
-				"normalized": "jVRS䎟ROYRbe0m5508k",
 				"value": "jVRS䎟ROYRbe0m5508k"
 			},
 			{
@@ -1937,7 +1741,6 @@
 				"raw": ",",
 				"startIndex": 146,
 				"endIndex": 147,
-				"normalized": ",",
 				"value": null
 			},
 			{
@@ -1945,7 +1748,6 @@
 				"raw": "O0C",
 				"startIndex": 147,
 				"endIndex": 150,
-				"normalized": "O0C",
 				"value": "O0C"
 			},
 			{
@@ -1953,7 +1755,6 @@
 				"raw": "\u001f",
 				"startIndex": 150,
 				"endIndex": 151,
-				"normalized": "\u001f",
 				"value": "\u001f"
 			}
 		]
@@ -1966,7 +1767,6 @@
 				"raw": "'TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1\u0000rV7P'",
 				"startIndex": 0,
 				"endIndex": 156,
-				"normalized": "'TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1�rV7P'",
 				"value": "TR(:\b5RN)_e3w<gD5iL1EO-3zZw ntX3@0<KP9}V0 3Q80{Tqp}7dkUykEm ks �(ZnXhqsp3)G4JKqbWAfx7sPRW\"zKg19p\"Gcoi22xb\"3h5WQan.I4EUmЕ1IBofxvJ73hTA2Em\bA97(qOU)1�rV7P"
 			},
 			{
@@ -1974,7 +1774,6 @@
 				"raw": "5528LZ14",
 				"startIndex": 156,
 				"endIndex": 164,
-				"normalized": "5528LZ14",
 				"value": "5528",
 				"unit": "LZ14",
 				"numberType": "integer"
@@ -1984,7 +1783,6 @@
 				"raw": ")",
 				"startIndex": 164,
 				"endIndex": 165,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -1992,7 +1790,6 @@
 				"raw": "䓑gqcRX",
 				"startIndex": 165,
 				"endIndex": 173,
-				"normalized": "䓑gqcRX",
 				"value": "䓑gqcRX"
 			},
 			{
@@ -2000,7 +1797,6 @@
 				"raw": "\"aiu� \"",
 				"startIndex": 173,
 				"endIndex": 182,
-				"normalized": "\"aiu� \"",
 				"value": "aiu� "
 			},
 			{
@@ -2008,7 +1804,6 @@
 				"raw": "z3i74FJ3\u00004x8F-V5b1f(",
 				"startIndex": 182,
 				"endIndex": 202,
-				"normalized": "z3i74FJ3�4x8F-V5b1f(",
 				"value": "z3i74FJ3�4x8F-V5b1f"
 			},
 			{
@@ -2016,7 +1811,6 @@
 				"raw": "U",
 				"startIndex": 202,
 				"endIndex": 203,
-				"normalized": "U",
 				"value": "U"
 			},
 			{
@@ -2024,7 +1818,6 @@
 				"raw": "\u000b",
 				"startIndex": 203,
 				"endIndex": 204,
-				"normalized": "\u000b",
 				"value": "\u000b"
 			},
 			{
@@ -2032,7 +1825,6 @@
 				"raw": " ",
 				"startIndex": 204,
 				"endIndex": 205,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -2040,7 +1832,6 @@
 				"raw": "bUc",
 				"startIndex": 205,
 				"endIndex": 208,
-				"normalized": "bUc",
 				"value": "bUc"
 			}
 		]
@@ -2053,7 +1844,6 @@
 				"raw": "\t",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "\t",
 				"value": null
 			},
 			{
@@ -2061,7 +1851,6 @@
 				"raw": "b6SUejoqAEDa",
 				"startIndex": 1,
 				"endIndex": 13,
-				"normalized": "b6SUejoqAEDa",
 				"value": "b6SUejoqAEDa"
 			},
 			{
@@ -2069,7 +1858,6 @@
 				"raw": "\u000e",
 				"startIndex": 13,
 				"endIndex": 14,
-				"normalized": "\u000e",
 				"value": "\u000e"
 			},
 			{
@@ -2077,7 +1865,6 @@
 				"raw": "9",
 				"startIndex": 14,
 				"endIndex": 15,
-				"normalized": "9",
 				"value": "9",
 				"numberType": "integer"
 			},
@@ -2086,7 +1873,6 @@
 				"raw": ",",
 				"startIndex": 15,
 				"endIndex": 16,
-				"normalized": ",",
 				"value": null
 			},
 			{
@@ -2094,7 +1880,6 @@
 				"raw": "kYO\\",
 				"startIndex": 16,
 				"endIndex": 20,
-				"normalized": "kYO�",
 				"value": "kYO�"
 			}
 		]
@@ -2107,7 +1892,6 @@
 				"raw": "Iv1\u0000B",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "Iv1�B",
 				"value": "Iv1�B"
 			},
 			{
@@ -2115,7 +1899,6 @@
 				"raw": "}",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "}",
 				"value": null
 			},
 			{
@@ -2123,7 +1906,6 @@
 				"raw": "1E",
 				"startIndex": 9,
 				"endIndex": 11,
-				"normalized": "1E",
 				"value": "1",
 				"unit": "E",
 				"numberType": "integer"
@@ -2133,7 +1915,6 @@
 				"raw": "+",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -2141,7 +1922,6 @@
 				"raw": "X9oO",
 				"startIndex": 12,
 				"endIndex": 16,
-				"normalized": "X9oO",
 				"value": "X9oO"
 			},
 			{
@@ -2149,7 +1929,6 @@
 				"raw": "\u001f",
 				"startIndex": 16,
 				"endIndex": 17,
-				"normalized": "\u001f",
 				"value": "\u001f"
 			},
 			{
@@ -2157,7 +1936,6 @@
 				"raw": "N3G",
 				"startIndex": 17,
 				"endIndex": 20,
-				"normalized": "N3G",
 				"value": "N3G"
 			}
 		]
@@ -2170,7 +1948,6 @@
 				"raw": "H",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "H",
 				"value": "H"
 			},
 			{
@@ -2178,7 +1955,6 @@
 				"raw": "%",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "%",
 				"value": "%"
 			},
 			{
@@ -2186,7 +1962,6 @@
 				"raw": "7Zkc0P17",
 				"startIndex": 2,
 				"endIndex": 10,
-				"normalized": "7Zkc0P17",
 				"value": "7",
 				"unit": "Zkc0P17",
 				"numberType": "integer"
@@ -2196,7 +1971,6 @@
 				"raw": " ",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -2204,7 +1978,6 @@
 				"raw": "m2cqKMI5Cz34YPit",
 				"startIndex": 11,
 				"endIndex": 27,
-				"normalized": "m2cqKMI5Cz34YPit",
 				"value": "m2cqKMI5Cz34YPit"
 			},
 			{
@@ -2212,7 +1985,6 @@
 				"raw": ".2",
 				"startIndex": 27,
 				"endIndex": 29,
-				"normalized": ".2",
 				"value": ".2",
 				"numberType": "number"
 			},
@@ -2221,7 +1993,6 @@
 				"raw": ".7",
 				"startIndex": 29,
 				"endIndex": 31,
-				"normalized": ".7",
 				"value": ".7",
 				"numberType": "number"
 			},
@@ -2230,7 +2001,6 @@
 				"raw": ",",
 				"startIndex": 31,
 				"endIndex": 32,
-				"normalized": ",",
 				"value": null
 			},
 			{
@@ -2238,7 +2008,6 @@
 				"raw": "oP",
 				"startIndex": 32,
 				"endIndex": 34,
-				"normalized": "oP",
 				"value": "oP"
 			},
 			{
@@ -2246,7 +2015,6 @@
 				"raw": " ",
 				"startIndex": 34,
 				"endIndex": 35,
-				"normalized": " ",
 				"value": null
 			}
 		]
@@ -2259,7 +2027,6 @@
 				"raw": ">",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ">",
 				"value": ">"
 			},
 			{
@@ -2267,7 +2034,6 @@
 				"raw": "u",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "u",
 				"value": "u"
 			},
 			{
@@ -2275,7 +2041,6 @@
 				"raw": ")",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -2283,7 +2048,6 @@
 				"raw": "k2a76",
 				"startIndex": 3,
 				"endIndex": 8,
-				"normalized": "k2a76",
 				"value": "k2a76"
 			},
 			{
@@ -2291,7 +2055,6 @@
 				"raw": "}",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "}",
 				"value": null
 			},
 			{
@@ -2299,7 +2062,6 @@
 				"raw": "y4\\6fb9ONI\\",
 				"startIndex": 9,
 				"endIndex": 20,
-				"normalized": "y4澹ONI�",
 				"value": "y4澹ONI�"
 			}
 		]
@@ -2312,7 +2074,6 @@
 				"raw": "#1",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "#1",
 				"value": "1"
 			},
 			{
@@ -2320,7 +2081,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2333,7 +2093,6 @@
 				"raw": "#-2",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "#-2",
 				"value": "-2"
 			},
 			{
@@ -2341,7 +2100,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2354,7 +2112,6 @@
 				"raw": "#--3",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "#--3",
 				"value": "--3"
 			},
 			{
@@ -2362,7 +2119,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2375,7 +2131,6 @@
 				"raw": "#---4",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "#---4",
 				"value": "---4"
 			},
 			{
@@ -2383,7 +2138,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2396,7 +2150,6 @@
 				"raw": "#a",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "#a",
 				"value": "a"
 			},
 			{
@@ -2404,7 +2157,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2417,7 +2169,6 @@
 				"raw": "#-b",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "#-b",
 				"value": "-b"
 			},
 			{
@@ -2425,7 +2176,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2438,7 +2188,6 @@
 				"raw": "#--c",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "#--c",
 				"value": "--c"
 			},
 			{
@@ -2446,7 +2195,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2459,7 +2207,6 @@
 				"raw": "#---d",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "#---d",
 				"value": "---d"
 			},
 			{
@@ -2467,7 +2214,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2480,7 +2226,6 @@
 				"raw": "#_",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "#_",
 				"value": "_"
 			},
 			{
@@ -2488,7 +2233,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2501,7 +2245,6 @@
 				"raw": "#_1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "#_1",
 				"value": "_1"
 			},
 			{
@@ -2509,7 +2252,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2522,7 +2264,6 @@
 				"raw": "#-",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "#-",
 				"value": "-"
 			},
 			{
@@ -2530,7 +2271,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2543,7 +2283,6 @@
 				"raw": "#",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "#",
 				"value": "#"
 			},
 			{
@@ -2551,7 +2290,6 @@
 				"raw": "+",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -2559,7 +2297,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2572,7 +2309,6 @@
 				"raw": "#",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "#",
 				"value": "#"
 			},
 			{
@@ -2580,7 +2316,6 @@
 				"raw": "#",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "#",
 				"value": "#"
 			},
 			{
@@ -2588,7 +2323,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2601,7 +2335,6 @@
 				"raw": "#",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "#",
 				"value": "#"
 			}
 		]
@@ -2614,7 +2347,6 @@
 				"raw": "#aa𐀀",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "#aa𐀀",
 				"value": "aa𐀀"
 			},
 			{
@@ -2622,7 +2354,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2635,7 +2366,6 @@
 				"raw": "-",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "-",
 				"value": "-"
 			},
 			{
@@ -2643,7 +2373,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2656,7 +2385,6 @@
 				"raw": "-1",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "-1",
 				"value": "-1",
 				"numberType": "integer"
 			},
@@ -2665,7 +2393,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2678,7 +2405,6 @@
 				"raw": "-.1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-.1",
 				"value": "-.1",
 				"numberType": "number"
 			},
@@ -2687,7 +2413,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2700,7 +2425,6 @@
 				"raw": "--1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "--1",
 				"value": "--1"
 			},
 			{
@@ -2708,7 +2432,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2721,7 +2444,6 @@
 				"raw": "-0",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "-0",
 				"value": "-0",
 				"numberType": "integer"
 			},
@@ -2730,7 +2452,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2743,7 +2464,6 @@
 				"raw": "-->",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-->",
 				"value": null
 			},
 			{
@@ -2751,7 +2471,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2764,7 +2483,6 @@
 				"raw": "foo",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "foo",
 				"value": "foo"
 			},
 			{
@@ -2772,7 +2490,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2785,7 +2502,6 @@
 				"raw": "--",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "--",
 				"value": "--"
 			},
 			{
@@ -2793,7 +2509,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2806,7 +2521,6 @@
 				"raw": "--0",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "--0",
 				"value": "--0"
 			},
 			{
@@ -2814,7 +2528,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2827,7 +2540,6 @@
 				"raw": "-",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "-",
 				"value": "-"
 			},
 			{
@@ -2835,7 +2547,6 @@
 				"raw": "\\",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\\",
 				"value": "\\"
 			},
 			{
@@ -2843,7 +2554,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2856,7 +2566,6 @@
 				"raw": "-\\ ",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "- ",
 				"value": "- "
 			},
 			{
@@ -2864,7 +2573,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2877,7 +2585,6 @@
 				"raw": "--💅",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "--💅",
 				"value": "--💅"
 			},
 			{
@@ -2885,7 +2592,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2898,7 +2604,6 @@
 				"raw": "-§",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-§",
 				"value": "-§"
 			},
 			{
@@ -2906,7 +2611,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2919,7 +2623,6 @@
 				"raw": "-×",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-×",
 				"value": "-×"
 			},
 			{
@@ -2927,7 +2630,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2940,7 +2642,6 @@
 				"raw": "--a𐀀",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "--a𐀀",
 				"value": "--a𐀀"
 			},
 			{
@@ -2948,7 +2649,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2961,7 +2661,6 @@
 				"raw": "url(foo)",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "url(foo)",
 				"value": "foo"
 			},
 			{
@@ -2969,7 +2668,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -2982,7 +2680,6 @@
 				"raw": "\\75 Rl(foo)",
 				"startIndex": 0,
 				"endIndex": 11,
-				"normalized": "uRl(foo)",
 				"value": "foo"
 			},
 			{
@@ -2990,7 +2687,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3003,7 +2699,6 @@
 				"raw": "uR\\6c (foo)",
 				"startIndex": 0,
 				"endIndex": 11,
-				"normalized": "uRl(foo)",
 				"value": "foo"
 			},
 			{
@@ -3011,7 +2706,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3024,7 +2718,6 @@
 				"raw": "url(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "url(",
 				"value": "url"
 			},
 			{
@@ -3032,7 +2725,6 @@
 				"raw": "'foo'",
 				"startIndex": 4,
 				"endIndex": 9,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -3040,7 +2732,6 @@
 				"raw": ")",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -3048,7 +2739,6 @@
 				"raw": "\n",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3061,7 +2751,6 @@
 				"raw": "url(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "url(",
 				"value": "url"
 			},
 			{
@@ -3069,7 +2758,6 @@
 				"raw": " ",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -3077,7 +2765,6 @@
 				"raw": "'foo'",
 				"startIndex": 5,
 				"endIndex": 10,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -3085,7 +2772,6 @@
 				"raw": ")",
 				"startIndex": 10,
 				"endIndex": 11,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -3093,7 +2779,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3106,7 +2791,6 @@
 				"raw": "url(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "url(",
 				"value": "url"
 			},
 			{
@@ -3114,7 +2798,6 @@
 				"raw": "  ",
 				"startIndex": 4,
 				"endIndex": 6,
-				"normalized": "  ",
 				"value": null
 			},
 			{
@@ -3122,7 +2805,6 @@
 				"raw": "'foo'",
 				"startIndex": 6,
 				"endIndex": 11,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -3130,7 +2812,6 @@
 				"raw": ")",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -3138,7 +2819,6 @@
 				"raw": "\n",
 				"startIndex": 12,
 				"endIndex": 13,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3151,7 +2831,6 @@
 				"raw": "url(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "url(",
 				"value": "url"
 			},
 			{
@@ -3159,7 +2838,6 @@
 				"raw": "   ",
 				"startIndex": 4,
 				"endIndex": 7,
-				"normalized": "   ",
 				"value": null
 			},
 			{
@@ -3167,7 +2845,6 @@
 				"raw": "'foo'",
 				"startIndex": 7,
 				"endIndex": 12,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -3175,7 +2852,6 @@
 				"raw": ")",
 				"startIndex": 12,
 				"endIndex": 13,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -3183,7 +2859,6 @@
 				"raw": "\n",
 				"startIndex": 13,
 				"endIndex": 14,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3196,7 +2871,6 @@
 				"raw": "not-url(",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "not-url(",
 				"value": "not-url"
 			},
 			{
@@ -3204,7 +2878,6 @@
 				"raw": "   ",
 				"startIndex": 8,
 				"endIndex": 11,
-				"normalized": "   ",
 				"value": null
 			},
 			{
@@ -3212,7 +2885,6 @@
 				"raw": "'foo'",
 				"startIndex": 11,
 				"endIndex": 16,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -3220,7 +2892,6 @@
 				"raw": ")",
 				"startIndex": 16,
 				"endIndex": 17,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -3228,7 +2899,6 @@
 				"raw": "\n",
 				"startIndex": 17,
 				"endIndex": 18,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3241,7 +2911,6 @@
 				"raw": "url(   foo)",
 				"startIndex": 0,
 				"endIndex": 11,
-				"normalized": "url(   foo)",
 				"value": "foo"
 			},
 			{
@@ -3249,7 +2918,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3262,7 +2930,6 @@
 				"raw": "{",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "{",
 				"value": null
 			},
 			{
@@ -3270,7 +2937,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3283,7 +2949,6 @@
 				"raw": "(",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "(",
 				"value": null
 			},
 			{
@@ -3291,7 +2956,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3304,7 +2968,6 @@
 				"raw": "[",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "[",
 				"value": null
 			},
 			{
@@ -3312,7 +2975,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3325,7 +2987,6 @@
 				"raw": "<",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "<",
 				"value": "<"
 			},
 			{
@@ -3333,7 +2994,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3346,7 +3006,6 @@
 				"raw": "<!--",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "<!--",
 				"value": null
 			},
 			{
@@ -3354,7 +3013,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3367,7 +3025,6 @@
 				"raw": "<",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "<",
 				"value": "<"
 			},
 			{
@@ -3375,7 +3032,6 @@
 				"raw": "--",
 				"startIndex": 1,
 				"endIndex": 3,
-				"normalized": "--",
 				"value": "--"
 			},
 			{
@@ -3383,7 +3039,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3396,7 +3051,6 @@
 				"raw": "<",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "<",
 				"value": "<"
 			},
 			{
@@ -3404,7 +3058,6 @@
 				"raw": "!",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "!",
 				"value": "!"
 			},
 			{
@@ -3412,7 +3065,6 @@
 				"raw": "-",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "-",
 				"value": "-"
 			},
 			{
@@ -3420,7 +3072,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3433,7 +3084,6 @@
 				"raw": "10",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "10",
 				"value": "10",
 				"numberType": "integer"
 			},
@@ -3442,7 +3092,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3455,7 +3104,6 @@
 				"raw": "+10",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "+10",
 				"value": "+10",
 				"numberType": "integer"
 			},
@@ -3464,7 +3112,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3477,7 +3124,6 @@
 				"raw": "-10",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-10",
 				"value": "-10",
 				"numberType": "integer"
 			},
@@ -3486,7 +3132,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3499,7 +3144,6 @@
 				"raw": "0",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "0",
 				"value": "0",
 				"numberType": "integer"
 			},
@@ -3508,7 +3152,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3521,7 +3164,6 @@
 				"raw": "+0",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "+0",
 				"value": "+0",
 				"numberType": "integer"
 			},
@@ -3530,7 +3172,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3543,7 +3184,6 @@
 				"raw": "-0",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "-0",
 				"value": "-0",
 				"numberType": "integer"
 			},
@@ -3552,7 +3192,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3565,7 +3204,6 @@
 				"raw": ".0",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": ".0",
 				"value": ".0",
 				"numberType": "number"
 			},
@@ -3574,7 +3212,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3587,7 +3224,6 @@
 				"raw": ".1",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": ".1",
 				"value": ".1",
 				"numberType": "number"
 			},
@@ -3596,7 +3232,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3609,7 +3244,6 @@
 				"raw": "+.1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "+.1",
 				"value": "+.1",
 				"numberType": "number"
 			},
@@ -3618,7 +3252,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3631,7 +3264,6 @@
 				"raw": "-.1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "-.1",
 				"value": "-.1",
 				"numberType": "number"
 			},
@@ -3640,7 +3272,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3653,7 +3284,6 @@
 				"raw": "1.1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "1.1",
 				"value": "1.1",
 				"numberType": "number"
 			},
@@ -3662,7 +3292,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3675,7 +3304,6 @@
 				"raw": "+1.1",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "+1.1",
 				"value": "+1.1",
 				"numberType": "number"
 			},
@@ -3684,7 +3312,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3697,7 +3324,6 @@
 				"raw": "-1.1",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "-1.1",
 				"value": "-1.1",
 				"numberType": "number"
 			},
@@ -3706,7 +3332,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3719,7 +3344,6 @@
 				"raw": "1.1e2",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "1.1e2",
 				"value": "1.1e2",
 				"numberType": "number"
 			},
@@ -3728,7 +3352,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3741,7 +3364,6 @@
 				"raw": "+1.1e+2",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "+1.1e+2",
 				"value": "+1.1e+2",
 				"numberType": "number"
 			},
@@ -3750,7 +3372,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3763,7 +3384,6 @@
 				"raw": "-1.1e-2",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "-1.1e-2",
 				"value": "-1.1e-2",
 				"numberType": "number"
 			},
@@ -3772,7 +3392,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3785,7 +3404,6 @@
 				"raw": "-1.1e-22",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "-1.1e-22",
 				"value": "-1.1e-22",
 				"numberType": "number"
 			},
@@ -3794,7 +3412,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3807,7 +3424,6 @@
 				"raw": "-1.1e-22e",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "-1.1e-22e",
 				"value": "-1.1e-22",
 				"unit": "e",
 				"numberType": "number"
@@ -3817,7 +3433,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3830,7 +3445,6 @@
 				"raw": "1e",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "1e",
 				"value": "1",
 				"unit": "e",
 				"numberType": "integer"
@@ -3840,7 +3454,6 @@
 				"raw": "+",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -3848,7 +3461,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3861,7 +3473,6 @@
 				"raw": ".2",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": ".2",
 				"value": ".2",
 				"numberType": "number"
 			},
@@ -3870,7 +3481,6 @@
 				"raw": ".7",
 				"startIndex": 2,
 				"endIndex": 4,
-				"normalized": ".7",
 				"value": ".7",
 				"numberType": "number"
 			},
@@ -3879,7 +3489,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3892,7 +3501,6 @@
 				"raw": "-123.753e-2",
 				"startIndex": 0,
 				"endIndex": 11,
-				"normalized": "-123.753e-2",
 				"value": "-123.753e-2",
 				"numberType": "number"
 			},
@@ -3901,7 +3509,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3914,7 +3521,6 @@
 				"raw": "-123.753e-2px",
 				"startIndex": 0,
 				"endIndex": 13,
-				"normalized": "-123.753e-2px",
 				"value": "-123.753e-2",
 				"unit": "px",
 				"numberType": "number"
@@ -3924,7 +3530,6 @@
 				"raw": "\n",
 				"startIndex": 13,
 				"endIndex": 14,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3937,7 +3542,6 @@
 				"raw": "-123.753e-2%",
 				"startIndex": 0,
 				"endIndex": 12,
-				"normalized": "-123.753e-2%",
 				"value": "-123.753e-2"
 			},
 			{
@@ -3945,7 +3549,6 @@
 				"raw": "\n",
 				"startIndex": 12,
 				"endIndex": 13,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3958,7 +3561,6 @@
 				"raw": "1.2",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "1.2",
 				"value": "1.2",
 				"numberType": "number"
 			},
@@ -3967,7 +3569,6 @@
 				"raw": ".3",
 				"startIndex": 3,
 				"endIndex": 5,
-				"normalized": ".3",
 				"value": ".3",
 				"numberType": "number"
 			},
@@ -3976,7 +3577,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -3989,7 +3589,6 @@
 				"raw": "+",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -3997,7 +3596,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4010,7 +3608,6 @@
 				"raw": "+1",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "+1",
 				"value": "+1",
 				"numberType": "integer"
 			},
@@ -4019,7 +3616,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4032,7 +3628,6 @@
 				"raw": "+.1",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "+.1",
 				"value": "+.1",
 				"numberType": "number"
 			},
@@ -4041,7 +3636,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4054,7 +3648,6 @@
 				"raw": "+",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "+",
 				"value": "+"
 			},
 			{
@@ -4062,7 +3655,6 @@
 				"raw": "+1",
 				"startIndex": 1,
 				"endIndex": 3,
-				"normalized": "+1",
 				"value": "+1",
 				"numberType": "integer"
 			},
@@ -4071,7 +3663,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4084,7 +3675,6 @@
 				"raw": "\\",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "\\",
 				"value": "\\"
 			},
 			{
@@ -4092,7 +3682,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4105,7 +3694,6 @@
 				"raw": "\\#",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "#",
 				"value": "#"
 			},
 			{
@@ -4113,7 +3701,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4126,7 +3713,6 @@
 				"raw": "\\ ",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": " ",
 				"value": " "
 			},
 			{
@@ -4134,7 +3720,6 @@
 				"raw": "\n",
 				"startIndex": 2,
 				"endIndex": 3,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4147,7 +3732,6 @@
 				"raw": "\\61 b",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "ab",
 				"value": "ab"
 			},
 			{
@@ -4155,7 +3739,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4168,7 +3751,6 @@
 				"raw": "\\",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "�",
 				"value": "�"
 			}
 		]
@@ -4181,7 +3763,6 @@
 				"raw": "}",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "}",
 				"value": null
 			},
 			{
@@ -4189,7 +3770,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4202,7 +3782,6 @@
 				"raw": ")",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -4210,7 +3789,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4223,7 +3801,6 @@
 				"raw": "]",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "]",
 				"value": null
 			},
 			{
@@ -4231,7 +3808,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4244,7 +3820,6 @@
 				"raw": ";",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": ";",
 				"value": null
 			},
 			{
@@ -4252,7 +3827,6 @@
 				"raw": "\n",
 				"startIndex": 1,
 				"endIndex": 2,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4265,7 +3839,6 @@
 				"raw": "\"foo\"",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "\"foo\"",
 				"value": "foo"
 			},
 			{
@@ -4273,7 +3846,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -4281,7 +3853,6 @@
 				"raw": "'foo'",
 				"startIndex": 6,
 				"endIndex": 11,
-				"normalized": "'foo'",
 				"value": "foo"
 			},
 			{
@@ -4289,7 +3860,6 @@
 				"raw": "\n",
 				"startIndex": 11,
 				"endIndex": 12,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4302,7 +3872,6 @@
 				"raw": "\"foo",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "\"foo",
 				"value": "foo"
 			}
 		]
@@ -4315,7 +3884,6 @@
 				"raw": "\"fo",
 				"startIndex": 0,
 				"endIndex": 3,
-				"normalized": "\"fo",
 				"value": null
 			},
 			{
@@ -4323,7 +3891,6 @@
 				"raw": "\n",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -4331,7 +3898,6 @@
 				"raw": "o",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "o",
 				"value": "o"
 			},
 			{
@@ -4339,7 +3905,6 @@
 				"raw": "\"",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\"",
 				"value": ""
 			}
 		]
@@ -4352,7 +3917,6 @@
 				"raw": "\"fo\\\no\"",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "\"foo\"",
 				"value": "foo"
 			},
 			{
@@ -4360,7 +3924,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4373,7 +3936,6 @@
 				"raw": "\"fo\\",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "\"fo",
 				"value": "fo"
 			}
 		]
@@ -4386,7 +3948,6 @@
 				"raw": "\"esc\\61 ped\"",
 				"startIndex": 0,
 				"endIndex": 12,
-				"normalized": "\"escaped\"",
 				"value": "escaped"
 			},
 			{
@@ -4394,7 +3955,6 @@
 				"raw": "\n",
 				"startIndex": 12,
 				"endIndex": 13,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4407,7 +3967,6 @@
 				"raw": "\"foo\\\"",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "\"foo\"",
 				"value": "foo\""
 			}
 		]
@@ -4420,7 +3979,6 @@
 				"raw": "\"'foo'\"",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "\"'foo'\"",
 				"value": "'foo'"
 			},
 			{
@@ -4428,7 +3986,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -4436,7 +3993,6 @@
 				"raw": "'\"foo\"'",
 				"startIndex": 8,
 				"endIndex": 15,
-				"normalized": "'\"foo\"'",
 				"value": "\"foo\""
 			},
 			{
@@ -4444,7 +4000,6 @@
 				"raw": "\n",
 				"startIndex": 15,
 				"endIndex": 16,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4457,7 +4012,6 @@
 				"raw": "\"\\\"foo\\\"\"",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "\"\"foo\"\"",
 				"value": "\"foo\""
 			},
 			{
@@ -4465,7 +4019,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			},
 			{
@@ -4473,7 +4026,6 @@
 				"raw": "'\\'foo\\''",
 				"startIndex": 10,
 				"endIndex": 19,
-				"normalized": "''foo''",
 				"value": "'foo'"
 			},
 			{
@@ -4481,7 +4033,6 @@
 				"raw": "\n",
 				"startIndex": 19,
 				"endIndex": 20,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4494,7 +4045,6 @@
 				"raw": "url(\n",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "url(\n",
 				"value": ""
 			}
 		]
@@ -4507,7 +4057,6 @@
 				"raw": "url(a\n",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "url(a\n",
 				"value": "a"
 			}
 		]
@@ -4520,7 +4069,6 @@
 				"raw": "url( a\n",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "url( a\n",
 				"value": "a"
 			}
 		]
@@ -4533,7 +4081,6 @@
 				"raw": "url()",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "url()",
 				"value": ""
 			},
 			{
@@ -4541,7 +4088,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4554,7 +4100,6 @@
 				"raw": "url( )",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "url( )",
 				"value": ""
 			},
 			{
@@ -4562,7 +4107,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4575,7 +4119,6 @@
 				"raw": "url( a)",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "url( a)",
 				"value": "a"
 			},
 			{
@@ -4583,7 +4126,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4596,7 +4138,6 @@
 				"raw": "url( a )",
 				"startIndex": 0,
 				"endIndex": 8,
-				"normalized": "url( a )",
 				"value": "a"
 			},
 			{
@@ -4604,7 +4145,6 @@
 				"raw": "\n",
 				"startIndex": 8,
 				"endIndex": 9,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4617,7 +4157,6 @@
 				"raw": "url( \\) )",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "url( ) )",
 				"value": ")"
 			},
 			{
@@ -4625,7 +4164,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4638,7 +4176,6 @@
 				"raw": "url(https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org)",
 				"startIndex": 0,
 				"endIndex": 212,
-				"normalized": "url(https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org)",
 				"value": "https://https:⁄⁄www.netmeister.org@https://www.netmeister.org/https:⁄⁄www.netmeister.org⁄?https://www.netmeister.org=https://www.netmeister.org;https://www.netmeister.org#https://www.netmeister.org"
 			},
 			{
@@ -4646,7 +4183,6 @@
 				"raw": "\n",
 				"startIndex": 212,
 				"endIndex": 213,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4659,7 +4195,6 @@
 				"raw": "url(https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_\\)\\(*&^#top)",
 				"startIndex": 0,
 				"endIndex": 94,
-				"normalized": "url(https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_)(*&^#top)",
 				"value": "https://www.netmeister.org/%62%6C%6F%67/%75%72%6C%73%2E%68%74%6D%6C?!@#$%25=+_)(*&^#top"
 			},
 			{
@@ -4667,7 +4202,6 @@
 				"raw": "\n",
 				"startIndex": 94,
 				"endIndex": 95,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4680,7 +4214,6 @@
 				"raw": "Url(a)",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "Url(a)",
 				"value": "a"
 			},
 			{
@@ -4688,7 +4221,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4701,7 +4233,6 @@
 				"raw": "uRl(a)",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "uRl(a)",
 				"value": "a"
 			},
 			{
@@ -4709,7 +4240,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4722,7 +4252,6 @@
 				"raw": "urL(a)",
 				"startIndex": 0,
 				"endIndex": 6,
-				"normalized": "urL(a)",
 				"value": "a"
 			},
 			{
@@ -4730,7 +4259,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4743,7 +4271,6 @@
 				"raw": "uri(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "uri(",
 				"value": "uri"
 			},
 			{
@@ -4751,7 +4278,6 @@
 				"raw": "a",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -4759,7 +4285,6 @@
 				"raw": ")",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -4767,7 +4292,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4780,7 +4304,6 @@
 				"raw": "uul(",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "uul(",
 				"value": "uul"
 			},
 			{
@@ -4788,7 +4311,6 @@
 				"raw": "a",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -4796,7 +4318,6 @@
 				"raw": ")",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": ")",
 				"value": null
 			},
 			{
@@ -4804,7 +4325,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4817,7 +4337,6 @@
 				"raw": "\n",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4830,7 +4349,6 @@
 				"raw": " \n",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": " \n",
 				"value": null
 			}
 		]
@@ -4843,7 +4361,6 @@
 				"raw": "a",
 				"startIndex": 0,
 				"endIndex": 1,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -4851,7 +4368,6 @@
 				"raw": "  ",
 				"startIndex": 1,
 				"endIndex": 3,
-				"normalized": "  ",
 				"value": null
 			},
 			{
@@ -4859,7 +4375,6 @@
 				"raw": "b",
 				"startIndex": 3,
 				"endIndex": 4,
-				"normalized": "b",
 				"value": "b"
 			},
 			{
@@ -4867,7 +4382,6 @@
 				"raw": "\n",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4880,7 +4394,6 @@
 				"raw": "\\61 b",
 				"startIndex": 0,
 				"endIndex": 5,
-				"normalized": "ab",
 				"value": "ab"
 			},
 			{
@@ -4888,7 +4401,6 @@
 				"raw": "\n",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4901,7 +4413,6 @@
 				"raw": "\\000061 b",
 				"startIndex": 0,
 				"endIndex": 9,
-				"normalized": "ab",
 				"value": "ab"
 			},
 			{
@@ -4909,7 +4420,6 @@
 				"raw": "\n",
 				"startIndex": 9,
 				"endIndex": 10,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4922,7 +4432,6 @@
 				"raw": "\\61 ",
 				"startIndex": 0,
 				"endIndex": 4,
-				"normalized": "a",
 				"value": "a"
 			},
 			{
@@ -4930,7 +4439,6 @@
 				"raw": " ",
 				"startIndex": 4,
 				"endIndex": 5,
-				"normalized": " ",
 				"value": null
 			},
 			{
@@ -4938,7 +4446,6 @@
 				"raw": "b",
 				"startIndex": 5,
 				"endIndex": 6,
-				"normalized": "b",
 				"value": "b"
 			},
 			{
@@ -4946,7 +4453,6 @@
 				"raw": "\n",
 				"startIndex": 6,
 				"endIndex": 7,
-				"normalized": "\n",
 				"value": null
 			}
 		]
@@ -4959,7 +4465,6 @@
 				"raw": "\t\n",
 				"startIndex": 0,
 				"endIndex": 2,
-				"normalized": "\t\n",
 				"value": null
 			}
 		]
@@ -4972,7 +4477,6 @@
 				"raw": "f\\ o\\\to",
 				"startIndex": 0,
 				"endIndex": 7,
-				"normalized": "f o\to",
 				"value": "f o\to"
 			},
 			{
@@ -4980,7 +4484,6 @@
 				"raw": "\n",
 				"startIndex": 7,
 				"endIndex": 8,
-				"normalized": "\n",
 				"value": null
 			}
 		]
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index f372a4f780ce5..8e9b2b1d1ba1b 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -12,8 +12,7 @@ class Tests_CssApi_WpCssTokenProcessor extends WP_UnitTestCase {
 	 * @dataProvider corpus_provider
 	 */
 	public function test_processor_matches_spec( string $css, array $expected_tokens ): void {
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor );
+		$actual_tokens = $this->collect_tokens( $css );
 		$this->assertSame( $expected_tokens, $actual_tokens );
 	}
 
@@ -28,13 +27,15 @@ public static function corpus_provider(): array {
 	}
 
 	/**
-	 * Collects all tokens from a CSS processor into an array.
+	 * Tokenizes CSS and collects every token into an array.
 	 *
-	 * @param WP_CSS_Token_Processor $processor The CSS processor.
-	 * @return array Array of tokens with type, raw, startIndex, endIndex, structured.
+	 * @param string        $css  CSS to tokenize.
+	 * @param string[]|null $keys Optional. Keys to keep on each token. Default all.
+	 * @return array Array of tokens with type, raw, startIndex, endIndex, value, unit and numberType.
 	 */
-	public static function collect_tokens( WP_CSS_Token_Processor $processor, $keys = null ): array {
-		$tokens = array();
+	public static function collect_tokens( string $css, ?array $keys = null ): array {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$tokens    = array();
 
 		while ( $processor->next_token() ) {
 			$type = $processor->get_token_type();
@@ -44,20 +45,19 @@ public static function collect_tokens( WP_CSS_Token_Processor $processor, $keys
 
 			$token = array(
 				'type'       => $type,
-				'raw'        => $processor->get_unnormalized_token(),
+				'raw'        => substr( $css, $byte_start, $processor->get_token_length() ),
 				'startIndex' => $byte_start,
 				'endIndex'   => $byte_end,
-				'normalized' => $processor->get_normalized_token(),
-				'value'      => $processor->get_token_value(),
+				'value'      => $processor->get_token()->get_value(),
 			);
-			if ( null !== $processor->get_token_unit() ) {
-				$token['unit'] = $processor->get_token_unit();
+			if ( null !== $processor->get_token()->get_unit() ) {
+				$token['unit'] = $processor->get_token()->get_unit();
 			}
 			if (
 				WP_CSS_Token_Processor::TOKEN_NUMBER === $type ||
 				WP_CSS_Token_Processor::TOKEN_DIMENSION === $type
 			) {
-				$token['numberType'] = $processor->get_token_type_flag();
+				$token['numberType'] = $processor->get_token()->get_flag();
 			}
 
 			if ( null !== $keys ) {
@@ -81,7 +81,7 @@ public function test_string_backslash_newline( string $css, string $expected_val
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$this->assertSame( $expected_value, $processor->get_token_value() );
+		$this->assertSame( $expected_value, $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -108,7 +108,7 @@ public function test_string_backslash_eof(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$this->assertSame( 'string', $processor->get_token_value() );
+		$this->assertSame( 'string', $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -148,7 +148,7 @@ public function test_url_backslash_eof(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_URL, $processor->get_token_type() );
-		$this->assertSame( "string\u{FFFD}", $processor->get_token_value() );
+		$this->assertSame( "string\u{FFFD}", $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -165,8 +165,7 @@ public function test_preprocessed_token_keeps_source_bytes( string $css, string
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( $expected_type, $processor->get_token_type() );
-		$this->assertSame( $expected_value, $processor->get_token_value() );
-		$this->assertSame( $css, $processor->get_unnormalized_token() );
+		$this->assertSame( $expected_value, $processor->get_token()->get_value() );
 		$this->assertSame( 0, $processor->get_token_start() );
 		$this->assertSame( strlen( $css ), $processor->get_token_length() );
 		$this->assertFalse( $processor->next_token() );
@@ -213,7 +212,7 @@ public function test_ident_backslash_newline( string $css ): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
-		$this->assertSame( 'abc', $processor->get_token_value() );
+		$this->assertSame( 'abc', $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -240,7 +239,7 @@ public function test_ident_backslash_eof(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
-		$this->assertSame( "abc\u{FFFD}", $processor->get_token_value() );
+		$this->assertSame( "abc\u{FFFD}", $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -253,24 +252,24 @@ public function test_bad_string_token_value_is_null(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
-		$this->assertNull( $processor->get_token_value() );
+		$this->assertNull( $processor->get_token()->get_value() );
 	}
 
 	/**
-	 * Tests that is_token_terminated() reports whether the last token ended at its closing delimiter.
+	 * Tests that WP_CSS_Token::is_terminated() reports whether the last token ended at its closing delimiter.
 	 *
 	 * @ticket 65738
-	 * @dataProvider data_is_token_terminated
+	 * @dataProvider data_is_terminated
 	 */
-	public function test_is_token_terminated( string $css, string $expected_type, bool $expected ): void {
+	public function test_is_terminated( string $css, string $expected_type, bool $expected ): void {
 		$processor = WP_CSS_Token_Processor::create( $css );
 
-		$this->assertFalse( $processor->is_token_terminated(), 'Before the first token there is nothing to report.' );
+		$this->assertNull( $processor->get_token(), 'Before the first token there is nothing to report.' );
 
 		$type = null;
 		while ( $processor->next_token() ) {
 			$type       = $processor->get_token_type();
-			$terminated = $processor->is_token_terminated();
+			$terminated = $processor->get_token()->is_terminated();
 		}
 
 		$this->assertSame( $expected_type, $type, 'The last token type did not match.' );
@@ -278,11 +277,11 @@ public function test_is_token_terminated( string $css, string $expected_type, bo
 	}
 
 	/**
-	 * Data provider for test_is_token_terminated().
+	 * Data provider for test_is_terminated().
 	 *
 	 * @return array[]
 	 */
-	public static function data_is_token_terminated(): array {
+	public static function data_is_terminated(): array {
 		return array(
 			'comment terminated'                 => array( '/* a */', WP_CSS_Token_Processor::TOKEN_COMMENT, true ),
 			'comment empty terminated'           => array( '/**/', WP_CSS_Token_Processor::TOKEN_COMMENT, true ),
@@ -312,24 +311,24 @@ public static function data_is_token_terminated(): array {
 	}
 
 	/**
-	 * Tests that is_token_terminated() is reset for the token after an unterminated one.
+	 * Tests that WP_CSS_Token::is_terminated() is reset for the token after an unterminated one.
 	 *
 	 * @ticket 65738
 	 */
-	public function test_is_token_terminated_resets_between_tokens(): void {
+	public function test_is_terminated_resets_between_tokens(): void {
 		$processor = WP_CSS_Token_Processor::create( "'a\nb" );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
-		$this->assertTrue( $processor->is_token_terminated() );
+		$this->assertTrue( $processor->get_token()->is_terminated() );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_WHITESPACE, $processor->get_token_type() );
-		$this->assertTrue( $processor->is_token_terminated() );
+		$this->assertTrue( $processor->get_token()->is_terminated() );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
-		$this->assertTrue( $processor->is_token_terminated() );
+		$this->assertTrue( $processor->get_token()->is_terminated() );
 	}
 
 	/**
@@ -344,12 +343,12 @@ public function test_hash_tokens_expose_type_flags( string $css, array $expected
 		foreach ( $expected_tokens as $expected_token ) {
 			$this->assertTrue( $processor->next_token() );
 			$this->assertSame( $expected_token['type'], $processor->get_token_type() );
-			$this->assertSame( $expected_token['raw'], $processor->get_unnormalized_token() );
-			$this->assertSame( $expected_token['type_flag'], $processor->get_token_type_flag() );
+			$this->assertSame( $expected_token['raw'], substr( $css, $processor->get_token_start(), $processor->get_token_length() ) );
+			$this->assertSame( $expected_token['type_flag'], $processor->get_token()->get_flag() );
 		}
 
 		$this->assertFalse( $processor->next_token() );
-		$this->assertNull( $processor->get_token_type_flag() );
+		$this->assertNull( $processor->get_token() );
 	}
 
 	/**
@@ -451,7 +450,7 @@ public function test_token_type_flag( string $css, ?string $expected_type ): voi
 		$processor = WP_CSS_Token_Processor::create( $css );
 
 		$this->assertTrue( $processor->next_token() );
-		$this->assertSame( $expected_type, $processor->get_token_type_flag() );
+		$this->assertSame( $expected_type, $processor->get_token()->get_flag() );
 	}
 
 	/**
@@ -495,21 +494,18 @@ public function test_non_utf8_sequences_in_identifiers(): void {
 		$expected = array(
 			// .class�name (0xF1 replaced with U+FFFD).
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => "class\xF1name",
-				'normalized' => 'class�name',
-				'value'      => 'class�name',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => "class\xF1name",
+				'value' => 'class�name',
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value', 'unit' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value', 'unit' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -529,8 +525,7 @@ public function test_invalid_utf8_in_normal_segment_combined_with_escape(): void
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -550,8 +545,7 @@ public function test_invalid_utf8_as_escaped_character(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -561,21 +555,18 @@ public function test_invalid_utf8_with_valid_prefix_in_identifiers(): void {
 
 		$expected = array(
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => "test\xE2\x80name",
-				'normalized' => 'test�name',
-				'value'      => 'test�name',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => "test\xE2\x80name",
+				'value' => 'test�name',
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -586,21 +577,18 @@ public function test_invalid_utf8_with_two_single_byte_invalid_sequences(): void
 
 		$expected = array(
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => "test\xE2\xE2name",
-				'normalized' => 'test��name',
-				'value'      => 'test��name',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => "test\xE2\xE2name",
+				'value' => 'test��name',
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -713,8 +701,7 @@ public function test_tokenize_labels_core_tokens(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -795,8 +782,7 @@ public function test_complex_selector_with_pseudo_classes(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -873,8 +859,7 @@ public function test_css_comments(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -971,8 +956,7 @@ public function test_media_query(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1109,8 +1093,7 @@ public function test_keyframes_animation(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1175,8 +1158,7 @@ public function test_vendor_prefixed_properties(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1261,8 +1243,7 @@ public function test_attribute_selectors(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1351,8 +1332,7 @@ public function test_calc_function(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1485,8 +1465,7 @@ public function test_color_functions(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1551,8 +1530,7 @@ public function test_css_variables(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1641,8 +1619,7 @@ public function test_gradient_functions(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1727,8 +1704,7 @@ public function test_grid_layout(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1801,8 +1777,7 @@ public function test_url_formats(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1883,8 +1858,7 @@ public function test_important_declarations(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -1957,8 +1931,7 @@ public function test_complex_combinators(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
@@ -2031,13 +2004,12 @@ public function test_escaped_identifiers(): void {
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw' ) );
 		$this->assertSame( $actual_tokens, $expected );
 	}
 
 	/**
-	 * Tests that get_normalized_token() applies CSS normalization.
+	 * Tests that token values are decoded and normalized.
 	 *
 	 * Uses a comprehensive CSS selector with rules that includes:
 	 * - CSS escapes in class names and IDs
@@ -2047,7 +2019,7 @@ public function test_escaped_identifiers(): void {
 	 * - Null bytes in identifiers
 	 * - Mixed line endings (\r\n, \r, \f) that need normalization
 	 */
-	public function test_get_normalized_token_applies_normalization(): void {
+	public function test_token_values_are_decoded_and_normalized(): void {
 		// Comprehensive CSS with normalization requirements.
 		$css = "/* Comment\r\nwith\flines */\r\n" .
 				".c\\6c ass.n\\61 me\r#id\\@value\r\n{\r\n" .
@@ -2058,200 +2030,175 @@ public function test_get_normalized_token_applies_normalization(): void {
 		$expected = array(
 			// Comment with \r\n and \f.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COMMENT,
-				'raw'        => "/* Comment\r\nwith\flines */",
-				'normalized' => "/* Comment\nwith\nlines */",
-				'value'      => " Comment\nwith\nlines ",
+				'type'  => WP_CSS_Token_Processor::TOKEN_COMMENT,
+				'raw'   => "/* Comment\r\nwith\flines */",
+				'value' => " Comment\nwith\nlines ",
 			),
 			// Whitespace with \r\n.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r\n",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r\n",
+				'value' => null,
 			),
 			// Class selector delimiter.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			// Class name with escape (\6c = 'l'), space gets consumed by escape.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'c\\6c ass',
-				'normalized' => 'class', // Escapes decoded.
-				'value'      => 'class', // Decoded: \6c → l, space consumed.
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'c\\6c ass',
+				'value' => 'class', // Decoded: \6c → l, space consumed.
 			),
 			// Delimiter.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			// Identifier with escape (\61 = 'a'), space gets consumed.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'n\\61 me',
-				'normalized' => 'name', // Escapes decoded.
-				'value'      => 'name', // Decoded: \61 → a, space consumed.
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'n\\61 me',
+				'value' => 'name', // Decoded: \61 → a, space consumed.
 			),
 			// Whitespace with \r.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r",
+				'value' => null,
 			),
 			// ID selector with escape.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_HASH,
-				'raw'        => '#id\\@value',
-				'normalized' => '#id@value', // Escapes decoded.
-				'value'      => 'id@value', // Decoded value.
+				'type'  => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'   => '#id\\@value',
+				'value' => 'id@value', // Decoded value.
 			),
 			// Whitespace with \r\n.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r\n",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r\n",
+				'value' => null,
 			),
 			// Opening brace.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
-				'raw'        => '{',
-				'normalized' => '{',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'   => '{',
+				'value' => null,
 			),
 			// Whitespace with \r\n and tab (consumed together).
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r\n\t",
-				'normalized' => "\n\t",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r\n\t",
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'background',
-				'normalized' => 'background',
-				'value'      => 'background',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'background',
+				'value' => 'background',
 			),
 			// Colon.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			// Whitespace with \f.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\f",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\f",
+				'value' => null,
 			),
 			// URL token with escapes (entire url(...) is one token).
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_URL,
-				'raw'        => 'url(path\\2f to\\2f image.png)',
-				'normalized' => 'url(path/to/image.png)', // Escapes decoded.
-				'value'      => 'path/to/image.png', // Decoded: \2f → /, spaces consumed.
+				'type'  => WP_CSS_Token_Processor::TOKEN_URL,
+				'raw'   => 'url(path\\2f to\\2f image.png)',
+				'value' => 'path/to/image.png', // Decoded: \2f → /, spaces consumed.
 			),
 			// Semicolon.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			// Whitespace with \r\n and tab (consumed together).
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r\n\t",
-				'normalized' => "\n\t",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r\n\t",
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'content',
-				'normalized' => 'content',
-				'value'      => 'content',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'content',
+				'value' => 'content',
 			),
 			// Colon.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			// Whitespace with \r.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r",
+				'value' => null,
 			),
 			// String with escape (\A = newline, space consumed).
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
-				'raw'        => '"text\\A string"',
-				'normalized' => "\"text\nstring\"", // Escapes decoded, quotes preserved.
-				'value'      => "text\nstring", // \A → \n, space consumed.
+				'type'  => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'   => '"text\\A string"',
+				'value' => "text\nstring", // \A → \n, space consumed.
 			),
 			// Semicolon.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			// Whitespace with \r\n.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => "\r\n",
-				'normalized' => "\n",
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => "\r\n",
+				'value' => null,
 			),
 			// Closing brace.
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
-				'raw'        => '}',
-				'normalized' => '}',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'   => '}',
+				'value' => null,
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
 	/**
-	 * Tests that get_normalized_token() does not decode escapes in a comment.
+	 * Tests that a comment value keeps its escapes.
 	 *
 	 * @ticket 65738
-	 * @dataProvider data_normalized_comment
+	 * @dataProvider data_comment_value
 	 */
-	public function test_get_normalized_token_keeps_comment_escapes( string $css, string $expected ): void {
+	public function test_comment_value_keeps_escapes( string $css, string $expected ): void {
 		$processor = WP_CSS_Token_Processor::create( $css );
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_COMMENT, $processor->get_token_type() );
 
-		$this->assertSame( $expected, $processor->get_normalized_token() );
+		$this->assertSame( $expected, $processor->get_token()->get_value() );
 	}
 
 	/**
-	 * Data provider for test_get_normalized_token_keeps_comment_escapes().
+	 * Data provider for test_comment_value_keeps_escapes().
 	 *
 	 * @return array[]
 	 */
-	public static function data_normalized_comment(): array {
+	public static function data_comment_value(): array {
 		return array(
-			'escape'                => array( '/* \\41 */', '/* \\41 */' ),
-			'newlines preprocessed' => array( "/*\\41\r\n\f*/", "/*\\41\n\n*/" ),
+			'escape'                => array( '/* \\41 */', ' \\41 ' ),
+			'newlines preprocessed' => array( "/*\\41\r\n\f*/", "\\41\n\n" ),
 		);
 	}
 
@@ -2259,85 +2206,72 @@ public function test_dimension_token_value(): void {
 		$css           = '10px;15em;20%;30pt;40pc;50vw;';
 		$expected      = array(
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '10px',
-				'normalized' => '10px',
-				'value'      => '10',
-				'unit'       => 'px',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '10px',
+				'value' => '10',
+				'unit'  => 'px',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '15em',
-				'normalized' => '15em',
-				'value'      => '15',
-				'unit'       => 'em',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '15em',
+				'value' => '15',
+				'unit'  => 'em',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
-				'raw'        => '20%',
-				'normalized' => '20%',
-				'value'      => '20',
+				'type'  => WP_CSS_Token_Processor::TOKEN_PERCENTAGE,
+				'raw'   => '20%',
+				'value' => '20',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '30pt',
-				'normalized' => '30pt',
-				'value'      => '30',
-				'unit'       => 'pt',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '30pt',
+				'value' => '30',
+				'unit'  => 'pt',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '40pc',
-				'normalized' => '40pc',
-				'value'      => '40',
-				'unit'       => 'pc',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '40pc',
+				'value' => '40',
+				'unit'  => 'pc',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '50vw',
-				'normalized' => '50vw',
-				'value'      => '50',
-				'unit'       => 'vw',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '50vw',
+				'value' => '50',
+				'unit'  => 'vw',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 		);
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value', 'unit' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value', 'unit' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -2400,318 +2334,268 @@ public function test_escape_sequences_in_unusual_places() {
 		$expected = array(
 			// @\6D edia -> @media
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
-				'raw'        => '@\\6D edia',
-				'normalized' => '@media',
-				'value'      => 'media',
+				'type'  => WP_CSS_Token_Processor::TOKEN_AT_KEYWORD,
+				'raw'   => '@\\6D edia',
+				'value' => 'media',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// \73 creen -> screen
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => '\\73 creen',
-				'normalized' => 'screen',
-				'value'      => 'screen',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => '\\73 creen',
+				'value' => 'screen',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
-				'raw'        => '{',
-				'normalized' => '{',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'   => '{',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// Delimiter .
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DELIM,
-				'raw'        => '.',
-				'normalized' => '.',
-				'value'      => '.',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DELIM,
+				'raw'   => '.',
+				'value' => '.',
 			),
 			// \63 l\61 ss\5F name -> class_name
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => '\\63 l\\61 ss\\5F name',
-				'normalized' => 'class_name',
-				'value'      => 'class_name',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => '\\63 l\\61 ss\\5F name',
+				'value' => 'class_name',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// #\69 d\5C 0test -> #id\0test (with encoded null byte)
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_HASH,
-				'raw'        => "#\\69 d\\5C 0test\x00",
-				'normalized' => "#id\\0test�",
+				'type'  => WP_CSS_Token_Processor::TOKEN_HASH,
+				'raw'   => "#\\69 d\\5C 0test\x00",
 				// Ensure the value is normalized.
-				'value'      => "id\\0test�",
+				'value' => "id\\0test�",
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
-				'raw'        => '{',
-				'normalized' => '{',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_LEFT_BRACE,
+				'raw'   => '{',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// c\6F lor -> color
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'c\\6F lor',
-				'normalized' => 'color',
-				'value'      => 'color',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'c\\6F lor',
+				'value' => 'color',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// r\65 d -> red
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'r\\65 d',
-				'normalized' => 'red',
-				'value'      => 'red',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'r\\65 d',
+				'value' => 'red',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// \21 important -> !important (single identifier with escaped !)
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => '\\21 important',
-				'normalized' => '!important',
-				'value'      => '!important',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => '\\21 important',
+				'value' => '!important',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// w\69 dth -> width
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'w\\69 dth',
-				'normalized' => 'width',
-				'value'      => 'width',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'w\\69 dth',
+				'value' => 'width',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// 10\70 x -> 10px (dimension with escaped unit)
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_DIMENSION,
-				'raw'        => '10\\70 x',
-				'normalized' => '10px',
-				'value'      => '10',
+				'type'  => WP_CSS_Token_Processor::TOKEN_DIMENSION,
+				'raw'   => '10\\70 x',
+				'value' => '10',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'background',
-				'normalized' => 'background',
-				'value'      => 'background',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'background',
+				'value' => 'background',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// \75 rl( -> url( (escaped function name)
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_FUNCTION,
-				'raw'        => '\\75 rl(',
-				'normalized' => 'url(',
-				'value'      => 'url',
+				'type'  => WP_CSS_Token_Processor::TOKEN_FUNCTION,
+				'raw'   => '\\75 rl(',
+				'value' => 'url',
 			),
 			// String with escapes: "p\61 th\2F img\2E png"
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
-				'raw'        => '"p\\61 th\\2F img\\2E png"',
-				'normalized' => '"path/img.png"',
-				'value'      => 'path/img.png',
+				'type'  => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'   => '"p\\61 th\\2F img\\2E png"',
+				'value' => 'path/img.png',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
-				'raw'        => ')',
-				'normalized' => ')',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN,
+				'raw'   => ')',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'content',
-				'normalized' => 'content',
-				'value'      => 'content',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'content',
+				'value' => 'content',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// String with escaped backslashes: "\5C \5C " -> "\\"
 			// Each \5C sequence (with trailing space consumed) becomes one backslash
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_STRING,
-				'raw'        => '"\\5C \\5C "',
-				'normalized' => '"\\\\"',
-				'value'      => '\\\\',  // Two backslashes total
+				'type'  => WP_CSS_Token_Processor::TOKEN_STRING,
+				'raw'   => '"\\5C \\5C "',
+				'value' => '\\\\',  // Two backslashes total
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => 'font-family',
-				'normalized' => 'font-family',
-				'value'      => 'font-family',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => 'font-family',
+				'value' => 'font-family',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_COLON,
-				'raw'        => ':',
-				'normalized' => ':',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_COLON,
+				'raw'   => ':',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			// \22 Arial\22 -> "Arial" (escaped quotes make it an ident)
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_IDENT,
-				'raw'        => '\\22 Arial\\22 ',
-				'normalized' => '"Arial"',
-				'value'      => '"Arial"',
+				'type'  => WP_CSS_Token_Processor::TOKEN_IDENT,
+				'raw'   => '\\22 Arial\\22 ',
+				'value' => '"Arial"',
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
-				'raw'        => ';',
-				'normalized' => ';',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_SEMICOLON,
+				'raw'   => ';',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
-				'raw'        => ' ',
-				'normalized' => ' ',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_WHITESPACE,
+				'raw'   => ' ',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
-				'raw'        => '}',
-				'normalized' => '}',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'   => '}',
+				'value' => null,
 			),
 			array(
-				'type'       => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
-				'raw'        => '}',
-				'normalized' => '}',
-				'value'      => null,
+				'type'  => WP_CSS_Token_Processor::TOKEN_RIGHT_BRACE,
+				'raw'   => '}',
+				'value' => null,
 			),
 		);
 
-		$processor     = WP_CSS_Token_Processor::create( $css );
-		$actual_tokens = $this->collect_tokens( $processor, array( 'type', 'raw', 'normalized', 'value' ) );
+		$actual_tokens = $this->collect_tokens( $css, array( 'type', 'raw', 'value' ) );
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
@@ -2726,8 +2610,7 @@ public function test_decode_range_respects_length_boundary(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$this->assertSame( 'helloAworld', $processor->get_token_value() );
-		$this->assertSame( '"helloAworld"', $processor->get_normalized_token() );
+		$this->assertSame( 'helloAworld', $processor->get_token()->get_value() );
 	}
 
 	/**
@@ -2740,15 +2623,14 @@ public function test_decode_escape_at_hex_limit_is_six_digits(): void {
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
-		$this->assertSame( 'A1rest', $processor->get_token_value() );
+		$this->assertSame( 'A1rest', $processor->get_token()->get_value() );
 	}
 
 	/**
 	 * Test bounds check when consuming and ident start token.
 	 */
 	public function test_ident_start_codepoint_bounds_check(): void {
-		$processor       = WP_CSS_Token_Processor::create( '-' );
-		$actual_tokens   = $this->collect_tokens( $processor, array( 'type', 'raw' ) );
+		$actual_tokens   = $this->collect_tokens( '-', array( 'type', 'raw' ) );
 		$expected_tokens = array(
 			array(
 				'type' => WP_CSS_Token_Processor::TOKEN_DELIM,
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 6db563924fcc1..22a9d31a3f3a7 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -104,7 +104,7 @@ public function test_ident( string $input, string $expected ): void {
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
 
-		$this->assertSame( str_replace( "\0", '�', $input ), $processor->get_token_value() );
+		$this->assertSame( str_replace( "\0", '�', $input ), $processor->get_token()->get_value() );
 		$this->assertFalse( $processor->next_token() );
 	}
 

From ec1b00527caf5b7b9a8341379d9b35b29949c93c Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:13:43 +0400
Subject: [PATCH 59/77] Add WP_CSS_Builder to write PHP values as CSS text

Code that puts a PHP value into CSS has no public way to escape it:
the serializer's escapers are internal, so each caller writes its own.
WP_CSS_Builder writes a value as a quoted string, a url() function
holding a quoted string, or an identifier, each reading back as the
given value.

The escape rules stay in WP_CSS_Token_Serializer, which may later
escape for other contexts or with other character sets; the builder
forwards to it. escape_string() becomes public and marked
@access private, as escape_ident() already is.

url() writes the quoted form, url("..."), so it needs only the string
escapes. The unquoted url token needs its own escapes for parentheses,
quotes and whitespace.
---
 .../css-api/class-wp-css-builder.php          | 110 +++++++++++++
 .../css-api/class-wp-css-token-serializer.php |   6 +-
 src/wp-settings.php                           |   1 +
 tests/phpunit/tests/css-api/wpCssBuilder.php  | 146 ++++++++++++++++++
 4 files changed, 262 insertions(+), 1 deletion(-)
 create mode 100644 src/wp-includes/css-api/class-wp-css-builder.php
 create mode 100644 tests/phpunit/tests/css-api/wpCssBuilder.php

diff --git a/src/wp-includes/css-api/class-wp-css-builder.php b/src/wp-includes/css-api/class-wp-css-builder.php
new file mode 100644
index 0000000000000..d778780c91462
--- /dev/null
+++ b/src/wp-includes/css-api/class-wp-css-builder.php
@@ -0,0 +1,110 @@
+<?php
+/**
+ * CSS API: WP_CSS_Builder class
+ *
+ * @package WordPress
+ * @subpackage CSS-API
+ * @since 7.3.0
+ */
+
+/**
+ * Writes PHP values as CSS text.
+ *
+ * Each method returns CSS text that reads back as the given value: a string
+ * token, a `url()` function holding a string token, or an identifier. Combine
+ * the results with literal CSS to write a value with parts that come from
+ * input.
+ *
+ * Example:
+ *
+ * ```php interactive
+ * $image_url = 'https://example.com/a (1) "b".jpg';
+ * echo 'background-image: ' . WP_CSS_Builder::url( $image_url );
+ * // Outputs: background-image: url("https://example.com/a (1) \22 b\22 .jpg")
+ * ```
+ *
+ * The characters escaped beyond those CSS requires may change; the value
+ * the text reads back as does not.
+ *
+ * @since 7.3.0
+ *
+ * @see WP_CSS_Token_Serializer
+ */
+class WP_CSS_Builder {
+	/**
+	 * Writes a value as a quoted CSS string.
+	 *
+	 * Quotes, `\` and control characters are hex-escaped, as are `< > & , ;
+	 * { }`, which may be problematic in HTML or for rudimentary CSS
+	 * processors. CSS cannot represent NULL, so it reads back as U+FFFD.
+	 * Invalid UTF-8 reads back as U+FFFD.
+	 *
+	 * Example:
+	 *
+	 * ```php interactive
+	 * echo 'content: ' . WP_CSS_Builder::string( 'Say "hi"' );
+	 * // Outputs: content: "Say \22 hi\22 "
+	 * ```
+	 *
+	 * @since 7.3.0
+	 *
+	 * @param string $value Value the string should read back as.
+	 * @return string Quoted CSS string.
+	 */
+	public static function string( string $value ): string {
+		return WP_CSS_Token_Serializer::escape_string( $value );
+	}
+
+	/**
+	 * Writes a URL as a CSS `url()` function holding a quoted string.
+	 *
+	 * The URL is written as string() writes it. It is not validated or
+	 * sanitized; pass it through esc_url() or sanitize_url() first when it
+	 * comes from input.
+	 *
+	 * Example:
+	 *
+	 * ```php interactive
+	 * echo WP_CSS_Builder::url( 'https://example.com/a(1).png' );
+	 * // Outputs: url("https://example.com/a(1).png")
+	 * ```
+	 *
+	 * @since 7.3.0
+	 *
+	 * @link https://www.w3.org/TR/css-values-4/#urls
+	 *
+	 * @param string $url URL the function should read back as.
+	 * @return string CSS `url()` function.
+	 */
+	public static function url( string $url ): string {
+		return 'url(' . self::string( $url ) . ')';
+	}
+
+	/**
+	 * Writes a value as a CSS identifier.
+	 *
+	 * Code points that cannot appear in an identifier at their position are
+	 * hex-escaped, as are the characters string() escapes. Use it for a
+	 * property name, a custom property name in `var()`, or a keyword or
+	 * family name written without quotes.
+	 *
+	 * An empty value returns an empty string, which is not an identifier.
+	 *
+	 * Example:
+	 *
+	 * ```php interactive
+	 * echo 'font-family: ' . WP_CSS_Builder::ident( '1st Font' );
+	 * // Outputs: font-family: \31 st\20 Font
+	 * ```
+	 *
+	 * @since 7.3.0
+	 *
+	 * @link https://www.w3.org/TR/css-syntax-3/#ident-token-diagram
+	 *
+	 * @param string $value Value the identifier should read back as.
+	 * @return string CSS identifier, or an empty string for an empty value.
+	 */
+	public static function ident( string $value ): string {
+		return WP_CSS_Token_Serializer::escape_ident( $value );
+	}
+}
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index 17071bfcf1dc9..c437b4dd849b1 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -20,6 +20,7 @@
  * @access private
  *
  * @see WP_CSS_Token_Processor
+ * @see WP_CSS_Builder
  */
 class WP_CSS_Token_Serializer {
 	/**
@@ -409,11 +410,14 @@ public static function escape_ident( string $value ): string {
 	 * @link https://drafts.csswg.org/cssom/#serialize-a-string
 	 *
 	 * @since 7.3.0
+	 * @access private
+	 *
+	 * @see WP_CSS_Builder::string()
 	 *
 	 * @param string $value Decoded value.
 	 * @return string Quoted string text.
 	 */
-	private static function escape_string( string $value ): string {
+	public static function escape_string( string $value ): string {
 		$value  = wp_scrub_utf8( $value );
 		$result = '';
 		$length = strlen( $value );
diff --git a/src/wp-settings.php b/src/wp-settings.php
index d596b8224369f..366a7a469b8dd 100644
--- a/src/wp-settings.php
+++ b/src/wp-settings.php
@@ -292,6 +292,7 @@
 require ABSPATH . WPINC . '/css-api/class-wp-css-token.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-processor.php';
 require ABSPATH . WPINC . '/css-api/class-wp-css-token-serializer.php';
+require ABSPATH . WPINC . '/css-api/class-wp-css-builder.php';
 require ABSPATH . WPINC . '/class-wp-block-processor.php';
 require ABSPATH . WPINC . '/class-wp-http.php';
 require ABSPATH . WPINC . '/class-wp-http-streams.php';
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssBuilder.php
new file mode 100644
index 0000000000000..321ca42fd1b84
--- /dev/null
+++ b/tests/phpunit/tests/css-api/wpCssBuilder.php
@@ -0,0 +1,146 @@
+<?php
+
+/**
+ * Tests for WP_CSS_Builder.
+ *
+ * @group css-api
+ *
+ * @coversDefaultClass WP_CSS_Builder
+ */
+class Tests_CssApi_WpCssBuilder extends WP_UnitTestCase {
+	/**
+	 * Tests that string() writes one string token that reads back as the value.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_values
+	 *
+	 * @covers ::string
+	 */
+	public function test_string_reads_back_as_the_value( string $value, string $expected_value ): void {
+		$tokens = self::tokenize( WP_CSS_Builder::string( $value ) );
+
+		$this->assertCount( 1, $tokens );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $tokens[0]->get_type() );
+		$this->assertTrue( $tokens[0]->is_terminated() );
+		$this->assertSame( $expected_value, $tokens[0]->get_value() );
+	}
+
+	/**
+	 * Tests that url() writes a url function holding one string token that reads back as the value.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_values
+	 *
+	 * @covers ::url
+	 */
+	public function test_url_reads_back_as_the_value( string $value, string $expected_value ): void {
+		$tokens = self::tokenize( WP_CSS_Builder::url( $value ) );
+
+		$this->assertCount( 3, $tokens );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_FUNCTION, $tokens[0]->get_type() );
+		$this->assertSame( 'url', $tokens[0]->get_value() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $tokens[1]->get_type() );
+		$this->assertSame( $expected_value, $tokens[1]->get_value() );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_RIGHT_PAREN, $tokens[2]->get_type() );
+	}
+
+	/**
+	 * Tests that ident() writes one ident token that reads back as the value.
+	 *
+	 * @ticket 65738
+	 * @dataProvider data_values
+	 *
+	 * @covers ::ident
+	 */
+	public function test_ident_reads_back_as_the_value( string $value, string $expected_value ): void {
+		$tokens = self::tokenize( WP_CSS_Builder::ident( $value ) );
+
+		$this->assertCount( 1, $tokens );
+		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $tokens[0]->get_type() );
+		$this->assertSame( $expected_value, $tokens[0]->get_value() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array[]
+	 */
+	public static function data_values(): array {
+		return array(
+			'plain'                  => array( 'abc', 'abc' ),
+			'url with a query'       => array( 'https://example.com/a?b=1&c=2', 'https://example.com/a?b=1&c=2' ),
+			'parentheses and spaces' => array( 'https://example.com/a (1).jpg', 'https://example.com/a (1).jpg' ),
+			'double quote'           => array( 'a"b', 'a"b' ),
+			'single quote'           => array( "a'b", "a'b" ),
+			'backslash'              => array( 'a\\b', 'a\\b' ),
+			'declaration delimiters' => array( 'a;b:c}d{e', 'a;b:c}d{e' ),
+			'html delimiters'        => array( '</style><a>&amp;', '</style><a>&amp;' ),
+			'newline and tab'        => array( "a\nb\tc\r\fd", "a\nb\tc\r\fd" ),
+			'leading digit'          => array( '1a', '1a' ),
+			'leading hyphen digit'   => array( '-1a', '-1a' ),
+			'lone hyphen'            => array( '-', '-' ),
+			'custom property name'   => array( '--a', '--a' ),
+			'non-ascii'              => array( 'café 😀', 'café 😀' ),
+			'null byte'              => array( "a\0b", "a\u{FFFD}b" ),
+			'invalid utf-8'          => array( "a\xFFb", "a\u{FFFD}b" ),
+		);
+	}
+
+	/**
+	 * Tests that string() and url() write an empty value as an empty string.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::string
+	 * @covers ::url
+	 */
+	public function test_empty_string_and_url(): void {
+		$this->assertSame( '""', WP_CSS_Builder::string( '' ) );
+		$this->assertSame( 'url("")', WP_CSS_Builder::url( '' ) );
+	}
+
+	/**
+	 * Tests that ident() returns an empty string for an empty value.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::ident
+	 */
+	public function test_empty_ident(): void {
+		$this->assertSame( '', WP_CSS_Builder::ident( '' ) );
+	}
+
+	/**
+	 * Tests the examples in the docblocks.
+	 *
+	 * @ticket 65738
+	 *
+	 * @covers ::string
+	 * @covers ::url
+	 * @covers ::ident
+	 */
+	public function test_docblock_examples(): void {
+		$this->assertSame(
+			'url("https://example.com/a (1) \\22 b\\22 .jpg")',
+			WP_CSS_Builder::url( 'https://example.com/a (1) "b".jpg' )
+		);
+		$this->assertSame( '"Say \\22 hi\\22 "', WP_CSS_Builder::string( 'Say "hi"' ) );
+		$this->assertSame( 'url("https://example.com/a(1).png")', WP_CSS_Builder::url( 'https://example.com/a(1).png' ) );
+		$this->assertSame( '\\31 st\\20 Font', WP_CSS_Builder::ident( '1st Font' ) );
+	}
+
+	/**
+	 * Tokenizes CSS.
+	 *
+	 * @param string $css CSS to tokenize.
+	 * @return WP_CSS_Token[] Tokens.
+	 */
+	private static function tokenize( string $css ): array {
+		$processor = WP_CSS_Token_Processor::create( $css );
+		$tokens    = array();
+		while ( $processor->next_token() ) {
+			$tokens[] = $processor->get_token();
+		}
+		return $tokens;
+	}
+}

From f0020b55b495b64d615f5cebc6ff1ca82dff67f1 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:15:09 +0400
Subject: [PATCH 60/77] Mark private CSS API declarations @ignore

The developer documentation site skips declarations marked @ignore.
Every PHP-private member and every declaration marked @access private
now has it, as the HTML API does. Private members without a @since
tag gain @since 7.3.0 with it.
---
 .../css-api/class-wp-css-token-processor.php  | 83 +++++++++++++++++++
 .../css-api/class-wp-css-token-serializer.php | 12 +++
 .../css-api/class-wp-css-token.php            | 12 +++
 3 files changed, 107 insertions(+)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 23e97efcb4021..5fea13712785c 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -240,16 +240,25 @@ class WP_CSS_Token_Processor {
 	public const TOKEN_CDO = 'CDO-token';
 
 	/**
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string
 	 */
 	private $css;
 
 	/**
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int
 	 */
 	private $length = 0;
 
 	/**
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int
 	 */
 	private $at = 0;
@@ -257,6 +266,9 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The type of the current token. One of the self::TOKEN_* constants.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string|null
 	 * @phpstan-var self::TOKEN_*|null
 	 */
@@ -272,6 +284,9 @@ class WP_CSS_Token_Processor {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string|null
 	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
 	 */
@@ -286,6 +301,9 @@ class WP_CSS_Token_Processor {
 	 *                 ↑
 	 *     The url token starts at byte 12.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int|null
 	 */
 	private $token_starts_at = null;
@@ -299,6 +317,9 @@ class WP_CSS_Token_Processor {
 	 *                 ╰────┬─────╯
 	 *     The url token is 12 bytes long.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int|null
 	 */
 	private $token_length = null;
@@ -315,6 +336,9 @@ class WP_CSS_Token_Processor {
 	 *                      ↑
 	 *     The url value starts at byte 17.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int|null
 	 */
 	private $token_value_starts_at = null;
@@ -328,6 +352,9 @@ class WP_CSS_Token_Processor {
 	 *                      ╰─┬─╯
 	 *     The url value is 5 bytes long.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int|null
 	 */
 	private $token_value_length = null;
@@ -335,6 +362,9 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The current token, created on the first call to get_token().
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var WP_CSS_Token|null
 	 */
 	private $token = null;
@@ -342,6 +372,9 @@ class WP_CSS_Token_Processor {
 	/**
 	 * The unit of the current token, e.g. "px", "em", "deg", etc.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string|null
 	 */
 	private $token_unit = null;
@@ -357,6 +390,9 @@ class WP_CSS_Token_Processor {
 	 *            ╰─┬╯
 	 *     The string token is not terminated: the input ends before the closing quote.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var bool
 	 */
 	private $token_is_terminated = true;
@@ -367,6 +403,7 @@ class WP_CSS_Token_Processor {
 	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param string $css         CSS source to tokenize.
 	 */
@@ -768,6 +805,9 @@ public function get_token_length(): ?int {
 
 	/**
 	 * Clears token state between tokens.
+	 *
+	 * @since 7.3.0
+	 * @ignore
 	 */
 	private function after_token(): void {
 		$this->token_type            = null;
@@ -789,6 +829,9 @@ private function after_token(): void {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function consume_string(): bool {
@@ -900,6 +943,9 @@ private function consume_string(): bool {
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-numeric-token
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-number
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function consume_numeric(): bool {
@@ -1019,6 +1065,9 @@ private function consume_numeric(): bool {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-ident-like-token
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function consume_ident_like(): bool {
@@ -1079,6 +1128,9 @@ private function consume_ident_like(): bool {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function consume_url(): bool {
@@ -1218,6 +1270,9 @@ private function consume_url(): bool {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-remnants-of-bad-url
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function consume_remnants_of_bad_url(): bool {
@@ -1259,6 +1314,9 @@ private function consume_remnants_of_bad_url(): bool {
 	 * Advances the cursor past the sequence; the caller decodes the bytes.
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-name
+	 *
+	 * @since 7.3.0
+	 * @ignore
 	 */
 	private function consume_ident_sequence(): void {
 		while ( $this->at < $this->length ) {
@@ -1299,6 +1357,10 @@ private function consume_ident_sequence(): void {
 	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return int The number of bytes consumed.
 	 */
 	private function consume_ident_codepoint( $at ): int {
@@ -1319,6 +1381,10 @@ private function consume_ident_codepoint( $at ): int {
 	 *     An ident-start code point, a digit, or U+002D HYPHEN-MINUS (-).
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#ident-start-code-point
+	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return int The number of bytes consumed.
 	 */
 	private function consume_ident_start_codepoint( $at ): int {
@@ -1364,6 +1430,7 @@ private function consume_ident_start_codepoint( $at ): int {
 	 *
 	 * @since 7.3.0
 	 * @access private
+	 * @ignore
 	 *
 	 * @param string $css            CSS source the offsets index.
 	 * @param int    $start          Start byte offset.
@@ -1474,6 +1541,7 @@ public static function decode_range( string $css, int $start, int $length, bool
 	 *
 	 * @since 7.3.0
 	 * @access private
+	 * @ignore
 	 *
 	 * @param string $css    CSS source the offsets index.
 	 * @param int    $start  Start byte offset.
@@ -1501,6 +1569,9 @@ public static function preprocess_range( string $css, int $start, int $length ):
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $css             CSS source.
 	 * @param int    $offset          Byte offset (should point to the character after the backslash).
 	 * @param int    &$bytes_consumed Output parameter: number of bytes consumed.
@@ -1583,6 +1654,9 @@ private static function decode_escape_at( string $css, int $offset, &$bytes_cons
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-valid-escape
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $css    CSS source.
 	 * @param int    $offset Byte offset.
 	 * @return bool
@@ -1618,6 +1692,9 @@ private static function is_valid_escape( string $css, int $offset ): bool {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#starts-with-a-number
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return bool
 	 */
 	private function would_next_3_code_points_start_a_number(): bool {
@@ -1673,6 +1750,9 @@ private function would_next_3_code_points_start_a_number(): bool {
 	 *
 	 * @link https://www.w3.org/TR/css-syntax-3/#would-start-an-identifier
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $offset Byte offset of the first code point to check.
 	 * @return bool
 	 */
@@ -1698,6 +1778,9 @@ private function check_if_3_code_points_start_an_ident_sequence( int $offset ):
 	/**
 	 * Convert a UTF-8 byte sequence to its Unicode codepoint.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param  string $character  UTF-8 encoded byte sequence representing a single Unicode character.
 	 *
 	 * @return int Unicode codepoint.
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index c437b4dd849b1..d9103be9339b1 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -18,6 +18,7 @@
  *
  * @since 7.3.0
  * @access private
+ * @ignore
  *
  * @see WP_CSS_Token_Processor
  * @see WP_CSS_Builder
@@ -32,6 +33,7 @@ class WP_CSS_Token_Serializer {
 	 * @see WP_CSS_Token_Serializer::serialize()
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var array<string, string[]>
 	 */
@@ -84,6 +86,7 @@ class WP_CSS_Token_Serializer {
 	 * @see WP_CSS_Token_Serializer::MARKED_PAIRS
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string[]
 	 */
@@ -105,6 +108,7 @@ class WP_CSS_Token_Serializer {
 	 * @see WP_CSS_Token_Serializer::MARKED_PAIRS
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string[]
 	 */
@@ -118,6 +122,7 @@ class WP_CSS_Token_Serializer {
 	 * Text of the token types that have no value.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var array<string, string>
 	 */
@@ -141,6 +146,7 @@ class WP_CSS_Token_Serializer {
 	 * Closing token type of each token type that opens a block.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var array<string, string>
 	 */
@@ -315,6 +321,7 @@ public static function serialize( iterable $tokens ): string {
 	 * Serializes one token other than whitespace or a comment.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param WP_CSS_Token $token Token.
 	 * @return string CSS text.
@@ -379,6 +386,7 @@ private static function serialize_token( WP_CSS_Token $token ): string {
 	 *
 	 * @since 7.3.0
 	 * @access private
+	 * @ignore
 	 *
 	 * @param string $value Decoded value.
 	 * @return string Identifier text.
@@ -411,6 +419,7 @@ public static function escape_ident( string $value ): string {
 	 *
 	 * @since 7.3.0
 	 * @access private
+	 * @ignore
 	 *
 	 * @see WP_CSS_Builder::string()
 	 *
@@ -461,6 +470,7 @@ public static function escape_string( string $value ): string {
 	 * @link https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param string $value Decoded name.
 	 * @return string Escaped name.
@@ -516,6 +526,7 @@ private static function escape_name( string $value ): string {
 	 * @link https://drafts.csswg.org/css-syntax-3/#non-ascii-ident-code-point
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param int $code_point Code point above U+007F.
 	 * @return bool Whether the code point may appear unescaped in an identifier.
@@ -550,6 +561,7 @@ private static function is_non_ascii_ident_code_point( int $code_point ): bool {
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param string $value Decoded value.
 	 * @return string Url text, including `url(` and `)`.
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 2d31a5d27f675..aba73cffc912c 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -38,6 +38,7 @@ final class WP_CSS_Token {
 	 * CSS source the offsets index.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string
 	 */
@@ -47,6 +48,7 @@ final class WP_CSS_Token {
 	 * Token type.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string
 	 * @phpstan-var WP_CSS_Token_Processor::TOKEN_*
@@ -57,6 +59,7 @@ final class WP_CSS_Token {
 	 * Byte offset at which the token starts.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var int
 	 */
@@ -66,6 +69,7 @@ final class WP_CSS_Token {
 	 * Byte length of the token.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var int
 	 */
@@ -75,6 +79,7 @@ final class WP_CSS_Token {
 	 * Type flag of a hash, number or dimension token.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string|null
 	 * @phpstan-var 'id'|'unrestricted'|'integer'|'number'|null
@@ -85,6 +90,7 @@ final class WP_CSS_Token {
 	 * Decoded unit of a dimension token.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string|null
 	 */
@@ -94,6 +100,7 @@ final class WP_CSS_Token {
 	 * Byte offset at which the value of a string, url or comment token starts.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var int|null
 	 */
@@ -103,6 +110,7 @@ final class WP_CSS_Token {
 	 * Byte length of the value of a string, url or comment token.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var int|null
 	 */
@@ -112,6 +120,7 @@ final class WP_CSS_Token {
 	 * Whether the token ended at its closing delimiter.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var bool
 	 */
@@ -121,6 +130,7 @@ final class WP_CSS_Token {
 	 * Decoded value, or false before the first call to get_value().
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @var string|null|false
 	 */
@@ -133,6 +143,7 @@ final class WP_CSS_Token {
 	 *
 	 * @since 7.3.0
 	 * @access private
+	 * @ignore
 	 *
 	 * @param string      $css           CSS source the offsets index.
 	 * @param string      $type          Token type, one of the WP_CSS_Token_Processor::TOKEN_* constants.
@@ -264,6 +275,7 @@ public function is_terminated(): bool {
 	 * Decodes the value from the CSS source.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @return string|null The decoded value, or null for token types without a value.
 	 */

From 5742ca951c6647b7a8c810d298dc3ec68db88a60 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:40:10 +0400
Subject: [PATCH 61/77] Document token values on WP_CSS_Token instead of the
 removed getters

The per-type description of a token's value and the termination rules
were on WP_CSS_Token_Processor::get_token_value() and
is_token_terminated(), which no longer exist. They move to
WP_CSS_Token::get_value() and is_terminated(), which had one-line
descriptions. The class example that echoed get_normalized_token() now
echoes token types, and the @see tags naming removed methods are gone.
---
 .../css-api/class-wp-css-token-processor.php  | 13 +++--
 .../css-api/class-wp-css-token.php            | 50 +++++++++++++++++--
 2 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 5fea13712785c..3f8f1e2c3d182 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -29,8 +29,8 @@
  * > CHARACTER (�).
  *
  * This processor delays normalization as much as possible. That keeps the raw byte
- * positions intact for accurate rewrites while still letting consumers ask for a
- * normalized token when they need one.
+ * positions intact for accurate rewrites; WP_CSS_Token::get_value() normalizes and
+ * decodes a token's value when it is asked for.
  * For example, `url(a<NUL>b)` is a URL token whose value is `a�b`, where `<NUL>`
  * means one zero byte in the source. That byte stays in the raw token, so later
  * edits still use byte offsets from the original input.
@@ -53,9 +53,14 @@
  * ```php interactive
  * $processor = WP_CSS_Token_Processor::create( 'width: 10px;' );
  * while ( $processor->next_token() ) {
- *     echo $processor->get_normalized_token();
+ *     echo $processor->get_token_type() . "\n";
  * }
- * // Outputs: "width: 10px;"
+ * // Outputs:
+ * // ident-token
+ * // colon-token
+ * // whitespace-token
+ * // dimension-token
+ * // semicolon-token
  * ```
  *
  * Gathering diagnostics with byte offsets:
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index aba73cffc912c..2af6b4202c2b9 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -197,8 +197,6 @@ public function get_type(): string {
 	 *
 	 * @since 7.3.0
 	 *
-	 * @see WP_CSS_Token_Processor::get_token_type_flag()
-	 *
 	 * @return string|null The type flag, or null.
 	 * @phpstan-return 'id'|'unrestricted'|'integer'|'number'|null
 	 */
@@ -209,11 +207,34 @@ public function get_flag(): ?string {
 	/**
 	 * Gets the decoded value.
 	 *
+	 * The value is the token's text after input preprocessing and escape
+	 * decoding, without its delimiters:
+	 *
+	 * - ident, delim: the whole token.
+	 * - function: the name, without `(`.
+	 * - at-keyword, hash: the name, without `@` or `#`.
+	 * - string, url: the contents, without quotes or `url(` and `)`.
+	 * - comment: the text between `/*` and `*` `/`. Comments contain no
+	 *   escapes, so only preprocessing applies.
+	 * - number, percentage, dimension: the number as written in the source,
+	 *   without `%` or the unit. CSS Syntax 3 parses it as a number; this
+	 *   method keeps the text.
+	 * - Every other type, including bad-string and bad-url: null.
+	 *
 	 * The value is decoded on the first call and kept for later calls.
 	 *
+	 * Example:
+	 *
+	 * ```php interactive
+	 * $processor = WP_CSS_Token_Processor::create( '"a\\62 c"' );
+	 * $processor->next_token();
+	 * echo $processor->get_token()->get_value();
+	 * // Outputs: abc
+	 * ```
+	 *
 	 * @since 7.3.0
 	 *
-	 * @see WP_CSS_Token_Processor::get_token_value()
+	 * @link https://www.w3.org/TR/css-syntax-3/#tokenization
 	 *
 	 * @return string|null The decoded value, or null for token types without a value.
 	 */
@@ -261,9 +282,30 @@ public function get_length(): int {
 	/**
 	 * Reports whether the token ended at its closing delimiter.
 	 *
+	 * Comment, string, url and bad-url tokens have a closing delimiter: `*` `/`,
+	 * the matching quote, or `)`. When the input ends before the delimiter,
+	 * the tokenizer still returns the token, and this method returns false.
+	 * It returns true for every other token type, which have no closing
+	 * delimiter.
+	 *
+	 * Example:
+	 *
+	 * ```php interactive
+	 * $processor = WP_CSS_Token_Processor::create( '"abc' );
+	 * $processor->next_token();
+	 * $token = $processor->get_token();
+	 * echo $token->get_type() . "\n";
+	 * var_dump( $token->is_terminated() );
+	 * // Outputs:
+	 * // string-token
+	 * // bool(false)
+	 * ```
+	 *
 	 * @since 7.3.0
 	 *
-	 * @see WP_CSS_Token_Processor::is_token_terminated()
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-comment
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-string-token
+	 * @link https://www.w3.org/TR/css-syntax-3/#consume-url-token
 	 *
 	 * @return bool Whether the token ended at its closing delimiter.
 	 */

From 8f432eee244eaf41877d2270fe2a430a4f9d4393 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:40:59 +0400
Subject: [PATCH 62/77] Read token values through WP_CSS_Token in
 is_valid_declaration_value()

WP_CSS_Token_Processor::get_token_value() was removed; get_token()->get_value() returns the same value.
---
 .../html-api/class-wp-html-style-attribute-processor.php    | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 1031d0ab606ef..f414332adabd9 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -267,10 +267,6 @@ public function set_value( string $value, ?bool $important = null ): bool {
 			return false;
 		}
 
-		if ( '' === $value ) {
-			return $this->remove_declaration();
-		}
-
 		if ( ! $this->is_valid_declaration_value( $value ) ) {
 			return false;
 		}
@@ -1626,7 +1622,7 @@ private function is_valid_declaration_value( string $value ): bool {
 
 				$top_level_tokens[] = array(
 					'type'  => $type,
-					'value' => $processor->get_token_value(),
+					'value' => $processor->get_token()->get_value(),
 				);
 			}
 

From 0085ea80a9272d76b47334718825ef2fcc553057 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:40:59 +0400
Subject: [PATCH 63/77] Reject an empty value in set_value() instead of
 removing the declaration

remove_declaration() removes the current declaration. set_value( '' )
was a second way to do it, and made an empty value mean something in
set_value() that it means nowhere else: append_declaration() rejects
it, as does set_value() for a value that is only whitespace.
---
 docs/wp-html-style-attribute-processor-spec.md |  8 ++------
 .../html-api/wpHtmlStyleAttributeProcessor.php | 18 +++++-------------
 2 files changed, 7 insertions(+), 19 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index d0060646e8262..4cf1aa54300d0 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -98,9 +98,6 @@ returns `false`.
 After `set_value()` or `set_important()` succeeds without removing the
 declaration, the cursor remains on the same logical declaration.
 
-`set_value( '' )` removes the current declaration. On success it has the same
-cursor semantics as `remove_declaration()`.
-
 `append_declaration()` does not move the cursor. If the cursor was exhausted, it
 remains invalid until a later `next_declaration()` advances to the appended
 declaration.
@@ -195,8 +192,7 @@ properties and value grammars.
 
 Values must be complete and self-contained. Reject inputs that:
 
-- are empty after CSS whitespace trimming, except `set_value( '' )`, which
-  removes the current declaration;
+- are empty after CSS whitespace trimming;
 - contain top-level declaration separators such as semicolons;
 - contain a top-level `!important`, because priority is a separate argument;
 - contain bad strings or bad URLs;
@@ -344,7 +340,7 @@ Tests should cover:
 - value token view: `null` off-cursor, trivia and priority exclusion, offsets
   into the style text, and the re-tokenization invariant;
 - `set_value()` priority preservation, setting, clearing, and empty-value
-  removal;
+  rejection;
 - `set_important()` setting, clearing, cursor behavior, and safe normalization;
 - rejection of unsafe values and property names with atomic failure;
 - append behavior, duplicate appends, exhausted cursor behavior, and empty-value
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index dbcabd5dec7ad..5854b71a03f37 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -553,24 +553,16 @@ public function test_set_value_preserves_sets_and_clears_importance() {
 
 	/**
 	 * @covers ::set_value
-	 * @covers ::remove_declaration
-	 * @covers ::get_property_name
-	 * @covers ::is_important
 	 */
-	public function test_set_value_with_empty_string_removes_current_declaration() {
+	public function test_set_value_rejects_empty_value() {
 		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
-		$this->assertTrue( $processor->set_value( '' ) );
+		$this->assertFalse( $processor->set_value( '' ) );
+		$this->assertFalse( $processor->set_value( " \t" ) );
 
-		$this->assertNull( $processor->get_property_name() );
-		$this->assertNull( $processor->is_important() );
-		$this->assertFalse( $processor->set_value( 'green' ) );
-		$this->assertFalse( $processor->remove_declaration() );
-
-		$this->assertTrue( $processor->next_declaration() );
-		$this->assertSame( 'background', $processor->get_property_name() );
-		$this->assertSame( 'background: white;', $processor->get_updated_style() );
+		$this->assertSame( 'color', $processor->get_property_name() );
+		$this->assertSame( 'color: red; background: white;', $processor->get_updated_style() );
 	}
 
 	/**

From 8120beb7b797eef198e0c92a847bf03612e4499f Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 27 Oct 2026 18:41:17 +0400
Subject: [PATCH 64/77] Mark private style attribute processor declarations
 @ignore

The developer documentation site skips declarations marked @ignore.
Every private member of WP_HTML_Style_Attribute_Processor now has it,
with @since 7.3.0 where the docblock had no @since.
---
 ...lass-wp-html-style-attribute-processor.php | 127 ++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index f414332adabd9..fdf9a63fa52da 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -32,6 +32,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * CSS whitespace characters.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string
 	 */
 	private const WHITESPACE = " \t\n\r\f";
@@ -39,6 +42,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Decoded style attribute value.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var string
 	 */
 	private $style;
@@ -46,6 +52,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * CSS tokens of the style attribute value.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var WP_CSS_Token[]
 	 */
 	private $tokens = array();
@@ -65,6 +74,9 @@ class WP_HTML_Style_Attribute_Processor {
 	 * value. The `important_*` offsets are null when the declaration has no
 	 * `!important` priority.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var array<int, array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}>
 	 */
 	private $declarations = array();
@@ -72,6 +84,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Whether the style attribute value has been parsed.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var bool
 	 */
 	private $parsed = false;
@@ -79,6 +94,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Index of the current declaration, or -1 before the first declaration.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int
 	 */
 	private $current_declaration = -1;
@@ -86,6 +104,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Whether the current declaration was removed and no new declaration has been selected.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var bool
 	 */
 	private $current_declaration_removed = false;
@@ -93,6 +114,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Lexical updates to apply to the original style attribute value.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}>
 	 */
 	private $lexical_updates = array();
@@ -100,6 +124,9 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Sequence counter used to keep lexical updates in queue order.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @var int
 	 */
 	private $lexical_update_order = 0;
@@ -111,6 +138,7 @@ class WP_HTML_Style_Attribute_Processor {
 	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
 	 *
 	 * @since 7.3.0
+	 * @ignore
 	 *
 	 * @param string $style Decoded CSS text value from a style attribute.
 	 */
@@ -546,6 +574,9 @@ static function ( $a, $b ) {
 
 	/**
 	 * Parses CSS tokens and declarations from the style attribute value.
+	 *
+	 * @since 7.3.0
+	 * @ignore
 	 */
 	private function parse(): void {
 		$this->tokens       = array();
@@ -567,6 +598,9 @@ private function parse(): void {
 
 	/**
 	 * Lazily parses the style attribute value when declaration access needs it.
+	 *
+	 * @since 7.3.0
+	 * @ignore
 	 */
 	private function ensure_parsed(): void {
 		if ( $this->parsed ) {
@@ -578,6 +612,9 @@ private function ensure_parsed(): void {
 
 	/**
 	 * Parses the token list according to the CSS declaration-list shape.
+	 *
+	 * @since 7.3.0
+	 * @ignore
 	 */
 	private function parse_declaration_list(): void {
 		$index = 0;
@@ -614,6 +651,9 @@ private function parse_declaration_list(): void {
 	/**
 	 * Consumes an at-rule and returns the token index after it.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $index At-keyword token index.
 	 * @return int Token index after the at-rule.
 	 */
@@ -656,6 +696,9 @@ private function consume_at_rule( int $index ): int {
 	/**
 	 * Consumes a simple block.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int    $index        Token index for the opening token.
 	 * @param string $closing_type Expected closing token type.
 	 * @return int Token index after the block.
@@ -700,6 +743,9 @@ private function consume_simple_block( int $index, string $closing_type ): int {
 	/**
 	 * Consumes a declaration candidate up to the next top-level semicolon or EOF.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $index Starting token index.
 	 * @return array{int,int,bool} End token index, byte offset after candidate, and whether it ended in a semicolon.
 	 */
@@ -743,6 +789,9 @@ private function consume_declaration_segment( int $index ): array {
 	/**
 	 * Parses a declaration from a token segment.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $start_index First token index in the segment.
 	 * @param int $end_index   Token index after the segment.
 	 * @param int $after       Byte offset after the declaration.
@@ -822,6 +871,9 @@ private function parse_declaration_segment( int $start_index, int $end_index, in
 	/**
 	 * Gets top-level non-ignored token indexes from a token range.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $start Start token index.
 	 * @param int $end   End token index.
 	 * @return int[] Top-level non-ignored token indexes.
@@ -869,6 +921,9 @@ private function get_top_level_non_ignored_token_indexes( int $start, int $end )
 	/**
 	 * Skips ignored CSS tokens.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int      $index Token index.
 	 * @param int|null $end   Optional token index at which to stop.
 	 * @return int Token index after ignored tokens.
@@ -886,6 +941,9 @@ private function skip_ignored_tokens( int $index, ?int $end = null ): int {
 	/**
 	 * Trims ignored CSS tokens from the end of a token range.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $start Start token index.
 	 * @param int $end   End token index.
 	 * @return int Trimmed end token index.
@@ -901,6 +959,9 @@ private function trim_ignored_tokens( int $start, int $end ): int {
 	/**
 	 * Checks whether a token is ignored by declaration-list grammar.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param WP_CSS_Token $token Token.
 	 * @return bool Whether the token is ignored.
 	 */
@@ -914,6 +975,9 @@ private function is_ignored_token( WP_CSS_Token $token ): bool {
 	/**
 	 * Gets the byte offset after a token.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param WP_CSS_Token $token Token.
 	 * @return int Byte offset after the token.
 	 */
@@ -924,6 +988,9 @@ private static function get_token_end( WP_CSS_Token $token ): int {
 	/**
 	 * Gets the byte offset before contiguous whitespace ending at an offset.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $offset Byte offset.
 	 * @return int Offset before preceding whitespace.
 	 */
@@ -938,6 +1005,9 @@ private function get_offset_before_preceding_whitespace( int $offset ): int {
 	/**
 	 * Gets the byte offset after contiguous whitespace beginning at an offset.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $offset Byte offset.
 	 * @return int Offset after following whitespace.
 	 */
@@ -954,6 +1024,9 @@ private function get_offset_after_following_whitespace( int $offset ): int {
 	/**
 	 * Gets the current declaration metadata.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @return array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null}|null
 	 */
 	private function get_current_declaration(): ?array {
@@ -971,6 +1044,9 @@ private function get_current_declaration(): ?array {
 	/**
 	 * Checks whether a replacement preserves the current declaration's structure.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param array{name:string, start:int, after:int, value_start:int, value_end:int, value_tokens:array{int,int}, important:bool, important_start:int|null, important_end:int|null} $declaration        Current declaration metadata.
 	 * @param int                                                                                                                                                                                                                           $start              Byte offset at which to start the replacement.
 	 * @param int                                                                                                                                                                                                                           $length             Number of bytes to replace.
@@ -1014,6 +1090,9 @@ private function is_current_declaration_replacement_safe( array $declaration, in
 	/**
 	 * Checks whether removing a declaration preserves remaining structure.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int    $removed_declaration Removed declaration index.
 	 * @param int    $start               Byte offset at which to start the replacement.
 	 * @param int    $length              Number of bytes to replace.
@@ -1066,6 +1145,9 @@ private function is_remove_declaration_safe( int $removed_declaration, int $star
 	/**
 	 * Gets the parsed value source from a serialized declaration.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $declaration_text Serialized declaration text.
 	 * @return string|null Parsed declaration value, or null if parsing failed.
 	 */
@@ -1087,6 +1169,9 @@ private function get_parsed_declaration_value( string $declaration_text ): ?stri
 	/**
 	 * Applies queued lexical updates and reparses the updated style attribute value.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int  $current_declaration         Declaration index to keep before the next cursor advance.
 	 * @param bool $current_declaration_removed Optional. Whether the current declaration was removed.
 	 */
@@ -1109,6 +1194,9 @@ private function apply_lexical_updates( int $current_declaration, bool $current_
 	/**
 	 * Queues a lexical update, replacing any earlier update for the same declaration.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int      $start       Byte offset at which to start the update.
 	 * @param int      $length      Number of bytes to replace.
 	 * @param string   $text        Replacement text.
@@ -1135,6 +1223,9 @@ private function queue_lexical_update( int $start, int $length, string $text, ?i
 	/**
 	 * Checks whether an append has already been queued at a byte offset.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $insert_at Byte offset.
 	 * @return bool Whether an append has already been queued at the offset.
 	 */
@@ -1154,6 +1245,9 @@ private function has_queued_append_at( int $insert_at ): bool {
 	 * Comments and whitespace are CSS parser trivia. They do not determine
 	 * whether the existing declaration list needs a semicolon before appending.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $insert_at Byte offset at which the declaration will be inserted.
 	 * @return string Separator text.
 	 */
@@ -1174,6 +1268,9 @@ private function get_append_separator( int $insert_at ): string {
 	/**
 	 * Gets the last top-level non-ignored token before a byte offset.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $insert_at Byte offset before which to scan.
 	 * @return WP_CSS_Token|null Token, or null when there is none.
 	 */
@@ -1229,6 +1326,9 @@ private function get_last_top_level_non_ignored_token_before( int $insert_at ):
 	 * EOF. Appending must materialize those closers before adding a new
 	 * declaration.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int $insert_at Byte offset at which the declaration will be inserted.
 	 * @return string|null Closing delimiters, or null when repair cannot be precise.
 	 */
@@ -1312,6 +1412,9 @@ private function get_eof_repair( int $insert_at ): ?string {
 	 * unclosed component value. In that case preserving the original text and
 	 * appending a top-level declaration are incompatible.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int    $insert_at             Byte offset at which the declaration will be inserted.
 	 * @param string $eof_repair            EOF repair text.
 	 * @param string $separator             Separator text.
@@ -1358,6 +1461,9 @@ private function is_parseable_append( int $insert_at, string $eof_repair, string
 	 * may be queued inside a range removed from the original style. This method
 	 * collapses those updates while preserving the requested replacement text.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> $updates Lexical updates.
 	 * @return array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> Merged updates.
 	 */
@@ -1408,6 +1514,9 @@ private function merge_overlapping_lexical_updates( array $updates ): array {
 	/**
 	 * Formats a declaration as `name: value;` or `name: value !important;`.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $property_name CSS property name text.
 	 * @param string $value         CSS declaration value text.
 	 * @param bool   $important     Whether to append !important.
@@ -1423,6 +1532,9 @@ private function format_declaration( string $property_name, string $value, bool
 	 * Whitespace and comments before and after the value are removed, and the
 	 * rest is written as serialize_declaration() writes a value.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $value CSS declaration value.
 	 * @return string Value text.
 	 */
@@ -1448,6 +1560,9 @@ private function serialize_value( string $value ): string {
 	/**
 	 * Checks whether two property names match.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $actual Property name from a declaration.
 	 * @param string $query  Queried property name.
 	 * @return bool Whether the property names match.
@@ -1468,6 +1583,9 @@ private function matches_property_name( string $actual, string $query ): bool {
 	 * value unless the property is a custom property. Blocks left open at EOF are
 	 * closed by CSS and are valid.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param int  $start              First value token index.
 	 * @param int  $end                Token index after the value.
 	 * @param bool $is_custom_property Whether the declaration is a custom property.
@@ -1528,6 +1646,9 @@ private function is_parsed_value_valid( int $start, int $end, bool $is_custom_pr
 	/**
 	 * Checks whether a property name is a custom property.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $property_name Property name.
 	 * @return bool Whether this is a custom property name.
 	 */
@@ -1538,6 +1659,9 @@ private function is_custom_property_name( string $property_name ): bool {
 	/**
 	 * Checks whether a CSS property name is syntactically valid.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $property_name CSS property name.
 	 * @return bool Whether the property name is valid.
 	 */
@@ -1589,6 +1713,9 @@ private function is_valid_property_name( string $property_name ): bool {
 	/**
 	 * Checks whether a CSS declaration value is syntactically safe to insert.
 	 *
+	 * @since 7.3.0
+	 * @ignore
+	 *
 	 * @param string $value CSS declaration value.
 	 * @return bool Whether the value is valid.
 	 */

From f3e7bff40260b1b578aad1e47f5b4b19157ba79b Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 28 Oct 2026 07:52:15 +0400
Subject: [PATCH 65/77] Remove the encoding parameter from
 WP_CSS_Token_Processor::create()

The parameter accepted only 'UTF-8' and returned null for any other
value, so create() was typed static|null and every caller checked for a
null it could not get. Every caller passes text that is already decoded:
an attribute value or a string from the database.

An optional trailing parameter can be added in a later release without
breaking callers if the tokenizer ever reads other encodings; removing
one after release cannot.
---
 .../css-api/class-wp-css-token-processor.php  | 19 +++++-------------
 .../tests/css-api/wpCssTokenProcessor.php     | 20 -------------------
 2 files changed, 5 insertions(+), 34 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 3f8f1e2c3d182..7ab51df33c072 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -410,7 +410,7 @@ class WP_CSS_Token_Processor {
 	 * @since 7.3.0
 	 * @ignore
 	 *
-	 * @param string $css         CSS source to tokenize.
+	 * @param string $css CSS source to tokenize.
 	 */
 	private function __construct( string $css ) {
 		$this->css    = $css;
@@ -420,23 +420,14 @@ private function __construct( string $css ) {
 	/**
 	 * Creates a CSS processor for the given CSS string.
 	 *
-	 * Use this method to create a CSS processor instance.
-	 *
-	 * ## Current Support
-	 *
-	 * - The only supported document encoding is `UTF-8`, which is the default value.
+	 * The CSS is read as UTF-8. Convert CSS in another encoding to UTF-8 first.
 	 *
 	 * @since 7.3.0
 	 *
-	 * @param string $css      CSS source to tokenize.
-	 * @param string $encoding Text encoding of the document; must be default of 'UTF-8'.
-	 * @return static|null The created processor if successful, otherwise null.
+	 * @param string $css CSS source to tokenize.
+	 * @return static The created processor.
 	 */
-	public static function create( string $css, string $encoding = 'UTF-8' ) {
-		if ( 'UTF-8' !== $encoding ) {
-			return null;
-		}
-
+	public static function create( string $css ) {
 		return new static( $css );
 	}
 
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 8e9b2b1d1ba1b..140b538b5c287 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -2275,26 +2275,6 @@ public function test_dimension_token_value(): void {
 		$this->assertSame( $expected, $actual_tokens );
 	}
 
-	/**
-	 * Tests that create() validates encoding and only accepts UTF-8.
-	 */
-	public function test_create_validates_encoding(): void {
-		// UTF-8 encoding should work (default).
-		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }' );
-		$this->assertInstanceOf( WP_CSS_Token_Processor::class, $processor );
-
-		// UTF-8 encoding should work (explicit).
-		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'UTF-8' );
-		$this->assertInstanceOf( WP_CSS_Token_Processor::class, $processor );
-
-		// Other encodings should return null.
-		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'ISO-8859-1' );
-		$this->assertNull( $processor );
-
-		$processor = WP_CSS_Token_Processor::create( '.class { color: red; }', 'Windows-1252' );
-		$this->assertNull( $processor );
-	}
-
 	/**
 	 * Tests escape sequences in unusual and edge-case positions.
 	 *

From 8941a8129d58ea664f60a6fd37b8e68507455b8d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 28 Oct 2026 07:52:32 +0400
Subject: [PATCH 66/77] Remove null checks for WP_CSS_Token_Processor::create()

create() no longer returns null, so the four checks could never be true.
---
 .../class-wp-html-style-attribute-processor.php       | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index fdf9a63fa52da..6dc7c007413cf 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -583,10 +583,6 @@ private function parse(): void {
 		$this->declarations = array();
 
 		$processor = WP_CSS_Token_Processor::create( $this->style );
-		if ( null === $processor ) {
-			$this->parsed = true;
-			return;
-		}
 
 		while ( $processor->next_token() ) {
 			$this->tokens[] = $processor->get_token();
@@ -1675,7 +1671,7 @@ private function is_valid_property_name( string $property_name ): bool {
 		}
 
 		$processor = WP_CSS_Token_Processor::create( $property_name );
-		if ( null === $processor || ! $processor->next_token() ) {
+		if ( ! $processor->next_token() ) {
 			return false;
 		}
 
@@ -1692,7 +1688,7 @@ private function is_valid_property_name( string $property_name ): bool {
 		}
 
 		$sentinel_processor = WP_CSS_Token_Processor::create( $property_name . ': sentinel' );
-		if ( null === $sentinel_processor || ! $sentinel_processor->next_token() ) {
+		if ( ! $sentinel_processor->next_token() ) {
 			return false;
 		}
 
@@ -1726,9 +1722,6 @@ private function is_valid_declaration_value( string $value ): bool {
 
 		$sentinel_property = '--wp-style-attribute-processor-sentinel';
 		$processor         = WP_CSS_Token_Processor::create( $value . ';' . $sentinel_property . ':1' );
-		if ( null === $processor ) {
-			return false;
-		}
 
 		$stack            = array();
 		$top_level_tokens = array();

From 722e34c6546df8babc05d8ca94b24ca9514fb85d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 19:27:28 +0400
Subject: [PATCH 67/77] Construct WP_CSS_Token_Processor with a public
 constructor

Replace the static create() factory and private constructor with a
public __construct( string $css ).

A factory is useful when creation can fail, has several modes, or picks
the returned class. Since the encoding argument was removed, create()
does none of these. WP_HTML_Tag_Processor and WP_Block_Processor also
take their input through a public constructor.

This also removes the PHPStan new.static error: a subclass constructor
with another signature would make new static( $css ) throw a TypeError.
---
 .../css-api/class-wp-css-token-processor.php  | 27 ++++------------
 .../css-api/class-wp-css-token-serializer.php |  2 +-
 .../css-api/class-wp-css-token.php            |  6 ++--
 tests/phpunit/tests/css-api/wpCssBuilder.php  |  2 +-
 tests/phpunit/tests/css-api/wpCssToken.php    | 12 +++----
 .../tests/css-api/wpCssTokenProcessor.php     | 32 +++++++++----------
 .../tests/css-api/wpCssTokenSerializer.php    |  6 ++--
 7 files changed, 36 insertions(+), 51 deletions(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 7ab51df33c072..61e5568279c19 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -51,7 +51,7 @@
  * Basic iteration:
  *
  * ```php interactive
- * $processor = WP_CSS_Token_Processor::create( 'width: 10px;' );
+ * $processor = new WP_CSS_Token_Processor( 'width: 10px;' );
  * while ( $processor->next_token() ) {
  *     echo $processor->get_token_type() . "\n";
  * }
@@ -67,7 +67,7 @@
  *
  * ```php interactive
  * $css       = "color: red;\ncolor: \"re\nd\";";
- * $processor = WP_CSS_Token_Processor::create( $css );
+ * $processor = new WP_CSS_Token_Processor( $css );
  * while ( $processor->next_token() ) {
  *     if ( WP_CSS_Token_Processor::TOKEN_BAD_STRING === $processor->get_token_type() ) {
  *         echo "Bad string at byte {$processor->get_token_start()}, {$processor->get_token_length()} bytes long.\n";
@@ -403,34 +403,19 @@ class WP_CSS_Token_Processor {
 	private $token_is_terminated = true;
 
 	/**
-	 * Constructor for the CSS processor.
+	 * Constructor.
 	 *
-	 * Do not instantiate directly. Use WP_CSS_Token_Processor::create() instead.
+	 * The CSS is read as UTF-8. Convert CSS in another encoding to UTF-8 first.
 	 *
 	 * @since 7.3.0
-	 * @ignore
 	 *
 	 * @param string $css CSS source to tokenize.
 	 */
-	private function __construct( string $css ) {
+	public function __construct( string $css ) {
 		$this->css    = $css;
 		$this->length = strlen( $css );
 	}
 
-	/**
-	 * Creates a CSS processor for the given CSS string.
-	 *
-	 * The CSS is read as UTF-8. Convert CSS in another encoding to UTF-8 first.
-	 *
-	 * @since 7.3.0
-	 *
-	 * @param string $css CSS source to tokenize.
-	 * @return static The created processor.
-	 */
-	public static function create( string $css ) {
-		return new static( $css );
-	}
-
 	/**
 	 * Moves to the next token in the CSS stream.
 	 *
@@ -729,7 +714,7 @@ public function next_token(): bool {
 	 * Example:
 	 *
 	 * ```php interactive
-	 * $processor = WP_CSS_Token_Processor::create( 'a "b"' );
+	 * $processor = new WP_CSS_Token_Processor( 'a "b"' );
 	 * $tokens    = array();
 	 * while ( $processor->next_token() ) {
 	 *     $tokens[] = $processor->get_token();
diff --git a/src/wp-includes/css-api/class-wp-css-token-serializer.php b/src/wp-includes/css-api/class-wp-css-token-serializer.php
index d9103be9339b1..5a0e0683b8035 100644
--- a/src/wp-includes/css-api/class-wp-css-token-serializer.php
+++ b/src/wp-includes/css-api/class-wp-css-token-serializer.php
@@ -242,7 +242,7 @@ class WP_CSS_Token_Serializer {
 	 * Example:
 	 *
 	 * ```php interactive
-	 * $processor = WP_CSS_Token_Processor::create( 'url( a&b ) calc(1px  +  2px' );
+	 * $processor = new WP_CSS_Token_Processor( 'url( a&b ) calc(1px  +  2px' );
 	 * $tokens    = array();
 	 * while ( $processor->next_token() ) {
 	 *     $tokens[] = $processor->get_token();
diff --git a/src/wp-includes/css-api/class-wp-css-token.php b/src/wp-includes/css-api/class-wp-css-token.php
index 2af6b4202c2b9..55af708415637 100644
--- a/src/wp-includes/css-api/class-wp-css-token.php
+++ b/src/wp-includes/css-api/class-wp-css-token.php
@@ -17,7 +17,7 @@
  * Example:
  *
  * ```php interactive
- * $processor = WP_CSS_Token_Processor::create( 'font-family: "Exo\20 2"' );
+ * $processor = new WP_CSS_Token_Processor( 'font-family: "Exo\20 2"' );
  * $tokens    = array();
  * while ( $processor->next_token() ) {
  *     $tokens[] = $processor->get_token();
@@ -226,7 +226,7 @@ public function get_flag(): ?string {
 	 * Example:
 	 *
 	 * ```php interactive
-	 * $processor = WP_CSS_Token_Processor::create( '"a\\62 c"' );
+	 * $processor = new WP_CSS_Token_Processor( '"a\\62 c"' );
 	 * $processor->next_token();
 	 * echo $processor->get_token()->get_value();
 	 * // Outputs: abc
@@ -291,7 +291,7 @@ public function get_length(): int {
 	 * Example:
 	 *
 	 * ```php interactive
-	 * $processor = WP_CSS_Token_Processor::create( '"abc' );
+	 * $processor = new WP_CSS_Token_Processor( '"abc' );
 	 * $processor->next_token();
 	 * $token = $processor->get_token();
 	 * echo $token->get_type() . "\n";
diff --git a/tests/phpunit/tests/css-api/wpCssBuilder.php b/tests/phpunit/tests/css-api/wpCssBuilder.php
index 321ca42fd1b84..bba5a66e05ee8 100644
--- a/tests/phpunit/tests/css-api/wpCssBuilder.php
+++ b/tests/phpunit/tests/css-api/wpCssBuilder.php
@@ -136,7 +136,7 @@ public function test_docblock_examples(): void {
 	 * @return WP_CSS_Token[] Tokens.
 	 */
 	private static function tokenize( string $css ): array {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$tokens    = array();
 		while ( $processor->next_token() ) {
 			$tokens[] = $processor->get_token();
diff --git a/tests/phpunit/tests/css-api/wpCssToken.php b/tests/phpunit/tests/css-api/wpCssToken.php
index 5f052cc6af272..10fa39d42fb23 100644
--- a/tests/phpunit/tests/css-api/wpCssToken.php
+++ b/tests/phpunit/tests/css-api/wpCssToken.php
@@ -17,7 +17,7 @@ class Tests_CssApi_WpCssToken extends WP_UnitTestCase {
 	 * @covers WP_CSS_Token_Processor::get_token
 	 */
 	public function test_get_token_matches_spec( string $css, array $expected_tokens ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$tokens    = array();
 		while ( $processor->next_token() ) {
 			$tokens[] = $processor->get_token();
@@ -71,7 +71,7 @@ public static function data_corpus(): array {
 	 * @covers WP_CSS_Token_Processor::get_token
 	 */
 	public function test_get_token_returns_null_without_a_current_token(): void {
-		$processor = WP_CSS_Token_Processor::create( 'a' );
+		$processor = new WP_CSS_Token_Processor( 'a' );
 		$this->assertNull( $processor->get_token(), 'There is no token before next_token().' );
 
 		$this->assertTrue( $processor->next_token() );
@@ -89,7 +89,7 @@ public function test_get_token_returns_null_without_a_current_token(): void {
 	 * @covers ::get_value
 	 */
 	public function test_value_decodes_after_the_processor_moves_on(): void {
-		$processor = WP_CSS_Token_Processor::create( '\\66 oo "b\\61 r" url(b\\61 z) #\\31 a 1\\70 x' );
+		$processor = new WP_CSS_Token_Processor( '\\66 oo "b\\61 r" url(b\\61 z) #\\31 a 1\\70 x' );
 		$tokens    = array();
 		while ( $processor->next_token() ) {
 			$tokens[] = $processor->get_token();
@@ -126,7 +126,7 @@ public function test_value_decodes_after_the_processor_moves_on(): void {
 	 * @covers ::get_flag
 	 */
 	public function test_flag( string $css, string $expected_type, ?string $expected_flag ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$this->assertTrue( $processor->next_token() );
 
 		$token = $processor->get_token();
@@ -162,7 +162,7 @@ public static function data_flag(): array {
 	 * @covers ::is_terminated
 	 */
 	public function test_is_terminated( string $css, bool $expected ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$this->assertTrue( $processor->next_token() );
 
 		$token = $processor->get_token();
@@ -196,7 +196,7 @@ public static function data_is_terminated(): array {
 	 * @covers ::get_value
 	 */
 	public function test_comment_value( string $css, string $expected ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_COMMENT, $processor->get_token_type() );
 
diff --git a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
index 140b538b5c287..c4c190e87cec9 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenProcessor.php
@@ -34,7 +34,7 @@ public static function corpus_provider(): array {
 	 * @return array Array of tokens with type, raw, startIndex, endIndex, value, unit and numberType.
 	 */
 	public static function collect_tokens( string $css, ?array $keys = null ): array {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$tokens    = array();
 
 		while ( $processor->next_token() ) {
@@ -77,7 +77,7 @@ public static function collect_tokens( string $css, ?array $keys = null ): array
 	 * @dataProvider data_string_backslash_newline
 	 */
 	public function test_string_backslash_newline( string $css, string $expected_value ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
@@ -104,7 +104,7 @@ public static function data_string_backslash_newline(): array {
 	 * @ticket 65738
 	 */
 	public function test_string_backslash_eof(): void {
-		$processor = WP_CSS_Token_Processor::create( "'string\\" );
+		$processor = new WP_CSS_Token_Processor( "'string\\" );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
@@ -118,7 +118,7 @@ public function test_string_backslash_eof(): void {
 	 * @dataProvider data_url_backslash_newline
 	 */
 	public function test_url_backslash_newline( string $css ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_URL, $processor->get_token_type() );
@@ -144,7 +144,7 @@ public static function data_url_backslash_newline(): array {
 	 * @ticket 65738
 	 */
 	public function test_url_backslash_eof(): void {
-		$processor = WP_CSS_Token_Processor::create( 'url(string\\' );
+		$processor = new WP_CSS_Token_Processor( 'url(string\\' );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_URL, $processor->get_token_type() );
@@ -161,7 +161,7 @@ public function test_url_backslash_eof(): void {
 	 * @dataProvider data_preprocessed_token_keeps_source_bytes
 	 */
 	public function test_preprocessed_token_keeps_source_bytes( string $css, string $expected_type, ?string $expected_value ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( $expected_type, $processor->get_token_type() );
@@ -208,7 +208,7 @@ public static function data_preprocessed_token_keeps_source_bytes(): Generator {
 	 * @dataProvider data_ident_backslash_newline
 	 */
 	public function test_ident_backslash_newline( string $css ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
@@ -235,7 +235,7 @@ public static function data_ident_backslash_newline(): array {
 	 * @ticket 65738
 	 */
 	public function test_ident_backslash_eof(): void {
-		$processor = WP_CSS_Token_Processor::create( 'abc\\' );
+		$processor = new WP_CSS_Token_Processor( 'abc\\' );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_IDENT, $processor->get_token_type() );
@@ -248,7 +248,7 @@ public function test_ident_backslash_eof(): void {
 	 * @ticket 65738
 	 */
 	public function test_bad_string_token_value_is_null(): void {
-		$processor = WP_CSS_Token_Processor::create( "'str\ning'" );
+		$processor = new WP_CSS_Token_Processor( "'str\ning'" );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
@@ -262,7 +262,7 @@ public function test_bad_string_token_value_is_null(): void {
 	 * @dataProvider data_is_terminated
 	 */
 	public function test_is_terminated( string $css, string $expected_type, bool $expected ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertNull( $processor->get_token(), 'Before the first token there is nothing to report.' );
 
@@ -316,7 +316,7 @@ public static function data_is_terminated(): array {
 	 * @ticket 65738
 	 */
 	public function test_is_terminated_resets_between_tokens(): void {
-		$processor = WP_CSS_Token_Processor::create( "'a\nb" );
+		$processor = new WP_CSS_Token_Processor( "'a\nb" );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_BAD_STRING, $processor->get_token_type() );
@@ -338,7 +338,7 @@ public function test_is_terminated_resets_between_tokens(): void {
 	 * @dataProvider data_hash_tokens_expose_type_flags
 	 */
 	public function test_hash_tokens_expose_type_flags( string $css, array $expected_tokens ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		foreach ( $expected_tokens as $expected_token ) {
 			$this->assertTrue( $processor->next_token() );
@@ -447,7 +447,7 @@ public static function data_hash_tokens_expose_type_flags(): array {
 	 * @dataProvider data_token_type_flag
 	 */
 	public function test_token_type_flag( string $css, ?string $expected_type ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( $expected_type, $processor->get_token()->get_flag() );
@@ -2183,7 +2183,7 @@ public function test_token_values_are_decoded_and_normalized(): void {
 	 * @dataProvider data_comment_value
 	 */
 	public function test_comment_value_keeps_escapes( string $css, string $expected ): void {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_COMMENT, $processor->get_token_type() );
 
@@ -2586,7 +2586,7 @@ public function test_escape_sequences_in_unusual_places() {
 	 * the closing quote must not appear in the token value.
 	 */
 	public function test_decode_range_respects_length_boundary(): void {
-		$processor = WP_CSS_Token_Processor::create( '"hello\\41 world"; color: red;' );
+		$processor = new WP_CSS_Token_Processor( '"hello\\41 world"; color: red;' );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
@@ -2599,7 +2599,7 @@ public function test_decode_range_respects_length_boundary(): void {
 	 * @link https://www.w3.org/TR/css-syntax-3/#consume-escaped-code-point
 	 */
 	public function test_decode_escape_at_hex_limit_is_six_digits(): void {
-		$processor = WP_CSS_Token_Processor::create( '"\\0000411rest"' );
+		$processor = new WP_CSS_Token_Processor( '"\\0000411rest"' );
 
 		$this->assertTrue( $processor->next_token() );
 		$this->assertSame( WP_CSS_Token_Processor::TOKEN_STRING, $processor->get_token_type() );
diff --git a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
index 22a9d31a3f3a7..07259163a8475 100644
--- a/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
+++ b/tests/phpunit/tests/css-api/wpCssTokenSerializer.php
@@ -95,7 +95,7 @@ public function test_ident( string $input, string $expected ): void {
 		$serialized = WP_CSS_Token_Serializer::escape_ident( $input );
 		$this->assertSame( $expected, $serialized );
 
-		$processor = WP_CSS_Token_Processor::create( $serialized );
+		$processor = new WP_CSS_Token_Processor( $serialized );
 		if ( '' === $input ) {
 			$this->assertFalse( $processor->next_token() );
 			return;
@@ -490,7 +490,7 @@ public static function data_hash_flag_round_trips(): array {
 	 */
 	public function test_serialize_accepts_a_generator(): void {
 		$generator = ( static function ( string $css ): Generator {
-			$processor = WP_CSS_Token_Processor::create( $css );
+			$processor = new WP_CSS_Token_Processor( $css );
 			while ( $processor->next_token() ) {
 				yield $processor->get_token();
 			}
@@ -550,7 +550,7 @@ static function ( array $test_case ): array {
 	 * @return WP_CSS_Token[] Tokens.
 	 */
 	private static function tokenize( string $css ): array {
-		$processor = WP_CSS_Token_Processor::create( $css );
+		$processor = new WP_CSS_Token_Processor( $css );
 		$tokens    = array();
 		while ( $processor->next_token() ) {
 			$tokens[] = $processor->get_token();

From 23f7c710a4d2fa6c2bf06b5a36868fdafba3274a Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 19:27:45 +0400
Subject: [PATCH 68/77] Remove an always-true null check in
 consume_ident_codepoint()

utf8_ord() returns an int, and _wp_scan_utf8() has already confirmed
that the bytes are one valid code point.
---
 src/wp-includes/css-api/class-wp-css-token-processor.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 61e5568279c19..82bcab05af5af 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -1398,7 +1398,7 @@ private function consume_ident_start_codepoint( $at ): int {
 
 		$codepoint_byte_length = $new_at - $at;
 		$codepoint             = self::utf8_ord( substr( $this->css, $at, $codepoint_byte_length ) );
-		if ( null !== $codepoint && $codepoint >= 0x80 ) {
+		if ( $codepoint >= 0x80 ) {
 			return $codepoint_byte_length;
 		}
 		return 0;

From 0419f88d54c4a3f6c88f29ec0d2093a49aad218b Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 19:28:33 +0400
Subject: [PATCH 69/77] Construct the CSS tokenizer with its public constructor

---
 .../class-wp-html-style-attribute-processor.php        | 10 +++++-----
 .../tests/html-api/wpHtmlStyleAttributeProcessor.php   |  2 +-
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 6dc7c007413cf..7a5797c86814f 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -582,7 +582,7 @@ private function parse(): void {
 		$this->tokens       = array();
 		$this->declarations = array();
 
-		$processor = WP_CSS_Token_Processor::create( $this->style );
+		$processor = new WP_CSS_Token_Processor( $this->style );
 
 		while ( $processor->next_token() ) {
 			$this->tokens[] = $processor->get_token();
@@ -1535,7 +1535,7 @@ private function format_declaration( string $property_name, string $value, bool
 	 * @return string Value text.
 	 */
 	private function serialize_value( string $value ): string {
-		$processor = WP_CSS_Token_Processor::create( $value );
+		$processor = new WP_CSS_Token_Processor( $value );
 		$tokens    = array();
 		while ( $processor->next_token() ) {
 			$tokens[] = $processor->get_token();
@@ -1670,7 +1670,7 @@ private function is_valid_property_name( string $property_name ): bool {
 			return false;
 		}
 
-		$processor = WP_CSS_Token_Processor::create( $property_name );
+		$processor = new WP_CSS_Token_Processor( $property_name );
 		if ( ! $processor->next_token() ) {
 			return false;
 		}
@@ -1687,7 +1687,7 @@ private function is_valid_property_name( string $property_name ): bool {
 			return false;
 		}
 
-		$sentinel_processor = WP_CSS_Token_Processor::create( $property_name . ': sentinel' );
+		$sentinel_processor = new WP_CSS_Token_Processor( $property_name . ': sentinel' );
 		if ( ! $sentinel_processor->next_token() ) {
 			return false;
 		}
@@ -1721,7 +1721,7 @@ private function is_valid_declaration_value( string $value ): bool {
 		}
 
 		$sentinel_property = '--wp-style-attribute-processor-sentinel';
-		$processor         = WP_CSS_Token_Processor::create( $value . ';' . $sentinel_property . ':1' );
+		$processor         = new WP_CSS_Token_Processor( $value . ';' . $sentinel_property . ':1' );
 
 		$stack            = array();
 		$top_level_tokens = array();
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 5854b71a03f37..f4e177c50c1d9 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -238,7 +238,7 @@ public function test_get_value_tokens_match_the_retokenized_source_slice( string
 		$slice = substr( $style, $first->get_start(), $last->get_start() + $last->get_length() - $first->get_start() );
 
 		$expected  = array();
-		$tokenizer = WP_CSS_Token_Processor::create( $slice );
+		$tokenizer = new WP_CSS_Token_Processor( $slice );
 		while ( $tokenizer->next_token() ) {
 			$token      = $tokenizer->get_token();
 			$expected[] = array( $token->get_type(), $token->get_flag(), $token->get_value(), $token->get_unit(), $token->is_terminated() );

From 6e82fe842ec1448bfbd04b8e3e1d785f6e29feb9 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 19:27:45 +0400
Subject: [PATCH 70/77] Remove an always-true null check in
 consume_ident_start_codepoint()

utf8_ord() returns an int, and _wp_scan_utf8() has already confirmed
that the bytes are one valid code point.
---
 src/wp-includes/css-api/class-wp-css-token-processor.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 61e5568279c19..82bcab05af5af 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -1398,7 +1398,7 @@ private function consume_ident_start_codepoint( $at ): int {
 
 		$codepoint_byte_length = $new_at - $at;
 		$codepoint             = self::utf8_ord( substr( $this->css, $at, $codepoint_byte_length ) );
-		if ( null !== $codepoint && $codepoint >= 0x80 ) {
+		if ( $codepoint >= 0x80 ) {
 			return $codepoint_byte_length;
 		}
 		return 0;

From 93b9252cc67d174a3cf5f2665aaa23fb9033bd19 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 19:38:37 +0400
Subject: [PATCH 71/77] Construct WP_HTML_Style_Attribute_Processor with a
 public constructor

Replace the private constructor and the static create() method with a
public constructor, as WP_CSS_Token_Processor now has. The parameter
stays untyped so that PHP 7.4 can accept `true` and `null`.

WP_HTML_Tag_Processor::get_attribute() returns `true` for a boolean
style attribute and `null` for a missing one. The constructor reads both
as an empty style, so its result can be passed in directly. Any other
type that is not a string throws a TypeError, as create() did.
---
 ...lass-wp-html-style-attribute-processor.php |  35 +--
 .../wpHtmlStyleAttributeProcessor.php         | 252 +++++++++++-------
 2 files changed, 175 insertions(+), 112 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 7a5797c86814f..cc8c8d5e455a6 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -15,12 +15,11 @@
  * delimiting braces. It does not parse HTML attribute syntax, decode character
  * references, or operate on raw HTML markup.
  *
- * String values read from {@see WP_HTML_Tag_Processor::get_attribute()} can be
- * passed to this class, and values returned by
+ * Values read from {@see WP_HTML_Tag_Processor::get_attribute()} can be passed
+ * to the constructor, and values returned by
  * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} can be passed
- * back to {@see WP_HTML_Tag_Processor::set_attribute()}. Missing and boolean
- * style attributes are an HTML concern and must be handled before creating this
- * processor.
+ * back to {@see WP_HTML_Tag_Processor::set_attribute()}. A missing (`null`) or
+ * boolean (`true`) style attribute gives an empty style.
  *
  * Unlike associative-array based style helpers, this processor preserves the
  * declaration list model of CSS. Multiple declarations with the same property
@@ -134,32 +133,22 @@ class WP_HTML_Style_Attribute_Processor {
 	/**
 	 * Constructor.
 	 *
-	 * Do not instantiate directly. Use
-	 * {@see WP_HTML_Style_Attribute_Processor::create()} instead.
+	 * `true` and `null` give an empty style.
 	 *
 	 * @since 7.3.0
-	 * @ignore
 	 *
-	 * @param string $style Decoded CSS text value from a style attribute.
+	 * @param string|true|null $decoded_css_text Decoded CSS text value from a style attribute.
 	 */
-	private function __construct( string $style ) {
-		$this->style = $style;
-	}
+	public function __construct( $decoded_css_text ) {
+		if ( true === $decoded_css_text || null === $decoded_css_text ) {
+			$decoded_css_text = '';
+		}
 
-	/**
-	 * Creates a processor for decoded CSS text from a style attribute.
-	 *
-	 * @since 7.3.0
-	 *
-	 * @param string $decoded_css_text Decoded CSS text value from a style attribute.
-	 * @return static Created processor.
-	 */
-	public static function create( $decoded_css_text ) {
 		if ( ! is_string( $decoded_css_text ) ) {
 			throw new TypeError( __METHOD__ . '(): Argument #1 ($decoded_css_text) must be of type string' );
 		}
 
-		return new static( $decoded_css_text );
+		$this->style = $decoded_css_text;
 	}
 
 	/**
@@ -231,7 +220,7 @@ public function is_important(): ?bool {
 	 *
 	 * Token offsets index the current style text, which
 	 * {@see WP_HTML_Style_Attribute_Processor::get_updated_style()} returns.
-	 * Before any mutation that is the text passed to `create()`.
+	 * Before any mutation that is the text passed to the constructor.
 	 *
 	 * @since 7.3.0
 	 *
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index f4e177c50c1d9..29eb9d4be315c 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -13,37 +13,108 @@
  */
 class Tests_HtmlApi_WpHtmlStyleAttributeProcessor extends WP_UnitTestCase {
 	/**
-	 * @covers ::create
+	 * @covers ::__construct
 	 * @covers ::get_updated_style
 	 */
-	public function test_create_accepts_decoded_css_text_strings() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red' );
+	public function test_constructor_accepts_decoded_css_text_strings() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red' );
 
 		$this->assertSame( 'color: red', $processor->get_updated_style() );
 	}
 
 	/**
-	 * @covers ::create
+	 * @ticket 65738
 	 *
-	 * @dataProvider data_non_string_style_attribute_values
+	 * @covers ::__construct
+	 * @covers ::next_declaration
+	 * @covers ::get_updated_style
 	 *
-	 * @param mixed $style_attribute_value Non-string style attribute value.
+	 * @dataProvider data_boolean_and_missing_style_attribute_values
+	 *
+	 * @param true|null $style_attribute_value Value of a boolean or missing style attribute.
 	 */
-	public function test_create_rejects_non_string_style_attribute_values( $style_attribute_value ) {
-		$this->expectException( TypeError::class );
+	public function test_constructor_reads_true_and_null_as_an_empty_style( $style_attribute_value ) {
+		$processor = new WP_HTML_Style_Attribute_Processor( $style_attribute_value );
 
-		WP_HTML_Style_Attribute_Processor::create( $style_attribute_value );
+		$this->assertFalse( $processor->next_declaration() );
+		$this->assertSame( '', $processor->get_updated_style() );
 	}
 
 	/**
-	 * @coversNothing
+	 * @ticket 65738
+	 *
+	 * @covers ::__construct
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_boolean_and_missing_style_attribute_values
+	 *
+	 * @param true|null $style_attribute_value Value of a boolean or missing style attribute.
 	 */
-	public function test_constructor_is_not_public() {
-		$reflection  = new ReflectionClass( WP_HTML_Style_Attribute_Processor::class );
-		$constructor = $reflection->getConstructor();
+	public function test_append_declaration_to_a_style_read_from_true_or_null( $style_attribute_value ) {
+		$processor = new WP_HTML_Style_Attribute_Processor( $style_attribute_value );
 
-		$this->assertNotNull( $constructor );
-		$this->assertFalse( $constructor->isPublic() );
+		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
+		$this->assertSame( 'color: red;', $processor->get_updated_style() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{true|null}>
+	 */
+	public static function data_boolean_and_missing_style_attribute_values(): array {
+		return array(
+			'missing style attribute' => array( null ),
+			'boolean style attribute' => array( true ),
+		);
+	}
+
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::__construct
+	 * @covers ::append_declaration
+	 * @covers ::get_updated_style
+	 *
+	 * @dataProvider data_html_with_boolean_and_missing_style_attributes
+	 *
+	 * @param string $html HTML with a `div` whose style attribute is boolean or missing.
+	 */
+	public function test_style_from_get_attribute_on_a_boolean_or_missing_attribute_can_be_appended_to( string $html ) {
+		$tags = new WP_HTML_Tag_Processor( $html );
+		$this->assertTrue( $tags->next_tag( 'div' ) );
+
+		$styles = new WP_HTML_Style_Attribute_Processor( $tags->get_attribute( 'style' ) );
+		$this->assertTrue( $styles->append_declaration( 'color', 'red' ) );
+		$this->assertTrue( $tags->set_attribute( 'style', $styles->get_updated_style() ) );
+
+		$this->assertSame( '<div style="color: red;"></div>', $tags->get_updated_html() );
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string}>
+	 */
+	public static function data_html_with_boolean_and_missing_style_attributes(): array {
+		return array(
+			'missing style attribute' => array( '<div></div>' ),
+			'boolean style attribute' => array( '<div style></div>' ),
+		);
+	}
+
+	/**
+	 * @covers ::__construct
+	 *
+	 * @dataProvider data_non_string_style_attribute_values
+	 *
+	 * @param mixed $style_attribute_value Value other than a string, `true` or `null`.
+	 */
+	public function test_constructor_rejects_other_types( $style_attribute_value ) {
+		$this->expectException( TypeError::class );
+
+		new WP_HTML_Style_Attribute_Processor( $style_attribute_value );
 	}
 
 	/**
@@ -61,7 +132,7 @@ public function test_raw_value_getter_is_not_public_api() {
 	 * @covers ::is_important
 	 */
 	public function test_next_declaration_reads_properties_in_order_and_preserves_duplicates() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'COLOR: red; color: blue !important; background: white' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'COLOR: red; color: blue !important; background: white' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'color', $processor->get_property_name() );
@@ -84,7 +155,7 @@ public function test_next_declaration_reads_properties_in_order_and_preserves_du
 	 * @covers ::get_property_name
 	 */
 	public function test_next_declaration_query_visits_matching_duplicate_properties() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white; COLOR: blue;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white; COLOR: blue;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertSame( 'color', $processor->get_property_name() );
@@ -100,7 +171,7 @@ public function test_next_declaration_query_visits_matching_duplicate_properties
 	 * @covers ::get_property_name
 	 */
 	public function test_custom_property_queries_match_exact_decoded_casing() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '--Tone: warm; --tone: cool;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '--Tone: warm; --tone: cool;' );
 
 		$this->assertTrue( $processor->next_declaration( '--tone' ) );
 		$this->assertSame( '--tone', $processor->get_property_name() );
@@ -112,7 +183,7 @@ public function test_custom_property_queries_match_exact_decoded_casing() {
 	 * @covers ::next_declaration
 	 */
 	public function test_next_declaration_accepts_named_property_name_argument() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertSame( 'background', $processor->get_property_name() );
@@ -127,7 +198,7 @@ public function test_next_declaration_accepts_named_property_name_argument() {
 	 * @param bool   $important Expected importance.
 	 */
 	public function test_important_priority_syntax_variants( string $style, bool $important ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( $important, $processor->is_important() );
@@ -139,7 +210,7 @@ public function test_important_priority_syntax_variants( string $style, bool $im
 	 * @covers ::get_value_tokens
 	 */
 	public function test_get_value_tokens_returns_null_when_not_on_a_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white' );
 
 		$this->assertNull( $processor->get_value_tokens(), 'Expected null before the first declaration.' );
 
@@ -162,7 +233,7 @@ public function test_get_value_tokens_returns_null_when_not_on_a_declaration() {
 	 * @param array  $expected_tokens Expected value tokens.
 	 */
 	public function test_get_value_tokens_covers_only_the_declaration_value( string $style, array $expected_tokens ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$tokens = $processor->get_value_tokens();
@@ -178,7 +249,7 @@ public function test_get_value_tokens_covers_only_the_declaration_value( string
 	 */
 	public function test_get_value_tokens_decodes_values_and_keeps_source_offsets() {
 		$style     = 'content: "a\\"b"';
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$tokens = $processor->get_value_tokens();
@@ -197,7 +268,7 @@ public function test_get_value_tokens_decodes_values_and_keeps_source_offsets()
 	 * @covers ::remove_declaration
 	 */
 	public function test_get_value_tokens_follow_the_updated_style_after_mutations() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( 'green' ) );
@@ -227,7 +298,7 @@ public function test_get_value_tokens_follow_the_updated_style_after_mutations()
 	 * @param string $style Style text.
 	 */
 	public function test_get_value_tokens_match_the_retokenized_source_slice( string $style ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$tokens = $processor->get_value_tokens();
@@ -261,7 +332,7 @@ static function ( WP_CSS_Token $token ): array {
 	 * @covers ::remove_declaration
 	 */
 	public function test_serialize_declaration_returns_null_when_not_on_a_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white' );
 
 		$this->assertNull( $processor->serialize_declaration(), 'Expected null before the first declaration.' );
 
@@ -285,7 +356,7 @@ public function test_serialize_declaration_returns_null_when_not_on_a_declaratio
 	 * @param string $expected Expected text of the first declaration.
 	 */
 	public function test_serialize_declaration_writes_the_current_declaration( string $style, string $expected ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( $expected, $processor->serialize_declaration() );
@@ -327,10 +398,10 @@ public static function data_serialized_declarations(): array {
 	 * @param string $style Style text.
 	 */
 	public function test_serialize_declaration_reads_back_as_the_same_declaration( string $style ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 		$this->assertTrue( $processor->next_declaration() );
 
-		$reread = WP_HTML_Style_Attribute_Processor::create( $processor->serialize_declaration() );
+		$reread = new WP_HTML_Style_Attribute_Processor( $processor->serialize_declaration() );
 		$this->assertTrue( $reread->next_declaration() );
 
 		$this->assertSame( $processor->get_property_name(), $reread->get_property_name() );
@@ -349,7 +420,7 @@ public function test_serialize_declaration_reads_back_as_the_same_declaration( s
 	 * @covers ::set_value
 	 */
 	public function test_serialize_declaration_follows_mutations() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertTrue( $processor->set_value( 'green /* c */', true ) );
@@ -399,7 +470,7 @@ private static function significant_tokens( array $tokens ): array {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_value_updates_current_declaration_without_collapsing_duplicates() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red !important; color: color(display-p3 1 0 0);' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; color: color(display-p3 1 0 0);' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( 'green', false ) );
@@ -413,7 +484,7 @@ public function test_set_value_updates_current_declaration_without_collapsing_du
 	 * @covers ::get_updated_style
 	 */
 	public function test_declaration_values_allow_leading_and_trailing_comments_as_trivia() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( '/* before */ green /* after */' ) );
@@ -435,13 +506,13 @@ public function test_declaration_values_allow_leading_and_trailing_comments_as_t
 	 * @param string $written Expected value text in the updated style.
 	 */
 	public function test_trimming_a_value_keeps_its_final_escape_or_backslash_delimiter( string $value, string $written ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: 1; width: 1px' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '--x: 1; width: 1px' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertTrue( $processor->set_value( $value ), 'Expected set_value() to succeed.' );
 		$this->assertSame( "--x: {$written}; width: 1px", $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: 1px' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'width: 1px' );
 
 		$this->assertTrue( $processor->append_declaration( '--x', $value ), 'Expected append_declaration() to succeed.' );
 		$this->assertSame( "width: 1px; --x: {$written};", $processor->get_updated_style() );
@@ -477,13 +548,13 @@ public static function data_values_ending_in_escaped_whitespace_or_a_backslash_d
 	 * @param string $written Expected value text in the updated style.
 	 */
 	public function test_set_value_and_append_declaration_write_the_value_from_its_tokens( string $value, string $written ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: 1; width: 1px' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '--x: 1; width: 1px' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertTrue( $processor->set_value( $value ), 'Expected set_value() to succeed.' );
 		$this->assertSame( "--x: {$written}; width: 1px", $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: 1px' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'width: 1px' );
 
 		$this->assertTrue( $processor->append_declaration( '--x', $value ), 'Expected append_declaration() to succeed.' );
 		$this->assertSame( "width: 1px; --x: {$written};", $processor->get_updated_style() );
@@ -514,13 +585,13 @@ public static function data_values_written_from_tokens() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_value_and_append_declaration_write_the_name_as_an_identifier() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'C\\6f LOR: red' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'C\\6f LOR: red' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertTrue( $processor->set_value( 'blue' ) );
 		$this->assertSame( 'color: blue;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
 
 		$this->assertTrue( $processor->append_declaration( "--a\u{A0}b", '1' ) );
 		$this->assertSame( '--a\\a0 b: 1;', $processor->get_updated_style() );
@@ -531,7 +602,7 @@ public function test_set_value_and_append_declaration_write_the_name_as_an_ident
 	 * @covers ::is_important
 	 */
 	public function test_set_value_preserves_sets_and_clears_importance() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red !important; background: white; border-color: black;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red !important; background: white; border-color: black;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( 'green' ) );
@@ -555,7 +626,7 @@ public function test_set_value_preserves_sets_and_clears_importance() {
 	 * @covers ::set_value
 	 */
 	public function test_set_value_rejects_empty_value() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertFalse( $processor->set_value( '' ) );
@@ -570,7 +641,7 @@ public function test_set_value_rejects_empty_value() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_value_rejects_css_whitespace_only_values_without_removing_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertFalse( $processor->set_value( " \t\n\r\f" ) );
@@ -584,7 +655,7 @@ public function test_set_value_rejects_css_whitespace_only_values_without_removi
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_important_sets_and_clears_priority() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white ! /*x*/ important;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white ! /*x*/ important;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_important( true ) );
@@ -602,49 +673,49 @@ public function test_set_important_sets_and_clears_priority() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_important_can_repair_unclosed_eof_component_values() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'color: var(--x) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x /*c*/' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x /*c*/' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'color: var(--x /*c*/) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'background: url(foo) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x ' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x ' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'color: var(--x ) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x /*c*/ ' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x /*c*/ ' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'color: var(--x /*c*/ ) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo ' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo ' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertTrue( $processor->set_important( true ) );
 		$this->assertTrue( $processor->is_important() );
 		$this->assertSame( 'background: url(foo ) !important', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo\\)' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo\\)' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertTrue( $processor->set_important( true ) );
@@ -656,7 +727,7 @@ public function test_set_important_can_repair_unclosed_eof_component_values() {
 	 * @covers ::set_important
 	 */
 	public function test_set_important_returns_false_without_current_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertFalse( $processor->set_important( true ) );
 	}
@@ -666,7 +737,7 @@ public function test_set_important_returns_false_without_current_declaration() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_removes_only_current_duplicate() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; color: blue; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
@@ -680,7 +751,7 @@ public function test_remove_declaration_removes_only_current_duplicate() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_removes_adjacent_duplicate_declarations() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; color: blue; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; color: blue; background: white;' );
 
 		while ( $processor->next_declaration( 'color' ) ) {
 			$this->assertTrue( $processor->remove_declaration() );
@@ -696,7 +767,7 @@ public function test_remove_declaration_removes_adjacent_duplicate_declarations(
 	 * @covers ::get_value_tokens
 	 */
 	public function test_getters_return_null_after_removing_current_declaration_until_cursor_advances() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
@@ -715,19 +786,19 @@ public function test_getters_return_null_after_removing_current_declaration_unti
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_preserves_surrounding_comments() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '/*keep*/ color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/ color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; /*keep*/ background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
 		$this->assertSame( '/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; /*keep*/ background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; /*keep*/ background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'background' ) );
 		$this->assertTrue( $processor->remove_declaration() );
@@ -739,7 +810,7 @@ public function test_remove_declaration_preserves_surrounding_comments() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_remove_declaration_with_invalid_fragments_preserves_remaining_structure() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; invalid; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; invalid; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
@@ -754,7 +825,7 @@ public function test_remove_declaration_with_invalid_fragments_preserves_remaini
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_adds_duplicate_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'color(display-p3 1 0 0)', true ) );
 
@@ -766,7 +837,7 @@ public function test_append_declaration_adds_duplicate_declaration() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_preserves_multiple_appends_in_order() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
@@ -785,7 +856,7 @@ public function test_append_declaration_preserves_multiple_appends_in_order() {
 	 * @covers ::set_value
 	 */
 	public function test_mixed_mutations_preserve_the_logical_cursor_and_declaration_order() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->set_value( 'green', true ) );
@@ -812,17 +883,17 @@ public function test_mixed_mutations_preserve_the_logical_cursor_and_declaration
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_treats_comments_as_trivia_for_separators() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '/*keep*/' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '/*keep*/' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertSame( '/*keep*/ color: red;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;/*keep*/' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;/*keep*/' );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( 'color: red;/*keep*/ background: white;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x;/*keep*/);' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x;/*keep*/);' );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( 'color: var(--x;/*keep*/); background: white;', $processor->get_updated_style() );
@@ -833,7 +904,7 @@ public function test_append_declaration_treats_comments_as_trivia_for_separators
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_lowercases_ordinary_properties_and_preserves_custom_properties() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
 
 		$this->assertTrue( $processor->append_declaration( 'BackgroundColor', 'red' ) );
 		$this->assertTrue( $processor->append_declaration( '--Tone', 'warm' ) );
@@ -847,7 +918,7 @@ public function test_append_declaration_lowercases_ordinary_properties_and_prese
 	 * @covers ::get_property_name
 	 */
 	public function test_appended_declarations_can_be_inspected_by_the_cursor() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 
@@ -862,7 +933,7 @@ public function test_appended_declarations_can_be_inspected_by_the_cursor() {
 	 * @covers ::set_value
 	 */
 	public function test_append_declaration_preserves_exhausted_cursor_until_it_advances() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertFalse( $processor->next_declaration() );
@@ -883,7 +954,7 @@ public function test_append_declaration_preserves_exhausted_cursor_until_it_adva
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_after_removing_only_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;   ' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;   ' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertTrue( $processor->remove_declaration() );
@@ -897,27 +968,27 @@ public function test_append_declaration_after_removing_only_declaration() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_repairs_unclosed_eof_component_values() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x' );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( 'color: var(--x); background: white;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'width: calc(1px + var(--gap' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'width: calc(1px + var(--gap' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertSame( 'width: calc(1px + var(--gap)); color: red;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo' );
 
 		$this->assertTrue( $processor->append_declaration( 'color', 'red' ) );
 		$this->assertSame( 'background: url(foo); color: red;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo ' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo ' );
 
 		$this->assertTrue( $processor->append_declaration( 'border', '0' ) );
 		$this->assertSame( 'background: url(foo ); border: 0;', $processor->get_updated_style() );
 
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'background: url(foo\\)' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'background: url(foo\\)' );
 
 		$this->assertTrue( $processor->append_declaration( 'border', '0' ) );
 		$this->assertSame( 'background: url(foo\\)); border: 0;', $processor->get_updated_style() );
@@ -935,7 +1006,7 @@ public function test_append_declaration_repairs_unclosed_eof_component_values()
 	 * @param string $expected Updated style text.
 	 */
 	public function test_append_declaration_closes_strings_and_comments_left_open( string $style, string $expected ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( $expected, $processor->get_updated_style() );
@@ -965,7 +1036,7 @@ public static function data_styles_ending_inside_a_string_or_comment(): array {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_important_closes_a_string_left_open() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'font-family: "a' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'font-family: "a' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertTrue( $processor->set_important( true ) );
@@ -981,7 +1052,7 @@ public function test_set_important_closes_a_string_left_open() {
 	 * @param string $style Style text.
 	 */
 	public function test_append_declaration_rejects_eof_repairs_that_cannot_be_precise( string $style ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertFalse( $processor->append_declaration( 'background', 'white' ) );
 		$this->assertSame( $style, $processor->get_updated_style() );
@@ -1005,7 +1076,7 @@ public static function data_styles_ending_in_a_backslash(): array {
 	 */
 	public function test_invalid_fragments_are_skipped_and_preserved() {
 		$style     = 'color red; @media (min-width: 1px) { color: green; } background: white;';
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
@@ -1017,7 +1088,7 @@ public function test_invalid_fragments_are_skipped_and_preserved() {
 	 * @covers ::next_declaration
 	 */
 	public function test_stray_right_brace_consumes_bad_declaration_until_semicolon() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '} color: red; background: white;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '} color: red; background: white;' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'background', $processor->get_property_name() );
@@ -1033,7 +1104,7 @@ public function test_stray_right_brace_consumes_bad_declaration_until_semicolon(
 	 * @param string $style Style attribute value whose first declaration CSS ignores.
 	 */
 	public function test_declarations_with_values_css_ignores_are_skipped_and_preserved( string $style ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( $style );
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( 'color', $processor->get_property_name() );
@@ -1045,7 +1116,7 @@ public function test_declarations_with_values_css_ignores_are_skipped_and_preser
 	 * @covers ::next_declaration
 	 */
 	public function test_custom_property_values_may_mix_blocks_with_other_tokens() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '--x: { a } b; color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '--x: { a } b; color: red;' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertSame( '--x', $processor->get_property_name() );
@@ -1059,7 +1130,7 @@ public function test_custom_property_values_may_mix_blocks_with_other_tokens() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_escaped_property_names_match_decoded_names_and_are_written_as_identifiers() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'c\\6f lor: red; --t\\6f ne: cool; --Tone: warm;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertSame( 'color', $processor->get_property_name() );
@@ -1078,7 +1149,7 @@ public function test_escaped_property_names_match_decoded_names_and_are_written_
 	 * @covers ::is_important
 	 */
 	public function test_important_inside_unclosed_function_is_not_declaration_priority() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: var(--x, red !important' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: var(--x, red !important' );
 
 		$this->assertTrue( $processor->next_declaration() );
 		$this->assertFalse( $processor->is_important() );
@@ -1090,7 +1161,7 @@ public function test_important_inside_unclosed_function_is_not_declaration_prior
 	 * @covers ::get_updated_style
 	 */
 	public function test_declaration_values_reject_top_level_semicolons_and_important_priority() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertFalse( $processor->set_value( 'blue; color: green' ) );
@@ -1108,7 +1179,7 @@ public function test_declaration_values_reject_top_level_semicolons_and_importan
 	 * @covers ::get_updated_style
 	 */
 	public function test_append_declaration_rejects_empty_values() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertFalse( $processor->append_declaration( 'background', '' ) );
 		$this->assertFalse( $processor->append_declaration( 'background', '/* comment */' ) );
@@ -1120,7 +1191,7 @@ public function test_append_declaration_rejects_empty_values() {
 	 * @covers ::get_updated_style
 	 */
 	public function test_set_value_rejects_comment_only_values_without_removing_declaration() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertFalse( $processor->set_value( '/* comment */' ) );
@@ -1138,7 +1209,7 @@ public function test_set_value_rejects_comment_only_values_without_removing_decl
 	 * @param string $value Malformed CSS declaration value.
 	 */
 	public function test_declaration_values_reject_malformed_eof_tokens( string $value ) {
-		$processor = WP_HTML_Style_Attribute_Processor::create( 'color: red;' );
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red;' );
 
 		$this->assertTrue( $processor->next_declaration( 'color' ) );
 		$this->assertFalse( $processor->set_value( $value ) );
@@ -1151,7 +1222,7 @@ public function test_declaration_values_reject_malformed_eof_tokens( string $val
 	 * @covers ::get_updated_style
 	 */
 	public function test_property_names_reject_escaped_source_identifiers() {
-		$processor = WP_HTML_Style_Attribute_Processor::create( '' );
+		$processor = new WP_HTML_Style_Attribute_Processor( '' );
 
 		$this->assertFalse( $processor->append_declaration( 'color\\', 'red' ) );
 		$this->assertFalse( $processor->append_declaration( 'c\\6f lor', 'red' ) );
@@ -1177,7 +1248,7 @@ public function test_updated_style_can_be_set_on_html_tag_processor_after_string
 		$style = $tags->get_attribute( 'style' );
 		$this->assertIsString( $style );
 
-		$styles = WP_HTML_Style_Attribute_Processor::create( $style );
+		$styles = new WP_HTML_Style_Attribute_Processor( $style );
 		$this->assertTrue( $styles->append_declaration( 'background', 'white' ) );
 		$this->assertTrue( $tags->set_attribute( 'style', $styles->get_updated_style() ) );
 
@@ -1324,8 +1395,11 @@ public static function data_value_tokens_source_slices(): array {
 	 */
 	public static function data_non_string_style_attribute_values(): array {
 		return array(
-			'missing style attribute' => array( null ),
-			'boolean style attribute' => array( true ),
+			'false'  => array( false ),
+			'int'    => array( 1 ),
+			'float'  => array( 1.5 ),
+			'array'  => array( array( 'color: red' ) ),
+			'object' => array( new stdClass() ),
 		);
 	}
 

From 4d3361c7dfe32fdcfcc9b08456de92a44ef8919d Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:02:21 +0400
Subject: [PATCH 72/77] Apply a style mutation from the parse that verified it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A successful mutation parsed the whole style twice, on the same text.
The verification step built the edited text, parsed it as a candidate
processor and checked the candidate's declarations. Then
apply_lexical_updates() rebuilt that text from the update queue and
parsed it again.

The verification methods now return the parsed candidate, or null where
they returned false, and the mutators take its style text, tokens and
declarations. The checks are unchanged, and so is the cursor handling.

Every mutator queued one update and applied it before returning, so the
queue never held more than one update: queue_lexical_update() always
found it empty, and has_queued_append_at() always returned false. The
test suite passed with assertions for both, and with an assertion that
the sorted and merged output equals the single replacement. With the
candidate's text as the updated style, the queue, its sort and merge,
and the separator check that read it are removed. get_updated_style()
returns the current text.

Timings in µs per call, before and after. PHP 8.5.12 CLI, opcache and
JIT off. N declarations of five kinds, 36 bytes each; 10 calls per run
(remove_declaration() at N=5: 5 calls, removing all); median of runs
within 1 s, one process per variant; median of 3 interleaved rounds.

                          N=5            N=20            N=100
  set_value()          124 -> 74      395 -> 212     1787 ->  916
  set_important()      111 -> 55      383 -> 191     1789 ->  889
  remove_declaration()  42 -> 21      264 -> 132     1670 ->  831
  append_declaration() 180 -> 105     476 -> 263     1989 -> 1103

The before and after runs produce the same output for every case.
---
 ...lass-wp-html-style-attribute-processor.php | 334 ++++--------------
 .../wpHtmlStyleAttributeProcessor.php         | 145 ++++++++
 2 files changed, 215 insertions(+), 264 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index cc8c8d5e455a6..6887ba3acc892 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -110,26 +110,6 @@ class WP_HTML_Style_Attribute_Processor {
 	 */
 	private $current_declaration_removed = false;
 
-	/**
-	 * Lexical updates to apply to the original style attribute value.
-	 *
-	 * @since 7.3.0
-	 * @ignore
-	 *
-	 * @var array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}>
-	 */
-	private $lexical_updates = array();
-
-	/**
-	 * Sequence counter used to keep lexical updates in queue order.
-	 *
-	 * @since 7.3.0
-	 * @ignore
-	 *
-	 * @var int
-	 */
-	private $lexical_update_order = 0;
-
 	/**
 	 * Constructor.
 	 *
@@ -295,27 +275,19 @@ public function set_value( string $value, ?bool $important = null ): bool {
 			return false;
 		}
 
-		if (
-			! $this->is_current_declaration_replacement_safe(
-				$declaration,
-				$declaration['start'],
-				$declaration['after'] - $declaration['start'],
-				$text,
-				$is_important,
-				$parsed_value
-			)
-		) {
-			return false;
-		}
-
-		$this->queue_lexical_update(
+		$updated = $this->verify_current_declaration_replacement(
+			$declaration,
 			$declaration['start'],
 			$declaration['after'] - $declaration['start'],
 			$text,
-			$this->current_declaration
+			$is_important,
+			$parsed_value
 		);
+		if ( null === $updated ) {
+			return false;
+		}
 
-		$this->apply_lexical_updates( $this->current_declaration );
+		$this->apply_update( $updated, $this->current_declaration );
 
 		return true;
 	}
@@ -343,73 +315,52 @@ public function set_important( bool $important ): bool {
 				return false;
 			}
 
-			$insert_at   = $declaration['value_end'];
 			$insert_text = ' !important';
-			if (
-				! $this->is_current_declaration_replacement_safe(
-					$declaration,
-					$declaration['value_end'],
-					0,
-					$insert_text,
-					true
-				)
-			) {
+			$updated     = $this->verify_current_declaration_replacement(
+				$declaration,
+				$declaration['value_end'],
+				0,
+				$insert_text,
+				true
+			);
+			if ( null === $updated ) {
 				$eof_repair    = strlen( $this->style ) === $declaration['after']
 					? $this->get_eof_repair( $declaration['after'] )
 					: null;
 				$current_value = substr( $this->style, $declaration['value_start'], $declaration['after'] - $declaration['value_start'] );
 
-				if (
-					null === $eof_repair ||
-					'' === $eof_repair ||
-					! $this->is_current_declaration_replacement_safe(
-						$declaration,
-						$declaration['after'],
-						0,
-						$eof_repair . $insert_text,
-						true,
-						trim( $current_value . $eof_repair, self::WHITESPACE )
-					)
-				) {
+				if ( null === $eof_repair || '' === $eof_repair ) {
 					return false;
 				}
 
-				$insert_at   = $declaration['after'];
-				$insert_text = $eof_repair . $insert_text;
+				$updated = $this->verify_current_declaration_replacement(
+					$declaration,
+					$declaration['after'],
+					0,
+					$eof_repair . $insert_text,
+					true,
+					trim( $current_value . $eof_repair, self::WHITESPACE )
+				);
 			}
-
-			$this->queue_lexical_update(
-				$insert_at,
-				0,
-				$insert_text,
-				$this->current_declaration
-			);
 		} else {
 			if ( null === $declaration['important_start'] || null === $declaration['important_end'] ) {
 				return false;
 			}
 
-			if (
-				! $this->is_current_declaration_replacement_safe(
-					$declaration,
-					$declaration['important_start'],
-					$declaration['important_end'] - $declaration['important_start'],
-					'',
-					false
-				)
-			) {
-				return false;
-			}
-
-			$this->queue_lexical_update(
+			$updated = $this->verify_current_declaration_replacement(
+				$declaration,
 				$declaration['important_start'],
 				$declaration['important_end'] - $declaration['important_start'],
 				'',
-				$this->current_declaration
+				false
 			);
 		}
 
-		$this->apply_lexical_updates( $this->current_declaration );
+		if ( null === $updated ) {
+			return false;
+		}
+
+		$this->apply_update( $updated, $this->current_declaration );
 
 		return true;
 	}
@@ -439,18 +390,12 @@ public function remove_declaration(): bool {
 		$remove_end   = $this->get_offset_after_following_whitespace( $declaration['after'] );
 		$replacement  = ( $remove_start > 0 && $remove_end < strlen( $this->style ) ) ? ' ' : '';
 
-		if ( ! $this->is_remove_declaration_safe( $this->current_declaration, $remove_start, $remove_end - $remove_start, $replacement ) ) {
+		$updated = $this->verify_declaration_removal( $this->current_declaration, $remove_start, $remove_end - $remove_start, $replacement );
+		if ( null === $updated ) {
 			return false;
 		}
 
-		$this->queue_lexical_update(
-			$remove_start,
-			$remove_end - $remove_start,
-			$replacement,
-			$this->current_declaration
-		);
-
-		$this->apply_lexical_updates( $this->current_declaration - 1, true );
+		$this->apply_update( $updated, $this->current_declaration - 1, true );
 
 		return true;
 	}
@@ -498,23 +443,18 @@ public function append_declaration( string $property_name, string $value, bool $
 			return false;
 		}
 
-		if ( ! $this->is_parseable_append( $repair_at, $eof_repair, $separator, $declaration_text, $old_declaration_count, $name, $parsed_value, $important ) ) {
+		$updated = $this->verify_append( $repair_at, $eof_repair, $separator, $declaration_text, $old_declaration_count, $name, $parsed_value, $important );
+		if ( null === $updated ) {
 			return false;
 		}
 
-		$this->queue_lexical_update(
-			$repair_at,
-			0,
-			$eof_repair . $separator . $declaration_text,
-			null
-		);
-
 		$append_after_exhausted_cursor = $this->current_declaration >= $old_declaration_count;
 		$current_after_append          = $append_after_exhausted_cursor
 			? $old_declaration_count - 1
 			: $this->current_declaration;
 
-		$this->apply_lexical_updates(
+		$this->apply_update(
+			$updated,
 			$current_after_append,
 			$this->current_declaration_removed || $append_after_exhausted_cursor
 		);
@@ -530,35 +470,7 @@ public function append_declaration( string $property_name, string $value, bool $
 	 * @return string Updated decoded CSS text value for the style attribute.
 	 */
 	public function get_updated_style(): string {
-		if ( empty( $this->lexical_updates ) ) {
-			return $this->style;
-		}
-
-		usort(
-			$this->lexical_updates,
-			static function ( $a, $b ) {
-				if ( $a['start'] !== $b['start'] ) {
-					return $a['start'] - $b['start'];
-				}
-
-				return $a['order'] - $b['order'];
-			}
-		);
-
-		$updates = $this->merge_overlapping_lexical_updates( $this->lexical_updates );
-
-		$bytes_already_copied = 0;
-		$output               = '';
-
-		foreach ( $updates as $update ) {
-			$output              .= substr( $this->style, $bytes_already_copied, $update['start'] - $bytes_already_copied );
-			$output              .= $update['text'];
-			$bytes_already_copied = $update['start'] + $update['length'];
-		}
-
-		$output .= substr( $this->style, $bytes_already_copied );
-
-		return $output;
+		return $this->style;
 	}
 
 	/**
@@ -1027,7 +939,7 @@ private function get_current_declaration(): ?array {
 	}
 
 	/**
-	 * Checks whether a replacement preserves the current declaration's structure.
+	 * Parses the style with a replacement and checks that it preserves the current declaration's structure.
 	 *
 	 * @since 7.3.0
 	 * @ignore
@@ -1038,9 +950,9 @@ private function get_current_declaration(): ?array {
 	 * @param string                                                                                                                                                                                                                        $text               Replacement text.
 	 * @param bool                                                                                                                                                                                                                          $expected_important Expected important flag after replacement.
 	 * @param string|null                                                                                                                                                                                                                   $expected_value     Optional expected value source after replacement.
-	 * @return bool Whether the replacement is safe.
+	 * @return self|null Parsed processor for the replaced style, or null when the replacement is not safe.
 	 */
-	private function is_current_declaration_replacement_safe( array $declaration, int $start, int $length, string $text, bool $expected_important, ?string $expected_value = null ): bool {
+	private function verify_current_declaration_replacement( array $declaration, int $start, int $length, string $text, bool $expected_important, ?string $expected_value = null ): ?self {
 		$candidate_style = substr( $this->style, 0, $start ) . $text . substr( $this->style, $start + $length );
 		$candidate       = new self( $candidate_style );
 		$candidate->ensure_parsed();
@@ -1049,7 +961,7 @@ private function is_current_declaration_replacement_safe( array $declaration, in
 			count( $candidate->declarations ) !== count( $this->declarations ) ||
 			! isset( $candidate->declarations[ $this->current_declaration ] )
 		) {
-			return false;
+			return null;
 		}
 
 		$updated_declaration = $candidate->declarations[ $this->current_declaration ];
@@ -1057,7 +969,7 @@ private function is_current_declaration_replacement_safe( array $declaration, in
 			$updated_declaration['name'] !== $declaration['name'] ||
 			$updated_declaration['important'] !== $expected_important
 		) {
-			return false;
+			return null;
 		}
 
 		$old_value = trim(
@@ -1069,11 +981,13 @@ private function is_current_declaration_replacement_safe( array $declaration, in
 			self::WHITESPACE
 		);
 
-		return null === $expected_value ? $old_value === $new_value : $expected_value === $new_value;
+		$is_safe = null === $expected_value ? $old_value === $new_value : $expected_value === $new_value;
+
+		return $is_safe ? $candidate : null;
 	}
 
 	/**
-	 * Checks whether removing a declaration preserves remaining structure.
+	 * Parses the style with a declaration removed and checks that the remaining structure is preserved.
 	 *
 	 * @since 7.3.0
 	 * @ignore
@@ -1082,15 +996,15 @@ private function is_current_declaration_replacement_safe( array $declaration, in
 	 * @param int    $start               Byte offset at which to start the replacement.
 	 * @param int    $length              Number of bytes to replace.
 	 * @param string $text                Replacement text.
-	 * @return bool Whether the removal is safe.
+	 * @return self|null Parsed processor for the style without the declaration, or null when the removal is not safe.
 	 */
-	private function is_remove_declaration_safe( int $removed_declaration, int $start, int $length, string $text ): bool {
+	private function verify_declaration_removal( int $removed_declaration, int $start, int $length, string $text ): ?self {
 		$candidate_style = substr( $this->style, 0, $start ) . $text . substr( $this->style, $start + $length );
 		$candidate       = new self( $candidate_style );
 		$candidate->ensure_parsed();
 
 		if ( count( $candidate->declarations ) !== count( $this->declarations ) - 1 ) {
-			return false;
+			return null;
 		}
 
 		$candidate_index = 0;
@@ -1100,7 +1014,7 @@ private function is_remove_declaration_safe( int $removed_declaration, int $star
 			}
 
 			if ( ! isset( $candidate->declarations[ $candidate_index ] ) ) {
-				return false;
+				return null;
 			}
 
 			$candidate_declaration = $candidate->declarations[ $candidate_index ];
@@ -1118,13 +1032,13 @@ private function is_remove_declaration_safe( int $removed_declaration, int $star
 				$candidate_declaration['important'] !== $declaration['important'] ||
 				$candidate_value !== $value
 			) {
-				return false;
+				return null;
 			}
 
 			++$candidate_index;
 		}
 
-		return true;
+		return $candidate;
 	}
 
 	/**
@@ -1152,78 +1066,29 @@ private function get_parsed_declaration_value( string $declaration_text ): ?stri
 	}
 
 	/**
-	 * Applies queued lexical updates and reparses the updated style attribute value.
+	 * Replaces the style text, tokens and declarations with those of a verified update.
 	 *
 	 * @since 7.3.0
 	 * @ignore
 	 *
+	 * @param self $updated                     Parsed processor for the updated style.
 	 * @param int  $current_declaration         Declaration index to keep before the next cursor advance.
 	 * @param bool $current_declaration_removed Optional. Whether the current declaration was removed.
 	 */
-	private function apply_lexical_updates( int $current_declaration, bool $current_declaration_removed = false ): void {
-		$this->style = $this->get_updated_style();
+	private function apply_update( self $updated, int $current_declaration, bool $current_declaration_removed = false ): void {
+		$this->style        = $updated->style;
+		$this->tokens       = $updated->tokens;
+		$this->declarations = $updated->declarations;
+		$this->parsed       = true;
 
-		$this->lexical_updates             = array();
-		$this->lexical_update_order        = 0;
 		$this->current_declaration         = $current_declaration;
 		$this->current_declaration_removed = $current_declaration_removed;
-		$this->parsed                      = false;
-
-		$this->parse();
 
 		if ( $this->current_declaration >= count( $this->declarations ) ) {
 			$this->current_declaration = count( $this->declarations );
 		}
 	}
 
-	/**
-	 * Queues a lexical update, replacing any earlier update for the same declaration.
-	 *
-	 * @since 7.3.0
-	 * @ignore
-	 *
-	 * @param int      $start       Byte offset at which to start the update.
-	 * @param int      $length      Number of bytes to replace.
-	 * @param string   $text        Replacement text.
-	 * @param int|null $declaration Declaration index associated with the update.
-	 */
-	private function queue_lexical_update( int $start, int $length, string $text, ?int $declaration ): void {
-		if ( null !== $declaration ) {
-			foreach ( $this->lexical_updates as $index => $update ) {
-				if ( $update['declaration'] === $declaration ) {
-					unset( $this->lexical_updates[ $index ] );
-				}
-			}
-		}
-
-		$this->lexical_updates[] = array(
-			'start'       => $start,
-			'length'      => $length,
-			'text'        => $text,
-			'declaration' => $declaration,
-			'order'       => $this->lexical_update_order++,
-		);
-	}
-
-	/**
-	 * Checks whether an append has already been queued at a byte offset.
-	 *
-	 * @since 7.3.0
-	 * @ignore
-	 *
-	 * @param int $insert_at Byte offset.
-	 * @return bool Whether an append has already been queued at the offset.
-	 */
-	private function has_queued_append_at( int $insert_at ): bool {
-		foreach ( $this->lexical_updates as $update ) {
-			if ( null === $update['declaration'] && $insert_at === $update['start'] && 0 === $update['length'] ) {
-				return true;
-			}
-		}
-
-		return false;
-	}
-
 	/**
 	 * Gets the separator to use before an appended declaration.
 	 *
@@ -1237,10 +1102,6 @@ private function has_queued_append_at( int $insert_at ): bool {
 	 * @return string Separator text.
 	 */
 	private function get_append_separator( int $insert_at ): string {
-		if ( $this->has_queued_append_at( $insert_at ) ) {
-			return ' ';
-		}
-
 		$last_token = $this->get_last_top_level_non_ignored_token_before( $insert_at );
 
 		if ( null === $last_token ) {
@@ -1391,7 +1252,7 @@ private function get_eof_repair( int $insert_at ): ?string {
 	}
 
 	/**
-	 * Checks whether an appended declaration will parse as a new declaration.
+	 * Parses the style with a declaration appended and checks that it parses as a new declaration.
 	 *
 	 * Malformed existing declarations can leave the append point inside an
 	 * unclosed component value. In that case preserving the original text and
@@ -1408,9 +1269,9 @@ private function get_eof_repair( int $insert_at ): ?string {
 	 * @param string $expected_name          Expected parsed property name.
 	 * @param string $expected_value         Expected parsed value source.
 	 * @param bool   $expected_important     Expected important flag.
-	 * @return bool Whether the appended declaration is parseable.
+	 * @return self|null Parsed processor for the style with the declaration, or null when it does not parse as a new declaration.
 	 */
-	private function is_parseable_append( int $insert_at, string $eof_repair, string $separator, string $declaration_text, int $old_declaration_count, string $expected_name, string $expected_value, bool $expected_important ): bool {
+	private function verify_append( int $insert_at, string $eof_repair, string $separator, string $declaration_text, int $old_declaration_count, string $expected_name, string $expected_value, bool $expected_important ): ?self {
 		$expected_start  = $insert_at + strlen( $eof_repair ) + strlen( $separator );
 		$expected_after  = $expected_start + strlen( $declaration_text );
 		$candidate_style = substr( $this->style, 0, $insert_at ) . $eof_repair . $separator . $declaration_text . substr( $this->style, $insert_at );
@@ -1418,7 +1279,7 @@ private function is_parseable_append( int $insert_at, string $eof_repair, string
 		$candidate->ensure_parsed();
 
 		if ( count( $candidate->declarations ) !== $old_declaration_count + 1 ) {
-			return false;
+			return null;
 		}
 
 		foreach ( $candidate->declarations as $declaration ) {
@@ -1428,72 +1289,17 @@ private function is_parseable_append( int $insert_at, string $eof_repair, string
 					self::WHITESPACE
 				);
 
-				return (
+				$is_parseable = (
 					$expected_name === $declaration['name'] &&
 					$expected_value === $parsed_value &&
 					$expected_important === $declaration['important']
 				);
-			}
-		}
-
-		return false;
-	}
-
-	/**
-	 * Merges overlapping lexical updates into non-overlapping replacements.
-	 *
-	 * Adjacent declaration removals may share separator whitespace, and appends
-	 * may be queued inside a range removed from the original style. This method
-	 * collapses those updates while preserving the requested replacement text.
-	 *
-	 * @since 7.3.0
-	 * @ignore
-	 *
-	 * @param array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> $updates Lexical updates.
-	 * @return array<int, array{start:int, length:int, text:string, declaration:int|null, order:int}> Merged updates.
-	 */
-	private function merge_overlapping_lexical_updates( array $updates ): array {
-		$merged = array();
-
-		foreach ( $updates as $update ) {
-			if ( empty( $merged ) ) {
-				$merged[] = $update;
-				continue;
-			}
-
-			$last_index = count( $merged ) - 1;
-			$last       = $merged[ $last_index ];
-			$last_end   = $last['start'] + $last['length'];
-			$update_end = $update['start'] + $update['length'];
-
-			if ( $update['start'] > $last_end ) {
-				$merged[] = $update;
-				continue;
-			}
 
-			$text = $update['text'];
-			if ( 0 === $last['start'] && '' === $last['text'] && 0 === $update['length'] ) {
-				$text = ltrim( $text, ';' . self::WHITESPACE );
+				return $is_parseable ? $candidate : null;
 			}
-
-			$merged[ $last_index ]['length'] = max( $last_end, $update_end ) - $last['start'];
-			$merged[ $last_index ]['text']   = $last['text'] . $text;
-		}
-
-		foreach ( $merged as $index => $update ) {
-			if ( 0 !== $update['start'] || '' !== $update['text'] ) {
-				continue;
-			}
-
-			$end = $update['length'];
-			while ( $end < strlen( $this->style ) && false !== strpos( self::WHITESPACE, $this->style[ $end ] ) ) {
-				++$end;
-			}
-
-			$merged[ $index ]['length'] = $end;
 		}
 
-		return $merged;
+		return null;
 	}
 
 	/**
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 29eb9d4be315c..5b73e9a313268 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -878,6 +878,151 @@ public function test_mixed_mutations_preserve_the_logical_cursor_and_declaration
 		$this->assertSame( 'background: white; border: 1px !important;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::append_declaration
+	 * @covers ::remove_declaration
+	 * @covers ::set_important
+	 * @covers ::set_value
+	 *
+	 * @dataProvider data_mutations
+	 *
+	 * @param string  $style      Style text.
+	 * @param array[] $operations Method name and arguments of each call. Every call must return true.
+	 * @param int     $index      Index of the declaration the cursor reads next after the calls.
+	 */
+	public function test_mutations_leave_the_declarations_a_new_processor_reads( string $style, array $operations, int $index ) {
+		$processor = new WP_HTML_Style_Attribute_Processor( $style );
+
+		foreach ( $operations as $operation ) {
+			$method = array_shift( $operation );
+			$this->assertTrue( $processor->$method( ...$operation ), "Expected {$method}() to return true." );
+		}
+
+		$reread = new WP_HTML_Style_Attribute_Processor( $processor->get_updated_style() );
+
+		$this->assertSame(
+			array_slice( self::read_remaining_declarations( $reread ), $index ),
+			self::read_remaining_declarations( $processor )
+		);
+	}
+
+	/**
+	 * Data provider.
+	 *
+	 * @return array<string, array{string, array[], int}>
+	 */
+	public static function data_mutations(): array {
+		$style = 'color: red; width: calc(1px + 2px) !important; --x: "a" b; background: url(a.png)';
+		$open  = 'color: red; width: calc(1px + var(--gap';
+
+		return array(
+			'set_value() on the first declaration'      => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'set_value', 'rgb(1 2 3 / 50%)' ) ),
+				0,
+			),
+			'set_value() on a middle declaration'       => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'set_value', 'calc(100% - 2 * var(--gap, 10px))', false ) ),
+				1,
+			),
+			'set_important() adds the priority'         => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'set_important', true ) ),
+				0,
+			),
+			'set_important() removes the priority'      => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'set_important', false ) ),
+				1,
+			),
+			'set_important() closes blocks open at EOF' => array(
+				$open,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'set_important', true ) ),
+				1,
+			),
+			'remove_declaration() on the first'         => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'remove_declaration' ) ),
+				0,
+			),
+			'remove_declaration() on a middle one'      => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'remove_declaration' ) ),
+				1,
+			),
+			'remove_declaration() on the last'          => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'next_declaration' ), array( 'next_declaration' ), array( 'remove_declaration' ) ),
+				3,
+			),
+			'append_declaration() before the first'     => array(
+				$style,
+				array( array( 'append_declaration', 'padding', '1px 2px' ) ),
+				0,
+			),
+			'append_declaration() on a declaration'     => array(
+				$style,
+				array( array( 'next_declaration' ), array( 'next_declaration' ), array( 'append_declaration', 'padding', '1px 2px', true ) ),
+				1,
+			),
+			'append_declaration() closes blocks at EOF' => array(
+				$open,
+				array( array( 'append_declaration', 'padding', '1px 2px' ) ),
+				0,
+			),
+			'mixed calls'                               => array(
+				$style,
+				array(
+					array( 'next_declaration' ),
+					array( 'set_value', 'blue', true ),
+					array( 'append_declaration', 'border', '1px solid' ),
+					array( 'set_important', false ),
+					array( 'next_declaration' ),
+					array( 'remove_declaration' ),
+					array( 'append_declaration', 'margin', '0' ),
+					array( 'next_declaration' ),
+					array( 'set_value', '"b" c' ),
+					array( 'set_important', true ),
+					array( 'next_declaration', 'background' ),
+					array( 'remove_declaration' ),
+				),
+				2,
+			),
+		);
+	}
+
+	/**
+	 * Reads the current declaration, or the next one when the cursor is not on one, and every declaration after it.
+	 *
+	 * @param WP_HTML_Style_Attribute_Processor $processor Processor whose cursor moves to the end.
+	 * @return array[] Name, priority, value tokens and serialization of each declaration.
+	 */
+	private static function read_remaining_declarations( WP_HTML_Style_Attribute_Processor $processor ): array {
+		$declarations = array();
+		if ( null === $processor->get_property_name() && ! $processor->next_declaration() ) {
+			return $declarations;
+		}
+
+		do {
+			$declarations[] = array(
+				'name'       => $processor->get_property_name(),
+				'important'  => $processor->is_important(),
+				'tokens'     => array_map(
+					static function ( WP_CSS_Token $token ): array {
+						return array( $token->get_type(), $token->get_flag(), $token->get_value(), $token->get_unit(), $token->get_start(), $token->get_length(), $token->is_terminated() );
+					},
+					$processor->get_value_tokens()
+				),
+				'serialized' => $processor->serialize_declaration(),
+			);
+		} while ( $processor->next_declaration() );
+
+		return $declarations;
+	}
+
 	/**
 	 * @covers ::append_declaration
 	 * @covers ::get_updated_style

From 0624057759cdcc7ed4ab6296a99037bdccbaa821 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:04:08 +0400
Subject: [PATCH 73/77] Document how to set a property with
 WP_HTML_Style_Attribute_Processor

The processor has no method that sets a property. The class docblock
now shows how: remove the property's declarations in one named
next_declaration() loop, then append the new declaration. It covers
setting several properties in one unnamed pass, since the cursor moves
forward only, and how the appended declaration's position interacts
with shorthands in the cascade.

A test confirms that remove_declaration() in a named loop removes every
matching declaration, including ones that follow a removed one.

The example outputs were checked by running the examples as written.
---
 ...lass-wp-html-style-attribute-processor.php | 57 +++++++++++++++++++
 .../wpHtmlStyleAttributeProcessor.php         | 20 +++++++
 2 files changed, 77 insertions(+)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 6887ba3acc892..7088a157c0c81 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -25,7 +25,64 @@
  * declaration list model of CSS. Multiple declarations with the same property
  * name remain separate entries and can be inspected or changed individually.
  *
+ * ## Setting a property
+ *
+ * To set a property, remove its declarations in one `next_declaration( $name )`
+ * loop, then call append_declaration().
+ *
+ * Example:
+ *
+ * ```php interactive
+ * $styles = new WP_HTML_Style_Attribute_Processor( 'background-image: url(a.png); color: red' );
+ * while ( $styles->next_declaration( 'background-image' ) ) {
+ *     $styles->remove_declaration();
+ * }
+ * $styles->append_declaration( 'background-image', WP_CSS_Builder::url( 'https://example.com/b.png' ) );
+ * echo $styles->get_updated_style();
+ * // Outputs: color: red; background-image: url("https://example.com/b.png");
+ * ```
+ *
+ * The cursor moves forward only. After one `next_declaration( $name )` loop
+ * ends, a second one finds nothing. To set several properties, remove all of
+ * their declarations in one `next_declaration()` loop that compares
+ * get_property_name() with each name, then append each declaration.
+ *
+ * Example:
+ *
+ * ```php interactive
+ * $values = array(
+ *     'color' => 'green',
+ *     'width' => '2px',
+ * );
+ * $styles = new WP_HTML_Style_Attribute_Processor( 'color: red; width: 1px; COLOR: blue; height: 2px' );
+ * while ( $styles->next_declaration() ) {
+ *     if ( isset( $values[ $styles->get_property_name() ] ) ) {
+ *         $styles->remove_declaration();
+ *     }
+ * }
+ * foreach ( $values as $name => $value ) {
+ *     $styles->append_declaration( $name, $value );
+ * }
+ * echo $styles->get_updated_style();
+ * // Outputs: height: 2px; color: green; width: 2px;
+ * ```
+ *
+ * The appended declaration is last, so it overrides earlier declarations that
+ * set the same thing, shorthands included:
+ *
+ * - In `background-image: url(a); background: red`, setting `background-image`
+ *   to `url(b)` gives `background: red; background-image: url(b);`, which shows
+ *   image b.
+ * - In `background-color: blue`, setting `background` to `url(c)` gives
+ *   `background-color: blue; background: url(c);`. The shorthand resets the
+ *   color.
+ *
+ * set_value() keeps the declaration where it is, so a later shorthand still
+ * overrides it.
+ *
  * @since 7.3.0
+ *
+ * @see WP_CSS_Builder
  */
 class WP_HTML_Style_Attribute_Processor {
 	/**
diff --git a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
index 5b73e9a313268..8eec264f5ff5c 100644
--- a/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
+++ b/tests/phpunit/tests/html-api/wpHtmlStyleAttributeProcessor.php
@@ -760,6 +760,26 @@ public function test_remove_declaration_removes_adjacent_duplicate_declarations(
 		$this->assertSame( 'background: white;', $processor->get_updated_style() );
 	}
 
+	/**
+	 * @ticket 65738
+	 *
+	 * @covers ::next_declaration
+	 * @covers ::remove_declaration
+	 * @covers ::get_updated_style
+	 */
+	public function test_remove_declaration_in_a_named_loop_removes_every_matching_declaration() {
+		$processor = new WP_HTML_Style_Attribute_Processor( 'color: red; width: 1px; color: blue; color: green; height: 2px; COLOR: black' );
+
+		$removed = 0;
+		while ( $processor->next_declaration( 'color' ) ) {
+			$this->assertTrue( $processor->remove_declaration() );
+			++$removed;
+		}
+
+		$this->assertSame( 4, $removed );
+		$this->assertSame( 'width: 1px; height: 2px;', $processor->get_updated_style() );
+	}
+
 	/**
 	 * @covers ::remove_declaration
 	 * @covers ::get_property_name

From 567c5d07fe4142114afd72155d912d58f4e1769e Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:05:49 +0400
Subject: [PATCH 74/77] Mark WP_CSS_Token_Processor::next_token() impure for
 PHPStan

next_token() advances the cursor, so two calls on one processor can
return different results. Without the annotation PHPStan reuses the
first call's result for the second, which reports a later
"if ( $processor->next_token() )" as always true and its else branch
as unreachable.

WP_HTML_Tag_Processor::next_token() carries the same annotation.
---
 src/wp-includes/css-api/class-wp-css-token-processor.php | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/wp-includes/css-api/class-wp-css-token-processor.php b/src/wp-includes/css-api/class-wp-css-token-processor.php
index 82bcab05af5af..e9b0e27e4bd7e 100644
--- a/src/wp-includes/css-api/class-wp-css-token-processor.php
+++ b/src/wp-includes/css-api/class-wp-css-token-processor.php
@@ -426,6 +426,8 @@ public function __construct( string $css ) {
 	 * @since 7.3.0
 	 *
 	 * @return bool Whether a token was found.
+	 *
+	 * @phpstan-impure
 	 */
 	public function next_token(): bool {
 		$this->after_token();

From 0fd8e23cbc0e020760c20154c24581218c7e46e0 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:06:30 +0400
Subject: [PATCH 75/77] Name every accepted type in the style processor's
 TypeError

---
 .../html-api/class-wp-html-style-attribute-processor.php        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
index 7088a157c0c81..04c8486f3eef2 100644
--- a/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-style-attribute-processor.php
@@ -182,7 +182,7 @@ public function __construct( $decoded_css_text ) {
 		}
 
 		if ( ! is_string( $decoded_css_text ) ) {
-			throw new TypeError( __METHOD__ . '(): Argument #1 ($decoded_css_text) must be of type string' );
+			throw new TypeError( __METHOD__ . '(): Argument #1 ($decoded_css_text) must be of type string|true|null' );
 		}
 
 		$this->style = $decoded_css_text;

From 0620a873261f4ba8eaa42b128ccfafd68ffd21a9 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:35:25 +0400
Subject: [PATCH 76/77] Construct the CSS processors with their public
 constructors

---
 .../phpunit/includes/build-style-attribute-declarations.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tests/phpunit/includes/build-style-attribute-declarations.php b/tests/phpunit/includes/build-style-attribute-declarations.php
index 53db21b0717e6..f8715eb855866 100644
--- a/tests/phpunit/includes/build-style-attribute-declarations.php
+++ b/tests/phpunit/includes/build-style-attribute-declarations.php
@@ -26,7 +26,7 @@ function build_style_attribute_declarations( string $style ): ?array {
 		);
 	};
 
-	$processor          = WP_HTML_Style_Attribute_Processor::create( $style );
+	$processor          = new WP_HTML_Style_Attribute_Processor( $style );
 	$declarations       = array();
 	$declaration_tokens = 0;
 
@@ -48,7 +48,7 @@ function build_style_attribute_declarations( string $style ): ?array {
 
 		// The serializer separates tokens that would read as one with an empty comment.
 		$serialized = WP_CSS_Token_Serializer::serialize( $tokens );
-		$reader     = WP_CSS_Token_Processor::create( $serialized );
+		$reader     = new WP_CSS_Token_Processor( $serialized );
 		$value      = '';
 		while ( $reader->next_token() ) {
 			$token  = $reader->get_token();
@@ -62,7 +62,7 @@ function build_style_attribute_declarations( string $style ): ?array {
 	}
 
 	// Any token not counted above, other than whitespace, a comment or a `;`, is not part of a declaration.
-	$reader = WP_CSS_Token_Processor::create( $style );
+	$reader = new WP_CSS_Token_Processor( $style );
 	while ( $reader->next_token() ) {
 		$token = $reader->get_token();
 		if ( ! $is_ignored( $token ) && WP_CSS_Token_Processor::TOKEN_SEMICOLON !== $token->get_type() ) {

From 09cb6fd142c38f60bd1c2d44f0ea0d4d7afa83ea Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Thu, 29 Oct 2026 21:54:05 +0400
Subject: [PATCH 77/77] Describe the style processor's constructor and
 immediate updates in its spec

---
 .../wp-html-style-attribute-processor-spec.md | 34 ++++++++-----------
 1 file changed, 14 insertions(+), 20 deletions(-)

diff --git a/docs/wp-html-style-attribute-processor-spec.md b/docs/wp-html-style-attribute-processor-spec.md
index 4cf1aa54300d0..9d24f841676c2 100644
--- a/docs/wp-html-style-attribute-processor-spec.md
+++ b/docs/wp-html-style-attribute-processor-spec.md
@@ -20,21 +20,18 @@ The processor's north star is:
 
 ## Construction
 
-Creation uses:
+Creation uses the public constructor:
 
 ```php
-WP_HTML_Style_Attribute_Processor::create( $decoded_css_text )
+new WP_HTML_Style_Attribute_Processor( $decoded_css_text )
 ```
 
-The constructor is private. `create()` accepts only string input and returns a
-processor instance of the called class. The implementation must remain
-compatible with WordPress' supported PHP versions, so the runtime signature may
-use PHPDoc and explicit validation instead of PHP syntax unavailable in those
-versions.
-
-Callers must not pass raw `WP_HTML_Tag_Processor::get_attribute( 'style' )`
-results directly unless they have already checked that the result is a string.
-Missing or boolean attributes are an HTML-layer concern, not accepted CSS text.
+The constructor accepts a string, `true` or `null`, the values
+`WP_HTML_Tag_Processor::get_attribute( 'style' )` returns. `true` (an attribute
+with no value) and `null` (a missing attribute) give an empty style. Any other
+type throws a `TypeError`. The implementation must remain compatible with
+WordPress' supported PHP versions, so the runtime signature uses PHPDoc and
+explicit validation instead of a union type.
 
 Parsing is lazy. Creating a processor does not scan the style text until cursor
 movement, mutation validation, or serialization requires it.
@@ -63,7 +60,7 @@ The internal declaration data consists of:
 Initial public methods:
 
 ```php
-public static function create( $decoded_css_text );
+public function __construct( $decoded_css_text );
 public function next_declaration( ?string $property_name = null ): bool;
 public function get_property_name(): ?string;
 public function is_important(): ?bool;
@@ -82,7 +79,7 @@ The processor exposes a declaration value as tokens, through
 string would be re-tokenized by every consumer.
 
 Bookmarks, seek, and rewind are out of scope. Callers that need to rescan should
-create a new processor from the updated style text.
+construct a new processor from the updated style text.
 
 ## Cursor Semantics
 
@@ -102,11 +99,8 @@ declaration, the cursor remains on the same logical declaration.
 remains invalid until a later `next_declaration()` advances to the appended
 declaration.
 
-`next_declaration()` flushes pending safe edits before advancing because
-advancement must reflect the updated declaration list.
-
-Current-position getters should reflect successful pending edits without forcing
-a full reparse where practical, following HTML API style.
+A successful mutation updates the style text and the declaration list before
+it returns, so later getters and `next_declaration()` see the updated list.
 
 Each successful mutation parses the whole style text again. Removing most of the
 declarations of a long style one at a time therefore takes time that grows with
@@ -148,7 +142,7 @@ value tokens are included. A declaration with no value tokens, such as
 `color:;`, returns an empty list.
 
 Offsets index the current style text, which `get_updated_style()` returns.
-Before any mutation that is the text passed to `create()`. A successful
+Before any mutation that is the text passed to the constructor. A successful
 mutation reparses the updated text, and the offsets follow it.
 
 Re-tokenizing the source slice from the first token's start to the end of the
@@ -332,7 +326,7 @@ self-contained and do not receive EOF repair.
 
 Tests should cover:
 
-- private construction and `create()` behavior;
+- construction, including `true`, `null` and other non-string input;
 - decoded string input boundary;
 - declaration traversal, duplicate preservation, and property-name matching;
 - getter `null` behavior off-cursor;