#64099: Improve hoisted stylesheet ordering #10436

westonruter · 2025-10-30T00:03:31Z

This primarily ensures that stylesheets related to blocks are inserted right after wp-block-library whereas other stylesheets not related to blocks are appended to the end of the HEAD. This helps ensure the expected cascade is preserved. If no wp-block-library inline style is present, then all styles get appended to the HEAD regardless.

When the CSS placeholder comment is removed from the wp-block-library inline style, the entire inline style is now removed if there are no styles left (aside from the sourceURL comment).

This PR also addresses various deficiencies with the logic in wp_load_classic_theme_block_styles_on_demand() and wp_hoist_late_printed_styles() after more thorough review.

Lastly, the use of the HTML Tag Processor was significantly improved to leverage WP_HTML_Text_Replacement.

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

This is a follow-up to #10288 (r61008) and to @dmsnell's post-merge feedback.

Gemini Review

The changes introduce a new mechanism for hoisting late-printed styles, particularly block-related styles, to the <head> section in classic themes. This is a significant improvement for performance and proper CSS cascade.

Here's a detailed review:

phpcompat.xml.dist

Observation: A new exclusion rule for PHPCompatibility.FunctionDeclarations.NewClosure.ThisFoundOutsideClass has been added for /src/wp-includes/script-loader.php.
Review: This indicates a new closure using this outside a class context has been introduced. The comment correctly notes this is a temporary exclusion pending PHPCompatibility v10. This is acceptable as a temporary measure, but it's important to follow up and remove this exclusion once the compatibility issue is resolved.

src/wp-includes/script-loader.php

Docblock for wp_print_head_scripts():
- Observation: The docblock has been updated to provide a clearer explanation of how wp_hoist_late_printed_styles() functions, detailing the two sets of styles (block-related and others) and their hoisting.
- Review: This is a good improvement for code clarity and documentation.
wp_load_classic_theme_block_styles_on_demand():
- Observation: Comments have been refined for clarity regarding opt-out mechanisms. A new early exit if ( ! wp_should_load_separate_core_block_assets() ) { return; } has been added. The print_late_styles filter and its associated comment have been removed.
- Review: The early exit is a good optimization. The removal of the print_late_styles filter suggests a more streamlined approach to handling late styles, which is positive.
wp_hoist_late_printed_styles():
- Observation: The capture_late_styles closure now captures both $printed_block_styles and $printed_late_styles. Logic has been added to differentiate and gather block-related styles. print_late_styles() is replaced by wp_styles()->do_footer_items(). The anonymous WP_HTML_Tag_Processor class has new utility methods (get_span, insert_before, insert_after, remove). The style insertion logic within the wp_template_enhancement_output_buffer filter has been significantly refactored to precisely insert block styles after wp-block-library-inline-css and other late styles before </head>. It also handles the removal of empty inline style tags.
- Review: This is the core of the change and appears well-executed. Separating block styles from other late styles is crucial for maintaining the CSS cascade. The use of WP_HTML_Tag_Processor for precise HTML manipulation is a robust approach. The logic for removing empty inline style tags (especially those only containing a sourceURL comment) is a good detail.
- Nitpick: The regex preg_match( ':^/\*# sourceURL=\\S+? \*/$:', trim( $css_text ) ) is quite specific. A brief comment explaining its purpose (to identify an inline style that is effectively empty, containing only a sourceURL comment) would enhance readability.

tests/phpunit/tests/template.php

setUp() and tearDown():
- Observation: Several lines related to global wp_scripts, wp_styles, and _wp_theme_features have been removed.
- Review: This suggests a cleaner test setup and teardown, indicating that these globals are either no longer being directly manipulated or are handled by other mechanisms.
data_wp_hoist_late_printed_styles():
- Observation: The data provider now includes inline_size_limit and expected_styles, and new test cases have been added to cover various scenarios (e.g., min/max inline styles, opting out of separate block styles, disabling block library).
- Review: This is a substantial improvement in test coverage, ensuring the new logic is thoroughly validated under different configurations.
test_wp_hoist_late_printed_styles():
- Observation: The method signature is updated. switch_theme('default') is called earlier. Filters for styles_inline_size_limit and wp_get_custom_css are added. wp_load_classic_theme_block_styles_on_demand() and register_core_block_style_handles() are explicitly called. A new helper ensure_style_asset_file_created() is used to create necessary CSS files for testing. wp_enqueue_style now uses https. The wp_hoist_late_printed_styles() call is conditional. the_content filter is applied. Assertions are updated to use the new $expected_styles array and a new helper get_array_snapshot_export().
- Review: These are excellent improvements. The ensure_style_asset_file_created() helper makes the tests more robust by not relying on a prior build step. The expanded assertions and the get_array_snapshot_export() helper significantly improve the maintainability and clarity of the test suite, especially for snapshot testing. The @ticket and @covers tags are correctly used.

Conclusion:

The changes are well-implemented and significantly improve the handling of late-printed styles in classic themes, particularly for block styles. The accompanying test suite is comprehensive and robust. The temporary phpcompat.xml.dist exclusion should be addressed in the future.

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.

…istered()

…ideClass suppression for PHPCS See WordPress#10288 (comment)

…sideClass in script-loader.php

github-actions · 2025-10-30T00:25:06Z

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

The Plugin and Theme Directories cannot be accessed within Playground.
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.

dmsnell · 2025-10-30T03:14:59Z

src/wp-includes/script-loader.php

-					$instance->set_bookmark( 'here' );
-					return $instance->bookmarks['here'];
+					$this->set_bookmark( 'here' );
+					return $this->bookmarks['here'];


so much better with the removal of the additional surprising complexity!

dmsnell · 2025-10-30T03:18:45Z

tests/phpunit/tests/template.php

 	}

+	/**
+	 * Export PHP array as string formatted for pasting into unit test case.


a brief example would go a long way. I have a rough idea of what this is supposed to do, which I assume is to aid in debugging test failures, but I really can’t visualize it.

Added in 156c6f5

dmsnell · 2025-10-30T03:19:28Z

tests/phpunit/tests/template.php

+		$export = preg_replace( '/\barray \($/m', 'array(', $export );
+		if ( isset( $snapshot[0] ) ) {
+			$export = preg_replace( '/^(\s+)\d+\s+=>\s+/m', '$1', $export );
+		}


we’re trying to remove numeric indices?

Yeah, unfortunately var_export() includes them, even when sequential and starting from 0.

…into trac-64099-improve-hoisted-stylesheet-ordering

…of HEAD

…into trac-64099-improve-hoisted-stylesheet-ordering

Co-authored-by: Dennis Snell <[email protected]>

…parate_core_block_assets was disabled

westonruter · 2025-11-05T07:00:23Z

src/wp-includes/script-loader.php

+		function ( $buffer ) use ( $placeholder, &$printed_block_styles, &$printed_late_styles ) {

 			// Anonymous subclass of WP_HTML_Tag_Processor which exposes underlying bookmark spans.
 			$processor = new class( $buffer ) extends WP_HTML_Tag_Processor {


@dmsnell How does this updated WP_HTML_Tag_Processor extension look here? Note the insert_before and insert_after methods.

And now a review method as well.

…ave no effect

…into trac-64099-improve-hoisted-stylesheet-ordering

westonruter · 2025-11-06T03:17:46Z

This was a big headache. But I believe all the kinks are now worked out!

peterwilsoncc · 2025-11-06T23:00:43Z

I've tested this with a helper plugin that includes ~~three~~ four functions to run and am seeing some regressions between the 6.8 branch and this one when it comes to de registering or modifying the block CSS.

There's various ways a theme may wish to modify the block styles that are now being replaced with Core's styles.

Test function	WordPress 6.8	Feature branch	Result
`add_dependency_to_block_library`			✅
`deregister_and_replace_blocks_styles`			⚠️
`remove_theme_support_block_styles`			⚠️
`register_custom_block_styles`			⚠️

…into trac-64099-improve-hoisted-stylesheet-ordering

…le is printed and ensure it is added just in time

westonruter · 2025-11-07T03:02:22Z

@peterwilsoncc Thank you for this. After evaluating the error scenarios, they all appear to be the same as is described in my ticket comment. Namely, if a site is explicitly expecting wp-block-library to be present and not the separate block styles, then they need to add this plugin code:

add_filter( 'should_load_separate_core_block_assets', '__return_false' );

This needs to be called out in the dev note for sure.

…into trac-64099-improve-hoisted-stylesheet-ordering

Reverts part of 9f816a3 It turns out the depenency src is empty when a build hasn't been done

peterwilsoncc

This looks good for commit.

I've gone through manual testing and reviewed the code in the editor as the diff is a little less clear than reading the code.

As discussed here and in slack, I think we'll need to shout out classic themes replacing styles in the dev note to ensure they are using the correct filters.

Hitting approve as the tests look firmly on their way to passing.

…) to preserve CSS cascade. This ensures that on-demand block styles are inserted right after the `wp-block-library` inline style whereas other stylesheets not related to blocks are appended to the end of the `HEAD`. This helps ensure the expected cascade is preserved. If no `wp-block-library` inline style is present, then all styles get appended to the `HEAD` regardless. The handling of the CSS placeholder comment added to the `wp-block-library` inline style is also improved. It is now inserted later to ensure the inline style is printed. Additionally, when the CSS placeholder comment is removed from the `wp-block-library` inline style, the entire `STYLE` tag is now removed if there are no styles left (aside from the `sourceURL` comment). Lastly, the use of the HTML Tag Processor is significantly improved to leverage `WP_HTML_Text_Replacement`. Developed in #10436 Follow-up to [61008]. Props westonruter, peterwilsoncc, dmsnell. Fixes #64099. git-svn-id: https://develop.svn.wordpress.org/trunk@61174 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2025-11-07T04:28:13Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61174
GitHub commit: 5b28781

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

…) to preserve CSS cascade. This ensures that on-demand block styles are inserted right after the `wp-block-library` inline style whereas other stylesheets not related to blocks are appended to the end of the `HEAD`. This helps ensure the expected cascade is preserved. If no `wp-block-library` inline style is present, then all styles get appended to the `HEAD` regardless. The handling of the CSS placeholder comment added to the `wp-block-library` inline style is also improved. It is now inserted later to ensure the inline style is printed. Additionally, when the CSS placeholder comment is removed from the `wp-block-library` inline style, the entire `STYLE` tag is now removed if there are no styles left (aside from the `sourceURL` comment). Lastly, the use of the HTML Tag Processor is significantly improved to leverage `WP_HTML_Text_Replacement`. Developed in WordPress/wordpress-develop#10436 Follow-up to [61008]. Props westonruter, peterwilsoncc, dmsnell. Fixes #64099. Built from https://develop.svn.wordpress.org/trunk@61174 git-svn-id: http://core.svn.wordpress.org/trunk@60510 1a063a9b-81f0-0310-95a4-ce76da25c4cd

…) to preserve CSS cascade. This ensures that on-demand block styles are inserted right after the `wp-block-library` inline style whereas other stylesheets not related to blocks are appended to the end of the `HEAD`. This helps ensure the expected cascade is preserved. If no `wp-block-library` inline style is present, then all styles get appended to the `HEAD` regardless. The handling of the CSS placeholder comment added to the `wp-block-library` inline style is also improved. It is now inserted later to ensure the inline style is printed. Additionally, when the CSS placeholder comment is removed from the `wp-block-library` inline style, the entire `STYLE` tag is now removed if there are no styles left (aside from the `sourceURL` comment). Lastly, the use of the HTML Tag Processor is significantly improved to leverage `WP_HTML_Text_Replacement`. Developed in WordPress/wordpress-develop#10436 Follow-up to [61008]. Props westonruter, peterwilsoncc, dmsnell. Fixes #64099. Built from https://develop.svn.wordpress.org/trunk@61174 git-svn-id: https://core.svn.wordpress.org/trunk@60510 1a063a9b-81f0-0310-95a4-ce76da25c4cd

dmsnell

@westonruter the HTML API usage looks nice. adding those extra methods to the anonymous class does clean up the logic in the part handling the STYLE placeholders.

dmsnell · 2025-11-17T21:02:45Z

src/wp-includes/script-loader.php

+				 */
+				private function get_span(): WP_HTML_Span {
+					// Note: This call will never fail according to the usage of this class, given it is always called after ::next_tag() is true.
+					$this->set_bookmark( 'here' );


technically it could also fail if there are too many bookmarks already. probably not an issue. in my own code I haven’t been documenting these cases of overlooking the failure given I control the whole flow of execution in the anonymous classes.

westonruter added 9 commits October 29, 2025 17:02

Use well-formed HTML in tests

137e732

Use HTTPS and fix late inline style contents

f5d49cd

Add separate test case specifically for filtering print_late_styles

cccb1ef

Add comment for PHPCompatibility issue

137b9de

Use more specific return type for WP_Block_Type_Registry::get_all_reg…

8975233

…istered()

Remove PHPCompatibility.FunctionDeclarations.NewClosure.ThisFoundOuts…

6308437

…ideClass suppression for PHPCS See WordPress#10288 (comment)

Add a rendered block to the output

2d94ec6

Add failing test cases for test_wp_hoist_late_printed_styles

2d537f7

Exclude PHPCompatibility.FunctionDeclarations.NewClosure.ThisFoundOut…

92cd33c

…sideClass in script-loader.php

westonruter mentioned this pull request Oct 30, 2025

Add on demand block style loading in classic themes #10288

Closed

1 task

dmsnell reviewed Oct 30, 2025

View reviewed changes

westonruter changed the title ~~#4099: Improve hoisted stylesheet ordering~~ #64099: Improve hoisted stylesheet ordering Nov 2, 2025

westonruter and others added 10 commits November 1, 2025 23:02

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

d5a964b

…into trac-64099-improve-hoisted-stylesheet-ordering

Print block styles after wp-block-library and everything else at end …

53d21e6

…of HEAD

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

9d8bd27

…into trac-64099-improve-hoisted-stylesheet-ordering

Add example for get_array_snapshot_export

156c6f5

Co-authored-by: Dennis Snell <[email protected]>

Prevent enabling should_load_block_assets_on_demand if should_load_se…

16d3f54

…parate_core_block_assets was disabled

Improve tests

99b1b42

Remove obsolete print_late_styles override

28faf6d

Update tests

d305804

Add todo comments

e8482a0

Refactor HTML Tag Processor logic

54b2474

westonruter commented Nov 5, 2025

View reviewed changes

westonruter added 5 commits November 5, 2025 11:41

Fix missing use of footer in assertion

d93e767

Use correct variable in assertion

ec25a5f

Remove unhelpful test cases since print_late_styles filter seems to h…

53ef0c6

…ave no effect

Set styles_inline_size_limit to unlimited for test

ead1aa2

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

d2afb80

…into trac-64099-improve-hoisted-stylesheet-ordering

westonruter force-pushed the trac-64099-improve-hoisted-stylesheet-ordering branch 4 times, most recently from 2b38a00 to 1895883 Compare November 6, 2025 01:53

Debug

fd0c402

westonruter force-pushed the trac-64099-improve-hoisted-stylesheet-ordering branch from 1895883 to fd0c402 Compare November 6, 2025 02:55

Undebug

c2fd29f

westonruter force-pushed the trac-64099-improve-hoisted-stylesheet-ordering branch from dd0ce41 to c2fd29f Compare November 6, 2025 03:15

westonruter marked this pull request as ready for review November 6, 2025 03:17

westonruter requested review from dmsnell and peterwilsoncc November 6, 2025 03:17

westonruter added 4 commits November 6, 2025 16:21

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

4447f46

…into trac-64099-improve-hoisted-stylesheet-ordering

Opt for ignore list rather than ack list

9607f0e

Only use placeholder comment for ensuring wp-block-library inline sty…

9b86cde

…le is printed and ensure it is added just in time

Improve ensure_style_asset_file_created helper

9f816a3

westonruter and others added 5 commits November 6, 2025 19:08

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

b8f8d37

…into trac-64099-improve-hoisted-stylesheet-ordering

Remove see wrappers of auto-linked function names in dev docs.

0a6564e

Add missing static to closure

885bddd

Unimprove ensure_style_asset_file_created helper

2216f14

Reverts part of 9f816a3 It turns out the depenency src is empty when a build hasn't been done

Update phpcs exclusion after 885bddd

732b28e

peterwilsoncc approved these changes Nov 7, 2025

View reviewed changes

github-actions bot closed this Nov 7, 2025

dmsnell reviewed Nov 17, 2025

View reviewed changes

#64099: Improve hoisted stylesheet ordering #10436

#64099: Improve hoisted stylesheet ordering #10436

Uh oh!

Conversation

westonruter commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Gemini Review

Uh oh!

github-actions bot commented Oct 30, 2025

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westonruter commented Nov 6, 2025

Uh oh!

peterwilsoncc commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

westonruter commented Nov 7, 2025

Uh oh!

peterwilsoncc left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 7, 2025

Uh oh!

dmsnell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

westonruter commented Oct 30, 2025 •

edited

Loading

peterwilsoncc commented Nov 6, 2025 •

edited

Loading