From d3cc2fad009813659b69a008844f0d5711e52082 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Thu, 10 Sep 2026 20:50:48 -0400
Subject: [PATCH 1/5] fix(navigation): preserve separate responsive menus

---
 .../Style/GeneratedBlockStyleProjector.php    |  4 +-
 .../Support/NavigationToggleSuppressor.php    | 38 +++++++++++++++++++
 php-transformer/tests/contract/run.php        | 23 +++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/php-transformer/src/HtmlToBlocks/Style/GeneratedBlockStyleProjector.php b/php-transformer/src/HtmlToBlocks/Style/GeneratedBlockStyleProjector.php
index d0a3d5a57..34219a5cc 100644
--- a/php-transformer/src/HtmlToBlocks/Style/GeneratedBlockStyleProjector.php
+++ b/php-transformer/src/HtmlToBlocks/Style/GeneratedBlockStyleProjector.php
@@ -44,7 +44,9 @@ public function applyDeclaredBlockSupport(
                 }
             }
         }
-        if ( 'core/navigation' === $name && is_array($fallback['spacing'] ?? null) ) {
+        if ( 'core/navigation' === $name
+            && ! in_array('blocks-engine-list-navigation', $classes, true)
+            && is_array($fallback['spacing'] ?? null) ) {
             $declarations = $this->styleResolver->styleAttributeMapper()->serialize(array( 'spacing' => $fallback['spacing'] ))['style'];
             foreach ( $classes as $class ) {
                 if ( '' !== $declarations && 'blocks-engine-list-navigation' !== $class && ! str_starts_with($class, 'blocks-engine-') ) {
diff --git a/php-transformer/src/HtmlToBlocks/Support/NavigationToggleSuppressor.php b/php-transformer/src/HtmlToBlocks/Support/NavigationToggleSuppressor.php
index 85751af1b..28fffb2a4 100644
--- a/php-transformer/src/HtmlToBlocks/Support/NavigationToggleSuppressor.php
+++ b/php-transformer/src/HtmlToBlocks/Support/NavigationToggleSuppressor.php
@@ -766,15 +766,25 @@ private function hasEquivalentSourceNavigationVariant(DOMElement $navigation): b
         }
 
         $navigationRoot = $this->navigationLandmarkAncestor($navigation) ?? $navigation;
+        // A captured details disclosure owns its summary and panel navigation.
+        // It remains an independent mobile surface, rather than evidence that a
+        // sibling desktop navigation should be replaced by Core's overlay toggle.
+        if ( $this->isInsideCapturedDisclosure($navigationRoot) ) {
+            return false;
+        }
         $signature = $this->sourceNavigationSignature($navigationRoot);
         if ( '' === $signature ) {
             return false;
         }
+        if ( $this->hasCapturedDisclosureNavigation($document, $signature) ) {
+            return false;
+        }
 
         foreach ( $document->getElementsByTagName('nav') as $candidate ) {
             if ( ! $candidate instanceof DOMElement
                 || $candidate->isSameNode($navigationRoot)
                 || $this->isProjectedNavigationSuppressed($candidate)
+                || $this->isInsideCapturedDisclosure($candidate)
                 || SourceDom::elementContains($navigationRoot, $candidate)
                 || SourceDom::elementContains($candidate, $navigationRoot)
             ) {
@@ -790,6 +800,34 @@ private function hasEquivalentSourceNavigationVariant(DOMElement $navigation): b
         return false;
     }
 
+    private function hasCapturedDisclosureNavigation(DOMDocument $document, string $signature): bool
+    {
+        foreach ( $document->getElementsByTagName('details') as $disclosure ) {
+            if ( ! $disclosure instanceof DOMElement || ! $this->isCapturedDialogControl($disclosure) ) {
+                continue;
+            }
+
+            foreach ( $disclosure->getElementsByTagName('nav') as $candidate ) {
+                if ( $candidate instanceof DOMElement && $signature === $this->sourceNavigationSignature($candidate) ) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    private function isInsideCapturedDisclosure(DOMElement $element): bool
+    {
+        for ( $node = $element; $node instanceof DOMElement; $node = $node->parentNode ) {
+            if ( 'details' === strtolower($node->tagName) && $this->isCapturedDialogControl($node) ) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     private function hasMobileNavigationSignal(DOMElement $element): bool
     {
         for ( $node = $element; $node instanceof DOMElement && 'body' !== strtolower($node->tagName); $node = $node->parentNode ) {
diff --git a/php-transformer/tests/contract/run.php b/php-transformer/tests/contract/run.php
index 26f8b40e0..31bfe33f3 100644
--- a/php-transformer/tests/contract/run.php
+++ b/php-transformer/tests/contract/run.php
@@ -1018,6 +1018,29 @@ public function recognize(DOMElement $element, PatternContext $context): ?Patter
 $capturedMobileMenuDisclosureMarkup = (string) ($capturedMobileMenuDisclosure['serialized_blocks'] ?? '');
 $assert(str_contains($capturedMobileMenuDisclosureMarkup, '"overlayMenu":"never"') && ! str_contains($capturedMobileMenuDisclosureMarkup, 'blocks-engine-native-responsive-navigation'), 'navigation inside a captured native disclosure does not create a nested mobile overlay', $capturedMobileMenuDisclosureMarkup);
 
+// Separate desktop and mobile source surfaces are not an overlay pair when the
+// mobile menu keeps its own native details interaction. In particular, the
+// desktop menu must retain its authored display at desktop widths instead of
+// receiving the global native-responsive display:flex bridge.
+$separateResponsiveMenuArtifact = ( new ArtifactCompiler() )->compile(
+    array(
+        'entry' => 'index.html',
+        'files' => array(
+            'index.html' => '<!doctype html><html><head><style>'
+                . '.data-liberation-mobile-document{display:none!important}'
+                . '@media(max-width:768px){.data-liberation-desktop-document{display:none!important}.data-liberation-mobile-document{display:contents!important}}'
+                . '@media(min-width:769px){.desktop-navbar{display:block}}'
+                . '</style></head><body><div class="data-liberation-desktop-document"><header><nav class="desktop-navbar"><ul><li><a href="/">Home</a></li><li><a href="/contact">Contact</a></li></ul></nav></header></div>'
+                . '<div class="data-liberation-mobile-document"><header><details class="dla-disclosure"><summary aria-label="Menu"><svg aria-hidden="true"></svg></summary><div class="dla-dialog" role="dialog"><nav class="mobile-navbar"><ul><li><a href="/">Home</a></li><li><a href="/contact">Contact</a></li></ul></nav></div></details></header></div></body></html>',
+        ),
+    )
+)->toArray();
+$separateResponsiveMenuMarkup = (string) ($separateResponsiveMenuArtifact['serialized_blocks'] ?? '');
+$separateResponsiveMenuCss = implode("\n", array_map(static fn (array $asset): string => 'css' === ($asset['kind'] ?? '') ? (string) ($asset['content'] ?? '') : '', $separateResponsiveMenuArtifact['assets'] ?? array()));
+$assert(! str_contains($separateResponsiveMenuMarkup, 'blocks-engine-native-responsive-navigation') && 2 === substr_count($separateResponsiveMenuMarkup, '"overlayMenu":"never"'), 'a separately preserved disclosure menu does not promote its desktop companion to native responsive navigation', $separateResponsiveMenuMarkup);
+$assert(str_contains($separateResponsiveMenuMarkup, '<!-- wp:details') && str_contains($separateResponsiveMenuMarkup, '<summary><svg aria-hidden="true">'), 'the mobile source summary remains the emitted interactive menu control', $separateResponsiveMenuMarkup);
+$assert(str_contains($separateResponsiveMenuCss, '@media(max-width:768px)') && str_contains($separateResponsiveMenuCss, '@media(min-width:769px)') && ! str_contains($separateResponsiveMenuCss, 'blocks-engine-native-responsive-navigation{display:flex!important}'), 'the emitted artifact retains authored mobile and desktop menu visibility without a native host override', $separateResponsiveMenuCss);
+
 $linkedCapturedDisclosure = ( new HtmlTransformer() )->transform('<details><summary>&nbsp;</summary><div role="dialog" data-blocks-engine-triggers="menu-trigger"><nav><a href="/about">About</a></nav></div></details>')->toArray();
 $linkedCapturedDisclosureBlock = $linkedCapturedDisclosure['blocks'][0] ?? array();
 $assert(str_ends_with((string) ($linkedCapturedDisclosureBlock['blockName'] ?? ''), '/captured-dialog') && array('menu-trigger') === ($linkedCapturedDisclosureBlock['attrs']['triggerIds'] ?? null), 'explicitly linked captured disclosures lower to the typed dialog block');

From f4b62d1ebbb2e22f09d39867982951719ec269ca Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Thu, 10 Sep 2026 21:33:32 -0400
Subject: [PATCH 2/5] fix(navigation): preserve resolved flow layout

---
 php-transformer/composer.json                 |  1 +
 .../Patterns/NavigationPattern.php            | 25 +++++++++
 .../tests/integration/wordpress-site-plan.php |  4 ++
 .../tests/unit/navigation-layout-default.php  | 53 +++++++++++++++++++
 .../tools/visual-parity/package.json          |  2 +-
 .../tests/navigation-layout-default.mjs       | 24 +++++++++
 6 files changed, 108 insertions(+), 1 deletion(-)
 create mode 100644 php-transformer/tests/unit/navigation-layout-default.php
 create mode 100644 php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs

diff --git a/php-transformer/composer.json b/php-transformer/composer.json
index b9117a266..b020fff3d 100644
--- a/php-transformer/composer.json
+++ b/php-transformer/composer.json
@@ -134,6 +134,7 @@
       "php tests/unit/navigation-block-normalizer.php",
       "php tests/unit/menu-chrome-presentation-carry.php",
       "php tests/unit/navigation-inline-margin-carry.php",
+      "php tests/unit/navigation-layout-default.php",
       "php tests/unit/navigation-source-provenance.php",
       "php tests/unit/navigation-dropped-anchors.php",
       "php tests/unit/navigation-inert-support-children.php",
diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 35cbae11b..acaf99930 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -95,6 +95,7 @@ public function recognize(DOMElement $element, PatternContext $context): ?Patter
         $navigationAttrs = $label instanceof DOMElement
             ? $this->nestedLabeledNavigationAttributes($element, $presentationAttributes)
             : $this->navigationContainerAttributes($element, $presentationAttributes);
+        $navigationAttrs = $this->withResolvedNonFlexNavigationLayout($navigationAttrs, $element, $navigationContext);
         $navigationAttrs['overlayMenu'] = $this->overlayMenu($element, $navigationContext);
         if ( 'mobile' === $navigationAttrs['overlayMenu'] ) {
             $navigationAttrs = $this->withClassName($navigationAttrs, 'blocks-engine-native-responsive-navigation');
@@ -605,6 +606,30 @@ private function withInlineNavigationDisplay(array $attrs, DOMElement $element,
         return $attrs;
     }
 
+    /** @param array<string, mixed> $attrs @return array<string, mixed> */
+    private function withResolvedNonFlexNavigationLayout(array $attrs, DOMElement $element, ?NavigationPatternContext $navigationContext): array
+    {
+        if ( null === $navigationContext || is_array($attrs['layout'] ?? null) ) {
+            return $attrs;
+        }
+
+        $display = '';
+        foreach ( CssValueSplitter::splitTopLevel($navigationContext->resolvedStyle($element), array( ';' )) as $declaration ) {
+            $separator = strpos($declaration, ':');
+            if ( false !== $separator && 'display' === strtolower(trim(substr($declaration, 0, $separator))) ) {
+                $display = strtolower(trim(preg_replace('/\s*!important\s*$/i', '', substr($declaration, $separator + 1)) ?? ''));
+            }
+        }
+
+        if ( '' !== $display && ! in_array($display, array( 'flex', 'inline-flex', 'grid', 'inline-grid' ), true) ) {
+            // core/navigation defaults to flex when layout is omitted. Core maps
+            // the explicit default layout to is-layout-flow at render time.
+            $attrs['layout'] = array( 'type' => 'default' );
+        }
+
+        return $attrs;
+    }
+
     private function resolvedStyleDeclaresFamily(string $style, string $family): bool
     {
         $property = match ( $family ) {
diff --git a/php-transformer/tests/integration/wordpress-site-plan.php b/php-transformer/tests/integration/wordpress-site-plan.php
index 0cc2e4536..72df9e501 100644
--- a/php-transformer/tests/integration/wordpress-site-plan.php
+++ b/php-transformer/tests/integration/wordpress-site-plan.php
@@ -167,6 +167,10 @@
 $videoBlock = parse_blocks($videoSaved)[0] ?? array();
 $nativeVideoBlock = $videoBlock['innerBlocks'][0] ?? array();
 $assert('core/group' === ($videoBlock['blockName'] ?? null) && 'bg-video' === ($videoBlock['attrs']['className'] ?? null) && 'core/video' === ($nativeVideoBlock['blockName'] ?? null) && ! str_contains($videoSaved, '"playsInline":true') && array(array( 'kind' => 'captions', 'src' => 'captions.vtt', 'srcLang' => 'en', 'label' => 'English', 'default' => true )) === ($nativeVideoBlock['attrs']['tracks'] ?? null) && str_contains($videoRendered, '<video src="hero.mp4" poster="hero.jpg" controls="controls" autoplay="autoplay" loop="loop" muted="muted" playsinline="playsinline"><track kind="captions" src="captions.vtt" srclang="en" label="English" default="default"></video>'), 'WordPress persists a custom-host geometry wrapper around editable core/video markup with poster, tracks, and playback metadata.');
+$flowNavigation = ( new HtmlTransformer() )->transform('<style>.flow-menu{display:block}</style><nav class="flow-menu"><ul><li><a href="/">Home</a></li></ul></nav>')->toArray();
+$flowNavigationSaved = serialize_blocks(parse_blocks((string) ($flowNavigation['serialized_blocks'] ?? '')));
+$flowNavigationRendered = do_blocks($flowNavigationSaved);
+$assert(str_contains($flowNavigationSaved, '"layout":{"type":"default"}') && str_contains($flowNavigationRendered, 'is-layout-flow') && ! str_contains($flowNavigationRendered, 'is-layout-flex'), 'WordPress parses the serialized non-flex navigation layout and renders its flow class instead of core/navigation default flex.');
 $stylableButton = (new HtmlTransformer())->transform('<style>.wix-label{padding:12px 20px;background:#173b64;border-radius:6px;color:#fff}</style><a class="wix-button" href="mailto:hello@example.com" target="_blank" rel="noopener external" aria-label="Email us"><span class="wix-label"><span>Email us</span></span><svg aria-hidden="true"><g><path d="M0 0h1v1z"/></g></svg></a>')->toArray();
 $stylableButtonMarkup = (string) ($stylableButton['serialized_blocks'] ?? '');
 $stylableButtonId = wp_insert_post(array('post_type' => 'page', 'post_status' => 'draft', 'post_title' => 'Stylable button', 'post_content' => serialize_blocks(parse_blocks($stylableButtonMarkup))), true);
diff --git a/php-transformer/tests/unit/navigation-layout-default.php b/php-transformer/tests/unit/navigation-layout-default.php
new file mode 100644
index 000000000..138fd69f9
--- /dev/null
+++ b/php-transformer/tests/unit/navigation-layout-default.php
@@ -0,0 +1,53 @@
+<?php
+declare(strict_types=1);
+
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
+
+use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\HtmlTransformer;
+
+$failures = 0;
+$passes = 0;
+$assert = static function (bool $condition, string $message, string $detail = '') use (&$failures, &$passes): void {
+    if ( $condition ) {
+        ++$passes;
+        return;
+    }
+
+    ++$failures;
+    fwrite(STDERR, 'FAIL: ' . $message . ( '' === $detail ? '' : ' - ' . $detail ) . PHP_EOL);
+};
+$navigation = static function (string $style): array {
+    return ( new HtmlTransformer() )->transform(
+        '<style>.menu{' . $style . '}</style><nav class="menu"><ul><li><a href="/">Home</a></li></ul></nav>'
+    )->toArray();
+};
+
+$block = $navigation('display:block');
+$attrs = $block['blocks'][0]['attrs'] ?? array();
+$serialized = (string) ($block['serialized_blocks'] ?? '');
+$assert('default' === ($attrs['layout']['type'] ?? null), 'a resolver-proven block navigation records the core flow layout');
+$assert(str_contains($serialized, '"layout":{"type":"default"}'), 'the flow layout survives canonical navigation serialization', $serialized);
+
+$vertical = ( new HtmlTransformer() )->transform('<nav style="display:flex;flex-direction:column"><ul><li><a href="/">Home</a></li></ul></nav>')->toArray();
+$assert(
+    array( 'type' => 'flex', 'orientation' => 'vertical' ) === ($vertical['blocks'][0]['attrs']['layout'] ?? null),
+    'an explicit vertical flex navigation retains its native flex intent'
+);
+
+$grid = ( new HtmlTransformer() )->transform('<nav style="display:grid"><ul><li><a href="/">Home</a></li></ul></nav>')->toArray();
+$gridClass = (string) ($grid['blocks'][0]['attrs']['className'] ?? '');
+$gridCss = implode("\n", array_column($grid['assets'] ?? array(), 'content'));
+$assert(
+    ! isset($grid['blocks'][0]['attrs']['layout']) && '' !== $gridClass && str_contains($gridCss, '.' . strtok($gridClass, ' ') . '{display:grid}'),
+    'an explicit grid navigation keeps its author-owned grid intent without a fabricated flow layout'
+);
+
+$unstyled = ( new HtmlTransformer() )->transform('<nav><ul><li><a href="/">Home</a></li></ul></nav>')->toArray();
+$assert(! isset($unstyled['blocks'][0]['attrs']['layout']), 'a navigation without resolved display evidence keeps the core default untouched');
+
+if ( 0 < $failures ) {
+    fwrite(STDERR, "Navigation default layout contract: {$failures} failed, {$passes} passed\n");
+    exit(1);
+}
+
+echo "Navigation default layout contract passed: {$passes} assertions\n";
diff --git a/php-transformer/tools/visual-parity/package.json b/php-transformer/tools/visual-parity/package.json
index 9c0adbffa..1c1aa65b7 100644
--- a/php-transformer/tools/visual-parity/package.json
+++ b/php-transformer/tools/visual-parity/package.json
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "install:browsers": "playwright install chromium",
-    "test": "node tests/smoke.mjs && node tests/blockquote-margin-reset.mjs && node tests/exact-fit-inline-flow.mjs && node tests/layout-shell-editor-geometry.mjs && node tests/custom-video-host-editor-geometry.mjs && node tests/issue-1493-reduced-public-fixture.mjs && node tests/responsive-document-variants.mjs && node tests/image-custom-host-promotion.mjs && node tests/empty-group-editor-height.mjs && node tests/button-height-ownership.mjs"
+    "test": "node tests/smoke.mjs && node tests/blockquote-margin-reset.mjs && node tests/exact-fit-inline-flow.mjs && node tests/layout-shell-editor-geometry.mjs && node tests/custom-video-host-editor-geometry.mjs && node tests/issue-1493-reduced-public-fixture.mjs && node tests/responsive-document-variants.mjs && node tests/image-custom-host-promotion.mjs && node tests/empty-group-editor-height.mjs && node tests/button-height-ownership.mjs && node tests/navigation-layout-default.mjs"
   },
   "devDependencies": {
     "playwright": "^1.56.0"
diff --git a/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs b/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs
new file mode 100644
index 000000000..461127ed7
--- /dev/null
+++ b/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs
@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { chromium } from 'playwright';
+
+const root = new URL('../../..', import.meta.url).pathname;
+const source = '<style>.flow-menu{display:block}</style><nav class="flow-menu"><ul><li><a href="/">Home</a></li></ul></nav>';
+const result = JSON.parse(execFileSync('php', ['-r', 'require $argv[1] . "/vendor/autoload.php"; echo json_encode((new Automattic\\BlocksEngine\\PhpTransformer\\HtmlToBlocks\\HtmlTransformer())->transform(base64_decode($argv[2]))->toArray());', root, Buffer.from(source).toString('base64')], { encoding: 'utf8' }));
+
+assert.equal(result.blocks[0]?.attrs?.layout?.type, 'default', 'serialized navigation carries explicit core flow layout');
+assert.match(result.serialized_blocks, /"layout":\{"type":"default"\}/, 'canonical block markup retains the flow layout attribute');
+
+const browser = await chromium.launch({ headless: true });
+try {
+  const page = await browser.newPage();
+  // This is the core/navigation server-rendered shape for layout.type default.
+  await page.setContent('<style>.is-layout-flow{display:block}.is-layout-flex{display:flex}</style><nav class="wp-block-navigation is-layout-flow wp-block-navigation-is-layout-flow"><ul class="wp-block-navigation__container wp-block-navigation"><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="/"><span class="wp-block-navigation-item__label">Home</span></a></li></ul></nav>');
+  const rendered = await page.locator('nav').evaluate((element) => ({ className: element.className, display: getComputedStyle(element).display }));
+  assert.match(rendered.className, /is-layout-flow/, 'WordPress-rendered navigation has the flow layout class');
+  assert.equal(rendered.display, 'block', 'the browser renders the WordPress flow navigation as block, not flex');
+} finally {
+  await browser.close();
+}
+
+console.log('Navigation default layout browser regression passed');

From c4f6197af5aa72d2dfe1daa0a33fa7c7d0c06bf3 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Thu, 10 Sep 2026 22:17:31 -0400
Subject: [PATCH 3/5] fix(navigation): resolve conditional display

---
 .../src/HtmlToBlocks/HtmlCompilation.php      |  5 +-
 .../Patterns/NavigationPattern.php            |  8 +---
 .../Patterns/NavigationPatternContext.php     | 11 ++++-
 .../src/HtmlToBlocks/Style/StyleResolver.php  | 48 ++++++++++++++++++-
 .../tests/unit/navigation-layout-default.php  | 12 +++++
 .../tests/navigation-layout-default.mjs       | 12 +++--
 6 files changed, 81 insertions(+), 15 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
index d732b76a7..08a5e886d 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
@@ -2560,7 +2560,7 @@ private function createPatternContext(bool $includeRuntimeDomTarget): PatternCon
             new NavigationPatternContext(
                 $includeRuntimeDomTarget ? fn (DOMElement $sourceElement): bool => $this->runtimeIslands->isRuntimeDomTarget($sourceElement) : null,
                 fn (DOMElement $item, DOMElement $anchor): string => $this->navigationUnderlineColor($item, $anchor),
-                fn (DOMElement $sourceElement): string => $this->styleResolver->resolveCssVariablesInValue($this->styleResolver->specificityResolvedPresentationStyle($sourceElement)),
+                fn (DOMElement $sourceElement): string => $this->styleResolver->resolveCssVariablesInValue($this->styleResolver->specificityResolvedPresentationStyle($sourceElement), $sourceElement),
                 fn (DOMElement $sourceElement): array => $this->navigationStyleProjector->navigationColorInteractionStates($sourceElement),
                 fn (DOMElement $sourceElement): string => $this->navigationToggleSuppressor->navigationOverlayMenu($sourceElement),
                 fn (DOMElement $sourceElement): string => $this->responsiveNavigationToggleMarker($sourceElement),
@@ -2569,7 +2569,8 @@ function (DOMElement $sourceElement, array $authorClasses): void {
                     $this->recordInheritedNavigationPresentation($sourceElement, $authorClasses);
                     $this->recordNavigationContainerPaintReset($sourceElement, $authorClasses);
                 },
-                fn (DOMElement $sourceElement): array => $this->authorSemanticMarkersForElement($sourceElement)
+                fn (DOMElement $sourceElement): array => $this->authorSemanticMarkersForElement($sourceElement),
+                fn (DOMElement $sourceElement): string => $this->styleResolver->resolvedConditionalDisplay($sourceElement)
             ),
             new MediaPatternContext(
                 fn (DOMElement $sourceElement): string => $this->styleResolver->mergedPresentationStyle($sourceElement),
diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index acaf99930..2d8445bd7 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -613,13 +613,7 @@ private function withResolvedNonFlexNavigationLayout(array $attrs, DOMElement $e
             return $attrs;
         }
 
-        $display = '';
-        foreach ( CssValueSplitter::splitTopLevel($navigationContext->resolvedStyle($element), array( ';' )) as $declaration ) {
-            $separator = strpos($declaration, ':');
-            if ( false !== $separator && 'display' === strtolower(trim(substr($declaration, 0, $separator))) ) {
-                $display = strtolower(trim(preg_replace('/\s*!important\s*$/i', '', substr($declaration, $separator + 1)) ?? ''));
-            }
-        }
+        $display = strtolower(trim($navigationContext->resolvedDisplay($element)));
 
         if ( '' !== $display && ! in_array($display, array( 'flex', 'inline-flex', 'grid', 'inline-grid' ), true) ) {
             // core/navigation defaults to flex when layout is omitted. Core maps
diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPatternContext.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPatternContext.php
index 7331fa447..7c0ac1bd2 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPatternContext.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPatternContext.php
@@ -12,6 +12,7 @@ final class NavigationPatternContext
     private readonly ?Closure $runtimeDomTarget;
     private readonly Closure $underlineColor;
     private readonly Closure $resolvedStyle;
+    private readonly ?Closure $resolvedDisplay;
     private readonly ?Closure $colorInteractionStates;
     private readonly ?Closure $overlayMenu;
     private readonly ?Closure $responsiveToggleMarker;
@@ -23,6 +24,7 @@ final class NavigationPatternContext
      * @param callable(DOMElement): bool|null $runtimeDomTarget
      * @param callable(DOMElement, DOMElement): string $underlineColor
      * @param callable(DOMElement): string $resolvedStyle
+     * @param callable(DOMElement): string|null $resolvedDisplay
      * @param callable(DOMElement): list<string>|null $colorInteractionStates
      * @param callable(DOMElement): string|null $overlayMenu
      * @param callable(DOMElement): string|null $responsiveToggleMarker
@@ -39,7 +41,8 @@ public function __construct(
         ?callable $responsiveToggleMarker = null,
         ?callable $linkIconMarker = null,
         ?callable $inheritedPresentation = null,
-        ?callable $labelPresentationMarkers = null
+        ?callable $labelPresentationMarkers = null,
+        ?callable $resolvedDisplay = null
     ) {
         $this->linkIconMarker         = null === $linkIconMarker ? null : Closure::fromCallable($linkIconMarker);
         $this->inheritedPresentation  = null === $inheritedPresentation ? null : Closure::fromCallable($inheritedPresentation);
@@ -47,6 +50,7 @@ public function __construct(
         $this->runtimeDomTarget       = null === $runtimeDomTarget ? null : Closure::fromCallable($runtimeDomTarget);
         $this->underlineColor         = Closure::fromCallable($underlineColor);
         $this->resolvedStyle          = Closure::fromCallable($resolvedStyle);
+        $this->resolvedDisplay        = null === $resolvedDisplay ? null : Closure::fromCallable($resolvedDisplay);
         $this->colorInteractionStates = null === $colorInteractionStates ? null : Closure::fromCallable($colorInteractionStates);
         $this->overlayMenu            = null === $overlayMenu ? null : Closure::fromCallable($overlayMenu);
         $this->responsiveToggleMarker = null === $responsiveToggleMarker ? null : Closure::fromCallable($responsiveToggleMarker);
@@ -78,6 +82,11 @@ public function resolvedStyle(DOMElement $element): string
         return ($this->resolvedStyle)($element);
     }
 
+    public function resolvedDisplay(DOMElement $element): string
+    {
+        return null === $this->resolvedDisplay ? '' : ($this->resolvedDisplay)($element);
+    }
+
     /** @return list<string> */
     public function colorInteractionStates(DOMElement $element): array
     {
diff --git a/php-transformer/src/HtmlToBlocks/Style/StyleResolver.php b/php-transformer/src/HtmlToBlocks/Style/StyleResolver.php
index a2d5aa057..200f507ea 100644
--- a/php-transformer/src/HtmlToBlocks/Style/StyleResolver.php
+++ b/php-transformer/src/HtmlToBlocks/Style/StyleResolver.php
@@ -403,6 +403,21 @@ public function conditionalDeclaration(DOMElement $element, string $property): s
         return $value;
     }
 
+    /**
+     * Resolve a source display declaration with the conditional custom-property
+     * scope that a responsive capture applies to the rendered element.
+     */
+    public function resolvedConditionalDisplay(DOMElement $element): string
+    {
+        $display = $this->conditionalDeclaration($element, 'display');
+        if ( '' === $display ) {
+            $display = (string) ($this->cssDeclarations($this->specificityResolvedPresentationStyle($element))['display'] ?? '');
+        }
+
+        $display = trim(preg_replace('/\s*!important\s*$/i', '', $display) ?? $display);
+        return $this->expandCssVariableReferences($display, $this->conditionalCascadedCustomProperties($element));
+    }
+
     /**
      * Value a rule states for this element that the matcher cannot evaluate.
      *
@@ -2443,8 +2458,13 @@ function (string $prelude, string $body, array $conditions) use (&$analysis, &$i
                             'mediaTextSpecificity' => $this->mediaTextSelectorSpecificity($selector),
                         );
                     }
-                    if (! $this->selectorCarriesPseudoState($selector) && array() !== $conditions && array() !== $declarations) {
-                        $analysis['conditional'][] = array('selector' => $selector, 'declarations' => $declarations, 'conditions' => $conditions);
+                    if (! $this->selectorCarriesPseudoState($selector) && array() !== $conditions && (array() !== $declarations || array() !== $cascadedValueDeclarations)) {
+                        $analysis['conditional'][] = array(
+                            'selector' => $selector,
+                            'declarations' => $declarations,
+                            'cascadedDeclarations' => $cascadedValueDeclarations,
+                            'conditions' => $conditions,
+                        );
                     }
                     if ($supportedRestingSelector) {
                         foreach ($imageEntries as $entry) {
@@ -3146,6 +3166,30 @@ public function cascadedCustomProperties(DOMElement $element): array
         return $customProperties;
     }
 
+    /** @return array<string, string> */
+    private function conditionalCascadedCustomProperties(DOMElement $element): array
+    {
+        $customProperties = $this->cascadedCustomProperties($element);
+        $ancestors = array();
+        for ( $current = $element; $current instanceof DOMElement; $current = $current->parentNode instanceof DOMElement ? $current->parentNode : null ) {
+            $ancestors[] = $current;
+        }
+        foreach ( array_reverse($ancestors) as $ancestor ) {
+            foreach ( $this->styleRuleCandidates($ancestor, 'conditional') as $rule ) {
+                if ( ! $this->matchesCssSelector($ancestor, (string) ($rule['selector'] ?? '')) ) {
+                    continue;
+                }
+                foreach ( $rule['cascadedDeclarations'] ?? array() as $name => $value ) {
+                    if ( str_starts_with((string) $name, '--') ) {
+                        $customProperties[(string) $name] = (string) $value;
+                    }
+                }
+            }
+        }
+
+        return $customProperties;
+    }
+
     /**
      * The element's own resolved value for one paint property — from matched
      * CSS or inline style directly on `$element`, with any `var()` reference
diff --git a/php-transformer/tests/unit/navigation-layout-default.php b/php-transformer/tests/unit/navigation-layout-default.php
index 138fd69f9..906693c28 100644
--- a/php-transformer/tests/unit/navigation-layout-default.php
+++ b/php-transformer/tests/unit/navigation-layout-default.php
@@ -28,6 +28,18 @@
 $assert('default' === ($attrs['layout']['type'] ?? null), 'a resolver-proven block navigation records the core flow layout');
 $assert(str_contains($serialized, '"layout":{"type":"default"}'), 'the flow layout survives canonical navigation serialization', $serialized);
 
+$conditional = ( new HtmlTransformer() )->transform(
+    '<style>:root{--navbar-display:flex}.captured-header{--navbar-display:flex}'
+    . '@media(min-width:769px){.captured-header{--navbar-display:block}}'
+    . '.navbar{display:var(--navbar-display,block)}</style>'
+    . '<header class="captured-header"><nav class="navbar"><ul><li><a href="/">Home</a></li></ul></nav></header>'
+)->toArray();
+$conditionalNavigation = $conditional['blocks'][0]['innerBlocks'][0] ?? array();
+$assert(
+    'default' === ($conditionalNavigation['attrs']['layout']['type'] ?? null),
+    'a captured desktop custom-property override resolves on its navigation ancestor rather than from the global flex fallback'
+);
+
 $vertical = ( new HtmlTransformer() )->transform('<nav style="display:flex;flex-direction:column"><ul><li><a href="/">Home</a></li></ul></nav>')->toArray();
 $assert(
     array( 'type' => 'flex', 'orientation' => 'vertical' ) === ($vertical['blocks'][0]['attrs']['layout'] ?? null),
diff --git a/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs b/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs
index 461127ed7..d56631657 100644
--- a/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs
+++ b/php-transformer/tools/visual-parity/tests/navigation-layout-default.mjs
@@ -3,15 +3,21 @@ import { execFileSync } from 'node:child_process';
 import { chromium } from 'playwright';
 
 const root = new URL('../../..', import.meta.url).pathname;
-const source = '<style>.flow-menu{display:block}</style><nav class="flow-menu"><ul><li><a href="/">Home</a></li></ul></nav>';
+const source = '<style>:root{--navbar-display:flex}.captured-header{--navbar-display:flex}@media(min-width:769px){.captured-header{--navbar-display:block}}.navbar{display:var(--navbar-display,block)}</style><header class="captured-header"><nav class="navbar"><ul><li><a href="/">Home</a></li></ul></nav></header>';
 const result = JSON.parse(execFileSync('php', ['-r', 'require $argv[1] . "/vendor/autoload.php"; echo json_encode((new Automattic\\BlocksEngine\\PhpTransformer\\HtmlToBlocks\\HtmlTransformer())->transform(base64_decode($argv[2]))->toArray());', root, Buffer.from(source).toString('base64')], { encoding: 'utf8' }));
+const navigation = result.blocks.flatMap((block) => block.innerBlocks ?? []).find((block) => block.blockName === 'core/navigation');
 
-assert.equal(result.blocks[0]?.attrs?.layout?.type, 'default', 'serialized navigation carries explicit core flow layout');
+assert.equal(navigation?.attrs?.layout?.type, 'default', 'serialized navigation carries explicit core flow layout');
 assert.match(result.serialized_blocks, /"layout":\{"type":"default"\}/, 'canonical block markup retains the flow layout attribute');
 
 const browser = await chromium.launch({ headless: true });
 try {
-  const page = await browser.newPage();
+  const sourcePage = await browser.newPage({ viewport: { width: 1440, height: 300 } });
+  await sourcePage.setContent(source);
+  assert.equal(await sourcePage.locator('nav').evaluate((element) => getComputedStyle(element).display), 'block', 'the captured desktop custom-property cascade resolves navigation to block');
+  await sourcePage.close();
+
+  const page = await browser.newPage({ viewport: { width: 1440, height: 300 } });
   // This is the core/navigation server-rendered shape for layout.type default.
   await page.setContent('<style>.is-layout-flow{display:block}.is-layout-flex{display:flex}</style><nav class="wp-block-navigation is-layout-flow wp-block-navigation-is-layout-flow"><ul class="wp-block-navigation__container wp-block-navigation"><li class="wp-block-navigation-item wp-block-navigation-link"><a class="wp-block-navigation-item__content" href="/"><span class="wp-block-navigation-item__label">Home</span></a></li></ul></nav>');
   const rendered = await page.locator('nav').evaluate((element) => ({ className: element.className, display: getComputedStyle(element).display }));

From c29178ea5188dff88aadeed5fcb96e24a5a91086 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Fri, 11 Sep 2026 12:19:59 -0400
Subject: [PATCH 4/5] fix(navigation): keep authored menu box to one
 application

---
 php-transformer/src/HtmlToBlocks/HtmlCompilation.php | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
index 08a5e886d..a8a8a4d7b 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
@@ -2076,6 +2076,14 @@ private function materializeAuthorStylesheet(string $html, string $staticCss, bo
             // became 155x82 and menu 1005 at x=265. `max-width:100%` keeps the
             // block shrinkable, so a narrow viewport still hands over to core's
             // responsive overlay rather than overflowing the page.
+            // core's navigation renderer repeats the block's class list on the
+            // inner container, so a single authored box is painted twice: once
+            // on the <nav> and again on its <ul>. Measured on busybearscleaning
+            // at 1440px, an authored 19.3517px padding produced a 105.78px menu
+            // against the source's 68.09px. The source declared that box on one
+            // element, so the repeated container copy is neutralized and the
+            // authored geometry keeps its single application.
+            $afterAuthorCssParts[] = '.wp-block-navigation.blocks-engine-list-navigation>.wp-block-navigation__container{padding:0;margin:0;border-width:0}';
             $afterAuthorCssParts[] = 'nav.wp-block-group>.wp-block-navigation.blocks-engine-list-navigation{width:max-content;max-width:100%}';
             foreach ( $this->navigationStyleProjector->listNavigationInlineMarginRules($serializedBlocks) as $inlineMarginRule ) {
                 $afterAuthorCssParts[] = $inlineMarginRule;

From f6d1f387418ae9f7471bf8d1303ae023aa6047ef Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Fri, 11 Sep 2026 12:26:27 -0400
Subject: [PATCH 5/5] fix(navigation): neutralize repeated container box

---
 php-transformer/src/HtmlToBlocks/HtmlCompilation.php | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
index a8a8a4d7b..452276c9e 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
@@ -2083,7 +2083,11 @@ private function materializeAuthorStylesheet(string $html, string $staticCss, bo
             // against the source's 68.09px. The source declared that box on one
             // element, so the repeated container copy is neutralized and the
             // authored geometry keeps its single application.
-            $afterAuthorCssParts[] = '.wp-block-navigation.blocks-engine-list-navigation>.wp-block-navigation__container{padding:0;margin:0;border-width:0}';
+            // An authored selector can outrank any generated one, so the reset
+            // is declared important. The <nav> keeps the authored class list and
+            // therefore still paints the source box exactly once, whether the
+            // source declared it on the menu element or on its list.
+            $afterAuthorCssParts[] = '.wp-block-navigation.blocks-engine-list-navigation>.wp-block-navigation__container{padding:0!important;margin:0!important;border-width:0!important}';
             $afterAuthorCssParts[] = 'nav.wp-block-group>.wp-block-navigation.blocks-engine-list-navigation{width:max-content;max-width:100%}';
             foreach ( $this->navigationStyleProjector->listNavigationInlineMarginRules($serializedBlocks) as $inlineMarginRule ) {
                 $afterAuthorCssParts[] = $inlineMarginRule;