fix(fonts): preserve source stylesheet on Google Fonts cap overflow

Replace hard-fail with tagged-union return for resolve_google_font_faces()
and embed_font_sources(). On cap violation, emit assets/css/embedded-fonts.css
with original Google @import, surface font_materialization_partial_preserved
diagnostic with observed_bytes, limit_bytes, and url. Producer path unchanged.

Fixes #732

Author: faisalahammad

TESTING_INSTRUCTIONS.md

@@ -1,28 +1,63 @@
-# Testing Instructions: Restore Repository Lint Gate (#750)
+# Testing instructions for #732
 
-## What Changed
+## What changed
 
-1. Restored `review lint` alongside `review test` in the Homeboy CI matrix.
-2. Applied PHPCBF to current production PHP, resolving 4,021 mechanical findings introduced before the gate was restored.
-3. Recorded the remaining 237 findings in Homeboy's repository baseline so unchanged debt passes and new findings fail the gate.
-4. Removed the stale PHPStan baseline entry for the deleted transformer adapter.
-5. Dropped the unsupported second argument to `ArtifactCompiler::compile()` while retaining `compiler_options` as an explicitly diagnosed compatibility no-op.
-6. Preserved the resumable import and SVG font behavior merged after the contributor branch was opened.
+A valid compiler font plan that exceeds SSI's fixed Google Fonts byte caps (CSS > 256 KiB or aggregate woff2 > 4 MiB) used to hard-abort the entire import. Now the import falls back to a preserved `@import` of the original Google stylesheet and continues, with a diagnostic that reports the exact cap reason and observed bytes.
 
-## Verification
+## Install
+
+1. Back up your existing `wp-content/plugins/static-site-importer/` directory.
+2. Unzip `static-site-importer-fix-732.zip` over your WordPress install so the new files land at `wp-content/plugins/static-site-importer/`.
+3. Activate (or reactivate) **Static Site Importer** from **Plugins**.
+4. Make sure the **Blocks Engine** PHP transformer dependency is installed (`composer install` from the plugin root if not already).
+
+## Test 1: standalone smoke (headless)
+
+From the plugin root:
+
+```bash
+php tests/smoke-google-fonts-cap-fallback.php
+php tests/smoke-webfont-producer-consumer.php
+```
+
+The first new smoke covers CSS-too-large and aggregate-too-large fallbacks. The second is the producer-path regression sentinel and must still pass.
+
+## Test 2: full fast lane
 
 ```bash
-homeboy review lint --summary
 npm test
-for file in static-site-importer.php includes/*.php; do php -l "$file" >/dev/null || exit 1; done
+npm run test:inventory
+```
+
+A pre-existing failure in `tests/smoke-url-batch-import.php` is unrelated to this fix.
+
+## Test 3: end-to-end repro (per issue)
+
+The issue repro is the fixture matrix against `29-multilingual-i18n`. The expected behavior changes:
+
+```sh
+node tools/run-fixture-matrix.mjs --local --static-site-importer <path-to-this-plugin> --blocks-engine <path-to-blocks-engine> --target-fixture 29-multilingual-i18n --surface-coverage 7 --wp-codebox-bin <path-to-wp-codebox/bin/wp-codebox-source.mjs> --allow-stale-override --skip-install --skip-sync
 ```
 
-Expected results:
+What to look for:
+
+- The matrix output must NOT contain `static_site_importer_font_materialization_failed`.
+- The static front page is created.
+- Browser surfaces (Chrome/SVG parity surfaces) render text using the Noto Sans JP / Noto Naskh Arabic families.
+- The Homeboy evidence run shows a `font_materialization_partial_preserved` diagnostic with one of these inner reasons: `google_fonts_stylesheet_preserved_due_to_size` (CSS > 256 KiB) or `google_fonts_payloads_partial_preserved` (aggregate woff2 > 4 MiB). The diagnostic's `details.observed_bytes`, `details.limit_bytes`, and `details.url` fields should be populated.
+
+## Test 4: happy path regression
+
+Run a small Google Fonts fixture (1 family, 1 weight) through any normal import path. Embedded font asset should still be downloaded and embedded as a `data:font/woff2;base64,…` URL inside `assets/css/embedded-fonts.css`. No `font_materialization_partial_preserved` diagnostic should appear.
+
+## Rollback
+
+If something goes wrong, deactivate the plugin and restore the backup from step 1 of Install.
 
-- Homeboy lint passes with no drift from the 237-finding baseline.
-- The test manifest passes 42 selected checks: 34 standalone PHP and eight Node lanes.
-- Every production PHP file passes syntax validation.
+## Files touched in this fix
 
-## Ratcheting
+- `includes/class-static-site-importer-font-materializer.php` — return shape change in `resolve_google_font_faces()` and `embed_font_sources()`; new preservation branch in `prepare_overlay()`; new `diagnostic_with_detail()` helper
+- `tests/smoke-google-fonts-cap-fallback.php` — new standalone PHP smoke
+- `test-manifest.json`, `homeboy-test-manifest.json` — registered the new smoke
 
-When existing findings are repaired, run `homeboy review lint --ratchet` to remove resolved fingerprints from `homeboy.json`. New findings fail CI without requiring the existing debt to be repaired in the same change.
+Producer path (`materialize_producer_faces`) is untouched.

homeboy-test-manifest.json

@@ -31,6 +31,7 @@
     "tests/smoke-validation-runtime-diagnostics.php": { "environment": "standalone-php" },
     "tests/smoke-visual-repair-css.php": { "environment": "standalone-php" },
     "tests/smoke-webfont-producer-consumer.php": { "environment": "standalone-php" },
+    "tests/smoke-google-fonts-cap-fallback.php": { "environment": "standalone-php" },
     "tests/smoke-website-artifact-import-input.php": { "environment": "standalone-php" },
     "tests/smoke-wordpress-site-plan-materializer.php": { "environment": "standalone-php" },
     "tests/smoke-artifact-run-primitives.php": { "environment": "standalone-php" },

includes/class-static-site-importer-font-materializer.php

@@ -78,15 +78,63 @@ public static function prepare_overlay( array $plan, array $resolved_plan ) {
 		}
 
 		$font_faces = self::resolve_google_font_faces( $plan, $families, $diagnostics );
-		if ( '' === $font_faces ) {
+		if ( is_array( $font_faces ) && isset( $font_faces['state'] ) && 'preserved' === $font_faces['state'] ) {
+			$preserved_url  = (string) ( $font_faces['url'] ?? '' );
+			$fallback_url   = self::is_google_stylesheet_url( $preserved_url ) ? $preserved_url : '';
+			$imports        = array();
+			foreach ( $plan['stylesheets'] ?? array() as $stylesheet ) {
+				$content = is_array( $stylesheet ) && is_scalar( $stylesheet['content'] ?? null ) ? (string) $stylesheet['content'] : '';
+				if ( preg_match_all( '/@import\s+(?:url\()?\s*["\']?([^"\'\s\)]+)["\']?\s*\)?/i', $content, $matches ) ) {
+					foreach ( $matches[1] as $candidate ) {
+						if ( self::is_google_stylesheet_url( $candidate ) ) {
+							$imports[] = $candidate;
+						}
+					}
+				}
+			}
+			$imports = array_values( array_unique( $imports ) );
+			if ( '' === $fallback_url && ! empty( $imports ) ) {
+				$fallback_url = $imports[0];
+			}
+			$css_lines = array();
+			foreach ( $imports as $import_url ) {
+				$css_lines[] = '@import "' . addcslashes( $import_url, "\"\\\n" ) . '";';
+			}
+			if ( empty( $css_lines ) && '' !== $fallback_url ) {
+				$css_lines[] = '@import "' . addcslashes( $fallback_url, "\"\\\n" ) . '";';
+			}
+			$css_body = empty( $css_lines ) ? '' : trim( implode( "\n", $css_lines ) ) . "\n";
+			$outer_detail = array(
+				'reason'         => (string) ( $font_faces['reason'] ?? '' ),
+				'observed_bytes' => (int) ( $font_faces['observed_bytes'] ?? 0 ),
+				'url'            => $preserved_url,
+			);
+			if ( 'google_fonts_payloads_partial_preserved' === $outer_detail['reason'] ) {
+				$outer_detail['limit_bytes']     = self::TOTAL_FONT_LIMIT;
+				$outer_detail['aggregate_bytes'] = (int) ( $font_faces['aggregate_bytes'] ?? $font_faces['observed_bytes'] );
+			} elseif ( 'google_fonts_stylesheet_preserved_due_to_size' === $outer_detail['reason'] ) {
+				$outer_detail['limit_bytes'] = self::CSS_LIMIT;
+			}
+			$diagnostics[] = self::diagnostic_with_detail( 'font_materialization_partial_preserved', $outer_detail );
+			if ( '' === $css_body ) {
+				return new WP_Error( 'static_site_importer_font_materialization_failed', '', $diagnostics );
+			}
+			$writes[] = self::write( 'assets/css/embedded-fonts.css', $css_body, 'theme.font_materialization' );
+			return self::with_runtime_registration( $writes, $resolved_plan, array(), $diagnostics );
+		}
+		if ( is_array( $font_faces ) && isset( $font_faces['state'] ) && 'embedded' === $font_faces['state'] ) {
+			$embedded_css = (string) ( $font_faces['css'] ?? '' );
+		} else {
+			$embedded_css = is_string( $font_faces ) ? $font_faces : '';
+		}
+		if ( '' === trim( $embedded_css ) ) {
 			return new WP_Error( 'static_site_importer_font_materialization_failed', '', $diagnostics );
 		}
-
-		$writes[] = self::write( 'assets/css/embedded-fonts.css', trim( $font_faces ) . "\n", 'theme.font_materialization' );
+		$writes[] = self::write( 'assets/css/embedded-fonts.css', trim( $embedded_css ) . "\n", 'theme.font_materialization' );
 		foreach ( $svg_writes as $svg_write ) {
 			$writes[] = self::write(
 				$svg_write['target_path'],
-				self::embed_svg_font_faces( $svg_write['content'], $font_faces ),
+				self::embed_svg_font_faces( $svg_write['content'], $embedded_css ),
 				$svg_write['source_path']
 			);
 		}
@@ -532,8 +580,10 @@ private static function matching_svg_writes( array $writes, array $families ): a
 		return $matches;
 	}
 
-	/** @param array<int,string> $families @param array<int,array<string,string>> $diagnostics */
-	private static function resolve_google_font_faces( array $plan, array $families, array &$diagnostics ): string {
+	/** @param array<int,string> $families @param array<int,array<string,string>> $diagnostics
+	 *  @return array{state:'embedded',css:string}|array{state:'preserved',reason:string,observed_bytes:int,url:string}
+	 */
+	private static function resolve_google_font_faces( array $plan, array $families, array &$diagnostics ): array {
 		$imports = array();
 		foreach ( $plan['stylesheets'] ?? array() as $stylesheet ) {
 			$content = is_array( $stylesheet ) && is_scalar( $stylesheet['content'] ?? null ) ? (string) $stylesheet['content'] : '';
@@ -544,12 +594,12 @@ private static function resolve_google_font_faces( array $plan, array $families,
 		$imports = array_values( array_unique( $imports ) );
 		if ( empty( $imports ) ) {
 			$diagnostics[] = self::diagnostic( 'stylesheet_import_missing' );
-			return '';
+			return array( 'state' => 'preserved', 'reason' => 'stylesheet_import_missing', 'observed_bytes' => 0, 'url' => '' );
 		}
 		foreach ( $imports as $import ) {
 			if ( ! self::is_google_stylesheet_url( $import ) ) {
 				$diagnostics[] = self::diagnostic( 'untrusted_stylesheet_url' );
-				return '';
+				return array( 'state' => 'preserved', 'reason' => 'untrusted_stylesheet_url', 'observed_bytes' => 0, 'url' => (string) $import );
 			}
 		}
 
@@ -560,58 +610,67 @@ private static function resolve_google_font_faces( array $plan, array $families,
 			$response = self::request( $import, self::CSS_LIMIT );
 			$css      = is_wp_error( $response ) ? '' : (string) wp_remote_retrieve_body( $response );
 			if ( is_wp_error( $response ) || 200 !== (int) wp_remote_retrieve_response_code( $response ) || '' === $css ) {
-				$diagnostics[] = self::diagnostic( 'stylesheet_fetch_failed' );
-				return '';
+				$diagnostics[] = self::diagnostic_with_detail( 'stylesheet_fetch_failed', array( 'url' => $import, 'observed_bytes' => strlen( $css ), 'limit_bytes' => self::CSS_LIMIT ) );
+				return array( 'state' => 'preserved', 'reason' => 'stylesheet_fetch_failed', 'observed_bytes' => strlen( $css ), 'url' => $import );
 			}
 			if ( strlen( $css ) > self::CSS_LIMIT ) {
-				$diagnostics[] = self::diagnostic( 'stylesheet_response_too_large' );
-				return '';
+				$diagnostics[] = self::diagnostic_with_detail( 'google_fonts_stylesheet_preserved_due_to_size', array( 'url' => $import, 'observed_bytes' => strlen( $css ), 'limit_bytes' => self::CSS_LIMIT ) );
+				return array( 'state' => 'preserved', 'reason' => 'google_fonts_stylesheet_preserved_due_to_size', 'observed_bytes' => strlen( $css ), 'url' => $import );
 			}
 			$embedded = self::embed_font_sources( $css, $families, $font_payloads, $font_payload_bytes, $diagnostics );
-			if ( '' === $embedded ) {
-				return '';
+			if ( is_array( $embedded ) && isset( $embedded['state'] ) && 'preserved' === $embedded['state'] ) {
+				if ( '' === (string) ( $embedded['url'] ?? '' ) ) {
+					$embedded['url'] = $import;
+				}
+				return $embedded;
 			}
-			$faces[] = $embedded;
+			$faces[] = is_array( $embedded ) ? (string) ( $embedded['css'] ?? '' ) : (string) $embedded;
 		}
-		return implode( "\n", $faces );
+		return array( 'state' => 'embedded', 'css' => implode( "\n", $faces ) );
 	}
 
-	/** @param array<int,string> $families @param array<string,string> $payloads @param array<int,array<string,string>> $diagnostics */
-	private static function embed_font_sources( string $css, array $families, array &$payloads, int &$payload_bytes, array &$diagnostics ): string {
+	/** @param array<int,string> $families @param array<string,string> $payloads @param array<int,array<string,string>> $diagnostics
+	 *  @return array{state:'embedded',css:string}|array{state:'preserved',reason:string,observed_bytes:int,url:string}
+	 */
+	private static function embed_font_sources( string $css, array $families, array &$payloads, int &$payload_bytes, array &$diagnostics ): array {
 		if ( ! preg_match_all( '/@font-face\s*\{([^{}]*)\}/is', $css, $faces ) ) {
-			$diagnostics[] = self::diagnostic( 'stylesheet_font_faces_missing' );
-			return '';
+			$diagnostics[] = self::diagnostic_with_detail( 'stylesheet_font_faces_missing', array( 'observed_bytes' => strlen( $css ), 'limit_bytes' => self::CSS_LIMIT ) );
+			return array( 'state' => 'preserved', 'reason' => 'stylesheet_font_faces_missing', 'observed_bytes' => strlen( $css ), 'url' => '' );
 		}
-		$embedded = array();
+		$embedded          = array();
+		$current_source_url = '';
 		foreach ( $faces[0] as $index => $face ) {
+			$current_source_url = '';
 			if ( ! preg_match( '/font-family\s*:\s*(["\']?)([^;"\']+)\1\s*;/i', $faces[1][ $index ], $family ) || ! in_array( trim( $family[2] ), $families, true ) ) {
 				continue;
 			}
 			if ( str_contains( $face, '<' ) || ! preg_match_all( '/url\(\s*(["\']?)([^"\'\s\)]+)\1\s*\)/i', $face, $urls ) ) {
 				$diagnostics[] = self::diagnostic( 'untrusted_font_url' );
-				return '';
+				return array( 'state' => 'preserved', 'reason' => 'untrusted_font_url', 'observed_bytes' => 0, 'url' => $current_source_url );
 			}
 			$rewritten = $face;
 			foreach ( array_unique( $urls[2] ) as $url ) {
+				$current_source_url = $url;
 				$parts = wp_parse_url( $url );
 				$path  = is_array( $parts ) ? strtolower( (string) ( $parts['path'] ?? '' ) ) : '';
 				if ( ! is_array( $parts ) || 'https' !== strtolower( (string) ( $parts['scheme'] ?? '' ) ) || 'fonts.gstatic.com' !== strtolower( (string) ( $parts['host'] ?? '' ) ) || ( isset( $parts['port'] ) && 443 !== (int) $parts['port'] ) || isset( $parts['user'] ) || isset( $parts['pass'] ) || ! preg_match( '/\.woff2?$/', $path ) ) {
 					$diagnostics[] = self::diagnostic( 'untrusted_font_url' );
-					return '';
+					return array( 'state' => 'preserved', 'reason' => 'untrusted_font_url', 'observed_bytes' => 0, 'url' => $url );
 				}
 				if ( ! isset( $payloads[ $url ] ) ) {
 					$response = self::request( $url, self::FONT_LIMIT );
 					$payload  = is_wp_error( $response ) ? '' : (string) wp_remote_retrieve_body( $response );
-					if ( is_wp_error( $response ) || 200 !== (int) wp_remote_retrieve_response_code( $response ) || '' === $payload || strlen( $payload ) > self::FONT_LIMIT ) {
-						$diagnostics[] = self::diagnostic( 'font_payload_fetch_failed' );
-						return '';
+					$observed = strlen( $payload );
+					if ( is_wp_error( $response ) || 200 !== (int) wp_remote_retrieve_response_code( $response ) || '' === $payload || $observed > self::FONT_LIMIT ) {
+						$diagnostics[] = self::diagnostic_with_detail( 'font_payload_fetch_failed', array( 'url' => $url, 'observed_bytes' => $observed, 'limit_bytes' => self::FONT_LIMIT ) );
+						return array( 'state' => 'preserved', 'reason' => 'font_payload_fetch_failed', 'observed_bytes' => $observed, 'url' => $url );
 					}
-					if ( self::TOTAL_FONT_LIMIT < $payload_bytes + strlen( $payload ) ) {
-						$diagnostics[] = self::diagnostic( 'font_payload_total_too_large' );
-						return '';
+					if ( self::TOTAL_FONT_LIMIT < $payload_bytes + $observed ) {
+						$diagnostics[] = self::diagnostic_with_detail( 'google_fonts_payloads_partial_preserved', array( 'url' => $url, 'observed_bytes' => $observed, 'aggregate_bytes' => $payload_bytes, 'limit_bytes' => self::TOTAL_FONT_LIMIT ) );
+						return array( 'state' => 'preserved', 'reason' => 'google_fonts_payloads_partial_preserved', 'observed_bytes' => $observed, 'aggregate_bytes' => $payload_bytes, 'url' => $url );
 					}
 					$payloads[ $url ] = $payload;
-					$payload_bytes   += strlen( $payload );
+					$payload_bytes   += $observed;
 				}
 				$mime      = str_ends_with( $path, '.woff2' ) ? 'font/woff2' : 'font/woff';
 				$rewritten = str_replace( $url, 'data:' . $mime . ';base64,' . base64_encode( $payloads[ $url ] ), $rewritten ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode -- Encodes a fetched font asset for a CSS data URL.
@@ -621,7 +680,7 @@ private static function embed_font_sources( string $css, array $families, array
 		if ( empty( $embedded ) ) {
 			$diagnostics[] = self::diagnostic( 'matching_font_faces_missing' );
 		}
-		return implode( "\n", $embedded );
+		return array( 'state' => 'embedded', 'css' => implode( "\n", $embedded ) );
 	}
 
 	private static function request( string $url, int $limit ) {
@@ -828,4 +887,14 @@ private static function diagnostic( string $reason ): array {
 			'reason' => $reason,
 		);
 	}
+
+	/** @return array{type:string,source:string,reason:string,details:array<string,mixed>} */
+	private static function diagnostic_with_detail( string $reason, array $details ): array {
+		return array(
+			'type'    => 'font_materialization_failed',
+			'source'  => 'static-site-importer/font-materializer',
+			'reason'  => $reason,
+			'details' => $details,
+		);
+	}
 }

test-manifest.json

@@ -35,6 +35,7 @@
     { "path": "tests/smoke-validation-runtime-diagnostics.php", "environment": "standalone-php" },
     { "path": "tests/smoke-visual-repair-css.php", "environment": "standalone-php" },
     { "path": "tests/smoke-webfont-producer-consumer.php", "environment": "standalone-php" },
+    { "path": "tests/smoke-google-fonts-cap-fallback.php", "environment": "standalone-php" },
     { "path": "tests/smoke-website-artifact-import-input.php", "environment": "standalone-php" },
     { "path": "tests/smoke-wordpress-site-plan-materializer.php", "environment": "standalone-php" },
     { "path": "tests/smoke-artifact-run-primitives.php", "environment": "standalone-php" },