[westonruter]

✅ Committed in r65318 (28d2f50).

---

This defines array shapes for block type selectors and for viewport media queries, which Gutenberg PRs depend on (see below).

Block type selectors

WP_Block_Type::$selectors is documented as a plain array. This defines its shape, following the selectors schema in block.json: an optional root selector string, plus selectors for block support features (such as color or typography), each either a selector string or an array of selectors keyed by subfeature (such as root or text).

// Plain @var, @param, and @return tags:
array<string, string|array<string, string>>

// @phpstan- tags:
array{ root?: string, ...<string, string|array<string, string>> }

The shape is unsealed, so any feature key is allowed. Core itself uses keys the schema doesn't list (states and filter), and third-party blocks can add their own. The plain form matches what WP_Theme_JSON::get_feature_selector() already uses.

The shape is applied to:

• The WP_Block_Type::$selectors property, whose description now also covers the states key, along with the selectors argument to the constructor.
• The return value of WP_Theme_JSON::get_block_selectors(), whose $block_type parameter is also now documented as WP_Block_Type rather than object.
• The selectors key of the $metadata parameter of WP_Theme_JSON::get_feature_declarations_for_node().
• The $block_selectors parameter of wp_get_state_style_groups().

There is one code change. WP_Theme_JSON::get_block_selectors() now builds the feature selectors first and prepends root with array( 'root' => $root_selector ) + $feature_selectors. The result has the same keys in the same order, but since BLOCK_SUPPORT_FEATURE_LEVEL_SELECTORS is accessed via static::, a subclass's feature named root can no longer replace the root selector string with an array.

New tests in Tests_Theme_wpThemeJson cover get_block_selectors():

• test_get_block_selectors_builds_default_selectors_with_root_first(): For a block without custom selectors, the default selectors list root first, followed by the feature selectors in the order of BLOCK_SUPPORT_FEATURE_LEVEL_SELECTORS.
• test_get_block_selectors_returns_custom_selectors(): Custom selectors set by the block are returned as they are.
• test_get_block_selectors_keeps_root_selector_string(): For a subclass that maps a support to a feature named root, the root selector string is kept.

Building the default selectors with $feature_selectors['root'] ??= $root_selector instead fails the first and third tests.

The $state_style parameter of wp_get_state_style_groups() is also now documented as array<string, mixed>, since it is keyed by style feature and each key is looked up in $block_selectors.

At rule level 10, these changes resolve 10 PHPStan errors, including missingType.iterableValue on the property and on the two functions, return.type for mixed returned from wp_get_block_css_selector() and WP_Theme_JSON::get_block_selectors(), and argument.type for mixed passed to wp_add_state_style_group(). They introduce one: the caller wp_get_block_state_style_rules() narrows each state style from mixed only with is_array(), so it now reports an argument.type error for passing array<mixed, mixed> as $state_style. That is a more accurate account of the untyped theme.json data than the missingType.iterableValue error it replaces. None of these errors are in the level 5 baselines.

Viewport media queries

WP_Theme_JSON::get_viewport_media_queries() only ever returns the @mobile, @tablet, and @desktop keys, each holding a non-empty @media query string, so this documents that in a @phpstan-return array shape:

array{
    '@mobile'?: non-falsy-string,
    '@tablet'?: non-falsy-string,
    '@desktop'?: non-falsy-string,
}

Without it, callers see each media query as mixed. The Navigation block passes them to wp_style_engine_get_stylesheet_from_css_rules() as the rules_group, which expects a string.

Gutenberg PRs depending on this

These Gutenberg PRs generate their WordPress stubs for PHPStan from this PR, so that the analysis sees these types:

• Theme JSON, Duotone: Fix return types and docblocks reported by PHPStan gutenberg#86103 applies the selectors shape in WP_Theme_JSON_Gutenberg and gutenberg_get_state_style_groups().
• PHPStan: Resolve always-true type checks gutenberg#86104 relies on the viewport media queries shape for the Navigation block.

Once this is committed, they will need their stubs regenerated from trunk before they are merged.

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5 (medium effort)
Used for: Deriving the array shape from the block.json schema and the code that reads the selectors, applying it, comparing PHPStan results before and after, running the related PHPUnit tests, and writing this description. Directed and reviewed by me.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[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.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

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

Props westonruter.

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

---

Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

• @propsbot add <username> to give props to a GitHub user. Requires write access.
• @propsbot remove <username> to leave a user out of the props. Requires write access.
• @propsbot refresh to refresh this list. Adding the props-bot label works too.

[Copilot]

🟢 Approval recommended

No active issues were identified, and the change is narrowly scoped to typed selector metadata, root-selector preservation, and focused test coverage.

No open issues 🎉

What changed in this PR

This pull request adds precise PHPDoc/PHPStan array shapes for block selectors and viewport media queries, while preserving the root selector during default selector generation. It also adds focused PHPUnit coverage.

Changes:

• Documents selector shapes across block types, theme JSON processing, and state-style helpers.
• Documents optional @mobile, @tablet, and @desktop media-query keys as non-empty strings.
• Refactors default selector construction to preserve the root selector.
• Adds tests for selector ordering, custom selectors, and subclass root-selector handling.

File	Description	Review note
tests/​phpunit/​tests/​theme/​wpThemeJson.php	Tests default selector ordering, custom selector passthrough, and root-selector preservation.	—
src/​wp-includes/​class-wp-theme-json.php	Adds selector and viewport media-query types and preserves the root selector during default generation.	Nit (1 vote): Keep the metadata shape open while narrowing the selectors key, since call sites provide additional keys such as path, selector, elements, and variations.
src/​wp-includes/​class-wp-block-type.php	Documents the structure of block selector metadata on the property and constructor arguments.	—
src/​wp-includes/​block-supports/​states.php	Adds precise types for state styles and block selector metadata.	—

_{Review effort: Lite}