Comments: Allow the Notes @mention chip markup in comment content (kses)

[adamsilverstein]

Backports the mention kses allowance from the Gutenberg Notes @mention work:

• WordPress/gutenberg#79604 (merged) and
• WordPress/gutenberg#80528 (the reworked span-chip markup, approved), which superseded the earlier link-based markup and WordPress/gutenberg#80221's per-note kses arming.

The notification layer (from the still-open WordPress/gutenberg#79606) has been split out to #12548 with its own Trac ticket, so this PR can land as soon as it is reviewed without waiting on the upstream notification work.

What

The Notes @ mention completer stores a mention as a non-interactive chip carrying the mentioned user's ID in a class token:

<span class="wp-note-mention user-N">@Name</span>

This PR allows exactly that markup - and nothing more - through comment kses, via two small always-on filters (hooked in default-filters.php):

• _wp_kses_allow_note_mention_span() (new, private) extends the pre_comment_content allowlist with class on span elements.
• _wp_kses_sanitize_note_mention_classes() (new, private) runs on pre_comment_content at priority 11 - right after wp_filter_kses - and uses the HTML API (class_list() / remove_class()) to strip every span class token except wp-note-mention and user-N. It bails while wp_filter_kses is not attached, so users with unfiltered_html (filtered through wp_filter_post_kses, where arbitrary classes are already permitted) are never narrowed below what core allows them.

wp_filter_comment() is untouched: no per-comment-type arming or disarming of kses state.

Why

This follows the discussion on this PR and on WordPress/gutenberg#80496:

• @westonruter's concern about the original approach: allowing an open-ended class on note links is a live CSS/JS selector surface in the admin. His data-attribute suggestion turned out to need a kses allowance anyway (data-* is not allowed by default in the comment context), and per @Mamaduka's review, an anchor-based mention breaks in the Link format UI regardless of how the ID is carried - mentions aren't links, they're tokens rendered as chips.
• The resolution keeps the class (it doubles as the rich-text format-differentiation and styling hook) but closes the open-class hole a different way: the allowance is unconditional yet reduced to exactly two inert tokens on a semantics-free element, so there is nothing left to scope per comment type and the stateful arm/disarm machinery disappears.

Behavior change: all commenters (including anonymous ones) can persist <span> elements whose class is limited to wp-note-mention and/or user-N. This is inert - the tokens are not styling or scripting hooks outside the notes sidebar, and mention notification parsing (#12548) only processes note-type comments.

Testing

Unit tests in tests/phpunit/tests/kses.php:

• test_wp_kses_allowed_html_pre_comment_content_allows_only_the_mention_span verifies the context gains the span allowance and nothing else beyond the stock $allowedtags.
• test_note_mention_markup_survives_note_content_sanitization / test_note_mention_markup_survives_regular_comment_content_sanitization verify the chip survives for both comment types.
• test_note_mention_span_classes_are_reduced_to_the_mention_tokens verifies junk class tokens are stripped.
• test_note_mention_class_attribute_removed_when_no_tokens_remain verifies the class attribute is dropped entirely when no valid tokens remain.
• test_note_mention_allows_only_class_on_mention_spans verifies every other span attribute (onclick, style, data-*, id) is still stripped.
• test_class_is_still_stripped_from_links_in_comment_content verifies links keep the default sanitization.
• test_note_mention_class_reduction_skipped_when_restrictive_kses_is_inactive verifies the reduction never narrows unfiltered_html users.

npm run test:php -- tests/phpunit/tests/kses.php

Trac ticket: https://core.trac.wordpress.org/ticket/65622

---

Proposed commit message

Comments: Allow the Notes @mention chip markup in comment content.

The Notes @mention completer stores a mention as a non-interactive chip,
`<span class="wp-note-mention user-N">@Name</span>`, the `user-N` class
token carrying the mentioned user's ID. The default comment kses allowlist
does not permit `span`, so for users without the `unfiltered_html`
capability the mention markup is stripped when the note is saved.

Allow `span` with `class` in the comment kses context, and reduce span
classes to the two mention tokens in a companion `pre_comment_content`
pass running right after kses, so the allowance stays inert: no other
element, attribute, or class token is newly available to commenters.

See related Gutenberg pull requests: https://github.com/WordPress/gutenberg/pull/79604 and https://github.com/WordPress/gutenberg/pull/80528.

Props mamaduka, westonruter.
Fixes #65622.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props adamsilverstein, westonruter, wildworks, mamaduka.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Mamaduka]

Sorry, only have time for a surface review.

• Not sure if we need new methods like wp_get_note_thread_root_id. Values can be easily derived.
• The follower notifications seem like work for a separate PR. I don't think it should be in scope for mention notifications.

I think the general API for managing email (or other) notifications would be better for the project than handling each case individually.

[adamsilverstein]

Sorry, only have time for a surface review.

• Not sure if we need new methods like wp_get_note_thread_root_id. Values can be easily derived.
• The follower notifications seem like work for a separate PR. I don't think it should be in scope for mention notifications.

I think the general API for managing email (or other) notifications would be better for the project than handling each case individually.

Reducing this to the kses only changes which matches the merged PRs. Opening a follow up for the notifications part to dig deeper.

[adamsilverstein]

Follow up: #12548

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/wp-includes/kses.php:1207

• The early bailout str_contains( $unslashed, '<span' ) is case-sensitive. A commenter could use <SPAN class="..."> so this function returns early and never strips class tokens, leaving an open-ended class attribute on spans (since class is now allowed through KSES). Removing this check avoids the bypass and matches the intended “always reduce span classes” behavior.

	$unslashed = wp_unslash( $content );

	if ( ! str_contains( $unslashed, '<span' ) ) {
		return $content;
	}

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

[westonruter]

@copilot This contradicts with what you previously said in #12503 (comment)

It seems here you are right. Updated in 1bef13b

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/wp-includes/kses.php:1154

• The phpdoc types for _wp_kses_allow_note_mention_span() don’t match what the wp_kses_allowed_html filter can actually pass. $allowed is not always an “allowed tags structure” (e.g. for the entities context it’s an array of entity-name strings), and $context is documented as possibly being an array even though wp_kses_allowed_html() normalizes array contexts to the string 'explicit' before applying the filter. This can mislead static analysis and future maintainers.

Consider loosening these annotations to match the filter contract (array + string).

 * @param array<string, array<string, bool>>        $allowed The allowed tags structure for the context.
 * @param string|array<string, array<string, bool>> $context The kses context.
 * @return array<string, array<string, bool>> Modified allowed tags structure.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.