From 73988cb783360a123bb7065d4f93b3fc9c9fe41d Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Tue, 1 Sep 2026 12:46:45 -0400
Subject: [PATCH 1/2] Preserve native animation and editor layout topology

---
 .../src/HtmlToBlocks/HtmlTransformer.php      |  8 +++++
 .../Style/RevealAnimationSettler.php          | 10 +------
 ...tifact-inline-style-extraction-base64.json |  3 +-
 .../artifact-inline-style-extraction.json     |  3 +-
 .../tests/unit/custom-block-generator.php     |  2 ++
 .../tests/unit/reveal-animation-settling.php  | 30 ++++++-------------
 6 files changed, 24 insertions(+), 32 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlTransformer.php b/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
index adc0bd02..b48f9911 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlTransformer.php
@@ -2032,6 +2032,14 @@ private function materializeAuthorStylesheet(string $html, string $staticCss, bo
             $beforeAuthorCssParts[] = ':root :where(.' . self::CSS_OWNED_LAYOUT_CLASS . ')>.block-editor-inner-blocks,'
                 . ':root :where(.' . self::CSS_OWNED_LAYOUT_CLASS . ')>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}';
         }
+        $layoutShellBlockName = $this->generatedBlocks()->blockName('layout-shell');
+        if ( str_contains($serializedBlocks, '<!-- wp:' . $layoutShellBlockName) ) {
+            // A layout shell preserves the source wrapper chain. Gutenberg's
+            // InnerBlocks wrappers must not become grid or flex items within it.
+            $layoutShellClass = 'wp-block-' . str_replace('/', '-', $layoutShellBlockName);
+            $beforeAuthorCssParts[] = ':root :where(.' . $layoutShellClass . ') .block-editor-inner-blocks,'
+                . ':root :where(.' . $layoutShellClass . ') .block-editor-block-list__layout{display:contents}';
+        }
         if ( str_contains($serializedBlocks, self::CSS_OWNED_FLOW_CLASS) ) {
             $beforeAuthorCssParts[] = ':root :where(.' . self::CSS_OWNED_FLOW_CLASS . '>p){margin-top:0;margin-bottom:0}';
         }
diff --git a/php-transformer/src/HtmlToBlocks/Style/RevealAnimationSettler.php b/php-transformer/src/HtmlToBlocks/Style/RevealAnimationSettler.php
index 908a58b0..72fcc148 100644
--- a/php-transformer/src/HtmlToBlocks/Style/RevealAnimationSettler.php
+++ b/php-transformer/src/HtmlToBlocks/Style/RevealAnimationSettler.php
@@ -242,17 +242,9 @@ private function animationConfiguration(array $declarations): array
             $delay = $this->timeSeconds(strtolower(trim((string) (CssValueSplitter::splitTopLevel($declarations['animation-delay'], array( ',' ))[0] ?? '')))) ?? $delay;
         }
 
-        // A scroll-driven timeline has no document clock behind it. Whether it
-        // ever advances depends on a scroll container the conversion does not
-        // control, and on this import it does not: `getAnimations()` reports the
-        // animation running while its progress — and the element's opacity —
-        // stays at zero.
-        $timeline = strtolower(trim((string) ($declarations['animation-timeline'] ?? '')));
-        $timelineDriven = '' !== $timeline && ! in_array($timeline, array( 'auto', 'none', 'initial', 'inherit', 'unset', 'revert', 'revert-layer' ), true);
-
         return array(
             'names' => $names,
-            'suspended' => $paused || $timelineDriven,
+            'suspended' => $paused,
             // The before phase is what the element shows either because the fill
             // mode paints it there, or because a non-positive delay leaves the
             // stalled animation inside its active phase at time zero.
diff --git a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
index 2071e43f..8a3a6902 100644
--- a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
+++ b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
@@ -26,11 +26,12 @@
   "expect": [
     { "path": "status", "assert": "equals", "value": "success" },
     { "path": "assets", "assert": "count", "count": 2 },
-    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-d34877b98a167d1b.css" },
+    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-6606e6560aa8bb51.css" },
     { "path": "assets.0.source", "assert": "equals", "value": "engine-support" },
     { "path": "assets.0.stylesheet_placement", "assert": "equals", "value": "before-author" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-grid)>*{margin-block-start:0;margin-block-end:0}" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-layout)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
+    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}" },
     { "path": "assets.1.path", "assert": "equals", "value": "index.inline.css" },
     { "path": "assets.1.kind", "assert": "equals", "value": "css" },
     { "path": "assets.1.role", "assert": "equals", "value": "stylesheet" },
diff --git a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
index 9c11403b..e8ff3e37 100644
--- a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
+++ b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
@@ -26,11 +26,12 @@
   "expect": [
     { "path": "status", "assert": "equals", "value": "success" },
     { "path": "assets", "assert": "count", "count": 2 },
-    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-d34877b98a167d1b.css" },
+    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-6606e6560aa8bb51.css" },
     { "path": "assets.0.source", "assert": "equals", "value": "engine-support" },
     { "path": "assets.0.stylesheet_placement", "assert": "equals", "value": "before-author" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-grid)>*{margin-block-start:0;margin-block-end:0}" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-layout)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
+    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}" },
     { "path": "assets.1.path", "assert": "equals", "value": "index.inline.css" },
     { "path": "assets.1.kind", "assert": "equals", "value": "css" },
     { "path": "assets.1.role", "assert": "equals", "value": "stylesheet" },
diff --git a/php-transformer/tests/unit/custom-block-generator.php b/php-transformer/tests/unit/custom-block-generator.php
index eb941a9c..1dc356b8 100644
--- a/php-transformer/tests/unit/custom-block-generator.php
+++ b/php-transformer/tests/unit/custom-block-generator.php
@@ -174,10 +174,12 @@
 $shellDefinitions = array_values(array_filter($shellResult['source_reports']['generated_blocks'] ?? array(), static fn (array $definition): bool => 'Layout Shell' === ($definition['block_json']['title'] ?? null)));
 $assert(str_ends_with((string) ($shellBlock['blockName'] ?? ''), '/layout-shell') && 8 === count($shellBlock['attrs']['wrappers'] ?? array()) && 'core/paragraph' === ($shellBlock['innerBlocks'][0]['blockName'] ?? null), '6: a projected wrapper chain becomes one layout-shell block around native editable content');
 $shellScript = (string) ($shellDefinitions[0]['assets']['index.js'] ?? '');
+$shellCss = implode("\n", array_map(static fn (array $asset): string => 'css' === ($asset['kind'] ?? '') ? (string) ($asset['content'] ?? '') : '', $shellResult['assets'] ?? array()));
 $assert(1 === count($shellDefinitions) && str_contains($shellScript, 'InnerBlocks.Content'), '6: layout-shell emits one companion definition whose save path retains native inner blocks');
 $assert(str_contains($shellScript, 'function wrappedContent( wrappers, content, outerProps )') && str_contains($shellScript, 'props = outerProps( props )') && str_contains($shellScript, 'content = wrappedContent( wrappers, content )') && str_contains($shellScript, 'edit: edit,'), '6: layout-shell edit preserves the save wrapper chain without merging editor props into authored wrappers');
 $assert(str_contains($shellScript, "useBlockProps( { style: { display: 'contents' } } )"), '6: layout-shell uses a box-neutral editor carrier so Gutenberg layout CSS cannot override authored wrapper positioning');
 $assert(str_contains($shellScript, "return createElement( 'div', useBlockProps( { style: { display: 'contents' } } ), content )"), '6: layout-shell retains the editor carrier for empty and source-backed wrapper chains');
+$assert(str_contains($shellCss, ':root :where(.wp-block-custom-layout-shell) .block-editor-inner-blocks,:root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}'), '6: layout-shell keeps Gutenberg InnerBlocks wrappers out of the preserved source layout topology');
 $assert(str_contains($shellScript, '__experimentalLabel: function( attributes, options )') && str_contains($shellScript, "context === 'list-view' || context === 'breadcrumb'") && str_contains($shellScript, "replace( /^_+/, '' ).replace( /_[a-z0-9]{5,}_\\d+$/i, '' )") && str_contains($shellScript, "return semantic + ': ' + detail") && str_contains($shellScript, "return 'Layout shell ('"), '6: layout-shell exposes concise semantic labels in List View and breadcrumbs');
 $assert(false === ($shellDefinitions[0]['block_json']['supports']['renaming'] ?? true), '6: generated semantic labels are read-only rather than persisted as user metadata');
 $assert(2 === ($shellResult['source_reports']['editability_report']['metrics']['max_nesting_depth'] ?? PHP_INT_MAX) && 8 === substr_count((string) ($shellResult['serialized_blocks'] ?? ''), 'id="shell-'), '6: layout-shell collapses List View depth while preserving every rendered source wrapper');
diff --git a/php-transformer/tests/unit/reveal-animation-settling.php b/php-transformer/tests/unit/reveal-animation-settling.php
index b3cb4da3..561153f7 100644
--- a/php-transformer/tests/unit/reveal-animation-settling.php
+++ b/php-transformer/tests/unit/reveal-animation-settling.php
@@ -5,11 +5,9 @@
  * A captured reveal must never leave content less visible than its end state.
  *
  * Wix pauses an entrance animation (`animation: motion-fadeIn … backwards paused`)
- * behind a runtime attribute, and capture can hand the same animation to a
- * scroll-driven timeline (`animation-timeline: view()`). Both are carried by
- * import while the driver that would finish them is not, and
- * `animation-fill-mode: backwards` then pins the element to the `0% {opacity:0}`
- * keyframe forever: the content is in the block markup and never paints (#239).
+ * behind a runtime attribute. That runtime driver is absent after import, so
+ * `animation-fill-mode: backwards` pins the element to `opacity:0`. A running
+ * scroll timeline remains browser-driven and must stay authored.
  *
  * The repair replaces an animation that cannot progress with the resolved state
  * it was travelling towards. An animation that can still run, and one whose start
@@ -46,8 +44,8 @@
 
 $scrollDriven = $fadeIn . '@supports (animation-timeline: view()){#comp-k3o4lijt{animation:motion-fadeIn 1200ms 1100ms cubic-bezier(0.445, 0.05, 0.55, 0.95) backwards 1;animation-composition:replace;animation-play-state:running;animation-timeline:view();animation-range:entry 0% cover 40%}}';
 $assert(
-    array( ':root #comp-k3o4lijt{animation:none!important;opacity:var(--comp-opacity, 1)!important}' ) === $settler->settleRules($scrollDriven),
-    'a scroll-driven entrance animation settles rather than resting on an unadvanced timeline',
+    array() === $settler->settleRules($scrollDriven),
+    'a running scroll-driven entrance animation keeps its browser-native timeline',
     implode(' | ', $settler->settleRules($scrollDriven))
 );
 
@@ -138,13 +136,8 @@
 };
 
 $afterAuthor = $collect($assets, static fn (array $asset): bool => 'engine-support' === ($asset['source'] ?? '') && 'after-author' === ($asset['stylesheet_placement'] ?? ''));
-foreach ( array( 'comp-k3nod418', 'comp-k3jrzme8' ) as $id ) {
-    $assert(
-        str_contains($afterAuthor, ':root #' . $id . '{animation:none!important;opacity:var(--comp-opacity, 1)!important}'),
-        'the theme stylesheet settles #' . $id . ' after the author CSS that hides it',
-        $afterAuthor
-    );
-}
+$assert(str_contains($afterAuthor, ':root #comp-k3nod418{animation:none!important;opacity:var(--comp-opacity, 1)!important}'), 'the theme stylesheet settles the paused reveal after author CSS', $afterAuthor);
+$assert(! str_contains($afterAuthor, ':root #comp-k3jrzme8{animation:none!important'), 'the theme stylesheet preserves the running scroll-timeline reveal', $afterAuthor);
 
 // The artifact pipeline materializes the author stylesheets itself and hands the
 // transform the projected copies, so the repair has to read those rather than the
@@ -157,13 +150,8 @@
     is_array($pipelineResult['assets'] ?? null) ? $pipelineResult['assets'] : array(),
     static fn (array $asset): bool => 'engine-support' === ($asset['source'] ?? '') && 'after-author' === ($asset['stylesheet_placement'] ?? '')
 );
-foreach ( array( 'comp-k3nod418', 'comp-k3jrzme8' ) as $id ) {
-    $assert(
-        str_contains($pipelineAfterAuthor, ':root #' . $id . '{animation:none!important;opacity:var(--comp-opacity, 1)!important}'),
-        'a pipeline transform that materializes its own author stylesheets still settles #' . $id,
-        $pipelineAfterAuthor
-    );
-}
+$assert(str_contains($pipelineAfterAuthor, ':root #comp-k3nod418{animation:none!important;opacity:var(--comp-opacity, 1)!important}'), 'a pipeline transform settles the paused reveal from its materialized author stylesheet', $pipelineAfterAuthor);
+$assert(! str_contains($pipelineAfterAuthor, ':root #comp-k3jrzme8{animation:none!important'), 'a pipeline transform preserves the running scroll timeline from its materialized author stylesheet', $pipelineAfterAuthor);
 
 $editorStaticState = $collect($assets, static fn (array $asset): bool => 'editor-static-state' === ($asset['source'] ?? ''));
 $assert(

From 3e37f04a59465fefae58c6d7c76e0522638575dd Mon Sep 17 00:00:00 2001
From: Chris Huber <chris.huber@automattic.com>
Date: Wed, 2 Sep 2026 07:57:25 -0400
Subject: [PATCH 2/2] Fix layout shell editor wrapper scope

---
 php-transformer/src/HtmlToBlocks/HtmlCompilation.php          | 4 ++--
 .../parity/artifact-inline-style-extraction-base64.json       | 4 ++--
 .../fixtures/parity/artifact-inline-style-extraction.json     | 4 ++--
 php-transformer/tests/unit/custom-block-generator.php         | 2 +-
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
index bab3ae0a..72dee007 100644
--- a/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
+++ b/php-transformer/src/HtmlToBlocks/HtmlCompilation.php
@@ -1999,8 +1999,8 @@ private function materializeAuthorStylesheet(string $html, string $staticCss, bo
             // A layout shell preserves the source wrapper chain. Gutenberg's
             // InnerBlocks wrappers must not become grid or flex items within it.
             $layoutShellClass = 'wp-block-' . str_replace('/', '-', $layoutShellBlockName);
-            $beforeAuthorCssParts[] = ':root :where(.' . $layoutShellClass . ') .block-editor-inner-blocks,'
-                . ':root :where(.' . $layoutShellClass . ') .block-editor-block-list__layout{display:contents}';
+            $beforeAuthorCssParts[] = ':root :where(.' . $layoutShellClass . ')>.block-editor-inner-blocks,'
+                . ':root :where(.' . $layoutShellClass . ')>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}';
         }
         if ( str_contains($serializedBlocks, self::CSS_OWNED_FLOW_CLASS) ) {
             $beforeAuthorCssParts[] = ':root :where(.' . self::CSS_OWNED_FLOW_CLASS . '>p){margin-top:0;margin-bottom:0}';
diff --git a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
index 8a3a6902..42f26b6c 100644
--- a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
+++ b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction-base64.json
@@ -26,12 +26,12 @@
   "expect": [
     { "path": "status", "assert": "equals", "value": "success" },
     { "path": "assets", "assert": "count", "count": 2 },
-    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-6606e6560aa8bb51.css" },
+    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-63874c2d7aa4cc26.css" },
     { "path": "assets.0.source", "assert": "equals", "value": "engine-support" },
     { "path": "assets.0.stylesheet_placement", "assert": "equals", "value": "before-author" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-grid)>*{margin-block-start:0;margin-block-end:0}" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-layout)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
-    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}" },
+    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
     { "path": "assets.1.path", "assert": "equals", "value": "index.inline.css" },
     { "path": "assets.1.kind", "assert": "equals", "value": "css" },
     { "path": "assets.1.role", "assert": "equals", "value": "stylesheet" },
diff --git a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
index e8ff3e37..c7fc8b65 100644
--- a/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
+++ b/php-transformer/tests/fixtures/parity/artifact-inline-style-extraction.json
@@ -26,12 +26,12 @@
   "expect": [
     { "path": "status", "assert": "equals", "value": "success" },
     { "path": "assets", "assert": "count", "count": 2 },
-    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-6606e6560aa8bb51.css" },
+    { "path": "assets.0.path", "assert": "equals", "value": "assets/css/engine-support-before-author-63874c2d7aa4cc26.css" },
     { "path": "assets.0.source", "assert": "equals", "value": "engine-support" },
     { "path": "assets.0.stylesheet_placement", "assert": "equals", "value": "before-author" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-grid)>*{margin-block-start:0;margin-block-end:0}" },
     { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.blocks-engine-css-owned-layout)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
-    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}" },
+    { "path": "assets.0.content", "assert": "contains", "value": ":root :where(.wp-block-custom-layout-shell)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}" },
     { "path": "assets.1.path", "assert": "equals", "value": "index.inline.css" },
     { "path": "assets.1.kind", "assert": "equals", "value": "css" },
     { "path": "assets.1.role", "assert": "equals", "value": "stylesheet" },
diff --git a/php-transformer/tests/unit/custom-block-generator.php b/php-transformer/tests/unit/custom-block-generator.php
index 1dc356b8..f05a45ff 100644
--- a/php-transformer/tests/unit/custom-block-generator.php
+++ b/php-transformer/tests/unit/custom-block-generator.php
@@ -179,7 +179,7 @@
 $assert(str_contains($shellScript, 'function wrappedContent( wrappers, content, outerProps )') && str_contains($shellScript, 'props = outerProps( props )') && str_contains($shellScript, 'content = wrappedContent( wrappers, content )') && str_contains($shellScript, 'edit: edit,'), '6: layout-shell edit preserves the save wrapper chain without merging editor props into authored wrappers');
 $assert(str_contains($shellScript, "useBlockProps( { style: { display: 'contents' } } )"), '6: layout-shell uses a box-neutral editor carrier so Gutenberg layout CSS cannot override authored wrapper positioning');
 $assert(str_contains($shellScript, "return createElement( 'div', useBlockProps( { style: { display: 'contents' } } ), content )"), '6: layout-shell retains the editor carrier for empty and source-backed wrapper chains');
-$assert(str_contains($shellCss, ':root :where(.wp-block-custom-layout-shell) .block-editor-inner-blocks,:root :where(.wp-block-custom-layout-shell) .block-editor-block-list__layout{display:contents}'), '6: layout-shell keeps Gutenberg InnerBlocks wrappers out of the preserved source layout topology');
+$assert(str_contains($shellCss, ':root :where(.wp-block-custom-layout-shell)>.block-editor-inner-blocks,:root :where(.wp-block-custom-layout-shell)>.block-editor-inner-blocks>.block-editor-block-list__layout{display:contents}'), '6: layout-shell keeps its Gutenberg InnerBlocks wrappers out of the preserved source layout topology');
 $assert(str_contains($shellScript, '__experimentalLabel: function( attributes, options )') && str_contains($shellScript, "context === 'list-view' || context === 'breadcrumb'") && str_contains($shellScript, "replace( /^_+/, '' ).replace( /_[a-z0-9]{5,}_\\d+$/i, '' )") && str_contains($shellScript, "return semantic + ': ' + detail") && str_contains($shellScript, "return 'Layout shell ('"), '6: layout-shell exposes concise semantic labels in List View and breadcrumbs');
 $assert(false === ($shellDefinitions[0]['block_json']['supports']['renaming'] ?? true), '6: generated semantic labels are read-only rather than persisted as user metadata');
 $assert(2 === ($shellResult['source_reports']['editability_report']['metrics']['max_nesting_depth'] ?? PHP_INT_MAX) && 8 === substr_count((string) ($shellResult['serialized_blocks'] ?? ''), 'id="shell-'), '6: layout-shell collapses List View depth while preserving every rendered source wrapper');