From 852bd52c49e2fa44aebb1cbeefc7aa6d16672af0 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 01:57:57 -0700
Subject: [PATCH 1/8] test(transformer): reproduce the branding anchor folded
 into a promoted navigation

A nav landmark that authors a branding anchor beside a menu list collapses into
one core/navigation with the brand as an extra menu item. The deferral guard only
recognises a brand anchor whose class matches a hard-coded vocabulary, so a class
outside that list leaves the collapse in place. Two consequences ride along: the
brand emits `anchorClassName`, which is not a registered core/navigation-link
attribute, and the menu list's className is copied onto the nav container where it
outranks the landmark's own padding rule.

Red first: the unit contract reports 10 failed / 7 passed and the parity fixture
fails at `blocks.0.innerBlocks` with 4 children instead of 2.

Covers gates N3 and N4.
---
 php-transformer/composer.json                 |   1 +
 .../parity/html-nav-brand-anchor-hoist.json   | 104 +++++++++
 .../unit/navigation-brand-anchor-hoist.php    | 198 ++++++++++++++++++
 3 files changed, 303 insertions(+)
 create mode 100644 php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
 create mode 100644 php-transformer/tests/unit/navigation-brand-anchor-hoist.php

diff --git a/php-transformer/composer.json b/php-transformer/composer.json
index a49b7213..18c1cb43 100644
--- a/php-transformer/composer.json
+++ b/php-transformer/composer.json
@@ -85,6 +85,7 @@
       "php tests/unit/artifact-author-stylesheet-projection.php",
       "php tests/unit/fallback-finding-normalizer.php",
       "php tests/unit/navigation-underline-color-resolver.php",
+      "php tests/unit/navigation-brand-anchor-hoist.php",
       "php tests/unit/button-signal-classifier.php",
       "php tests/unit/button-style-resolver.php",
       "php tests/unit/button-font-family-carry.php",
diff --git a/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json b/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
new file mode 100644
index 00000000..8fd080a3
--- /dev/null
+++ b/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
@@ -0,0 +1,104 @@
+{
+  "schema": "blocks-engine/php-transformer/parity-fixture/v1",
+  "name": "html-nav-brand-anchor-hoist",
+  "description": "A nav landmark that authors a branding anchor beside a menu list keeps three distinct elements: the landmark becomes a core/group{tagName:nav} carrier holding the brand block and the promoted core/navigation, so the brand is never folded in as a menu item. Detection is structural — a direct-child anchor outside the link cluster — so a brand class outside any vocabulary allowlist is still recognised. Folding the brand in emitted the unregistered anchorClassName attribute on core/navigation-link, copied the menu list's className onto the nav container, and blocked the shared link colour from being promoted to the navigation block.",
+  "source_reference": {
+    "repo": "php-transformer",
+    "path": "tests/fixtures/parity/html-nav-brand-anchor-hoist.json",
+    "notes": "Product-neutral header shape: nav landmark with a direct branding anchor whose class carries no brand/logo token, beside a ul menu whose class carries no navigation token."
+  },
+  "legacy_comparison": {
+    "skip": true,
+    "reason": "This fixture covers native block decomposition fidelity beyond the legacy converter."
+  },
+  "operation": "html_transformer.transform",
+  "input": {
+    "content": "<nav aria-label=\"Primary\"><a class=\"wordmark\" href=\"/\"><span class=\"name\">Harbor Studio</span><span class=\"place\">Camden, Maine</span></a><ul class=\"navlinks\"><li><a href=\"/\">Home</a></li><li><a href=\"/work/\">Work</a></li><li><a href=\"/contact/\">Contact</a></li></ul></nav>",
+    "options": {
+      "static_css": ".wordmark{display:flex;flex-direction:column;line-height:1}.wordmark .place{font-size:.6rem;letter-spacing:.16em;text-transform:uppercase;color:#A9B4C2}.navlinks{list-style:none;margin:0;padding:0;display:flex;gap:14px 22px}.navlinks a{letter-spacing:.16em;text-transform:uppercase;color:#DDE3EB}"
+    }
+  },
+  "expected_blocks": [
+    {
+      "path": "blocks.0",
+      "name": "core/group",
+      "attrs": {
+        "tagName": "nav"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.0",
+      "name": "core/paragraph"
+    },
+    {
+      "path": "blocks.0.innerBlocks.1",
+      "name": "core/navigation",
+      "attrs": {
+        "className": "navlinks blocks-engine-list-navigation",
+        "overlayMenu": "mobile",
+        "customTextColor": "#DDE3EB"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.1.innerBlocks.0",
+      "name": "core/navigation-link",
+      "attrs": {
+        "label": "Home",
+        "url": "/",
+        "kind": "custom"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.1.innerBlocks.2",
+      "name": "core/navigation-link",
+      "attrs": {
+        "label": "Contact",
+        "url": "/contact/",
+        "kind": "custom"
+      }
+    }
+  ],
+  "expected_fallbacks": [],
+  "expect": [
+    {
+      "path": "status",
+      "assert": "equals",
+      "value": "success"
+    },
+    {
+      "path": "blocks",
+      "assert": "count",
+      "count": 1
+    },
+    {
+      "path": "blocks.0.innerBlocks",
+      "assert": "count",
+      "count": 2
+    },
+    {
+      "path": "blocks.0.innerBlocks.1.innerBlocks",
+      "assert": "count",
+      "count": 3
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "not_contains",
+      "value": "anchorClassName"
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "contains",
+      "value": "<a class=\"wordmark\" href=\"/\">"
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "not_contains",
+      "value": "<!-- wp:html"
+    },
+    {
+      "path": "fallbacks",
+      "assert": "count",
+      "count": 0
+    }
+  ]
+}
diff --git a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
new file mode 100644
index 00000000..edf37bce
--- /dev/null
+++ b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
@@ -0,0 +1,198 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Contract for hoisting a branding anchor out of a promoted navigation.
+ *
+ * A header that authors three distinct elements — a nav landmark, a branding
+ * anchor, and a menu list — collapsed into ONE core/navigation with the brand as
+ * an extra menu item. The brand then emitted `anchorClassName`, which is not a
+ * registered core/navigation-link attribute, and the menu list's className was
+ * copied onto the nav container so `.navlinks{padding:0}` and
+ * `header nav{padding:22px}` selected the same element.
+ *
+ * The branding anchor is detected structurally — a direct-child anchor outside
+ * the link cluster — not from a class vocabulary, so a designer's choice of
+ * class name cannot reopen the defect.
+ */
+
+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);
+};
+
+$transform = static fn (string $html): array => ( new HtmlTransformer() )->transform($html, array())->toArray();
+
+/** @param array<int, array<string, mixed>> $blocks */
+$findBlocks = static function (array $blocks, string $name) use (&$findBlocks): array {
+    $found = array();
+    foreach ( $blocks as $block ) {
+        if ( $name === ($block['blockName'] ?? '') ) {
+            $found[] = $block;
+        }
+        $found = array_merge($found, $findBlocks(is_array($block['innerBlocks'] ?? null) ? $block['innerBlocks'] : array(), $name));
+    }
+
+    return $found;
+};
+
+$classTokens = static fn (array $block): array => preg_split('/\s+/', trim((string) ($block['attrs']['className'] ?? ''))) ?: array();
+
+// -- Azure-garden shape: brand class outside any allowlist, beside `<ul>` links.
+$unlistedBrandCss = 'header nav{max-width:1200px;margin:0 auto;padding:18px 22px 20px;display:flex;flex-direction:column;gap:16px;align-items:flex-start}'
+    . '.mark{display:flex;flex-direction:column;line-height:1}'
+    . '.mark .name{font-weight:600;font-size:1.4rem}'
+    . '.mark .place{margin-top:7px;font-size:.6rem;letter-spacing:.16em;text-transform:uppercase;color:#A9B4C2}'
+    . '.navlinks{list-style:none;margin:0;padding:0;display:flex;flex-wrap:wrap;gap:14px 22px}'
+    . '.navlinks a{font-size:.635rem;letter-spacing:.16em;text-transform:uppercase;color:#DDE3EB}'
+    . '@media (min-width:720px){header nav{flex-direction:row;align-items:flex-end;justify-content:space-between;padding:22px 22px 22px}}';
+$unlistedBrand = $transform(
+    '<style>' . $unlistedBrandCss . '</style>'
+    . '<header><nav aria-label="Primary">'
+    . '<a class="mark" href="/"><span class="name">Harbor Studio</span><span class="place">Camden, Maine</span></a>'
+    . '<ul class="navlinks">'
+    . '<li><a href="/">Home</a></li><li><a href="/work/">Work</a></li><li><a href="/studio/">Studio</a></li>'
+    . '<li><a href="/journal/">Journal</a></li><li><a href="/contact/">Contact</a></li>'
+    . '</ul></nav></header>'
+);
+$unlistedMarkup = (string) ($unlistedBrand['serialized_blocks'] ?? '');
+$unlistedBlocks = is_array($unlistedBrand['blocks'] ?? null) ? $unlistedBrand['blocks'] : array();
+$unlistedNavigations = $findBlocks($unlistedBlocks, 'core/navigation');
+$unlistedLinks = $findBlocks($unlistedBlocks, 'core/navigation-link');
+$unlistedNavGroups = array_values(array_filter(
+    $findBlocks($unlistedBlocks, 'core/group'),
+    static fn (array $block): bool => 'nav' === (string) ($block['attrs']['tagName'] ?? '')
+));
+
+$assert(
+    1 === count($unlistedNavigations),
+    'unlisted brand class: the menu still promotes to exactly one core/navigation',
+    (string) count($unlistedNavigations)
+);
+$assert(
+    5 === count($unlistedLinks),
+    'unlisted brand class: only the five menu anchors become navigation links',
+    (string) count($unlistedLinks)
+);
+$assert(
+    1 === count($unlistedNavGroups),
+    'unlisted brand class: the nav landmark is emitted as a core/group{tagName:nav} carrier',
+    (string) count($unlistedNavGroups)
+);
+$assert(
+    ! str_contains($unlistedMarkup, 'anchorClassName'),
+    'unlisted brand class: no navigation link carries the unregistered anchorClassName attribute',
+    $unlistedMarkup
+);
+$assert(
+    1 !== preg_match('/wp:navigation-link(?:(?!-->).)*Camden/s', $unlistedMarkup),
+    'unlisted brand class: the branding anchor is not folded in as a menu item label',
+    $unlistedMarkup
+);
+$assert(
+    str_contains($unlistedMarkup, '<a class="mark" href="/">'),
+    'unlisted brand class: the branding anchor keeps its own class so its authored layout still applies',
+    $unlistedMarkup
+);
+$assert(
+    0 === count($findBlocks($unlistedBlocks, 'core/html')),
+    'unlisted brand class: the hoisted brand is a real block rather than an HTML fallback',
+    $unlistedMarkup
+);
+$assert(
+    '#DDE3EB' === (string) ($unlistedNavigations[0]['attrs']['customTextColor'] ?? ''),
+    'unlisted brand class: the colour every remaining link shares is promoted onto the navigation',
+    json_encode($unlistedNavigations[0]['attrs'] ?? array())
+);
+
+// -- N4: the menu list's className must not land on the nav container, where it
+// would outrank `header nav` and zero the header's padding.
+$assert(
+    array() !== $unlistedNavGroups && ! in_array('navlinks', $classTokens($unlistedNavGroups[0]), true),
+    'promoted nav className: the list class is not copied onto the nav container element',
+    json_encode($unlistedNavGroups[0]['attrs'] ?? array())
+);
+$assert(
+    in_array('navlinks', $classTokens($unlistedNavigations[0]), true),
+    'promoted nav className: the list class moves to the block that stands in for the list',
+    json_encode($unlistedNavigations[0]['attrs'] ?? array())
+);
+$assert(
+    1 === preg_match('/<nav class="wp-block-group(?![^"]*\bnavlinks\b)[^"]*"/', $unlistedMarkup),
+    'promoted nav className: the saved nav element carries no list class',
+    $unlistedMarkup
+);
+
+// -- Tbilisi shape: allowlisted brand class, links in a div cluster with no list.
+$divClusterBrand = $transform(
+    '<style>header.site-header nav{max-width:1200px;margin:0 auto;padding:0.9rem 2rem;display:flex;flex-wrap:wrap;align-items:baseline;gap:0.6rem 2rem}'
+    . '.brand{font-weight:800;text-transform:uppercase;margin-right:auto;line-height:1}'
+    . '.nav-links{display:flex;flex-wrap:wrap;gap:0.35rem 1.9rem;align-items:baseline}'
+    . '.nav-links a{font-size:0.76rem;letter-spacing:0.19em;text-transform:uppercase;color:#231f1d}</style>'
+    . '<header class="site-header"><nav aria-label="Primary">'
+    . '<a class="brand" href="/">Harbor Tavern<span>Old Town</span></a>'
+    . '<div class="nav-links">'
+    . '<a href="/">Home</a><a href="/menu/">Menu</a><a href="/about/">About</a>'
+    . '<a href="/visit/">Visit</a><a href="/reserve/">Reservations</a>'
+    . '</div></nav></header>'
+);
+$divMarkup = (string) ($divClusterBrand['serialized_blocks'] ?? '');
+$divBlocks = is_array($divClusterBrand['blocks'] ?? null) ? $divClusterBrand['blocks'] : array();
+
+$assert(
+    1 === count($findBlocks($divBlocks, 'core/navigation')),
+    'div link cluster: the anchor cluster still promotes to one core/navigation',
+    (string) count($findBlocks($divBlocks, 'core/navigation'))
+);
+$assert(
+    5 === count($findBlocks($divBlocks, 'core/navigation-link')),
+    'div link cluster: only the five menu anchors become navigation links',
+    (string) count($findBlocks($divBlocks, 'core/navigation-link'))
+);
+$assert(
+    ! str_contains($divMarkup, 'anchorClassName'),
+    'div link cluster: no navigation link carries the unregistered anchorClassName attribute',
+    $divMarkup
+);
+$assert(
+    0 === count($findBlocks($divBlocks, 'core/html')),
+    'div link cluster: the hoisted brand is a real block rather than an HTML fallback',
+    $divMarkup
+);
+
+// -- Control: a menu with no branding anchor keeps today's single navigation block.
+$plainMenu = $transform(
+    '<style>.main-nav{display:flex;gap:1rem}</style>'
+    . '<nav class="main-nav" aria-label="Primary"><ul><li><a href="/">Home</a></li><li><a href="/about/">About</a></li></ul></nav>'
+);
+$plainBlocks = is_array($plainMenu['blocks'] ?? null) ? $plainMenu['blocks'] : array();
+
+$assert(
+    1 === count($plainBlocks) && 'core/navigation' === (string) ($plainBlocks[0]['blockName'] ?? ''),
+    'no branding anchor control: the promoted navigation is not wrapped in a carrier group',
+    json_encode(array_map(static fn (array $block): string => (string) ($block['blockName'] ?? ''), $plainBlocks))
+);
+$assert(
+    2 === count($findBlocks($plainBlocks, 'core/navigation-link')),
+    'no branding anchor control: both menu anchors remain navigation links',
+    (string) count($findBlocks($plainBlocks, 'core/navigation-link'))
+);
+
+if ( $failures > 0 ) {
+    fwrite(STDERR, "Navigation brand anchor hoist contract: {$failures} failed, {$passes} passed\n");
+    exit(1);
+}
+
+fwrite(STDOUT, "Navigation brand anchor hoist contract passed: {$passes} assertions\n");

From 68dcdfde8d61be0bfa58dfc100475f86626b51dd Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 01:59:25 -0700
Subject: [PATCH 2/8] refactor(transformer): let a pattern convert a sibling
 element
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pattern recognizers could convert an element's children but not an element
itself. A pattern that keeps a sibling out of its own block — a branding anchor
beside a menu, for example — needs that sibling emitted exactly as the generic
pipeline would emit it anywhere else, not rebuilt by hand from inner HTML.

Adds a nullable `convertElement` callback to PatternContext and wires it to the
element conversion entry point. No behavior change: nothing consumes it yet, and
the probe context leaves it null.
---
 .../src/HtmlToBlocks/HtmlTransformer.php        | 12 +++++++++++-
 .../HtmlToBlocks/Patterns/PatternContext.php    | 17 ++++++++++++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlTransformer.php b/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
index a1c2f86d..1f7b57a1 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
@@ -2494,7 +2494,8 @@ private function patternContext(bool $includeRuntimeDomTarget = true): PatternCo
             fn (DOMElement $sourceElement): array => $this->convertPatternChildren($sourceElement),
             fn (DOMElement $sourceElement, array $excludedTags): array => $this->convertPatternChildrenWithoutTags($sourceElement, $excludedTags),
             fn (DOMElement $item, DOMElement $anchor): string => $this->navigationUnderlineColor($item, $anchor),
-            fn (DOMElement $sourceElement): string => $this->resolveCssVariablesInValue($this->mergedPresentationStyle($sourceElement))
+            fn (DOMElement $sourceElement): string => $this->resolveCssVariablesInValue($this->mergedPresentationStyle($sourceElement)),
+            fn (DOMElement $sourceElement): ?array => $this->convertPatternElement($sourceElement)
         );
     }
 
@@ -2507,6 +2508,15 @@ private function convertPatternChildren(DOMElement $element): array
         return $this->convertChildren($element, $fallbacks, true);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
+    private function convertPatternElement(DOMElement $element): ?array
+    {
+        $fallbacks = array();
+        return $this->convertElement($element, $fallbacks, true);
+    }
+
     /**
      * @param array<int, string> $excludedTags
      * @return array<int, array<string, mixed>>
diff --git a/php-transformer/src/HtmlToBlocks/Patterns/PatternContext.php b/php-transformer/src/HtmlToBlocks/Patterns/PatternContext.php
index 127d389f..417dae15 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/PatternContext.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/PatternContext.php
@@ -16,6 +16,7 @@ final class PatternContext
      * @param callable(DOMElement, array<int, string>): array<int, array<string, mixed>>|null $convertChildrenWithoutTags
      * @param callable(DOMElement, DOMElement): string|null $navigationUnderlineColor
      * @param callable(DOMElement): string|null $resolvedStyle
+     * @param callable(DOMElement): array<string, mixed>|null $convertElement
      */
     public function __construct(
         private readonly mixed $presentationAttributes,
@@ -25,7 +26,8 @@ public function __construct(
         private readonly mixed $convertChildren = null,
         private readonly mixed $convertChildrenWithoutTags = null,
         private readonly mixed $navigationUnderlineColor = null,
-        private readonly mixed $resolvedStyle = null
+        private readonly mixed $resolvedStyle = null,
+        private readonly mixed $convertElement = null
     ) {
     }
 
@@ -69,6 +71,19 @@ public function convertChildrenCallback(): ?callable
         return is_callable($this->convertChildren) ? $this->convertChildren : null;
     }
 
+    /**
+     * Convert one element to the block the generic pipeline would emit for it.
+     * A pattern that keeps a sibling element out of its own block needs the
+     * element's own conversion rather than its children's, so the sibling is
+     * emitted exactly as it would be anywhere else in the document.
+     *
+     * @return callable(DOMElement): array<string, mixed>|null
+     */
+    public function convertElementCallback(): ?callable
+    {
+        return is_callable($this->convertElement) ? $this->convertElement : null;
+    }
+
     /**
      * @return callable(DOMElement, array<int, string>): array<int, array<string, mixed>>|null
      */

From 454836548bb34106c4ab0f66687b4e2ee20f3a26 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 02:03:33 -0700
Subject: [PATCH 3/8] fix(transformer): hoist a branding anchor out of the
 promoted navigation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A nav container holding a branding anchor beside its link cluster authors three
elements, each with its own CSS rule. Promoting all three into one
core/navigation made the brand a menu item, so the landmark's own box rules and
the menu list's rules competed on a single element and the brand emitted
`anchorClassName` — an attribute core/navigation-link does not register, which
stops a consumer's block transformation on the whole part.

The landmark is now emitted as a core/group carrier holding the brand block and a
core/navigation built from the link cluster alone. The brand is detected
structurally — a direct-child anchor outside the cluster, one anchor and one
cluster, no other significant children — so no class vocabulary decides whether
it survives, and it is converted by the generic pipeline rather than rebuilt from
inner HTML. The cluster owns the navigation block's presentation, so the menu
list's className stays with the menu.

The existing deferral guard still runs first and keeps the shapes it already
recognises unchanged. Any container the carrier cannot fully account for falls
through to the previous behavior.

Closes gates N3 and N4.
---
 .../Patterns/NavigationPattern.php            | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index b6234273..7cc654b0 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -46,6 +46,11 @@ public function match(DOMElement $element, PatternContext $context): ?array
             return null;
         }
 
+        $hoisted = $this->brandAnchorCarrier($element, $presentationAttributes, $innerHtml, $createBlock, $context->convertElementCallback(), $isRuntimeDomTarget, $navigationUnderlineColor);
+        if ( null !== $hoisted ) {
+            return $hoisted;
+        }
+
         $links = $this->navigationBlocks($element, $presentationAttributes, $innerHtml, $createBlock, $isRuntimeDomTarget, false, $navigationUnderlineColor);
 
         if ( array() === $links ) {
@@ -95,6 +100,111 @@ public function match(DOMElement $element, PatternContext $context): ?array
         return $createBlock('core/group', array_merge($presentationAttributes($element), array( 'tagName' => 'div' )), array( $labelBlock, $navigation ), $element);
     }
 
+    /**
+     * A nav container that holds a branding anchor beside its link cluster
+     * authors THREE elements — the landmark, the brand, and the menu — each with
+     * its own CSS rule. Folding all three into one core/navigation makes the
+     * brand a menu item: the landmark's own box rules then compete with the
+     * menu list's rules on a single element, and the brand emits
+     * `anchorClassName`, which core/navigation-link does not register.
+     *
+     * Emit the landmark as a carrier group instead, holding the brand block and
+     * a core/navigation built from the link cluster alone. The brand is found
+     * STRUCTURALLY — a direct-child anchor outside the cluster — so no class
+     * vocabulary decides whether it survives.
+     *
+     * `hasDirectBrandingAnchorBesideListNavigation()` runs first and keeps
+     * deferring the shapes it already recognises, so this covers exactly the
+     * containers that would otherwise absorb the brand.
+     *
+     * @return array<string, mixed>|null
+     */
+    private function brandAnchorCarrier(DOMElement $element, callable $presentationAttributes, callable $innerHtml, callable $createBlock, ?callable $convertElement, ?callable $isRuntimeDomTarget, ?callable $navigationUnderlineColor): ?array
+    {
+        if ( null === $convertElement ) {
+            return null;
+        }
+
+        if ( 'nav' !== strtolower($element->tagName) && ! $this->hasNavigationSignal($element) ) {
+            return null;
+        }
+
+        $anchor = null;
+        $cluster = null;
+        $brandLeads = true;
+        foreach ( $element->childNodes as $child ) {
+            if ( XML_COMMENT_NODE === $child->nodeType ) {
+                continue;
+            }
+
+            if ( XML_TEXT_NODE === $child->nodeType && '' === trim($child->textContent ?? '') ) {
+                continue;
+            }
+
+            if ( ! $child instanceof DOMElement ) {
+                return null;
+            }
+
+            if ( $this->isNavigationChromeElement($child) ) {
+                continue;
+            }
+
+            if ( 'a' === strtolower($child->tagName) ) {
+                if ( $anchor instanceof DOMElement
+                    || '' === $this->anchorLabel($child, $innerHtml)
+                    || preg_match('/<(?:' . self::BLOCK_LEVEL_LABEL_TAGS . ')\b/i', $innerHtml($child))
+                ) {
+                    return null;
+                }
+
+                $anchor = $child;
+                $brandLeads = ! $cluster instanceof DOMElement;
+                continue;
+            }
+
+            if ( $cluster instanceof DOMElement ) {
+                return null;
+            }
+
+            $cluster = $child;
+        }
+
+        if ( ! $anchor instanceof DOMElement || ! $cluster instanceof DOMElement ) {
+            return null;
+        }
+
+        $links = $this->navigationBlocks($cluster, $presentationAttributes, $innerHtml, $createBlock, $isRuntimeDomTarget, false, $navigationUnderlineColor);
+        if ( 2 > count($links) ) {
+            return null;
+        }
+
+        // An anchor that only converts to an HTML fallback would trade a menu
+        // item for raw markup; keep today's shape rather than lose the block.
+        $brand = $convertElement($anchor);
+        $brandName = is_array($brand) ? (string) ($brand['blockName'] ?? '') : '';
+        if ( '' === $brandName || 'core/html' === $brandName ) {
+            return null;
+        }
+
+        // The link cluster owns the navigation block's presentation: it is the
+        // element core/navigation stands in for, so the menu list's className
+        // stays with the menu instead of being copied onto the landmark.
+        $navigationAttrs = $this->navigationContainerAttributes($cluster, $presentationAttributes);
+        $navigationAttrs['overlayMenu'] = 'mobile';
+        $commonTextAttrs = $this->commonNavigationLinkTextAttributes($links);
+        if ( $this->isListNavigationSource($cluster) ) {
+            unset($commonTextAttrs['style']['typography']);
+        }
+        $navigationAttrs = array_replace_recursive($navigationAttrs, $commonTextAttrs);
+
+        $navigation = $createBlock('core/navigation', $navigationAttrs, $links, $cluster);
+        $carrierAttrs = array_merge($presentationAttributes($element), array(
+            'tagName' => 'nav' === strtolower($element->tagName) ? 'nav' : 'div',
+        ));
+
+        return $createBlock('core/group', $carrierAttrs, $brandLeads ? array( $brand, $navigation ) : array( $navigation, $brand ), $element);
+    }
+
     private function directSectionLabel(DOMElement $element): ?DOMElement
     {
         foreach ( $element->childNodes as $child ) {

From e4cdef6e405cf3452e7a2dcf6a0498c665501ca4 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 02:14:42 -0700
Subject: [PATCH 4/8] fix(transformer): keep script-driven nav chrome out of
 the brand carrier

`navigationBlocks()` refuses to promote a container whose skipped chrome is a
runtime DOM target, because a promoted navigation would drop an element that
scripts drive. The brand carrier skipped chrome without that check, so it could
have promoted a container the sibling path would have deferred.

Mirrors the existing guard rather than inventing a second policy.
---
 .../src/HtmlToBlocks/Patterns/NavigationPattern.php          | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 7cc654b0..aab85fb6 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -146,6 +146,11 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
             }
 
             if ( $this->isNavigationChromeElement($child) ) {
+                // Chrome that scripts drive at runtime is not decoration: a
+                // carrier group would drop it, so keep the source shape.
+                if ( null !== $isRuntimeDomTarget && $isRuntimeDomTarget($child) ) {
+                    return null;
+                }
                 continue;
             }
 

From 042a65ff3ce74a71db7b34bde170983fb0821d84 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 02:41:11 -0700
Subject: [PATCH 5/8] fix(transformer): hoist a brand lockup built from
 block-level markup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The carrier reused the deferral guard's rule that a branding anchor must hold no
block-level markup. That rule exists because the guard's sibling path flattens the
anchor into a menu item label, where a heading or div would be stripped. The
carrier converts the anchor instead, so the restriction only kept a
`<a class="wordmark"><h1>…</h1></a>` lockup absorbed into the menu — emitting the
unregistered `anchorClassName` and losing the heading.

Verified against the parent commit: both a heading lockup and a two-div lockup went
from one absorbed menu item to a converted brand block, `anchorClassName` 1 -> 0.
---
 .../Patterns/NavigationPattern.php            |  8 +++---
 .../unit/navigation-brand-anchor-hoist.php    | 27 +++++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index aab85fb6..9e355e97 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -154,11 +154,11 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
                 continue;
             }
 
+            // Block-level content inside the anchor is no obstacle here: the
+            // carrier converts the anchor rather than flattening it into a menu
+            // item label, so a lockup built from a heading survives whole.
             if ( 'a' === strtolower($child->tagName) ) {
-                if ( $anchor instanceof DOMElement
-                    || '' === $this->anchorLabel($child, $innerHtml)
-                    || preg_match('/<(?:' . self::BLOCK_LEVEL_LABEL_TAGS . ')\b/i', $innerHtml($child))
-                ) {
+                if ( $anchor instanceof DOMElement || '' === $this->anchorLabel($child, $innerHtml) ) {
                     return null;
                 }
 
diff --git a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
index edf37bce..14feb922 100644
--- a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
+++ b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
@@ -172,6 +172,33 @@
     $divMarkup
 );
 
+// -- A lockup built from block-level markup is still a brand, not a menu item:
+// the carrier converts the anchor instead of flattening it into a label.
+$blockLevelBrand = $transform(
+    '<style>header nav{display:flex;justify-content:space-between;padding:22px}.wordmark{display:block}'
+    . '.navlinks{list-style:none;margin:0;padding:0;display:flex;gap:20px}</style>'
+    . '<header><nav aria-label="Primary"><a class="wordmark" href="/"><h1>Harbor Studio</h1></a>'
+    . '<ul class="navlinks"><li><a href="/">Home</a></li><li><a href="/work/">Work</a></li></ul></nav></header>'
+);
+$blockLevelMarkup = (string) ($blockLevelBrand['serialized_blocks'] ?? '');
+$blockLevelBlocks = is_array($blockLevelBrand['blocks'] ?? null) ? $blockLevelBrand['blocks'] : array();
+
+$assert(
+    ! str_contains($blockLevelMarkup, 'anchorClassName'),
+    'block-level brand lockup: the heading anchor is not folded in as a menu item',
+    $blockLevelMarkup
+);
+$assert(
+    2 === count($findBlocks($blockLevelBlocks, 'core/navigation-link')),
+    'block-level brand lockup: only the two menu anchors become navigation links',
+    (string) count($findBlocks($blockLevelBlocks, 'core/navigation-link'))
+);
+$assert(
+    1 === count($findBlocks($blockLevelBlocks, 'core/heading')) && 0 === count($findBlocks($blockLevelBlocks, 'core/html')),
+    'block-level brand lockup: the authored heading survives as a heading block',
+    $blockLevelMarkup
+);
+
 // -- Control: a menu with no branding anchor keeps today's single navigation block.
 $plainMenu = $transform(
     '<style>.main-nav{display:flex;gap:1rem}</style>'

From 5a21249002b00e4c5abd14c462bef2f380f2054b Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 04:03:35 -0700
Subject: [PATCH 6/8] fix(transformer): require a brand cue before hoisting an
 anchor out of a menu
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Structural position alone does not identify a brand. A nav that authors an
ordinary menu link outside its list — `<nav><a>Home</a><ul>…</ul></nav>`, a
common hand-authored shape — had that link hoisted into a sibling block: it left
the editable menu, lost the promoted shared colour, and stopped counting as a
menu item.

The anchor must now also read as branding: a lockup built from element children,
or an explicit brand/logo cue. Every shape the carrier targets qualifies — a
name-plus-place lockup, a heading lockup, a single-line wordmark — while bare
anchor text stays a menu item. A fixture pins that bare-text shape to the
behavior it has without the carrier.

The carrier is also restricted to a real `<nav>` landmark rather than any
navigation-signalled container, which removes an untestable branch: a consumer's
raw-anchor link resolution scopes by lexical `<nav>` ancestry, so a brand hoisted
into a `div` carrier would fall outside both that pass and the block pass that
rewrites navigation links, losing coverage the folded shape had. The reason now
sits in the comment beside the tag, with a fixture pinning the nested landmark as
harmless: core/navigation is dynamic, so saved content still holds one `<nav>`.

Cheap structural checks now run before either conversion, so a bail no longer
leaves provenance and runtime-island records behind for output never emitted. The
comment no longer claims more coverage than the code has — an anchor holding only
an image with no accessible name is still classified as chrome before it reaches
the brand test.
---
 .../Patterns/NavigationPattern.php            | 62 +++++++++++--
 .../html-nav-bare-link-outside-list.json      | 82 +++++++++++++++++
 .../html-nav-brand-carrier-landmark.json      | 91 +++++++++++++++++++
 .../unit/navigation-brand-anchor-hoist.php    | 33 ++++++-
 4 files changed, 259 insertions(+), 9 deletions(-)
 create mode 100644 php-transformer/tests/fixtures/parity/html-nav-bare-link-outside-list.json
 create mode 100644 php-transformer/tests/fixtures/parity/html-nav-brand-carrier-landmark.json

diff --git a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
index 9e355e97..35dfdacb 100644
--- a/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
+++ b/php-transformer/src/HtmlToBlocks/Patterns/NavigationPattern.php
@@ -109,9 +109,23 @@ public function match(DOMElement $element, PatternContext $context): ?array
      * `anchorClassName`, which core/navigation-link does not register.
      *
      * Emit the landmark as a carrier group instead, holding the brand block and
-     * a core/navigation built from the link cluster alone. The brand is found
-     * STRUCTURALLY — a direct-child anchor outside the cluster — so no class
-     * vocabulary decides whether it survives.
+     * a core/navigation built from the link cluster alone. Structural position
+     * does the work a class allowlist used to do — a direct-child anchor outside
+     * the cluster — but position alone cannot tell a brand from an ordinary menu
+     * item that happens to sit outside the list, so the anchor must also read as
+     * a brand: a lockup (element children) or a brand/logo cue. A bare
+     * `<a>Home</a>` beside the list stays a menu item.
+     *
+     * Not covered: an anchor holding only an image with no accessible name is
+     * classified as navigation chrome before it reaches the brand test, so an
+     * image-only logo is still dropped — as it is without this carrier.
+     *
+     * The carrier is restricted to a real `<nav>` landmark. That is load-bearing,
+     * not cosmetic: a consumer's raw-anchor link resolution scopes by lexical
+     * `<nav>` ancestry, so a brand hoisted out of the link set keeps its resolved
+     * URL only while it renders inside a `<nav>`. A `div` carrier would put the
+     * brand outside both that pass and the block pass that rewrites
+     * `wp:navigation-link`, losing coverage the folded shape had.
      *
      * `hasDirectBrandingAnchorBesideListNavigation()` runs first and keeps
      * deferring the shapes it already recognises, so this covers exactly the
@@ -125,7 +139,7 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
             return null;
         }
 
-        if ( 'nav' !== strtolower($element->tagName) && ! $this->hasNavigationSignal($element) ) {
+        if ( 'nav' !== strtolower($element->tagName) ) {
             return null;
         }
 
@@ -158,7 +172,10 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
             // carrier converts the anchor rather than flattening it into a menu
             // item label, so a lockup built from a heading survives whole.
             if ( 'a' === strtolower($child->tagName) ) {
-                if ( $anchor instanceof DOMElement || '' === $this->anchorLabel($child, $innerHtml) ) {
+                if ( $anchor instanceof DOMElement
+                    || '' === $this->anchorLabel($child, $innerHtml)
+                    || ! $this->readsAsBrandAnchor($child)
+                ) {
                     return null;
                 }
 
@@ -178,6 +195,14 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
             return null;
         }
 
+        // Settle every cheap structural question before converting anything.
+        // Both conversions below run against the real block factory and record
+        // provenance and runtime islands, so a bail after them leaves recorded
+        // side effects behind for output that was never emitted.
+        if ( 2 > $cluster->getElementsByTagName('a')->length ) {
+            return null;
+        }
+
         $links = $this->navigationBlocks($cluster, $presentationAttributes, $innerHtml, $createBlock, $isRuntimeDomTarget, false, $navigationUnderlineColor);
         if ( 2 > count($links) ) {
             return null;
@@ -203,13 +228,34 @@ private function brandAnchorCarrier(DOMElement $element, callable $presentationA
         $navigationAttrs = array_replace_recursive($navigationAttrs, $commonTextAttrs);
 
         $navigation = $createBlock('core/navigation', $navigationAttrs, $links, $cluster);
-        $carrierAttrs = array_merge($presentationAttributes($element), array(
-            'tagName' => 'nav' === strtolower($element->tagName) ? 'nav' : 'div',
-        ));
+
+        // The carrier is the authored `<nav>`, so it keeps that tag (see above).
+        // The authored `aria-label` does not come with it: core/group registers no
+        // attribute that carries an accessible name, and inventing one would emit
+        // exactly the unregistered comment attribute this carrier exists to stop.
+        $carrierAttrs = array_merge($presentationAttributes($element), array( 'tagName' => 'nav' ));
 
         return $createBlock('core/group', $carrierAttrs, $brandLeads ? array( $brand, $navigation ) : array( $navigation, $brand ), $element);
     }
 
+    /**
+     * Whether a direct-child anchor reads as branding rather than as a menu item
+     * that happens to sit outside the list. A lockup — an anchor built from
+     * element children such as a name plus a location, or a heading — is the
+     * structural signal; an explicit brand/logo cue is accepted as well so a
+     * single-line wordmark still qualifies. Bare anchor text does not.
+     */
+    private function readsAsBrandAnchor(DOMElement $anchor): bool
+    {
+        foreach ( $anchor->childNodes as $child ) {
+            if ( $child instanceof DOMElement ) {
+                return true;
+            }
+        }
+
+        return $this->hasBrandAnchorSignal($anchor);
+    }
+
     private function directSectionLabel(DOMElement $element): ?DOMElement
     {
         foreach ( $element->childNodes as $child ) {
diff --git a/php-transformer/tests/fixtures/parity/html-nav-bare-link-outside-list.json b/php-transformer/tests/fixtures/parity/html-nav-bare-link-outside-list.json
new file mode 100644
index 00000000..9105d4f3
--- /dev/null
+++ b/php-transformer/tests/fixtures/parity/html-nav-bare-link-outside-list.json
@@ -0,0 +1,82 @@
+{
+  "schema": "blocks-engine/php-transformer/parity-fixture/v1",
+  "name": "html-nav-bare-link-outside-list",
+  "description": "An ordinary menu link that sits outside the list is still a menu item. Structural position alone does not make a direct-child anchor a brand, so the branding carrier must not hoist it: all three anchors stay core/navigation-link children of one navigation block, and the colour they share is still promoted to the navigation. Hoisting this shape would quietly remove a link from the editable menu.",
+  "source_reference": {
+    "repo": "php-transformer",
+    "path": "tests/fixtures/parity/html-nav-bare-link-outside-list.json",
+    "notes": "Product-neutral counterpart to html-nav-brand-anchor-hoist: same topology, but the outside anchor is bare text with no brand cue and no lockup children."
+  },
+  "legacy_comparison": {
+    "skip": true,
+    "reason": "This fixture covers native block decomposition fidelity beyond the legacy converter."
+  },
+  "operation": "html_transformer.transform",
+  "input": {
+    "content": "<nav aria-label=\"Primary\"><a href=\"/\">Home</a><ul class=\"menu\"><li><a href=\"/about/\">About</a></li><li><a href=\"/contact/\">Contact</a></li></ul></nav>",
+    "options": {
+      "static_css": ".menu{list-style:none;margin:0;padding:0;display:flex;gap:20px}.menu a,nav>a{letter-spacing:.16em;text-transform:uppercase;color:#DDE3EB}"
+    }
+  },
+  "expected_blocks": [
+    {
+      "path": "blocks.0",
+      "name": "core/navigation",
+      "attrs": {
+        "customTextColor": "#DDE3EB",
+        "overlayMenu": "mobile"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.0",
+      "name": "core/navigation-link",
+      "attrs": {
+        "label": "Home",
+        "url": "/",
+        "kind": "custom"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.2",
+      "name": "core/navigation-link",
+      "attrs": {
+        "label": "Contact",
+        "url": "/contact/",
+        "kind": "custom"
+      }
+    }
+  ],
+  "expected_fallbacks": [],
+  "expect": [
+    {
+      "path": "status",
+      "assert": "equals",
+      "value": "success"
+    },
+    {
+      "path": "blocks",
+      "assert": "count",
+      "count": 1
+    },
+    {
+      "path": "blocks.0.innerBlocks",
+      "assert": "count",
+      "count": 3
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "not_contains",
+      "value": "wp:group"
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "not_contains",
+      "value": "wp:paragraph"
+    },
+    {
+      "path": "fallbacks",
+      "assert": "count",
+      "count": 0
+    }
+  ]
+}
diff --git a/php-transformer/tests/fixtures/parity/html-nav-brand-carrier-landmark.json b/php-transformer/tests/fixtures/parity/html-nav-brand-carrier-landmark.json
new file mode 100644
index 00000000..4668f4d3
--- /dev/null
+++ b/php-transformer/tests/fixtures/parity/html-nav-brand-carrier-landmark.json
@@ -0,0 +1,91 @@
+{
+  "schema": "blocks-engine/php-transformer/parity-fixture/v1",
+  "name": "html-nav-brand-carrier-landmark",
+  "description": "The branding carrier keeps the authored nav tag rather than becoming a div, because a consumer's raw-anchor link resolution scopes by lexical nav ancestry — a hoisted brand keeps its resolved URL only while it renders inside a nav. The nested landmark that follows is harmless in saved content: core/navigation is a dynamic block, so the saved part carries exactly one nav element and landmark parity stays 1:1 with the source.",
+  "source_reference": {
+    "repo": "php-transformer",
+    "path": "tests/fixtures/parity/html-nav-brand-carrier-landmark.json",
+    "notes": "Pins the deliberate tagName choice and the landmark and item accounting that goes with it, so switching the carrier to div, losing landmark parity, or regressing semantic parity all fail loudly."
+  },
+  "legacy_comparison": {
+    "skip": true,
+    "reason": "This fixture covers native block decomposition fidelity beyond the legacy converter."
+  },
+  "operation": "html_transformer.transform",
+  "input": {
+    "content": "<header><nav aria-label=\"Primary\"><a class=\"wordmark\" href=\"/\"><span class=\"name\">Harbor Studio</span><span class=\"place\">Camden, Maine</span></a><ul class=\"navlinks\"><li><a href=\"/\">Home</a></li><li><a href=\"/work/\">Work</a></li></ul></nav></header>",
+    "options": {
+      "static_css": "header nav{max-width:1200px;margin:0 auto;padding:22px;display:flex;justify-content:space-between}.wordmark{display:flex;flex-direction:column;line-height:1}.navlinks{list-style:none;margin:0;padding:0;display:flex;gap:22px}.navlinks a{text-transform:uppercase;color:#DDE3EB}"
+    }
+  },
+  "expected_blocks": [
+    {
+      "path": "blocks.0",
+      "name": "core/group",
+      "attrs": {
+        "tagName": "nav"
+      }
+    },
+    {
+      "path": "blocks.0.innerBlocks.0",
+      "name": "core/paragraph"
+    },
+    {
+      "path": "blocks.0.innerBlocks.1",
+      "name": "core/navigation",
+      "attrs": {
+        "className": "navlinks blocks-engine-list-navigation",
+        "overlayMenu": "mobile",
+        "customTextColor": "#DDE3EB"
+      }
+    }
+  ],
+  "expected_fallbacks": [],
+  "expect": [
+    {
+      "path": "status",
+      "assert": "equals",
+      "value": "success"
+    },
+    {
+      "path": "source_reports.semantic_parity.status",
+      "assert": "equals",
+      "value": "pass"
+    },
+    {
+      "path": "source_reports.semantic_parity.landmarks.source.nav",
+      "assert": "equals",
+      "value": 1
+    },
+    {
+      "path": "source_reports.semantic_parity.landmarks.blocks.nav",
+      "assert": "equals",
+      "value": 1
+    },
+    {
+      "path": "source_reports.semantic_parity.findings",
+      "assert": "count",
+      "count": 0
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "contains",
+      "value": "<nav class=\"wp-block-group"
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "contains",
+      "value": "<a class=\"wordmark\" href=\"/\">"
+    },
+    {
+      "path": "serialized_blocks",
+      "assert": "not_contains",
+      "value": "anchorClassName"
+    },
+    {
+      "path": "fallbacks",
+      "assert": "count",
+      "count": 0
+    }
+  ]
+}
diff --git a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
index 14feb922..2813cbe3 100644
--- a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
+++ b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
@@ -97,7 +97,7 @@
     $unlistedMarkup
 );
 $assert(
-    1 !== preg_match('/wp:navigation-link(?:(?!-->).)*Camden/s', $unlistedMarkup),
+    0 === preg_match('/wp:navigation-link(?:(?!-->).)*Camden/s', $unlistedMarkup),
     'unlisted brand class: the branding anchor is not folded in as a menu item label',
     $unlistedMarkup
 );
@@ -199,6 +199,37 @@
     $blockLevelMarkup
 );
 
+// -- Structural position alone is not a brand. An ordinary menu link that happens
+// to sit outside the list keeps its place in the menu: it stays a navigation link,
+// keeps the promoted shared colour, and never becomes a hoisted sibling block.
+$bareLinkOutsideList = $transform(
+    '<style>header nav{display:flex;justify-content:space-between;padding:22px}'
+    . '.menu{list-style:none;margin:0;padding:0;display:flex;gap:20px}.menu a,nav>a{color:#DDE3EB}</style>'
+    . '<header><nav aria-label="Primary"><a href="/">Home</a>'
+    . '<ul class="menu"><li><a href="/about/">About</a></li><li><a href="/contact/">Contact</a></li></ul></nav></header>'
+);
+$bareLinkBlocks = is_array($bareLinkOutsideList['blocks'] ?? null) ? $bareLinkOutsideList['blocks'] : array();
+$bareLinkNavigations = $findBlocks($bareLinkBlocks, 'core/navigation');
+
+$assert(
+    3 === count($findBlocks($bareLinkBlocks, 'core/navigation-link')),
+    'bare link outside the list: all three anchors stay navigation links',
+    (string) count($findBlocks($bareLinkBlocks, 'core/navigation-link'))
+);
+$assert(
+    array() === array_values(array_filter(
+        $findBlocks($bareLinkBlocks, 'core/group'),
+        static fn (array $block): bool => 'nav' === (string) ($block['attrs']['tagName'] ?? '')
+    )),
+    'bare link outside the list: no carrier group is emitted',
+    (string) ($bareLinkOutsideList['serialized_blocks'] ?? '')
+);
+$assert(
+    '#DDE3EB' === (string) ($bareLinkNavigations[0]['attrs']['customTextColor'] ?? ''),
+    'bare link outside the list: the shared link colour is still promoted to the navigation',
+    json_encode($bareLinkNavigations[0]['attrs'] ?? array())
+);
+
 // -- Control: a menu with no branding anchor keeps today's single navigation block.
 $plainMenu = $transform(
     '<style>.main-nav{display:flex;gap:1rem}</style>'

From 9d947f5be1d664aa17c31dc7b7ada57fdb95fcc3 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 04:03:48 -0700
Subject: [PATCH 7/8] fix(transformer): count a carrier's hoisted links in
 navigation parity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Semantic parity counts every anchor under a source nav landmark on one side and
only core/navigation children on the other. Hoisting the brand out of the menu
therefore read as content loss: the azure-garden header went from parity `pass` to
`warning` with `navigation_item_count_mismatch` (source 6, block 5) — a false
positive on the exact shape the hoist exists to fix, and one the parity fixture's
`status == "success"` assertion could not catch.

When a navigation block's landmark is a `core/group{tagName:"nav"}` carrier, the
blocks hoisted out beside it now contribute their anchors to that menu's item
list. Counting them here rather than excluding them on the source side keeps a
brand that disappears entirely detectable as real loss.

Two existing parity policies already exclude outside anchors on the source side —
a landmark bearing mobile chrome, and one holding both a brand and a CTA beside
its list. The carrier's items are only added when neither applies, so the same
anchors are never counted on one side while being deliberately dropped on the
other. The fixture now pins `semantic_parity == "pass"`.
---
 .../Diagnostics/SemanticParityReporter.php    | 172 +++++++++++++++++-
 .../parity/html-nav-brand-anchor-hoist.json   |   5 +
 2 files changed, 174 insertions(+), 3 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php b/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
index be78a79c..eeda7911 100644
--- a/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
+++ b/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
@@ -231,6 +231,7 @@ private function collectSourceNavigationMenus(DOMElement $element, array &$menus
                 'selector' => $this->elementSelector($element),
                 'item_count' => count($items),
                 'items' => $items,
+                'excludes_outside_anchors' => $this->sourceMenuExcludesOutsideAnchors($element),
             );
         }
 
@@ -241,6 +242,35 @@ private function collectSourceNavigationMenus(DOMElement $element, array &$menus
         }
     }
 
+    /**
+     * Whether this menu's source item list already leaves out anchors that sit
+     * outside the link cluster. When it does, the block side must not add them
+     * back from a carrier group's siblings or the two sides double-disagree.
+     */
+    private function sourceMenuExcludesOutsideAnchors(DOMElement $element): bool
+    {
+        // A chrome-bearing landmark takes its items from the signaled containers
+        // alone, which leaves out every direct-child anchor by construction.
+        if ( $this->hasSourceNavigationChrome($element) ) {
+            return true;
+        }
+
+        if ( ! $this->hasDirectNavigationBrandOrAction($element) ) {
+            return false;
+        }
+
+        foreach ( $element->childNodes as $child ) {
+            if ( $child instanceof DOMElement
+                && in_array(strtolower($child->tagName), array( 'ul', 'ol' ), true)
+                && array() !== $this->sourceNavigationMenuItems($child)
+            ) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /**
      * @return array<int, array<string, string>>
      */
@@ -444,15 +474,16 @@ private function isSourceNavigationChromeAnchor(DOMElement $anchor): bool
     private function blockNavigationMenus(array $blocks): array
     {
         $menus = array();
-        $this->collectBlockNavigationMenus($blocks, 'blocks', $menus);
+        $this->collectBlockNavigationMenus($blocks, 'blocks', $menus, array());
         return $menus;
     }
 
     /**
      * @param array<int, array<string, mixed>> $blocks
      * @param array<int, array<string, mixed>> $menus
+     * @param array<int, array<string, mixed>> $siblings
      */
-    private function collectBlockNavigationMenus(array $blocks, string $path, array &$menus): void
+    private function collectBlockNavigationMenus(array $blocks, string $path, array &$menus, array $siblings): void
     {
         foreach ( $blocks as $index => $block ) {
             if ( ! is_array($block) ) {
@@ -468,11 +499,131 @@ private function collectBlockNavigationMenus(array $blocks, string $path, array
                     'represented_as_core_navigation' => true,
                     'item_count' => count($items),
                     'items' => $items,
+                    'carried_sibling_items' => $this->carriedNavigationSiblingItems($siblings, $index),
                 );
             }
 
             if ( ! empty($block['innerBlocks']) && is_array($block['innerBlocks']) ) {
-                $this->collectBlockNavigationMenus($block['innerBlocks'], $blockPath . '.innerBlocks', $menus);
+                $childSiblings = 'core/group' === ($block['blockName'] ?? '') && 'nav' === strtolower((string) ($block['attrs']['tagName'] ?? ''))
+                    ? $block['innerBlocks']
+                    : array();
+                $this->collectBlockNavigationMenus($block['innerBlocks'], $blockPath . '.innerBlocks', $menus, $childSiblings);
+            }
+        }
+    }
+
+    /**
+     * A navigation whose landmark is a core/group{tagName:"nav"} carrier shares
+     * that landmark with blocks hoisted out of the menu — a branding anchor, for
+     * instance. The source side counts every anchor under the landmark, so those
+     * hoisted links belong to this menu's item list too; otherwise a faithful
+     * hoist reads as content loss. Counting them here rather than excluding them
+     * on the source side keeps a brand that goes missing entirely detectable.
+     *
+     * @param array<int, array<string, mixed>> $siblings
+     * @return array{before: array<int, array<string, string>>, after: array<int, array<string, string>>}
+     */
+    private function carriedNavigationSiblingItems(array $siblings, int $navigationIndex): array
+    {
+        if ( array() === $siblings ) {
+            return array( 'before' => array(), 'after' => array() );
+        }
+
+        $before = array();
+        $after = array();
+        foreach ( $siblings as $siblingIndex => $sibling ) {
+            if ( ! is_array($sibling) || $siblingIndex === $navigationIndex || 'core/navigation' === ($sibling['blockName'] ?? '') ) {
+                continue;
+            }
+
+            $siblingItems = array();
+            $this->collectBlockAnchorItems(array( $sibling ), $siblingItems);
+            if ( array() === $siblingItems ) {
+                continue;
+            }
+
+            if ( $siblingIndex < $navigationIndex ) {
+                $before = array_merge($before, $siblingItems);
+                continue;
+            }
+
+            $after = array_merge($after, $siblingItems);
+        }
+
+        return array( 'before' => $before, 'after' => $after );
+    }
+
+    /**
+     * Anchor label/url pairs carried inside a block's rich text or link
+     * attributes, in document order, shaped to match the source item records.
+     *
+     * @param array<int, array<string, mixed>> $blocks
+     * @param array<int, array<string, string>> $items
+     */
+    private function collectBlockAnchorItems(array $blocks, array &$items): void
+    {
+        foreach ( $blocks as $block ) {
+            if ( ! is_array($block) ) {
+                continue;
+            }
+
+            $attrs = is_array($block['attrs'] ?? null) ? $block['attrs'] : array();
+
+            // Saved markup carries the anchor for blocks whose rich text is not
+            // mirrored into an attribute — a synthetic paragraph wrapping a link,
+            // for instance — so read both and de-duplicate by label+url below.
+            $candidates = array();
+            foreach ( array( 'content', 'text', 'value', 'caption' ) as $attribute ) {
+                if ( isset($attrs[$attribute]) && is_string($attrs[$attribute]) ) {
+                    $candidates[] = $attrs[$attribute];
+                }
+            }
+            if ( isset($block['innerHTML']) && is_string($block['innerHTML']) ) {
+                $candidates[] = $block['innerHTML'];
+            }
+
+            $seen = array();
+            foreach ( $candidates as $markup ) {
+                if ( ! str_contains($markup, '<a') ) {
+                    continue;
+                }
+
+                if ( preg_match_all('/<a\b[^>]*\bhref\s*=\s*(["\'])(.*?)\1[^>]*>(.*?)<\/a>/is', $markup, $matches, PREG_SET_ORDER) ) {
+                    foreach ( $matches as $match ) {
+                        $label = $this->normalizedNavigationLabel($match[3]);
+                        if ( '' === $label ) {
+                            continue;
+                        }
+
+                        $item = array(
+                            'label' => $label,
+                            'url' => $this->safeNavigationUrl(html_entity_decode($match[2], ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')),
+                        );
+                        $key = $item['label'] . "\0" . $item['url'];
+                        if ( isset($seen[$key]) ) {
+                            continue;
+                        }
+
+                        $seen[$key] = true;
+                        $items[] = $item;
+                    }
+                }
+            }
+
+            // core/button keeps its destination in `url` and its label in `text`
+            // rather than in anchor markup.
+            if ( 'core/button' === ($block['blockName'] ?? '') && isset($attrs['url']) ) {
+                $label = $this->normalizedNavigationLabel((string) ($attrs['text'] ?? ''));
+                if ( '' !== $label ) {
+                    $items[] = array(
+                        'label' => $label,
+                        'url' => $this->safeNavigationUrl((string) $attrs['url']),
+                    );
+                }
+            }
+
+            if ( ! empty($block['innerBlocks']) && is_array($block['innerBlocks']) ) {
+                $this->collectBlockAnchorItems($block['innerBlocks'], $items);
             }
         }
     }
@@ -583,6 +734,21 @@ private function semanticParityFindings(array $sourceLandmarks, array $blockLand
 
             $sourceItems = is_array($sourceMenu['items'] ?? null) ? array_values($sourceMenu['items']) : array();
             $blockItems = is_array($blockMenu['items'] ?? null) ? array_values($blockMenu['items']) : array();
+
+            // A carrier group holds blocks hoisted out of the menu beside it. The
+            // source side counts their anchors under the landmark unless it has
+            // already excluded outside anchors itself, so only add them here when
+            // it has not — otherwise the same anchors would be counted on one
+            // side and deliberately dropped on the other.
+            if ( true !== ($sourceMenu['excludes_outside_anchors'] ?? false) ) {
+                $carried = is_array($blockMenu['carried_sibling_items'] ?? null) ? $blockMenu['carried_sibling_items'] : array();
+                $blockItems = array_merge(
+                    is_array($carried['before'] ?? null) ? $carried['before'] : array(),
+                    $blockItems,
+                    is_array($carried['after'] ?? null) ? $carried['after'] : array()
+                );
+            }
+
             if ( count($sourceItems) !== count($blockItems) ) {
                 $findings[] = array(
                     'code' => 'navigation_item_count_mismatch',
diff --git a/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json b/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
index 8fd080a3..b62d0217 100644
--- a/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
+++ b/php-transformer/tests/fixtures/parity/html-nav-brand-anchor-hoist.json
@@ -85,6 +85,11 @@
       "assert": "not_contains",
       "value": "anchorClassName"
     },
+    {
+      "path": "source_reports.semantic_parity.status",
+      "assert": "equals",
+      "value": "pass"
+    },
     {
       "path": "serialized_blocks",
       "assert": "contains",

From ceca1b9f09057bdfeb5731ca5e271171185f7000 Mon Sep 17 00:00:00 2001
From: Matthew Batchelder <borkweb@gmail.com>
Date: Mon, 17 Aug 2026 07:50:38 -0700
Subject: [PATCH 8/8] fix(transformer): count a hoisted brand anchor once in
 navigation parity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
Correct the carried-item accounting added in 9d947f5b so a brand anchor hoisted beside a promoted navigation block is counted exactly once, and so the published parity record shows the same item list the comparison used. Pin both behaviours in the navigation hoist contract test.

## Why
Three defects sat in the carried-item collector. A brand that converts to a button nests the same anchor in two levels of saved markup — the `core/buttons` wrapper and its `core/button` child — because the collector reset its de-duplication set per markup candidate rather than per sibling subtree, it counted that anchor twice and raised a false `navigation_item_count_mismatch`. Separately, the fold happened inside the comparison loop only, so a published block menu could report `item_count` 5 beside a source menu of 6 while the report's own status said `pass`, and the internal `carried_sibling_items` key leaked into the published payload. A parity report that contradicts itself is worse than one that reports a mismatch: consumers reading the record cannot tell which number to trust.

## How
Thread a `$seen` set through `collectBlockAnchorItems()` so de-duplication spans a sibling's whole subtree instead of restarting at each markup candidate, keyed on label plus URL. Scope stays per sibling, because two siblings that genuinely link to the same place are two anchors on the source side too. Move the fold upstream into `withCarriedItemsResolved()`, which rewrites `items` and `item_count` on the block menu record before publication and drops the internal key, leaving the comparison loop to compare the two item lists directly. The existing skip — a source landmark that already excludes outside anchors, whether through mobile chrome or a brand-plus-CTA pairing — carries over unchanged, so neither side counts anchors the other deliberately drops.

## Testing
- [ ] `cd php-transformer && composer test:unit` — 27 suites, 806 assertions
- [ ] `cd php-transformer && composer test` — full suite including 278 parity fixtures
- [ ] `cd php-transformer && php tests/contract/run.php`
---
 .../Diagnostics/SemanticParityReporter.php    | 79 +++++++++++++------
 .../unit/navigation-brand-anchor-hoist.php    | 46 +++++++++++
 2 files changed, 101 insertions(+), 24 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php b/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
index eeda7911..41795628 100644
--- a/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
+++ b/php-transformer/src/HtmlToBlocks/Diagnostics/SemanticParityReporter.php
@@ -49,7 +49,7 @@ public function report(DOMElement $body, array $blocks, array $sourceProvenance,
         $sourceLandmarks = $this->sourceLandmarkReport($body);
         $blockLandmarks = $this->blockLandmarkReport($blocks, $sourceProvenance, $sourceLandmarks);
         $sourceMenus = $this->sourceNavigationMenus($body);
-        $blockMenus = $this->blockNavigationMenus($blocks);
+        $blockMenus = $this->withCarriedItemsResolved($this->blockNavigationMenus($blocks), $sourceMenus);
         $findings = $this->semanticParityFindings($sourceLandmarks, $blockLandmarks, $sourceMenus, $blockMenus);
         $findings = array_merge(
             $findings,
@@ -77,6 +77,44 @@ public function report(DOMElement $body, array $blocks, array $sourceProvenance,
         );
     }
 
+    /**
+     * Fold each carrier's hoisted links into the menu they belong to, so the
+     * published record shows the same item list the parity comparison uses.
+     * Leaving the two out of step would publish a menu counted as 5 beside a
+     * source menu of 6 while reporting parity as a pass.
+     *
+     * The fold is skipped when the paired source menu already leaves outside
+     * anchors out of its own list — a landmark bearing mobile chrome, or one
+     * holding both a brand and a CTA beside its list — because then neither side
+     * counts them.
+     *
+     * @param array<int, array<string, mixed>> $blockMenus
+     * @param array<int, array<string, mixed>> $sourceMenus
+     * @return array<int, array<string, mixed>>
+     */
+    private function withCarriedItemsResolved(array $blockMenus, array $sourceMenus): array
+    {
+        foreach ( $blockMenus as $index => $blockMenu ) {
+            $carried = is_array($blockMenu['carried_sibling_items'] ?? null) ? $blockMenu['carried_sibling_items'] : array();
+            unset($blockMenus[$index]['carried_sibling_items']);
+
+            if ( array() === $carried || true === ($sourceMenus[$index]['excludes_outside_anchors'] ?? false) ) {
+                continue;
+            }
+
+            $items = array_merge(
+                is_array($carried['before'] ?? null) ? $carried['before'] : array(),
+                is_array($blockMenu['items'] ?? null) ? array_values($blockMenu['items']) : array(),
+                is_array($carried['after'] ?? null) ? $carried['after'] : array()
+            );
+
+            $blockMenus[$index]['item_count'] = count($items);
+            $blockMenus[$index]['items'] = $items;
+        }
+
+        return array_values($blockMenus);
+    }
+
     /**
      * @return array{counts: array<string, int>, selectors: array<string, array<int, string>>}
      */
@@ -536,8 +574,14 @@ private function carriedNavigationSiblingItems(array $siblings, int $navigationI
                 continue;
             }
 
+            // One anchor can appear in more than one level of a block's saved
+            // markup — a core/buttons wrapper and its core/button child both
+            // carry it — so de-duplicate across each sibling's whole subtree.
+            // Scope is per sibling: two siblings that genuinely link to the same
+            // place are two anchors on the source side as well.
             $siblingItems = array();
-            $this->collectBlockAnchorItems(array( $sibling ), $siblingItems);
+            $seen = array();
+            $this->collectBlockAnchorItems(array( $sibling ), $siblingItems, $seen);
             if ( array() === $siblingItems ) {
                 continue;
             }
@@ -559,8 +603,9 @@ private function carriedNavigationSiblingItems(array $siblings, int $navigationI
      *
      * @param array<int, array<string, mixed>> $blocks
      * @param array<int, array<string, string>> $items
+     * @param array<string, true> $seen
      */
-    private function collectBlockAnchorItems(array $blocks, array &$items): void
+    private function collectBlockAnchorItems(array $blocks, array &$items, array &$seen): void
     {
         foreach ( $blocks as $block ) {
             if ( ! is_array($block) ) {
@@ -582,7 +627,6 @@ private function collectBlockAnchorItems(array $blocks, array &$items): void
                 $candidates[] = $block['innerHTML'];
             }
 
-            $seen = array();
             foreach ( $candidates as $markup ) {
                 if ( ! str_contains($markup, '<a') ) {
                     continue;
@@ -614,16 +658,15 @@ private function collectBlockAnchorItems(array $blocks, array &$items): void
             // rather than in anchor markup.
             if ( 'core/button' === ($block['blockName'] ?? '') && isset($attrs['url']) ) {
                 $label = $this->normalizedNavigationLabel((string) ($attrs['text'] ?? ''));
-                if ( '' !== $label ) {
-                    $items[] = array(
-                        'label' => $label,
-                        'url' => $this->safeNavigationUrl((string) $attrs['url']),
-                    );
+                $url = $this->safeNavigationUrl((string) $attrs['url']);
+                if ( '' !== $label && ! isset($seen[$label . "\0" . $url]) ) {
+                    $seen[$label . "\0" . $url] = true;
+                    $items[] = array( 'label' => $label, 'url' => $url );
                 }
             }
 
             if ( ! empty($block['innerBlocks']) && is_array($block['innerBlocks']) ) {
-                $this->collectBlockAnchorItems($block['innerBlocks'], $items);
+                $this->collectBlockAnchorItems($block['innerBlocks'], $items, $seen);
             }
         }
     }
@@ -733,22 +776,10 @@ private function semanticParityFindings(array $sourceLandmarks, array $blockLand
             }
 
             $sourceItems = is_array($sourceMenu['items'] ?? null) ? array_values($sourceMenu['items']) : array();
+            // Carrier siblings were already folded into `items` upstream, so both
+            // sides are directly comparable here.
             $blockItems = is_array($blockMenu['items'] ?? null) ? array_values($blockMenu['items']) : array();
 
-            // A carrier group holds blocks hoisted out of the menu beside it. The
-            // source side counts their anchors under the landmark unless it has
-            // already excluded outside anchors itself, so only add them here when
-            // it has not — otherwise the same anchors would be counted on one
-            // side and deliberately dropped on the other.
-            if ( true !== ($sourceMenu['excludes_outside_anchors'] ?? false) ) {
-                $carried = is_array($blockMenu['carried_sibling_items'] ?? null) ? $blockMenu['carried_sibling_items'] : array();
-                $blockItems = array_merge(
-                    is_array($carried['before'] ?? null) ? $carried['before'] : array(),
-                    $blockItems,
-                    is_array($carried['after'] ?? null) ? $carried['after'] : array()
-                );
-            }
-
             if ( count($sourceItems) !== count($blockItems) ) {
                 $findings[] = array(
                     'code' => 'navigation_item_count_mismatch',
diff --git a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
index 2813cbe3..8a79e3a4 100644
--- a/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
+++ b/php-transformer/tests/unit/navigation-brand-anchor-hoist.php
@@ -230,6 +230,52 @@
     json_encode($bareLinkNavigations[0]['attrs'] ?? array())
 );
 
+// -- Semantic parity must read the hoist as faithful, not as content loss: the
+// brand's link belongs to the menu's item list even though it now sits beside the
+// navigation block. A brand that converts to a button nests the same anchor in two
+// levels of saved markup, so it must still be counted exactly once.
+$carrierParity = static function (array $result): array {
+    $report = $result['source_reports']['semantic_parity'] ?? array();
+    $menus = $report['navigation_menus'] ?? array();
+
+    return array(
+        'status' => (string) ($report['status'] ?? ''),
+        'source' => (int) ($menus['source'][0]['item_count'] ?? -1),
+        'blocks' => (int) ($menus['blocks'][0]['item_count'] ?? -1),
+        'findings' => count(is_array($report['findings'] ?? null) ? $report['findings'] : array()),
+    );
+};
+
+$lockupParity = $carrierParity($unlistedBrand);
+$assert(
+    'pass' === $lockupParity['status'] && 0 === $lockupParity['findings'],
+    'hoisted brand: semantic parity reads the carrier as faithful',
+    json_encode($lockupParity)
+);
+$assert(
+    $lockupParity['source'] === $lockupParity['blocks'],
+    'hoisted brand: the reported block item count matches the source item count',
+    json_encode($lockupParity)
+);
+
+$buttonBrandParity = $carrierParity($transform(
+    '<style>nav{display:flex;gap:20px}'
+    . '.mark{display:inline-block;padding:10px 18px;background:#12151a;color:#fff;border-radius:6px}'
+    . '.navlinks{list-style:none;display:flex;gap:16px;margin:0;padding:0}</style>'
+    . '<nav aria-label="Primary"><a class="mark" href="/"><span>Harbor</span></a>'
+    . '<ul class="navlinks"><li><a href="/a/">A</a></li><li><a href="/b/">B</a></li></ul></nav>'
+));
+$assert(
+    'pass' === $buttonBrandParity['status'] && 0 === $buttonBrandParity['findings'],
+    'brand that converts to a button: semantic parity still reads the carrier as faithful',
+    json_encode($buttonBrandParity)
+);
+$assert(
+    3 === $buttonBrandParity['blocks'] && $buttonBrandParity['source'] === $buttonBrandParity['blocks'],
+    'brand that converts to a button: its anchor is counted once, not once per markup level',
+    json_encode($buttonBrandParity)
+);
+
 // -- Control: a menu with no branding anchor keeps today's single navigation block.
 $plainMenu = $transform(
     '<style>.main-nav{display:flex;gap:1rem}</style>'