From 903f6fcd54933f49658469c6a8530da32a9edaff Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Wed, 9 Sep 2026 13:09:32 -0400
Subject: [PATCH] fix(php-transformer): honor explicit block flow

---
 .../src/HtmlToBlocks/Patterns/ColumnsPattern.php          | 6 ++++++
 .../tests/unit/block-style-support-conversion.php         | 8 ++++++++
 2 files changed, 14 insertions(+)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/ColumnsPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/ColumnsPattern.php
index e8ded4d0f..b88303fda 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/ColumnsPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/ColumnsPattern.php
@@ -157,6 +157,12 @@ private function looksLikeColumnsContainer(DOMElement $element, string $resolved
             return false;
         }
 
+        // Semantic sidebar/content names can suggest a split layout only when
+        // author CSS does not explicitly retain normal document flow.
+        if ( preg_match('/(?:^|;)\s*display\s*:\s*(?:block|inline|flow-root|contents)\b/', $style) ) {
+            return false;
+        }
+
         // core/columns is a flex layout. Preserve resolved grid containers as
         // groups so their source classes continue to control track geometry.
         if ( preg_match('/(?:^|;)\s*display\s*:\s*(?:inline-)?grid\b/', $style) ) {
diff --git a/php-transformer/tests/unit/block-style-support-conversion.php b/php-transformer/tests/unit/block-style-support-conversion.php
index 59ed1176a..ad29cb9bc 100644
--- a/php-transformer/tests/unit/block-style-support-conversion.php
+++ b/php-transformer/tests/unit/block-style-support-conversion.php
@@ -295,6 +295,14 @@
 $nativeColumnsBlock = $nativeColumnsResult['blocks'][0] ?? array();
 $assert('core/columns' === ($nativeColumnsBlock['blockName'] ?? ''), '29: explicit native Columns markup remains core Columns', (string) ($nativeColumnsBlock['blockName'] ?? '(none)'));
 
+$blockFlowSidebarHtml = '<div class="plain-wrapper"><aside>Sidebar</aside><main>Content</main></div>';
+$blockFlowSidebarResult = ( new HtmlTransformer() )->transform($blockFlowSidebarHtml, array('static_css' => '.plain-wrapper{display:block}.lightbox{display:none}'))->toArray();
+$blockFlowSidebarBlock = $blockFlowSidebarResult['blocks'][0] ?? array();
+$blockFlowSidebarMarkup = (string) ($blockFlowSidebarResult['serialized_blocks'] ?? '');
+
+$assert('core/group' === ($blockFlowSidebarBlock['blockName'] ?? ''), '29a: explicit block flow overrides semantic sidebar/content column inference', (string) ($blockFlowSidebarBlock['blockName'] ?? '(none)'));
+$assert(! str_contains($blockFlowSidebarMarkup, '<!-- wp:columns'), '29b: explicit block flow never serializes core Columns', $blockFlowSidebarMarkup);
+
 $labelHtml = '<section class="pricing"><div class="section-head"><div class="tag" style="padding:4px 12px;border:1px solid #6b4f2d;border-radius:100px;background:#f2e3c6;width:137px;height:28px">Pricing</div><h2>Simple plans</h2></div><article class="pricing-card"><div class="tier-name">Team</div><div class="tier-price"><span class="amount">$29</span>/mo</div><div class="use-case-result">Launch faster</div></article></section>';
 $labelCss = '.tag{display:inline-flex;align-items:center;gap:6px;padding:4px 12px;border-radius:100px}.pricing-card{padding:2rem}.tier-name{font-family:monospace;font-size:11px;letter-spacing:.12em;text-transform:uppercase}.tier-price{display:flex;align-items:flex-end;gap:6px}.use-case-result{display:flex;align-items:center;gap:8px;padding:10px 14px;border-radius:6px}';
 $labelResult = ( new HtmlTransformer() )->transform($labelHtml, array('static_css' => $labelCss))->toArray();