From c5c1c3b4e694570066ec14589d01453b19b1f104 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 00:02:40 -0400
Subject: [PATCH 1/8] fix(php-transformer): recognize paragraph-labelled menus
 inside custom-element hosts

A presentation-only custom element wrapping a nav was captured as companion
HTML before NavigationPattern could see the landmark, so paragraph-wrapped
menu labels never became editable navigation links.
---
 php-transformer/composer.json                 |  1 +
 .../src/HtmlToBlocks/HtmlCompilation.php      | 34 ++++++++++
 .../Patterns/NavigationPattern.php            | 31 +++++++++
 .../unit/paragraph-label-desktop-menu.php     | 68 +++++++++++++++++++
 4 files changed, 134 insertions(+)
 create mode 100644 php-transformer/tests/unit/paragraph-label-desktop-menu.php

diff --git a/php-transformer/composer.json b/php-transformer/composer.json
index 40693eb1d..5a2708af0 100644
--- a/php-transformer/composer.json
+++ b/php-transformer/composer.json
@@ -229,6 +229,7 @@
       "php tests/unit/navigation-overlay-duplicate-collapse.php",
       "php tests/unit/layout-boundary-excludes-shell.php",
       "php tests/unit/navigation-nested-authored-anchor.php",
+       "php tests/unit/paragraph-label-desktop-menu.php",
       "php tests/unit/button-signal-classifier.php",
       "php tests/unit/pill-button-anchor.php",
       "php tests/unit/button-style-resolver.php",
diff --git a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
index aa5b04fa0..667b5fa98 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
@@ -3189,6 +3189,14 @@ private function convertElement(DOMElement $element, array &$fallbacks, bool $ca
             return $carousel;
         }
 
+        // A custom-element menu host is not a component. Recognize its landmark
+        // before generated-component capture freezes paragraph-wrapped labels
+        // into a companion content attribute.
+        $navigationHost = $this->recognizedNavigationHostBlock($element, $fallbacks);
+        if ( null !== $navigationHost ) {
+            return $navigationHost;
+        }
+
         if ( $this->isGeneratedComponentCandidate($element) ) {
             $generated = $this->fallbackEmitter()->maybeGenerateCustomBlock($element, $this->generatedBlocks(), true, true);
             if ( null !== $generated ) {
@@ -3318,6 +3326,32 @@ private function linkBearingElementBlock(DOMElement $element): ?array
         );
     }
 
+    /**
+     * Lower a custom-element host of a navigation landmark to that landmark's
+     * native navigation, keeping host identity CSS can still address.
+     *
+     * @param array<int, array<string, mixed>> $fallbacks
+     * @return array<string, mixed>|null
+     */
+    private function recognizedNavigationHostBlock(DOMElement $element, array &$fallbacks): ?array
+    {
+        $landmark = ( new NavigationPattern() )->hostedNavigationLandmark($element);
+        if ( ! $landmark instanceof DOMElement ) {
+            return null;
+        }
+
+        $navigation = $this->recognizePatterns($landmark, $fallbacks, array( AccordionPattern::class, SocialLinksPattern::class, NavigationPattern::class ));
+        if ( null === $navigation ) {
+            return null;
+        }
+
+        if ( '' === trim($this->attr($element, 'id') . $this->attr($element, 'class') . $this->attr($element, 'style')) ) {
+            return $navigation;
+        }
+
+        return $this->layoutShellBlockForElements(array( $element ), array( $navigation ), $element);
+    }
+
     /**
      * Preserve a static source wrapper chain around editable inner blocks.
      *
diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 9e1ec63e8..5fe314f90 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -52,6 +52,37 @@ public function claimsBeforeAuthorOwnedLayout(DOMElement $element): bool
         return $this->hasHeaderLinkCluster($element) || $this->hasRepeatedLinkItems($element);
     }
 
+    /**
+     * A custom-element host whose only element child is a navigation landmark.
+     *
+     * Builders wrap an ordinary `<nav>` in a presentation-only custom element.
+     * That host is not a menu itself; capturing it as a companion freezes the
+     * landmark, including paragraph-wrapped item labels, as escaped HTML.
+     * Callers offer the returned landmark to {@see recognize()} instead.
+     */
+    public function hostedNavigationLandmark(DOMElement $element): ?DOMElement
+    {
+        if ( ! str_contains(strtolower($element->tagName), '-') ) {
+            return null;
+        }
+
+        $landmark = null;
+        foreach ( $element->childNodes as $child ) {
+            if ( XML_TEXT_NODE === $child->nodeType && '' === trim($child->textContent ?? '') ) {
+                continue;
+            }
+            if ( XML_COMMENT_NODE === $child->nodeType ) {
+                continue;
+            }
+            if ( ! $child instanceof DOMElement || null !== $landmark || 'nav' !== strtolower($child->tagName) ) {
+                return null;
+            }
+            $landmark = $child;
+        }
+
+        return $landmark;
+    }
+
     public function recognize(DOMElement $element, PatternContext $context): ?PatternRecognitionResult
     {
         $presentationAttributes = $context->presentationAttributes(...);
diff --git a/php-transformer/tests/unit/paragraph-label-desktop-menu.php b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
new file mode 100644
index 000000000..257bea968
--- /dev/null
+++ b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
@@ -0,0 +1,68 @@
+<?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);
+};
+
+$items = '';
+foreach ( array(
+    array( 'Home', '/' ),
+    array( 'Journal', '/journal' ),
+    array( 'Shop', '/shop' ),
+    array( 'Events', '/events' ),
+    array( 'Contact', '/contact' ),
+    array( 'About', '/about' ),
+) as $item ) {
+    $items .= '<li class="item"><a href="' . $item[1] . '"><div class="pad"><div class="label-wrap"><p class="label">' . $item[0] . '</p></div></div></a></li>';
+}
+$menu = '<site-menu id="desktop-menu" class="desktop-menu" style="visibility:inherit">'
+    . '<nav aria-label="Site"><ul class="items">' . $items . '</ul><div class="more"><ul class="submenu"></ul></div></nav>'
+    . '</site-menu>';
+$layout = '<style>.menu-bar{display:flex;flex-direction:row;align-items:center}.items{display:flex;flex-direction:row;gap:12px;margin:0;padding:0}.label{margin:0;line-height:30px}</style>'
+    . '<header class="site-header"><div class="menu-bar">' . $menu . '</div></header>';
+$deep = $layout;
+for ( $depth = 0; $depth < 16; ++$depth ) {
+    $deep = '<div class="shell">' . $deep . '</div>';
+}
+
+$transform = static function (string $html): string {
+    $result = ( new HtmlTransformer() )->transform($html)->toArray();
+
+    return (string) ($result['serialized_blocks'] ?? '');
+};
+
+$shallow = $transform($layout);
+$deepMarkup = $transform($deep);
+
+foreach ( array( 'shallow layout wrapper' => $shallow, 'deep layout wrapper' => $deepMarkup ) as $name => $markup ) {
+    $assert(1 <= substr_count($markup, '<!-- wp:navigation '), $name . ' materializes the paragraph-labelled menu as core/navigation', $markup);
+    $assert(6 === substr_count($markup, 'wp:navigation-link'), $name . ' emits one navigation-link per menu item', $markup);
+    $assert(str_contains($markup, '"label":"Home"') && str_contains($markup, '"label":"Journal"') && str_contains($markup, '"label":"About"'), $name . ' keeps paragraph-wrapped labels as navigation-link labels', $markup);
+    $assert(str_contains($markup, 'id="desktop-menu"'), $name . ' keeps the menu host identity CSS can address', $markup);
+    $assert(! str_contains($markup, '<p class="label">') && ! str_contains($markup, '<p class=\\"label\\">'), $name . ' does not leave menu labels as companion-attribute HTML', $markup);
+}
+
+$component = $transform(
+    '<my-pricing><div class="tier"><h3>Basic</h3><p>$9</p></div><div class="tier"><h3>Pro</h3><p>$19</p></div><div class="tier"><h3>Max</h3><p>$49</p></div></my-pricing>'
+);
+$assert(! str_contains($component, '<!-- wp:navigation '), 'a custom element that is not a navigation host stays out of core/navigation', $component);
+
+if ( 0 < $failures ) {
+    fwrite(STDERR, "Paragraph-label desktop menu: {$failures} failed, {$passes} passed\n");
+    exit(1);
+}
+
+echo "Paragraph-label desktop menu passed: {$passes} assertions\n";

From 2d8eb603e21fbdae84a1640f158f79f510b93327 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 00:26:24 -0400
Subject: [PATCH 2/8] fix(php-transformer): keep hidden menu support text out
 of host recognition

A custom-element nav that also carries a display:none accessibility hint
must stay on the path that preserves that hint, instead of being replaced
by a navigation block that drops it.
---
 .../Patterns/NavigationPattern.php            | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 5fe314f90..007cea7b0 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -80,9 +80,46 @@ public function hostedNavigationLandmark(DOMElement $element): ?DOMElement
             $landmark = $child;
         }
 
+        // A hidden support hint is not a menu item. Recognition would drop it;
+        // leave that host on the path that keeps the hint hidden but present.
+        if ( $landmark instanceof DOMElement && $this->landmarkHasHiddenSupportText($landmark) ) {
+            return null;
+        }
+
         return $landmark;
     }
 
+    private function landmarkHasHiddenSupportText(DOMElement $landmark): bool
+    {
+        foreach ( $landmark->getElementsByTagName('*') as $descendant ) {
+            if ( ! $descendant instanceof DOMElement || '' === trim($descendant->textContent ?? '') ) {
+                continue;
+            }
+            $style = strtolower(preg_replace('/\s+/', '', $this->attr($descendant, 'style')) ?? '');
+            $hidden = $descendant->hasAttribute('hidden')
+                || str_contains($style, 'display:none')
+                || str_contains($style, 'visibility:hidden');
+            if ( ! $hidden || $this->hasAnchorAncestor($descendant, $landmark) ) {
+                continue;
+            }
+
+            return true;
+        }
+
+        return false;
+    }
+
+    private function hasAnchorAncestor(DOMElement $element, DOMElement $boundary): bool
+    {
+        for ( $node = $element; $node instanceof DOMElement && ! $node->isSameNode($boundary); $node = $node->parentNode instanceof DOMElement ? $node->parentNode : null ) {
+            if ( 'a' === strtolower($node->tagName) ) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     public function recognize(DOMElement $element, PatternContext $context): ?PatternRecognitionResult
     {
         $presentationAttributes = $context->presentationAttributes(...);

From 7b0587d3fc6b439cdde904dde974c385ec84746c Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 13:48:32 -0400
Subject: [PATCH 3/8] fix(php-transformer): carry horizontal menu packing onto
 navigation

A block list's text-align and a row flex list's justify-content were
dropped when the list became a flex core/navigation, so items started
at the container edge instead of the source position.
---
 .../Patterns/NavigationPattern.php            | 73 +++++++++++++++++++
 .../unit/paragraph-label-desktop-menu.php     |  3 +-
 2 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 007cea7b0..338154a09 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -208,6 +208,11 @@ public function recognize(DOMElement $element, PatternContext $context): ?Patter
         if ( $label instanceof DOMElement ) {
             $navigationAttrs['layout'] = array( 'type' => 'flex', 'orientation' => 'vertical' );
         }
+        $navigationAttrs = $this->withResolvedListPackingJustification(
+            $navigationAttrs,
+            $listSource instanceof DOMElement ? $listSource : $element,
+            $navigationContext
+        );
 
         // Declare responsive-overlay intent explicitly so the saved block carries
         // its interactive behavior in the content itself rather than relying on
@@ -1040,6 +1045,74 @@ private function verticalNavigationJustification(string $style): string
         return 'left';
     }
 
+    /**
+     * Carry a source list's item packing onto core/navigation.
+     *
+     * A block list of inline items packs with `text-align`; a row flex list
+     * packs with `justify-content`. The generated container is a flex row
+     * whose default is flex-start, so that declaration has to be restated as
+     * `layout.justifyContent` or the items start at the container's leading
+     * edge. A column flex list keeps the cross-axis value the vertical
+     * orientation path already recorded.
+     *
+     * @param array<string, mixed> $attrs
+     * @return array<string, mixed>
+     */
+    private function withResolvedListPackingJustification(array $attrs, DOMElement $list, ?NavigationPatternContext $navigationContext): array
+    {
+        if ( ! $navigationContext instanceof NavigationPatternContext ) {
+            return $attrs;
+        }
+
+        $justification = $this->listPackingJustification($navigationContext->resolvedStyle($list));
+        if ( '' === $justification ) {
+            return $attrs;
+        }
+
+        $layout = is_array($attrs['layout'] ?? null) ? $attrs['layout'] : array();
+        $layout['justifyContent'] = $justification;
+        if ( ! isset($layout['type']) ) {
+            $layout['type'] = 'flex';
+        }
+        $attrs['layout'] = $layout;
+
+        return $attrs;
+    }
+
+    private function listPackingJustification(string $style): string
+    {
+        if ( 1 === preg_match('/(?:^|;)\s*display\s*:\s*(?:inline-)?flex\b/i', $style)
+            && 1 === preg_match('/(?:^|;)\s*flex-direction\s*:\s*column(?:-reverse)?\b/i', $style) ) {
+            return '';
+        }
+
+        $declared = '';
+        if ( 1 === preg_match('/(?:^|;)\s*justify-content\s*:\s*([^;]+)/i', $style, $match) ) {
+            $declared = $this->cssDeclarationValue($match[1]);
+        } elseif ( 1 === preg_match('/(?:^|;)\s*text-align\s*:\s*([^;]+)/i', $style, $match) ) {
+            $declared = $this->cssDeclarationValue($match[1]);
+        }
+        if ( '' === $declared ) {
+            return '';
+        }
+        if ( str_contains($declared, 'space-between') ) {
+            return 'space-between';
+        }
+        if ( str_contains($declared, 'flex-end') || 1 === preg_match('/(?:^|[\s,])(?:right|end)(?:[\s,]|$)/', $declared) ) {
+            return 'right';
+        }
+        if ( str_contains($declared, 'center') ) {
+            return 'center';
+        }
+
+        return '';
+    }
+
+    private function cssDeclarationValue(string $value): string
+    {
+        return strtolower(trim((string) preg_replace('/\s*!important\s*$/i', '', trim($value))));
+    }
+
     private function resolvedStyleDeclaresFamily(string $style, string $family): bool
     {
         $property = match ( $family ) {
diff --git a/php-transformer/tests/unit/paragraph-label-desktop-menu.php b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
index 257bea968..4f5eb2de3 100644
--- a/php-transformer/tests/unit/paragraph-label-desktop-menu.php
+++ b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
@@ -29,7 +29,7 @@
     $items .= '<li class="item"><a href="' . $item[1] . '"><div class="pad"><div class="label-wrap"><p class="label">' . $item[0] . '</p></div></div></a></li>';
 }
 $menu = '<site-menu id="desktop-menu" class="desktop-menu" style="visibility:inherit">'
-    . '<nav aria-label="Site"><ul class="items">' . $items . '</ul><div class="more"><ul class="submenu"></ul></div></nav>'
+    . '<nav aria-label="Site"><ul class="items" style="text-align:right">' . $items . '</ul><div class="more"><ul class="submenu"></ul></div></nav>'
     . '</site-menu>';
 $layout = '<style>.menu-bar{display:flex;flex-direction:row;align-items:center}.items{display:flex;flex-direction:row;gap:12px;margin:0;padding:0}.label{margin:0;line-height:30px}</style>'
     . '<header class="site-header"><div class="menu-bar">' . $menu . '</div></header>';
@@ -52,6 +52,7 @@
     $assert(6 === substr_count($markup, 'wp:navigation-link'), $name . ' emits one navigation-link per menu item', $markup);
     $assert(str_contains($markup, '"label":"Home"') && str_contains($markup, '"label":"Journal"') && str_contains($markup, '"label":"About"'), $name . ' keeps paragraph-wrapped labels as navigation-link labels', $markup);
     $assert(str_contains($markup, 'id="desktop-menu"'), $name . ' keeps the menu host identity CSS can address', $markup);
+    $assert(str_contains($markup, '"justifyContent":"right"'), $name . ' keeps the list text-align packing as navigation justification', $markup);
     $assert(! str_contains($markup, '<p class="label">') && ! str_contains($markup, '<p class=\\"label\\">'), $name . ' does not leave menu labels as companion-attribute HTML', $markup);
 }
 

From 70ad30b5b3b08a93a1b81cbb832f144eac4cba92 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 13:58:16 -0400
Subject: [PATCH 4/8] fix(php-transformer): project horizontal menu packing
 onto the container

layout.justifyContent packs a wrapping column on the cross axis, so a
right-aligned list still started at the container edge. Restate the
source packing as a row on the generated list.
---
 .../Patterns/NavigationPattern.php            | 25 ++++++++++++++++---
 .../unit/paragraph-label-desktop-menu.php     | 22 ++++++++++------
 2 files changed, 37 insertions(+), 10 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 338154a09..96ef75c20 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -1052,8 +1052,9 @@ private function verticalNavigationJustification(string $style): string
      * packs with `justify-content`. The generated container is a flex row
      * whose default is flex-start, so that declaration has to be restated as
      * `layout.justifyContent` or the items start at the container's leading
-     * edge. A column flex list keeps the cross-axis value the vertical
-     * orientation path already recorded.
+     * edge. The generated list also inherits an ancestor column and wraps, so
+     * the same packing is projected onto the container. A column flex list
+     * keeps the cross-axis value the vertical orientation path already recorded.
      *
      * @param array<string, mixed> $attrs
      * @return array<string, mixed>
@@ -1064,7 +1065,8 @@ private function withResolvedListPackingJustification(array $attrs, DOMElement $
             return $attrs;
         }
 
-        $justification = $this->listPackingJustification($navigationContext->resolvedStyle($list));
+        $style = $navigationContext->resolvedStyle($list);
+        $justification = $this->listPackingJustification($style);
         if ( '' === $justification ) {
             return $attrs;
         }
@@ -1075,6 +1077,23 @@ private function withResolvedListPackingJustification(array $attrs, DOMElement $
             $layout['type'] = 'flex';
         }
         $attrs['layout'] = $layout;
+        $justify = match ( $justification ) {
+            'right' => 'flex-end',
+            'center' => 'center',
+            'space-between' => 'space-between',
+            default => '',
+        };
+        if ( '' !== $justify ) {
+            $declarations = 'flex-direction:row!important;justify-content:' . $justify . '!important';
+            if ( 1 === preg_match('/(?:^|;)\s*white-space\s*:\s*nowrap\b/i', $style) ) {
+                $declarations .= ';flex-wrap:nowrap!important';
+            }
+            $navigationContext->projectSourceToNativeTarget(
+                $list,
+                '.wp-block-navigation.blocks-engine-list-navigation>.wp-block-navigation__container',
+                $declarations
+            );
+        }
 
         return $attrs;
     }
diff --git a/php-transformer/tests/unit/paragraph-label-desktop-menu.php b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
index 4f5eb2de3..c6af6a10f 100644
--- a/php-transformer/tests/unit/paragraph-label-desktop-menu.php
+++ b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
@@ -38,14 +38,20 @@
     $deep = '<div class="shell">' . $deep . '</div>';
 }
 
-$transform = static function (string $html): string {
-    $result = ( new HtmlTransformer() )->transform($html)->toArray();
-
+$transform = static function (string $html): array {
+    return ( new HtmlTransformer() )->transform($html)->toArray();
+};
+$markupOf = static function (array $result): string {
     return (string) ($result['serialized_blocks'] ?? '');
 };
+$cssOf = static function (array $result): string {
+    return implode("\n", array_map(static fn ($asset): string => (string) ($asset['content'] ?? ''), $result['assets'] ?? array()));
+};
 
-$shallow = $transform($layout);
-$deepMarkup = $transform($deep);
+$shallowResult = $transform($layout);
+$deepResult = $transform($deep);
+$shallow = $markupOf($shallowResult);
+$deepMarkup = $markupOf($deepResult);
 
 foreach ( array( 'shallow layout wrapper' => $shallow, 'deep layout wrapper' => $deepMarkup ) as $name => $markup ) {
     $assert(1 <= substr_count($markup, '<!-- wp:navigation '), $name . ' materializes the paragraph-labelled menu as core/navigation', $markup);
@@ -53,12 +59,14 @@
     $assert(str_contains($markup, '"label":"Home"') && str_contains($markup, '"label":"Journal"') && str_contains($markup, '"label":"About"'), $name . ' keeps paragraph-wrapped labels as navigation-link labels', $markup);
     $assert(str_contains($markup, 'id="desktop-menu"'), $name . ' keeps the menu host identity CSS can address', $markup);
     $assert(str_contains($markup, '"justifyContent":"right"'), $name . ' keeps the list text-align packing as navigation justification', $markup);
+    $css = 'shallow layout wrapper' === $name ? $cssOf($shallowResult) : $cssOf($deepResult);
+    $assert(str_contains($css, 'flex-direction:row!important;justify-content:flex-end!important'), $name . ' projects the list packing onto the navigation container', $css);
     $assert(! str_contains($markup, '<p class="label">') && ! str_contains($markup, '<p class=\\"label\\">'), $name . ' does not leave menu labels as companion-attribute HTML', $markup);
 }
 
-$component = $transform(
+$component = $markupOf($transform(
     '<my-pricing><div class="tier"><h3>Basic</h3><p>$9</p></div><div class="tier"><h3>Pro</h3><p>$19</p></div><div class="tier"><h3>Max</h3><p>$49</p></div></my-pricing>'
-);
+));
 $assert(! str_contains($component, '<!-- wp:navigation '), 'a custom element that is not a navigation host stays out of core/navigation', $component);
 
 if ( 0 < $failures ) {

From 9e35ea27ee3ae74dc283065b2b0fb45fba43e9df Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 14:09:29 -0400
Subject: [PATCH 5/8] fix(php-transformer): scope menu packing to the source
 list

A global row rule also right-aligned other menus. Hang the packing
declarations off the source list's own classes.
---
 .../Patterns/NavigationPattern.php            | 24 ++++++++++++-------
 .../unit/paragraph-label-desktop-menu.php     |  2 +-
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 96ef75c20..39bdd7dbf 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -3,6 +3,7 @@
 
 namespace Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns;
 
+use Automattic\BlocksEngine\PhpTransformer\Css\CssIdent;
 use Automattic\BlocksEngine\PhpTransformer\Css\CssValueSplitter;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Classification\MenuVocabulary;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Style\StyleAttributeMapper;
@@ -1084,15 +1085,22 @@ private function withResolvedListPackingJustification(array $attrs, DOMElement $
             default => '',
         };
         if ( '' !== $justify ) {
-            $declarations = 'flex-direction:row!important;justify-content:' . $justify . '!important';
-            if ( 1 === preg_match('/(?:^|;)\s*white-space\s*:\s*nowrap\b/i', $style) ) {
-                $declarations .= ';flex-wrap:nowrap!important';
+            $scope = CssIdent::compoundClassSelector($this->authorClassNames(SourceDom::attr($list, 'class')));
+            if ( '' === $scope ) {
+                $id = trim(SourceDom::attr($list, 'id'));
+                $scope = 1 === preg_match('/^[A-Za-z][A-Za-z0-9_.:-]*$/D', $id) ? '#' . CssIdent::escape($id) : '';
+            }
+            if ( '' !== $scope ) {
+                $declarations = 'flex-direction:row!important;justify-content:' . $justify . '!important';
+                if ( 1 === preg_match('/(?:^|;)\s*white-space\s*:\s*nowrap\b/i', $style) ) {
+                    $declarations .= ';flex-wrap:nowrap!important';
+                }
+                $navigationContext->projectSourceToNativeTarget(
+                    $list,
+                    '.wp-block-navigation.blocks-engine-list-navigation' . $scope . '>.wp-block-navigation__container',
+                    $declarations
+                );
             }
-            $navigationContext->projectSourceToNativeTarget(
-                $list,
-                '.wp-block-navigation.blocks-engine-list-navigation>.wp-block-navigation__container',
-                $declarations
-            );
         }
 
         return $attrs;
diff --git a/php-transformer/tests/unit/paragraph-label-desktop-menu.php b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
index c6af6a10f..cb68e5a3d 100644
--- a/php-transformer/tests/unit/paragraph-label-desktop-menu.php
+++ b/php-transformer/tests/unit/paragraph-label-desktop-menu.php
@@ -60,7 +60,7 @@
     $assert(str_contains($markup, 'id="desktop-menu"'), $name . ' keeps the menu host identity CSS can address', $markup);
     $assert(str_contains($markup, '"justifyContent":"right"'), $name . ' keeps the list text-align packing as navigation justification', $markup);
     $css = 'shallow layout wrapper' === $name ? $cssOf($shallowResult) : $cssOf($deepResult);
-    $assert(str_contains($css, 'flex-direction:row!important;justify-content:flex-end!important'), $name . ' projects the list packing onto the navigation container', $css);
+    $assert(str_contains($css, '.wp-block-navigation.blocks-engine-list-navigation.items>.wp-block-navigation__container{flex-direction:row!important;justify-content:flex-end!important}'), $name . ' projects the list packing onto that navigation container only', $css);
     $assert(! str_contains($markup, '<p class="label">') && ! str_contains($markup, '<p class=\\"label\\">'), $name . ' does not leave menu labels as companion-attribute HTML', $markup);
 }
 

From bf5cbf91cfc8cbc848d3759b613995eb6b859f24 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 13:59:40 -0400
Subject: [PATCH 6/8] fix(site-plan): share identical responsive variant menus

When desktop and mobile menus have the same ordered items, both core/navigation blocks reference one wp_navigation entity so a single rename updates every viewport.
---
 php-transformer/composer.json                 |   3 +-
 .../WordPressSitePlan/WordPressSitePlan.php   | 272 ++++++++++++++++++
 .../tests/unit/shared-variant-navigation.php  | 110 +++++++
 3 files changed, 384 insertions(+), 1 deletion(-)
 create mode 100644 php-transformer/tests/unit/shared-variant-navigation.php

diff --git a/php-transformer/composer.json b/php-transformer/composer.json
index 5a2708af0..f6aa1c4c5 100644
--- a/php-transformer/composer.json
+++ b/php-transformer/composer.json
@@ -229,7 +229,8 @@
       "php tests/unit/navigation-overlay-duplicate-collapse.php",
       "php tests/unit/layout-boundary-excludes-shell.php",
       "php tests/unit/navigation-nested-authored-anchor.php",
-       "php tests/unit/paragraph-label-desktop-menu.php",
+        "php tests/unit/paragraph-label-desktop-menu.php",
+        "php tests/unit/shared-variant-navigation.php",
       "php tests/unit/button-signal-classifier.php",
       "php tests/unit/pill-button-anchor.php",
       "php tests/unit/button-style-resolver.php",
diff --git a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
index 71b08a8b0..a6388cbb5 100644
--- a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
+++ b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
@@ -213,6 +213,7 @@ public function fromCompilerInput(array $data, WordPressSitePlanInput $input): a
         foreach ($pages as &$page) unset($page['_projected_source_block_markup']); unset($page);
         self::assertEntityBindingsRemainPageOwned($runtimeDeclarations, $pages, $assets);
         $templates = $this->templates($pages, $parts, $surfaces, $tokens, $references, $routeMap);
+        self::shareVariantNavigations($pages, $parts, $templates);
         $operations = $this->operations($pages);
         $scriptLoading = $this->scriptLoading($pages, $parts, $assets, $tokens, $operations, $runtimeDeclarations);
         // Asset payloads are the last canonicalization pass, so the placeholder
@@ -1901,8 +1902,279 @@ private static function bootstrap(array $assets, array $scripts = array(), array
             $lines[] = "    return \$permalink;";
             $lines[] = "}, 10, 2 );";
         }
+        $navigationPosts = self::sharedNavigationPosts($parts, $pages, $templates);
+        if (array() !== $navigationPosts) $lines = array_merge($lines, self::navigationEntityBootstrap($navigationPosts));
         return implode("\n", $lines) . "\n";
     }
+
+    /**
+     * @param array<int,array<string,mixed>> $pages
+     * @param array<int,array<string,mixed>> $parts
+     * @param array<int,array<string,mixed>> $templates
+     */
+    private static function shareVariantNavigations(array &$pages, array &$parts, array &$templates): void
+    {
+        $documents = array();
+        foreach ($parts as $index => $part) $documents[] = array('kind' => 'part', 'index' => $index, 'area' => (string) ($part['area'] ?? ''), 'variant' => is_int($part['placement']['variant'] ?? null) ? $part['placement']['variant'] : null, 'markup' => (string) ($part['canonical_block_markup'] ?? ''));
+        foreach ($pages as $index => $page) $documents[] = array('kind' => 'page', 'index' => $index, 'area' => '', 'variant' => null, 'markup' => (string) ($page['canonical_block_markup'] ?? ''));
+        foreach ($templates as $index => $template) $documents[] = array('kind' => 'template', 'index' => $index, 'area' => '', 'variant' => null, 'markup' => (string) ($template['canonical_block_markup'] ?? ''));
+        $found = array();
+        foreach ($documents as $docIndex => $document) {
+            foreach (self::variantNavigations($document['markup'], $document['area'], $document['variant']) as $navigation) {
+                $navigation['doc'] = $docIndex;
+                $found[] = $navigation;
+            }
+        }
+        $groups = array();
+        foreach ($found as $index => $navigation) {
+            if (null === $navigation['variant'] || null === $navigation['signature']) continue;
+            $groups[$navigation['area'] . "\0" . $navigation['signature']][$navigation['variant']][] = $index;
+        }
+        $assigned = array();
+        $used = array();
+        foreach ($groups as $key => $byVariant) {
+            if (count($byVariant) < 2) continue;
+            $ref = 900000000 + (hexdec(substr(hash('sha256', $key), 0, 6)) % 99999999);
+            while (isset($used[$ref])) $ref = 900000000 + (($ref + 1) % 99999999);
+            $used[$ref] = true;
+            foreach ($byVariant as $indexes) foreach ($indexes as $index) $assigned[$index] = $ref;
+        }
+        if (array() === $assigned) return;
+        $replacements = array();
+        foreach ($assigned as $index => $ref) { $row = $found[$index]; $row['ref'] = $ref; $replacements[$row['doc']][] = $row; }
+        foreach ($replacements as $docIndex => $rows) {
+            usort($rows, static fn(array $left, array $right): int => $right['offset'] <=> $left['offset']);
+            $markup = $documents[$docIndex]['markup'];
+            foreach ($rows as $row) $markup = substr($markup, 0, $row['offset']) . self::withNavigationRef($row['opening'], $row['ref']) . substr($markup, $row['offset'] + strlen($row['opening']));
+            $kind = $documents[$docIndex]['kind'];
+            $index = $documents[$docIndex]['index'];
+            if ('part' === $kind) { $parts[$index]['canonical_block_markup'] = $markup; $parts[$index]['content_hash'] = self::contentHash($markup); }
+            elseif ('page' === $kind) { $pages[$index]['canonical_block_markup'] = $markup; $pages[$index]['content_hash'] = self::contentHash($markup); }
+            else { $templates[$index]['canonical_block_markup'] = $markup; $templates[$index]['content_hash'] = self::contentHash($markup); }
+        }
+    }
+
+    /** @param array<int,array<string,mixed>> $parts @param array<int,array<string,mixed>> $pages @param array<int,array<string,mixed>> $templates @return array<int,array{rank:int,content:string}> */
+    private static function sharedNavigationPosts(array $parts, array $pages, array $templates): array
+    {
+        $documents = array();
+        foreach ($parts as $part) $documents[] = array('markup' => (string) ($part['canonical_block_markup'] ?? ''), 'area' => (string) ($part['area'] ?? ''), 'variant' => is_int($part['placement']['variant'] ?? null) ? $part['placement']['variant'] : null);
+        foreach ($pages as $page) $documents[] = array('markup' => (string) ($page['canonical_block_markup'] ?? ''), 'area' => '', 'variant' => null);
+        foreach ($templates as $template) $documents[] = array('markup' => (string) ($template['canonical_block_markup'] ?? ''), 'area' => '', 'variant' => null);
+        $catalog = array();
+        foreach ($documents as $document) {
+            foreach (self::variantNavigations($document['markup'], $document['area'], $document['variant']) as $navigation) {
+                $ref = $navigation['ref'];
+                if (!is_int($ref) || $ref < 900000000 || '' === $navigation['inner']) continue;
+                if (!isset($catalog[$ref]) || $navigation['rank'] < $catalog[$ref]['rank']) $catalog[$ref] = array('rank' => $navigation['rank'], 'content' => self::navigationEntityContent($navigation['inner']));
+            }
+        }
+        ksort($catalog, SORT_NUMERIC);
+        return $catalog;
+    }
+
+    /** @param array<int,array{rank:int,content:string}> $posts @return array<int,string> */
+    private static function navigationEntityBootstrap(array $posts): array
+    {
+        $menus = array();
+        $index = 0;
+        foreach ($posts as $ref => $post) {
+            ++$index;
+            $menus[$ref] = array('slug' => 'blocks-engine-navigation-' . $ref, 'title' => 1 === count($posts) ? 'Navigation' : 'Navigation ' . $index, 'content' => $post['content']);
+        }
+        $lines = array('$blocks_engine_navigations = ' . var_export($menus, true) . ';');
+        $lines[] = "add_action( 'init', static function () use ( \$blocks_engine_navigations ): void {";
+        $lines[] = "    if ( ! function_exists( 'wp_insert_post' ) ) return;";
+        $lines[] = "    \$refs = array();";
+        $lines[] = "    foreach ( \$blocks_engine_navigations as \$sentinel => \$menu ) {";
+        $lines[] = "        \$found = get_posts( array( 'name' => \$menu['slug'], 'post_type' => 'wp_navigation', 'post_status' => 'publish', 'posts_per_page' => 1, 'suppress_filters' => true ) );";
+        $lines[] = "        if ( \$found ) { \$refs[ (int) \$sentinel ] = (int) \$found[0]->ID; continue; }";
+        $lines[] = "        \$created = wp_insert_post( array( 'post_type' => 'wp_navigation', 'post_status' => 'publish', 'post_title' => \$menu['title'], 'post_name' => \$menu['slug'], 'post_content' => \$menu['content'] ), true );";
+        $lines[] = "        if ( ! is_wp_error( \$created ) && (int) \$created > 0 ) \$refs[ (int) \$sentinel ] = (int) \$created;";
+        $lines[] = "    }";
+        $lines[] = "    \$GLOBALS['blocks_engine_navigation_refs'] = \$refs;";
+        $lines[] = "}, 1 );";
+        $lines[] = "\$blocks_engine_bind_navigation_refs = static function ( string \$content ): string {";
+        $lines[] = "    \$refs = \$GLOBALS['blocks_engine_navigation_refs'] ?? array();";
+        $lines[] = "    if ( ! is_array( \$refs ) || array() === \$refs || ! str_contains( \$content, '\"ref\":' ) ) return \$content;";
+        $lines[] = "    foreach ( \$refs as \$sentinel => \$id ) \$content = str_replace( '\"ref\":' . \$sentinel, '\"ref\":' . \$id, \$content );";
+        $lines[] = "    \$ids = array_fill_keys( array_map( 'intval', array_values( \$refs ) ), true );";
+        $lines[] = '    return preg_replace_callback(\'/<!--\\s*wp:navigation\\s+(\\{.*?\\})\\s*-->.*?<!--\\s*\\/wp:navigation\\s*-->/s\', static function ( array $match ) use ( $ids ): string {';
+        $lines[] = "        \$attrs = json_decode( \$match[1], true );";
+        $lines[] = "        if ( ! is_array( \$attrs ) || ! isset( \$ids[ (int) ( \$attrs['ref'] ?? 0 ) ] ) ) return \$match[0];";
+        $lines[] = "        \$encoded = function_exists( 'wp_json_encode' ) ? wp_json_encode( \$attrs, JSON_UNESCAPED_SLASHES ) : json_encode( \$attrs, JSON_UNESCAPED_SLASHES );";
+        $lines[] = "        return '<!-- wp:navigation ' . \$encoded . ' /-->';";
+        $lines[] = "    }, \$content ) ?? \$content;";
+        $lines[] = "};";
+        $lines[] = "add_filter( 'get_block_file_template', static function ( \$template ) use ( \$blocks_engine_bind_navigation_refs ) { if ( \$template instanceof WP_Block_Template ) \$template->content = \$blocks_engine_bind_navigation_refs( \$template->content ); return \$template; }, 20 );";
+        $lines[] = "add_filter( 'get_block_templates', static function ( array \$templates ) use ( \$blocks_engine_bind_navigation_refs ): array { foreach ( \$templates as \$template ) if ( \$template instanceof WP_Block_Template ) \$template->content = \$blocks_engine_bind_navigation_refs( \$template->content ); return \$templates; }, 20 );";
+        $lines[] = "add_filter( 'render_block_core/template-part', static function ( string \$content ) use ( \$blocks_engine_bind_navigation_refs ): string { return \$blocks_engine_bind_navigation_refs( \$content ); }, 9 );";
+        foreach (array('page', 'post', 'wp_template', 'wp_template_part') as $type) {
+            $lines[] = "add_filter( 'rest_prepare_{$type}', static function ( \$response ) use ( \$blocks_engine_bind_navigation_refs ) { if ( ! \$response instanceof WP_REST_Response ) return \$response; \$data = \$response->get_data(); if ( isset( \$data['content']['raw'] ) && is_string( \$data['content']['raw'] ) ) \$data['content']['raw'] = \$blocks_engine_bind_navigation_refs( \$data['content']['raw'] ); if ( isset( \$data['content']['rendered'] ) && is_string( \$data['content']['rendered'] ) ) \$data['content']['rendered'] = \$blocks_engine_bind_navigation_refs( \$data['content']['rendered'] ); \$response->set_data( \$data ); return \$response; } );";
+        }
+        $lines[] = "add_filter( 'render_block_data', static function ( array \$block ): array { if ( 'core/navigation' !== ( \$block['blockName'] ?? null ) ) return \$block; \$refs = \$GLOBALS['blocks_engine_navigation_refs'] ?? array(); \$ref = \$block['attrs']['ref'] ?? null; if ( is_int( \$ref ) && isset( \$refs[ \$ref ] ) ) \$block['attrs']['ref'] = \$refs[ \$ref ]; return \$block; }, 9 );";
+        return $lines;
+    }
+
+    /** @return array<int,array{offset:int,opening:string,inner:string,signature:?string,variant:?string,area:string,rank:int,ref:?int}> */
+    private static function variantNavigations(string $markup, string $partArea, ?int $partVariant): array
+    {
+        $navigations = array();
+        $stack = array();
+        $offset = 0;
+        $length = strlen($markup);
+        while ($offset < $length && false !== ($start = strpos($markup, '<!--', $offset))) {
+            $comment = self::blockCommentAt($markup, $start);
+            if (null === $comment) { $offset = $start + 4; continue; }
+            $offset = $start + $comment['length'];
+            if ($comment['closing']) { array_pop($stack); continue; }
+            $variant = self::responsiveVariantClassFromAttrs($comment['attrs']);
+            $tag = is_string($comment['attrs']['tagName'] ?? null) ? $comment['attrs']['tagName'] : null;
+            if (!$comment['selfClosing']) $stack[] = array('variant' => $variant, 'tag' => $tag);
+            if ('navigation' !== $comment['name'] || $comment['selfClosing']) continue;
+            $variantIdentity = null;
+            $area = $partArea;
+            foreach ($stack as $frame) {
+                if (null !== $frame['variant']) $variantIdentity = $frame['variant'];
+                if (in_array($frame['tag'], array('header', 'footer'), true)) $area = $frame['tag'];
+            }
+            if (null === $variantIdentity && null !== $partVariant) $variantIdentity = 'inline:' . $area . ':' . $partVariant;
+            $close = self::navigationCloseOffset($markup, $offset);
+            if (null === $close) continue;
+            $inner = trim(substr($markup, $offset, $close - $offset));
+            $navigations[] = array(
+                'offset' => $start,
+                'opening' => $comment['comment'],
+                'inner' => $inner,
+                'signature' => self::navigationItemSignature($inner),
+                'variant' => $variantIdentity,
+                'area' => $area,
+                'rank' => self::navigationVariantRank($variantIdentity, $partVariant),
+                'ref' => is_int($comment['attrs']['ref'] ?? null) ? $comment['attrs']['ref'] : (is_numeric($comment['attrs']['ref'] ?? null) ? (int) $comment['attrs']['ref'] : null),
+            );
+            $offset = $close;
+        }
+        return $navigations;
+    }
+
+    /** @return array{name:string,closing:bool,selfClosing:bool,length:int,comment:string,attrs:array<string,mixed>}|null */
+    private static function blockCommentAt(string $markup, int $offset): ?array
+    {
+        if (!preg_match('/^<!--\s*(\/?)wp:([a-z0-9\/-]+)/', substr($markup, $offset), $match)) return null;
+        $end = strpos($markup, '-->', $offset);
+        if (false === $end) return null;
+        $comment = substr($markup, $offset, $end + 3 - $offset);
+        $attrs = array();
+        $jsonStart = strpos($comment, '{');
+        if (false !== $jsonStart && '/' !== $match[1]) {
+            $depth = 0;
+            $jsonEnd = null;
+            for ($index = $jsonStart, $limit = strlen($comment) - 3; $index < $limit; ++$index) {
+                if ('{' === $comment[$index]) ++$depth;
+                elseif ('}' === $comment[$index] && 0 === --$depth) { $jsonEnd = $index; break; }
+            }
+            if (null !== $jsonEnd) {
+                $decoded = json_decode(substr($comment, $jsonStart, $jsonEnd - $jsonStart + 1), true);
+                if (is_array($decoded)) $attrs = $decoded;
+            }
+        }
+        return array('name' => $match[2], 'closing' => '/' === $match[1], 'selfClosing' => str_ends_with(rtrim(substr($comment, 0, -3)), '/'), 'length' => strlen($comment), 'comment' => $comment, 'attrs' => $attrs);
+    }
+
+    private static function navigationCloseOffset(string $markup, int $offset): ?int
+    {
+        $depth = 1;
+        $cursor = $offset;
+        while ($depth > 0 && false !== ($next = strpos($markup, '<!--', $cursor))) {
+            $slice = substr($markup, $next, 40);
+            if (preg_match('/^<!--\s*\/wp:navigation\s*-->/', $slice)) {
+                --$depth;
+                if (0 === $depth) return $next;
+            } elseif (preg_match('/^<!--\s*wp:navigation(?:\s|\{)/', $slice)) {
+                ++$depth;
+            }
+            $cursor = $next + 4;
+        }
+        return null;
+    }
+
+    /** @param array<string,mixed> $attrs */
+    private static function responsiveVariantClassFromAttrs(array $attrs): ?string
+    {
+        foreach (preg_split('/\s+/', trim((string) ($attrs['className'] ?? ''))) ?: array() as $class) {
+            if (in_array($class, array('data-liberation-desktop-document', 'data-liberation-mobile-document'), true) || 1 === preg_match('/^site-document-variant-[a-z][a-z0-9_-]{0,31}$/', $class)) return $class;
+        }
+        return null;
+    }
+
+    private static function navigationVariantRank(?string $variant, ?int $partVariant): int
+    {
+        if (is_string($variant)) {
+            if (in_array($variant, array('data-liberation-desktop-document', 'site-document-variant-default'), true) || str_ends_with($variant, ':1')) return 0;
+            if (str_contains($variant, 'mobile') || str_ends_with($variant, ':2')) return 1;
+        }
+        if (1 === $partVariant) return 0;
+        return null === $partVariant ? 3 : 1;
+    }
+
+    private static function navigationItemSignature(string $inner): ?string
+    {
+        $items = array();
+        $offset = 0;
+        $length = strlen($inner);
+        while ($offset < $length && false !== ($start = strpos($inner, '<!--', $offset))) {
+            $comment = self::blockCommentAt($inner, $start);
+            if (null === $comment) { $offset = $start + 4; continue; }
+            $offset = $start + $comment['length'];
+            if ($comment['closing'] || !in_array($comment['name'], array('navigation-link', 'navigation-submenu'), true)) continue;
+            $label = trim((string) ($comment['attrs']['label'] ?? ''));
+            $url = preg_replace('/#.*$/', '', (string) ($comment['attrs']['url'] ?? '')) ?? '';
+            if ('' === $label && '' === $url) continue;
+            $items[] = array($comment['name'], $label, $url);
+        }
+        return array() === $items ? null : json_encode($items, JSON_UNESCAPED_SLASHES);
+    }
+
+    private static function navigationEntityContent(string $inner): string
+    {
+        $offset = 0;
+        $length = strlen($inner);
+        $parts = array();
+        while ($offset < $length && false !== ($start = strpos($inner, '<!--', $offset))) {
+            if ($start > $offset) $parts[] = substr($inner, $offset, $start - $offset);
+            $comment = self::blockCommentAt($inner, $start);
+            if (null === $comment) { $parts[] = substr($inner, $start, 4); $offset = $start + 4; continue; }
+            $offset = $start + $comment['length'];
+            if (!$comment['closing'] && in_array($comment['name'], array('navigation-link', 'navigation-submenu'), true)) {
+                $attrs = $comment['attrs'];
+                $classes = array_values(array_filter(preg_split('/\s+/', trim((string) ($attrs['className'] ?? ''))) ?: array(), static fn(string $class): bool => '' !== $class && !in_array($class, array('blocks-engine-current-navigation-item', 'blocks-engine-current-navigation-underline', 'current', 'active', 'selected'), true) && !preg_match('/^blocks-engine-navigation-current-color-[a-f0-9]{64}$/', $class)));
+                if (array() === $classes) unset($attrs['className']); else $attrs['className'] = implode(' ', $classes);
+                $encoded = json_encode($attrs, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+                $parts[] = '<!-- wp:' . $comment['name'] . ' ' . $encoded . ($comment['selfClosing'] ? ' /-->' : ' -->');
+                continue;
+            }
+            $parts[] = $comment['comment'];
+        }
+        if ($offset < $length) $parts[] = substr($inner, $offset);
+        return trim(implode('', $parts));
+    }
+
+    private static function withNavigationRef(string $opening, int $ref): string
+    {
+        $start = strpos($opening, '{');
+        if (false === $start) return $opening;
+        $depth = 0;
+        $end = null;
+        for ($index = $start, $limit = strlen($opening); $index < $limit; ++$index) {
+            if ('{' === $opening[$index]) ++$depth;
+            elseif ('}' === $opening[$index] && 0 === --$depth) { $end = $index; break; }
+        }
+        if (null === $end) return $opening;
+        $json = substr($opening, $start, $end - $start + 1);
+        if (str_contains($json, '"ref":')) return $opening;
+        $injected = '{}' === $json ? '{"ref":' . $ref . '}' : '{"ref":' . $ref . ',' . substr($json, 1);
+        return substr($opening, 0, $start) . $injected . substr($opening, $end + 1);
+    }
     // A file-system path and a URL path are different encodings of the same
     // name: browsers request exactly what the bootstrap emits and the server
     // URL-decodes the request path before touching the filesystem, so a
diff --git a/php-transformer/tests/unit/shared-variant-navigation.php b/php-transformer/tests/unit/shared-variant-navigation.php
new file mode 100644
index 000000000..5b2e11e1c
--- /dev/null
+++ b/php-transformer/tests/unit/shared-variant-navigation.php
@@ -0,0 +1,110 @@
+<?php
+declare(strict_types=1);
+
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
+
+use Automattic\BlocksEngine\PhpTransformer\ArtifactCompiler\ArtifactCompiler;
+
+$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);
+};
+
+$links = static function (array $items): string {
+    $html = '';
+    foreach ($items as $item) {
+        $html .= '<a href="' . $item[1] . '">' . $item[0] . '</a>';
+    }
+    return $html;
+};
+$identical = array(array('Home', '/'), array('Journal', '/journal'), array('Shop', '/shop'));
+$divergent = array(array('Home', '/'), array('Journal', '/journal'), array('Visits', '/visits'));
+$document = static function (string $title, array $mobileItems) use ($links, $identical): string {
+    $desktop = '<header class="site-header"><nav class="desktop-menu" aria-label="Site">' . $links($identical) . '</nav></header><main><h1>' . $title . '</h1></main>';
+    $mobile = '<header class="site-header"><nav class="mobile-menu" aria-label="Site">' . $links($mobileItems) . '</nav></header><main><h1>' . $title . '</h1></main>';
+    return '<div class="data-liberation-desktop-document">' . $desktop . '</div><div class="data-liberation-mobile-document">' . $mobile . '</div>';
+};
+$compile = static function (array $files): array {
+    return (new ArtifactCompiler())->compile(array('entrypoint' => 'index.html', 'files' => $files))->toArray()['source_reports']['wordpress_site_plan'];
+};
+$markupOf = static function (array $plan): string {
+    $markup = '';
+    foreach (array_merge($plan['template_parts'], $plan['pages'], $plan['templates']) as $document) {
+        $markup .= (string) ($document['canonical_block_markup'] ?? '');
+    }
+    return $markup;
+};
+$functionsOf = static function (array $plan): string {
+    foreach ($plan['writes'] as $write) {
+        if ('functions.php' === ($write['target_path'] ?? null)) {
+            return (string) ($write['payload']['data'] ?? '');
+        }
+    }
+    return '';
+};
+$entityCount = static function (string $functions): int {
+    return preg_match_all("/'slug' => 'blocks-engine-navigation-\\d+'/", $functions);
+};
+$navigationRefs = static function (string $markup): array {
+    $refs = array();
+    if (!preg_match_all('/<!--\s*wp:navigation\s+(\{.*?\})\s*(?:\/)?-->/s', $markup, $matches)) {
+        return $refs;
+    }
+    foreach ($matches[1] as $json) {
+        $attrs = json_decode($json, true);
+        if (is_array($attrs) && isset($attrs['ref'])) {
+            $refs[] = $attrs['ref'];
+        }
+    }
+    return $refs;
+};
+
+$sharedPlan = $compile(array(
+    'index.html' => $document('Home', $identical),
+    'about.html' => $document('About', $identical),
+));
+$sharedMarkup = $markupOf($sharedPlan);
+$sharedFunctions = $functionsOf($sharedPlan);
+$sharedRefs = $navigationRefs($sharedMarkup);
+$sharedNavCount = preg_match_all('/<!--\s*wp:navigation\s+/', $sharedMarkup);
+$assert(2 === $sharedNavCount, 'identical variant menus stay two core/navigation blocks', 'count=' . $sharedNavCount);
+$assert(2 === count($sharedRefs) && 1 === count(array_unique($sharedRefs)), 'identical variant menus share one navigation ref', json_encode($sharedRefs));
+$assert(str_contains($sharedMarkup, '"className":"desktop-menu"') && str_contains($sharedMarkup, '"className":"mobile-menu"'), 'variant presentation stays on each navigation block', $sharedMarkup);
+$assert(1 === $entityCount($sharedFunctions), 'identical variant menus emit one wp_navigation entity', (string) $entityCount($sharedFunctions));
+$assert(str_contains($sharedFunctions, '"label":"Home"') && str_contains($sharedFunctions, '"label":"Journal"') && str_contains($sharedFunctions, '"label":"Shop"') && !str_contains($sharedFunctions, '"label":"Visits"'), 'the shared entity carries the identical item set');
+
+$splitPlan = $compile(array('index.html' => $document('Home', $identical)));
+$splitMarkup = $markupOf($splitPlan);
+$splitRefs = $navigationRefs($splitMarkup);
+$splitNavCount = preg_match_all('/<!--\s*wp:navigation\s+/', $splitMarkup);
+$assert(2 === $splitNavCount && str_contains($splitMarkup, 'data-liberation-desktop-document') && str_contains($splitMarkup, 'data-liberation-mobile-document'), 'in-document variant menus remain two navigations inside their viewport wrappers', 'count=' . $splitNavCount);
+$assert(2 === count($splitRefs) && 1 === count(array_unique($splitRefs)), 'in-document identical variant menus share one navigation ref', json_encode($splitRefs));
+$assert(1 === $entityCount($functionsOf($splitPlan)), 'in-document identical variant menus emit one wp_navigation entity');
+
+$splitDivergent = $compile(array('index.html' => $document('Home', $divergent)));
+$assert(array() === $navigationRefs($markupOf($splitDivergent)), 'in-document divergent variant menus stay independent', json_encode($navigationRefs($markupOf($splitDivergent))));
+
+$divergentPlan = $compile(array(
+    'index.html' => $document('Home', $divergent),
+    'about.html' => $document('About', $divergent),
+));
+$divergentMarkup = $markupOf($divergentPlan);
+$divergentRefs = $navigationRefs($divergentMarkup);
+$divergentNavCount = preg_match_all('/<!--\s*wp:navigation\s+/', $divergentMarkup);
+$assert(2 === $divergentNavCount, 'divergent variant menus stay two core/navigation blocks', 'count=' . $divergentNavCount);
+$assert(array() === $divergentRefs, 'divergent variant menus stay independent', json_encode($divergentRefs));
+$assert(0 === $entityCount($functionsOf($divergentPlan)), 'divergent variant menus do not emit a shared wp_navigation entity');
+$assert(str_contains($divergentMarkup, '"label":"Shop"') && str_contains($divergentMarkup, '"label":"Visits"'), 'divergent menus keep their own items');
+
+if (0 < $failures) {
+    fwrite(STDERR, "Shared variant navigation: {$failures} failed, {$passes} passed\n");
+    exit(1);
+}
+
+echo "Shared variant navigation passed: {$passes} assertions\n";

From e6b8208cd43d5955e7e602771496b777892b88f7 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 14:08:03 -0400
Subject: [PATCH 7/8] fix(site-plan): read variant scope from nested wrapper
 classes

Responsive document classes can live on layout-shell wrapper attributes, so identical variant menus still share one navigation entity.
---
 .../src/WordPressSitePlan/WordPressSitePlan.php | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
index a6388cbb5..e68c02ada 100644
--- a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
+++ b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
@@ -2101,8 +2101,21 @@ private static function navigationCloseOffset(string $markup, int $offset): ?int
     /** @param array<string,mixed> $attrs */
     private static function responsiveVariantClassFromAttrs(array $attrs): ?string
     {
-        foreach (preg_split('/\s+/', trim((string) ($attrs['className'] ?? ''))) ?: array() as $class) {
-            if (in_array($class, array('data-liberation-desktop-document', 'data-liberation-mobile-document'), true) || 1 === preg_match('/^site-document-variant-[a-z][a-z0-9_-]{0,31}$/', $class)) return $class;
+        return self::responsiveVariantClassIn($attrs);
+    }
+
+    private static function responsiveVariantClassIn(mixed $value): ?string
+    {
+        if (is_string($value)) {
+            foreach (preg_split('/\s+/', trim($value)) ?: array() as $class) {
+                if (in_array($class, array('data-liberation-desktop-document', 'data-liberation-mobile-document'), true) || 1 === preg_match('/^site-document-variant-[a-z][a-z0-9_-]{0,31}$/', $class)) return $class;
+            }
+            return null;
+        }
+        if (!is_array($value)) return null;
+        foreach ($value as $item) {
+            $found = self::responsiveVariantClassIn($item);
+            if (null !== $found) return $found;
         }
         return null;
     }

From 56656ede090938d7ff09bfcbafdffaaf2e742bb8 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Sat, 26 Sep 2026 14:25:13 -0400
Subject: [PATCH 8/8] fix(site-plan): bind shared navigation refs before render

Page content is parsed before render filters can replace a sentinel ref, so init writes the created wp_navigation id into stored blocks.
---
 .../src/WordPressSitePlan/WordPressSitePlan.php       | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
index e68c02ada..bbf84c30b 100644
--- a/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
+++ b/php-transformer/src/WordPressSitePlan/WordPressSitePlan.php
@@ -1992,6 +1992,17 @@ private static function navigationEntityBootstrap(array $posts): array
         $lines[] = "        \$created = wp_insert_post( array( 'post_type' => 'wp_navigation', 'post_status' => 'publish', 'post_title' => \$menu['title'], 'post_name' => \$menu['slug'], 'post_content' => \$menu['content'] ), true );";
         $lines[] = "        if ( ! is_wp_error( \$created ) && (int) \$created > 0 ) \$refs[ (int) \$sentinel ] = (int) \$created;";
         $lines[] = "    }";
+        $lines[] = "    global \$wpdb;";
+        $lines[] = "    foreach ( \$refs as \$sentinel => \$id ) {";
+        $lines[] = "        \$post_ids = \$wpdb->get_col( \$wpdb->prepare( \"SELECT ID FROM {\$wpdb->posts} WHERE post_type IN ('page','post','wp_template','wp_template_part') AND post_content LIKE %s\", '%\"ref\":' . (int) \$sentinel . '%' ) );";
+        $lines[] = "        foreach ( \$post_ids as \$post_id ) {";
+        $lines[] = "            \$stored = get_post_field( 'post_content', \$post_id );";
+        $lines[] = "            \$bound = str_replace( '\"ref\":' . (int) \$sentinel, '\"ref\":' . (int) \$id, \$stored );";
+        $lines[] = "            if ( \$bound === \$stored ) continue;";
+        $lines[] = "            \$wpdb->update( \$wpdb->posts, array( 'post_content' => \$bound ), array( 'ID' => (int) \$post_id ) );";
+        $lines[] = "            clean_post_cache( (int) \$post_id );";
+        $lines[] = "        }";
+        $lines[] = "    }";
         $lines[] = "    \$GLOBALS['blocks_engine_navigation_refs'] = \$refs;";
         $lines[] = "}, 1 );";
         $lines[] = "\$blocks_engine_bind_navigation_refs = static function ( string \$content ): string {";