Preserve repeating background layers as native group backgrounds

php-transformer/composer.json

@@ -457,6 +457,7 @@
       "php tests/unit/color-scheme-variant.php",
       "php tests/unit/color-scheme-projection.php",
       "php tests/unit/background-image-extractor.php",
+      "php tests/unit/repeating-background-layer.php",
       "php tests/unit/empty-layout-background-carrier.php",
       "php tests/unit/empty-span-spacer-selector-carrier.php",
       "php tests/unit/empty-definite-grid-cells.php",

php-transformer/src/HtmlToBlocks/Elements/FlowContainerElementConverter.php

@@ -309,6 +309,10 @@ private function lower(DOMElement $element, string $tagName, array &$fallbacks):
         if ( array() === $children && ! $this->context->hasDirectMediaChild($element) ) {
             $backgroundImage = $this->context->backgroundImageBlock($element);
             if ( null !== $backgroundImage ) {
+                // A background group already owns the source element's box.
+                if ( 'core/group' === ($backgroundImage['blockName'] ?? '') ) {
+                    return ConversionOutcome::handled($backgroundImage);
+                }
                 $children[] = $backgroundImage;
             }
         }

php-transformer/src/HtmlToBlocks/HtmlCompilation.php

@@ -137,6 +137,7 @@
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\DetailsPattern;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\ColumnsPatternContext;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\CommerceStructureRecognizer;
+use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\CoverStyleResolver;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\GalleryPattern;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\GalleryPatternContext;
 use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\Patterns\LogoPatternContext;
@@ -9143,6 +9144,19 @@ private function backgroundImageBlockFromElement(DOMElement $element): ?array
             return null;
         }
 
+        if ( (new CoverStyleResolver())->hasRepeatingBackground($this->styleResolver->mergedPresentationStyle($element)) ) {
+            $attrs = $this->styleResolver->presentationAttributes($element);
+            $attrs['style']['background'] = array_filter(array(
+                'backgroundImage'    => array( 'url' => $this->resolvedAssetImageUrl($url) ),
+                'backgroundRepeat'   => $declarations['background-repeat'] ?? 'repeat',
+                // Core defaults a missing size to cover, not CSS's initial auto.
+                'backgroundSize'     => $declarations['background-size'] ?? 'auto',
+                'backgroundPosition' => $declarations['background-position'] ?? '',
+            ), static fn ($value): bool => '' !== $value);
+
+            return $this->createBlock('core/group', $attrs, array(), $element);
+        }
+
         $width = trim((string) ($declarations['width'] ?? ''));
         $height = trim((string) ($declarations['height'] ?? ''));
         $scale = strtolower(trim((string) ($declarations['background-size'] ?? '')));

php-transformer/tests/unit/repeating-background-layer.php

@@ -0,0 +1,58 @@
+<?php
+declare(strict_types=1);
+
+require dirname(__DIR__, 2) . '/vendor/autoload.php';
+
+use Automattic\BlocksEngine\PhpTransformer\HtmlToBlocks\HtmlTransformer;
+
+$failures = 0;
+$assert = static function (bool $condition, string $message) use (&$failures): void {
+    if ( ! $condition ) {
+        ++$failures;
+        fwrite(STDERR, 'FAIL: ' . $message . PHP_EOL);
+    }
+};
+
+$fixture = static function (string $declarations): string {
+    return '<!doctype html><html><head><meta charset="utf-8"><title>Tile</title><style>body{margin:0}.band{position:relative;padding:80px 24px}.t{position:absolute;inset:0}h2{position:relative;margin:0}</style></head>'
+        . '<body><section class="band"><div class="t" style="background-image:url(tile.png);' . $declarations . '"></div><h2>Answer every call</h2></section></body></html>';
+};
+
+foreach ( array(
+    array( 'background-repeat:repeat', 'repeat', 'auto', null ),
+    array( 'background-repeat:repeat;background-size:20px 30px;background-position:left top', 'repeat', '20px 30px', 'left top' ),
+    array( 'background-repeat:repeat-x;background-size:contain', 'repeat-x', 'contain', null ),
+    array( 'background: url(tile.png) repeat', 'repeat', 'auto', null ),
+) as [$declarations, $repeat, $size, $position] ) {
+    $result = (new HtmlTransformer())->transform($fixture($declarations))->toArray();
+    $markup = (string) ($result['serialized_blocks'] ?? '');
+    $assert(! str_contains($markup, '<!-- wp:image'), $declarations . ': repeating paint must not become an image.');
+    preg_match_all('/<!-- wp:group (\{.*?\}) -->/', $markup, $matches);
+    $layers = array();
+    foreach ( $matches[1] as $json ) {
+        $attrs = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
+        if ( isset($attrs['style']['background']['backgroundImage']['url']) ) {
+            $layers[] = $attrs;
+        }
+    }
+    $assert(1 === count($layers), $declarations . ': exactly one group owns the background.');
+    $attrs = $layers[0] ?? array();
+    $background = $attrs['style']['background'] ?? array();
+    $assert('tile.png' === ($background['backgroundImage']['url'] ?? null), 'The layer keeps the asset URL.');
+    $assert($repeat === ($background['backgroundRepeat'] ?? null), 'The layer keeps the repeat.');
+    $assert($size === ($background['backgroundSize'] ?? null), 'The layer uses authored size or explicit CSS initial auto.');
+    if ( null !== $position ) {
+        $assert($position === ($background['backgroundPosition'] ?? null), 'The layer keeps the authored position.');
+    }
+    $assert(str_contains((string) ($attrs['className'] ?? ''), 't'), 'The background group itself carries source presentation.');
+    $assert(! preg_match('/<!-- wp:group [^\n]* -->\s*<div[^>]*class="[^"]*\bt\b[^>]*>\s*<!-- wp:group/', $markup), 'The empty source wrapper is replaced, not duplicated.');
+    $assert(str_contains($markup, 'Answer every call'), 'Sibling heading survives.');
+}
+
+$control = (new HtmlTransformer())->transform($fixture('background-repeat:no-repeat;background-size:cover'))->toArray();
+$assert(str_contains((string) ($control['serialized_blocks'] ?? ''), '<!-- wp:image'), 'Non-repeating cover paint still takes the image path.');
+
+if ( 0 < $failures ) {
+    exit(1);
+}
+fwrite(STDOUT, "Repeating background layer tests passed.\n");