Describe JavaScript escaping strategy in detail

Author: sirreal

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

@@ -3845,7 +3845,47 @@ public function set_modifiable_text( string $plaintext_content ): bool {
 					false !== stripos( $plaintext_content, '<script' )
 				) {
 					/*
-					 * JavaScript can be safely escaped.
+					 * JavaScript can be safely escaped with a few exceptions. This is achieved by
+					 * replacing dangerous sequences like "<script" and "</script" with a form
+					 * using a Unicode escape sequence "<\u0073cript>" and "</\u0073cript>".
+					 *
+					 * `<script` and `</script` appear in JavaScript source code in limited places,
+					 * all of which support a Unicode escape sequence on the "s" character.
+					 * JavaScript identifiers, string literals, template literals, and RegExp
+					 * literals all support Unicode escape sequences, meaning that the escaped form
+					 * is indistinguishable from the unescaped form when the JavaScript
+					 * is evaluated.
+					 *
+					 * There are a few exceptions where the escaped form can be detected:
+					 *
+					 * - The escaped form would appear in any JavaScript comments.
+					 * - “Raw” strings via `String.raw()` or the `raw` property of the first
+					 *   argument to a tagged template literal exposes the raw form, revealing any
+					 *   escaping that has been applied.
+					 * - The `source` property of a RegExp object reveals an escaped form the of
+					 *   the pattern.
+					 *
+					 * For JavaScript that needs to avoid these issues, workarounds may
+					 * be available. For example:
+					 *
+					 *      // Instead of:
+					 *      const rawStringWillBeEscaped = String.raw`</script>`;
+					 *
+					 *      // This will yield the same result with no escaping required:
+					 *      const rawStringWillBePreserved = String.raw`</scr` + String.raw`ipt>`;
+					 *
+					 *      // After the escaping has been applied and the JavaScript evaluated,
+					 *      // these are the resulting values:
+					 *      rawStringWillBeEscaped;  // "</\\u0073cript>"
+					 *      rawStringWillBePreserve; // "</script>"
+					 *
+					 *
+					 * Escaping is applied only where strictly necessary, reducing the likelyhood
+					 * that observable differences manifest in the escaped JavaScript.
+					 *
+					 * The alternatives are to reject JavaScript that could be safely escaped in
+					 * a majority of cases or to relax restrictions in ways that produce dangerous
+					 * or broken HTML documents, neither are desirable.
 					 */
 					if ( $this->is_javascript_script_tag() ) {
 						$plaintext_content = preg_replace_callback(