Skip to content

Expose ordered engine support CSS as its own asset - #877

Merged
borkweb merged 6 commits into
trunkfrom
fix/engine-support-css-asset
Aug 14, 2026
Merged

Expose ordered engine support CSS as its own asset#877
borkweb merged 6 commits into
trunkfrom
fix/engine-support-css-asset

Conversation

@borkweb

@borkweb borkweb commented Aug 14, 2026

Copy link
Copy Markdown
Member

Why

HtmlTransformer::materializeAuthorStylesheet() concatenated two different things into one
generated asset (source: 'author-css'): the engine support CSS the transformer generates so
its own output works, and the rewritten author stylesheet. A consumer that writes its own
author CSS cannot take the second, and had no reliable way to extract the first.

The real consumer — automattic/site-build — was reduced to grepping the asset for
/\.(be-inline-geometry-[a-z0-9-]+)\{[^{}]*\}/ and discarding everything else. Measured across six
generated sites, every engine marker class appeared in the block markup with zero matching CSS
in the theme:

  • <mark> richtext carriers rendered with the browser default yellow highlight on headlines and
    brand text — 15–42 unstyled marks per site, an accessibility regression.
  • Synthetic <p> wrappers kept UA margin:1em 0, so header/nav lockups sat misaligned.
  • blocks-engine-control-* button rules were dropped — 10 occurrences in one site's markup, 22 in
    another, 0 matching rules in either theme. Transformed buttons rendered unstyled.

A shape-based regex in the consumer was considered and rejected: the generated rules already use four
distinct selector shapes (:where(.blocks-engine-*), :where(mark)[style*=…],
.blocks-engine-control-X.blocks-engine-control-X>.wp-block-button__link, .wp-block-navigation…),
so any regex under-carries. The boundary is knowledge only the transformer has.

What changed

1. The generated stylesheet is split by ownership. author-css now holds only the rewritten
author stylesheet plus its own leading at-rule preamble. Engine-generated rules move to
source: 'engine-support' assets.

2. Cascade order is preserved and expressible. Some support rules deliberately preceded the
author CSS (carrier rules keeping inline precedence) and others deliberately followed it
(list-navigation display:flex!important, mobile overlay, button rules). A single support asset
would have lost that, so assets carry stylesheet_placement: before-author | author |
after-author. A consumer that never takes the author CSS at all still knows which side each rule
belongs on. ArtifactCompiler orders them beforeAuthor → manifest → other → afterAuthor.

3. New blocks-engine-css-owned-layout neutralizer. Rules already existed for
css-owned-flow, css-owned-grid and css-owned-layout-item, but nothing for css-owned-layout.
In a real WordPress theme a layout:constrained block gets core CSS applying
max-width: <contentSize>; margin-inline: auto to its non-aligned children — which collapses a
CSS-owned flex container toward the centre. Observed downstream: a primary nav rendering ~860px wide
and centred inside a header the author CSS sized at 1280px. The static-site output never sees core
layout CSS, so the gap was invisible there.

4. The richtext-marker <mark> is now self-sufficient. It carries inline
background-color:transparent;color:inherit, matching what the styled-inline path already did — the
divergence between the two paths was itself the bug. The :where() stylesheet reset is retained,
not replaced: zero specificity means it never fights the inline value, and it still covers consumers
whose sanitizers strip inline styles.

Verification

Gate Result
composer test exit 0
Parity fixtures 275 passed
tests/unit/engine-support-css-asset.php 49 assertions

The 11 modified parity fixtures are legitimate expected-output changes: marks gain inline
background-color:transparent, and one asset count goes 1 → 2 where the new css-owned-layout
neutralizer applies.

VERSION → 0.4.17; CHANGELOG names the new asset source, the placement enum, and the neutralizer.

@borkweb
borkweb marked this pull request as draft August 14, 2026 20:25
Remove the aggressive css-owned-layout neutralizer and restore marker-only background and color guards so engine defaults no longer outrank authored declarations.
@borkweb
borkweb marked this pull request as ready for review August 14, 2026 21:03
@borkweb
borkweb merged commit 0765240 into trunk Aug 14, 2026
4 checks passed
@borkweb
borkweb deleted the fix/engine-support-css-asset branch August 14, 2026 22:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant