webui_docs/

build.rs

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

//! Build orchestrator: content pipeline → protocol build → parallel render → output.

use std::collections::HashMap;
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::atomic::AtomicU64;
use std::sync::{Arc, OnceLock};
use std::time::Instant;

use console::style;
use rayon::prelude::*;
use serde_json::{Map, Value};
use webui::BuildOptions;
use webui_handler::{Protocol, RenderOptions, WebUIHandler};
use webui_tokens::TokenFile;

use crate::appearance::{PreparedAppearance, BOOTSTRAP_SCRIPT};
use crate::bundler::{
    bundle_assets, collect_component_scripts_for_html, discover_component_scripts,
    extract_bundle_scripts, inject_module_script_tags, inject_script_tag, module_script_tag,
    page_bundle_signature, resolve_config_component_source, resolve_node_modules, BundleOptions,
    BundleResult, BundleThread, PageBundleEntry, RootBundleEntry, ScriptSource,
};
use crate::content::process_content_with_states;
use crate::error::{Error, Result};
use crate::markdown::Highlighter;
use crate::metadata::document_title;
use crate::regions::RegionSet;
use crate::state::{load_render_states, merge_page_state, StateDependencies};
use crate::types::{BuildStats, DocsConfig, PageDescriptor, ShowMode};

webui_handler::define_string_response_writer!(StringWriter, buf);

fn region_layout(page: &PageDescriptor) -> &str {
    let layout = page.state["page"]["layout"].as_str().unwrap_or("doc");
    if layout == "home" && !page.is_home {
        "doc"
    } else {
        layout
    }
}

fn template_css(template_dir: &Path, show: ShowMode) -> Result<String> {
    if show == ShowMode::Content {
        return Ok(include_str!("../template/docs.css").to_string());
    }
    let mut css = String::new();
    for name in ["docs.css", "shell.css"] {
        let path = template_dir.join(name);
        match fs::read_to_string(&path) {
            Ok(source) => css.push_str(&source),
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
            Err(error) => {
                return Err(Error::Io(format!(
                    "Cannot read {}: {error}",
                    path.display()
                )));
            }
        }
    }
    Ok(css)
}

/// Persistent state held by the dev server across rebuilds. The dev
/// server always performs a full rebuild on every watcher tick — the
/// previous incremental machinery proved too complex for the marginal
/// time savings — so this struct exists solely to amortize startup
/// costs that don't depend on user-edited content.
///
/// Today that's just the syntect `Highlighter` (the syntax + theme
/// load is ~30-50ms). One-shot CLI builds construct a fresh
/// `BuildCache::default()` and discard it.
#[derive(Default)]
pub struct BuildCache {
    /// Syntect highlighter — kept alive across rebuilds so we don't pay
    /// the syntax/theme load cost on every keystroke.
    pub(crate) highlighter: Option<Highlighter>,
    /// Suppress per-step terminal output (`✔ Rendered 31 pages`, etc.).
    /// The dev server flips this on after the first build so subsequent
    /// rebuilds collapse into the rolling rebuild line.
    pub quiet: bool,
    /// Skip the `remove_dir_all(out_dir)` step. Files are overwritten
    /// in place. Dev-mode optimization — saves the macOS-ENOTEMPTY
    /// retry path and shaves disk I/O off every rebuild. Stale files
    /// from deleted source pages survive until the next process restart.
    pub skip_clean: bool,
    /// Dev-mode flag: when true, the bundler skips minification for
    /// faster rebuilds during `webui-press serve`.
    pub dev_mode: bool,
    /// Additional state inputs discovered from Markdown.
    /// Versions describe this build's reads; failed builds retain watch paths.
    pub(crate) dependencies: StateDependencies,
}

impl BuildCache {
    /// Create an empty cache with verbose output and clean-then-build
    /// semantics. Subsequent calls to [`build_docs_with_cache`] will
    /// populate it on first use.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Switch the cache into dev-server rebuild mode: suppresses
    /// per-step output banners and skips wiping the output directory.
    pub fn set_dev_rebuild(&mut self) {
        self.quiet = true;
        self.skip_clean = true;
        self.dev_mode = true;
    }
}

fn inject_theme_tokens(
    state: &mut Value,
    token_file: &TokenFile,
    protocol_tokens: &[String],
) -> Result<()> {
    let resolved = webui_tokens::resolve_tokens(protocol_tokens, token_file)
        .map_err(|e| Error::Build(format!("Failed to resolve theme tokens: {e}")))?;
    webui_tokens::inject_into_state(state, &resolved);
    Ok(())
}

struct NotFoundStateInput<'a> {
    config: &'a DocsConfig,
    base_path: &'a str,
    nav: Value,
    footer: Value,
    content: &'a str,
    head_injection: &'a str,
    global_state: Option<&'a Value>,
}

fn build_not_found_state(input: NotFoundStateInput<'_>) -> Value {
    let state = json_obj([
        (
            "site",
            json_obj([
                ("title", Value::String(input.config.site.title.clone())),
                ("base", Value::String(input.base_path.to_string())),
                (
                    "url",
                    input.config.site.url.as_deref().map_or(Value::Null, |url| {
                        Value::String(url.trim_end_matches('/').to_string())
                    }),
                ),
            ]),
        ),
        ("navigation", input.nav),
        ("sidebar", json_obj([("sections", Value::Array(vec![]))])),
        (
            "page",
            json_obj([
                ("title", Value::String("Page Not Found".to_string())),
                (
                    "documentTitle",
                    Value::String(document_title("Page Not Found", &input.config.site.title)),
                ),
                (
                    "description",
                    Value::String("The page you're looking for doesn't exist.".to_string()),
                ),
                ("content", Value::String(input.content.to_string())),
                (
                    "path",
                    Value::String(format!("{}404.html", input.base_path)),
                ),
                ("canonicalUrl", Value::Null),
                ("headings", Value::Array(Vec::new())),
                ("outline", Value::Bool(false)),
                ("isHome", Value::Bool(false)),
                ("layout", Value::String("doc".to_string())),
            ]),
        ),
        ("hero", Value::Null),
        ("footer", input.footer),
        ("prev", Value::Null),
        ("next", Value::Null),
        ("pageData", Value::Null),
        ("headTags", Value::String(input.head_injection.to_string())),
        ("label", Value::String("Copy".to_string())),
        ("icon", Value::String("🌙".to_string())),
    ]);

    merge_page_state(state, input.global_state, None)
}

// ── Output helpers ──────────────────────────────────────────────
//
// Mirrors the styling vocabulary in `crates/webui-cli/src/utils/output.rs`
// so webui-press feels at home in a workspace where users may also see
// `webui build` / `webui serve` output.

/// Monotonic counter used to produce unique per-rebuild temp-dir names.
/// Combined with the process id and a fxhash of the page path so two
/// rebuilds running in the same process can never collide on the
/// per-page scratch dir.
static REBUILD_NONCE: AtomicU64 = AtomicU64::new(0);

fn print_header(cache: &BuildCache, title: &str) {
    if cache.quiet {
        return;
    }
    eprintln!(
        "\n  {} {}",
        style("⚡").cyan().bold(),
        style(title).cyan().bold()
    );
}

fn print_success(cache: &BuildCache, message: &str) {
    if cache.quiet {
        return;
    }
    eprintln!("  {} {message}", style("✔").green());
}

fn print_bundle_summary(cache: &BuildCache, result: &BundleResult) {
    print_success(
        cache,
        &format!(
            "Bundled {} component script{} into {} root script{} and {} page script group{} in {:.0}ms",
            result.component_count,
            if result.component_count == 1 { "" } else { "s" },
            usize::from(result.root_script.is_some()),
            if result.root_script.is_some() {
                ""
            } else {
                "s"
            },
            result.page_entry_count,
            if result.page_entry_count == 1 {
                ""
            } else {
                "s"
            },
            result.duration.as_secs_f64() * 1000.0
        ),
    );
}

fn print_finish(cache: &BuildCache, message: &str) {
    if cache.quiet {
        return;
    }
    eprintln!("\n  {} {message}\n", style("✨").green());
}

/// Build a JSON object from key-value pairs without using `json!` (which calls `unwrap`).
fn json_obj<const N: usize>(entries: [(&str, Value); N]) -> Value {
    let mut map = Map::with_capacity(N);
    for (k, v) in entries {
        map.insert(k.to_string(), v);
    }
    Value::Object(map)
}

/// Build a documentation site from the given configuration.
///
/// `config_dir` is the directory containing `config.json`. It is used to
/// resolve relative paths declared in the config (such as a custom page's
/// `state_file`).
///
/// One-shot variant for the CLI build command. The dev server uses
/// [`build_docs_with_cache`] so the syntect highlighter survives across
/// rebuilds.
pub fn build_docs(
    config: &DocsConfig,
    config_dir: &Path,
    template_dir: &Path,
) -> Result<BuildStats> {
    let mut cache = BuildCache::new();
    build_docs_with_cache(config, config_dir, template_dir, &mut cache)
}

/// Build a documentation site, reusing the supplied [`BuildCache`] across
/// invocations.
///
/// **Always performs a full rebuild.** The previous incremental machinery
/// (per-page state hashes, component-bundle signatures, descriptor cache,
/// search-index sig, etc.) was removed because the resulting invariants
/// were complex for a dev-server-only optimization. The rebuild is
/// already fast in practice and a from-scratch run keeps the output
/// guaranteed-consistent with the source.
///
/// The cache exists today purely to amortize startup costs that are
/// independent of user-edited content (the syntect highlighter load).
pub fn build_docs_with_cache(
    config: &DocsConfig,
    config_dir: &Path,
    template_dir: &Path,
    cache: &mut BuildCache,
) -> Result<BuildStats> {
    cache.dependencies.begin_build();
    let start = Instant::now();
    let base_path = &config.base_path;
    let out_dir = Path::new(&config.out_dir);

    // Flat output: site files live at the root of `out_dir`. URLs in HTML
    // include `basePath` via `<base href>` and link rewriting; the dev server
    // (`webui-press serve`) maps URL `<basePath>/foo` → file `out_dir/foo`.
    // For deploys (e.g. GitHub Pages project sites), the host mounts `out_dir`
    // at `<basePath>`, so the same flat layout works.
    let site_dir = out_dir.to_path_buf();

    // Per-page and 404 scratch directories follow the output volume so a whole
    // Press build never spans two filesystem roots.
    let scratch_root = crate::scratch::scratch_base(out_dir, config_dir).map_err(|e| {
        Error::Io(format!(
            "Cannot prepare the Press scratch directory for {}: {e}",
            out_dir.display()
        ))
    })?;

    // Read custom CSS
    let custom_css = config
        .css
        .as_ref()
        .and_then(|p| fs::read_to_string(p).ok())
        .unwrap_or_default();
    let mut appearance = PreparedAppearance::prepare(config, config_dir, &mut cache.dependencies)?;
    let appearance_bootstrap = format!("appearance-init-{:x}.js", fxhash(BOOTSTRAP_SCRIPT));

    print_header(cache, &config.site.title);
    eprintln!();

    // Compute the `<head>` injection string up-front, BEFORE any
    // filesystem mutations. Including it here makes it cheap to bake
    // into each page's state inside `process_content` (avoiding a
    // post-process_content mutation pass that would force-clone every
    // cached descriptor) and lets the content cache invalidate when
    // the link tags change. We don't write the CSS files yet — that
    // happens after content processing succeeds, so a content failure
    // can't corrupt the previous valid output.
    let base_css = template_css(template_dir, config.show)?;
    appearance.add_css_validation_context(&base_css)?;
    appearance.add_css_validation_context(&custom_css)?;
    let token_file = appearance.legacy_tokens();
    let has_base_css = !base_css.is_empty();
    let base_css_link = if has_base_css {
        format!("<link rel=\"stylesheet\" href=\"{base_path}docs.css\">")
    } else {
        String::new()
    };
    let has_theme_css = !custom_css.is_empty();
    let theme_css_link = if has_theme_css {
        format!("<link rel=\"stylesheet\" href=\"{base_path}theme.css\">")
    } else {
        String::new()
    };
    let head_injection = {
        let mut parts: Vec<String> = Vec::with_capacity(4 + config.head.len());
        let appearance_head =
            appearance.head_tags(config.show, &format!("{base_path}{appearance_bootstrap}"))?;
        if !appearance_head.is_empty() {
            parts.push(appearance_head);
        }
        if !base_css_link.is_empty() {
            parts.push(base_css_link.clone());
        }
        parts.push(format!(
            "<link rel=\"stylesheet\" href=\"{base_path}appearance.css\">"
        ));
        if !theme_css_link.is_empty() {
            parts.push(theme_css_link.clone());
        }
        for tag in &config.head {
            parts.push(tag.to_html());
        }
        parts.join("\n  ")
    };

    // Step 1: Process content. Highlighter is cached across rebuilds —
    // syntect's default syntax/theme load is ~30-50ms which we don't want
    // to pay every keystroke.
    let render_states = load_render_states(config, config_dir)?;
    let highlighter = cache.highlighter.take().unwrap_or_default();
    let mut dependencies = StateDependencies::default();
    let content = process_content_with_states(
        config,
        &highlighter,
        &head_injection,
        &render_states,
        &mut dependencies,
    );
    if content.is_err() {
        dependencies.paths.append(&mut cache.dependencies.paths);
        dependencies.paths.sort();
        dependencies.paths.dedup();
    } else {
        cache.dependencies.retain_current_paths();
    }
    dependencies.extend(std::mem::take(&mut cache.dependencies));
    cache.dependencies = dependencies;

    // Restore the highlighter for the next rebuild.
    cache.highlighter = Some(highlighter);
    let mut pages = content?;
    let press_state = json_obj([("appearance", appearance.state(config.show))]);
    for page in &mut pages {
        page.state["webuiPress"] = press_state.clone();
    }
    let search_entries = prepare_page_search(&mut pages);

    // Step 2: Resolve component sources for the per-page builds
    let mut component_sources: Vec<String> = Vec::new();
    let cwd = std::env::current_dir().unwrap_or_default();
    // Built-in component library (e.g. crates/webui-press/components/)
    let builtin_components = template_dir.parent().map(|p| p.join("components"));
    if let Some(ref bc) = builtin_components {
        if bc.exists() {
            component_sources.push(bc.to_string_lossy().to_string());
        }
    }
    // User component sources from config. Local paths are resolved against
    // the current project root; npm package names/scopes must stay bare so
    // webui-discovery resolves them from node_modules.
    if let Some(ref user_sources) = config.components {
        for source in user_sources {
            component_sources.push(resolve_config_component_source(source, &cwd));
        }
    }
    // Template-local components (e.g. docs-search, docs-theme-toggle living
    // beside the template's index.html).
    component_sources.push(template_dir.to_string_lossy().to_string());

    let template_html = fs::read_to_string(template_dir.join("index.html"))
        .map_err(|e| Error::Build(format!("Failed to read template: {e}")))?;
    let regions = RegionSet::load(&config.regions, config_dir, template_html)?;
    // Validate configured region names even when the selected presentation
    // makes every shell region inactive. Authored page content is never filtered.
    let mut regions = if config.show == ShowMode::Content {
        RegionSet::load(
            &Default::default(),
            config_dir,
            include_str!("../template/content.html").to_string(),
        )?
    } else {
        regions
    };
    if !appearance.has_multiple_themes() {
        regions.deactivate("header.themePicker");
    }
    crate::outline::prepare(&mut pages, config, regions.contains(crate::outline::REGION))?;
    let component_script_index = discover_component_scripts(&component_sources)?;

    // Step 3: Wipe the previous output and recreate the site root.
    // Always done — a from-scratch run guarantees the output matches
    // the current source with no possibility of stale per-page dirs,
    // stale CSS files, or orphaned assets surviving a config change.
    if out_dir.exists() && !cache.skip_clean {
        remove_dir_all_retry(out_dir)
            .map_err(|e| Error::Io(format!("Cannot clean output dir: {e}")))?;
    }
    fs::create_dir_all(&site_dir).map_err(|e| Error::Io(format!("Cannot create site dir: {e}")))?;

    // Materialize the CSS files referenced by the head injection. Done
    // after content processing succeeds so a content failure can't
    // corrupt the previous valid output (the wipe above still happens
    // because we clean before processing — but that order means a
    // failure leaves no output at all, never half-output).
    if has_base_css {
        fs::write(site_dir.join("docs.css"), &base_css)
            .map_err(|e| Error::Io(format!("Cannot write docs.css: {e}")))?;
    }
    if has_theme_css {
        fs::write(site_dir.join("theme.css"), &custom_css)
            .map_err(|e| Error::Io(format!("Cannot write theme.css: {e}")))?;
    }
    fs::write(site_dir.join("appearance.css"), &appearance.css)
        .map_err(|e| Error::Io(format!("Cannot write appearance.css: {e}")))?;
    if config.show != ShowMode::Content {
        fs::write(site_dir.join(&appearance_bootstrap), BOOTSTRAP_SCRIPT)
            .map_err(|e| Error::Io(format!("Cannot write appearance bootstrap: {e}")))?;
    }

    let handler = WebUIHandler::with_plugin(|| {
        Box::new(webui_handler::plugin::webui::WebUIHydrationPlugin::new())
    });

    // Pre-create per-page output directories sequentially (avoids races and
    // cheap fs::create_dir_all calls competing on the same parent paths).
    for page in &pages {
        let page_dir = site_dir.join(page.path.strip_prefix(base_path).unwrap_or(&page.path));
        fs::create_dir_all(&page_dir)
            .map_err(|e| Error::Io(format!("Cannot create dir {}: {e}", page_dir.display())))?;
    }

    // Step 2b: Extract <script bundle> tags from page content BEFORE
    // rendering. Page scripts become imports in the page's virtual esbuild
    // entry; the source HTML keeps plain, non-bundled scripts untouched.
    //
    // Also collect `scriptFile` entries from customPages config. These
    // produce per-page scripts without polluting the HTML string.
    let mut explicit_page_scripts: HashMap<String, Vec<ScriptSource>> = HashMap::new();
    let mut page_contents_with_scripts: HashMap<String, String> = HashMap::new();

    for page in &pages {
        let content = page.state["page"]["content"].as_str().unwrap_or("");
        if content.contains("<script") && content.contains("bundle") {
            let (modified, scripts) = extract_bundle_scripts(content);
            if !scripts.is_empty() {
                page_contents_with_scripts.insert(page.path.clone(), modified);
                explicit_page_scripts
                    .entry(page.path.clone())
                    .or_default()
                    .extend(scripts);
            }
        }
        let omitted = crate::outline::omitted(config, crate::outline::enabled(&page.state));
        for script_file in regions.script_files(region_layout(page), omitted) {
            explicit_page_scripts
                .entry(page.path.clone())
                .or_default()
                .push(ScriptSource::File(script_file.to_string()));
        }
    }

    // Collect scriptFile from customPages config.
    for (link, custom_page) in &config.custom_pages {
        if let Some(script_path) = custom_page.script_file() {
            // Build the full page path matching how process_content constructs
            // URL paths: base_path + link (minus leading slash).
            let normalized = if link.ends_with('/') {
                link.clone()
            } else {
                format!("{link}/")
            };
            let page_path = format!("{}{}", base_path, &normalized[1..]);
            explicit_page_scripts
                .entry(page_path)
                .or_default()
                .push(ScriptSource::File(script_path.to_string()));
        }
    }

    let not_found_content = format!(
        "<h1>404 — Page Not Found</h1>\
         <p>The page you're looking for doesn't exist or has been moved.</p>\
         <p><a href=\"{base_path}\">← Back to Home</a></p>"
    );

    let template_script_path = template_dir.join("index.ts");
    let template_script = if config.show == ShowMode::All && template_script_path.exists() {
        Some(
            template_script_path
                .canonicalize()
                .unwrap_or(template_script_path),
        )
    } else {
        None
    };
    let template_shell = regions.template_shell();
    let root_component_scripts =
        collect_component_scripts_for_html(&[template_shell.as_str()], &component_script_index)?;
    let root_bundle = if template_script.is_some() || !root_component_scripts.is_empty() {
        Some(RootBundleEntry {
            script_path: template_script,
            component_scripts: root_component_scripts,
        })
    } else {
        None
    };

    // Build virtual entries only for pages with content-specific scripts.
    // Template/chrome scripts are loaded once through the root entry, so pages
    // that only use template components do not get duplicate tiny page-N files.
    let mut page_bundles: Vec<PageBundleEntry> = Vec::new();
    let mut page_bundle_ids: HashMap<String, usize> = HashMap::with_capacity(pages.len());
    let mut page_bundle_signatures: HashMap<String, usize> = HashMap::new();
    for page in &pages {
        let content = page_contents_with_scripts
            .get(&page.path)
            .map(String::as_str)
            .unwrap_or_else(|| page.state["page"]["content"].as_str().unwrap_or(""));
        let omitted = crate::outline::omitted(config, crate::outline::enabled(&page.state));
        let region_fragments = regions.html_fragments(region_layout(page), omitted);
        let mut html_sources = Vec::with_capacity(region_fragments.len() + 1);
        html_sources.push(content);
        html_sources.extend(region_fragments);
        let mut component_scripts =
            collect_component_scripts_for_html(&html_sources, &component_script_index)?;
        if let Some(root) = &root_bundle {
            component_scripts.retain(|path| !root.component_scripts.contains(path));
        }
        let explicit_scripts = explicit_page_scripts.remove(&page.path).unwrap_or_default();
        if component_scripts.is_empty() && explicit_scripts.is_empty() {
            continue;
        }
        let signature = page_bundle_signature(&component_scripts, &explicit_scripts, config_dir);
        if let Some(&id) = page_bundle_signatures.get(&signature) {
            page_bundle_ids.insert(page.path.clone(), id);
            continue;
        }

        let id = page_bundles.len();
        page_bundle_signatures.insert(signature, id);
        page_bundle_ids.insert(page.path.clone(), id);
        page_bundles.push(PageBundleEntry {
            id,
            page_path: page.path.clone(),
            component_scripts,
            explicit_scripts,
        });
    }

    let not_found_omitted = crate::outline::omitted(config, false);
    let not_found_region_fragments = regions.html_fragments("doc", not_found_omitted);
    let mut not_found_sources = Vec::with_capacity(not_found_region_fragments.len() + 1);
    not_found_sources.push(not_found_content.as_str());
    not_found_sources.extend(not_found_region_fragments);
    let mut not_found_component_scripts =
        collect_component_scripts_for_html(&not_found_sources, &component_script_index)?;
    if let Some(root) = &root_bundle {
        not_found_component_scripts.retain(|path| !root.component_scripts.contains(path));
    }
    let not_found_scripts: Vec<ScriptSource> = regions
        .script_files("doc", not_found_omitted)
        .map(|path| ScriptSource::File(path.to_string()))
        .collect();
    let not_found_bundle_id =
        if not_found_component_scripts.is_empty() && not_found_scripts.is_empty() {
            None
        } else {
            let signature =
                page_bundle_signature(&not_found_component_scripts, &not_found_scripts, config_dir);
            if let Some(&id) = page_bundle_signatures.get(&signature) {
                Some(id)
            } else {
                let id = page_bundles.len();
                page_bundle_signatures.insert(signature, id);
                page_bundles.push(PageBundleEntry {
                    id,
                    page_path: format!("{base_path}404/"),
                    component_scripts: not_found_component_scripts,
                    explicit_scripts: not_found_scripts,
                });
                Some(id)
            }
        };

    // Start the one client bundle in parallel with per-page template parsing.
    // Each page blocks only when it reaches projection finalization.
    let node_modules = if root_bundle.is_some() || !page_bundles.is_empty() {
        Some(resolve_node_modules(config_dir)?)
    } else {
        None
    };
    let (projection_source, projection_completer) = webui::projection_manifest_barrier();
    let site_dir_for_bundle = site_dir.clone();
    let root_bundle_for_bundle = root_bundle.clone();
    let page_bundles_for_bundle = page_bundles.clone();
    let bundler_config = config.bundler.clone();
    let config_dir_for_bundle = config_dir.to_path_buf();
    let content_dir_for_bundle = PathBuf::from(&config.content_dir);
    let base_path_for_bundle = base_path.to_string();
    let dev_mode = cache.dev_mode;
    // Published before the projection completer wakes page builds. This keeps
    // parsing overlapped with esbuild while making exact generated URLs
    // available before each protocol is handed to the renderer.
    let generated_preloads = Arc::new(OnceLock::new());
    let generated_preloads_for_bundle = Arc::clone(&generated_preloads);
    let bundle_thread = BundleThread::spawn(move || {
        match bundle_assets(&BundleOptions {
            site_dir: &site_dir_for_bundle,
            base_path: &base_path_for_bundle,
            node_modules: node_modules.as_deref(),
            root_bundle: root_bundle_for_bundle.as_ref(),
            page_bundles: &page_bundles_for_bundle,
            bundler_config: bundler_config.as_ref(),
            dev_mode,
            config_dir: &config_dir_for_bundle,
            content_dir: &content_dir_for_bundle,
        }) {
            Ok(result) => {
                if generated_preloads_for_bundle
                    .set(result.preloads.clone())
                    .is_err()
                {
                    let message = "Generated preload metadata was published twice".to_string();
                    projection_completer.complete(Err(message.clone()));
                    return Err(Error::Build(message));
                }
                projection_completer.complete(Ok(result.projection.clone()));
                Ok(result)
            }
            Err(error) => {
                projection_completer.complete(Err(error.to_string()));
                Err(error)
            }
        }
    });

    // Per-page build + render + write in parallel.
    //
    // Each page is its own complete app: we substitute `{{{page.content}}}`
    // in the template with the page's actual HTML (including any custom
    // elements like <code-block>) and run `webui::build()` on the result.
    // This means the build pipeline naturally discovers the components used
    // on this page, expands their declarative shadow DOM, and emits their
    // template metadata to `window.__webui.templates` for client-side
    // hydration — no manual registration tricks required.
    let total_bytes = std::sync::atomic::AtomicUsize::new(0);
    let component_css: std::sync::Mutex<HashMap<String, String>> =
        std::sync::Mutex::new(HashMap::new());

    let page_start = Instant::now();
    pages.par_iter_mut().try_for_each(|page| -> Result<()> {
        let page_dir = site_dir.join(page.path.strip_prefix(base_path).unwrap_or(&page.path));
        let target = page_dir.join("index.html");

        // Use modified content (with bundled script tags removed) if scripts were extracted.
        let content = page_contents_with_scripts
            .get(&page.path)
            .map(|s| s.as_str())
            .unwrap_or_else(|| page.state["page"]["content"].as_str().unwrap_or(""));

        // Protect markdown code blocks before injecting content into the
        // region-resolved template.
        let (protected, pre_blocks) = protect_pre_blocks(content);
        let omitted = crate::outline::omitted(config, crate::outline::enabled(&page.state));
        let page_html = regions
            .render(region_layout(page), omitted)
            .replace("{{{page.content}}}", &protected);

        // Per-page temp dir holding only this page's index.html — components
        // come exclusively from `component_sources`, which already includes
        // the template dir (for docs-search/docs-theme-toggle) plus any
        // configured component libraries.
        //
        // Name includes pid + per-rebuild nonce so two parallel page
        // builds (and successive rebuilds) can never collide and wipe
        // each other's in-progress files.
        let nonce = REBUILD_NONCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        let page_tmp = scratch_root.join(format!(
            "webui-press-page-{}-{:x}-{nonce:x}",
            std::process::id(),
            fxhash(&page.path),
        ));
        if page_tmp.exists() {
            fs::remove_dir_all(&page_tmp).ok();
        }
        fs::create_dir_all(&page_tmp)
            .map_err(|e| Error::Io(format!("Cannot create page temp: {e}")))?;
        fs::write(page_tmp.join("index.html"), &page_html)
            .map_err(|e| Error::Io(format!("Cannot write page temp: {e}")))?;

        let mut build_result = webui::build(BuildOptions {
            app_dir: page_tmp.clone(),
            entry: "index.html".to_string(),
            plugin: Some(webui::Plugin::WebUI),
            components: component_sources.clone(),
            theme: appearance.validation_tokens(),
            projection_manifests: vec![projection_source.clone()],
            ..BuildOptions::default()
        })
        .map_err(|e| Error::Build(format!("{}: {}", page.path, e.chain_message())))?;
        let preloads = generated_preloads.get().ok_or_else(|| {
            Error::Build("Generated preload metadata was not published".to_string())
        })?;
        let (hrefs, mut preload_warnings) = preloads.resolve(
            &build_result.protocol.module_preloads,
            page_bundle_ids.get(&page.path).copied(),
        );
        build_result.protocol.module_preloads = hrefs;
        build_result.warnings.append(&mut preload_warnings);

        total_bytes.fetch_add(
            build_result.protocol_bytes.len(),
            std::sync::atomic::Ordering::Relaxed,
        );

        // Collect per-component CSS files (Link strategy emits one .css
        // per component used on the page). Multiple pages share components,
        // so we dedupe by filename in a shared map and write once after
        // the parallel pass completes.
        if !build_result.css_files.is_empty() {
            let mut css_map = component_css
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner);
            for (name, content) in build_result.css_files {
                css_map.entry(name).or_insert(content);
            }
        }

        let layout = region_layout(page).to_string();
        regions.apply_state(&layout, &mut page.state, omitted)?;
        if let Some(token_file) = token_file {
            inject_theme_tokens(&mut page.state, token_file, &build_result.protocol.tokens)?;
        }

        let protocol = Protocol::new(build_result.protocol);
        let mut writer = StringWriter::with_capacity(8192);
        handler
            .render(
                &protocol,
                &page.state,
                &RenderOptions::new("index.html", &page.path),
                &mut writer,
            )
            .map_err(|e| Error::Render(format!("{}: {e}", page.path)))?;

        // Restore the protected <pre> blocks via a single-pass scan.
        let html = restore_pre_blocks(&writer.buf, &pre_blocks);

        // Write directly inside the parallel closure.
        fs::write(&target, &html)
            .map_err(|e| Error::Io(format!("Cannot write {}: {e}", page.path)))?;

        fs::remove_dir_all(&page_tmp).ok();
        Ok(())
    })?;

    print_success(
        cache,
        &format!(
            "Rendered {} pages in {:.0}ms",
            pages.len(),
            page_start.elapsed().as_secs_f64() * 1000.0
        ),
    );
    let bundle_result = bundle_thread.join()?;
    print_bundle_summary(cache, &bundle_result);

    // Step 4: Write the index prepared with page heading metadata before render.
    let search_path = site_dir.join("search-index.json");
    fs::write(
        &search_path,
        serde_json::to_string(&search_entries)
            .map_err(|e| Error::Build(format!("JSON error: {e}")))?,
    )
    .map_err(|e| Error::Io(e.to_string()))?;
    print_success(
        cache,
        &format!("Indexed {} pages for search", search_entries.len()),
    );

    // Step 5: Copy static public assets.
    let public_dir = Path::new(&config.public_dir);
    if public_dir.exists() {
        copy_dir(public_dir, &site_dir)?;
    }

    // Step 6: Generate 404 page
    let nav_val = pages
        .first()
        .map(|p| p.state["navigation"].clone())
        .unwrap_or_default();

    let footer_val = config
        .footer
        .as_ref()
        .map(|f| json_obj([("html", Value::String(f.html.clone()))]))
        .unwrap_or(Value::Null);

    let mut not_found_state = build_not_found_state(NotFoundStateInput {
        config,
        base_path,
        nav: nav_val,
        footer: footer_val,
        content: &not_found_content,
        head_injection: &head_injection,
        global_state: render_states.global(),
    });
    not_found_state["webuiPress"] = press_state;
    regions.apply_state("doc", &mut not_found_state, not_found_omitted)?;

    let (protected_not_found, not_found_pre_blocks) = protect_pre_blocks(&not_found_content);
    let not_found_html = regions
        .render("doc", not_found_omitted)
        .replace("{{{page.content}}}", &protected_not_found);
    let nf_tmp = scratch_root.join(format!(
        "webui-press-404-{}-{:x}",
        std::process::id(),
        REBUILD_NONCE.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
    ));
    if nf_tmp.exists() {
        fs::remove_dir_all(&nf_tmp).ok();
    }
    fs::create_dir_all(&nf_tmp).map_err(|e| Error::Io(e.to_string()))?;
    fs::write(nf_tmp.join("index.html"), &not_found_html).map_err(|e| Error::Io(e.to_string()))?;

    let mut nf_build = webui::build(BuildOptions {
        app_dir: nf_tmp.clone(),
        entry: "index.html".to_string(),
        plugin: Some(webui::Plugin::WebUI),
        components: component_sources.clone(),
        theme: appearance.validation_tokens(),
        projection_manifests: vec![projection_source],
        ..BuildOptions::default()
    })
    .map_err(|e| Error::Build(format!("404 build failed: {}", e.chain_message())))?;
    let preloads = generated_preloads
        .get()
        .ok_or_else(|| Error::Build("Generated preload metadata was not published".to_string()))?;
    let (hrefs, mut preload_warnings) =
        preloads.resolve(&nf_build.protocol.module_preloads, not_found_bundle_id);
    nf_build.protocol.module_preloads = hrefs;
    nf_build.warnings.append(&mut preload_warnings);

    if let Some(token_file) = token_file {
        inject_theme_tokens(&mut not_found_state, token_file, &nf_build.protocol.tokens)?;
    }

    // Fold the 404 page's component CSS into the shared map, then write
    // all per-component stylesheets at site root in one pass. The handler
    // emits relative hrefs like `<link rel="stylesheet" href="code-block.css">`;
    // the template's <base href="{site.base}"> resolves them against site root.
    {
        let mut css_map = component_css
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner);
        for (name, content) in &nf_build.css_files {
            css_map
                .entry(name.clone())
                .or_insert_with(|| content.clone());
        }
    }

    let nf_protocol = Protocol::new(nf_build.protocol);
    let mut writer_404 = StringWriter::with_capacity(4096);
    handler
        .render(
            &nf_protocol,
            &not_found_state,
            &RenderOptions::new("index.html", &format!("{base_path}404/")),
            &mut writer_404,
        )
        .map_err(|e| Error::Render(format!("404: {e}")))?;

    let not_found_output = restore_pre_blocks(&writer_404.buf, &not_found_pre_blocks);
    fs::write(site_dir.join("404.html"), not_found_output).map_err(|e| Error::Io(e.to_string()))?;
    fs::remove_dir_all(&nf_tmp).ok();
    print_success(cache, "Generated 404 page");

    // Step 7: Write per-component stylesheets collected during the
    // parallel page builds (and the 404 build above). Sort by name for
    // deterministic output.
    let css_map_local = component_css
        .into_inner()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let mut css_names: Vec<&String> = css_map_local.keys().collect();
    css_names.sort();
    let css_count = css_names.len();
    for name in css_names {
        fs::write(site_dir.join(name), &css_map_local[name])
            .map_err(|e| Error::Io(format!("Cannot write {name}: {e}")))?;
    }
    if css_count > 0 {
        print_success(cache, &format!("Wrote {css_count} component stylesheets"));
    }

    // Step 8: Inject page script <script> tags into rendered pages.
    if bundle_result.root_script.is_some() || !bundle_result.script_map.is_empty() {
        let mut linked_count = 0usize;
        for page in &pages {
            let page_rel_paths = if let Some(bundle_id) = page_bundle_ids.get(&page.path) {
                let rel_paths = bundle_result.script_map.get(bundle_id).ok_or_else(|| {
                    Error::Build(format!(
                        "Missing bundled script for page {} entry {}",
                        page.path, bundle_id
                    ))
                })?;
                if rel_paths.is_empty() {
                    None
                } else {
                    Some(rel_paths)
                }
            } else {
                None
            };
            if bundle_result.root_script.is_none() && page_rel_paths.is_none() {
                continue;
            }
            let page_dir = site_dir.join(page.path.strip_prefix(base_path).unwrap_or(&page.path));
            let target = page_dir.join("index.html");
            let mut html = fs::read_to_string(&target)
                .map_err(|e| Error::Io(format!("Cannot read {}: {e}", target.display())))?;

            if let Some(rel_path) = bundle_result.root_script.as_ref() {
                let tag = module_script_tag(base_path, rel_path);
                inject_script_tag(&mut html, &tag);
                linked_count += 1;
            }
            if let Some(rel_paths) = page_rel_paths {
                linked_count += inject_module_script_tags(&mut html, base_path, rel_paths);
            }

            fs::write(&target, &html)
                .map_err(|e| Error::Io(format!("Cannot rewrite {}: {e}", page.path)))?;
        }
        if let Some(bundle_id) = not_found_bundle_id {
            let rel_paths = bundle_result.script_map.get(&bundle_id).ok_or_else(|| {
                Error::Build(format!(
                    "Missing bundled script for 404 page entry {bundle_id}"
                ))
            })?;
            let target = site_dir.join("404.html");
            let mut html = fs::read_to_string(&target)
                .map_err(|e| Error::Io(format!("Cannot read {}: {e}", target.display())))?;
            if let Some(rel_path) = bundle_result.root_script.as_ref() {
                let tag = module_script_tag(base_path, rel_path);
                inject_script_tag(&mut html, &tag);
                linked_count += 1;
            }
            linked_count += inject_module_script_tags(&mut html, base_path, rel_paths);
            fs::write(&target, &html)
                .map_err(|e| Error::Io(format!("Cannot rewrite 404.html: {e}")))?;
        } else if let Some(rel_path) = bundle_result.root_script.as_ref() {
            let target = site_dir.join("404.html");
            let mut html = fs::read_to_string(&target)
                .map_err(|e| Error::Io(format!("Cannot read {}: {e}", target.display())))?;
            let tag = module_script_tag(base_path, rel_path);
            inject_script_tag(&mut html, &tag);
            fs::write(&target, &html)
                .map_err(|e| Error::Io(format!("Cannot rewrite 404.html: {e}")))?;
            linked_count += 1;
        }
        if linked_count > 0 {
            print_success(
                cache,
                &format!(
                    "Linked {} script tag{}",
                    linked_count,
                    if linked_count == 1 { "" } else { "s" }
                ),
            );
        }
    }

    let elapsed = start.elapsed();
    let total_bytes = total_bytes.load(std::sync::atomic::Ordering::Relaxed);
    print_finish(cache, &format!("Built in {:.1}s", elapsed.as_secs_f64()));

    Ok(BuildStats {
        pages: pages.len(),
        protocol_bytes: total_bytes,
    })
}

/// Recursively remove a directory, retrying briefly on `ENOTEMPTY`.
///
/// On macOS (and occasionally Linux), `fs::remove_dir_all` can fail
/// with `Directory not empty` when something writes a file into a
/// subdirectory between the moment we walked it and the moment we try
/// to `rmdir` it. Likely culprits during a dev-server rebuild:
///
///  - Spotlight / `mds` writing index hints,
///  - Finder dropping a `.DS_Store`,
///  - the user's editor reindexing the project,
///  - a back-to-back save firing another rebuild before the first one
///    finished cleanup (the worker coalesces, but a stray write into
///    `out_dir` from a parallel `cargo` or another tool is still
///    possible).
///
/// We retry up to a handful of times with short backoff. After that the
/// error propagates so the user sees a real failure rather than an
/// infinite loop.
fn remove_dir_all_retry(path: &Path) -> std::io::Result<()> {
    const MAX_ATTEMPTS: u32 = 5;
    let mut delay = std::time::Duration::from_millis(20);
    for attempt in 1..=MAX_ATTEMPTS {
        match fs::remove_dir_all(path) {
            Ok(()) => return Ok(()),
            Err(e) if attempt < MAX_ATTEMPTS && is_dir_not_empty(&e) => {
                std::thread::sleep(delay);
                delay = delay.saturating_mul(2);
            }
            Err(e) => return Err(e),
        }
    }
    // Loop guarantees a return on each iteration; this is unreachable
    // but `for` returning `()` makes the type-checker happy without it.
    Ok(())
}

/// Returns true if the error is `ENOTEMPTY` / `EEXIST` style "directory
/// not empty". On macOS this is errno 66; on Linux it's 39. We also
/// match by `ErrorKind` once Rust exposes one (currently `Other`).
fn is_dir_not_empty(e: &std::io::Error) -> bool {
    match e.raw_os_error() {
        Some(66) => true,  // macOS / BSD: ENOTEMPTY
        Some(39) => true,  // Linux: ENOTEMPTY
        Some(145) => true, // Windows: ERROR_DIR_NOT_EMPTY
        _ => false,
    }
}

/// Iteratively copy a directory tree (BFS via stack — no recursion).
fn copy_dir(src: &Path, dest: &Path) -> Result<()> {
    if !src.exists() {
        return Ok(());
    }
    fs::create_dir_all(dest).map_err(|e| Error::Io(e.to_string()))?;
    let mut stack: Vec<(std::path::PathBuf, std::path::PathBuf)> =
        vec![(src.to_path_buf(), dest.to_path_buf())];
    while let Some((s, d)) = stack.pop() {
        for entry in fs::read_dir(&s).map_err(|e| Error::Io(e.to_string()))? {
            let entry = entry.map_err(|e| Error::Io(e.to_string()))?;
            let dest_path = d.join(entry.file_name());
            let ft = entry.file_type().map_err(|e| Error::Io(e.to_string()))?;
            if ft.is_dir() {
                fs::create_dir_all(&dest_path).map_err(|e| Error::Io(e.to_string()))?;
                stack.push((entry.path(), dest_path));
            } else {
                fs::copy(entry.path(), &dest_path).map_err(|e| Error::Io(e.to_string()))?;
            }
        }
    }
    Ok(())
}

/// Truncate a string to at most `max` bytes at a valid UTF-8 boundary.
pub(crate) fn truncate_utf8(s: &str, max: usize) -> &str {
    if s.len() <= max {
        return s;
    }
    let mut end = max;
    while end > 0 && !s.is_char_boundary(end) {
        end -= 1;
    }
    &s[..end]
}

#[derive(Default)]
struct SearchText {
    content: String,
    headings: Vec<SearchHeading>,
}

/// Heading metadata emitted into `search-index.json`.
///
/// The client search UI uses this to create separate, anchor-linked rows for
/// matching sections (`Page > Heading`) without re-parsing page HTML at runtime.
struct SearchHeading {
    text: String,
    anchor: String,
    level: u8,
}

/// Mutable heading capture state while scanning rendered HTML.
struct CurrentHeading {
    text: String,
    anchor: String,
    level: u8,
}

struct HtmlTag<'a> {
    name: &'a str,
    is_end: bool,
}

fn prepare_page_search(pages: &mut [PageDescriptor]) -> Vec<Value> {
    let mut entries = Vec::with_capacity(pages.len());
    for page in pages {
        let html = page.state["page"]["content"].as_str().unwrap_or("");
        let title = page.state["page"]["title"].as_str().unwrap_or("");
        let entry = build_search_entry(title, &page.path, html);
        // Reuse the search scan and the Markdown renderer's actual IDs. Raw
        // custom-page headings without IDs are searchable but not TOC targets.
        let headings = entry["headings"]
            .as_array()
            .map(|headings| {
                let mut anchored = Vec::with_capacity(headings.len());
                for heading in headings {
                    if heading["anchor"].as_str().is_some_and(|id| !id.is_empty()) {
                        anchored.push(heading.clone());
                    }
                }
                anchored
            })
            .unwrap_or_default();
        page.state["page"]["headings"] = Value::Array(headings);
        if !page.is_home {
            entries.push(entry);
        }
    }
    entries
}

/// Build a single search-index entry for a page. Strips HTML tags,
/// decodes escaped text, captures headings for weighted ranking,
/// collapses whitespace, and truncates body content to 500 bytes.
pub(crate) fn build_search_entry(title: &str, path: &str, html: &str) -> Value {
    let search_text = extract_search_text(html);
    let content = normalize_search_text(&search_text.content);
    let truncated = truncate_utf8(&content, 500);
    let headings: Vec<Value> = search_text
        .headings
        .into_iter()
        .map(|heading| {
            json_obj([
                ("text", Value::String(heading.text)),
                ("anchor", Value::String(heading.anchor)),
                (
                    "level",
                    Value::Number(serde_json::Number::from(u64::from(heading.level))),
                ),
            ])
        })
        .collect();
    json_obj([
        ("title", Value::String(title.to_string())),
        ("path", Value::String(path.to_string())),
        ("content", Value::String(truncated.to_string())),
        ("headings", Value::Array(headings)),
    ])
}

fn extract_search_text(html: &str) -> SearchText {
    let mut text = SearchText {
        content: String::with_capacity(html.len() / 2),
        headings: Vec::with_capacity(8),
    };
    let mut current_heading: Option<CurrentHeading> = None;
    let mut skip_header_anchor = 0usize;
    let mut cursor = 0;

    while cursor < html.len() {
        let remaining = &html[cursor..];
        let Some(tag_offset) = remaining.find('<') else {
            push_search_text(
                &mut text,
                current_heading.as_mut(),
                skip_header_anchor,
                remaining,
            );
            break;
        };
        let text_end = cursor + tag_offset;
        push_search_text(
            &mut text,
            current_heading.as_mut(),
            skip_header_anchor,
            &html[cursor..text_end],
        );
        let tag_start = text_end + 1;
        let Some(tag_len) = html[tag_start..].find('>') else {
            push_search_text(
                &mut text,
                current_heading.as_mut(),
                skip_header_anchor,
                &html[text_end..],
            );
            break;
        };
        let tag_end = tag_start + tag_len;
        handle_search_tag(
            &html[tag_start..tag_end],
            &mut text,
            &mut current_heading,
            &mut skip_header_anchor,
        );
        cursor = tag_end + 1;
    }

    text
}

fn handle_search_tag(
    raw_tag: &str,
    text: &mut SearchText,
    current_heading: &mut Option<CurrentHeading>,
    skip_header_anchor: &mut usize,
) {
    if let Some(tag) = parse_html_tag(raw_tag) {
        if tag.is_end {
            handle_end_tag(tag.name, text, current_heading, skip_header_anchor);
        } else {
            handle_start_tag(tag.name, raw_tag, current_heading, skip_header_anchor);
        }
    }
    push_search_space(text, current_heading.as_mut(), *skip_header_anchor);
}

fn handle_start_tag(
    name: &str,
    raw_tag: &str,
    current_heading: &mut Option<CurrentHeading>,
    skip_header_anchor: &mut usize,
) {
    if let Some(level) = heading_level(name) {
        *current_heading = Some(CurrentHeading {
            text: String::with_capacity(64),
            anchor: html_escape::decode_html_entities(attr_value(raw_tag, "id").unwrap_or(""))
                .into_owned(),
            level,
        });
    } else if name.eq_ignore_ascii_case("a") && raw_tag.contains("header-anchor") {
        *skip_header_anchor += 1;
    }
}

fn handle_end_tag(
    name: &str,
    text: &mut SearchText,
    current_heading: &mut Option<CurrentHeading>,
    skip_header_anchor: &mut usize,
) {
    if name.eq_ignore_ascii_case("a") && *skip_header_anchor > 0 {
        *skip_header_anchor -= 1;
    }
    if heading_level(name).is_some() {
        if let Some(raw_heading) = current_heading.take() {
            let heading_text = normalize_search_text(&raw_heading.text);
            if !heading_text.is_empty() {
                text.headings.push(SearchHeading {
                    text: heading_text,
                    anchor: raw_heading.anchor,
                    level: raw_heading.level,
                });
            }
        }
    }
}

fn parse_html_tag(raw: &str) -> Option<HtmlTag<'_>> {
    let mut tag = raw.trim_start();
    if tag.starts_with('!') || tag.starts_with('?') {
        return None;
    }
    let is_end = tag.starts_with('/');
    if is_end {
        tag = tag[1..].trim_start();
    }

    let mut name_end = 0;
    for (idx, byte) in tag.bytes().enumerate() {
        if byte.is_ascii_alphanumeric() || byte == b'-' {
            name_end = idx + 1;
        } else {
            break;
        }
    }
    if name_end == 0 {
        return None;
    }
    Some(HtmlTag {
        name: &tag[..name_end],
        is_end,
    })
}

/// Return a heading level for `h1` through `h6`.
///
/// The scanner works on tag names from already-rendered markdown, so an ASCII
/// byte check is sufficient and avoids allocating a lowercased copy.
fn heading_level(name: &str) -> Option<u8> {
    let bytes = name.as_bytes();
    if bytes.len() == 2 && bytes[0].eq_ignore_ascii_case(&b'h') && (b'1'..=b'6').contains(&bytes[1])
    {
        Some(bytes[1] - b'0')
    } else {
        None
    }
}

/// Extract an HTML attribute value from a rendered start tag without a DOM
/// parser.
///
/// Search indexing runs once per page at build time, but it still avoids regex
/// and allocation-heavy parsing. This helper handles quoted and unquoted values
/// because heading IDs are generated as ordinary HTML attributes.
fn attr_value<'a>(raw_tag: &'a str, attr_name: &str) -> Option<&'a str> {
    let bytes = raw_tag.as_bytes();
    let mut cursor = 0;

    while cursor < bytes.len() {
        while bytes.get(cursor).is_some_and(u8::is_ascii_whitespace) {
            cursor += 1;
        }

        let name_start = cursor;
        while bytes.get(cursor).is_some_and(|b| is_attr_name_byte(*b)) {
            cursor += 1;
        }
        if name_start == cursor {
            cursor += 1;
            continue;
        }
        let name = &raw_tag[name_start..cursor];

        while bytes.get(cursor).is_some_and(u8::is_ascii_whitespace) {
            cursor += 1;
        }
        if bytes.get(cursor) != Some(&b'=') {
            continue;
        }
        cursor += 1;
        while bytes.get(cursor).is_some_and(u8::is_ascii_whitespace) {
            cursor += 1;
        }

        let (value_start, value_end) = attr_value_range(raw_tag, cursor);
        if name.eq_ignore_ascii_case(attr_name) {
            return Some(&raw_tag[value_start..value_end]);
        }
        cursor = value_end.saturating_add(1);
    }

    None
}

fn is_attr_name_byte(byte: u8) -> bool {
    byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b':')
}

fn attr_value_range(raw_tag: &str, cursor: usize) -> (usize, usize) {
    let bytes = raw_tag.as_bytes();
    match bytes.get(cursor).copied() {
        Some(b'"' | b'\'') => {
            let quote = bytes[cursor];
            let value_start = cursor + 1;
            let value_end = raw_tag[value_start..]
                .find(char::from(quote))
                .map_or(raw_tag.len(), |offset| value_start + offset);
            (value_start, value_end)
        }
        Some(_) => {
            let value_start = cursor;
            let value_end = raw_tag[value_start..]
                .find(char::is_whitespace)
                .map_or(raw_tag.len(), |offset| value_start + offset);
            (value_start, value_end)
        }
        None => (raw_tag.len(), raw_tag.len()),
    }
}

fn push_search_text(
    text: &mut SearchText,
    current_heading: Option<&mut CurrentHeading>,
    skip_header_anchor: usize,
    value: &str,
) {
    if skip_header_anchor > 0 {
        return;
    }
    text.content.push_str(value);
    if let Some(heading) = current_heading {
        heading.text.push_str(value);
    }
}

fn push_search_space(
    text: &mut SearchText,
    current_heading: Option<&mut CurrentHeading>,
    skip_header_anchor: usize,
) {
    if skip_header_anchor > 0 {
        return;
    }
    text.content.push(' ');
    if let Some(heading) = current_heading {
        heading.text.push(' ');
    }
}

fn normalize_search_text(raw: &str) -> String {
    let decoded = html_escape::decode_html_entities(raw);
    let mut normalized = String::with_capacity(decoded.len());
    let mut first = true;
    for token in decoded.split_whitespace() {
        if !first {
            normalized.push(' ');
        }
        normalized.push_str(token);
        first = false;
    }
    normalized
}

const PRE_BLOCK_MARKER_PREFIX: &str = "<span data-webui-press-pre-block=\"";
const PRE_BLOCK_MARKER_SUFFIX: &str = "\"></span>";

/// Replace `<pre …>…</pre>` blocks with placeholder elements so the WebUI
/// HTML parser does not normalize whitespace inside them. Returns the
/// modified string and the original blocks (in order) for restoration
/// after rendering.
fn protect_pre_blocks(content: &str) -> (String, Vec<String>) {
    use std::fmt::Write as _;
    let mut blocks: Vec<String> = Vec::new();
    let mut out = String::with_capacity(content.len());
    let mut cursor = 0;
    while let Some(rel_start) = find_pre_open(&content[cursor..]) {
        let start = cursor + rel_start;
        if let Some(rel_end) = content[start..].find("</pre>") {
            let end = start + rel_end + "</pre>".len();
            out.push_str(&content[cursor..start]);
            out.push_str(PRE_BLOCK_MARKER_PREFIX);
            // write! into existing buffer — avoids `format!` allocation per block.
            let _ = write!(&mut out, "{}", blocks.len());
            out.push_str(PRE_BLOCK_MARKER_SUFFIX);
            blocks.push(content[start..end].to_string());
            cursor = end;
        } else {
            break;
        }
    }
    out.push_str(&content[cursor..]);
    (out, blocks)
}

/// Find the next opening `<pre` tag where the next byte is one of `>`, ` `,
/// `\t`, `\n`, or `\r`. Avoids matching `<presentation`, `<pretend`, etc.
fn find_pre_open(s: &str) -> Option<usize> {
    let bytes = s.as_bytes();
    let mut i = 0;
    while let Some(rel) = s[i..].find("<pre") {
        let pos = i + rel;
        let after = pos + 4;
        match bytes.get(after) {
            Some(b'>' | b' ' | b'\t' | b'\n' | b'\r') => return Some(pos),
            _ => i = after,
        }
    }
    None
}

/// Single-pass restoration of pre-block placeholder elements to their
/// original content. Faster than calling `String::replace` once per block.
fn restore_pre_blocks(html: &str, blocks: &[String]) -> String {
    if blocks.is_empty() {
        return html.to_string();
    }
    let extra: usize = blocks.iter().map(|b| b.len()).sum();
    let mut out = String::with_capacity(html.len() + extra);
    let mut cursor = 0;
    while let Some(rel) = html[cursor..].find(PRE_BLOCK_MARKER_PREFIX) {
        let p = cursor + rel;
        out.push_str(&html[cursor..p]);
        let after = p + PRE_BLOCK_MARKER_PREFIX.len();
        if let Some(end_rel) = html[after..].find(PRE_BLOCK_MARKER_SUFFIX) {
            let num_str = &html[after..after + end_rel];
            if let Ok(idx) = num_str.parse::<usize>() {
                if let Some(block) = blocks.get(idx) {
                    out.push_str(block);
                    cursor = after + end_rel + PRE_BLOCK_MARKER_SUFFIX.len();
                    continue;
                }
            }
            // Unknown placeholder — keep verbatim.
            out.push_str(&html[p..after + end_rel + PRE_BLOCK_MARKER_SUFFIX.len()]);
            cursor = after + end_rel + PRE_BLOCK_MARKER_SUFFIX.len();
        } else {
            out.push_str(&html[p..]);
            return out;
        }
    }
    out.push_str(&html[cursor..]);
    out
}

/// Cheap deterministic hash for build-time artifact and temporary-file identities.
fn fxhash(s: &str) -> u64 {
    fxhash_bytes(s.as_bytes())
}

fn fxhash_bytes(bytes: &[u8]) -> u64 {
    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
    for &b in bytes {
        hash ^= u64::from(b);
        hash = hash.wrapping_mul(0x100_0000_01b3);
    }
    hash
}

#[cfg(test)]
mod tests {
    use super::*;

    type TestResult<T = ()> = std::result::Result<T, Box<dyn std::error::Error>>;

    #[test]
    fn early_build_failure_does_not_recheck_versions_from_a_previous_build() -> TestResult {
        let root = tempfile::tempdir()?;
        let file = root.path().join("state.json");
        fs::write(&file, r#"{"count":1}"#)?;
        let mut loader = crate::state::StateLoader::new();
        loader.load_markdown_state(Some("state.json"), None, &root.path().join("page.md"))?;
        let mut cache = BuildCache {
            dependencies: loader.into_dependencies(),
            ..BuildCache::default()
        };
        fs::write(&file, r#"{"count":2}"#)?;
        assert_eq!(cache.dependencies.changed_paths(), cache.dependencies.paths);
        let mut config = docs_config()?;
        config.state = Some(Value::Null);
        config.out_dir = root.path().join("output").to_string_lossy().into_owned();
        assert!(build_docs_with_cache(&config, root.path(), root.path(), &mut cache).is_err());
        assert!(cache.dependencies.changed_paths().is_empty());
        assert_eq!(cache.dependencies.paths, vec![fs::canonicalize(file)?]);
        Ok(())
    }

    fn test_obj<const N: usize>(entries: [(&str, Value); N]) -> Value {
        let mut map = Map::with_capacity(N);
        for (key, value) in entries {
            map.insert(key.to_string(), value);
        }
        Value::Object(map)
    }

    fn string_value(value: &str) -> Value {
        Value::String(value.to_string())
    }

    fn docs_config() -> TestResult<DocsConfig> {
        let config = serde_json::from_str(
            r#"{
                "site": { "title": "Docs" },
                "basePath": "/",
                "contentDir": ".",
                "nav": [],
                "sidebar": []
            }"#,
        )?;
        Ok(config)
    }

    #[test]
    fn not_found_state_includes_global_state() -> TestResult {
        let config = docs_config()?;
        let global = test_obj([("release", test_obj([("version", string_value("v1.2.3"))]))]);

        let state = build_not_found_state(NotFoundStateInput {
            config: &config,
            base_path: "/",
            nav: Value::Array(vec![]),
            footer: Value::Null,
            content: "<h1>404</h1>",
            head_injection: "<meta name=\"docs\">",
            global_state: Some(&global),
        });

        assert_eq!(state["release"]["version"], "v1.2.3");
        assert_eq!(state["page"]["title"], "Page Not Found");
        assert_eq!(state["page"]["documentTitle"], "Page Not Found | Docs");
        assert_eq!(state["page"]["path"], "/404.html");
        assert_eq!(state["page"]["canonicalUrl"], Value::Null);
        assert_eq!(state["page"]["headings"], Value::Array(Vec::new()));
        assert_eq!(state["pageData"], Value::Null);
        assert_eq!(state["headTags"], "<meta name=\"docs\">");
        Ok(())
    }

    #[test]
    fn custom_home_layout_uses_non_home_regions() {
        let state = test_obj([("page", test_obj([("layout", string_value("home"))]))]);
        let custom_page = PageDescriptor {
            path: "/custom/".to_string(),
            is_home: false,
            state: state.clone(),
        };
        let home_page = PageDescriptor {
            path: "/".to_string(),
            is_home: true,
            state,
        };

        assert_eq!(region_layout(&custom_page), "doc");
        assert_eq!(region_layout(&home_page), "home");
    }

    // --- truncate_utf8 ---------------------------------------------------

    #[test]
    fn truncate_utf8_short_string_unchanged() {
        assert_eq!(truncate_utf8("hello", 100), "hello");
    }

    #[test]
    fn truncate_utf8_ascii_at_exact_boundary() {
        assert_eq!(truncate_utf8("hello world", 5), "hello");
    }

    #[test]
    fn truncate_utf8_steps_back_off_multibyte_boundary() {
        // "é" is two bytes (0xC3 0xA9). Cutting at 1 byte must step back to 0.
        let s = "é-suffix";
        let out = truncate_utf8(s, 1);
        assert!(s.is_char_boundary(out.len()), "out.len()={}", out.len());
        assert_eq!(out, "");
    }

    #[test]
    fn truncate_utf8_keeps_multibyte_when_room_allows() {
        let s = "café";
        let out = truncate_utf8(s, 5); // "café" is 5 bytes total
        assert_eq!(out, "café");
    }

    // --- protect_pre_blocks / find_pre_open ------------------------------

    #[test]
    fn protect_pre_blocks_with_attrs() {
        let input = r#"<p>before</p><pre class="hljs">code</pre><p>after</p>"#;
        let (out, blocks) = protect_pre_blocks(input);
        assert_eq!(blocks.len(), 1);
        assert!(out.contains(r#"<span data-webui-press-pre-block="0"></span>"#));
        assert!(!out.contains("<pre"));
        assert_eq!(blocks[0], r#"<pre class="hljs">code</pre>"#);
    }

    #[test]
    fn protect_pre_blocks_bare_open_tag() {
        // Was previously missed because we only matched "<pre " (with space).
        let input = "<pre>code</pre>";
        let (out, blocks) = protect_pre_blocks(input);
        assert_eq!(blocks.len(), 1, "got out={out:?} blocks={blocks:?}");
        assert_eq!(blocks[0], "<pre>code</pre>");
    }

    #[test]
    fn protect_pre_blocks_does_not_match_presentation_tag() {
        // <presentation> must NOT be treated as a pre block.
        let input = "<presentation>x</presentation>";
        let (_out, blocks) = protect_pre_blocks(input);
        assert_eq!(blocks.len(), 0);
    }

    #[test]
    fn protect_then_restore_round_trip() {
        let input = "before <pre>a</pre> mid <pre class=\"x\">b</pre> end";
        let (protected, blocks) = protect_pre_blocks(input);
        let restored = restore_pre_blocks(&protected, &blocks);
        assert_eq!(restored, input);
    }

    #[test]
    fn restore_pre_blocks_no_blocks_returns_input() {
        assert_eq!(restore_pre_blocks("plain html", &[]), "plain html");
    }

    #[test]
    fn pre_block_placeholder_survives_webui_component_slot_render() -> TestResult {
        let input = "<code-block><pre><code>let x = 1;\n</code></pre></code-block>";
        let (protected, blocks) = protect_pre_blocks(input);
        let page_html = format!("<!DOCTYPE html><html><body>{protected}</body></html>");

        let tmp = std::env::temp_dir().join(format!(
            "webui-press-slot-test-{}-{:x}",
            std::process::id(),
            fxhash(input)
        ));
        if tmp.exists() {
            fs::remove_dir_all(&tmp)?;
        }
        fs::create_dir_all(&tmp)?;
        fs::write(tmp.join("index.html"), page_html)?;

        let components = vec![Path::new(env!("CARGO_MANIFEST_DIR"))
            .join("components")
            .to_string_lossy()
            .into_owned()];
        let build_result = webui::build(BuildOptions {
            app_dir: tmp.clone(),
            entry: "index.html".to_string(),
            plugin: Some(webui::Plugin::WebUI),
            components,
            ..BuildOptions::default()
        })?;

        let mut writer = StringWriter::with_capacity(4096);
        let handler = WebUIHandler::with_plugin(|| {
            Box::new(webui_handler::plugin::webui::WebUIHydrationPlugin::new())
        });
        let protocol = Protocol::new(build_result.protocol);
        handler.render(
            &protocol,
            &Value::Object(Map::new()),
            &RenderOptions::new("index.html", "/"),
            &mut writer,
        )?;

        fs::remove_dir_all(&tmp)?;

        let html = restore_pre_blocks(&writer.buf, &blocks);
        assert!(
            html.contains("<pre><code>let x = 1;\n</code></pre>"),
            "slotted pre block should be restored after WebUI render: {html}"
        );
        assert!(
            !html.contains(PRE_BLOCK_MARKER_PREFIX),
            "placeholder marker must not survive output: {html}"
        );

        Ok(())
    }

    #[test]
    fn build_search_entry_decodes_code_text_and_captures_headings() {
        let entry = build_search_entry(
            "`<for>` Loop Directive",
            "/guide/concepts/directives/for/",
            r##"<h1 id="for"><code>&lt;for&gt;</code> Loop Directive <a class="header-anchor" href="#for">#</a></h1><p>Use <code>&lt;for&gt;</code> loops.</p><h2 id="syntax">Syntax <a class="header-anchor" href="#syntax">#</a></h2><h3 id="nested">Nested Search <a class="header-anchor" href="#nested">#</a></h3>"##,
        );

        assert_eq!(entry["title"].as_str(), Some("`<for>` Loop Directive"));
        assert_eq!(
            entry["content"].as_str(),
            Some("<for> Loop Directive Use <for> loops. Syntax Nested Search")
        );
        let Some(headings) = entry["headings"].as_array() else {
            panic!("headings should be an array: {entry:?}");
        };
        assert_eq!(headings.len(), 3);
        assert_eq!(headings[0]["text"].as_str(), Some("<for> Loop Directive"));
        assert_eq!(headings[0]["anchor"].as_str(), Some("for"));
        assert_eq!(headings[0]["level"].as_u64(), Some(1));
        assert_eq!(headings[1]["text"].as_str(), Some("Syntax"));
        assert_eq!(headings[1]["anchor"].as_str(), Some("syntax"));
        assert_eq!(headings[1]["level"].as_u64(), Some(2));
        assert_eq!(headings[2]["text"].as_str(), Some("Nested Search"));
        assert_eq!(headings[2]["anchor"].as_str(), Some("nested"));
        assert_eq!(headings[2]["level"].as_u64(), Some(3));
    }

    #[test]
    fn page_headings_reuse_search_text_and_existing_anchors() {
        let mut pages = vec![PageDescriptor {
            path: "/nested/docs/guide".to_string(),
            is_home: false,
            state: test_obj([(
                "page",
                test_obj([
                    ("title", string_value("Guide")),
                    (
                        "content",
                        string_value(concat!(
                            "<h1 id=\"guide\">Guide</h1>",
                            "<h2 id=\"syntax\"><code>&lt;for&gt;</code> &amp; Syntax",
                            "<a class=\"header-anchor\" href=\"#syntax\">#</a></h2>",
                            "<h3>Unanchored custom heading</h3>",
                            "<h6 id=\"details&amp;more\">Details</h6>"
                        )),
                    ),
                ]),
            )]),
        }];
        let entries = prepare_page_search(&mut pages);
        let headings = pages[0].state["page"]["headings"].clone();
        assert_eq!(headings[0], entries[0]["headings"][0]);
        assert_eq!(headings[1], entries[0]["headings"][1]);
        assert_eq!(headings[1]["text"], "<for> & Syntax");
        assert_eq!(headings[1]["anchor"], "syntax");
        assert_eq!(headings[1]["level"], 2);
        assert_eq!(headings[2]["level"], 6);
        assert_eq!(headings[2]["anchor"], "details&more");
        assert_eq!(headings.as_array().map(Vec::len), Some(3));
        assert_eq!(entries[0]["headings"].as_array().map(Vec::len), Some(4));

        pages[0].is_home = true;
        assert!(prepare_page_search(&mut pages).is_empty());
        assert_eq!(pages[0].state["page"]["headings"], headings);
    }

    // --- fxhash ----------------------------------------------------------

    #[test]
    fn fxhash_deterministic() {
        assert_eq!(fxhash("abc"), fxhash("abc"));
        assert_ne!(fxhash("abc"), fxhash("abd"));
    }
}