<?php
/**
 * Fills the templates/theme-stubs/ .tpl files from a parsed document,
 * rewritten assets, and mapped nav items, producing an entirely
 * in-memory Generated_Theme. Never touches disk and never calls a live
 * WordPress function — including slug sanitization, which uses a small
 * local helper instead of sanitize_title() so this class stays testable
 * without a WordPress runtime.
 *
 * @package Esipher
 */

namespace Esipher;

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

/**
 * Generates the six required theme files from stub templates.
 */
class Theme_Generator {

	/**
	 * Directory containing the .tpl stub files.
	 *
	 * @var string
	 */
	private $stub_dir;

	/**
	 * Default fallback name used when a slug can't be derived.
	 */
	const FALLBACK_SLUG = 'esipher-theme';

	/**
	 * Constructor.
	 *
	 * @param string|null $stub_dir Absolute path to templates/theme-stubs/;
	 *                              defaults to the plugin's own copy,
	 *                              resolved relative to this file rather
	 *                              than any global constant.
	 */
	public function __construct( $stub_dir = null ) {
		$this->stub_dir = $stub_dir ? rtrim( $stub_dir, '/' ) . '/' : dirname( __DIR__ ) . '/templates/theme-stubs/';
	}

	/**
	 * Generate the theme file set.
	 *
	 * @param Parsed_Document  $doc              Parsed source document.
	 * @param Rewritten_Assets $assets           Rewritten asset output.
	 * @param array[]          $nav_items        Nav_Mapper::map() output.
	 *                                           Always empty for a
	 *                                           multi-page conversion —
	 *                                           each page's own nav
	 *                                           travels inside its own
	 *                                           content instead of one
	 *                                           shared wp_nav_menu() call.
	 * @param string           $preferred_slug   Desired theme slug.
	 * @param string           $version          Theme version string.
	 * @param bool             $has_page_content Whether Generated_Theme::
	 *                                           $pages will be populated
	 *                                           by the caller — removes
	 *                                           wpautop/wptexturize from
	 *                                           the_content (see
	 *                                           render_page_content_asset_filter()'s
	 *                                           own docblock). Default
	 *                                           false (the ordinary
	 *                                           single-page path).
	 *
	 * @return Generated_Theme
	 */
	public function generate( Parsed_Document $doc, Rewritten_Assets $assets, array $nav_items, $preferred_slug, $version = '1.0.0', $has_page_content = false ) {
		$slug            = $this->sanitize_slug( $preferred_slug );
		$function_prefix = str_replace( '-', '_', $slug );
		$theme_name      = '' !== $doc->title ? $doc->title : ucwords( str_replace( array( '-', '_' ), ' ', $slug ) );

		// A multi-page conversion ships no framework JS (see
		// Multi_Page_Rewriter), so nothing wires up the mobile menu
		// toggle. Bundle a tiny dependency-free helper that does.
		$nav_helper_js = $has_page_content ? $this->load_nav_helper_js() : '';

		if ( '' !== $nav_helper_js ) {
			$assets->enqueue_php = rtrim( $assets->enqueue_php ) . "\n" . sprintf(
				"wp_enqueue_script( %s, get_template_directory_uri() . '/assets/esipher-nav.js', array(), %s, true );",
				$this->php_string_literal( $slug . '-esipher-nav' ),
				$this->php_string_literal( $version )
			);
		}

		$tokens = array(
			'{{THEME_NAME}}'                => $theme_name,
			'{{THEME_SLUG}}'                => $slug,
			'{{THEME_VERSION}}'             => $version,
			'{{THEME_DESCRIPTION}}'         => $this->extract_description( $doc ),
			'{{FUNCTION_PREFIX}}'           => $function_prefix,
			'{{ENQUEUE_CALLS}}'             => $this->indent( $assets->enqueue_php ),
			'{{HEAD_META_TAGS}}'            => $this->render_head_tags( $doc ),
			'{{NAV_MENU_CALL}}'             => $this->render_nav_call( $nav_items, $function_prefix ),
			'{{NAV_FALLBACK_FUNCTION}}'     => $this->render_nav_fallback_function( $nav_items, $function_prefix ),
			'{{BODY_CONTENT}}'              => $assets->body_html,
			'{{ROOT_ASSET_SERVER}}'         => $this->render_root_asset_server( $assets->root_files, $assets->favicon_request_path, $function_prefix ),
			'{{MODULE_SCRIPT_FILTER}}'      => $this->render_module_script_filter( $assets->module_script_handles, $function_prefix ),
			'{{THEME_COLOR_CUSTOMIZER}}'    => $this->render_theme_color_customizer( $assets->theme_color_vars, $slug, $function_prefix ),
			'{{PAGE_CONTENT_ASSET_FILTER}}' => $this->render_page_content_asset_filter( $has_page_content, $function_prefix ),
		);

		$theme                 = new Generated_Theme();
		$theme->slug           = $slug;
		$theme->assets_to_copy = $assets->copy_manifest;

		foreach ( array( 'style.css', 'functions.php', 'header.php', 'footer.php', 'index.php', 'page.php' ) as $file ) {
			$theme->files[ $file ] = $this->render_stub( $file . '.tpl', $tokens );
		}

		if ( '' !== $nav_helper_js ) {
			$theme->files['assets/esipher-nav.js'] = $nav_helper_js;
		}

		// CSS/JS files with rewritten content get that content written
		// directly rather than raw-copied — see rewrite_css_urls() and
		// Asset_Rewriter::rewrite_vite_preload_base().
		foreach ( array_merge( $assets->css_rewrites, $assets->js_rewrites ) as $dest_relative => $content ) {
			$theme->files[ $dest_relative ] = $content;

			$source_path = array_search( $dest_relative, $theme->assets_to_copy, true );

			if ( false !== $source_path ) {
				unset( $theme->assets_to_copy[ $source_path ] );
			}
		}

		return $theme;
	}

	/**
	 * Load a .tpl file and substitute every token in one pass.
	 *
	 * @param string $filename Stub filename, e.g. 'style.css.tpl'.
	 * @param array  $tokens   Token => replacement map.
	 *
	 * @return string
	 */
	private function render_stub( $filename, array $tokens ) {
		$contents = file_get_contents( $this->stub_dir . $filename );

		return strtr( $contents, $tokens );
	}

	/**
	 * @return string Contents of the bundled mobile-nav helper script,
	 *                or '' if it can't be read.
	 */
	private function load_nav_helper_js() {
		$path = dirname( __DIR__ ) . '/templates/theme-assets/esipher-nav.js';

		if ( ! is_file( $path ) ) {
			return '';
		}

		$js = file_get_contents( $path ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- reading this plugin's own bundled asset.

		return false !== $js ? $js : '';
	}

	/**
	 * Prefer the source document's meta description; fall back to a
	 * generic note when none was present.
	 *
	 * @param Parsed_Document $doc Parsed source document.
	 *
	 * @return string
	 */
	private function extract_description( Parsed_Document $doc ) {
		foreach ( $doc->meta as $attrs ) {
			if ( isset( $attrs['name'] ) && 'description' === $attrs['name'] && ! empty( $attrs['content'] ) ) {
				return $attrs['content'];
			}
		}

		return 'Converted from an AI site-builder export by Esipher.';
	}

	/**
	 * Render the head <meta>/<link> tags to carry over verbatim: every
	 * <meta> except charset/viewport (header.php already emits those),
	 * and every <link> except rel="stylesheet" (already enqueued).
	 *
	 * @param Parsed_Document $doc Parsed source document.
	 *
	 * @return string
	 */
	private function render_head_tags( Parsed_Document $doc ) {
		$lines = array();

		foreach ( $doc->meta as $attrs ) {
			if ( isset( $attrs['charset'] ) ) {
				continue;
			}

			if ( isset( $attrs['name'] ) && 'viewport' === $attrs['name'] ) {
				continue;
			}

			$lines[] = '<meta ' . $this->render_attributes( $attrs ) . '>';
		}

		foreach ( $doc->links as $attrs ) {
			if ( isset( $attrs['rel'] ) && 'stylesheet' === strtolower( $attrs['rel'] ) ) {
				continue;
			}

			$rel = isset( $attrs['rel'] ) ? strtolower( $attrs['rel'] ) : '';
			$as  = isset( $attrs['as'] ) ? strtolower( $attrs['as'] ) : '';

			if ( isset( $attrs['href'] ) && ( 'modulepreload' === $rel || ( 'preload' === $rel && 'image' === $as ) ) ) {
				$attrs['href'] = $this->rewrite_asset_preload_href( $attrs['href'] );
			}

			$lines[] = '<link ' . $this->render_attributes( $attrs ) . '>';
		}

		return $this->indent( implode( "\n", $lines ) );
	}

	/**
	 * A <link rel="modulepreload"> or <link rel="preload" as="image">
	 * carries over the export's original root-relative href (e.g.
	 * "/assets/vendor-abc123.js" or "/assets/hero-abc123.jpg"), which no
	 * longer matches where the theme actually serves that file from
	 * (wp-content/themes/{slug}/assets/...) — rewritten the same way for
	 * both, since both are the same underlying problem at different tag
	 * types:
	 * - modulepreload left as-is: the browser preloads and registers the
	 *   module under the stale root URL while the app's own import()
	 *   calls resolve it under the theme URL — two different URLs for the
	 *   same file means two separate ES module instances, so React, the
	 *   Supabase client, etc. all get instantiated twice and end up
	 *   fighting over the same DOM ("removeChild" errors, "Multiple
	 *   GoTrueClient instances"). Verified against a real heavily
	 *   code-split export that broke exactly this way.
	 * - preload-as-image left as-is: just a wasted, always-404 request —
	 *   verified against a real export (the actual <img> tag pointing at
	 *   the same file is separately, correctly rewritten via Asset_
	 *   Rewriter's normal body-asset handling, so the image still
	 *   displays; this preload hint just never helps and litters the
	 *   console/network tab with a permanent failed request otherwise).
	 *
	 * External hrefs are left untouched in both cases.
	 *
	 * @param string $href Original href attribute value.
	 *
	 * @return string
	 */
	private function rewrite_asset_preload_href( $href ) {
		if ( preg_match( '#^(?:[a-z][a-z0-9+.-]*:)?//#i', $href ) ) {
			return $href;
		}

		$basename = basename( (string) wp_parse_url( $href, PHP_URL_PATH ) );

		if ( '' === $basename ) {
			return $href;
		}

		return '<?php echo esc_url( get_template_directory_uri() . \'/assets/' . $basename . '\' ); ?>';
	}

	/**
	 * Serialize an attribute assoc array back to `key="value"` pairs.
	 *
	 * @param array<string,string> $attrs Attribute map.
	 *
	 * @return string
	 */
	private function render_attributes( array $attrs ) {
		$parts = array();

		foreach ( $attrs as $key => $value ) {
			$parts[] = $key . '="' . str_replace( '"', '&quot;', $value ) . '"';
		}

		return implode( ' ', $parts );
	}

	/**
	 * A wp_nav_menu() call with a fallback to the hardcoded menu function,
	 * so a real WP menu can be assigned later in Appearance > Menus
	 * without ever breaking the header in the meantime. Omitted entirely
	 * when no nav was found in the source export.
	 *
	 * @param array[] $nav_items      Nav_Mapper::map() output.
	 * @param string  $function_prefix Theme function name prefix.
	 *
	 * @return string
	 */
	private function render_nav_call( array $nav_items, $function_prefix ) {
		if ( empty( $nav_items ) ) {
			return '';
		}

		return sprintf(
			"<?php wp_nav_menu( array( 'theme_location' => 'primary', 'fallback_cb' => '%s_fallback_menu' ) ); ?>",
			$function_prefix
		);
	}

	/**
	 * A request interceptor, destined for functions.php, that serves
	 * "passthrough" files back at their original site-root-relative path
	 * — e.g. a request for /logo.ico or /assets/hero-abc123.png is
	 * served from the theme's own copy — regardless of where in the
	 * source (often compiled JS) the reference lives. Omitted when
	 * Asset_Rewriter found no such files to copy through.
	 *
	 * $root_files is a fixed whitelist built entirely from real scanned
	 * filenames (see Asset_Rewriter::copy_passthrough_files()), never
	 * from request input, so an exact in_array() match is the only
	 * safety check this needs — allowing a '/' in the matched path (for
	 * the assets/... case) doesn't reopen any path-traversal risk.
	 *
	 * The robots.txt file is intentionally never among $root_files (see
	 * Asset_Rewriter::discover_root_passthrough_files()), so this never
	 * competes with WordPress core's own dynamic /robots.txt.
	 *
	 * @param string[]    $root_files            Site-root-relative paths
	 *                                           copied into the theme.
	 * @param string|null $favicon_request_path  Rewritten_Assets::
	 *                                           $favicon_request_path.
	 * @param string      $function_prefix       Theme function name prefix.
	 *
	 * @return string
	 */
	private function render_root_asset_server( array $root_files, $favicon_request_path, $function_prefix ) {
		if ( empty( $root_files ) ) {
			return '';
		}

		$known_array = implode(
			', ',
			array_map( array( $this, 'php_string_literal' ), $root_files )
		);

		// A WordPress Customizer "Site Icon" set via Appearance >
		// Customize > Site Identity only affects WP-native chrome
		// (admin, login, wp_site_icon()'s own <link> tags) by default —
		// the SPA never calls any of that, it just requests whatever
		// favicon path was baked into its own markup. Redirecting that
		// one known path to the site icon's real URL when one is set
		// makes "Site Icon" actually change what the browser shows.
		$favicon_override = '';

		if ( null !== $favicon_request_path && in_array( $favicon_request_path, $root_files, true ) ) {
			$favicon_override = "\n\tif ( " . $this->php_string_literal( $favicon_request_path ) . " === \$relative_path && has_site_icon() ) {\n"
				. "\t\twp_safe_redirect( get_site_icon_url( 512 ), 302 );\n"
				. "\t\texit;\n"
				. "\t}\n";
		}

		$template = <<<'EOT'
function {{PREFIX}}_serve_root_asset() {
	$known = array( {{KNOWN}} );

	$request_path  = isset( $_SERVER['REQUEST_URI'] ) ? wp_parse_url( wp_unslash( $_SERVER['REQUEST_URI'] ), PHP_URL_PATH ) : '';
	$relative_path = ltrim( (string) $request_path, '/' );

	if ( '' === $relative_path || ! in_array( $relative_path, $known, true ) ) {
		return;
	}
{{FAVICON_OVERRIDE}}
	$file = get_template_directory() . '/' . $relative_path;

	if ( ! file_exists( $file ) ) {
		return;
	}

	// wp_check_filetype() doesn't reliably resolve some extensions this
	// passthrough mechanism regularly serves (.js in particular isn't in
	// WordPress core's allowed-mimes list, so it falls back to
	// application/octet-stream) — a service worker script served with
	// the wrong MIME type fails to register outright, so these are
	// resolved explicitly first.
	$known_mime_types = array(
		'js'          => 'application/javascript',
		'mjs'         => 'application/javascript',
		'json'        => 'application/json',
		'webmanifest' => 'application/manifest+json',
		'css'         => 'text/css',
		'ico'         => 'image/x-icon',
		'png'         => 'image/png',
		'jpg'         => 'image/jpeg',
		'jpeg'        => 'image/jpeg',
		'svg'         => 'image/svg+xml',
		'gif'         => 'image/gif',
		'webp'        => 'image/webp',
		'woff'        => 'font/woff',
		'woff2'       => 'font/woff2',
		'ttf'         => 'font/ttf',
		'txt'         => 'text/plain',
		'xml'         => 'application/xml',
	);

	$extension = strtolower( pathinfo( $file, PATHINFO_EXTENSION ) );

	if ( isset( $known_mime_types[ $extension ] ) ) {
		$content_type = $known_mime_types[ $extension ];
	} else {
		$filetype     = wp_check_filetype( $file );
		$content_type = $filetype['type'] ? $filetype['type'] : 'application/octet-stream';
	}

	// No explicit Content-Length: it would be the *uncompressed* file
	// size, but a server-level filter (e.g. Apache's mod_deflate) may
	// gzip the actual bytes sent afterward — declaring a length that
	// doesn't match what's really on the wire is tolerated by an
	// ordinary fetch() but broke real service worker registrations
	// outright ("unknown error fetching the script"), since that fetch
	// is validated more strictly. Let the server frame the response.
	header( 'Content-Type: ' . $content_type );

	readfile( $file );
	exit;
}
add_action( 'init', '{{PREFIX}}_serve_root_asset', 0 );
EOT;

		return strtr(
			$template,
			array(
				'{{PREFIX}}'           => $function_prefix,
				'{{KNOWN}}'            => $known_array,
				'{{FAVICON_OVERRIDE}}' => $favicon_override,
			)
		);
	}

	/**
	 * A script_loader_tag filter, destined for functions.php, that
	 * restores type="module" on exactly the enqueue handles that need it
	 * — wp_enqueue_script() doesn't preserve the original <script>'s
	 * type, which is harmless for a single self-contained bundle but
	 * breaks a code-split build outright (a real bundle with dozens of
	 * chunks importing each other failed at runtime with "Cannot use
	 * import statement outside a module" until this was added). Omitted
	 * when nothing needs it.
	 *
	 * @param string[] $module_handles  Enqueue handles needing type="module".
	 * @param string   $function_prefix Theme function name prefix.
	 *
	 * @return string
	 */
	private function render_module_script_filter( array $module_handles, $function_prefix ) {
		if ( empty( $module_handles ) ) {
			return '';
		}

		$handles_array = implode(
			', ',
			array_map( array( $this, 'php_string_literal' ), $module_handles )
		);

		$template = <<<'EOT'
function {{PREFIX}}_add_module_type( $tag, $handle, $src ) {
	$module_handles = array( {{HANDLES}} );

	if ( ! in_array( $handle, $module_handles, true ) || false !== strpos( $tag, ' type=' ) ) {
		return $tag;
	}

	return str_replace( ' src=', ' type="module" src=', $tag );
}
add_filter( 'script_loader_tag', '{{PREFIX}}_add_module_type', 10, 3 );
EOT;

		return strtr(
			$template,
			array(
				'{{PREFIX}}'  => $function_prefix,
				'{{HANDLES}}' => $handles_array,
			)
		);
	}

	/**
	 * Removes wpautop and wptexturize from the_content for a multi-page
	 * conversion's generated theme — both are default WordPress filters
	 * meant for hand-typed classic-editor content, not pre-rendered HTML,
	 * and both actively corrupt it: wpautop's blank-line heuristics
	 * insert stray <p> tags into an already-structured page (verified
	 * against a real multi-page export, where this closed an <a> card
	 * early and visually dropped a "Recent Posts" entry), and
	 * wptexturize mangles characters that are already correctly encoded
	 * (a straight ' inside raw HTML becoming a doubled/malformed curly
	 * quote). Every page this theme creates is exported markup, never
	 * something typed into the block editor, so removing both site-wide
	 * within this generated theme is safe. Omitted entirely for an
	 * ordinary single-page conversion.
	 *
	 * Asset_Rewriter::ASSETS_URL_PLACEHOLDER itself is *not* resolved
	 * here (unlike the single-page pipeline's body_html, which lives in
	 * an actual .php template and uses a real `<?php echo ... ?>`
	 * snippet) — a the_content filter can't know the theme's own final
	 * slug reliably (get_template_directory_uri() reflects whichever
	 * theme is currently *active*, not necessarily this one, and this
	 * filter would still be silently absent from the Block Editor's own
	 * canvas either way, since the editor reads raw post_content
	 * directly and never runs the_content on it — confirmed live: a
	 * successfully-bundled image showed correctly on the front end but
	 * broken in the editor). Installer::create_pages() resolves the
	 * placeholder to a real, absolute URL once instead, at the point it
	 * already knows this install's final slug.
	 *
	 * Also enqueues one small, fixed inline-CSS override neutralizing
	 * WordPress's own auto-injected `.wp-block-group__inner-container`
	 * wrapper div, which every core/group block's children get wrapped
	 * in regardless of what Block_Converter itself emits. Confirmed live
	 * against a real converted export: that wrapper sits directly
	 * between a Tailwind `grid lg:grid-cols-12` group and its own
	 * `lg:col-span-8` child group, silently breaking the grid
	 * relationship entirely (the child is no longer CSS Grid's *direct*
	 * child), collapsing that column to its longest word's width and
	 * wrapping the rest of its text one word per line. `display:
	 * contents` removes the wrapper from the layout tree without
	 * removing its children from the DOM, exactly undoing that —
	 * verified fixed live the same way. Safe unconditionally: the
	 * wrapper div itself never carries any of the page's own Tailwind
	 * classes (only WordPress's own generated ones), so there's no
	 * styling on it to lose.
	 *
	 * @param bool   $has_page_content Whether this theme has any
	 *                                 Generated_Theme::$pages content.
	 * @param string $function_prefix  Theme function name prefix.
	 *
	 * @return string
	 */
	private function render_page_content_asset_filter( $has_page_content, $function_prefix ) {
		if ( ! $has_page_content ) {
			return '';
		}

		$template = <<<'EOT'
remove_filter( 'the_content', 'wpautop' );
remove_filter( 'the_content', 'wptexturize' );

function {{PREFIX}}_enqueue_group_inner_container_fix() {
	wp_register_style( '{{PREFIX}}-group-inner-container-fix', false, array(), null );
	wp_enqueue_style( '{{PREFIX}}-group-inner-container-fix' );
	wp_add_inline_style( '{{PREFIX}}-group-inner-container-fix', '.wp-block-group__inner-container{display:contents}' );
}
add_action( 'wp_enqueue_scripts', '{{PREFIX}}_enqueue_group_inner_container_fix', 20 );
EOT;

		return strtr( $template, array( '{{PREFIX}}' => $function_prefix ) );
	}

	/**
	 * A Customizer section with one real color-picker control per
	 * detected :root CSS custom property (see Asset_Rewriter::
	 * discover_theme_color_vars()), plus a wp_head-hooked function that
	 * enqueues a small inline-CSS override for whichever ones the user has
	 * changed from the export's own default. Since these variables are
	 * consumed as hsl(var(--name)) by the app's own compiled CSS, this is
	 * genuine rebranding — not a token gesture — while remaining pure CSS
	 * layered on top; it never touches the compiled JS bundle. Omitted
	 * entirely when no such variables were detected.
	 *
	 * The generated hex<->HSL conversion function is a plain, WP-free PHP
	 * function embedded directly in the theme's own functions.php rather
	 * than calling back into this plugin's Color_Converter class: a
	 * theme must keep working if the Esipher plugin is later deactivated.
	 * Keep the two algorithms in sync if either ever changes — see
	 * Color_Converter's own docblock.
	 *
	 * @param array<string,string> $color_vars      Rewritten_Assets::
	 *                                               $theme_color_vars.
	 * @param string               $theme_slug      Text domain for
	 *                                              translatable labels.
	 * @param string               $function_prefix Theme function name
	 *                                              prefix.
	 *
	 * @return string
	 */
	private function render_theme_color_customizer( array $color_vars, $theme_slug, $function_prefix ) {
		if ( empty( $color_vars ) ) {
			return '';
		}

		$converter = new Color_Converter();

		$controls     = array();
		$var_defaults = array();

		foreach ( $color_vars as $var_name => $default_triplet ) {
			$mod_key     = $function_prefix . '_color_' . str_replace( '-', '_', $var_name );
			$default_hex = $converter->hsl_triplet_to_hex( $default_triplet );
			$label       = ucwords( str_replace( array( '-', '_' ), ' ', $var_name ) );

			$controls[] = "\t\$wp_customize->add_setting(\n"
				. "\t\t" . $this->php_string_literal( $mod_key ) . ",\n"
				. "\t\tarray(\n"
				. "\t\t\t'default'           => " . $this->php_string_literal( $default_hex ) . ",\n"
				. "\t\t\t'sanitize_callback' => 'sanitize_hex_color',\n"
				. "\t\t\t'transport'         => 'refresh',\n"
				. "\t\t)\n"
				. "\t);\n"
				. "\t\$wp_customize->add_control(\n"
				. "\t\tnew WP_Customize_Color_Control(\n"
				. "\t\t\t\$wp_customize,\n"
				. "\t\t\t" . $this->php_string_literal( $mod_key ) . ",\n"
				. "\t\t\tarray(\n"
				. "\t\t\t\t'label'   => __( " . $this->php_string_literal( $label ) . ', ' . $this->php_string_literal( $theme_slug ) . " ),\n"
				. "\t\t\t\t'section' => " . $this->php_string_literal( $function_prefix . '_colors' ) . ",\n"
				. "\t\t\t)\n"
				. "\t\t)\n"
				. "\t);\n";

			$var_defaults[] = "\t\t" . $this->php_string_literal( $mod_key ) . ' => array( '
				. "'var' => " . $this->php_string_literal( $var_name ) . ', '
				. "'default' => " . $this->php_string_literal( $default_hex ) . ' ),';
		}

		$template = <<<'EOT'
function {{PREFIX}}_register_theme_colors( $wp_customize ) {
	$wp_customize->add_section(
		{{SECTION_ID}},
		array(
			'title'    => __( 'Theme Colors', {{TEXT_DOMAIN}} ),
			'priority' => 30,
		)
	);

{{CONTROLS}}
}
add_action( 'customize_register', '{{PREFIX}}_register_theme_colors' );

function {{PREFIX}}_hsl_from_hex( $hex ) {
	$hex = ltrim( (string) $hex, '#' );

	if ( 3 === strlen( $hex ) ) {
		$hex = $hex[0] . $hex[0] . $hex[1] . $hex[1] . $hex[2] . $hex[2];
	}

	if ( 6 !== strlen( $hex ) || ! ctype_xdigit( $hex ) ) {
		return '0 0% 0%';
	}

	$r = hexdec( substr( $hex, 0, 2 ) ) / 255;
	$g = hexdec( substr( $hex, 2, 2 ) ) / 255;
	$b = hexdec( substr( $hex, 4, 2 ) ) / 255;

	$max = max( $r, $g, $b );
	$min = min( $r, $g, $b );
	$l   = ( $max + $min ) / 2;

	if ( $max === $min ) {
		$h = 0.0;
		$s = 0.0;
	} else {
		$d = $max - $min;
		$s = $l > 0.5 ? $d / ( 2 - $max - $min ) : $d / ( $max + $min );

		if ( $max === $r ) {
			$h = ( $g - $b ) / $d + ( $g < $b ? 6 : 0 );
		} elseif ( $max === $g ) {
			$h = ( $b - $r ) / $d + 2;
		} else {
			$h = ( $r - $g ) / $d + 4;
		}

		$h /= 6;
	}

	return round( $h * 360, 1 ) . ' ' . round( $s * 100, 1 ) . '% ' . round( $l * 100, 1 ) . '%';
}

function {{PREFIX}}_enqueue_theme_color_overrides() {
	$vars = array(
{{VAR_DEFAULTS}}
	);

	$lines = array();

	foreach ( $vars as $mod_key => $data ) {
		$hex = get_theme_mod( $mod_key, $data['default'] );

		if ( ! preg_match( '/^#[0-9a-fA-F]{3,8}$/', (string) $hex ) ) {
			continue;
		}

		$lines[] = '--' . $data['var'] . ': ' . {{PREFIX}}_hsl_from_hex( $hex ) . ';';
	}

	if ( empty( $lines ) ) {
		return;
	}

	wp_register_style( '{{PREFIX}}-theme-colors', false, array(), null );
	wp_enqueue_style( '{{PREFIX}}-theme-colors' );
	wp_add_inline_style( '{{PREFIX}}-theme-colors', ':root{' . implode( '', $lines ) . '}' );
}
add_action( 'wp_enqueue_scripts', '{{PREFIX}}_enqueue_theme_color_overrides', 20 );
EOT;

		return strtr(
			$template,
			array(
				'{{PREFIX}}'       => $function_prefix,
				'{{SECTION_ID}}'   => $this->php_string_literal( $function_prefix . '_colors' ),
				'{{TEXT_DOMAIN}}'  => $this->php_string_literal( $theme_slug ),
				'{{CONTROLS}}'     => implode( "\n", $controls ),
				'{{VAR_DEFAULTS}}' => implode( "\n", $var_defaults ),
			)
		);
	}

	/**
	 * A PHP function definition, destined for functions.php, that echoes
	 * the mapped nav items as a hardcoded <ul>. Omitted when there are no
	 * nav items (and render_nav_call() then omits the wp_nav_menu() call
	 * that would have referenced it).
	 *
	 * @param array[] $nav_items       Nav_Mapper::map() output.
	 * @param string  $function_prefix Theme function name prefix.
	 *
	 * @return string
	 */
	private function render_nav_fallback_function( array $nav_items, $function_prefix ) {
		if ( empty( $nav_items ) ) {
			return '';
		}

		$lines   = array();
		$lines[] = "function {$function_prefix}_fallback_menu() {";
		$lines[] = '?>';
		$lines[] = rtrim( $this->render_nav_list_html( $nav_items ) );
		$lines[] = '<?php';
		$lines[] = '}';

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

	/**
	 * Recursively render a nav item list (with dropdown children) as a
	 * plain <ul>/<li>/<a> tree.
	 *
	 * @param array[] $items Nav items, each with label/href/children.
	 *
	 * @return string
	 */
	private function render_nav_list_html( array $items ) {
		$html = "<ul class=\"esipher-fallback-menu\">\n";

		foreach ( $items as $item ) {
			$html .= '<li><a href="' . htmlspecialchars( $item['href'], ENT_QUOTES ) . '">'
				. htmlspecialchars( $item['label'], ENT_QUOTES ) . '</a>';

			if ( ! empty( $item['children'] ) ) {
				$html .= $this->render_nav_list_html( $item['children'] );
			}

			$html .= "</li>\n";
		}

		$html .= "</ul>\n";

		return $html;
	}

	/**
	 * Render a PHP single-quoted string literal for a value, escaping
	 * backslashes and single quotes.
	 *
	 * @param string $value Raw string value.
	 *
	 * @return string PHP source text, including the surrounding quotes.
	 */
	private function php_string_literal( $value ) {
		return "'" . addcslashes( $value, "'\\" ) . "'";
	}

	/**
	 * Prefix every line of $text with a tab, for readability inside the
	 * generated PHP function bodies. A no-op for empty input.
	 *
	 * @param string $text Multi-line text.
	 *
	 * @return string
	 */
	private function indent( $text ) {
		if ( '' === $text ) {
			return '';
		}

		return implode(
			"\n",
			array_map(
				function ( $line ) {
					return "\t" . $line;
				},
				explode( "\n", $text )
			)
		);
	}

	/**
	 * Local slug sanitizer (lowercase, alnum + hyphens only). Deliberately
	 * not sanitize_title() — using the real WP function would drop this
	 * class's zero-WP-runtime testability for a marginal fidelity gain.
	 *
	 * @param string $value Preferred/raw slug input.
	 *
	 * @return string
	 */
	private function sanitize_slug( $value ) {
		$value = strtolower( trim( (string) $value ) );
		$value = preg_replace( '/[^a-z0-9]+/', '-', $value );
		$value = trim( $value, '-' );

		return '' !== $value ? $value : self::FALLBACK_SLUG;
	}
}