fix: Sabberworm dependency collision causes fatal during animation CSS parsing

inc/class-base-css.php

@@ -384,6 +384,15 @@ 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 — Blocks_Animation::frontend_load() serves the
+			// full stock stylesheet whenever this guard fails, so the animation
+			// rules never depend on the optimized fragment generated here.
+			return $style;
+		}
+
 		$prepared_classes = array( ':root' );
 
 		foreach ( $classes as $class ) {
@@ -445,6 +454,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
 	 *

inc/class-blocks-animation.php

@@ -172,7 +172,15 @@ public function frontend_load( $block_content, $block ) {
 		}
 
 		if ( ! self::$scripts_loaded['animation'] && strpos( $block_content, 'animated' ) ) {
-			if ( ! defined( 'OTTER_BLOCKS_VERSION' ) || ( defined( 'OTTER_BLOCKS_VERSION' ) && ! get_option( 'themeisle_blocks_settings_optimize_animations_css', true ) ) ) {
+			// The stock stylesheet also serves pages whose generated CSS was built
+			// while a foreign php-css-parser copy blocked the optimization (issue
+			// #2942) — the cached CSS carries no animation rules, so this delivery
+			// must not depend on the optimized path having run.
+			if (
+				! defined( 'OTTER_BLOCKS_VERSION' ) ||
+				! get_option( 'themeisle_blocks_settings_optimize_animations_css', true ) ||
+				! Base_CSS::has_own_css_parser()
+			) {
 				wp_enqueue_style( 'otter-animation' );
 			}
 

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,131 @@
+/**
+ * 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 — including on later
+ * requests served from the generated post-CSS cache, which carries no
+ * animation rules while the guard fails.
+ *
+ * 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.
+ */
+
+// The Progress Bar makes the generated post CSS non-empty, so the second
+// request is served from the cached stylesheet file.
+const FOREIGN_POST_CONTENT = `<!-- wp:paragraph {"className":"animated fadeIn"} -->
+<p class="animated fadeIn">Animated collision probe</p>
+<!-- /wp:paragraph -->
+
+<!-- wp:themeisle-blocks/progress-bar {"id":"wp-block-themeisle-blocks-progress-bar-e2e2942","title":"Collision probe","percentage":75,"titleColor":"#123abc","height":36} -->
+<div id="wp-block-themeisle-blocks-progress-bar-e2e2942" class="wp-block-themeisle-blocks-progress-bar"><div class="wp-block-themeisle-blocks-progress-bar__title">Collision probe</div><div class="wp-block-themeisle-blocks-progress-bar__area"><div class="wp-block-themeisle-blocks-progress-bar__area__bar"></div></div></div>
+<!-- /wp:themeisle-blocks/progress-bar -->`;
+
+const OWN_POST_CONTENT = `<!-- wp:paragraph {"className":"animated fadeIn"} -->
+<p class="animated fadeIn">Animated collision probe</p>
+<!-- /wp:paragraph -->`;
+
+test.describe( 'Sabberworm collision fallback', () => {
+	const createdPosts = [];
+
+	const createProbePost = async( requestUtils, title, content ) => {
+		const post = await requestUtils.rest({
+			method: 'POST',
+			path: '/wp/v2/posts',
+			data: {
+				status: 'publish',
+				title,
+				content
+			}
+		});
+
+		createdPosts.push( post.id );
+
+		// Plain query form: independent of the permalink structure.
+		return `/?p=${ post.id }`;
+	};
+
+	test.afterAll( async({ requestUtils }) => {
+		await requestUtils.rest({
+			method: 'POST',
+			path: '/otter-e2e/v1/sabberworm',
+			data: { mode: 'own' }
+		});
+
+		// Only this spec's own posts — other specs run against the same site.
+		// Best-effort per post: one failed request must not orphan the rest.
+		while ( createdPosts.length ) {
+			const postId = createdPosts.pop();
+			try {
+				await requestUtils.rest({
+					method: 'DELETE',
+					path: `/wp/v2/posts/${ postId }`,
+					params: { force: true }
+				});
+			} catch ( error ) {
+				console.warn( `Could not delete post ${ postId }:`, error.message );
+			}
+		}
+	});
+
+	test( 'serves the full stylesheet when a foreign parser is loaded, also from the CSS cache', async({ page, otterUtils, requestUtils }) => {
+		await otterUtils.setSabberwormMode( 'foreign' );
+
+		try {
+			const postUrl = await createProbePost( requestUtils, 'Foreign parser probe', FOREIGN_POST_CONTENT );
+
+			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/ );
+
+			// The first request generated and cached the post CSS without animation
+			// rules; the fallback must survive requests served from that cache.
+			const cachedResponse = await page.goto( postUrl );
+			const cachedHtml = await cachedResponse.text();
+			expect( cachedHtml ).toContain( 'otter-animation-css' );
+			expect( cachedHtml ).not.toContain( 'Fatal error' );
+		} 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', OWN_POST_CONTENT );
+
+		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({