class-static-site-importer-theme-materializer.php

<?php
/**
 * Theme file materialization helpers.
 *
 * @package StaticSiteImporter
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Writes generated theme artifacts to disk.
 */
class Static_Site_Importer_Theme_Materializer {

	/**
	 * Build static generated theme file writes.
	 *
	 * @param string $theme_dir       Theme directory.
	 * @param string $theme_slug      Theme slug.
	 * @param string $theme_name      Theme name.
	 * @param string $css             Source CSS.
	 * @param bool   $has_header_part Whether a header template part exists.
	 * @param bool   $has_footer_part Whether a footer template part exists.
	 * @param array<int,array<string,mixed>> $scripts     Materialized script asset rows.
	 * @param array<int,array<string,mixed>> $stylesheets Materialized stylesheet asset rows.
	 * @param array<string,mixed>            $artifacts   Compiled website artifacts.
	 * @return array<string,string> Absolute write paths mapped to file contents.
	 */
	public static function base_theme_writes( string $theme_dir, string $theme_slug, string $theme_name, string $css, bool $has_header_part, bool $has_footer_part, array $scripts = array(), array $stylesheets = array(), array $artifacts = array() ): array {
		return array(
			$theme_dir . '/functions.php'             => self::functions_php( $theme_slug, $scripts, $stylesheets ),
			$theme_dir . '/theme.json'                => self::theme_json( $theme_name, $css, $artifacts ),
			$theme_dir . '/templates/404.html'        => self::not_found_template( $has_header_part, $has_footer_part ),
			$theme_dir . '/templates/archive.html'    => self::archive_template( $has_header_part, $has_footer_part ),
			$theme_dir . '/templates/front-page.html' => self::content_template( '', $has_header_part, $has_footer_part ),
			$theme_dir . '/templates/page.html'       => self::content_template( '', $has_header_part, $has_footer_part ),
			$theme_dir . '/templates/index.html'      => self::content_template( '', $has_header_part, $has_footer_part ),
		);
	}

	/**
	 * Build the generated archive template.
	 *
	 * @param bool $has_header_part Whether a shared header template part was generated.
	 * @param bool $has_footer_part Whether a shared footer template part was generated.
	 * @return string
	 */
	private static function archive_template( bool $has_header_part, bool $has_footer_part ): string {
		return self::content_template( '', $has_header_part, $has_footer_part );
	}

	/**
	 * Build the generated 404 template.
	 *
	 * @param bool $has_header_part Whether a shared header template part was generated.
	 * @param bool $has_footer_part Whether a shared footer template part was generated.
	 * @return string
	 */
	private static function not_found_template( bool $has_header_part, bool $has_footer_part ): string {
		$body = '<!-- wp:heading {"level":1} --><h1 class="wp-block-heading">Page not found</h1><!-- /wp:heading -->' . "\n\n" .
			'<!-- wp:paragraph --><p>The requested page could not be found.</p><!-- /wp:paragraph -->';

		return self::content_template( $body, $has_header_part, $has_footer_part );
	}

	/**
	 * Build a template that renders imported page content.
	 *
	 * @param string $background_blocks Background decoration blocks.
	 * @param bool   $has_header_part   Whether a shared header template part was generated.
	 * @param bool   $has_footer_part   Whether a shared footer template part was generated.
	 * @return string
	 */
	public static function content_template( string $background_blocks, bool $has_header_part, bool $has_footer_part ): string {
		$header_part = $has_header_part ? '<!-- wp:template-part {"slug":"header","tagName":"header"} /-->' : '';
		$footer_part = $has_footer_part ? '<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->' : '';

		return trim(
			$header_part . "\n\n" .
			$background_blocks . "\n\n" .
			'<!-- wp:post-content /-->' . "\n\n" .
			$footer_part
		) . "\n";
	}

	/**
	 * Build a theme pattern file for an imported page body.
	 *
	 * @param string $title        Pattern title.
	 * @param string $pattern_slug Pattern slug.
	 * @param string $content      Block markup.
	 * @return string
	 */
	public static function pattern_file( string $title, string $pattern_slug, string $content ): string {
		return "<?php\n" .
			"/**\n" .
			' * Title: ' . $title . "\n" .
			' * Slug: ' . $pattern_slug . "\n" .
			" * Categories: static-site-importer\n" .
			" */\n" .
			"?>\n" .
			trim( $content ) . "\n";
	}

	/**
	 * Ensure theme directories exist.
	 *
	 * @param string $theme_dir Theme directory.
	 * @return true|WP_Error
	 */
	public static function ensure_dirs( string $theme_dir ) {
		foreach ( array( $theme_dir, $theme_dir . '/templates', $theme_dir . '/parts', $theme_dir . '/patterns', $theme_dir . '/assets', $theme_dir . '/assets/css', $theme_dir . '/assets/icons', $theme_dir . '/assets/media' ) as $dir ) {
			if ( ! wp_mkdir_p( $dir ) ) {
				return new WP_Error( 'static_site_importer_mkdir_failed', sprintf( 'Failed to create directory: %s', $dir ) );
			}
		}

		return true;
	}

	/**
	 * Write compiler-emitted files that can be consumed without re-importing HTML.
	 *
	 * @param string              $theme_dir Theme directory.
	 * @param string              $theme_uri Theme URI.
	 * @param array<string,mixed> $artifacts WordPress artifacts from Blocks Engine.
	 * @param bool                $write_files Whether to write materialized asset files.
	 * @param string              $svg_font_usage_markup Bounded page SVG candidates that can be promoted.
	 * @return array{css:string,js:string,assets:array<string,array<string,mixed>>,scripts:array<int,array<string,mixed>>,stylesheets:array<int,array<string,mixed>>,diagnostics:array<int,array<string,mixed>>}|WP_Error
	 */
	public static function materialize_website_artifact_files( string $theme_dir, string $theme_uri, array $artifacts, bool $write_files = true, string $svg_font_usage_markup = '' ) {
		$native_plan = self::materialize_materialization_plan_assets( $theme_dir, $theme_uri, $artifacts, $write_files, $svg_font_usage_markup );
		if ( is_wp_error( $native_plan ) || null !== $native_plan ) {
			return $native_plan;
		}

		$files = isset( $artifacts['files'] ) && is_array( $artifacts['files'] ) ? $artifacts['files'] : array();
		if ( isset( $artifacts['source_files'] ) && is_array( $artifacts['source_files'] ) ) {
			$files = array_merge( $files, $artifacts['source_files'] );
		}
		$css         = array();
		$assets      = array();
		$diagnostics = array();

		foreach ( $files as $file ) {
			if ( ! is_array( $file ) ) {
				continue;
			}

			$relative  = self::normalize_artifact_materialization_path( isset( $file['path'] ) ? (string) $file['path'] : '' );
			$retention = self::source_retention_policy( $file, $relative, 'website_artifact:files' );
			if ( '' === $relative ) {
				$diagnostics[] = array(
					'type'    => 'website_artifact_file_skipped',
					'source'  => 'website_artifact:files',
					'reason'  => 'unsafe_artifact_path',
					'path'    => isset( $file['path'] ) && is_scalar( $file['path'] ) ? (string) $file['path'] : '',
					'message' => 'A website artifact file was skipped because its path is not safe to materialize inside the generated theme.',
				);
				continue;
			}
			if ( isset( $retention['diagnostic'] ) ) {
				$diagnostics[] = $retention['diagnostic'];
			}

			$content = self::materialization_plan_asset_content( $file, $relative );
			if ( is_wp_error( $content ) ) {
				return $content;
			}
			$kind  = isset( $file['kind'] ) ? (string) $file['kind'] : '';
			$lower = strtolower( $relative );
			if ( 'css' === $kind || str_ends_with( $lower, '.css' ) ) {
				$css[] = trim( $content );
				continue;
			}
			if ( 'js' === $kind || str_ends_with( $lower, '.js' ) ) {
				$js[] = trim( $content );
				continue;
			}

			$target_relative = 'assets/materialized/' . $relative;
			$target          = trailingslashit( $theme_dir ) . $target_relative;
			if ( $write_files ) {
				$dir = dirname( $target );
				if ( ! wp_mkdir_p( $dir ) ) {
					return new WP_Error( 'static_site_importer_artifact_asset_mkdir_failed', sprintf( 'Failed to create website artifact asset directory: %s', $dir ) );
				}

				$result = self::write_file( $target, $content );
				if ( is_wp_error( $result ) ) {
					return $result;
				}
			}

			$assets[ $relative ] = array(
				'source'           => $relative,
				'path'             => $relative,
				'url'              => trailingslashit( $theme_uri ) . $target_relative,
				'final_url'        => trailingslashit( $theme_uri ) . $target_relative,
				'mime_type'        => self::mime_type( $target ),
				'theme_path'       => $target_relative,
				'policy'           => 'theme',
				'source_role'      => $retention['source_role'],
				'keep_source'      => $retention['keep_source'],
				'deletion_allowed' => $retention['deletion_allowed'],
			);
		}

		return array(
			'css'         => trim( implode( "\n\n", array_filter( $css ) ) ),
			'js'          => '',
			'assets'      => $assets,
			'scripts'     => array(),
			'stylesheets' => array(),
			'diagnostics' => $diagnostics,
		);
	}

	/**
	 * Write native Blocks Engine asset materialization rows when the plan carries payloads.
	 *
	 * @param string              $theme_dir Theme directory.
	 * @param string              $theme_uri Theme URI.
	 * @param array<string,mixed> $artifacts WordPress artifacts from Blocks Engine.
	 * @param bool                $write_files Whether to write materialized asset files.
	 * @return array{css:string,js:string,assets:array<string,array<string,mixed>>,scripts:array<int,array<string,mixed>>,stylesheets:array<int,array<string,mixed>>,diagnostics:array<int,array<string,mixed>>}|null|WP_Error
	 */
	private static function materialize_materialization_plan_assets( string $theme_dir, string $theme_uri, array $artifacts, bool $write_files = true, string $svg_font_usage_markup = '' ) {
		$site = isset( $artifacts['site'] ) && is_array( $artifacts['site'] ) ? $artifacts['site'] : array();
		if ( 'blocks-engine/php-transformer/materialization-plan/v1' !== (string) ( $site['schema'] ?? '' ) || ! array_key_exists( 'assets', $site ) ) {
			return null;
		}

		if ( ! is_array( $site['assets'] ) ) {
			return new WP_Error( 'static_site_importer_materialization_plan_assets_invalid', 'Blocks Engine materialization_plan.assets must be an array.' );
		}

		if ( ! self::materialization_plan_assets_include_payloads( $site['assets'] ) ) {
			return null;
		}

		$css         = array();
		$assets      = array();
		$scripts     = array();
		$stylesheets = array();
		$diagnostics = array();
		$order       = 0;
		$svg_candidates = array_merge( $site['assets'], isset( $artifacts['files'] ) && is_array( $artifacts['files'] ) ? $artifacts['files'] : array(), isset( $artifacts['source_files'] ) && is_array( $artifacts['source_files'] ) ? $artifacts['source_files'] : array() );
		$svg_font_faces = self::google_font_faces_for_svg_assets( $site, $svg_candidates, $diagnostics, $svg_font_usage_markup );

		foreach ( $site['assets'] as $asset ) {
			if ( ! is_array( $asset ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_asset_invalid', 'Blocks Engine materialization_plan.assets entries must be arrays.' );
			}

			$relative  = self::normalize_artifact_materialization_path( isset( $asset['path'] ) && is_scalar( $asset['path'] ) ? (string) $asset['path'] : '' );
			$retention = self::source_retention_policy( $asset, $relative, 'materialization_plan.assets' );
			if ( '' === $relative ) {
				return new WP_Error( 'static_site_importer_materialization_plan_asset_path_invalid', 'Blocks Engine materialization_plan.assets entries must include safe relative paths.' );
			}
			if ( isset( $retention['diagnostic'] ) ) {
				$diagnostics[] = $retention['diagnostic'];
			}

			$content = self::materialization_plan_asset_content( $asset, $relative );
			if ( is_wp_error( $content ) ) {
				return $content;
			}

			$kind  = isset( $asset['kind'] ) && is_scalar( $asset['kind'] ) ? (string) $asset['kind'] : '';
			$role  = isset( $asset['role'] ) && is_scalar( $asset['role'] ) ? (string) $asset['role'] : '';
			$lower = strtolower( $relative );
			if ( 'html' === $kind || str_ends_with( $lower, '.html' ) || str_ends_with( $lower, '.htm' ) ) {
				continue;
			}
			if ( '' !== $svg_font_faces && self::is_svg_asset( $asset, $relative ) ) {
				$content = self::embed_svg_font_faces( $content, $svg_font_faces );
			}
			++$order;

			$target_relative = 'assets/materialized/' . $relative;
			$target          = trailingslashit( $theme_dir ) . $target_relative;
			if ( $write_files ) {
				$dir = dirname( $target );
				if ( ! wp_mkdir_p( $dir ) ) {
					return new WP_Error( 'static_site_importer_materialization_plan_asset_mkdir_failed', sprintf( 'Failed to create materialization-plan asset directory: %s', $dir ) );
				}

				$result = self::write_file( $target, $content );
				if ( is_wp_error( $result ) ) {
					return $result;
				}
			}

			$assets[ $relative ] = self::materialization_plan_asset_report( $asset, $relative, trailingslashit( $theme_uri ) . $target_relative, $target_relative, self::mime_type( $target ), $order, $retention );

			if ( 'css' === $kind || 'stylesheet' === $role || str_ends_with( $lower, '.css' ) ) {
				$css[] = array(
					'path'    => $relative,
					'content' => trim( $content ),
				);
				$stylesheets[] = $assets[ $relative ];
				continue;
			}
			if ( 'js' === $kind || 'script' === $role || str_ends_with( $lower, '.js' ) ) {
				$scripts[] = $assets[ $relative ];
				continue;
			}
		}

		$supplemental = self::materialize_supplemental_artifact_file_assets( $theme_dir, $theme_uri, $artifacts, $assets, $order, $write_files, $svg_font_faces );
		if ( is_wp_error( $supplemental ) ) {
			return $supplemental;
		}
		foreach ( $supplemental['diagnostics'] as $diagnostic ) {
			$diagnostics[] = $diagnostic;
		}

		$font_stylesheets = self::materialize_font_materialization_stylesheets( $theme_dir, $theme_uri, $site, $assets, $order, $write_files, $svg_font_faces );
		if ( is_wp_error( $font_stylesheets ) ) {
			return $font_stylesheets;
		}
		$stylesheets = array_merge( $font_stylesheets, $stylesheets );

		return array(
			'css'         => trim( implode( "\n\n", array_filter( self::rewrite_materialized_css_chunks( $css, $assets ) ) ) ),
			'js'          => '',
			'assets'      => $assets,
			'scripts'     => $scripts,
			'stylesheets' => $stylesheets,
			'diagnostics' => $diagnostics,
			'svg_font_faces' => $svg_font_faces,
		);
	}

	/**
	 * Resolve trusted Google Fonts plan imports to CSS that external SVG images can use.
	 *
	 * @param array<string,mixed>               $site        Materialization plan site artifact.
	 * @param array<int,array<string,mixed>>    $assets      Candidate compiler asset rows.
	 * @param array<int,array<string,mixed>>    $diagnostics Diagnostics, passed by reference.
	 * @return string Self-contained @font-face CSS, or an empty string.
	 */
	private static function google_font_faces_for_svg_assets( array $site, array $assets, array &$diagnostics, string $svg_font_usage_markup = '' ): string {
		$plan = isset( $site['theme']['font_materialization'] ) && is_array( $site['theme']['font_materialization'] ) ? $site['theme']['font_materialization'] : array();
		if ( 'blocks-engine/php-transformer/font-materialization-plan/v1' !== (string) ( $plan['schema'] ?? '' ) || 'google_fonts' !== (string) ( $plan['provider'] ?? '' ) || empty( $plan['fonts'] ) || ! is_array( $plan['fonts'] ) ) {
			return '';
		}

		$families = self::google_font_plan_families( $plan['fonts'] );
		if ( empty( $families ) ) {
			return '';
		}
		$has_matching_svg = false;
		foreach ( $assets as $asset ) {
			if ( ! is_array( $asset ) || ! self::is_svg_asset( $asset, isset( $asset['path'] ) && is_scalar( $asset['path'] ) ? (string) $asset['path'] : '' ) ) {
				continue;
			}
			$content = isset( $asset['content'] ) && is_scalar( $asset['content'] ) ? (string) $asset['content'] : '';
			if ( self::svg_uses_font_family( $content, $families ) ) {
				$has_matching_svg = true;
				break;
			}
		}
		if ( ! $has_matching_svg && self::svg_uses_font_family( $svg_font_usage_markup, $families ) ) {
			$has_matching_svg = true;
		}
		if ( ! $has_matching_svg ) {
			return '';
		}

		$imports = array();
		foreach ( isset( $plan['stylesheets'] ) && is_array( $plan['stylesheets'] ) ? $plan['stylesheets'] : array() as $stylesheet ) {
			$content = is_array( $stylesheet ) && isset( $stylesheet['content'] ) && is_scalar( $stylesheet['content'] ) ? (string) $stylesheet['content'] : '';
			if ( preg_match_all( '/@import\s+(?:url\()?\s*["\']?([^"\'\s\)]+)["\']?\s*\)?/i', $content, $matches ) ) {
				$imports = array_merge( $imports, $matches[1] );
			}
		}
		$imports = array_values( array_unique( $imports ) );
		if ( empty( $imports ) ) {
			$diagnostics[] = self::google_font_svg_diagnostic( 'stylesheet_import_missing', 'No Google Fonts stylesheet import was available for SVG font embedding.' );
			return '';
		}
		foreach ( $imports as $import ) {
			if ( ! self::is_google_fonts_stylesheet_url( $import ) ) {
				$diagnostics[] = self::google_font_svg_diagnostic( 'untrusted_stylesheet_url', 'Every stylesheet import must be an allowlisted Google Fonts CSS endpoint before SVG font embedding can begin.' );
				return '';
			}
		}

		$faces = array();
		$font_payloads = array();
		$font_payload_bytes = 0;
		foreach ( $imports as $import ) {
			$response = self::bounded_google_font_request( $import, 262144 );
			if ( is_wp_error( $response ) || 200 !== (int) wp_remote_retrieve_response_code( $response ) ) {
				$diagnostics[] = self::google_font_svg_diagnostic( 'stylesheet_fetch_failed', 'The allowlisted Google Fonts stylesheet could not be fetched for SVG embedding.' );
				return '';
			}
			$css = (string) wp_remote_retrieve_body( $response );
			if ( strlen( $css ) > 262144 ) {
				$diagnostics[] = self::google_font_svg_diagnostic( 'stylesheet_response_too_large', 'The Google Fonts stylesheet exceeded the SVG font embedding response limit.' );
				return '';
			}
			$embedded = self::embed_google_font_face_sources( $css, $families, $diagnostics, $font_payloads, $font_payload_bytes );
			if ( '' === $embedded ) {
				return '';
			}
			$faces[] = $embedded;
		}

		return implode( "\n", $faces );
	}

	/** @param array<int,mixed> $fonts @return array<int,string> */
	private static function google_font_plan_families( array $fonts ): array {
		$families = array();
		foreach ( $fonts as $font ) {
			$family = is_array( $font ) ? ( $font['family'] ?? $font['font_family'] ?? '' ) : $font;
			if ( is_scalar( $family ) && '' !== trim( (string) $family ) ) {
				$families[] = trim( (string) $family );
			}
		}
		return array_values( array_unique( $families ) );
	}

	private static function is_google_fonts_stylesheet_url( string $url ): bool {
		$parts = wp_parse_url( $url );
		return is_array( $parts ) && 'https' === strtolower( (string) ( $parts['scheme'] ?? '' ) ) && 'fonts.googleapis.com' === strtolower( (string) ( $parts['host'] ?? '' ) ) && ( ! isset( $parts['port'] ) || 443 === (int) $parts['port'] ) && ! isset( $parts['user'], $parts['pass'] ) && in_array( (string) ( $parts['path'] ?? '' ), array( '/css', '/css2' ), true );
	}

	private static function bounded_google_font_request( string $url, int $limit ) {
		return wp_safe_remote_get(
			$url,
			array(
				'timeout'             => 15,
				'redirection'         => 0,
				'limit_response_size' => $limit,
				'headers'             => array( 'User-Agent' => 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36' ),
			)
		);
	}

	/** @param array<int,string> $families @param array<int,array<string,mixed>> $diagnostics @param array<string,string> $font_payloads */
	private static function embed_google_font_face_sources( string $css, array $families, array &$diagnostics, array &$font_payloads, int &$font_payload_bytes ): string {
		if ( ! preg_match_all( '/@font-face\s*\{([^{}]*)\}/is', $css, $faces ) ) {
			$diagnostics[] = self::google_font_svg_diagnostic( 'stylesheet_font_faces_missing', 'The Google Fonts stylesheet did not contain embeddable @font-face rules.' );
			return '';
		}
		$embedded = array();
		foreach ( $faces[0] as $index => $face ) {
			$body = $faces[1][ $index ];
			if ( ! preg_match( '/font-family\s*:\s*(["\']?)([^;"\']+)\1\s*;/i', $body, $family_match ) || ! in_array( trim( $family_match[2] ), $families, true ) ) {
				continue;
			}
			if ( str_contains( $face, '<' ) ) {
				$diagnostics[] = self::google_font_svg_diagnostic( 'untrusted_font_url', 'A Google Fonts stylesheet referenced a non-allowlisted font payload URL.' );
				return '';
			}
			if ( ! preg_match_all( '/url\(\s*(["\']?)([^"\'\s\)]+)\1\s*\)/i', $face, $urls ) ) {
				continue;
			}
			$rewritten = $face;
			$urls = array_unique( $urls[2] );
			foreach ( $urls as $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'], $parts['pass'] ) || ! preg_match( '/\.woff2?$/', $path ) ) {
					$diagnostics[] = self::google_font_svg_diagnostic( 'untrusted_font_url', 'A Google Fonts stylesheet referenced a non-allowlisted font payload URL.' );
					return '';
				}
			}
			foreach ( $urls as $url ) {
				$parts = wp_parse_url( $url );
				$path = is_array( $parts ) ? strtolower( (string) ( $parts['path'] ?? '' ) ) : '';
				if ( ! isset( $font_payloads[ $url ] ) ) {
					$response = self::bounded_google_font_request( $url, 2097152 );
					$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 ) > 2097152 ) {
						$diagnostics[] = self::google_font_svg_diagnostic( 'font_payload_fetch_failed', 'An allowlisted Google Fonts payload could not be embedded within the response limit.' );
						return '';
					}
					if ( 4194304 < $font_payload_bytes + strlen( $payload ) ) {
						$diagnostics[] = self::google_font_svg_diagnostic( 'font_payload_total_too_large', 'The unique Google Fonts payloads exceeded the SVG font embedding aggregate limit.' );
						return '';
					}
					$font_payloads[ $url ] = $payload;
					$font_payload_bytes += strlen( $payload );
				}
				$payload = $font_payloads[ $url ];
				$mime = str_ends_with( $path, '.woff2' ) ? 'font/woff2' : 'font/woff';
				$rewritten = str_replace( $url, 'data:' . $mime . ';base64,' . base64_encode( $payload ), $rewritten );
			}
			$embedded[] = $rewritten;
		}
		if ( empty( $embedded ) ) {
			$diagnostics[] = self::google_font_svg_diagnostic( 'matching_font_faces_missing', 'No Google Fonts @font-face rules matched SVG text font-family usage.' );
		}
		return implode( "\n", $embedded );
	}

	/** @param array<string,mixed> $asset */
	private static function is_svg_asset( array $asset, string $path ): bool {
		return 'svg' === strtolower( (string) ( $asset['kind'] ?? '' ) ) || 'image/svg+xml' === strtolower( (string) ( $asset['mime_type'] ?? '' ) ) || str_ends_with( strtolower( $path ), '.svg' );
	}

	/** @param array<int,string> $families */
	private static function svg_uses_font_family( string $svg, array $families ): bool {
		if ( ! preg_match( '/<text\b/i', $svg ) ) {
			return false;
		}
		foreach ( $families as $family ) {
			if ( preg_match( '/font-family\s*[:=]\s*(["\']?)' . preg_quote( $family, '/' ) . '\\1/i', $svg ) ) {
				return true;
			}
		}
		return false;
	}

	public static function embed_svg_font_faces( string $svg, string $font_faces ): string {
		if ( '' === $font_faces || ! self::svg_uses_font_family( $svg, self::font_families_from_faces( $font_faces ) ) || ! preg_match( '/<svg\b[^>]*>/i', $svg, $match, PREG_OFFSET_CAPTURE ) ) {
			return $svg;
		}
		$offset = $match[0][1] + strlen( $match[0][0] );
		return substr( $svg, 0, $offset ) . '<style type="text/css">' . $font_faces . '</style>' . substr( $svg, $offset );
	}

	/** @return array<int,string> */
	private static function font_families_from_faces( string $css ): array {
		preg_match_all( '/font-family\s*:\s*(["\']?)([^;"\']+)\1\s*;/i', $css, $matches );
		return array_values( array_unique( array_map( 'trim', $matches[2] ?? array() ) ) );
	}

	/** @return array<string,string> */
	private static function google_font_svg_diagnostic( string $reason, string $message ): array {
		return array( 'type' => 'svg_font_embedding_failed', 'source' => 'static-site-importer/theme-materializer', 'reason' => $reason, 'message' => $message );
	}

	/**
	 * Materialize payload-bearing artifact files omitted from a native asset plan.
	 *
	 * Some generators emit CSS that references artifact-local files while their
	 * native materialization plan only lists assets observed in DOM nodes. SSI owns
	 * the final theme filesystem, so it keeps those file payloads available and in
	 * the asset map for CSS URL rewriting.
	 *
	 * @param string                            $theme_dir   Theme directory.
	 * @param string                            $theme_uri   Theme URI.
	 * @param array<string,mixed>               $artifacts   WordPress artifacts from Blocks Engine.
	 * @param array<string,array<string,mixed>> $assets      Materialized asset rows keyed by source path.
	 * @param int                               $order       Current materialization order.
	 * @param bool                              $write_files Whether to write materialized asset files.
	 * @param string                            $svg_font_faces Self-contained font CSS for matching SVG text.
	 * @return array{diagnostics:array<int,array<string,mixed>>}|WP_Error
	 */
	private static function materialize_supplemental_artifact_file_assets( string $theme_dir, string $theme_uri, array $artifacts, array &$assets, int &$order, bool $write_files = true, string $svg_font_faces = '' ) {
		$files = isset( $artifacts['files'] ) && is_array( $artifacts['files'] ) ? $artifacts['files'] : array();
		if ( isset( $artifacts['source_files'] ) && is_array( $artifacts['source_files'] ) ) {
			$files = array_merge( $files, $artifacts['source_files'] );
		}
		$diagnostics = array();

		foreach ( $files as $file ) {
			if ( ! is_array( $file ) ) {
				continue;
			}

			$relative = self::normalize_artifact_materialization_path( isset( $file['path'] ) && is_scalar( $file['path'] ) ? (string) $file['path'] : '' );
			if ( '' === $relative || isset( $assets[ $relative ] ) ) {
				continue;
			}

			$lower = strtolower( $relative );
			$kind  = isset( $file['kind'] ) && is_scalar( $file['kind'] ) ? (string) $file['kind'] : '';
			if ( 'html' === $kind || 'css' === $kind || 'js' === $kind || str_ends_with( $lower, '.html' ) || str_ends_with( $lower, '.htm' ) || str_ends_with( $lower, '.css' ) || str_ends_with( $lower, '.js' ) ) {
				continue;
			}

			$content = self::materialization_plan_asset_content( $file, $relative );
			if ( is_wp_error( $content ) ) {
				return $content;
			}
			if ( '' !== $svg_font_faces && self::is_svg_asset( $file, $relative ) ) {
				$content = self::embed_svg_font_faces( $content, $svg_font_faces );
			}

			$retention = self::source_retention_policy( $file, $relative, 'website_artifact.files' );
			if ( isset( $retention['diagnostic'] ) ) {
				$diagnostics[] = $retention['diagnostic'];
			}

			$target_relative = 'assets/materialized/' . $relative;
			$target          = trailingslashit( $theme_dir ) . $target_relative;
			if ( $write_files ) {
				$dir = dirname( $target );
				if ( ! wp_mkdir_p( $dir ) ) {
					return new WP_Error( 'static_site_importer_supplemental_artifact_asset_mkdir_failed', sprintf( 'Failed to create supplemental artifact asset directory: %s', $dir ) );
				}

				$result = self::write_file( $target, $content );
				if ( is_wp_error( $result ) ) {
					return $result;
				}
			}

			++$order;
			$assets[ $relative ] = self::materialization_plan_asset_report(
				array_merge( $file, array( 'origin' => 'website_artifact.files' ) ),
				$relative,
				trailingslashit( $theme_uri ) . $target_relative,
				$target_relative,
				self::mime_type( $target ),
				$order,
				$retention
			);
		}

		return array( 'diagnostics' => $diagnostics );
	}

	/**
	 * Write theme font materialization stylesheet rows declared by Blocks Engine.
	 *
	 * @param string                            $theme_dir Theme directory.
	 * @param string                            $theme_uri Theme URI.
	 * @param array<string,mixed>               $site      Materialization plan site artifact.
	 * @param array<string,array<string,mixed>> $assets    Materialized asset rows keyed by source path.
	 * @param int                               $order     Current materialization order.
	 * @param bool                               $write_files Whether to write materialized asset files.
	 * @param string                            $embedded_font_faces Self-contained font-face CSS resolved for SVG assets.
	 * @return array<int,array<string,mixed>>|WP_Error
	 */
	private static function materialize_font_materialization_stylesheets( string $theme_dir, string $theme_uri, array $site, array &$assets, int &$order, bool $write_files = true, string $embedded_font_faces = '' ) {
		$theme = isset( $site['theme'] ) && is_array( $site['theme'] ) ? $site['theme'] : array();
		$plan  = isset( $theme['font_materialization'] ) && is_array( $theme['font_materialization'] ) ? $theme['font_materialization'] : array();
		if ( 'blocks-engine/php-transformer/font-materialization-plan/v1' !== (string) ( $plan['schema'] ?? '' ) ) {
			return array();
		}

		$rows = isset( $plan['stylesheets'] ) && is_array( $plan['stylesheets'] ) ? $plan['stylesheets'] : array();
		if ( empty( $rows ) && isset( $plan['css'] ) && is_scalar( $plan['css'] ) && '' !== trim( (string) $plan['css'] ) ) {
			$rows[] = array(
				'path'      => 'assets/css/fonts.css',
				'role'      => 'stylesheet',
				'mime_type' => 'text/css',
				'content'   => trim( (string) $plan['css'] ) . "\n",
			);
		}
		if ( '' !== trim( $embedded_font_faces ) ) {
			$rows[] = array(
				'path'        => 'assets/css/embedded-fonts.css',
				'role'        => 'stylesheet',
				'mime_type'   => 'text/css',
				'content'     => trim( $embedded_font_faces ) . "\n",
				'source_role' => 'importer_owned',
				'keep_source' => false,
			);
		}

		$stylesheets = array();
		foreach ( $rows as $row ) {
			if ( ! is_array( $row ) ) {
				return new WP_Error( 'static_site_importer_font_materialization_stylesheet_invalid', 'Blocks Engine font_materialization.stylesheets entries must be arrays.' );
			}

			$relative = self::normalize_artifact_materialization_path( isset( $row['path'] ) && is_scalar( $row['path'] ) ? (string) $row['path'] : '' );
			if ( '' === $relative ) {
				return new WP_Error( 'static_site_importer_font_materialization_stylesheet_path_invalid', 'Blocks Engine font_materialization.stylesheets entries must include safe relative paths.' );
			}

			$content = isset( $row['content'] ) && is_scalar( $row['content'] ) ? (string) $row['content'] : '';
			if ( '' === trim( $content ) ) {
				continue;
			}

			$target = trailingslashit( $theme_dir ) . $relative;
			if ( $write_files ) {
				$dir = dirname( $target );
				if ( ! wp_mkdir_p( $dir ) ) {
					return new WP_Error( 'static_site_importer_font_materialization_stylesheet_mkdir_failed', sprintf( 'Failed to create font materialization stylesheet directory: %s', $dir ) );
				}

				$result = self::write_file( $target, $content );
				if ( is_wp_error( $result ) ) {
					return $result;
				}
			}

			++$order;
			$asset               = array_merge(
				$row,
				array(
					'path'   => $relative,
					'role'   => isset( $row['role'] ) && is_scalar( $row['role'] ) ? (string) $row['role'] : 'stylesheet',
					'kind'   => isset( $row['kind'] ) && is_scalar( $row['kind'] ) ? (string) $row['kind'] : 'css',
					'origin' => 'theme.font_materialization',
				)
			);
			$retention           = self::source_retention_policy( $asset, $relative, 'theme.font_materialization' );
			$assets[ $relative ] = self::materialization_plan_asset_report( $asset, $relative, trailingslashit( $theme_uri ) . $relative, $relative, self::mime_type( $target ), $order, $retention );
			$stylesheets[]       = $assets[ $relative ];
		}

		return $stylesheets;
	}

	/**
	 * Build an SSI asset report row while preserving native Blocks Engine metadata.
	 *
	 * @param array<string,mixed> $asset           Blocks Engine asset row.
	 * @param string              $relative        Safe source-relative path.
	 * @param string              $url             Materialized theme URL.
	 * @param string              $target_relative Materialized theme-relative path.
	 * @param string              $fallback_mime   MIME type inferred from written path.
	 * @param int                 $order           Native asset order.
	 * @param array<string,mixed> $retention       Source retention policy.
	 * @return array<string,mixed>
	 */
	private static function materialization_plan_asset_report( array $asset, string $relative, string $url, string $target_relative, string $fallback_mime, int $order, array $retention = array() ): array {
		$mime_type = isset( $asset['mime_type'] ) && is_scalar( $asset['mime_type'] ) && '' !== (string) $asset['mime_type'] ? (string) $asset['mime_type'] : $fallback_mime;
		$origin    = isset( $asset['origin'] ) && is_scalar( $asset['origin'] ) && '' !== (string) $asset['origin'] ? (string) $asset['origin'] : 'materialization_plan.assets';
		if ( empty( $retention ) ) {
			$retention = self::source_retention_policy( $asset, $relative, $origin );
		}
		$report = array(
			'source'           => $relative,
			'path'             => $relative,
			'url'              => $url,
			'final_url'        => $url,
			'mime_type'        => $mime_type,
			'theme_path'       => $target_relative,
			'policy'           => 'theme',
			'origin'           => $origin,
			'order'            => $order,
			'source_role'      => $retention['source_role'],
			'keep_source'      => $retention['keep_source'],
			'deletion_allowed' => $retention['deletion_allowed'],
		);

		foreach ( array( 'role', 'kind', 'type', 'media', 'as', 'crossorigin', 'integrity', 'placement', 'source_hash' ) as $key ) {
			if ( isset( $asset[ $key ] ) && is_scalar( $asset[ $key ] ) && '' !== (string) $asset[ $key ] ) {
				$report[ $key ] = (string) $asset[ $key ];
			}
		}

		foreach ( array( 'defer', 'async' ) as $key ) {
			if ( array_key_exists( $key, $asset ) ) {
				$report[ $key ] = (bool) $asset[ $key ];
			}
		}

		return $report;
	}

	/**
	 * Resolve source retention semantics for materialized artifact payloads.
	 *
	 * Canonical sources are retained unless the row explicitly declares an ephemeral/importer-owned source role.
	 *
	 * @param array<string,mixed> $source Source artifact row.
	 * @param string              $path   Source-relative path.
	 * @param string              $origin Source origin label for diagnostics.
	 * @return array{source_role:string,keep_source:bool,deletion_allowed:bool,diagnostic?:array<string,mixed>}
	 */
	private static function source_retention_policy( array $source, string $path, string $origin ): array {
		$source_role = isset( $source['source_role'] ) && is_scalar( $source['source_role'] ) && '' !== trim( (string) $source['source_role'] ) ? strtolower( preg_replace( '/[^a-z0-9_-]+/i', '_', trim( (string) $source['source_role'] ) ) ?? '' ) : 'canonical';
		if ( '' === $source_role ) {
			$source_role = 'canonical';
		}
		$keep_source = array_key_exists( 'keep_source', $source ) ? (bool) $source['keep_source'] : true;
		$ephemeral   = in_array( $source_role, array( 'ephemeral', 'importer_owned', 'importer-owned', 'temporary', 'temp' ), true );

		$policy = array(
			'source_role'      => $source_role,
			'keep_source'      => $keep_source || ! $ephemeral,
			'deletion_allowed' => $ephemeral && ! $keep_source,
		);

		if ( ! $keep_source && ! $ephemeral ) {
			$policy['diagnostic'] = array(
				'type'             => 'website_artifact_source_retention_guard',
				'severity'         => 'warning',
				'source'           => $origin,
				'source_path'      => $path,
				'path'             => $path,
				'source_role'      => $source_role,
				'keep_source'      => true,
				'deletion_allowed' => false,
				'reason'           => 'canonical_source_retained',
				'message'          => 'Website artifact source was retained because destructive source handling requires source_role=ephemeral or source_role=importer_owned.',
			);
		}

		return $policy;
	}

	/**
	 * Rewrite CSS url(...) references to materialized theme URLs.
	 *
	 * @param array<int,array{path:string,content:string}> $chunks CSS chunks and their source paths.
	 * @param array<string,array<string,mixed>>             $assets Materialized asset rows keyed by source path.
	 * @return array<int,string>
	 */
	private static function rewrite_materialized_css_chunks( array $chunks, array $assets ): array {
		$rewritten = array();
		foreach ( $chunks as $chunk ) {
			$rewritten[] = self::rewrite_materialized_css_urls( $chunk['content'], $chunk['path'], $assets );
		}

		return $rewritten;
	}

	/**
	 * Rewrite one CSS payload's relative url(...) references.
	 *
	 * @param string                            $css             CSS payload.
	 * @param string                            $stylesheet_path Source-relative stylesheet path.
	 * @param array<string,array<string,mixed>> $assets          Materialized asset rows keyed by source path.
	 * @return string
	 */
	private static function rewrite_materialized_css_urls( string $css, string $stylesheet_path, array $assets ): string {
		if ( '' === trim( $css ) || empty( $assets ) ) {
			return $css;
		}

		$stylesheet_dir = dirname( $stylesheet_path );
		return preg_replace_callback(
			'/url\(\s*(["\']?)([^)"\']+)\1\s*\)/i',
			static function ( array $matches ) use ( $assets, $stylesheet_dir ): string {
				$url = trim( (string) $matches[2] );
				if ( '' === $url || str_starts_with( $url, '#' ) || str_starts_with( strtolower( $url ), 'data:' ) || preg_match( '#^[a-z][a-z0-9+.-]*:#i', $url ) || str_starts_with( $url, '/' ) ) {
					return $matches[0];
				}

				$candidate = self::resolve_materialized_relative_url( $stylesheet_dir, $url );
				if ( '' === $candidate || ! isset( $assets[ $candidate ]['final_url'] ) || ! is_scalar( $assets[ $candidate ]['final_url'] ) ) {
					return $matches[0];
				}

				return 'url(' . $matches[1] . (string) $assets[ $candidate ]['final_url'] . $matches[1] . ')';
			},
			$css
		) ?? $css;
	}

	/**
	 * Resolve a relative asset URL against a source stylesheet path.
	 *
	 * @param string $base_dir Source stylesheet directory.
	 * @param string $url      Relative CSS URL.
	 * @return string Safe source-relative path, or empty string when it escapes the artifact root.
	 */
	private static function resolve_materialized_relative_url( string $base_dir, string $url ): string {
		$path     = ( '.' === $base_dir ? '' : trim( $base_dir, '/' ) . '/' ) . strtok( $url, '?#' );
		$segments = array();
		foreach ( explode( '/', str_replace( '\\', '/', $path ) ) as $segment ) {
			if ( '' === $segment || '.' === $segment ) {
				continue;
			}
			if ( '..' === $segment ) {
				if ( empty( $segments ) ) {
					return '';
				}
				array_pop( $segments );
				continue;
			}
			$segments[] = $segment;
		}

		return self::normalize_artifact_materialization_path( implode( '/', $segments ) );
	}

	/**
	 * Check whether native asset rows include write payloads.
	 *
	 * @param array<int,mixed> $assets Blocks Engine materialization-plan asset rows.
	 * @return bool
	 */
	private static function materialization_plan_assets_include_payloads( array $assets ): bool {
		foreach ( $assets as $asset ) {
			if ( is_array( $asset ) && ( array_key_exists( 'content', $asset ) || array_key_exists( 'content_base64', $asset ) ) ) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Decode a native materialization-plan asset payload.
	 *
	 * @param array<string,mixed> $asset    Blocks Engine asset row.
	 * @param string              $relative Safe relative asset path.
	 * @return string|WP_Error
	 */
	private static function materialization_plan_asset_content( array $asset, string $relative ) {
		if ( isset( $asset['content_base64'] ) ) {
			if ( ! is_scalar( $asset['content_base64'] ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_asset_content_invalid', sprintf( 'Blocks Engine materialization_plan.assets content_base64 must be scalar: %s', $relative ) );
			}

			$base64 = preg_replace( '/\s+/', '', (string) $asset['content_base64'] ) ?? '';
			// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- Decodes declared artifact payload content, not executable code.
			$decoded = base64_decode( $base64, true );
			if ( false === $decoded ) {
				return new WP_Error( 'static_site_importer_materialization_plan_asset_base64_invalid', sprintf( 'Blocks Engine materialization_plan.assets content_base64 is not valid base64: %s', $relative ) );
			}

			return $decoded;
		}

		if ( isset( $asset['content'] ) && is_scalar( $asset['content'] ) ) {
			return (string) $asset['content'];
		}

		return new WP_Error( 'static_site_importer_materialization_plan_asset_content_missing', sprintf( 'Blocks Engine materialization_plan.assets entries must include content or content_base64: %s', $relative ) );
	}

	/**
	 * Normalize template part artifacts into generated theme writes.
	 *
	 * @param string              $theme_dir Theme directory.
	 * @param array<string,mixed>                     $artifacts WordPress artifacts from Blocks Engine.
	 * @param array<string,array<string,mixed>>       $assets Materialized assets keyed by source path.
	 * @param array<string,string>                    $permalinks Imported page permalinks keyed by source path.
	 * @return array{writes:array<string,string>,reports:array<int,array<string,mixed>>}|WP_Error Absolute write paths and report rows.
	 */
	public static function template_part_artifact_writes( string $theme_dir, array $artifacts, array $assets = array(), array $permalinks = array() ) {
		$template_parts = self::template_part_artifacts_from_materialization_plan( $artifacts );
		if ( is_wp_error( $template_parts ) ) {
			return $template_parts;
		}

		if ( null === $template_parts ) {
			$template_parts = self::navigation_template_parts_from_materialization_plan( $artifacts );
			if ( is_wp_error( $template_parts ) ) {
				return $template_parts;
			}
		}

		if ( null === $template_parts ) {
			$template_parts = isset( $artifacts['template_parts'] ) && is_array( $artifacts['template_parts'] ) ? $artifacts['template_parts'] : array();
		}

		if ( empty( $template_parts ) ) {
			$template_parts = self::source_file_template_parts( $artifacts );
		}

		$writes  = array();
		$reports = array();
		foreach ( $template_parts as $template_part ) {
			if ( ! is_array( $template_part ) ) {
				return new WP_Error( 'static_site_importer_template_part_invalid', 'Template part artifacts must be arrays.' );
			}

			$relative = self::template_part_artifact_relative_path( $template_part );
			if ( '' === $relative ) {
				return new WP_Error( 'static_site_importer_template_part_unsupported', 'Template part artifacts must resolve to a supported header or footer theme part.' );
			}

			if ( ! isset( $template_part['block_markup'] ) || ! is_scalar( $template_part['block_markup'] ) ) {
				return new WP_Error( 'static_site_importer_template_part_markup_missing', 'Template part artifacts must include serialized block_markup.' );
			}

			$markup = (string) $template_part['block_markup'];
			if ( '' === trim( $markup ) ) {
				return new WP_Error( 'static_site_importer_template_part_markup_empty', 'Template part artifact block_markup must not be empty.' );
			}
			$source_path = isset( $template_part['source_path'] ) && is_scalar( $template_part['source_path'] ) ? (string) $template_part['source_path'] : '';
			$source_path = (string) strtok( $source_path, '#' );
			$markup      = Static_Site_Importer_Page_Materializer::rewrite_materialized_asset_references( $markup, $assets, $source_path, $permalinks );

			$writes[ trailingslashit( $theme_dir ) . $relative ] = $markup;
			$reports[] = self::template_part_artifact_report_payload( $relative, $template_part, $markup );
		}

		return array(
			'writes'  => $writes,
			'reports' => $reports,
		);
	}

	/**
	 * Extract header/footer parts from source HTML files when the compiler has not
	 * emitted explicit template-part artifacts.
	 *
	 * @param array<string,mixed> $artifacts WordPress artifacts from Blocks Engine.
	 * @return array<int,array<string,mixed>>
	 */
	private static function source_file_template_parts( array $artifacts ): array {
		$files = isset( $artifacts['source_files'] ) && is_array( $artifacts['source_files'] ) ? $artifacts['source_files'] : array();
		$files = self::entrypoint_first_source_files( $files, $artifacts );
		foreach ( $files as $file ) {
			if ( ! is_array( $file ) || ! isset( $file['path'] ) || ! is_scalar( $file['path'] ) ) {
				continue;
			}

			$path = (string) $file['path'];
			if ( ! preg_match( '/\.html?$/i', $path ) ) {
				continue;
			}

			$content = '';
			if ( isset( $file['content'] ) && is_scalar( $file['content'] ) ) {
				$content = (string) $file['content'];
			} elseif ( isset( $file['content_base64'] ) && is_scalar( $file['content_base64'] ) ) {
				// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_decode -- Decodes trusted website artifact file content.
				$decoded = base64_decode( (string) $file['content_base64'], true );
				if ( false !== $decoded ) {
					$content = $decoded;
				}
			}
			if ( '' === $content ) {
				continue;
			}

			$parts = self::template_parts_from_html( $content, $path );
			if ( ! empty( $parts ) ) {
				return $parts;
			}
		}

		return array();
	}

	/**
	 * Order source files so the site entrypoint is scanned first.
	 *
	 * The entrypoint page is the imported front page, so its chrome is the
	 * authoritative candidate for shared template parts. Without this ordering
	 * the fallback synthesizes parts from whichever file happens to sort first.
	 *
	 * @param array<int,mixed>    $files     Source files.
	 * @param array<string,mixed> $artifacts WordPress artifacts from Blocks Engine.
	 * @return array<int,mixed>
	 */
	private static function entrypoint_first_source_files( array $files, array $artifacts ): array {
		$entrypoint = '';
		foreach ( array( 'entry_path', 'entrypoint' ) as $key ) {
			if ( isset( $artifacts[ $key ] ) && is_scalar( $artifacts[ $key ] ) && '' !== trim( (string) $artifacts[ $key ] ) ) {
				$entrypoint = ltrim( str_replace( '\\', '/', trim( (string) $artifacts[ $key ] ) ), '/' );
				break;
			}
		}
		if ( '' === $entrypoint ) {
			return $files;
		}

		$leading  = array();
		$trailing = array();
		foreach ( $files as $file ) {
			$path = is_array( $file ) && isset( $file['path'] ) && is_scalar( $file['path'] ) ? ltrim( str_replace( '\\', '/', (string) $file['path'] ), '/' ) : '';
			if ( '' !== $path && ( $path === $entrypoint || str_ends_with( $path, '/' . $entrypoint ) ) ) {
				$leading[] = $file;
				continue;
			}
			$trailing[] = $file;
		}

		return array_merge( $leading, $trailing );
	}

	/**
	 * Convert source HTML landmarks into reusable block theme parts.
	 *
	 * @param string $html        Source HTML document.
	 * @param string $source_path Source file path for reports.
	 * @return array<int,array<string,mixed>>
	 */
	private static function template_parts_from_html( string $html, string $source_path ): array {
		$document  = new Static_Site_Importer_Document( $html );
		$fragments = $document->fragments();
		$parts     = array();

		foreach ( array( 'header', 'footer' ) as $slug ) {
			$fragment = trim( $fragments[ $slug ] );
			if ( '' === $fragment ) {
				$fragment = self::first_landmark_html( $html, $slug );
			}
			if ( '' === trim( $fragment ) ) {
				continue;
			}

			$diagnostics = array();
			$markup      = Static_Site_Importer_Page_Materializer::html_to_blocks( self::strip_inline_svg_markup( $fragment ), $source_path . '#' . $slug, $diagnostics );
			if ( '' === trim( $markup ) ) {
				continue;
			}

			$parts[] = array(
				'source_path'  => $source_path . '#' . $slug,
				'slug'         => $slug,
				'title'        => ucfirst( $slug ),
				'area'         => $slug,
				'generated'    => true,
				'block_markup' => trim( $markup ) . "\n",
			);
		}

		return $parts;
	}

	/**
	 * Remove inline SVG from synthesized source-derived template parts.
	 *
	 * @param string $html HTML fragment.
	 * @return string
	 */
	private static function strip_inline_svg_markup( string $html ): string {
		if ( '' === trim( $html ) || ! str_contains( strtolower( $html ), '<svg' ) ) {
			return $html;
		}

		return (string) preg_replace( '#<svg\b[^>]*>.*?</svg>#is', '', $html );
	}

	/**
	 * Return the first separable landmark's outer HTML.
	 *
	 * Landmarks nested inside `<main>` remain part of the page body markup, so
	 * synthesizing a shared template part from them would render the same chrome
	 * twice. Only landmarks outside the page body are reusable site chrome.
	 *
	 * @param string $html Source HTML document.
	 * @param string $tag  Landmark tag name.
	 * @return string
	 */
	private static function first_landmark_html( string $html, string $tag ): string {
		if ( '' === trim( $html ) ) {
			return '';
		}

		$dom      = new DOMDocument();
		$previous = libxml_use_internal_errors( true );
		$loaded   = $dom->loadHTML( $html, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD );
		libxml_clear_errors();
		libxml_use_internal_errors( $previous );
		if ( ! $loaded ) {
			return '';
		}

		$mains = $dom->getElementsByTagName( 'main' );
		$main  = $mains->length > 0 ? $mains->item( 0 ) : null;

		foreach ( $dom->getElementsByTagName( $tag ) as $node ) {
			if ( ! $node instanceof DOMElement ) {
				continue;
			}

			if ( $main instanceof DOMElement && self::dom_is_descendant_of( $node, $main ) ) {
				continue;
			}

			return trim( (string) $dom->saveHTML( $node ) );
		}

		return '';
	}

	/**
	 * Check whether a DOM node is contained by another element.
	 *
	 * @param DOMElement $candidate Candidate element.
	 * @param DOMElement $ancestor  Ancestor element.
	 * @return bool
	 */
	private static function dom_is_descendant_of( DOMElement $candidate, DOMElement $ancestor ): bool {
		$node = $candidate->parentNode;
		while ( $node instanceof DOMNode ) {
			if ( $node->isSameNode( $ancestor ) ) {
				return true;
			}

			$node = $node->parentNode;
		}

		return false;
	}

	/**
	 * Read generic WordPress template-part writes from a Blocks Engine materialization plan.
	 *
	 * @param array<string,mixed> $artifacts WordPress artifacts from the transformer adapter.
	 * @return array<int,array<string,mixed>>|null|WP_Error Template part artifacts, null when no plan write list exists.
	 */
	private static function template_part_artifacts_from_materialization_plan( array $artifacts ) {
		$site = isset( $artifacts['site'] ) && is_array( $artifacts['site'] ) ? $artifacts['site'] : array();
		if ( 'blocks-engine/php-transformer/materialization-plan/v1' !== (string) ( $site['schema'] ?? '' ) || ! array_key_exists( 'template_part_writes', $site ) ) {
			return null;
		}

		if ( ! is_array( $site['template_part_writes'] ) ) {
			return new WP_Error( 'static_site_importer_materialization_plan_template_part_writes_invalid', 'Blocks Engine materialization_plan.template_part_writes must be an array.' );
		}

		$template_parts = array();
		foreach ( $site['template_part_writes'] as $write ) {
			if ( ! is_array( $write ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_template_part_write_invalid', 'Blocks Engine template part write entries must be arrays.' );
			}

			if ( 'wp_template_part' !== (string) ( $write['type'] ?? '' ) ) {
				continue;
			}

			$content = isset( $write['content'] ) && is_scalar( $write['content'] ) ? (string) $write['content'] : '';
			if ( '' === trim( $content ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_template_part_content_missing', 'Blocks Engine wp_template_part writes must include non-empty content.' );
			}

			$template_parts[] = array_filter(
				array(
					'source_path'  => isset( $write['source_path'] ) && is_scalar( $write['source_path'] ) ? (string) $write['source_path'] : '',
					'slug'         => isset( $write['slug'] ) && is_scalar( $write['slug'] ) ? (string) $write['slug'] : '',
					'title'        => isset( $write['title'] ) && is_scalar( $write['title'] ) ? (string) $write['title'] : '',
					'area'         => isset( $write['area'] ) && is_scalar( $write['area'] ) ? (string) $write['area'] : '',
					'block_markup' => $content,
				),
				static fn ( string $value ): bool => '' !== $value
			);
		}

		return $template_parts;
	}

	/**
	 * Read native navigation rows from a Blocks Engine materialization plan.
	 *
	 * @param array<string,mixed> $artifacts WordPress artifacts from the transformer adapter.
	 * @return array<int,array<string,mixed>>|null|WP_Error Navigation-backed template parts, null when no rows exist.
	 */
	private static function navigation_template_parts_from_materialization_plan( array $artifacts ) {
		$site = isset( $artifacts['site'] ) && is_array( $artifacts['site'] ) ? $artifacts['site'] : array();
		if ( 'blocks-engine/php-transformer/materialization-plan/v1' !== (string) ( $site['schema'] ?? '' ) || ! array_key_exists( 'navigation', $site ) ) {
			return null;
		}

		if ( ! is_array( $site['navigation'] ) ) {
			return new WP_Error( 'static_site_importer_materialization_plan_navigation_invalid', 'Blocks Engine materialization_plan.navigation must be an array.' );
		}

		$template_parts = array();
		foreach ( $site['navigation'] as $navigation ) {
			if ( ! is_array( $navigation ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_navigation_row_invalid', 'Blocks Engine materialization-plan navigation entries must be arrays.' );
			}

			$content = '';
			foreach ( array( 'block_markup', 'content' ) as $key ) {
				if ( isset( $navigation[ $key ] ) && is_scalar( $navigation[ $key ] ) && '' !== trim( (string) $navigation[ $key ] ) ) {
					$content = (string) $navigation[ $key ];
					break;
				}
			}

			if ( '' === trim( $content ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_navigation_content_missing', 'Blocks Engine navigation rows must include non-empty block_markup or content.' );
			}

			$template_parts[] = array_filter(
				array(
					'source_path'  => isset( $navigation['source_path'] ) && is_scalar( $navigation['source_path'] ) ? (string) $navigation['source_path'] : '',
					'slug'         => isset( $navigation['slug'] ) && in_array( sanitize_key( (string) $navigation['slug'] ), array( 'header', 'footer' ), true ) ? sanitize_key( (string) $navigation['slug'] ) : 'header',
					'title'        => isset( $navigation['title'] ) && is_scalar( $navigation['title'] ) ? (string) $navigation['title'] : 'Navigation',
					'area'         => isset( $navigation['area'] ) && in_array( sanitize_key( (string) $navigation['area'] ), array( 'header', 'footer' ), true ) ? sanitize_key( (string) $navigation['area'] ) : 'header',
					'block_markup' => $content,
				),
				static fn ( string $value ): bool => '' !== $value
			);
		}

		return $template_parts;
	}

	/**
	 * Normalize compiler file paths before writing them to a generated theme.
	 *
	 * @param string $path Artifact file path.
	 * @return string Safe relative path, or empty string when unsafe.
	 */
	public static function normalize_artifact_materialization_path( string $path ): string {
		$path = str_replace( '\\', '/', trim( $path ) );
		$path = preg_replace( '/\0+/', '', $path );
		if ( ! is_string( $path ) || '' === $path || str_starts_with( $path, '/' ) || preg_match( '#^[a-z][a-z0-9+.-]*:#i', $path ) ) {
			return '';
		}

		$segments = array();
		foreach ( explode( '/', $path ) as $segment ) {
			if ( '' === $segment || '.' === $segment ) {
				continue;
			}
			if ( '..' === $segment ) {
				return '';
			}
			$segments[] = preg_replace( '/[^A-Za-z0-9._-]/', '-', $segment );
		}

		return implode( '/', array_filter( $segments ) );
	}

	/**
	 * Resolve a template part artifact to an SSI-supported theme part path.
	 *
	 * @param array<string,mixed> $template_part Template part artifact.
	 * @return string Relative theme path, or empty string when unsupported.
	 */
	private static function template_part_artifact_relative_path( array $template_part ): string {
		$slug = isset( $template_part['slug'] ) && is_scalar( $template_part['slug'] ) ? sanitize_key( (string) $template_part['slug'] ) : '';
		$area = isset( $template_part['area'] ) && is_scalar( $template_part['area'] ) ? sanitize_key( (string) $template_part['area'] ) : '';
		$part = '';

		if ( in_array( $slug, array( 'header', 'footer' ), true ) ) {
			$part = $slug;
		} elseif ( in_array( $area, array( 'header', 'footer' ), true ) ) {
			$part = $area;
		}

		return '' !== $part ? 'parts/' . $part . '.html' : '';
	}

	/**
	 * Build a compact report row for a materialized template part artifact.
	 *
	 * @param string              $path          Relative generated theme path.
	 * @param array<string,mixed> $template_part Template part artifact.
	 * @param string              $markup        Serialized block markup.
	 * @return array<string,mixed>
	 */
	private static function template_part_artifact_report_payload( string $path, array $template_part, string $markup ): array {
		$source_paths = isset( $template_part['source_paths'] ) && is_array( $template_part['source_paths'] ) ? array_values( array_filter( $template_part['source_paths'], 'is_scalar' ) ) : array();
		if ( empty( $source_paths ) && isset( $template_part['source_path'] ) && is_scalar( $template_part['source_path'] ) && '' !== (string) $template_part['source_path'] ) {
			$source_paths = array( (string) $template_part['source_path'] );
		}

		return array(
			'path'               => $path,
			'slug'               => isset( $template_part['slug'] ) && is_scalar( $template_part['slug'] ) ? (string) $template_part['slug'] : '',
			'area'               => isset( $template_part['area'] ) && is_scalar( $template_part['area'] ) ? (string) $template_part['area'] : '',
			'generated'          => ! empty( $template_part['generated'] ),
			'source_paths'       => $source_paths,
			'source_hash'        => isset( $template_part['source_hash'] ) && is_scalar( $template_part['source_hash'] ) ? (string) $template_part['source_hash'] : '',
			'block_markup_bytes' => strlen( $markup ),
			'block_markup_hash'  => hash( 'sha256', $markup ),
		);
	}

	/**
	 * Normalize compiler-declared WordPress template artifacts into generated theme writes.
	 *
	 * @param string              $theme_dir Theme directory.
	 * @param array<string,mixed> $artifacts WordPress artifacts from Blocks Engine.
	 * @return array{writes:array<string,string>,reports:array<int,array<string,mixed>>}|WP_Error Absolute write paths and report rows.
	 */
	public static function template_artifact_writes( string $theme_dir, array $artifacts ) {
		$templates = self::template_artifacts_from_materialization_plan( $artifacts );
		if ( is_wp_error( $templates ) ) {
			return $templates;
		}

		$writes  = array();
		$reports = array();
		foreach ( $templates as $template ) {
			$relative = self::template_artifact_relative_path( $template );
			if ( '' === $relative ) {
				return new WP_Error( 'static_site_importer_template_unsupported', 'Template artifacts must resolve to a safe templates/*.html path.' );
			}

			$markup = self::template_artifact_markup( $template );
			if ( '' === trim( $markup ) ) {
				return new WP_Error( 'static_site_importer_template_markup_empty', 'Template artifact block markup must not be empty.' );
			}

			$writes[ trailingslashit( $theme_dir ) . $relative ] = $markup;
			$reports[] = self::template_artifact_report_payload( $relative, $template, $markup );
		}

		return array(
			'writes'  => $writes,
			'reports' => $reports,
		);
	}

	/**
	 * Build block template writes from conventional source document names.
	 *
	 * @param string               $theme_dir Theme directory.
	 * @param array<string,string> $contents  Converted block markup keyed by source path.
	 * @return array{writes:array<string,string>,reports:array<int,array<string,mixed>>}
	 */
	public static function source_document_template_writes( string $theme_dir, array $contents ): array {
		$template_map = array(
			'404'            => '404',
			'archive'        => 'archive',
			'search'         => 'search',
			'search-results' => 'search',
		);
		$writes       = array();
		$reports      = array();

		foreach ( $contents as $source_path => $content ) {
			$slug          = sanitize_title( preg_replace( '/\.[^.]+$/', '', basename( (string) $source_path ) ) ?? '' );
			$template_slug = $template_map[ $slug ] ?? '';
			if ( '' === $template_slug || '' === trim( (string) $content ) ) {
				continue;
			}

			$relative = 'templates/' . $template_slug . '.html';
			$writes[ trailingslashit( $theme_dir ) . $relative ] = trim( (string) $content ) . "\n";
			$reports[] = array(
				'path'             => $relative,
				'slug'             => $template_slug,
				'source'           => 'source_document',
				'source_path'      => (string) $source_path,
				'block_count'      => substr_count( (string) $content, '<!-- wp:' ),
				'core_html_blocks' => substr_count( (string) $content, '<!-- wp:html' ),
			);
		}

		return array(
			'writes'  => $writes,
			'reports' => $reports,
		);
	}

	/**
	 * Read generic WordPress template writes from a Blocks Engine materialization plan.
	 *
	 * @param array<string,mixed> $artifacts WordPress artifacts from the transformer adapter.
	 * @return array<int,array<string,mixed>>|WP_Error Template artifacts.
	 */
	private static function template_artifacts_from_materialization_plan( array $artifacts ) {
		$site = isset( $artifacts['site'] ) && is_array( $artifacts['site'] ) ? $artifacts['site'] : array();
		if ( 'blocks-engine/php-transformer/materialization-plan/v1' !== (string) ( $site['schema'] ?? '' ) ) {
			return array();
		}

		$template_rows = array();
		if ( array_key_exists( 'template_writes', $site ) ) {
			if ( ! is_array( $site['template_writes'] ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_template_writes_invalid', 'Blocks Engine materialization_plan.template_writes must be an array.' );
			}

			foreach ( $site['template_writes'] as $write ) {
				if ( ! is_array( $write ) ) {
					return new WP_Error( 'static_site_importer_materialization_plan_template_write_invalid', 'Blocks Engine template write entries must be arrays.' );
				}

				if ( 'wp_template' !== (string) ( $write['type'] ?? '' ) ) {
					continue;
				}

				$template_rows[] = $write;
			}
		}

		if ( array_key_exists( 'templates', $site ) ) {
			if ( ! is_array( $site['templates'] ) ) {
				return new WP_Error( 'static_site_importer_materialization_plan_templates_invalid', 'Blocks Engine materialization_plan.templates must be an array.' );
			}

			foreach ( $site['templates'] as $template ) {
				if ( ! is_array( $template ) ) {
					return new WP_Error( 'static_site_importer_materialization_plan_template_invalid', 'Blocks Engine template entries must be arrays.' );
				}

				$template_rows[] = $template;
			}
		}

		return $template_rows;
	}

	/**
	 * Resolve a template artifact to a generated theme template path.
	 *
	 * @param array<string,mixed> $template Template artifact.
	 * @return string Relative theme path, or empty string when unsupported.
	 */
	private static function template_artifact_relative_path( array $template ): string {
		foreach ( array( 'path', 'theme_path', 'file' ) as $key ) {
			if ( isset( $template[ $key ] ) && is_scalar( $template[ $key ] ) ) {
				$relative = self::normalize_artifact_materialization_path( (string) $template[ $key ] );
				if ( preg_match( '#^templates/[A-Za-z0-9._-]+\.html$#', $relative ) ) {
					return $relative;
				}
			}
		}

		$slug = isset( $template['slug'] ) && is_scalar( $template['slug'] ) ? sanitize_title( (string) $template['slug'] ) : '';
		if ( '' === $slug ) {
			return '';
		}

		return 'templates/' . $slug . '.html';
	}

	/**
	 * Extract serialized block markup from a template artifact.
	 *
	 * @param array<string,mixed> $template Template artifact.
	 * @return string Serialized block markup.
	 */
	private static function template_artifact_markup( array $template ): string {
		foreach ( array( 'block_markup', 'content', 'markup' ) as $key ) {
			if ( isset( $template[ $key ] ) && is_scalar( $template[ $key ] ) ) {
				return (string) $template[ $key ];
			}
		}

		return '';
	}

	/**
	 * Build a compact report row for a materialized template artifact.
	 *
	 * @param string              $path     Relative generated theme path.
	 * @param array<string,mixed> $template Template artifact.
	 * @param string              $markup   Serialized block markup.
	 * @return array<string,mixed>
	 */
	private static function template_artifact_report_payload( string $path, array $template, string $markup ): array {
		return array(
			'path'               => $path,
			'slug'               => isset( $template['slug'] ) && is_scalar( $template['slug'] ) ? (string) $template['slug'] : preg_replace( '#^templates/(.+)\.html$#', '$1', $path ),
			'title'              => isset( $template['title'] ) && is_scalar( $template['title'] ) ? (string) $template['title'] : '',
			'source_path'        => isset( $template['source_path'] ) && is_scalar( $template['source_path'] ) ? (string) $template['source_path'] : '',
			'block_markup_bytes' => strlen( $markup ),
			'block_markup_hash'  => hash( 'sha256', $markup ),
		);
	}

	/**
	 * Build functions.php.
	 *
	 * @param string $theme_slug Theme slug.
	 * @param array<int,array<string,mixed>> $scripts     Materialized script asset rows.
	 * @param array<int,array<string,mixed>> $stylesheets Materialized stylesheet asset rows.
	 * @return string
	 */
	private static function functions_php( string $theme_slug, array $scripts = array(), array $stylesheets = array() ): string {
		$style_handle     = sanitize_key( $theme_slug ) . '-style';
		$editor_handle    = sanitize_key( $theme_slug ) . '-editor-style';
		$script_lines     = '';
		$stylesheet_lines = '';
		$stylesheet_deps  = array();

		foreach ( $stylesheets as $stylesheet ) {
			if ( ! isset( $stylesheet['theme_path'] ) || ! is_scalar( $stylesheet['theme_path'] ) ) {
				continue;
			}

			$theme_path = self::normalize_artifact_materialization_path( (string) $stylesheet['theme_path'] );
			if ( '' === $theme_path ) {
				continue;
			}

			$handle            = sanitize_key( $theme_slug . '-asset-' . preg_replace( '/\.[^.]+$/', '', str_replace( '/', '-', $theme_path ) ) );
			$stylesheet_deps[] = $handle;
			// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
			$stylesheet_lines .= "\twp_enqueue_style( " . var_export( $handle, true ) . ', get_template_directory_uri() . ' . var_export( '/' . $theme_path, true ) . ", array(), wp_get_theme()->get( 'Version' )";
			$media             = isset( $stylesheet['media'] ) && is_scalar( $stylesheet['media'] ) && '' !== (string) $stylesheet['media'] ? (string) $stylesheet['media'] : '';
			// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
			$stylesheet_lines .= '' !== $media ? ', ' . var_export( $media, true ) . " );\n" : " );\n";
		}
		// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP array literals for functions.php.
		$stylesheet_dependencies = empty( $stylesheet_deps ) ? 'array()' : var_export( $stylesheet_deps, true );

		foreach ( $scripts as $script ) {
			if ( ! isset( $script['theme_path'] ) || ! is_scalar( $script['theme_path'] ) ) {
				continue;
			}

			$theme_path = self::normalize_artifact_materialization_path( (string) $script['theme_path'] );
			if ( '' === $theme_path ) {
				continue;
			}

			$handle    = sanitize_key( $theme_slug . '-asset-' . preg_replace( '/\.[^.]+$/', '', str_replace( '/', '-', $theme_path ) ) );
			$in_footer = 'head' !== (string) ( $script['placement'] ?? '' );
			// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
			$script_lines .= "\twp_enqueue_script( " . var_export( $handle, true ) . ', get_template_directory_uri() . ' . var_export( '/' . $theme_path, true ) . ", array(), wp_get_theme()->get( 'Version' ), " . ( $in_footer ? 'true' : 'false' ) . " );\n";
			if ( ! empty( $script['defer'] ) ) {
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
				$script_lines .= "\twp_script_add_data( " . var_export( $handle, true ) . ", 'defer', true );\n";
			}
			if ( ! empty( $script['async'] ) ) {
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
				$script_lines .= "\twp_script_add_data( " . var_export( $handle, true ) . ", 'async', true );\n";
			}
			if ( isset( $script['type'] ) && 'module' === strtolower( (string) $script['type'] ) ) {
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_var_export -- Generates quoted PHP string literals for functions.php.
				$script_lines .= "\twp_script_add_data( " . var_export( $handle, true ) . ", 'type', 'module' );\n";
			}
		}

		return "<?php\n" .
			"/**\n" .
			" * Generated theme bootstrap.\n" .
			" */\n\n" .
			"add_filter( 'upload_mimes', static function ( array \$mimes ): array {\n" .
			"\t// Generated SVG media is sanitized by the import pipeline at build time.\n" .
			"\t\$mimes['svg'] = 'image/svg+xml';\n" .
			"\treturn \$mimes;\n" .
			"} );\n\n" .
			"add_filter( 'wp_check_filetype_and_ext', static function ( array \$data, string \$file, string \$filename, array \$mimes ): array {\n" .
			"\tif ( 'svg' !== strtolower( pathinfo( \$filename, PATHINFO_EXTENSION ) ) ) {\n" .
			"\t\treturn \$data;\n" .
			"\t}\n" .
			"\t\$data['ext'] = 'svg';\n" .
			"\t\$data['type'] = 'image/svg+xml';\n" .
			"\treturn \$data;\n" .
			"}, 10, 4 );\n\n" .
			"add_action( 'after_setup_theme', static function (): void {\n" .
			"\tadd_theme_support( 'editor-styles' );\n" .
			"\tadd_editor_style( 'assets/css/editor-style.css' );\n" .
			"} );\n\n" .
			"add_action( 'wp_enqueue_scripts', static function (): void {\n" .
			$stylesheet_lines .
			"\twp_enqueue_style( '" . $style_handle . "', get_stylesheet_uri(), " . $stylesheet_dependencies . ", wp_get_theme()->get( 'Version' ) );\n" .
			$script_lines .
			"} );\n\n" .
			"add_action( 'enqueue_block_editor_assets', static function (): void {\n" .
			$stylesheet_lines .
			"\twp_enqueue_style( '" . $editor_handle . "', get_template_directory_uri() . '/assets/css/editor-style.css', " . $stylesheet_dependencies . ", wp_get_theme()->get( 'Version' ) );\n" .
			"} );\n";
	}

	/**
	 * Build theme.json.
	 *
	 * @param string              $theme_name Theme name.
	 * @param string              $css        Source CSS.
	 * @param array<string,mixed> $artifacts  Compiled website artifacts.
	 * @return string
	 */
	private static function theme_json( string $theme_name, string $css, array $artifacts = array() ): string {
		$data = array(
			'$schema'  => 'https://schemas.wp.org/trunk/theme.json',
			'version'  => 3,
			'title'    => $theme_name,
			'settings' => array(
				'layout' => array(
					'contentSize' => '760px',
					'wideSize'    => '1200px',
				),
				'spacing' => array(
					'blockGap' => true,
				),
			),
		);

		$design_tokens = self::design_tokens_from_css( $css );
		if ( ! empty( $design_tokens['palette'] ) ) {
			$data['settings']['color']['palette'] = $design_tokens['palette'];
		}

		$data['styles']['spacing']['blockGap'] = '0';

		if ( ! empty( $design_tokens['styles'] ) ) {
			$data['styles']['color'] = $design_tokens['styles'];
		}

		$body_font_family = self::body_font_family_from_css( $css );
		if ( null !== $body_font_family ) {
			$data['styles']['typography']['fontFamily'] = $body_font_family;
		}

		$data = self::merge_theme_json_fragment( $data, self::theme_json_fragment_from_artifacts( $artifacts ) );

		return wp_json_encode( $data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) . "\n";
	}

	/**
	 * Read explicit theme.json metadata from compiled artifacts.
	 *
	 * The importer only promotes data under stable generic keys. Figma-specific or
	 * source-specific inference belongs upstream in the transformer contract.
	 *
	 * @param array<string,mixed> $artifacts Compiled website artifacts.
	 * @return array<string,mixed>
	 */
	private static function theme_json_fragment_from_artifacts( array $artifacts ): array {
		$site      = isset( $artifacts['site'] ) && is_array( $artifacts['site'] ) ? $artifacts['site'] : array();
		$theme     = isset( $site['theme'] ) && is_array( $site['theme'] ) ? $site['theme'] : array();
		$fragments = array();

		foreach ( array( $artifacts['theme_json'] ?? null, $site['theme_json'] ?? null, $theme['theme_json'] ?? null ) as $candidate ) {
			if ( is_array( $candidate ) ) {
				$fragments[] = self::safe_theme_json_fragment( $candidate );
			}
		}

		foreach ( array( $artifacts['design_tokens'] ?? null, $site['design_tokens'] ?? null, $theme['design_tokens'] ?? null, $site['tokens'] ?? null ) as $candidate ) {
			if ( is_array( $candidate ) ) {
				$fragments[] = self::theme_json_fragment_from_design_tokens( $candidate );
			}
		}

		$fragment = array();
		foreach ( $fragments as $candidate ) {
			$fragment = self::merge_theme_json_fragment( $fragment, $candidate );
		}

		return $fragment;
	}

	/**
	 * Convert conservative design-token rows into theme.json settings/styles.
	 *
	 * @param array<string,mixed> $tokens Design token metadata.
	 * @return array<string,mixed>
	 */
	private static function theme_json_fragment_from_design_tokens( array $tokens ): array {
		$fragment = array();
		$palette  = self::theme_json_palette_from_token_rows( $tokens['colors'] ?? $tokens['palette'] ?? array() );
		$fonts    = self::theme_json_font_families_from_token_rows( $tokens['font_families'] ?? $tokens['fontFamilies'] ?? $tokens['fonts'] ?? array() );

		if ( ! empty( $palette ) ) {
			$fragment['settings']['color']['palette'] = $palette;
		}

		if ( ! empty( $fonts ) ) {
			$fragment['settings']['typography']['fontFamilies'] = $fonts;
		}

		$layout = isset( $tokens['layout'] ) && is_array( $tokens['layout'] ) ? $tokens['layout'] : array();
		foreach ( array( 'contentSize', 'wideSize' ) as $key ) {
			if ( isset( $layout[ $key ] ) && is_scalar( $layout[ $key ] ) && self::is_safe_css_size_value( (string) $layout[ $key ] ) ) {
				$fragment['settings']['layout'][ $key ] = (string) $layout[ $key ];
			}
		}

		return $fragment;
	}

	/**
	 * Normalize color token rows for theme.json palette.
	 *
	 * @param mixed $rows Token rows.
	 * @return array<int,array{slug:string,name:string,color:string}>
	 */
	private static function theme_json_palette_from_token_rows( mixed $rows ): array {
		if ( ! is_array( $rows ) ) {
			return array();
		}

		$palette = array();
		$seen    = array();
		foreach ( $rows as $row ) {
			if ( ! is_array( $row ) ) {
				continue;
			}

			$slug  = isset( $row['slug'] ) && is_scalar( $row['slug'] ) ? sanitize_title( (string) $row['slug'] ) : '';
			$name  = isset( $row['name'] ) && is_scalar( $row['name'] ) ? trim( (string) $row['name'] ) : '';
			$color = isset( $row['color'] ) && is_scalar( $row['color'] ) ? trim( (string) $row['color'] ) : '';

			if ( '' === $slug || '' === $name || isset( $seen[ $slug ] ) || ! self::is_safe_color_value( $color ) ) {
				continue;
			}

			$seen[ $slug ] = true;
			$palette[]     = array(
				'slug'  => $slug,
				'name'  => $name,
				'color' => $color,
			);
		}

		return $palette;
	}

	/**
	 * Normalize font-family token rows for theme.json typography settings.
	 *
	 * @param mixed $rows Token rows.
	 * @return array<int,array{slug:string,name:string,fontFamily:string}>
	 */
	private static function theme_json_font_families_from_token_rows( mixed $rows ): array {
		if ( ! is_array( $rows ) ) {
			return array();
		}

		$fonts = array();
		$seen  = array();
		foreach ( $rows as $row ) {
			if ( ! is_array( $row ) ) {
				continue;
			}

			$slug        = isset( $row['slug'] ) && is_scalar( $row['slug'] ) ? sanitize_title( (string) $row['slug'] ) : '';
			$name        = isset( $row['name'] ) && is_scalar( $row['name'] ) ? trim( (string) $row['name'] ) : '';
			$font_family = isset( $row['fontFamily'] ) && is_scalar( $row['fontFamily'] ) ? (string) $row['fontFamily'] : ( isset( $row['font_family'] ) && is_scalar( $row['font_family'] ) ? (string) $row['font_family'] : '' );

			if ( '' === $slug || '' === $name || isset( $seen[ $slug ] ) || ! self::is_safe_font_family_value( $font_family ) ) {
				continue;
			}

			$seen[ $slug ] = true;
			$fonts[]       = array(
				'slug'       => $slug,
				'name'       => $name,
				'fontFamily' => trim( $font_family ),
			);
		}

		return $fonts;
	}

	/**
	 * Filter an explicit theme.json fragment to importer-supported top-level keys.
	 *
	 * @param array<string,mixed> $fragment Candidate theme.json fragment.
	 * @return array<string,mixed>
	 */
	private static function safe_theme_json_fragment( array $fragment ): array {
		$safe = array();
		foreach ( array( 'settings', 'styles', 'customTemplates', 'templateParts', 'patterns' ) as $key ) {
			if ( isset( $fragment[ $key ] ) && self::theme_json_value_is_safe( $fragment[ $key ] ) ) {
				$safe[ $key ] = $fragment[ $key ];
			}
		}

		return $safe;
	}

	/**
	 * Deep-merge a theme.json fragment into base data.
	 *
	 * @param array<string,mixed> $base     Base theme.json data.
	 * @param array<string,mixed> $fragment Fragment to merge.
	 * @return array<string,mixed>
	 */
	private static function merge_theme_json_fragment( array $base, array $fragment ): array {
		foreach ( $fragment as $key => $value ) {
			if ( is_array( $value ) && isset( $base[ $key ] ) && is_array( $base[ $key ] ) && self::array_is_assoc( $value ) && self::array_is_assoc( $base[ $key ] ) ) {
				$base[ $key ] = self::merge_theme_json_fragment( $base[ $key ], $value );
			} else {
				$base[ $key ] = $value;
			}
		}

		return $base;
	}

	/**
	 * Check whether a theme.json fragment value is JSON-safe and bounded.
	 *
	 * @param mixed $value Candidate value.
	 * @param int   $depth Current recursion depth.
	 * @return bool
	 */
	private static function theme_json_value_is_safe( mixed $value, int $depth = 0 ): bool {
		if ( $depth > 8 ) {
			return false;
		}

		if ( is_string( $value ) ) {
			return strlen( $value ) <= 1000 && ! preg_match( '/[<>]/', $value );
		}

		if ( is_int( $value ) || is_float( $value ) || is_bool( $value ) || null === $value ) {
			return true;
		}

		if ( ! is_array( $value ) || count( $value ) > 200 ) {
			return false;
		}

		foreach ( $value as $key => $child ) {
			if ( ! is_int( $key ) && ! preg_match( '/^[A-Za-z0-9_\-]+$/', $key ) ) {
				return false;
			}

			if ( ! self::theme_json_value_is_safe( $child, $depth + 1 ) ) {
				return false;
			}
		}

		return true;
	}

	/**
	 * Check whether an array has string keys.
	 *
	 * @param array<mixed> $value Array to inspect.
	 * @return bool
	 */
	private static function array_is_assoc( array $value ): bool {
		if ( array() === $value ) {
			return false;
		}

		return array_keys( $value ) !== range( 0, count( $value ) - 1 );
	}

	/**
	 * Extract a safe body font-family declaration from source CSS.
	 *
	 * @param string $css Source CSS.
	 * @return string|null
	 */
	private static function body_font_family_from_css( string $css ): ?string {
		$css = trim( (string) preg_replace( '/\/\*.*?\*\//s', '', $css ) );
		if ( '' === $css || ! preg_match_all( '/([^{}]+)\{([^{}]*)\}/', $css, $rule_matches, PREG_SET_ORDER ) ) {
			return null;
		}

		$custom_properties = self::css_custom_properties( $css );

		foreach ( $rule_matches as $rule_match ) {
			$selectors = array_map( 'trim', explode( ',', strtolower( $rule_match[1] ) ) );
			if ( ! in_array( 'body', $selectors, true ) ) {
				continue;
			}

			if ( ! preg_match( '/(?:^|;)\s*font-family\s*:\s*([^;{}]+)/i', $rule_match[2], $property_match ) ) {
				continue;
			}

			$value = trim( preg_replace( '/\s*!important\s*$/i', '', $property_match[1] ) );

			// Source typography is commonly applied through CSS custom properties
			// (`body { font-family: var(--font-body) }`). Resolve the reference to
			// the concrete typeface stack so theme.json carries a font-family that
			// actually applies, rather than an undefined `var(--font-body)` that
			// silently falls back to the default theme font.
			$value = self::resolve_css_variables( $value, $custom_properties );

			if ( self::is_safe_font_family_value( $value ) ) {
				return $value;
			}
		}

		return null;
	}

	/**
	 * Collect `--name: value` custom-property declarations from CSS.
	 *
	 * @param string $css Source CSS.
	 * @return array<string,string> Map of property name to declared value.
	 */
	private static function css_custom_properties( string $css ): array {
		if ( ! preg_match_all( '/(--[A-Za-z0-9_-]+)\s*:\s*([^;{}]+)/', $css, $matches, PREG_SET_ORDER ) ) {
			return array();
		}

		$properties = array();
		foreach ( $matches as $match ) {
			$properties[ (string) $match[1] ] = trim( (string) $match[2] );
		}

		return $properties;
	}

	/**
	 * Expand `var(--name[, fallback])` references using custom-property definitions.
	 *
	 * Bounded recursive passes resolve variables whose values reference other
	 * variables. Unresolved references are left intact so the caller's safety
	 * validation rejects them.
	 *
	 * @param string                $value      CSS value possibly containing var() references.
	 * @param array<string,string>  $properties Custom-property map.
	 * @return string
	 */
	private static function resolve_css_variables( string $value, array $properties ): string {
		if ( false === strpos( $value, 'var(' ) ) {
			return $value;
		}

		for ( $pass = 0; $pass < 5; $pass++ ) {
			$expanded = preg_replace_callback(
				'/var\(\s*(--[A-Za-z0-9_-]+)\s*(?:,\s*([^()]*))?\)/',
				static function ( array $matches ) use ( $properties ): string {
					$name = (string) $matches[1];
					if ( isset( $properties[ $name ] ) && '' !== $properties[ $name ] ) {
						return $properties[ $name ];
					}

					return ( isset( $matches[2] ) && '' !== trim( (string) $matches[2] ) ) ? trim( (string) $matches[2] ) : (string) $matches[0];
				},
				$value
			);

			if ( ! is_string( $expanded ) || $expanded === $value ) {
				break;
			}
			$value = $expanded;
		}

		return trim( $value );
	}

	/**
	 * Check whether a CSS font-family value is safe to expose in theme.json.
	 *
	 * @param string $value CSS font-family value.
	 * @return bool
	 */
	private static function is_safe_font_family_value( string $value ): bool {
		$value = trim( $value );
		if ( '' === $value || strlen( $value ) > 300 ) {
			return false;
		}

		if ( preg_match( '/[<>;{}]/', $value ) || preg_match( '/\b(?:expression|url|import)\s*\(/i', $value ) ) {
			return false;
		}

		// A real font-family stack never contains CSS function syntax. Reject any
		// leftover parentheses (e.g. an unresolved `var(--font-body)`) so a dead
		// custom-property reference is never written into theme.json.
		if ( false !== strpos( $value, '(' ) || false !== strpos( $value, ')' ) ) {
			return false;
		}

		return (bool) preg_match( '/^[A-Za-z0-9_\-\s,"\']+$/', $value );
	}

	/**
	 * Extract conservative design tokens from obvious :root custom properties.
	 *
	 * @param string $css Source CSS.
	 * @return array{palette:array<int,array{slug:string,name:string,color:string}>,styles:array<string,string>}
	 */
	private static function design_tokens_from_css( string $css ): array {
		$palette = array();
		$styles  = array();
		$seen    = array();

		if ( '' === trim( $css ) || ! preg_match_all( '/:root\s*\{([^}]*)\}/i', $css, $root_matches ) ) {
			return array(
				'palette' => $palette,
				'styles'  => $styles,
			);
		}

		foreach ( $root_matches[1] as $root_body ) {
			$root_body = (string) preg_replace( '/\/\*.*?\*\//s', '', $root_body );
			if ( ! preg_match_all( '/--([A-Za-z0-9_-]+)\s*:\s*([^;{}]+);/', $root_body, $property_matches, PREG_SET_ORDER ) ) {
				continue;
			}

			foreach ( $property_matches as $property_match ) {
				$token_name = strtolower( $property_match[1] );
				$color      = trim( $property_match[2] );
				$slug       = sanitize_title( $token_name );

				if ( '' === $slug || isset( $seen[ $slug ] ) || ! self::is_safe_color_value( $color ) ) {
					continue;
				}

				$seen[ $slug ] = true;
				$palette[]     = array(
					'slug'  => $slug,
					'name'  => ucwords( str_replace( array( '-', '_' ), ' ', $token_name ) ),
					'color' => $color,
				);

				if ( ! isset( $styles['background'] ) && in_array( $slug, array( 'bg', 'background' ), true ) ) {
					$styles['background'] = 'var(--wp--preset--color--' . $slug . ')';
				}

				if ( ! isset( $styles['text'] ) && in_array( $slug, array( 'fg', 'foreground', 'text' ), true ) ) {
					$styles['text'] = 'var(--wp--preset--color--' . $slug . ')';
				}
			}
		}

		return array(
			'palette' => $palette,
			'styles'  => $styles,
		);
	}

	/**
	 * Check whether a CSS value is safe to expose as a theme palette color.
	 *
	 * @param string $value CSS value.
	 * @return bool
	 */
	private static function is_safe_color_value( string $value ): bool {
		$value = trim( $value );

		if ( preg_match( '/^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i', $value ) ) {
			return true;
		}

		return (bool) preg_match( '/^(?:rgb|rgba|hsl|hsla)\(\s*[-+0-9.%\s,\/]+\s*\)$/i', $value );
	}

	/**
	 * Check whether a CSS size is safe to expose in theme.json layout settings.
	 *
	 * @param string $value CSS size value.
	 * @return bool
	 */
	private static function is_safe_css_size_value( string $value ): bool {
		$value = trim( $value );
		if ( '' === $value || strlen( $value ) > 80 || preg_match( '/[<>;{}]/', $value ) ) {
			return false;
		}

		return (bool) preg_match( '/^(?:\d+(?:\.\d+)?(?:px|rem|em|vw|vh|%)|clamp\(\s*[-+0-9.%\s,\/a-z]+\s*\)|min\(\s*[-+0-9.%\s,\/a-z]+\s*\)|max\(\s*[-+0-9.%\s,\/a-z]+\s*\))$/i', $value );
	}

	/**
	 * Write a generated file.
	 *
	 * @param string $path    File path.
	 * @param string $content File content.
	 * @return true|WP_Error
	 */
	public static function write_file( string $path, string $content ) {
		$dir = dirname( $path );
		if ( '' !== $dir && '.' !== $dir && ! is_dir( $dir ) && ! wp_mkdir_p( $dir ) ) {
			return new WP_Error( 'static_site_importer_write_mkdir_failed', sprintf( 'Failed to create generated file directory: %s', $dir ) );
		}

		// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_file_put_contents -- Writes generated block-theme files to the selected theme directory.
		$result = file_put_contents( $path, $content );
		if ( false === $result ) {
			return new WP_Error( 'static_site_importer_write_failed', sprintf( 'Failed to write file: %s', $path ) );
		}

		return true;
	}

	/**
	 * Write a copy of the import report to a caller-selected path.
	 *
	 * @param string $path    Report path.
	 * @param string $content Report JSON.
	 * @return true|WP_Error
	 */
	public static function write_external_report( string $path, string $content ) {
		$dir = dirname( $path );
		if ( ! wp_mkdir_p( $dir ) ) {
			return new WP_Error( 'static_site_importer_report_mkdir_failed', sprintf( 'Failed to create report directory: %s', $dir ) );
		}

		return self::write_file( $path, $content );
	}

	/**
	 * Determine whether a path resolves inside a base directory.
	 *
	 * @param string $path Path to test.
	 * @param string $base Base directory.
	 * @return bool
	 */
	public static function path_is_under( string $path, string $base ): bool {
		$real_path = realpath( $path );
		$real_base = realpath( $base );

		if ( false === $real_path || false === $real_base ) {
			return false;
		}

		return 0 === strpos( trailingslashit( $real_path ), trailingslashit( $real_base ) );
	}

	/**
	 * Resolve a MIME type from a materialized path.
	 *
	 * @param string $path File path.
	 * @return string
	 */
	private static function mime_type( string $path ): string {
		return match ( strtolower( pathinfo( $path, PATHINFO_EXTENSION ) ) ) {
			'html', 'htm' => 'text/html',
			'css'         => 'text/css',
			'js', 'mjs'    => 'text/javascript',
			'json'        => 'application/json',
			'svg'         => 'image/svg+xml',
			'png'         => 'image/png',
			'jpg', 'jpeg'  => 'image/jpeg',
			'gif'         => 'image/gif',
			'webp'        => 'image/webp',
			'avif'        => 'image/avif',
			'woff'        => 'font/woff',
			'woff2'       => 'font/woff2',
			default       => 'application/octet-stream',
		};
	}
}