fix: Sabberworm dependency collision causes fatal during animation CSS parsing

inc/class-base-css.php

@@ -384,6 +384,20 @@ public function get_animation_css( $blocks ) {
 			return $style;
 		}
 
+		if ( ! self::has_own_css_parser() ) {
+			// Another plugin loaded a different php-css-parser release; mixing its
+			// classes with the bundled ones fatals at class-link time (issue #2942).
+			// Skip the optimization and serve the full stock stylesheet instead.
+			// This can run before Blocks_Animation registers the handle, so
+			// register it here or the enqueue never prints.
+			if ( defined( 'BLOCKS_ANIMATION_URL' ) && ! wp_style_is( 'otter-animation', 'registered' ) ) {
+				wp_register_style( 'otter-animation', BLOCKS_ANIMATION_URL . 'build/animation/index.css', array(), OTTER_BLOCKS_VERSION );
+			}
+
+			wp_enqueue_style( 'otter-animation' );
+			return $style;
+		}
+
 		$prepared_classes = array( ':root' );
 
 		foreach ( $classes as $class ) {
@@ -445,6 +459,42 @@ public function get_animation_css( $blocks ) {
 		return $style;
 	}
 
+	/**
+	 * Check that every Sabberworm class the animation parser touches resolves to
+	 * the copy bundled with this plugin.
+	 *
+	 * Another active plugin can ship a different php-css-parser release under the
+	 * same global namespace. Once any of its classes or interfaces is loaded,
+	 * loading the bundled counterparts fatals at class-link time with a
+	 * declaration-compatibility error, and that error is not catchable.
+	 *
+	 * @return bool
+	 */
+	public static function has_own_css_parser() {
+		$own_vendor = wp_normalize_path( OTTER_BLOCKS_PATH . '/vendor/' );
+
+		$sentinels = array(
+			'\Sabberworm\CSS\Parser',
+			'\Sabberworm\CSS\Comment\Commentable',
+			'\Sabberworm\CSS\Renderable',
+		);
+
+		foreach ( $sentinels as $sentinel ) {
+			if ( ! class_exists( $sentinel ) && ! interface_exists( $sentinel ) ) {
+				return false;
+			}
+
+			$reflection = new \ReflectionClass( $sentinel );
+			$file       = $reflection->getFileName();
+
+			if ( false === $file || 0 !== strpos( wp_normalize_path( $file ), $own_vendor ) ) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
 	/**
 	 * Get Animation Classes
 	 *

packages/e2e-tests/mu-plugins/includes/foreign-sabberworm-interface.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * Typed `Commentable` interface as shipped by php-css-parser 9.x.
+ *
+ * Lives in a subdirectory so WordPress does not auto-load it as an mu-plugin;
+ * otter-e2e-bootstrap.php requires it only while the foreign-Sabberworm
+ * scenario (issue #2942) is armed. Once defined, loading Otter's bundled
+ * untyped CSSList fatals at class-link time — exactly like a second plugin
+ * shipping a newer parser release.
+ *
+ * @package otter-blocks
+ */
+
+// phpcs:ignoreFile -- deliberately mirrors the upstream 9.x signatures.
+
+namespace Sabberworm\CSS\Comment;
+
+interface Commentable {
+	public function addComments( array $comments ): void;
+	public function getComments(): array;
+	public function setComments( array $comments ): void;
+}

packages/e2e-tests/mu-plugins/otter-e2e-bootstrap.php

@@ -115,6 +115,14 @@
  */
 const BROKEN_AUTOLOADER_OPTION = 'otter_e2e_broken_autoloader';
 
+/**
+ * When truthy, a typed php-css-parser 9.x `Commentable` interface is defined before
+ * any plugin loads, reproducing a second plugin shipping a different Sabberworm
+ * release (issue #2942). Otter must skip its animation-CSS optimization instead
+ * of fataling while loading its bundled untyped classes.
+ */
+const FOREIGN_SABBERWORM_OPTION = 'otter_e2e_foreign_sabberworm';
+
 /**
  * Form record post type, mirrored from \ThemeIsle\GutenbergBlocks\Plugins\Form_Submissions.
  */
@@ -835,6 +843,18 @@ function break_otter_autoloader( $classnames ) {
 
 add_filter( 'otter_blocks_autoloader', __NAMESPACE__ . '\\break_otter_autoloader' );
 
+// Foreign-Sabberworm scenario (issue #2942): define the typed 9.x interface before
+// any plugin code runs, like a competing plugin's autoloader would. The scenario
+// endpoints stay exempt so a spec can always disarm the flag, even against code
+// where the armed frontend fatals.
+if ( get_option( FOREIGN_SABBERWORM_OPTION, false ) ) {
+	$otter_e2e_request_uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
+
+	if ( false === strpos( $otter_e2e_request_uri, REST_NAMESPACE ) ) {
+		require __DIR__ . '/includes/foreign-sabberworm-interface.php';
+	}
+}
+
 add_filter( 'pre_wp_mail', __NAMESPACE__ . '\\stub_wp_mail_for_e2e', 10, 2 );
 add_filter( 'pre_http_request', __NAMESPACE__ . '\\stub_openai_http_for_e2e', 10, 3 );
 
@@ -1446,6 +1466,37 @@ function () {
 			)
 		);
 
+		register_rest_route(
+			REST_NAMESPACE,
+			'/sabberworm',
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'permission_callback' => __NAMESPACE__ . '\\require_admin',
+				'callback'            => function ( \WP_REST_Request $request ) {
+					$mode = $request->get_param( 'mode' );
+
+					if ( ! in_array( $mode, array( 'foreign', 'own' ), true ) ) {
+						return new \WP_Error(
+							'otter_e2e_invalid_sabberworm_mode',
+							'Mode must be "foreign" or "own".',
+							array( 'status' => 400 )
+						);
+					}
+
+					if ( 'foreign' === $mode ) {
+						update_option( FOREIGN_SABBERWORM_OPTION, true, false );
+					} else {
+						delete_option( FOREIGN_SABBERWORM_OPTION );
+					}
+
+					// Force the next frontend request through the parse path.
+					delete_transient( 'otter_animations_parsed' );
+
+					return rest_ensure_response( array( 'ok' => true ) );
+				},
+			)
+		);
+
 		register_rest_route(
 			REST_NAMESPACE,
 			'/widgets/seed',
@@ -1497,6 +1548,7 @@ function () {
 					delete_option( CAPTCHA_MODE_OPTION );
 					delete_option( OPENAI_STUB_OPTION );
 					delete_option( FS_BLOCKED_OPTION );
+					delete_option( FOREIGN_SABBERWORM_OPTION );
 					cleanup_form_records();
 					return rest_ensure_response( array( 'ok' => true ) );
 				},

src/blocks/test/e2e/blocks/sabberworm-collision.spec.js

@@ -0,0 +1,93 @@
+/**
+ * Internal dependencies
+ */
+import { test, expect } from '../fixtures';
+
+/**
+ * Frontend animation-CSS coverage for https://github.com/Codeinwp/otter-blocks/issues/2942.
+ *
+ * When another plugin loads a different php-css-parser release, mixing its
+ * classes with Otter's bundled copy fatals at class-link time while
+ * Base_CSS::get_animation_css() parses the animation stylesheet. The scenario
+ * mu-plugin predefines the typed 9.x `Commentable` interface before plugins
+ * load; the page must still render, with the full stock animation stylesheet
+ * enqueued instead of the optimized inline subset.
+ *
+ * Each test creates its own fresh post AFTER switching modes: the first
+ * singular view generates and caches the post CSS, and cached requests never
+ * reach the parser again.
+ *
+ * Serial project: flips a site-wide scenario flag that affects every request.
+ */
+
+const POST_CONTENT = `<!-- wp:paragraph {"className":"animated fadeIn"} -->
+<p class="animated fadeIn">Animated collision probe</p>
+<!-- /wp:paragraph -->`;
+
+const createProbePost = async( requestUtils, title ) => {
+	const post = await requestUtils.rest({
+		method: 'POST',
+		path: '/wp/v2/posts',
+		data: {
+			status: 'publish',
+			title,
+			content: POST_CONTENT
+		}
+	});
+
+	// Plain query form: independent of the permalink structure.
+	return `/?p=${ post.id }`;
+};
+
+test.describe( 'Sabberworm collision fallback', () => {
+	test.afterAll( async({ requestUtils }) => {
+		await requestUtils.rest({
+			method: 'POST',
+			path: '/otter-e2e/v1/sabberworm',
+			data: { mode: 'own' }
+		});
+	});
+
+	test( 'renders the page with the full stylesheet when a foreign parser is loaded', async({ page, otterUtils, requestUtils }) => {
+		await otterUtils.setSabberwormMode( 'foreign' );
+
+		try {
+			const postUrl = await createProbePost( requestUtils, 'Foreign parser probe' );
+
+			const response = await page.goto( postUrl );
+
+			expect( response.status() ).toBe( 200 );
+
+			await expect( page.getByText( 'Animated collision probe' ) ).toBeVisible();
+
+			// Assert on the server response: the animation frontend script rewrites
+			// the block's classes in the live DOM once the animation plays.
+			const html = await response.text();
+			expect( html ).toContain( 'animated fadeIn' );
+			expect( html ).not.toContain( 'Fatal error' );
+			expect( html ).not.toContain( 'must be compatible' );
+
+			// The optimization is skipped, so the stock stylesheet carries the animations.
+			expect( html ).toContain( 'otter-animation-css' );
+			expect( html ).toMatch( /animation\/index\.css/ );
+		} finally {
+			await otterUtils.setSabberwormMode( 'own' );
+		}
+	});
+
+	test( 'inlines the optimized animation CSS with the bundled parser', async({ page, otterUtils, requestUtils }) => {
+		await otterUtils.setSabberwormMode( 'own' );
+
+		const postUrl = await createProbePost( requestUtils, 'Bundled parser probe' );
+
+		const response = await page.goto( postUrl );
+
+		await expect( page.getByText( 'Animated collision probe' ) ).toBeVisible();
+
+		// The optimized subset is served: the fadeIn keyframe is present without
+		// the full stock stylesheet.
+		const html = await response.text();
+		expect( html ).toContain( '@keyframes fadeIn' );
+		expect( html ).not.toContain( 'otter-animation-css' );
+	});
+});

src/blocks/test/e2e/fixtures.ts

@@ -70,6 +70,13 @@ export type OtterUtils = {
 	/** Remove the seeded widget, its CSS file/options, and the filesystem block. */
 	cleanupOtterWidget: () => Promise<unknown>;
 
+	/**
+	 * 'foreign' predefines a typed php-css-parser 9.x Commentable interface before
+	 * plugins load (issue #2942 scenario); 'own' restores the bundled parser.
+	 * Both modes clear the parsed-animations transient.
+	 */
+	setSabberwormMode: ( mode: 'foreign' | 'own' ) => Promise<unknown>;
+
 	/** All stored Submission Records with their Delivery Status meta. */
 	getFormRecords: () => Promise<FormRecord[]>;
 
@@ -105,6 +112,7 @@ export const test = base.extend<{ otterUtils: OtterUtils }>({
 			setFilesystemMode: ( mode ) => call( 'filesystem', { mode }),
 			seedOtterWidget: ( sidebar ) => call( 'widgets/seed', sidebar ? { sidebar } : undefined ),
 			cleanupOtterWidget: () => call( 'widgets/cleanup' ),
+			setSabberwormMode: ( mode ) => call( 'sabberworm', { mode }),
 			getFormRecords: () => call( 'form/records' ) as Promise<FormRecord[]>,
 			cleanupFormRecords: () => call( 'form/records/cleanup' )
 		});

src/blocks/test/e2e/playwright.config.js

@@ -63,7 +63,10 @@ const SERIAL_SPECS = [
 	'**/blocks/widgets-css-frontend.spec.js',
 
 	// Flips a site-wide flag that breaks Otter's autoloader for every request.
-	'**/blocks/autoloader-resilience.spec.js'
+	'**/blocks/autoloader-resilience.spec.js',
+
+	// Flips a site-wide flag that injects a foreign Sabberworm interface for every request.
+	'**/blocks/sabberworm-collision.spec.js'
 ];
 
 const config = defineConfig({

tests/php/foreign-sabberworm-sandbox.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Standalone sandbox for the Sabberworm dependency-collision regression (issue #2942).
+ *
+ * Simulates another plugin having already loaded a newer php-css-parser release:
+ * its `Commentable` interface declares typed signatures, so loading Otter's
+ * bundled untyped `CSSList` fatals at class-link time on PHP 8.1+ with
+ * "Declaration of ... addComments(array $aComments) must be compatible ...".
+ * Base_CSS::get_animation_css() must detect the foreign copy and fall back to
+ * enqueueing the full stock stylesheet instead of parsing.
+ *
+ * Run in a separate PHP process (no WordPress loaded):
+ *   php foreign-sabberworm-sandbox.php
+ *
+ * @package gutenberg-blocks
+ */
+
+// phpcs:ignoreFile -- multi-namespace sandbox executed outside WordPress.
+
+namespace Sabberworm\CSS\Comment {
+	// The typed interface shape shipped by php-css-parser 9.x.
+	interface Commentable {
+		public function addComments( array $comments ): void;
+		public function getComments(): array;
+		public function setComments( array $comments ): void;
+	}
+}
+
+namespace {
+	error_reporting( E_ALL );
+
+	define( 'OTTER_BLOCKS_PATH', dirname( dirname( __DIR__ ) ) );
+	define( 'MONTH_IN_SECONDS', 30 * 24 * 60 * 60 );
+
+	function get_transient( $key ) { return false; }
+	function set_transient( $key, $value, $expiration ) { return true; }
+	function get_option( $key, $default_value = false ) { return $default_value; }
+	function add_action() {}
+	function add_filter() {}
+	function apply_filters( $tag, $value ) { return $value; }
+	function wp_normalize_path( $path ) { return str_replace( '\\', '/', $path ); }
+	function wp_enqueue_style( $handle ) { echo 'ENQUEUED:' . $handle . "\n"; }
+
+	// Minimal autoloader for Otter's bundled parser only — mirrors the situation
+	// where Otter's Composer autoloader serves the remaining Sabberworm classes.
+	spl_autoload_register(
+		function ( $class ) {
+			$prefix = 'Sabberworm\\CSS\\';
+			if ( 0 !== strpos( $class, $prefix ) ) {
+				return;
+			}
+			$file = OTTER_BLOCKS_PATH . '/vendor/sabberworm/php-css-parser/src/' . str_replace( '\\', '/', substr( $class, strlen( $prefix ) ) ) . '.php';
+			if ( is_file( $file ) ) {
+				require $file;
+			}
+		}
+	);
+
+	require OTTER_BLOCKS_PATH . '/inc/class-base-css.php';
+
+	$base   = new \ThemeIsle\GutenbergBlocks\Base_CSS();
+	$blocks = array(
+		array(
+			'blockName' => 'core/paragraph',
+			'attrs'     => array( 'className' => 'animated fadeIn' ),
+		),
+	);
+
+	$css = $base->get_animation_css( $blocks );
+
+	echo 'CSS_LENGTH:' . strlen( (string) $css ) . "\n";
+	echo "REQUEST COMPLETED WITHOUT FATAL\n";
+}