From 4b963c9eee0723dee426b405047c5ec2ce70cbad Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@a8c.com>
Date: Mon, 13 Jul 2026 21:10:20 -0400
Subject: [PATCH 1/2] Refine Figma DOM box classification

---
 .../scripts/figma-fixture-matrix-quality.php  | 40 +++++++++++-
 .../src/Html/StaticHtmlEmitter.php            | 11 ++++
 .../tests/contract/FixtureMatrixContract.php  | 63 +++++++++++++++++++
 .../tests/contract/HtmlValidityContract.php   | 17 ++---
 .../tests/contract/TextLayoutContract.php     |  8 +--
 figma-transformer/tests/contract/run.php      |  2 +-
 .../visual-parity/bin/dom-box-provider.mjs    | 17 ++++-
 .../tools/visual-parity/tests/smoke.mjs       |  5 +-
 8 files changed, 147 insertions(+), 16 deletions(-)

diff --git a/figma-transformer/scripts/figma-fixture-matrix-quality.php b/figma-transformer/scripts/figma-fixture-matrix-quality.php
index 1d527a6b..7d4c42fd 100644
--- a/figma-transformer/scripts/figma-fixture-matrix-quality.php
+++ b/figma-transformer/scripts/figma-fixture-matrix-quality.php
@@ -392,7 +392,7 @@ function matrix_analyze_dom_box_entrypoint(array $entrypoint): array
             $findings[] = matrix_dom_box_finding('dom_viewport_width_leak', $node, array('width' => $width, 'right' => $right, 'viewport_width' => $viewportWidth));
         }
 
-        if ( $width <= 1.0 || $height <= 1.0 ) {
+        if ( matrix_dom_box_is_unexpected_collapse($element, $width, $height) ) {
             $summary['dom_collapsed_box_count']++;
             $findings[] = matrix_dom_box_finding('dom_collapsed_box', $node, array('width' => $width, 'height' => $height));
         }
@@ -481,17 +481,55 @@ function matrix_dom_box_number(array $values, string $key, float $fallback): flo
     return isset($values[$key]) && is_numeric($values[$key]) ? (float) $values[$key] : $fallback;
 }
 
+/**
+ * @param array<string, mixed> $element
+ */
+function matrix_dom_box_is_unexpected_collapse(array $element, float $width, float $height): bool
+{
+    $collapsedWidth = $width <= 1.0;
+    $collapsedHeight = $height <= 1.0;
+    if ( ! $collapsedWidth && ! $collapsedHeight ) {
+        return false;
+    }
+
+    $source = is_array($element['source'] ?? null) ? $element['source'] : array();
+    $sourceType = isset($source['node_type']) && is_scalar($source['node_type']) ? strtoupper(trim((string) $source['node_type'])) : '';
+    $isVisibleGeometry = in_array($sourceType, array('LINE', 'VECTOR'), true)
+        && true === ($element['visibility']['visible'] ?? null);
+    if ( ! $isVisibleGeometry || $collapsedWidth === $collapsedHeight ) {
+        return true;
+    }
+
+    $orthogonalDimension = $collapsedWidth ? $height : $width;
+    if ( $orthogonalDimension <= 1.0 ) {
+        return true;
+    }
+
+    $sourceDimensions = is_array($source['visual_dimensions'] ?? null) ? $source['visual_dimensions'] : array();
+    $collapsedAxis = $collapsedWidth ? 'width' : 'height';
+    $sourceAxis = isset($sourceDimensions[$collapsedAxis]) && is_numeric($sourceDimensions[$collapsedAxis])
+        ? (float) $sourceDimensions[$collapsedAxis]
+        : null;
+    $domAxis = $collapsedWidth ? $width : $height;
+
+    // A one-axis line is expected; collapsed geometry must still agree with source evidence.
+    return $domAxis <= 1.0 && (null === $sourceAxis || abs($sourceAxis - $domAxis) > 0.5);
+}
+
 /**
  * @param array<string, mixed> $element
  * @return array<string, mixed>
  */
 function matrix_dom_box_node_summary(array $element): array
 {
+    $source = is_array($element['source'] ?? null) ? $element['source'] : array();
     return array_filter(array(
         'id' => isset($element['node_id']) && is_scalar($element['node_id']) ? (string) $element['node_id'] : null,
         'name' => isset($element['node_name']) && is_scalar($element['node_name']) ? (string) $element['node_name'] : null,
         'selector' => isset($element['selector']) && is_scalar($element['selector']) ? (string) $element['selector'] : null,
         'tag' => isset($element['tag']) && is_scalar($element['tag']) ? (string) $element['tag'] : null,
+        'source_node_type' => isset($source['node_type']) && is_scalar($source['node_type']) ? (string) $source['node_type'] : null,
+        'source_visual_dimensions' => is_array($source['visual_dimensions'] ?? null) ? $source['visual_dimensions'] : null,
     ), static fn (mixed $value): bool => null !== $value && '' !== $value);
 }
 
diff --git a/figma-transformer/src/Html/StaticHtmlEmitter.php b/figma-transformer/src/Html/StaticHtmlEmitter.php
index 2f54d194..235733eb 100644
--- a/figma-transformer/src/Html/StaticHtmlEmitter.php
+++ b/figma-transformer/src/Html/StaticHtmlEmitter.php
@@ -1055,6 +1055,17 @@ private function emitNode(array $node, array &$cssRules, array &$diagnostics, ar
         $layoutIntent = $this->layoutIntentClassifier()->layoutIntent($node, $parentNode);
         $elementClassName = null === $imageElement ? $className : $className . ' figma-image-asset';
         $attributes = sprintf(' class="%1$s" data-figma-node-id="%2$s" data-figma-node-name="%3$s"', $elementClassName, $id, $attributeName);
+        $attributes .= ' data-source-node-type="' . $this->sanitizeAttribute($type) . '"';
+        $sourceVisualBox = is_array($node['box'] ?? null) ? $node['box'] : array();
+        foreach ( array('width', 'height') as $dimension ) {
+            if ( ! isset($sourceVisualBox[$dimension]) && isset($node[$dimension]) && is_numeric($node[$dimension]) ) {
+                $sourceVisualBox[$dimension] = $node[$dimension];
+            }
+        }
+        if ( isset($sourceVisualBox['width'], $sourceVisualBox['height']) && is_numeric($sourceVisualBox['width']) && is_numeric($sourceVisualBox['height']) ) {
+            $attributes .= ' data-source-visual-width="' . $this->sanitizeAttribute((string) $sourceVisualBox['width']) . '"';
+            $attributes .= ' data-source-visual-height="' . $this->sanitizeAttribute((string) $sourceVisualBox['height']) . '"';
+        }
         $semanticRole = $this->semanticRoleMetadata($node, $tag, $type, $name);
         if ( null !== $semanticRole ) {
             $attributes .= ' data-figma-semantic-role="' . $this->sanitizeAttribute($semanticRole) . '"';
diff --git a/figma-transformer/tests/contract/FixtureMatrixContract.php b/figma-transformer/tests/contract/FixtureMatrixContract.php
index dfa423f5..76580524 100644
--- a/figma-transformer/tests/contract/FixtureMatrixContract.php
+++ b/figma-transformer/tests/contract/FixtureMatrixContract.php
@@ -426,6 +426,53 @@ function blocks_engine_figma_transformer_run_fixture_matrix_contract(callable $a
             ),
         ),
     ), '/tmp/dom-boxes.json');
+    $collapseClassificationQuality = matrix_analyze_dom_box_report(array(
+        'entrypoints' => array(
+            array(
+                'page_path' => '/classification.html',
+                'viewport' => array('width' => 1440, 'height' => 900),
+                'dom_css_loaded' => true,
+                'dom_capture_valid' => true,
+                'elements' => array(
+                    array(
+                        'node_id' => 'line:separator',
+                        'tag' => 'svg',
+                        'boundingClientRect' => array('left' => 0, 'right' => 240, 'top' => 0, 'bottom' => 1, 'width' => 240, 'height' => 1),
+                        'visibility' => array('visible' => true),
+                        'source' => array('node_type' => 'LINE', 'visual_dimensions' => array('width' => 240, 'height' => 1)),
+                    ),
+                    array(
+                        'node_id' => 'vector:tail',
+                        'tag' => 'svg',
+                        'boundingClientRect' => array('left' => 0, 'right' => 0.1, 'top' => 10, 'bottom' => 90, 'width' => 0.1, 'height' => 80),
+                        'visibility' => array('visible' => true),
+                        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 0.1, 'height' => 80)),
+                    ),
+                    array(
+                        'node_id' => 'text:collapsed',
+                        'tag' => 'p',
+                        'boundingClientRect' => array('left' => 0, 'right' => 0, 'top' => 100, 'bottom' => 124, 'width' => 0, 'height' => 24),
+                        'visibility' => array('visible' => false),
+                        'source' => array('node_type' => 'TEXT', 'visual_dimensions' => array('width' => 180, 'height' => 24)),
+                    ),
+                    array(
+                        'node_id' => 'frame:collapsed',
+                        'tag' => 'section',
+                        'boundingClientRect' => array('left' => 0, 'right' => 320, 'top' => 130, 'bottom' => 130, 'width' => 320, 'height' => 0),
+                        'visibility' => array('visible' => false),
+                        'source' => array('node_type' => 'FRAME', 'visual_dimensions' => array('width' => 320, 'height' => 120)),
+                    ),
+                    array(
+                        'node_id' => 'vector:unexpected-collapse',
+                        'tag' => 'svg',
+                        'boundingClientRect' => array('left' => 0, 'right' => 1, 'top' => 140, 'bottom' => 200, 'width' => 1, 'height' => 60),
+                        'visibility' => array('visible' => true),
+                        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 8, 'height' => 60)),
+                    ),
+                ),
+            ),
+        ),
+    ), '/tmp/dom-box-collapse-classification.json');
     $invalidDomBoxQuality = matrix_analyze_dom_box_report(array(
         'schema' => 'homeboy/static-artifact-dom-boxes/v1',
         'entrypoints' => array(
@@ -607,6 +654,22 @@ function blocks_engine_figma_transformer_run_fixture_matrix_contract(callable $a
     $assert(1 === ($domBoxQuality['summary']['dom_viewport_width_leak_count'] ?? null), 'fixture-matrix-dom-box-quality-viewport-width-leak');
     $assert(1 === ($domBoxQuality['summary']['dom_huge_vertical_spacing_count'] ?? null), 'fixture-matrix-dom-box-quality-huge-vertical-spacing');
     $assert(1 === ($domBoxQuality['summary']['dom_collapsed_box_count'] ?? null), 'fixture-matrix-dom-box-quality-collapsed-box');
+    $assert(3 === ($collapseClassificationQuality['summary']['dom_collapsed_box_count'] ?? null), 'fixture-matrix-dom-box-classification-warns-for-genuine-collapse');
+    $collapseFindingIds = array_map(
+        static fn (array $finding): string => (string) ($finding['node']['id'] ?? ''),
+        $collapseClassificationQuality['pages'][0]['findings'] ?? array()
+    );
+    $assert(! in_array('line:separator', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-allows-visible-one-pixel-line');
+    $assert(! in_array('vector:tail', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-allows-source-faithful-subpixel-vector');
+    $assert(in_array('text:collapsed', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-collapsed-text');
+    $assert(in_array('frame:collapsed', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-collapsed-container');
+    $assert(in_array('vector:unexpected-collapse', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-source-mismatched-vector');
+    $unexpectedVectorFinding = array_values(array_filter(
+        $collapseClassificationQuality['pages'][0]['findings'] ?? array(),
+        static fn (array $finding): bool => 'vector:unexpected-collapse' === ($finding['node']['id'] ?? null)
+    ))[0] ?? array();
+    $assert('VECTOR' === ($unexpectedVectorFinding['node']['source_node_type'] ?? null), 'fixture-matrix-dom-box-finding-preserves-source-node-type');
+    $assert(8 === ($unexpectedVectorFinding['node']['source_visual_dimensions']['width'] ?? null), 'fixture-matrix-dom-box-finding-preserves-source-visual-dimensions');
     $assert(1 === ($domBoxQuality['summary']['dom_offscreen_box_count'] ?? null), 'fixture-matrix-dom-box-quality-offscreen-box');
     $assert(2 === ($domBoxQuality['summary']['dom_missing_node_id_box_count'] ?? null), 'fixture-matrix-dom-box-quality-missing-node-id-boxes');
     $assert(false === ($invalidDomBoxQuality['summary']['dom_css_loaded'] ?? null), 'fixture-matrix-invalid-dom-box-css-not-loaded');
diff --git a/figma-transformer/tests/contract/HtmlValidityContract.php b/figma-transformer/tests/contract/HtmlValidityContract.php
index 257816d0..cb21a8f3 100644
--- a/figma-transformer/tests/contract/HtmlValidityContract.php
+++ b/figma-transformer/tests/contract/HtmlValidityContract.php
@@ -188,18 +188,19 @@ function blocks_engine_figma_transformer_run_html_validity_contract(callable $as
     $links = $result['source_report']['transform_diagnostics']['links'] ?? array();
     $assert(str_contains($html, '<main class="figma-root" data-figma-root="true" data-static-artifact-capture="ignore" data-page-title="Home Page" aria-label="Home Page" data-page-path="index.html"'), 'html-validity-document-root-carries-page-legibility-metadata');
     $assert(str_contains($html, 'data-static-artifact-capture="ignore"'), 'html-validity-document-root-ignored-by-dom-box-capture');
-    $assert(str_contains($html, 'data-figma-node-id="validity:nav" data-figma-node-name="Navigation" data-figma-semantic-role="nav"'), 'html-validity-nav-carries-semantic-role-metadata');
-    $assert(str_contains($html, 'data-figma-node-id="validity:services" data-figma-node-name="Services Section" data-figma-semantic-role="services"'), 'html-validity-services-section-carries-semantic-role-metadata');
-    $assert(str_contains($html, 'data-figma-node-id="validity:pricing" data-figma-node-name="Pricing" data-figma-semantic-role="pricing"'), 'html-validity-pricing-section-carries-semantic-role-metadata');
-    $assert(str_contains($html, 'data-figma-node-id="validity:contact-map" data-figma-node-name="Contact Map" data-figma-semantic-role="map"'), 'html-validity-map-section-carries-semantic-role-metadata');
-    $assert(str_contains($html, 'data-figma-node-id="validity:final-cta" data-figma-node-name="Final CTA" data-figma-semantic-role="cta"'), 'html-validity-cta-section-carries-semantic-role-metadata');
+    $assert(1 === preg_match('/data-figma-node-id="validity:news-item"[^>]* data-source-node-type="FRAME" data-source-visual-width="80" data-source-visual-height="32"/', $html), 'html-validity-node-preserves-source-dom-quality-evidence');
+    $assert(1 === preg_match('/data-figma-node-id="validity:nav" data-figma-node-name="Navigation"[^>]* data-figma-semantic-role="nav"/', $html), 'html-validity-nav-carries-semantic-role-metadata');
+    $assert(1 === preg_match('/data-figma-node-id="validity:services" data-figma-node-name="Services Section"[^>]* data-figma-semantic-role="services"/', $html), 'html-validity-services-section-carries-semantic-role-metadata');
+    $assert(1 === preg_match('/data-figma-node-id="validity:pricing" data-figma-node-name="Pricing"[^>]* data-figma-semantic-role="pricing"/', $html), 'html-validity-pricing-section-carries-semantic-role-metadata');
+    $assert(1 === preg_match('/data-figma-node-id="validity:contact-map" data-figma-node-name="Contact Map"[^>]* data-figma-semantic-role="map"/', $html), 'html-validity-map-section-carries-semantic-role-metadata');
+    $assert(1 === preg_match('/data-figma-node-id="validity:final-cta" data-figma-node-name="Final CTA"[^>]* data-figma-semantic-role="cta"/', $html), 'html-validity-cta-section-carries-semantic-role-metadata');
     $assert(str_contains($html, '<a class="figma-link" href="archive.html" data-figma-link-type="implicit-route"><div class="figma-node-validity-news-item-menu-item"'), 'html-validity-menu-item-container-linked');
-    $assert(str_contains($html, 'class="figma-node-validity-packed-nav-main-nav-links" data-figma-node-id="validity:packed-nav" data-figma-node-name="Main Nav Links"><a class="figma-link" href="archive.html" data-figma-link-type="implicit-route">News</a>      <a class="figma-link" href="page.html" data-figma-link-type="implicit-route">About</a>      <a class="figma-link" href="contact.html" data-figma-link-type="implicit-route">Contact</a>'), 'html-validity-packed-route-text-preserves-spacing-with-inline-links');
+    $assert(1 === preg_match('/class="figma-node-validity-packed-nav-main-nav-links" data-figma-node-id="validity:packed-nav" data-figma-node-name="Main Nav Links"[^>]*><a class="figma-link" href="archive\.html" data-figma-link-type="implicit-route">News<\/a>      <a class="figma-link" href="page\.html" data-figma-link-type="implicit-route">About<\/a>      <a class="figma-link" href="contact\.html" data-figma-link-type="implicit-route">Contact<\/a>/', $html), 'html-validity-packed-route-text-preserves-spacing-with-inline-links');
     $assert(! str_contains($html, '<a class="figma-link" href="archive.html" data-figma-link-type="implicit-route"><span class="figma-node-validity-news-text-text"'), 'html-validity-linked-menu-item-suppresses-descendant-anchor');
     $assert(1 === preg_match('/<a class="figma-link button" href="archive\.html" data-figma-link-type="implicit-route"><div class="[^"]*figma-node-validity-next-button-button/', $html), 'html-validity-linked-button-renders-structural-div');
     $assert(! str_contains($html, '<a class="figma-link button" href="archive.html" data-figma-link-type="implicit-route"><button'), 'html-validity-linked-button-not-anchor-wrapped-button');
-    $assert(str_contains($html, '<li class="figma-node-validity-footer-about-footer-text" data-figma-node-id="validity:footer-about" data-figma-node-name="Footer text"><a class="figma-link" href="page.html" data-figma-link-type="implicit-route">About</a></li>'), 'html-validity-linked-list-item-anchor-inside-li');
-    $assert(! str_contains($html, '<ul class="figma-node-validity-footer-links-frame-29" data-figma-node-id="validity:footer-links" data-figma-node-name="Frame 29"><a '), 'html-validity-list-has-no-direct-anchor-child');
+    $assert(1 === preg_match('/<li class="figma-node-validity-footer-about-footer-text" data-figma-node-id="validity:footer-about" data-figma-node-name="Footer text"[^>]*><a class="figma-link" href="page\.html" data-figma-link-type="implicit-route">About<\/a><\/li>/', $html), 'html-validity-linked-list-item-anchor-inside-li');
+    $assert(0 === preg_match('/<ul class="figma-node-validity-footer-links-frame-29" data-figma-node-id="validity:footer-links" data-figma-node-name="Frame 29"[^>]*><a /', $html), 'html-validity-list-has-no-direct-anchor-child');
     $assert(($links['implicit_route_links'] ?? 0) >= 3, 'html-validity-implicit-route-links-counted');
     $assert(($links['implicit_route_self_suppressed'] ?? 0) >= 1, 'html-validity-implicit-route-self-links-counted');
     $routeTargets = is_array($links['route_targets'] ?? null) ? $links['route_targets'] : array();
diff --git a/figma-transformer/tests/contract/TextLayoutContract.php b/figma-transformer/tests/contract/TextLayoutContract.php
index a000d0b1..8caff3ee 100644
--- a/figma-transformer/tests/contract/TextLayoutContract.php
+++ b/figma-transformer/tests/contract/TextLayoutContract.php
@@ -268,7 +268,7 @@ function blocks_engine_figma_transformer_run_text_layout_contract(callable $asse
     ));
     $orderedTextListHtml = $fileContent($orderedTextListResult, 'index.html');
     $orderedTextListCss = $fileContent($orderedTextListResult, 'style.css');
-    $assert(str_contains($orderedTextListHtml, '<ol class="figma-node-text-ordered-list-coverage-list" data-figma-node-id="text:ordered-list" data-figma-node-name="Coverage List" start="3">'), 'source-text-ordered-list-emits-ol-start');
+    $assert(1 === preg_match('/<ol class="figma-node-text-ordered-list-coverage-list" data-figma-node-id="text:ordered-list" data-figma-node-name="Coverage List"[^>]* start="3">/', $orderedTextListHtml), 'source-text-ordered-list-emits-ol-start');
     $assert(str_contains($orderedTextListHtml, '<li>Comprehensive News Coverage</li><li>In-Depth Reviews</li><li>Helpful Guides and Tutorials</li><li>Community Engagement</li>'), 'source-text-ordered-list-emits-list-items');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $orderedTextListHtml, 'ol', 1, 'source-text-ordered-list-single-ol');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $orderedTextListHtml, 'li', 4, 'source-text-ordered-list-li-count');
@@ -294,7 +294,7 @@ function blocks_engine_figma_transformer_run_text_layout_contract(callable $asse
     ));
     $bulletTextListHtml = $fileContent($bulletTextListResult, 'index.html');
     $bulletTextListCss = $fileContent($bulletTextListResult, 'style.css');
-    $assert(str_contains($bulletTextListHtml, '<ul class="figma-node-text-bullet-list-bullet-coverage-list" data-figma-node-id="text:bullet-list" data-figma-node-name="Bullet Coverage List"><li>Comprehensive News Coverage</li><li>In-Depth Reviews</li></ul>'), 'source-text-bullet-list-strips-embedded-marker-glyphs');
+    $assert(1 === preg_match('/<ul class="figma-node-text-bullet-list-bullet-coverage-list" data-figma-node-id="text:bullet-list" data-figma-node-name="Bullet Coverage List"[^>]*><li>Comprehensive News Coverage<\/li><li>In-Depth Reviews<\/li><\/ul>/', $bulletTextListHtml), 'source-text-bullet-list-strips-embedded-marker-glyphs');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $bulletTextListHtml, 'ul', 1, 'source-text-bullet-list-single-ul');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $bulletTextListHtml, 'li', 2, 'source-text-bullet-list-li-count');
     blocks_engine_figma_transformer_contract_assert_css_rule_contains($assert, $bulletTextListCss, '.figma-node-text-bullet-list-bullet-coverage-list', array('list-style:disc', 'padding-left:1.5em'), 'source-text-bullet-list-restores-marker-css');
@@ -332,7 +332,7 @@ function blocks_engine_figma_transformer_run_text_layout_contract(callable $asse
     ));
     $nestedRichTextListHtml = $fileContent($nestedRichTextListResult, 'index.html');
     $nestedRichTextListCss = $fileContent($nestedRichTextListResult, 'style.css');
-    $assert(str_contains($nestedRichTextListHtml, '<ol class="figma-node-text-nested-rich-list-nested-rich-coverage-list" data-figma-node-id="text:nested-rich-list" data-figma-node-name="Nested Rich Coverage List" start="2">'), 'source-text-nested-list-emits-root-ol-start');
+    $assert(1 === preg_match('/<ol class="figma-node-text-nested-rich-list-nested-rich-coverage-list" data-figma-node-id="text:nested-rich-list" data-figma-node-name="Nested Rich Coverage List"[^>]* start="2">/', $nestedRichTextListHtml), 'source-text-nested-list-emits-root-ol-start');
     $assert(str_contains($nestedRichTextListHtml, '<li>Intro item<ul style="list-style:disc;padding-left:1.5em"><li><span style="font-weight:700">Nested bold</span> note</li></ul></li><li>Final item</li>'), 'source-text-nested-list-emits-indent-and-rich-spans');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $nestedRichTextListHtml, 'ol', 1, 'source-text-nested-list-root-ol-count');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $nestedRichTextListHtml, 'ul', 1, 'source-text-nested-list-child-ul-count');
@@ -402,7 +402,7 @@ function blocks_engine_figma_transformer_run_text_layout_contract(callable $asse
         ),
     ));
     $explicitNewlineFalseListHtml = $fileContent($explicitNewlineFalseListResult, 'index.html');
-    $assert(str_contains($explicitNewlineFalseListHtml, '<ul class="figma-node-text-explicit-newline-false-list-explicit-newline-false-list" data-figma-node-id="text:explicit-newline-false-list" data-figma-node-name="Explicit Newline False List"><li>One</li><li>Two</li><li>Three</li></ul>'), 'source-text-explicit-newlines-keep-false-list-lines-separate');
+    $assert(1 === preg_match('/<ul class="figma-node-text-explicit-newline-false-list-explicit-newline-false-list" data-figma-node-id="text:explicit-newline-false-list" data-figma-node-name="Explicit Newline False List"[^>]*><li>One<\/li><li>Two<\/li><li>Three<\/li><\/ul>/', $explicitNewlineFalseListHtml), 'source-text-explicit-newlines-keep-false-list-lines-separate');
     blocks_engine_figma_transformer_contract_assert_tag_count($assert, $explicitNewlineFalseListHtml, 'li', 3, 'source-text-explicit-newlines-false-li-count');
 
     $derivedSoftWrapResult = blocks_engine_figma_transformer_transform_scenegraph(array(
diff --git a/figma-transformer/tests/contract/run.php b/figma-transformer/tests/contract/run.php
index 0b8ec32d..434620a7 100644
--- a/figma-transformer/tests/contract/run.php
+++ b/figma-transformer/tests/contract/run.php
@@ -3806,7 +3806,7 @@
     ),
 ), array('frame_id' => 'instance:placeholder-button'));
 $componentPlaceholderTextHtml = $fileContent($componentPlaceholderTextResult, 'index.html');
-$assert(str_contains($componentPlaceholderTextHtml, 'data-figma-node-id="instance:placeholder-button/component:placeholder-button-label" data-figma-node-name="Button label"></span>'), 'component-placeholder-button-label-hidden');
+$assert(1 === preg_match('/data-figma-node-id="instance:placeholder-button\/component:placeholder-button-label" data-figma-node-name="Button label"[^>]*><\/span>/', $componentPlaceholderTextHtml), 'component-placeholder-button-label-hidden');
 
 $unresolvedInstanceResult = blocks_engine_figma_transformer_transform_scenegraph(array(
     'name'  => 'Unresolved Component Instance Fixture',
diff --git a/php-transformer/tools/visual-parity/bin/dom-box-provider.mjs b/php-transformer/tools/visual-parity/bin/dom-box-provider.mjs
index 4b4132b5..c339c65e 100755
--- a/php-transformer/tools/visual-parity/bin/dom-box-provider.mjs
+++ b/php-transformer/tools/visual-parity/bin/dom-box-provider.mjs
@@ -4,6 +4,9 @@ const DEFAULT_VIEWPORT = { width: 1440, height: 900, device_scale_factor: 1 };
 const DEFAULT_NODE_ID_ATTR = 'data-figma-node-id';
 const DEFAULT_NODE_NAME_ATTRS = ['data-figma-node-name', 'data-figma-name'];
 const STATIC_ARTIFACT_CAPTURE_IGNORE_ATTR = 'data-static-artifact-capture';
+const SOURCE_NODE_TYPE_ATTR = 'data-source-node-type';
+const SOURCE_VISUAL_WIDTH_ATTR = 'data-source-visual-width';
+const SOURCE_VISUAL_HEIGHT_ATTR = 'data-source-visual-height';
 const ATTRIBUTE_NAME_PATTERN = /^[A-Za-z_:][-A-Za-z0-9_:.]*$/;
 const PLAYWRIGHT_SETUP_HELP = 'Install DOM capture dependencies with: npm ci --prefix php-transformer/tools/visual-parity && npm --prefix php-transformer/tools/visual-parity run install:browsers';
 const COMPUTED_STYLE_PROPERTIES = [
@@ -232,7 +235,7 @@ function printHelp() {
 }
 
 async function extractElements(page, pagePath, textSampleLimit, nodeIdAttr, nodeNameAttrs) {
-  return page.evaluate(({ pagePath: currentPagePath, limit, computedStyleProperties, nodeIdAttr: idAttr, nodeNameAttrs: nameAttrs, staticArtifactCaptureIgnoreAttr }) => {
+  return page.evaluate(({ pagePath: currentPagePath, limit, computedStyleProperties, nodeIdAttr: idAttr, nodeNameAttrs: nameAttrs, staticArtifactCaptureIgnoreAttr, sourceNodeTypeAttr, sourceVisualWidthAttr, sourceVisualHeightAttr }) => {
     function normalizeText(value) {
       return String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, limit);
     }
@@ -370,6 +373,8 @@ async function extractElements(page, pagePath, textSampleLimit, nodeIdAttr, node
       const computedStyle = serializeComputedStyle(element);
       const textSample = normalizeText(element.textContent);
       const textLength = fullTextLength(element.textContent);
+      const sourceWidth = Number.parseFloat(element.getAttribute(sourceVisualWidthAttr));
+      const sourceHeight = Number.parseFloat(element.getAttribute(sourceVisualHeightAttr));
       return {
         page_path: currentPagePath,
         node_id: nodeId,
@@ -382,6 +387,13 @@ async function extractElements(page, pagePath, textSampleLimit, nodeIdAttr, node
         text_metrics: serializeTextMetrics(element, computedStyle, textSample, textLength),
         asset_state: serializeAssetState(element, computedStyle),
         visibility: serializeVisibility(element, rect, computedStyle),
+        source: {
+          node_type: element.getAttribute(sourceNodeTypeAttr),
+          visual_dimensions: {
+            width: Number.isFinite(sourceWidth) ? sourceWidth : null,
+            height: Number.isFinite(sourceHeight) ? sourceHeight : null,
+          },
+        },
       };
     }
 
@@ -423,5 +435,8 @@ async function extractElements(page, pagePath, textSampleLimit, nodeIdAttr, node
     nodeIdAttr,
     nodeNameAttrs,
     staticArtifactCaptureIgnoreAttr: STATIC_ARTIFACT_CAPTURE_IGNORE_ATTR,
+    sourceNodeTypeAttr: SOURCE_NODE_TYPE_ATTR,
+    sourceVisualWidthAttr: SOURCE_VISUAL_WIDTH_ATTR,
+    sourceVisualHeightAttr: SOURCE_VISUAL_HEIGHT_ATTR,
   });
 }
diff --git a/php-transformer/tools/visual-parity/tests/smoke.mjs b/php-transformer/tools/visual-parity/tests/smoke.mjs
index 9e866041..48847265 100644
--- a/php-transformer/tools/visual-parity/tests/smoke.mjs
+++ b/php-transformer/tools/visual-parity/tests/smoke.mjs
@@ -58,7 +58,7 @@ await writeFile(domFixture, `<!doctype html><html><head><style>
     width: 120px;
     height: 24px;
   }
-</style></head><body><main class="hero" data-figma-node-id="12:34" data-figma-node-name="Hero">Hello world <img alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='2' height='3'%3E%3C/svg%3E"></main></body></html>`);
+</style></head><body><main class="hero" data-figma-node-id="12:34" data-figma-node-name="Hero" data-source-node-type="FRAME" data-source-visual-width="120" data-source-visual-height="24">Hello world <img alt="" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='2' height='3'%3E%3C/svg%3E"></main></body></html>`);
 await writeFile(domFixtureGeneric, `<!doctype html><html><head><style>
   body { margin: 0; }
   .hero { color: rgb(12, 34, 56); font-size: 20px; width: 120px; height: 24px; }
@@ -95,6 +95,9 @@ try {
   assert(domReport.entrypoints[0].stylesheet_status.body_margin === '0px', 'DOM provider captures body margin reset status');
   assert(domReport.entrypoints[0].elements[0].node_id === '12:34', 'DOM provider captures node id');
   assert(domReport.entrypoints[0].elements[0].node_name === 'Hero', 'DOM provider captures node name');
+  assert(domReport.entrypoints[0].elements[0].source.node_type === 'FRAME', 'DOM provider preserves source node type');
+  assert(domReport.entrypoints[0].elements[0].source.visual_dimensions.width === 120, 'DOM provider preserves source visual width');
+  assert(domReport.entrypoints[0].elements[0].source.visual_dimensions.height === 24, 'DOM provider preserves source visual height');
   assert(domReport.entrypoints[0].elements[0].selector === 'main[data-figma-node-id="12:34"]', 'DOM provider keys selector off default figma attribute');
   assert(domReport.entrypoints[0].elements[0].text_sample === 'Hello world', 'DOM provider captures text sample');
   assert(domReport.entrypoints[0].elements[0].page_path === '/dom-box.html', 'DOM provider adds page path to elements');

From cf2148771da6ea5740b6960e85a000bdbc071c47 Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@a8c.com>
Date: Mon, 13 Jul 2026 23:49:17 -0400
Subject: [PATCH 2/2] Handle rendered zero-axis Figma hairlines

---
 .../scripts/figma-fixture-matrix-quality.php  | 11 ++-
 .../tests/contract/FixtureMatrixContract.php  | 71 +++++++++++++++++++
 2 files changed, 80 insertions(+), 2 deletions(-)

diff --git a/figma-transformer/scripts/figma-fixture-matrix-quality.php b/figma-transformer/scripts/figma-fixture-matrix-quality.php
index 7d4c42fd..d6c2565f 100644
--- a/figma-transformer/scripts/figma-fixture-matrix-quality.php
+++ b/figma-transformer/scripts/figma-fixture-matrix-quality.php
@@ -511,9 +511,16 @@ function matrix_dom_box_is_unexpected_collapse(array $element, float $width, flo
         ? (float) $sourceDimensions[$collapsedAxis]
         : null;
     $domAxis = $collapsedWidth ? $width : $height;
+    if ( null === $sourceAxis || ! is_finite($sourceAxis) || $sourceAxis < 0.0 ) {
+        return true;
+    }
+
+    if ( abs($sourceAxis - $domAxis) <= 0.5 ) {
+        return false;
+    }
 
-    // A one-axis line is expected; collapsed geometry must still agree with source evidence.
-    return $domAxis <= 1.0 && (null === $sourceAxis || abs($sourceAxis - $domAxis) > 0.5);
+    // A zero-sized source axis may round up to one visible DOM pixel.
+    return ! (0.0 === $sourceAxis && $domAxis > 0.0 && $domAxis <= 1.0);
 }
 
 /**
diff --git a/figma-transformer/tests/contract/FixtureMatrixContract.php b/figma-transformer/tests/contract/FixtureMatrixContract.php
index 76580524..02b0f15a 100644
--- a/figma-transformer/tests/contract/FixtureMatrixContract.php
+++ b/figma-transformer/tests/contract/FixtureMatrixContract.php
@@ -448,6 +448,13 @@ function blocks_engine_figma_transformer_run_fixture_matrix_contract(callable $a
                         'visibility' => array('visible' => true),
                         'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 0.1, 'height' => 80)),
                     ),
+                    array(
+                        'node_id' => 'vector:source-zero-dom-one',
+                        'tag' => 'svg',
+                        'boundingClientRect' => array('left' => 0, 'right' => 943, 'top' => 90, 'bottom' => 91, 'width' => 943, 'height' => 1),
+                        'visibility' => array('visible' => true),
+                        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 0)),
+                    ),
                     array(
                         'node_id' => 'text:collapsed',
                         'tag' => 'p',
@@ -473,6 +480,56 @@ function blocks_engine_figma_transformer_run_fixture_matrix_contract(callable $a
             ),
         ),
     ), '/tmp/dom-box-collapse-classification.json');
+    $visibleVectorSourceZeroDomOne = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 0)),
+    );
+    $invisibleVectorSourceZeroDomOne = $visibleVectorSourceZeroDomOne;
+    $invisibleVectorSourceZeroDomOne['visibility']['visible'] = false;
+    $bothAxesCollapsedVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 1, 'height' => 1)),
+    );
+    $missingSourceAxisVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943)),
+    );
+    $nonNumericSourceAxisVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 'none')),
+    );
+    $sourceAxisNotCollapsedVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 2)),
+    );
+    $sourceAxisOneDomZeroVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 1)),
+    );
+    $sourceAxisFractionalDomZeroVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 0.75)),
+    );
+    $sourceAxisWithinToleranceVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => 0.75)),
+    );
+    $negativeSourceAxisVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => -0.25)),
+    );
+    $nanSourceAxisVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => NAN)),
+    );
+    $infiniteSourceAxisVector = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'VECTOR', 'visual_dimensions' => array('width' => 943, 'height' => INF)),
+    );
+    $ordinaryContentWithCollapsedAxis = array(
+        'visibility' => array('visible' => true),
+        'source' => array('node_type' => 'TEXT', 'visual_dimensions' => array('width' => 943, 'height' => 0)),
+    );
     $invalidDomBoxQuality = matrix_analyze_dom_box_report(array(
         'schema' => 'homeboy/static-artifact-dom-boxes/v1',
         'entrypoints' => array(
@@ -661,6 +718,20 @@ function blocks_engine_figma_transformer_run_fixture_matrix_contract(callable $a
     );
     $assert(! in_array('line:separator', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-allows-visible-one-pixel-line');
     $assert(! in_array('vector:tail', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-allows-source-faithful-subpixel-vector');
+    $assert(! in_array('vector:source-zero-dom-one', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-allows-visible-vector-source-zero-dom-one-through-analyzer');
+    $assert(! matrix_dom_box_is_unexpected_collapse($visibleVectorSourceZeroDomOne, 943, 1), 'fixture-matrix-dom-box-classification-allows-visible-vector-source-zero-dom-one');
+    $assert(matrix_dom_box_is_unexpected_collapse($invisibleVectorSourceZeroDomOne, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-invisible-vector');
+    $assert(matrix_dom_box_is_unexpected_collapse($bothAxesCollapsedVector, 1, 1), 'fixture-matrix-dom-box-classification-warns-for-both-axis-collapse');
+    $assert(matrix_dom_box_is_unexpected_collapse($missingSourceAxisVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-missing-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($nonNumericSourceAxisVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-non-numeric-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($nanSourceAxisVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-nan-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($infiniteSourceAxisVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-infinite-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($negativeSourceAxisVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-negative-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($sourceAxisNotCollapsedVector, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-non-collapsed-source-axis');
+    $assert(matrix_dom_box_is_unexpected_collapse($sourceAxisOneDomZeroVector, 943, 0), 'fixture-matrix-dom-box-classification-warns-for-source-one-dom-zero');
+    $assert(matrix_dom_box_is_unexpected_collapse($sourceAxisFractionalDomZeroVector, 943, 0), 'fixture-matrix-dom-box-classification-warns-for-source-fractional-dom-zero');
+    $assert(! matrix_dom_box_is_unexpected_collapse($sourceAxisWithinToleranceVector, 943, 1), 'fixture-matrix-dom-box-classification-allows-source-within-agreement-tolerance');
+    $assert(matrix_dom_box_is_unexpected_collapse($ordinaryContentWithCollapsedAxis, 943, 1), 'fixture-matrix-dom-box-classification-warns-for-ordinary-content');
     $assert(in_array('text:collapsed', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-collapsed-text');
     $assert(in_array('frame:collapsed', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-collapsed-container');
     $assert(in_array('vector:unexpected-collapse', $collapseFindingIds, true), 'fixture-matrix-dom-box-classification-warns-for-source-mismatched-vector');