From 5a4778859a78bd68b42792872faff1eb71f311e8 Mon Sep 17 00:00:00 2001
From: Luca Dobrescu <luca.dobrescu@vertistudio.com>
Date: Fri, 31 Jul 2026 10:50:26 +0300
Subject: [PATCH] fix: guard widgets CSS writability check against missing
 WP_Filesystem()

CSS_Handler::is_writable() called WP_Filesystem() before its
function_exists() fallback, so a frontend request with an active
sidebar and no generated widget stylesheet fataled with
"Call to undefined function WP_Filesystem()" when the include did
not expose the function. Run the guard first so the request degrades
to the inline widget CSS fallback, and verify the initialized
$wp_filesystem instance before reading its method.

Adds an isolated-process PHPUnit regression test and a frontend e2e
spec covering the blocked-filesystem fallback and the written-file
path.

Fixes #2937

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .wp-env.json                                  |   5 +-
 inc/css/class-css-handler.php                 |   9 +-
 .../mu-plugins/otter-e2e-bootstrap.php        | 167 ++++++++++++++++++
 .../e2e/blocks/widgets-css-frontend.spec.js   |  94 ++++++++++
 src/blocks/test/e2e/fixtures.ts               |  15 ++
 src/blocks/test/e2e/playwright.config.js      |   5 +-
 tests/php/is-writable-sandbox.php             |  65 +++++++
 tests/test-css-handler.php                    |  50 ++++++
 8 files changed, 403 insertions(+), 7 deletions(-)
 create mode 100644 src/blocks/test/e2e/blocks/widgets-css-frontend.spec.js
 create mode 100644 tests/php/is-writable-sandbox.php
 create mode 100644 tests/test-css-handler.php

diff --git a/.wp-env.json b/.wp-env.json
index ecc59bbe2..baf5a856f 100644
--- a/.wp-env.json
+++ b/.wp-env.json
@@ -6,7 +6,10 @@
     ".",
     "https://downloads.wordpress.org/plugin/ai-provider-for-openai.zip"
   ],
-  "themes": [ "./test/emptytheme" ],
+  "themes": [
+    "./test/emptytheme",
+    "https://downloads.wordpress.org/theme/twentytwentyone.zip"
+  ],
   "config": {
     "WP_DEBUG": true,
     "WP_DEBUG_LOG": true,
diff --git a/inc/css/class-css-handler.php b/inc/css/class-css-handler.php
index db96b5832..41afb4ecd 100644
--- a/inc/css/class-css-handler.php
+++ b/inc/css/class-css-handler.php
@@ -496,18 +496,17 @@ public static function save_widgets_styles() {
 	public static function is_writable() {
 		global $wp_filesystem;
 		include_once ABSPATH . 'wp-admin/includes/file.php';
-		WP_Filesystem();
-
-		$wp_upload_dir = wp_upload_dir( null, false );
-		$upload_dir    = $wp_upload_dir['basedir'];
 
 		if ( ! function_exists( 'WP_Filesystem' ) ) {
 			return false;
 		}
 
+		$wp_upload_dir = wp_upload_dir( null, false );
+		$upload_dir    = $wp_upload_dir['basedir'];
+
 		$writable = WP_Filesystem( false, $upload_dir );
 
-		return $writable && 'direct' === $wp_filesystem->method;
+		return $writable && $wp_filesystem instanceof \WP_Filesystem_Base && 'direct' === $wp_filesystem->method;
 	}
 
 	/**
diff --git a/packages/e2e-tests/mu-plugins/otter-e2e-bootstrap.php b/packages/e2e-tests/mu-plugins/otter-e2e-bootstrap.php
index 882241e0a..6288186ff 100644
--- a/packages/e2e-tests/mu-plugins/otter-e2e-bootstrap.php
+++ b/packages/e2e-tests/mu-plugins/otter-e2e-bootstrap.php
@@ -94,6 +94,19 @@
  */
 const OPENAI_STUB_OPTION = 'otter_e2e_openai_stub';
 
+/**
+ * When truthy, get_filesystem_method() reports a bogus method so WP_Filesystem()
+ * fails to initialize. Simulates hosts where the filesystem API is unavailable
+ * on the frontend (issue #2937) — CSS_Handler::is_writable() must degrade to
+ * `false` and the widgets CSS must fall back to an inline <style>.
+ */
+const FS_BLOCKED_OPTION = 'otter_e2e_fs_blocked';
+
+/**
+ * Numeric index used for the seeded block widget instance (widget id `block-999`).
+ */
+const WIDGET_SEED_INDEX = 999;
+
 /**
  * Form record post type, mirrored from \ThemeIsle\GutenbergBlocks\Plugins\Form_Submissions.
  */
@@ -941,6 +954,104 @@ function stub_captcha_http_verification_for_e2e( $preempt, $request, $url ) {
 
 add_filter( 'pre_http_request', __NAMESPACE__ . '\\stub_captcha_http_verification_for_e2e', 10, 3 );
 
+/**
+ * Report an unknown filesystem method while the fs-blocked scenario is active.
+ *
+ * WP_Filesystem() then fails to locate the abstraction class file and bails out
+ * without initializing `$wp_filesystem`, which is the closest reproducible
+ * stand-in for the production condition behind issue #2937.
+ *
+ * @param string $method Detected filesystem method.
+ * @return string
+ */
+function block_filesystem_method_for_e2e( $method ) {
+	return get_option( FS_BLOCKED_OPTION ) ? 'otter_e2e_blocked' : $method;
+}
+
+add_filter( 'filesystem_method', __NAMESPACE__ . '\\block_filesystem_method_for_e2e', PHP_INT_MAX );
+
+/**
+ * Seed a classic-widgets sidebar with an Otter block so the frontend
+ * widgets-CSS path (Block_Frontend::enqueue_widgets_css) is exercised.
+ *
+ * Clears the generated-stylesheet options so the next frontend request takes
+ * the "no CSS file yet" branch that calls CSS_Handler::is_writable().
+ *
+ * @param string $sidebar_id Sidebar to place the widget in.
+ * @return void
+ */
+function seed_otter_widget( $sidebar_id ) {
+	$markup = '<!-- wp:themeisle-blocks/progress-bar {"id":"wp-block-themeisle-blocks-progress-bar-e2e2937","title":"E2E Progress","percentage":75,"titleColor":"#123abc","height":36} -->' . "\n" .
+		'<div id="wp-block-themeisle-blocks-progress-bar-e2e2937" class="wp-block-themeisle-blocks-progress-bar"><div class="wp-block-themeisle-blocks-progress-bar__title">E2E Progress</div><div class="wp-block-themeisle-blocks-progress-bar__area"><div class="wp-block-themeisle-blocks-progress-bar__area__bar"></div></div></div>' . "\n" .
+		'<!-- /wp:themeisle-blocks/progress-bar -->';
+
+	$widget_blocks = get_option( 'widget_block', array() );
+
+	if ( ! is_array( $widget_blocks ) ) {
+		$widget_blocks = array();
+	}
+
+	$widget_blocks[ WIDGET_SEED_INDEX ] = array( 'content' => $markup );
+	$widget_blocks['_multiwidget']      = 1;
+	update_option( 'widget_block', $widget_blocks );
+
+	$sidebars = get_option( 'sidebars_widgets', array() );
+
+	if ( ! is_array( $sidebars ) ) {
+		$sidebars = array();
+	}
+
+	$existing = isset( $sidebars[ $sidebar_id ] ) && is_array( $sidebars[ $sidebar_id ] ) ? $sidebars[ $sidebar_id ] : array();
+
+	$sidebars[ $sidebar_id ] = array_values( array_unique( array_merge( array( 'block-' . WIDGET_SEED_INDEX ), $existing ) ) );
+	update_option( 'sidebars_widgets', $sidebars );
+
+	delete_option( 'themeisle_blocks_widgets_css_file' );
+	delete_option( 'themeisle_blocks_widgets_css' );
+	delete_option( 'themeisle_blocks_widgets_fonts' );
+}
+
+/**
+ * Remove the seeded widget and every widgets-CSS artifact it produced.
+ *
+ * @return void
+ */
+function cleanup_otter_widget() {
+	$widget_blocks = get_option( 'widget_block', array() );
+
+	if ( is_array( $widget_blocks ) && isset( $widget_blocks[ WIDGET_SEED_INDEX ] ) ) {
+		unset( $widget_blocks[ WIDGET_SEED_INDEX ] );
+		update_option( 'widget_block', $widget_blocks );
+	}
+
+	$sidebars = get_option( 'sidebars_widgets', array() );
+
+	if ( is_array( $sidebars ) ) {
+		foreach ( $sidebars as $sidebar_id => $widgets ) {
+			if ( is_array( $widgets ) ) {
+				$sidebars[ $sidebar_id ] = array_values( array_diff( $widgets, array( 'block-' . WIDGET_SEED_INDEX ) ) );
+			}
+		}
+		update_option( 'sidebars_widgets', $sidebars );
+	}
+
+	$file_name = get_option( 'themeisle_blocks_widgets_css_file' );
+
+	if ( $file_name ) {
+		$wp_upload_dir = wp_upload_dir( null, false );
+		$file_path     = $wp_upload_dir['basedir'] . '/themeisle-gutenberg/' . $file_name . '.css';
+
+		if ( is_file( $file_path ) ) {
+			wp_delete_file( $file_path );
+		}
+	}
+
+	delete_option( 'themeisle_blocks_widgets_css_file' );
+	delete_option( 'themeisle_blocks_widgets_css' );
+	delete_option( 'themeisle_blocks_widgets_fonts' );
+	delete_option( FS_BLOCKED_OPTION );
+}
+
 add_action(
 	'rest_api_init',
 	function () {
@@ -1226,6 +1337,61 @@ function () {
 			)
 		);
 
+		register_rest_route(
+			REST_NAMESPACE,
+			'/filesystem',
+			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( 'blocked', 'ok' ), true ) ) {
+						return new \WP_Error(
+							'otter_e2e_invalid_fs_mode',
+							'Mode must be "blocked" or "ok".',
+							array( 'status' => 400 )
+						);
+					}
+
+					if ( 'blocked' === $mode ) {
+						update_option( FS_BLOCKED_OPTION, true, false );
+					} else {
+						delete_option( FS_BLOCKED_OPTION );
+					}
+
+					return rest_ensure_response( array( 'ok' => true ) );
+				},
+			)
+		);
+
+		register_rest_route(
+			REST_NAMESPACE,
+			'/widgets/seed',
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'permission_callback' => __NAMESPACE__ . '\\require_admin',
+				'callback'            => function ( \WP_REST_Request $request ) {
+					$sidebar_id = $request->get_param( 'sidebar' );
+					seed_otter_widget( is_string( $sidebar_id ) && '' !== $sidebar_id ? $sidebar_id : 'sidebar-1' );
+					return rest_ensure_response( array( 'ok' => true ) );
+				},
+			)
+		);
+
+		register_rest_route(
+			REST_NAMESPACE,
+			'/widgets/cleanup',
+			array(
+				'methods'             => \WP_REST_Server::CREATABLE,
+				'permission_callback' => __NAMESPACE__ . '\\require_admin',
+				'callback'            => function () {
+					cleanup_otter_widget();
+					return rest_ensure_response( array( 'ok' => true ) );
+				},
+			)
+		);
+
 		register_rest_route(
 			REST_NAMESPACE,
 			'/reset',
@@ -1249,6 +1415,7 @@ function () {
 					delete_option( MAIL_LOG_OPTION );
 					delete_option( CAPTCHA_MODE_OPTION );
 					delete_option( OPENAI_STUB_OPTION );
+					delete_option( FS_BLOCKED_OPTION );
 					cleanup_form_records();
 					return rest_ensure_response( array( 'ok' => true ) );
 				},
diff --git a/src/blocks/test/e2e/blocks/widgets-css-frontend.spec.js b/src/blocks/test/e2e/blocks/widgets-css-frontend.spec.js
new file mode 100644
index 000000000..196ccff5f
--- /dev/null
+++ b/src/blocks/test/e2e/blocks/widgets-css-frontend.spec.js
@@ -0,0 +1,94 @@
+/**
+ * Internal dependencies
+ */
+import { test, expect } from '../fixtures';
+
+/**
+ * Frontend widgets-CSS coverage for https://github.com/Codeinwp/otter-blocks/issues/2937.
+ *
+ * A frontend request with an active sidebar and no generated widget stylesheet
+ * reaches CSS_Handler::is_writable() from Block_Frontend::enqueue_widgets_css()
+ * at wp_footer. In production that request fataled when WP_Filesystem() was
+ * unavailable. The exact missing-function condition can only be recreated in
+ * the isolated PHPUnit sandbox (tests/test-css-handler.php); here the
+ * filesystem is blocked at the get_filesystem_method() level, which drives the
+ * same is_writable() → false branch and asserts the user-visible contract: the
+ * page must finish rendering and serve the widget CSS inline.
+ *
+ * Serial project: switches the active theme and mutates site-wide widget,
+ * option, and filesystem state.
+ */
+
+const WIDGET_SELECTOR = '.wp-block-themeisle-blocks-progress-bar';
+const WIDGET_CSS_ID = '#wp-block-themeisle-blocks-progress-bar-e2e2937';
+
+test.describe( 'Widgets CSS frontend', () => {
+	test.beforeAll( async({ requestUtils }) => {
+		// Classic theme with a registered sidebar; block themes register none,
+		// so the widgets-CSS path is unreachable on the default theme.
+		await requestUtils.activateTheme( 'twentytwentyone' );
+
+		await requestUtils.rest({
+			method: 'POST',
+			path: '/otter-e2e/v1/widgets/seed'
+		});
+	});
+
+	test.afterAll( async({ requestUtils }) => {
+		await requestUtils.rest({
+			method: 'POST',
+			path: '/otter-e2e/v1/widgets/cleanup'
+		});
+
+		await requestUtils.activateTheme( 'twentytwentythree' );
+	});
+
+	test( 'completes the page with inline widget CSS when the filesystem is unavailable', async({ page, otterUtils }) => {
+		await otterUtils.setFilesystemMode( 'blocked' );
+
+		try {
+			// Take the no-stylesheet branch on a fresh request.
+			await otterUtils.seedOtterWidget();
+
+			const response = await page.goto( '/' );
+
+			expect( response.status() ).toBe( 200 );
+
+			// The widget itself rendered inside the sidebar.
+			await expect( page.locator( WIDGET_SELECTOR ) ).toBeVisible();
+
+			const content = await page.content();
+
+			// The inline <style> fallback is echoed at wp_footer, after the
+			// is_writable() call that used to fatal — its presence proves the
+			// request completed past the crash point.
+			expect( content ).toContain( WIDGET_CSS_ID );
+			expect( content ).toContain( '--percentage' );
+			expect( content ).not.toContain( 'Fatal error' );
+
+			// No stylesheet file could be written, so none may be enqueued.
+			await expect( page.locator( 'link#otter-widgets-css' ) ).toHaveCount( 0 );
+		} finally {
+			await otterUtils.setFilesystemMode( 'ok' );
+		}
+	});
+
+	test( 'writes and enqueues the widgets CSS file when the filesystem is available', async({ page, otterUtils }) => {
+		await otterUtils.setFilesystemMode( 'ok' );
+
+		// Fresh no-stylesheet state; this request regenerates and saves the file.
+		await otterUtils.seedOtterWidget();
+
+		await page.goto( '/' );
+		await expect( page.locator( WIDGET_SELECTOR ) ).toBeVisible();
+
+		// The file was written during the previous request; this one enqueues it.
+		await page.reload();
+
+		await expect( page.locator( WIDGET_SELECTOR ) ).toBeVisible();
+
+		const stylesheet = page.locator( 'link#otter-widgets-css' );
+		await expect( stylesheet ).toHaveCount( 1 );
+		await expect( stylesheet ).toHaveAttribute( 'href', /themeisle-gutenberg\/widgets-/ );
+	});
+});
diff --git a/src/blocks/test/e2e/fixtures.ts b/src/blocks/test/e2e/fixtures.ts
index d9e2f5a2e..dd13ff773 100644
--- a/src/blocks/test/e2e/fixtures.ts
+++ b/src/blocks/test/e2e/fixtures.ts
@@ -58,6 +58,18 @@ export type OtterUtils = {
 	/** Mint a `form-verification` nonce for API-driven submissions. */
 	getFormVerificationNonce: () => Promise<string>;
 
+	/**
+	 * 'blocked' makes get_filesystem_method() report a bogus method so
+	 * WP_Filesystem() fails to initialize (issue #2937 scenario); 'ok' restores it.
+	 */
+	setFilesystemMode: ( mode: 'blocked' | 'ok' ) => Promise<unknown>;
+
+	/** Seed a classic sidebar with an Otter block widget and clear the generated widgets-CSS options. */
+	seedOtterWidget: ( sidebar?: string ) => Promise<unknown>;
+
+	/** Remove the seeded widget, its CSS file/options, and the filesystem block. */
+	cleanupOtterWidget: () => Promise<unknown>;
+
 	/** All stored Submission Records with their Delivery Status meta. */
 	getFormRecords: () => Promise<FormRecord[]>;
 
@@ -90,6 +102,9 @@ export const test = base.extend<{ otterUtils: OtterUtils }>({
 				const response = ( await call( 'form/nonce' ) ) as { nonce: string };
 				return response.nonce;
 			},
+			setFilesystemMode: ( mode ) => call( 'filesystem', { mode }),
+			seedOtterWidget: ( sidebar ) => call( 'widgets/seed', sidebar ? { sidebar } : undefined ),
+			cleanupOtterWidget: () => call( 'widgets/cleanup' ),
 			getFormRecords: () => call( 'form/records' ) as Promise<FormRecord[]>,
 			cleanupFormRecords: () => call( 'form/records/cleanup' )
 		});
diff --git a/src/blocks/test/e2e/playwright.config.js b/src/blocks/test/e2e/playwright.config.js
index cac9dd4c7..78823c080 100644
--- a/src/blocks/test/e2e/playwright.config.js
+++ b/src/blocks/test/e2e/playwright.config.js
@@ -57,7 +57,10 @@ const SERIAL_SPECS = [
 	'**/blocks/design-library.spec.js',
 
 	// Flips the site-wide atomic-wind blocks option.
-	'**/blocks/atomic-wind-list-view.spec.js'
+	'**/blocks/atomic-wind-list-view.spec.js',
+
+	// Switches the active theme and mutates site-wide widget + filesystem state.
+	'**/blocks/widgets-css-frontend.spec.js'
 ];
 
 const config = defineConfig({
diff --git a/tests/php/is-writable-sandbox.php b/tests/php/is-writable-sandbox.php
new file mode 100644
index 000000000..6899d1fc6
--- /dev/null
+++ b/tests/php/is-writable-sandbox.php
@@ -0,0 +1,65 @@
+<?php
+/**
+ * Standalone sandbox for CSS_Handler::is_writable() regression testing.
+ *
+ * Simulates the production condition from
+ * https://github.com/Codeinwp/otter-blocks/issues/2937: the request includes
+ * wp-admin/includes/file.php, but WP_Filesystem() is still undefined
+ * afterwards. is_writable() must return false instead of raising an uncaught
+ * "Call to undefined function WP_Filesystem()" error.
+ *
+ * Run in a separate PHP process (no WordPress loaded):
+ *   php is-writable-sandbox.php
+ *
+ * @package gutenberg-blocks
+ */
+
+error_reporting( E_ALL ); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.prevent_path_disclosure_error_reporting, WordPress.PHP.DiscouragedPHPFunctions.runtime_configuration_error_reporting
+
+$plugin_dir = dirname( dirname( __DIR__ ) );
+
+// Fake ABSPATH whose wp-admin/includes/file.php does NOT define WP_Filesystem().
+$fake_abspath = rtrim( sys_get_temp_dir(), '/\\' ) . '/otter-2937-fake-wp-' . getmypid() . '/';
+
+if ( ! is_dir( $fake_abspath . 'wp-admin/includes' ) ) {
+	mkdir( $fake_abspath . 'wp-admin/includes', 0777, true );
+}
+
+file_put_contents( // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_read_file_put_contents
+	$fake_abspath . 'wp-admin/includes/file.php',
+	"<?php // Intentionally empty: simulates WP_Filesystem() remaining unavailable after the include.\n"
+);
+
+define( 'ABSPATH', $fake_abspath );
+
+/**
+ * Minimal stub of wp_upload_dir() used by CSS_Handler::is_writable().
+ *
+ * @param string|null $time Ignored.
+ * @param bool        $create_dir Ignored.
+ * @return array Upload dir data.
+ */
+function wp_upload_dir( $time = null, $create_dir = true ) {
+	return array(
+		'basedir' => sys_get_temp_dir(),
+		'baseurl' => 'http://example.org/wp-content/uploads',
+	);
+}
+
+/**
+ * No-op stub so class files can be loaded outside WordPress.
+ */
+function add_action() {}
+
+/**
+ * No-op stub so class files can be loaded outside WordPress.
+ */
+function add_filter() {}
+
+require $plugin_dir . '/inc/class-base-css.php';
+require $plugin_dir . '/inc/css/class-css-handler.php';
+
+$result = \ThemeIsle\GutenbergBlocks\CSS\CSS_Handler::is_writable();
+
+echo 'RESULT:' . var_export( $result, true ) . "\n"; // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export
+echo "REQUEST COMPLETED WITHOUT FATAL\n";
diff --git a/tests/test-css-handler.php b/tests/test-css-handler.php
new file mode 100644
index 000000000..1872d0dcf
--- /dev/null
+++ b/tests/test-css-handler.php
@@ -0,0 +1,50 @@
+<?php
+/**
+ * Class Test_CSS_Handler
+ *
+ * @package gutenberg-blocks
+ */
+
+use ThemeIsle\GutenbergBlocks\CSS\CSS_Handler;
+
+/**
+ * CSS_Handler filesystem tests.
+ *
+ * Regression coverage for https://github.com/Codeinwp/otter-blocks/issues/2937 —
+ * a frontend request fataled with "Call to undefined function WP_Filesystem()"
+ * because is_writable() called WP_Filesystem() before checking it exists.
+ */
+class Test_CSS_Handler extends WP_UnitTestCase {
+
+	/**
+	 * is_writable() must not fatal when WP_Filesystem() stays undefined after
+	 * including wp-admin/includes/file.php; it must fall back to `false` so the
+	 * frontend can use the inline CSS fallback.
+	 *
+	 * The scenario is impossible to create inside the loaded test environment
+	 * (WP_Filesystem() already exists), so the class is exercised in a separate
+	 * PHP process against a fake ABSPATH whose file.php defines nothing.
+	 */
+	public function test_is_writable_returns_false_when_wp_filesystem_is_unavailable() {
+		$sandbox = __DIR__ . '/php/is-writable-sandbox.php';
+
+		$command = escapeshellarg( PHP_BINARY ) . ' -d display_errors=1 ' . escapeshellarg( $sandbox ) . ' 2>&1';
+
+		exec( $command, $output, $exit_code ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.system_calls_exec
+
+		$output = implode( "\n", $output );
+
+		$this->assertSame( 0, $exit_code, 'The sandbox request fataled instead of degrading gracefully: ' . $output );
+		$this->assertStringContainsString( 'RESULT:false', $output, 'is_writable() should return false when WP_Filesystem() is unavailable: ' . $output );
+		$this->assertStringContainsString( 'REQUEST COMPLETED WITHOUT FATAL', $output );
+		$this->assertStringNotContainsString( 'Call to undefined function', $output );
+	}
+
+	/**
+	 * Sanity check: in a normal environment with a direct filesystem,
+	 * is_writable() still reports the upload dir as writable.
+	 */
+	public function test_is_writable_returns_true_in_normal_environment() {
+		$this->assertTrue( CSS_Handler::is_writable() );
+	}
+}