@ape-egg/vibe-compiler 3.0.0

package/src/compiler/compile.rs

@@ -0,0 +1,2985 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::time::Instant;
+use std::collections::{BTreeMap, HashSet, HashMap};
+use thiserror::Error;
+use colored::Colorize;
+use regex::Regex;
+use glob::Pattern;
+use rayon::prelude::*;
+use serde_json::{Map, Value};
+
+use crate::config::Config;
+use crate::parser::HtmlParser;
+
+/// Map an output-relative HTML path to the URL path the runtime resolves a
+/// manifest from. Strips the `root` dir (served at /) and collapses dynamic
+/// `$param` segments to a `$` token, e.g. with root `pages`:
+///   pages/armory.html        -> armory.html
+///   pages/the-arena/$id.html -> the-arena/$.html
+fn manifest_url_path(relative_path: &str, root: Option<&str>) -> String {
+    let stripped = match root {
+        Some(r) if relative_path == r => "",
+        Some(r) if relative_path.starts_with(&format!("{}/", r)) => &relative_path[r.len() + 1..],
+        _ => relative_path,
+    };
+
+    stripped
+        .split('/')
+        .map(|seg| match seg.strip_prefix('$') {
+            // $id.html -> $.html ; $id -> $
+            Some(rest) => match rest.find('.') {
+                Some(dot) => format!("${}", &rest[dot..]),
+                None => "$".to_string(),
+            },
+            None => seg.to_string(),
+        })
+        .collect::<Vec<_>>()
+        .join("/")
+}
+
+/// Write via a same-directory temp file + rename, so no reader — the dev
+/// server, the browser, another compiler process — can ever observe a
+/// partially-written file. Rename is atomic on POSIX; the temp name carries the
+/// pid so two processes writing the same target never share a temp file.
+pub(crate) fn atomic_write(path: &Path, contents: &str) -> std::io::Result<()> {
+    let file_name = path.file_name().and_then(|n| n.to_str()).unwrap_or("out");
+    let tmp = path.with_file_name(format!(".{}.{}.vibe-tmp", file_name, std::process::id()));
+    fs::write(&tmp, contents)?;
+    fs::rename(&tmp, path)
+}
+
+// =============================================================================
+// MIRROR_MODE: Copy asset files from source to output as-is, preserving
+// directory structure. HTML files are compiled separately.
+//
+// Asset whitelist approach: Common web asset extensions automatically copied.
+// Future refactoring: Replace with configurable include/exclude patterns,
+// or a more sophisticated asset pipeline.
+// =============================================================================
+// FOUC prevention class/attribute name (matches runtime/constants.js)
+// Can be used as class (.vibe-fouc) or attribute ([vibe-fouc])
+const FOUC_CLASS_OR_ATTR: &str = "vibe-fouc";
+
+const MIRROR_EXTENSIONS: &[&str] = &[
+    "css", "js",
+    // Fonts
+    "ttf", "otf", "woff", "woff2", "eot",
+    // Images
+    "png", "jpg", "jpeg", "gif", "svg", "webp", "avif", "ico",
+    // Media
+    "mp4", "webm", "ogg", "mp3", "wav", "flac", "aac",
+    // Documents
+    "pdf",
+    // Data
+    "json", "xml", "csv",
+];
+
+// Built-in files and directories to skip when walking source (supports glob
+// patterns). User-supplied `skipFiles` are appended to these in Config::load,
+// so the effective list lives on `config.skip_files` and is passed into
+// should_skip_path() at every call site.
+// Note: Output directory is checked dynamically (not hardcoded here)
+// Note: Dotfiles are handled by starts_with('.') check in should_skip_path()
+pub const SKIP_FILES: &[&str] = &[
+    "target",            // Rust build artifacts
+    "tests",             // Test files
+    "test-results",
+    "playwright-report",
+    "node_modules",      // Skip node_modules during scanning
+    "**/*.test.js",      // Test files
+    "**/*.config.js",    // Config files
+    "**/*.test.ts",      // Test files
+    "**/*.config.ts",    // Config files
+];
+
+/// Check if a path should be skipped based on the effective skip patterns
+/// (built-in SKIP_FILES + user `skipFiles`, merged in Config::load).
+pub fn should_skip_path(path: &Path, name: &str, patterns: &[String]) -> bool {
+    // Check if name starts with dot (dotfiles/directories)
+    if name.starts_with('.') {
+        return true;
+    }
+
+    // Check exact name match (for directories and simple filenames)
+    if patterns.iter().any(|p| p == name) {
+        return true;
+    }
+
+    // Check glob patterns (e.g., **/*.test.js)
+    for pattern_str in patterns {
+        if pattern_str.contains('*') {
+            if let Ok(pattern) = Pattern::new(pattern_str) {
+                // Try matching against just the filename
+                if pattern.matches(name) {
+                    return true;
+                }
+                // Try matching against the full path
+                if let Some(path_str) = path.to_str() {
+                    if pattern.matches(path_str) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+
+    false
+}
+
+/// Recursively gather JS sources that could write `$` state: every `.js` module
+/// (full text — also a candidate for the global `vibe()` call) plus, from each
+/// `.html` file, every inline `<script>` body and `on*` handler body. Skips the
+/// compiled output directory and anything `should_skip_path` excludes.
+fn collect_state_sources(
+    dir: &Path,
+    output_canon: Option<&Path>,
+    skip: &[String],
+    sources: &mut Vec<String>,
+    js_paths: &mut Vec<PathBuf>,
+) {
+    let entries = match fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(_) => return,
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        let name = match path.file_name().and_then(|n| n.to_str()) {
+            Some(n) => n,
+            None => continue,
+        };
+        if should_skip_path(&path, name, skip) {
+            continue;
+        }
+        if path.is_dir() {
+            // Never descend into the compiled output — its JS is bundled/minified
+            // and would falsely trip the analysis.
+            if let (Some(oc), Some(pc)) = (output_canon, path.canonicalize().ok()) {
+                if pc.as_path() == oc {
+                    continue;
+                }
+            }
+            collect_state_sources(&path, output_canon, skip, sources, js_paths);
+        } else {
+            match path.extension().and_then(|e| e.to_str()) {
+                Some("js") => {
+                    if let Ok(code) = fs::read_to_string(&path) {
+                        sources.push(code);
+                        js_paths.push(path);
+                    }
+                }
+                Some("html") => {
+                    if let Ok(html) = fs::read_to_string(&path) {
+                        sources.extend(extract_inline_scripts(&html));
+                        sources.extend(extract_event_handlers(&html));
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+}
+
+/// Inner JS of every `<script>…</script>` block.
+fn extract_inline_scripts(html: &str) -> Vec<String> {
+    let re = Regex::new(r"(?is)<script\b[^>]*>(.*?)</script>").unwrap();
+    re.captures_iter(html)
+        .map(|c| c[1].to_string())
+        .filter(|s| !s.trim().is_empty())
+        .collect()
+}
+
+/// Bodies of `on*="…"` / `on*='…'` event-handler attributes. The attribute-name
+/// match is heuristic (it can catch a non-handler like `only="…"`), so each body
+/// is kept only if it parses as JS — genuine handlers parse, false positives drop.
+fn extract_event_handlers(html: &str) -> Vec<String> {
+    use crate::compiler::reassignment_analyzer::parses_as_js;
+    let re = Regex::new(r#"(?is)\son[a-z]+\s*=\s*(?:"([^"]*)"|'([^']*)')"#).unwrap();
+    re.captures_iter(html)
+        .filter_map(|c| c.get(1).or_else(|| c.get(2)).map(|m| m.as_str().to_string()))
+        .filter(|body| !body.trim().is_empty() && parses_as_js(body))
+        .collect()
+}
+
+/// Rename `src="{component_src}"` to `data-vibe-recursive-src="{component_src}"`
+/// on `<component>` / `<div class="component">` tags. Used during cache build
+/// to neutralize cyclic refs before they reach `inline_component_elements` —
+/// the inliner's `src=` regex won't match the renamed attribute, so it stops
+/// re-expanding. `process_html_with_cache` restores the attribute to plain
+/// `src=` at the end of compilation so the runtime fetches it normally.
+fn escape_recursive_src(content: &str, component_src: &str) -> String {
+    let pattern = format!(
+        r#"(<(?:component|div)\s+[^>]*\b)src="{}""#,
+        regex::escape(component_src),
+    );
+    let re = Regex::new(&pattern).unwrap();
+    re.replace_all(content, format!(r#"$1data-vibe-recursive-src="{}""#, component_src))
+        .into_owned()
+}
+
+/// Remove FOUC prevention class and/or attribute from compiled HTML
+/// Since HTML is pre-rendered, there's no need for FOUC prevention
+fn remove_fouc_prevention(html: String) -> String {
+    let mut result = html;
+
+    // Remove as class: class="vibe-fouc" or class="vibe-fouc other-class" or class="other-class vibe-fouc"
+    result = Regex::new(&format!(r#"\s+class="{}""#, FOUC_CLASS_OR_ATTR))
+        .unwrap()
+        .replace_all(&result, "")
+        .to_string();
+    result = Regex::new(&format!(r#"class="{}\s+"#, FOUC_CLASS_OR_ATTR))
+        .unwrap()
+        .replace_all(&result, r#"class=""#)
+        .to_string();
+    result = Regex::new(&format!(r#"class="([^"]*\s+){}(\s+[^"]*)""#, FOUC_CLASS_OR_ATTR))
+        .unwrap()
+        .replace_all(&result, r#"class="$1$2""#)
+        .to_string();
+
+    // Remove as attribute: vibe-fouc or vibe-fouc=""
+    result = Regex::new(&format!(r#"\s+{}(?:="[^"]*")?"#, FOUC_CLASS_OR_ATTR))
+        .unwrap()
+        .replace_all(&result, "")
+        .to_string();
+
+    result
+}
+
+#[derive(Error, Debug)]
+pub enum CompileError {
+    #[error("Source directory not found: {0}")]
+    SourceNotFound(String),
+    #[error("Failed to create output directory: {0}")]
+    CreateDirError(String),
+    #[error("Failed to read file {path}: {source}")]
+    ReadError {
+        path: String,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to write file {path}: {source}")]
+    WriteError {
+        path: String,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("{file}:{line} - {message}")]
+    ValidationError {
+        file: String,
+        line: usize,
+        message: String,
+    },
+    #[error("Parse error: {0}")]
+    ParseError(#[from] crate::parser::html::ParseError),
+    #[error("Failed to execute command: {0}")]
+    CommandError(String),
+    #[error("Package manager not found")]
+    PackageManagerNotFound,
+    #[error("Component name '{component_name}' in '{file_path}' conflicts with reserved element. Component filenames cannot match standard HTML elements (case-insensitive). Use PascalCase (e.g., 'Nav.html' instead of 'nav.html') to avoid conflicts.")]
+    ReservedComponentName {
+        component_name: String,
+        file_path: String,
+    },
+    #[error("SPA mode: {0}")]
+    SpaError(String),
+}
+
+pub struct CompileStats {
+    pub files_compiled: usize,
+    pub files_copied: usize,
+    pub internal_components_unique: usize,
+    pub external_components_unique: usize,
+    pub internal_components_total: usize,
+    pub external_components_total: usize,
+    pub compile_time_ms: f64,
+    pub copy_time_ms: f64,
+    pub components_time_ms: f64,
+    pub validation_time_ms: Option<f64>,
+    pub node_modules_time_ms: Option<f64>,
+    pub package_manager: Option<String>,
+    pub node_modules_copied_as_is: bool,
+    pub components_as_is: bool,
+}
+
+pub struct ManifestStats {
+    pub pages_processed: usize,
+    pub pages_skipped: usize,
+    pub total_time_ms: f64,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+enum FileOperation {
+    Compiled,
+    Copied,
+}
+
+struct VerboseLogger {
+    operations: BTreeMap<String, Vec<(String, FileOperation)>>, // dir -> [(filename, operation)]
+    component_counts: HashMap<String, usize>, // component src -> count
+    component_children: HashMap<String, HashSet<String>>, // component src -> direct children
+    components_as_is: bool,
+}
+
+impl VerboseLogger {
+    fn new(components_as_is: bool) -> Self {
+        Self {
+            operations: BTreeMap::new(),
+            component_counts: HashMap::new(),
+            component_children: HashMap::new(),
+            components_as_is,
+        }
+    }
+
+    fn log_component_occurrence(&mut self, src: String) {
+        // Increment count for this component
+        *self.component_counts.entry(src).or_insert(0) += 1;
+    }
+
+    fn log_component_children(&mut self, src: String, children: Vec<String>) {
+        // Track children relationships
+        if !children.is_empty() {
+            self.component_children
+                .entry(src)
+                .or_insert_with(HashSet::new)
+                .extend(children);
+        }
+    }
+
+    fn log(&mut self, path: &Path, operation: FileOperation, source_root: &Path) {
+        let relative = path.strip_prefix(source_root).unwrap_or(path);
+        let dir = relative.parent()
+            .map(|p| p.to_string_lossy().to_string())
+            .unwrap_or_else(|| String::from(""));
+        let filename = relative.file_name()
+            .map(|f| f.to_string_lossy().to_string())
+            .unwrap_or_default();
+
+        self.operations
+            .entry(dir)
+            .or_insert_with(Vec::new)
+            .push((filename, operation));
+    }
+
+    fn print_components(&self) {
+        if self.components_as_is {
+            println!("\n{} (0 {}, 0 {}) - \"components-as-is\": true",
+                "Compiled components".bright_cyan(),
+                "internal".bright_green(),
+                "external".bright_magenta()
+            );
+            return;
+        }
+
+        if self.component_counts.is_empty() {
+            return;
+        }
+
+        // Count internal vs external
+        let mut internal_total = 0;
+        let mut external_total = 0;
+        for (src, count) in &self.component_counts {
+            if src.starts_with("http://") || src.starts_with("https://") {
+                external_total += count;
+            } else {
+                internal_total += count;
+            }
+        }
+
+        println!("\n{} ({} {}, {} {})",
+            "Compiled components".bright_cyan().bold(),
+            internal_total,
+            "internal".bright_green(),
+            external_total,
+            "external".bright_magenta()
+        );
+        println!();
+
+        // Sort components by count (descending) then alphabetically
+        let mut components: Vec<_> = self.component_counts.iter().collect();
+        components.sort_by(|(a_src, a_count), (b_src, b_count)| {
+            b_count.cmp(a_count).then_with(|| a_src.cmp(b_src))
+        });
+
+        // Find top-level components (those not referenced as children of others)
+        let all_children: HashSet<String> = self.component_children
+            .values()
+            .flat_map(|children| children.iter().cloned())
+            .collect();
+
+        // Print each top-level component with its tree
+        for (src, count) in &components {
+            // Only show as top-level if it's not a child of another component
+            if !all_children.contains(*src) {
+                let is_external = src.starts_with("http://") || src.starts_with("https://");
+
+                let display = if is_external {
+                    format!("{} ({})", src, count).bright_magenta()
+                } else {
+                    format!("{} ({})", src, count).bright_green()
+                };
+
+                println!("{}", display);
+
+                // Print children if any
+                if let Some(children) = self.component_children.get(*src) {
+                    let mut children_vec: Vec<_> = children.iter().collect();
+                    children_vec.sort();
+
+                    for child in children_vec {
+                        let is_external = child.starts_with("http://") || child.starts_with("https://");
+                        let display = if is_external {
+                            format!("  └─ {}", child).bright_magenta()
+                        } else {
+                            format!("  └─ {}", child).bright_green()
+                        };
+                        println!("{}", display);
+                    }
+                }
+            }
+        }
+    }
+
+    fn print_compiled(&self) {
+        self.print_operations("Compiled HTML", FileOperation::Compiled);
+    }
+
+    fn print_copied(&self) {
+        self.print_operations("Copied files", FileOperation::Copied);
+    }
+
+    fn print_operations(&self, label: &str, op_type: FileOperation) {
+        let matching: Vec<_> = self.operations.iter()
+            .map(|(dir, files)| {
+                let filtered: Vec<_> = files.iter()
+                    .filter(|(_, op)| {
+                        match (&op_type, op) {
+                            (FileOperation::Compiled, FileOperation::Compiled) => true,
+                            (FileOperation::Copied, FileOperation::Copied) => true,
+                            _ => false,
+                        }
+                    })
+                    .map(|(name, _)| name.clone())
+                    .collect();
+                (dir.clone(), filtered)
+            })
+            .filter(|(_, files)| !files.is_empty())
+            .collect();
+
+        if matching.is_empty() {
+            return;
+        }
+
+        let total_count: usize = matching.iter().map(|(_, files)| files.len()).sum();
+        println!("\n{} ({})", label.bright_cyan().bold(), total_count);
+        println!();
+
+        // Root files first
+        if let Some((_, files)) = matching.iter().find(|(dir, _)| dir.is_empty()) {
+            for file in files {
+                println!("  {}", file);
+            }
+        }
+
+        // Then directories hierarchically
+        self.print_directories(&matching, "", 1);
+    }
+
+    fn print_directories(&self, matching: &[(String, Vec<String>)], parent: &str, depth: usize) {
+        // Find all directories at this level
+        let mut dirs_at_level: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
+
+        for (dir, _) in matching {
+            if dir.is_empty() {
+                continue;
+            }
+
+            let remainder = if parent.is_empty() {
+                if dir.starts_with(parent) {
+                    dir.as_str()
+                } else {
+                    continue;
+                }
+            } else {
+                if dir.starts_with(parent) && dir.len() > parent.len() {
+                    &dir[parent.len() + 1..] // +1 for the separator
+                } else {
+                    continue;
+                }
+            };
+
+            if let Some(slash_pos) = remainder.find('/') {
+                dirs_at_level.insert(remainder[..slash_pos].to_string());
+            } else if !remainder.is_empty() {
+                dirs_at_level.insert(remainder.to_string());
+            }
+        }
+
+        // Print each directory
+        for dir_name in dirs_at_level {
+            let full_path = if parent.is_empty() {
+                dir_name.clone()
+            } else {
+                format!("{}/{}", parent, dir_name)
+            };
+
+            let indent = "  ".repeat(depth);
+
+            // Count files directly in this directory (not subdirectories)
+            let file_count = matching.iter()
+                .find(|(d, _)| d == &full_path)
+                .map(|(_, files)| files.len())
+                .unwrap_or(0);
+
+            if file_count > 0 {
+                println!("{}{} ({})", indent, format!("/{}", dir_name).cyan(), file_count);
+            } else {
+                println!("{}{}", indent, format!("/{}", dir_name).cyan());
+            }
+
+            // Print files in this directory
+            if let Some((_, files)) = matching.iter().find(|(d, _)| d == &full_path) {
+                for file in files {
+                    println!("{}  {}", indent, file);
+                }
+            }
+
+            // Recurse into subdirectories
+            self.print_directories(matching, &full_path, depth + 1);
+        }
+    }
+}
+
+pub struct Compiler {
+    config: Config,
+    verbose: bool,
+    logger: Option<VerboseLogger>,
+    unique_components: HashSet<String>,
+    /// Cache for all components (both internal paths and external URLs)
+    component_cache: std::collections::HashMap<String, String>,
+    /// Compiled (pre-stamp) HTML of every page this compiler wrote, keyed by
+    /// output path. Manifest generation builds from these bytes — never from a
+    /// disk read-back — so a concurrent writer rewriting the output directory
+    /// (e.g. a second compiler) can't feed a torn read into a manifest.
+    compiled_html: HashMap<PathBuf, String>,
+}
+
+impl Compiler {
+    pub fn new(config: Config, verbose: bool) -> Self {
+        let logger = if verbose { Some(VerboseLogger::new(config.components_as_is)) } else { None };
+        Self {
+            config,
+            verbose,
+            logger,
+            unique_components: HashSet::new(),
+            component_cache: HashMap::new(),
+            compiled_html: HashMap::new(),
+        }
+    }
+
+    /// Drop only the named cache entries, forcing those components to be
+    /// re-read + re-inlined on the next compile while every other component is
+    /// reused from cache. `keys` are normalized component srcs (e.g.
+    /// `/components/Sidebar.html`). Returns how many entries were actually
+    /// removed. This is the incremental-watch path: invalidate the edited
+    /// component and its inlining ancestors, nothing else.
+    pub fn invalidate_components(&mut self, keys: &std::collections::HashSet<String>) -> usize {
+        let before = self.component_cache.len();
+        self.component_cache.retain(|key, _| !keys.contains(key));
+        before - self.component_cache.len()
+    }
+
+    /// Number of components currently held in the inlining cache.
+    pub fn cached_component_count(&self) -> usize {
+        self.component_cache.len()
+    }
+
+    /// Take over another compiler's warm component cache, leaving it empty.
+    /// The watch loop uses this to carry the initial full-compile cache into the
+    /// incremental compiler, so even the first edit reuses everything unchanged
+    /// instead of re-fetching the whole tree.
+    pub fn adopt_component_cache(&mut self, other: &mut Compiler) {
+        self.component_cache = std::mem::take(&mut other.component_cache);
+    }
+
+    pub fn compile(&mut self) -> Result<CompileStats, CompileError> {
+        let mut stats = CompileStats {
+            files_compiled: 0,
+            files_copied: 0,
+            internal_components_unique: 0,
+            external_components_unique: 0,
+            internal_components_total: 0,
+            external_components_total: 0,
+            compile_time_ms: 0.0,
+            copy_time_ms: 0.0,
+            components_time_ms: 0.0,
+            validation_time_ms: None,
+            node_modules_time_ms: None,
+            package_manager: None,
+            node_modules_copied_as_is: false,
+            components_as_is: self.config.components_as_is,
+        };
+
+        // Validate source exists
+        if !self.config.source.exists() {
+            return Err(CompileError::SourceNotFound(
+                self.config.source.display().to_string(),
+            ));
+        }
+
+        // Load components for HTML compilation
+        let mut parser = HtmlParser::new(self.config.components_path());
+        parser.load_elements()?;
+
+        // Validate component names don't conflict with reserved elements
+        self.validate_component_names()?;
+
+        // Fetch and cache all components for inlining (when not components_as_is)
+        // This is separate from validation - we need component content for inlining regardless of validate flag
+        if !self.config.components_as_is {
+            let fetch_start = Instant::now();
+            if self.verbose {
+                println!("\nFetching components for inlining...");
+            }
+            self.fetch_all_components(&parser)?;
+            stats.components_time_ms = fetch_start.elapsed().as_secs_f64() * 1000.0;
+            if self.verbose {
+                println!("  All components fetched successfully");
+            }
+        }
+
+        // Validate HTML syntax (always runs)
+        let validation_start = Instant::now();
+        if self.verbose {
+            println!("\nValidating HTML syntax...");
+        }
+        self.validate_html_syntax()?;
+        stats.validation_time_ms = Some(validation_start.elapsed().as_secs_f64() * 1000.0);
+        if self.verbose {
+            println!("  HTML validation completed successfully");
+        }
+
+        // Clean output directory if not in no-clean mode
+        if !self.config.no_clean && self.config.output.exists() {
+            if self.verbose {
+                println!("  Cleaning output directory: {}", self.config.output.display());
+            }
+            fs::remove_dir_all(&self.config.output).map_err(|e| {
+                CompileError::WriteError {
+                    path: self.config.output.display().to_string(),
+                    source: e,
+                }
+            })?;
+        }
+
+        // Create output directory
+        if !self.config.output.exists() {
+            fs::create_dir_all(&self.config.output).map_err(|_| {
+                CompileError::CreateDirError(self.config.output.display().to_string())
+            })?;
+            if self.verbose {
+                println!("  Created output directory: {}", self.config.output.display());
+            }
+        }
+
+        // Canonicalize both output and source paths for reliable comparison
+        let canonical_output = self.config.output.canonicalize()
+            .unwrap_or_else(|_| self.config.output.clone());
+        let canonical_source = self.config.source.canonicalize()
+            .unwrap_or_else(|_| self.config.source.clone());
+
+        // Track compile and copy times separately
+        let compile_start = Instant::now();
+
+        // Process all HTML files in source (excluding components directory)
+        self.process_directory_html_only(&canonical_source, &parser, "", &canonical_output, &canonical_source, &mut stats)?;
+
+        // Process source directory for assets (CSS, JS, images, etc.)
+        self.process_directory_assets_only(&canonical_source, "", &canonical_output, &canonical_source, &mut stats)?;
+
+        // SPA mode: pages tree → fragments + route table + composed shell.
+        // Runs after both passes so the shell wins over any root index.html
+        // and fragments land beside the mirrored components.
+        if self.config.spa {
+            stats.files_compiled += self.compile_spa(&parser)?;
+        }
+
+        let process_time = compile_start.elapsed();
+
+        // Print verbose output after processing (components first, then HTML, then copied)
+        if let Some(ref logger) = self.logger {
+            logger.print_components();
+            logger.print_compiled();
+            logger.print_copied();
+        }
+
+        // Calculate unique components after processing all files
+        let internal_unique = self.unique_components.iter()
+            .filter(|src| !src.starts_with("http://") && !src.starts_with("https://"))
+            .count();
+        let external_unique = self.unique_components.iter()
+            .filter(|src| src.starts_with("http://") || src.starts_with("https://"))
+            .count();
+
+        stats.internal_components_unique = internal_unique;
+        stats.external_components_unique = external_unique;
+
+        // Calculate times based on counts (rough estimate)
+        // Component operations are part of compile time but tracked separately for user visibility
+        let total_files = stats.files_compiled + stats.files_copied;
+        let total_components = stats.internal_components_total + stats.external_components_total;
+
+        if total_files > 0 {
+            let total_ms = process_time.as_secs_f64() * 1000.0;
+
+            if total_components > 0 {
+                // Component processing is slowest, compile is medium, copy is fastest
+                // Rough weights: component=3, compile=2, copy=1
+                let total_weight = (total_components * 3 + stats.files_compiled * 2 + stats.files_copied) as f64;
+                stats.components_time_ms = (total_ms * (total_components * 3) as f64) / total_weight;
+                stats.compile_time_ms = (total_ms * (stats.files_compiled * 2) as f64) / total_weight;
+                stats.copy_time_ms = (total_ms * stats.files_copied as f64) / total_weight;
+            } else {
+                // No component operations, just split between compile and copy
+                stats.compile_time_ms = (total_ms * stats.files_compiled as f64) / total_files as f64;
+                stats.copy_time_ms = (total_ms * stats.files_copied as f64) / total_files as f64;
+            }
+        }
+
+        // Handle node_modules after successful compilation
+        if self.config.working_dir.join("node_modules").exists() {
+            if self.config.node_modules_as_is {
+                // Copy node_modules as-is (no install, just copy)
+                let nm_start = Instant::now();
+                self.copy_node_modules_as_is()?;
+                stats.node_modules_time_ms = Some(nm_start.elapsed().as_secs_f64() * 1000.0);
+                stats.node_modules_copied_as_is = true;
+
+                if self.verbose {
+                    println!("\n  Copied node_modules as-is");
+                }
+            } else {
+                // Use production-only strategy (runs install commands)
+                let pkg_manager = detect_package_manager(&self.config.working_dir).ok();
+                stats.package_manager = pkg_manager.clone();
+
+                let nm_start = Instant::now();
+                self.copy_production_node_modules()?;
+                stats.node_modules_time_ms = Some(nm_start.elapsed().as_secs_f64() * 1000.0);
+
+                if self.verbose {
+                    println!("  Copied production dependencies");
+                }
+            }
+        }
+
+        Ok(stats)
+    }
+
+    /// Compile specific HTML files (incremental compilation for watch mode)
+    pub fn compile_specific_html_files(
+        &mut self,
+        files: &[PathBuf],
+        parser: &HtmlParser,
+    ) -> Result<CompileStats, CompileError> {
+        let mut stats = CompileStats {
+            files_compiled: 0,
+            files_copied: 0,
+            internal_components_unique: 0,
+            external_components_unique: 0,
+            internal_components_total: 0,
+            external_components_total: 0,
+            compile_time_ms: 0.0,
+            copy_time_ms: 0.0,
+            components_time_ms: 0.0,
+            validation_time_ms: None,
+            node_modules_time_ms: None,
+            package_manager: None,
+            node_modules_copied_as_is: false,
+            components_as_is: self.config.components_as_is,
+        };
+
+        let start = Instant::now();
+
+        // Pre-fetch components needed by these specific files (only if not components_as_is)
+        if !self.config.components_as_is {
+            let fetch_start = Instant::now();
+            self.fetch_components_for_files(files, parser)?;
+            stats.components_time_ms = fetch_start.elapsed().as_secs_f64() * 1000.0;
+        }
+
+        for file_path in files {
+            // Validate HTML before compiling (same as full compile path)
+            let content = fs::read_to_string(file_path).map_err(|e| CompileError::ReadError {
+                path: file_path.display().to_string(),
+                source: e,
+            })?;
+            self.validate_html(&content, file_path)?;
+
+            // Calculate relative path
+            let relative_path = file_path
+                .strip_prefix(&self.config.source)
+                .map(|p| p.parent().unwrap_or(Path::new("")))
+                .unwrap_or(Path::new(""))
+                .to_str()
+                .unwrap_or("");
+
+            let (internal, external, component_srcs) = self.compile_html_file(file_path, parser, relative_path)?;
+            stats.files_compiled += 1;
+            stats.internal_components_total += internal;
+            stats.external_components_total += external;
+
+            // Track unique components
+            for src in &component_srcs {
+                self.unique_components.insert(src.clone());
+            }
+
+            if let Some(ref mut logger) = self.logger {
+                logger.log(file_path, FileOperation::Compiled, &self.config.source);
+                for src in component_srcs {
+                    logger.log_component_occurrence(src);
+                }
+            }
+        }
+
+        // Calculate unique components
+        let internal_unique = self.unique_components.iter()
+            .filter(|src| !src.starts_with("http://") && !src.starts_with("https://"))
+            .count();
+        let external_unique = self.unique_components.iter()
+            .filter(|src| src.starts_with("http://") || src.starts_with("https://"))
+            .count();
+
+        stats.internal_components_unique = internal_unique;
+        stats.external_components_unique = external_unique;
+
+        // Calculate compile time (excluding component fetch time which is already tracked)
+        let elapsed = start.elapsed().as_secs_f64() * 1000.0;
+        stats.compile_time_ms = elapsed - stats.components_time_ms;
+
+        Ok(stats)
+    }
+
+    /// Copy specific asset files (incremental compilation for watch mode)
+    pub fn copy_specific_asset_files(
+        &mut self,
+        files: &[PathBuf],
+    ) -> Result<CompileStats, CompileError> {
+        let mut stats = CompileStats {
+            files_compiled: 0,
+            files_copied: 0,
+            internal_components_unique: 0,
+            external_components_unique: 0,
+            internal_components_total: 0,
+            external_components_total: 0,
+            compile_time_ms: 0.0,
+            copy_time_ms: 0.0,
+            components_time_ms: 0.0,
+            validation_time_ms: None,
+            node_modules_time_ms: None,
+            package_manager: None,
+            node_modules_copied_as_is: false,
+            components_as_is: self.config.components_as_is,
+        };
+
+        let start = Instant::now();
+
+        for file_path in files {
+            // Calculate relative path for preserving directory structure
+            let relative_path = file_path
+                .strip_prefix(&self.config.source)
+                .map(|p| p.parent().unwrap_or(Path::new("")))
+                .unwrap_or(Path::new(""))
+                .to_str()
+                .unwrap_or("");
+
+            self.copy_file(file_path, relative_path)?;
+            stats.files_copied += 1;
+
+            if let Some(ref mut logger) = self.logger {
+                logger.log(file_path, FileOperation::Copied, &self.config.source);
+            }
+        }
+
+        let elapsed = start.elapsed().as_secs_f64() * 1000.0;
+        stats.copy_time_ms = elapsed;
+
+        Ok(stats)
+    }
+
+    /// Generate manifests for specific HTML files (incremental compilation for watch mode)
+    pub fn generate_manifests_for_files(&self, files: &[PathBuf]) -> Result<ManifestStats, CompileError> {
+        let start = Instant::now();
+
+        // Mirror generate_manifests: process each page's manifest in parallel.
+        // Manifest generation is the bulk of an incremental recompile (static
+        // analysis + serialization per page), so a sequential loop over the
+        // affected pages left most cores idle and dominated watch latency.
+        let output_dir = self.config.output.clone();
+        let source_root = self.config.source.clone();
+        let verbose = self.verbose;
+        let iterations_as_is = self.config.iterations_as_is;
+        let components_as_is = self.config.components_as_is;
+        let manifest_root = self.config.root.clone();
+        let spa = self.config.spa;
+        // Resolve constant global-state keys once, shared read-only across pages.
+        let global_constants = self.compute_global_constants();
+
+        let compiled_html = &self.compiled_html;
+        let results: Vec<bool> = files
+            .par_iter()
+            .map(|file_path| {
+                let relative_path = match file_path.strip_prefix(&source_root).unwrap_or(file_path).to_str() {
+                    Some(r) => r,
+                    None => return false,
+                };
+
+                let output_path = output_dir.join(relative_path);
+                if !output_path.exists() {
+                    return false;
+                }
+
+                // The HTML this compiler produced in memory is the source of
+                // truth; the on-disk file may have been rewritten by another
+                // process since we wrote it. Disk is only a fallback for pages
+                // this compiler never compiled (e.g. no-clean leftovers).
+                let disk_html;
+                let html: &str = match compiled_html.get(&output_path) {
+                    Some(h) => h,
+                    None => {
+                        disk_html = match fs::read_to_string(&output_path) {
+                            Ok(h) => h,
+                            Err(_) => return false,
+                        };
+                        &disk_html
+                    }
+                };
+
+                match Self::generate_file_manifest(
+                    html,
+                    &output_path,
+                    &output_dir,
+                    relative_path,
+                    verbose,
+                    iterations_as_is,
+                    components_as_is,
+                    &source_root,
+                    manifest_root.as_deref(),
+                    &global_constants,
+                    !(spa && relative_path == "index.html"),
+                ) {
+                    Ok(()) => true,
+                    Err(e) => {
+                        if verbose {
+                            eprintln!("  Skipped ({}): {}", e, relative_path);
+                        }
+                        false
+                    }
+                }
+            })
+            .collect();
+
+        let pages_processed = results.iter().filter(|&&ok| ok).count();
+        let pages_skipped = results.len() - pages_processed;
+
+        let total_time_ms = start.elapsed().as_millis() as f64;
+
+        Ok(ManifestStats {
+            pages_processed,
+            pages_skipped,
+            total_time_ms,
+        })
+    }
+
+    /// Generate manifest for a single file
+    fn generate_file_manifest(
+        html: &str,
+        html_path: &Path,
+        output_dir: &Path,
+        relative_path: &str,
+        _verbose: bool,
+        iterations_as_is: bool,
+        components_as_is: bool,
+        source_root: &Path,
+        manifest_root: Option<&str>,
+        global_constants: &Map<String, Value>,
+        stamp: bool,
+    ) -> Result<(), String> {
+        use crate::compiler::manifest_builder::ManifestBuilder;
+        use crate::compiler::component_tagger::ComponentTagger;
+        use crate::compiler::value_stamper::ValueStamper;
+
+        // Relocate whitespace-bearing name-bindings into a value-attribute BEFORE any
+        // html5ever round-trip splits them on their spaces (see name_binding_protect).
+        let protected = crate::compiler::name_binding_protect::protect(html);
+
+        // Tag components with deterministic IDs and structure state
+        let tagged = ComponentTagger::tag_components(&protected, &source_root.to_path_buf())?;
+        let html = &tagged.html;  // Use modified HTML with data-vibe-component-id attributes
+        let state = tagged.state;
+
+        // Build manifest from pre-stamp HTML (both conditional branches present, @[...] markers intact)
+        // This ensures restoration.template has both branches so runtime can switch between them
+        let manifest_builder = ManifestBuilder::new();
+        let manifest = manifest_builder.build_from_html(html, &state, iterations_as_is)?;
+
+        // Map the output-relative path to the served-URL path: drop the `root`
+        // dir (the folder served at /, e.g. `pages`) and collapse dynamic
+        // `$param` segments to a single `$` token. This lets the runtime resolve
+        // a manifest from a clean URL — `/armory` and `/the-arena/123` find
+        // `armory.html.manifest.js` and `the-arena/$.html.manifest.js`.
+        let manifest_rel = manifest_url_path(relative_path, manifest_root);
+
+        // Write manifest
+        let manifest_path = output_dir
+            .join("vibe-hyperspeed")
+            .join(format!("{}.manifest.js", manifest_rel));
+
+        // Ensure directory exists
+        if let Some(parent) = manifest_path.parent() {
+            fs::create_dir_all(parent)
+                .map_err(|e| format!("Failed to create manifest directory: {}", e))?;
+        }
+
+        let manifest_json = serde_json::to_string(&manifest)
+            .map_err(|e| format!("Failed to serialize manifest: {}", e))?;
+
+        let manifest_js = format!(
+            "// Pre-compiled manifest for /{}\n// Generated by Vibe compiler\n\nexport default {};\n",
+            manifest_rel,
+            manifest_json
+        );
+
+        atomic_write(&manifest_path, &manifest_js)
+            .map_err(|e| format!("Failed to write manifest: {}", e))?;
+
+        // Stamp the compiled HTML with initial state values for FOUC prevention:
+        // - @[...] bindings replaced with their initial values
+        // - Only the active conditional branch is kept (inactive branch stripped)
+        // - Iterations are pre-rendered with initial array data
+        // The manifest (written above) preserves BOTH branches so the runtime can
+        // restore them and switch between branches reactively.
+        //
+        // The SPA shell opts out (stamp: false): its state is location-dependent
+        // — unstampable by design — and it is served at EVERY route path while
+        // its manifest only resolves at /. Stamping would strip the raw
+        // `@[page.src]` outlet binding and leave deep links with nothing to
+        // hydrate from; unstamped, the runtime processes the raw binding at any
+        // URL (vibe-fouc covers the flash).
+        if stamp {
+            let stamper = ValueStamper::with_constants(&state, components_as_is, global_constants)
+                .map_err(|e| format!("Failed to create value stamper: {}", e))?;
+            let stamped = stamper.stamp_html(html.to_string())
+                .map_err(|e| format!("Failed to stamp HTML: {}", e))?;
+
+            atomic_write(html_path, &stamped)
+                .map_err(|e| format!("Failed to write stamped HTML: {}", e))?;
+        }
+
+        Ok(())
+    }
+
+    /// Resolve the global `$` state keys that reassignment analysis proves are
+    /// compile-time constants, mapped to their resolved values — the only globals
+    /// safe to value-stamp into pre-rendered HTML. Scans every JS source under the
+    /// project source root (`.js` modules, inline `<script>` bodies, and `on*`
+    /// handler bodies), skipping the compiled output and the configured skips.
+    /// Returns an empty map on any doubt (see reassignment_analyzer soundness).
+    fn compute_global_constants(&self) -> Map<String, Value> {
+        use crate::compiler::js_analyzer::JsAnalyzer;
+        use crate::compiler::reassignment_analyzer::classify_constant_keys;
+
+        let root = &self.config.source;
+        let output_canon = self.config.output.canonicalize().ok();
+
+        let mut sources: Vec<String> = Vec::new();
+        let mut js_paths: Vec<PathBuf> = Vec::new();
+        collect_state_sources(
+            root,
+            output_canon.as_deref(),
+            &self.config.skip_files,
+            &mut sources,
+            &mut js_paths,
+        );
+
+        // Resolve the global vibe()/state() initial state. Partial resolution
+        // keeps statically-resolvable keys (e.g. `version: VERSION`) and drops
+        // runtime-only ones (`settings: loadLocalStorage(...)`), which is exactly
+        // the set we could ever stamp.
+        let mut global_state: Map<String, Value> = Map::new();
+        for path in &js_paths {
+            let code = match fs::read_to_string(path) {
+                Ok(c) => c,
+                Err(_) => continue,
+            };
+            if !(code.contains("vibe(") || code.contains("state(")) {
+                continue;
+            }
+            let mut analyzer = JsAnalyzer::new(root.clone());
+            if let Some(Value::Object(state)) = analyzer.extract_state(&code) {
+                for (key, value) in state {
+                    global_state.insert(key, value);
+                }
+            }
+        }
+        if global_state.is_empty() {
+            return Map::new();
+        }
+
+        let constant_keys = classify_constant_keys(&global_state, &sources);
+        global_state
+            .into_iter()
+            .filter(|(key, _)| constant_keys.contains(key))
+            .collect()
+    }
+
+    /// Generate manifests (called separately from main.rs if needed)
+    pub fn generate_manifests(&self) -> Result<ManifestStats, CompileError> {
+
+        let start = Instant::now();
+        let mut pages_processed = 0;
+        let mut pages_skipped = 0;
+
+        if self.verbose {
+            println!("\nGenerating manifests (static analysis)");
+        }
+
+        // Find all HTML files in compiled output (excluding components directory)
+        let html_files = self.find_all_html_files(&self.config.output)?;
+
+        // Process manifests in parallel
+        let output_dir = self.config.output.clone();
+        let source_root = self.config.source.clone();
+        let verbose = self.verbose;
+        let iterations_as_is = self.config.iterations_as_is;
+        let components_as_is = self.config.components_as_is;
+        let manifest_root = self.config.root.clone();
+        let spa = self.config.spa;
+        // Resolve which global state keys are constant once, then share across all
+        // pages (read-only; `&Map` is Sync so the parallel map can borrow it).
+        let global_constants = self.compute_global_constants();
+
+        let compiled_html = &self.compiled_html;
+        let results: Vec<_> = html_files
+            .par_iter()
+            .map(|html_path| {
+                let relative_path = html_path.strip_prefix(&output_dir)
+                    .unwrap()
+                    .to_str()
+                    .unwrap();
+
+                // Prefer the HTML this compiler produced in memory — the disk
+                // copy may have been rewritten by another process since. Disk
+                // is only a fallback for pages this compiler never compiled
+                // (e.g. no-clean leftovers from an earlier run).
+                let disk_html;
+                let html: &str = match compiled_html.get(html_path.as_path()) {
+                    Some(h) => h,
+                    None => {
+                        disk_html = match fs::read_to_string(html_path) {
+                            Ok(h) => h,
+                            Err(_) => return (false, Some(relative_path.to_string())),
+                        };
+                        &disk_html
+                    }
+                };
+
+                // Try to generate manifest for this file (skip on error).
+                // The SPA shell keeps its raw bindings (manifest yes, stamp no).
+                let stamp = !(spa && relative_path == "index.html");
+                match Self::generate_file_manifest(html, html_path, &output_dir, relative_path, verbose, iterations_as_is, components_as_is, &source_root, manifest_root.as_deref(), &global_constants, stamp) {
+                    Ok(()) => (true, None),
+                    Err(e) => {
+                        if verbose {
+                            eprintln!("  Skipped ({}): {}", e, relative_path);
+                        }
+                        (false, Some(relative_path.to_string()))
+                    }
+                }
+            })
+            .collect();
+
+        // Count results
+        for (success, _) in results {
+            if success {
+                pages_processed += 1;
+            } else {
+                pages_skipped += 1;
+            }
+        }
+
+        let total_time_ms = start.elapsed().as_millis() as f64;
+
+        Ok(ManifestStats {
+            pages_processed,
+            pages_skipped,
+            total_time_ms,
+        })
+    }
+
+    /// Process directory for HTML files only (used for pages directory)
+    fn process_directory_html_only(
+        &mut self,
+        dir: &Path,
+        parser: &HtmlParser,
+        relative_path: &str,
+        canonical_output: &Path,
+        canonical_source: &Path,
+        stats: &mut CompileStats,
+    ) -> Result<(), CompileError> {
+        let entries = fs::read_dir(dir).map_err(|e| CompileError::ReadError {
+            path: dir.display().to_string(),
+            source: e,
+        })?;
+
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let file_name = path.file_name().unwrap().to_str().unwrap();
+
+            if path.is_dir() {
+                // Skip output directory (dynamically check, not hardcoded "compiled")
+                let canonical_path = path.canonicalize().unwrap_or_else(|_| path.clone());
+                if canonical_path == *canonical_output || canonical_path.starts_with(canonical_output) {
+                    continue;
+                }
+
+                // Skip special directories
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
+                    continue;
+                }
+
+                // Skip components directory
+                if file_name == self.config.components {
+                    continue;
+                }
+
+                // SPA mode: the pages tree becomes fragments + shell via
+                // compile_spa — no mirrored MPA documents in the output.
+                if self.config.spa && self.is_spa_pages_dir(&canonical_path) {
+                    continue;
+                }
+
+                // Recurse into subdirectory
+                let new_relative = if relative_path.is_empty() {
+                    file_name.to_string()
+                } else {
+                    format!("{}/{}", relative_path, file_name)
+                };
+
+                self.process_directory_html_only(&path, parser, &new_relative, canonical_output, canonical_source, stats)?;
+            } else if path.extension().and_then(|e| e.to_str()) == Some("html") {
+                let (internal, external, component_srcs) = self.compile_html_file(&path, parser, relative_path)?;
+                stats.files_compiled += 1;
+                stats.internal_components_total += internal;
+                stats.external_components_total += external;
+
+                // Track unique components
+                for src in &component_srcs {
+                    self.unique_components.insert(src.clone());
+                }
+
+                // Build component relationships and count occurrences before borrowing logger
+                let (component_relationships, all_srcs) = if self.logger.is_some() && !component_srcs.is_empty() {
+                    let relationships = self.build_component_relationships(&component_srcs);
+                    (Some(relationships), Some(component_srcs))
+                } else {
+                    (None, None)
+                };
+
+                if let Some(ref mut logger) = self.logger {
+                    logger.log(&path, FileOperation::Compiled, canonical_source);
+
+                    // Log each component occurrence (for counting)
+                    if let Some(all_srcs) = all_srcs {
+                        for src in all_srcs {
+                            logger.log_component_occurrence(src);
+                        }
+                    }
+
+                    // Log unique relationships (for tree structure)
+                    if let Some(relationships) = component_relationships {
+                        for (src, children) in relationships {
+                            logger.log_component_children(src, children);
+                        }
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Process directory for assets only (CSS, JS, images, etc.) - skip HTML
+    fn process_directory_assets_only(
+        &mut self,
+        dir: &Path,
+        relative_path: &str,
+        canonical_output: &Path,
+        canonical_source: &Path,
+        stats: &mut CompileStats,
+    ) -> Result<(), CompileError> {
+        let entries = fs::read_dir(dir).map_err(|e| CompileError::ReadError {
+            path: dir.display().to_string(),
+            source: e,
+        })?;
+
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let file_name = path.file_name().unwrap().to_str().unwrap();
+
+            if path.is_dir() {
+                // Skip output directory (dynamically check, not hardcoded "compiled")
+                let canonical_path = path.canonicalize().unwrap_or_else(|_| path.clone());
+                if canonical_path == *canonical_output || canonical_path.starts_with(canonical_output) {
+                    continue;
+                }
+
+                // Skip special directories
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
+                    continue;
+                }
+
+                // Skip node_modules (handled separately)
+                if file_name == "node_modules" {
+                    continue;
+                }
+
+                // SPA mode: the pages tree compiles to fragments, not output
+                // pages — the HTML walker already skips it, and the assets
+                // walker must too, or a co-located image/CSS/JSON resurrects
+                // an `output/pages/` directory SPA output promises not to have.
+                if self.config.spa && self.is_spa_pages_dir(&canonical_path) {
+                    continue;
+                }
+
+                // The components directory is always mirrored to the output. With
+                // components_as_is every component is loaded at runtime; otherwise
+                // most are inlined at build time, but iter-prop each-root components
+                // are deliberately left as runtime `<component src>` tags (see
+                // is_iter_prop_root in parser/html.rs) and the runtime fetches their
+                // source from here — exactly as it does in non-compiled mode.
+                if file_name == self.config.components {
+                    let new_relative = if relative_path.is_empty() {
+                        file_name.to_string()
+                    } else {
+                        format!("{}/{}", relative_path, file_name)
+                    };
+                    self.copy_directory(&path, &new_relative, canonical_source, stats)?;
+                    // Skip further processing (don't recurse into components)
+                    continue;
+                }
+
+                // Recurse into subdirectory
+                let new_relative = if relative_path.is_empty() {
+                    file_name.to_string()
+                } else {
+                    format!("{}/{}", relative_path, file_name)
+                };
+
+                self.process_directory_assets_only(&path, &new_relative, canonical_output, canonical_source, stats)?;
+            } else if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
+                // Skip files matching skip patterns
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
+                    continue;
+                }
+
+                // Only copy non-HTML assets
+                if ext != "html" && MIRROR_EXTENSIONS.contains(&ext) {
+                    self.copy_file(&path, relative_path)?;
+                    stats.files_copied += 1;
+                    if let Some(ref mut logger) = self.logger {
+                        logger.log(&path, FileOperation::Copied, canonical_source);
+                    }
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn compile_html_file(
+        &mut self,
+        path: &Path,
+        parser: &HtmlParser,
+        relative_path: &str,
+    ) -> Result<(usize, usize, Vec<String>), CompileError> {
+        let content = fs::read_to_string(path).map_err(|e| CompileError::ReadError {
+            path: path.display().to_string(),
+            source: e,
+        })?;
+
+        // Count <component src="..."> instances before processing (only if not components_as_is)
+        let (internal_count, external_count, component_srcs) = if !self.config.components_as_is {
+            self.extract_components(&content)
+        } else {
+            (0, 0, Vec::new())
+        };
+
+        // Compile: transform custom tags to <component>, inline if needed, transform custom elements
+        let processed = parser.process_html_with_cache(
+            &content,
+            self.config.elements_as_is,
+            &self.config.reserved_elements,
+            self.config.components_as_is,
+            &self.config.components,
+            &self.component_cache,
+        );
+
+        // Minify if requested
+        let mut output = if self.config.minify {
+            minify_html(&processed)
+        } else {
+            processed
+        };
+
+        // Remove FOUC prevention unless fouc_as_is is enabled
+        if !self.config.fouc_as_is {
+            output = remove_fouc_prevention(output);
+        }
+
+        // Write to output
+        let output_path = self.get_output_path(path, relative_path)?;
+        atomic_write(&output_path, &output).map_err(|e| CompileError::WriteError {
+            path: output_path.display().to_string(),
+            source: e,
+        })?;
+
+        // Keep the exact bytes for this pass's manifest generation.
+        self.compiled_html.insert(output_path, output);
+
+        // Return component counts and src list
+        Ok((internal_count, external_count, component_srcs))
+    }
+
+    /// True when a canonicalized directory is the configured pages tree.
+    fn is_spa_pages_dir(&self, canonical_path: &Path) -> bool {
+        self.config
+            .source
+            .join(&self.config.pages)
+            .canonicalize()
+            .map(|pages| pages == *canonical_path)
+            .unwrap_or(false)
+    }
+
+    fn collect_page_files(dir: &Path, skip: &[String], files: &mut Vec<PathBuf>) {
+        let Ok(entries) = fs::read_dir(dir) else { return };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let name = entry.file_name();
+            let name = name.to_string_lossy();
+            if should_skip_path(&path, &name, skip) {
+                continue;
+            }
+            if path.is_dir() {
+                Self::collect_page_files(&path, skip, files);
+            } else if path.extension().and_then(|e| e.to_str()) == Some("html") {
+                files.push(path);
+            }
+        }
+    }
+
+    /// SPA mode (fetched): transform every page into a fragment under
+    /// output/components/vibe-spa/, then compose the shell at output root.
+    /// Per-page stamped HTML, per-page manifests, and the pages/ output dir
+    /// do not exist in SPA mode — fragments are runtime-parsed on mount; the
+    /// shell flows through the normal manifest pipeline via compiled_html.
+    /// Returns the number of files written (pages + shell) for stats.
+    ///
+    /// Watch mode re-runs this whole pass on any pages-tree change — the
+    /// shell depends on every page's head/title/body attrs and the pass is
+    /// a few milliseconds, so per-page incrementality would buy nothing.
+    pub(crate) fn compile_spa(&mut self, parser: &HtmlParser) -> Result<usize, CompileError> {
+        use crate::compiler::spa;
+
+        let pages_dir = self.config.source.join(&self.config.pages);
+        if !pages_dir.exists() {
+            return Err(CompileError::SpaError(format!(
+                "needs a pages directory at {}",
+                pages_dir.display()
+            )));
+        }
+        let reserved = self.config.components_path().join("vibe-spa");
+        if reserved.exists() {
+            return Err(CompileError::SpaError(format!(
+                "{} is reserved for compiled page fragments — move or rename it",
+                reserved.display()
+            )));
+        }
+
+        let mut page_files = Vec::new();
+        Self::collect_page_files(&pages_dir, &self.config.skip_files, &mut page_files);
+        page_files.sort();
+        if page_files.is_empty() {
+            return Err(CompileError::SpaError(format!(
+                "found no pages under {}",
+                pages_dir.display()
+            )));
+        }
+
+        // Raw pre-pass: read every page and detect the shared-layout shape
+        // BEFORE component inlining consumes the <component src> root.
+        let mut raw_pages = Vec::new();
+        for path in &page_files {
+            let rel = path
+                .strip_prefix(&pages_dir)
+                .unwrap()
+                .to_string_lossy()
+                .replace('\\', "/");
+            let content = fs::read_to_string(path).map_err(|e| CompileError::ReadError {
+                path: path.display().to_string(),
+                source: e,
+            })?;
+            let candidate = spa::detect_layout_root(&content);
+            raw_pages.push((rel, content, candidate));
+        }
+        let candidates: Vec<_> = raw_pages.iter().map(|(_, _, c)| c.clone()).collect();
+        let hoisted = spa::hoistable_layout(&candidates);
+        if self.verbose {
+            if let Some((_, src)) = &hoisted {
+                println!("  spa: hoisted shared layout {} into the shell", src);
+            }
+        }
+
+        let mut pages = Vec::new();
+        // Disjoint build-id ranges per compile unit: the shell tags from 0,
+        // fragment i from (i + 1) * 1000. All units share one live document at
+        // runtime — the shell owns its chrome components for the app's
+        // lifetime, and a fragment tagged from the same base would claim those
+        // ids on mount (stomping shell state) and release them on unmount
+        // (killing shell bindings).
+        const SPA_UNIT_ID_STRIDE: usize = 1000;
+        for (page_index, (rel, content, candidate)) in raw_pages.into_iter().enumerate() {
+            // Hoisted mode compiles the REDUCED page (layout replaced by its
+            // slot content) through the unchanged pipeline — the fragment
+            // comes out as just the per-page content.
+            let content = match (&hoisted, candidate) {
+                (Some(_), Some((_, _, reduced))) => reduced,
+                _ => content,
+            };
+            let processed = parser.process_html_with_cache(
+                &content,
+                self.config.elements_as_is,
+                &self.config.reserved_elements,
+                self.config.components_as_is,
+                &self.config.components,
+                &self.component_cache,
+            );
+            // Build-inlined children get the compiled-document treatment:
+            // tagged wrapper ids + this.→_cN rewrites, matching their
+            // vibe-module scripts (the runtime's mounted-subtree pass claims
+            // ids via closest wrapper). Same protect→tag order as the
+            // manifest pipeline; the extracted state is a page concern and
+            // fragments have none to stamp.
+            let protected = crate::compiler::name_binding_protect::protect(&processed);
+            let id_base = (page_index + 1) * SPA_UNIT_ID_STRIDE;
+            let tagged =
+                crate::compiler::component_tagger::ComponentTagger::tag_components_from(
+                    &protected,
+                    &self.config.source,
+                    id_base,
+                )
+                .map_err(CompileError::SpaError)?;
+            if tagged.next_id > id_base + SPA_UNIT_ID_STRIDE {
+                return Err(CompileError::SpaError(format!(
+                    "pages/{} inlines {} components — more than the {} ids allotted per page",
+                    rel,
+                    tagged.next_id - id_base,
+                    SPA_UNIT_ID_STRIDE
+                )));
+            }
+            let page = spa::dissect_page(&rel, &tagged.html).map_err(CompileError::SpaError)?;
+
+            if let Some(api) = page.hygiene_offender {
+                eprintln!(
+                    "{}: pages/{} starts side effects ({}) without an $.on('unmount') teardown — under SPA these outlive navigation",
+                    "Warning".yellow(),
+                    rel,
+                    api
+                );
+            }
+
+            let fragment_path = self
+                .config
+                .output
+                .join("components")
+                .join("vibe-spa")
+                .join(&rel);
+            if let Some(parent) = fragment_path.parent() {
+                fs::create_dir_all(parent).map_err(|_| {
+                    CompileError::CreateDirError(parent.display().to_string())
+                })?;
+            }
+            atomic_write(&fragment_path, &page.fragment).map_err(|e| CompileError::WriteError {
+                path: fragment_path.display().to_string(),
+                source: e,
+            })?;
+
+            pages.push(page);
+        }
+
+        // Silent route collisions are unshippable: `foo.html` and
+        // `foo/index.html` both map to /foo, and stable-sort order would
+        // decide which page silently shadows the other. Hard error, naming
+        // both files (the reserved-dir check above set the precedent).
+        {
+            let mut seen: std::collections::HashMap<&str, &str> = std::collections::HashMap::new();
+            for page in &pages {
+                if let Some(first) = seen.insert(page.route.as_str(), page.rel_path.as_str()) {
+                    return Err(CompileError::SpaError(format!(
+                        "route collision: pages/{} and pages/{} both map to {} — rename one",
+                        first,
+                        page.rel_path,
+                        if page.route == "*" { "the '*' fallback (404)".to_string() } else { page.route.clone() }
+                    )));
+                }
+            }
+        }
+
+        // Build-id ranges are 1000 per unit above a shell base of 0, and the
+        // runtime mints its own ids from 1,000,000 — page index 999 would
+        // collide with the runtime floor. Nobody has a thousand pages; if you
+        // do, raise the runtime floor first.
+        if (pages.len() + 1) * SPA_UNIT_ID_STRIDE > 1_000_000 {
+            return Err(CompileError::SpaError(format!(
+                "{} pages exceeds the compiled id space ({} ids per page below the runtime's 1,000,000 floor)",
+                pages.len(),
+                SPA_UNIT_ID_STRIDE
+            )));
+        }
+
+        // The fragments dir mirrors the pages tree: prune fragments whose
+        // page no longer exists (watch-mode page removals, no-clean runs).
+        let fragments_root = self.config.output.join("components").join("vibe-spa");
+        let live: HashSet<String> = pages.iter().map(|p| p.rel_path.clone()).collect();
+        let mut existing = Vec::new();
+        Self::collect_page_files(&fragments_root, &self.config.skip_files, &mut existing);
+        for stale in existing {
+            let rel = stale
+                .strip_prefix(&fragments_root)
+                .unwrap()
+                .to_string_lossy()
+                .replace('\\', "/");
+            if !live.contains(&rel) {
+                let _ = fs::remove_file(&stale);
+            }
+        }
+
+        let order = spa::route_order(&pages);
+        let shell = spa::compose_shell(&pages, &order, hoisted.as_ref());
+        if self.verbose {
+            for note in &shell.notes {
+                println!("  spa: {}", note);
+            }
+        }
+
+        if self.config.source.join("index.html").exists() {
+            eprintln!(
+                "{}: SPA shell overwrites the compiled root index.html (source has its own index.html outside the pages tree)",
+                "Warning".yellow()
+            );
+        }
+
+        // The shell flows through the same component pipeline as pages so a
+        // hoisted layout is build-inlined (tagged wrappers + vibe-module
+        // scripts) instead of runtime-fetched piecemeal at boot.
+        let shell_processed = if hoisted.is_some() {
+            let processed = parser.process_html_with_cache(
+                &shell.html,
+                self.config.elements_as_is,
+                &self.config.reserved_elements,
+                self.config.components_as_is,
+                &self.config.components,
+                &self.component_cache,
+            );
+            let protected = crate::compiler::name_binding_protect::protect(&processed);
+            let tagged = crate::compiler::component_tagger::ComponentTagger::tag_components(
+                &protected,
+                &self.config.source,
+            )
+            .map_err(CompileError::SpaError)?;
+            if tagged.next_id > SPA_UNIT_ID_STRIDE {
+                return Err(CompileError::SpaError(format!(
+                    "the hoisted layout inlines {} components — more than the {} ids allotted to the shell",
+                    tagged.next_id, SPA_UNIT_ID_STRIDE
+                )));
+            }
+            tagged.html
+        } else {
+            shell.html
+        };
+        let shell_html = if self.config.minify {
+            minify_html(&shell_processed)
+        } else {
+            shell_processed
+        };
+        let shell_path = self.config.output.join("index.html");
+        atomic_write(&shell_path, &shell_html).map_err(|e| CompileError::WriteError {
+            path: shell_path.display().to_string(),
+            source: e,
+        })?;
+        // The shell rides the normal manifest pipeline like any page.
+        self.compiled_html.insert(shell_path, shell_html);
+
+        Ok(pages.len() + 1)
+    }
+
+    /// Regenerate the shell's manifest after a watch-mode recompose (the full
+    /// build gets it via generate_manifests; incremental recompiles target
+    /// only changed files, and the shell has no source counterpart to list).
+    /// Manifest yes, stamp no — same rule as the full pipeline.
+    pub(crate) fn generate_shell_manifest(&self) -> Result<(), CompileError> {
+        let shell_path = self.config.output.join("index.html");
+        let disk_html;
+        let html: &str = match self.compiled_html.get(&shell_path) {
+            Some(html) => html,
+            None => {
+                disk_html = fs::read_to_string(&shell_path).map_err(|e| CompileError::ReadError {
+                    path: shell_path.display().to_string(),
+                    source: e,
+                })?;
+                &disk_html
+            }
+        };
+        Self::generate_file_manifest(
+            html,
+            &shell_path,
+            &self.config.output,
+            "index.html",
+            self.verbose,
+            self.config.iterations_as_is,
+            self.config.components_as_is,
+            &self.config.source,
+            self.config.root.as_deref(),
+            &self.compute_global_constants(),
+            false,
+        )
+        .map_err(CompileError::SpaError)
+    }
+
+    fn extract_components(&self, content: &str) -> (usize, usize, Vec<String>) {
+        let mut internal = 0;
+        let mut external = 0;
+        let mut srcs = Vec::new();
+
+        // Simple regex-based extraction of <component src="..."> tags
+        let re = Regex::new(r#"<component[^>]+src\s*=\s*["']([^"']+)["']"#).unwrap();
+        for cap in re.captures_iter(content) {
+            if let Some(src) = cap.get(1) {
+                let src_str = src.as_str().to_string();
+                if src_str.starts_with("http://") || src_str.starts_with("https://") {
+                    external += 1;
+                } else {
+                    internal += 1;
+                }
+                srcs.push(src_str);
+            }
+        }
+
+        (internal, external, srcs)
+    }
+
+    fn build_component_relationships(&mut self, component_srcs: &[String]) -> Vec<(String, Vec<String>)> {
+        let mut relationships = Vec::new();
+        let mut visited = HashSet::new();
+
+        for src in component_srcs {
+            self.collect_component_children(src, &mut relationships, &mut visited);
+        }
+
+        relationships
+    }
+
+    fn collect_component_children(&mut self, component_src: &str, relationships: &mut Vec<(String, Vec<String>)>, visited: &mut HashSet<String>) {
+        if visited.contains(component_src) {
+            return;
+        }
+        visited.insert(component_src.to_string());
+
+        // Read component content
+        let content = if component_src.starts_with("http://") || component_src.starts_with("https://") {
+            match self.fetch_external_component_raw(component_src) {
+                Ok(c) => c,
+                Err(_) => return,
+            }
+        } else {
+            match self.resolve_component_path(component_src) {
+                Ok(path) => match fs::read_to_string(&path) {
+                    Ok(c) => c,
+                    Err(_) => return,
+                },
+                Err(_) => return,
+            }
+        };
+
+        // Extract immediate children
+        let children = self.extract_component_srcs(&content);
+
+        // Add this component and its children to relationships
+        relationships.push((component_src.to_string(), children.clone()));
+
+        // Recursively collect children's relationships
+        for child in children {
+            self.collect_component_children(&child, relationships, visited);
+        }
+    }
+
+
+    /// MIRROR_MODE: Copy file to output, preserving relative path
+    fn copy_file(&self, path: &Path, relative_path: &str) -> Result<(), CompileError> {
+        let output_path = self.get_output_path(path, relative_path)?;
+
+        fs::copy(path, &output_path).map_err(|e| CompileError::WriteError {
+            path: output_path.display().to_string(),
+            source: e,
+        })?;
+
+        Ok(())
+    }
+
+    /// Re-mirror specific source files under the components directory into the
+    /// output. The full build always mirrors components/ verbatim (see
+    /// process_directory_assets_only): runtime-fetched components —
+    /// `<component src="@[page.src]">` targets, iter-prop each-roots,
+    /// components_as_is — are served from that mirror at request time. Watch
+    /// mode calls this for every changed component so the mirror tracks edits
+    /// and deletions even when no page inlines the component (zero graph
+    /// dependents). Writes are atomic (same tmp+rename as compiled pages) so a
+    /// runtime fetch mid-copy never sees a torn file. Returns how many files
+    /// were copied.
+    pub fn mirror_component_files(&self, files: &[PathBuf]) -> Result<usize, CompileError> {
+        let mut copied = 0;
+        for path in files {
+            let relative = path.strip_prefix(&self.config.source).unwrap_or(path);
+            let output_path = self.config.output.join(relative);
+            if path.exists() {
+                if let Some(parent) = output_path.parent() {
+                    fs::create_dir_all(parent).map_err(|e| CompileError::WriteError {
+                        path: parent.display().to_string(),
+                        source: e,
+                    })?;
+                }
+                let contents = fs::read_to_string(path).map_err(|e| CompileError::ReadError {
+                    path: path.display().to_string(),
+                    source: e,
+                })?;
+                atomic_write(&output_path, &contents).map_err(|e| CompileError::WriteError {
+                    path: output_path.display().to_string(),
+                    source: e,
+                })?;
+                copied += 1;
+            } else if output_path.exists() {
+                fs::remove_file(&output_path).map_err(|e| CompileError::WriteError {
+                    path: output_path.display().to_string(),
+                    source: e,
+                })?;
+            }
+        }
+        Ok(copied)
+    }
+
+    /// Fetch components only for specific files (used in incremental compilation)
+    fn fetch_components_for_files(&mut self, files: &[PathBuf], parser: &HtmlParser) -> Result<(), CompileError> {
+        for html_file in files {
+            let content = match fs::read_to_string(html_file) {
+                Ok(c) => c,
+                Err(e) => {
+                    if self.verbose {
+                        eprintln!("  Warning: Failed to read {}: {}", html_file.display(), e);
+                    }
+                    continue;
+                }
+            };
+
+            // Transform custom tags to <component> tags
+            let transformed = parser.process_html(
+                &content,
+                self.config.elements_as_is,
+                &self.config.reserved_elements,
+                true, // components_as_is (don't inline, just transform)
+                &self.config.components,
+            );
+
+            // Extract and fetch components recursively
+            let components = self.extract_component_srcs(&transformed);
+            for component_src in components {
+                let mut visiting = std::collections::HashSet::new();
+                self.fetch_component_recursive(&component_src, parser, &mut visiting);
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Fetch and cache all components for inlining (separate from validation)
+    /// This recursively fetches all components (external and internal) and populates component_cache
+    fn fetch_all_components(&mut self, parser: &HtmlParser) -> Result<(), CompileError> {
+        // Find all HTML files in source directory (need to scan pages to find external component references)
+        let html_files = self.find_all_html_files(&self.config.source)?;
+
+        // Scan each HTML file for components
+        for html_file in html_files {
+            let content = match fs::read_to_string(&html_file) {
+                Ok(c) => c,
+                Err(e) => {
+                    if self.verbose {
+                        eprintln!("  Warning: Failed to read {}: {}", html_file.display(), e);
+                    }
+                    continue;
+                }
+            };
+
+            // Transform custom tags to <component> tags
+            let transformed = parser.process_html(
+                &content,
+                self.config.elements_as_is,
+                &self.config.reserved_elements,
+                true, // components_as_is (don't inline, just transform)
+                &self.config.components,
+            );
+
+            // Extract and fetch components recursively
+            let components = self.extract_component_srcs(&transformed);
+            for component_src in components {
+                let mut visiting = std::collections::HashSet::new();
+                self.fetch_component_recursive(&component_src, parser, &mut visiting);
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Recursively fetch a component and its nested components (for inlining).
+    /// Returns the fully inlined content (all nested components resolved).
+    ///
+    /// `visiting` tracks the chain of components currently being fetched. A
+    /// `<component src>` that points back into the chain is a cycle (direct
+    /// self-reference, or A→B→A) — those are valid runtime patterns (recursive
+    /// tree components bounded by data depth) but would expand infinitely at
+    /// compile time. Cycle references are escaped to `data-vibe-recursive-src`
+    /// in the cached content so the inliner's `src=` regex won't keep matching
+    /// them; `process_html_with_cache` restores the attribute name at the end
+    /// of compilation so the runtime sees a normal `<component src>` tag.
+    fn fetch_component_recursive(
+        &mut self,
+        component_src: &str,
+        parser: &HtmlParser,
+        visiting: &mut std::collections::HashSet<String>,
+    ) -> Option<String> {
+        // Normalize path: ensure it starts with / (unless it's a URL)
+        let normalized_src = if component_src.starts_with("http://") || component_src.starts_with("https://") {
+            component_src.to_string()
+        } else {
+            let without_prefix = component_src.trim_start_matches("./");
+            if without_prefix.starts_with('/') {
+                without_prefix.to_string()
+            } else {
+                format!("/{}", without_prefix)
+            }
+        };
+
+        // Return cached if already fetched and fully resolved
+        if let Some(cached) = self.component_cache.get(&normalized_src) {
+            return Some(cached.clone());
+        }
+
+        // Cycle: this component is already higher in the fetch chain. Don't
+        // recurse — the caller will leave the `<component src>` tag as-is and
+        // the runtime handles the recursion with real data bounds.
+        if visiting.contains(&normalized_src) {
+            return None;
+        }
+
+        // Fetch external or read internal component (raw content)
+        let content = if normalized_src.starts_with("http://") || normalized_src.starts_with("https://") {
+            match self.fetch_external_component_raw(&normalized_src) {
+                Ok(c) => c,
+                Err(e) => {
+                    if self.verbose {
+                        eprintln!("  Warning: Failed to fetch {}: {}", normalized_src, e);
+                    }
+                    return None;
+                }
+            }
+        } else {
+            match self.resolve_component_path(&normalized_src) {
+                Ok(path) => match fs::read_to_string(&path) {
+                    Ok(c) => c,
+                    Err(e) => {
+                        if self.verbose {
+                            eprintln!("  Warning: Failed to read component {}: {}", normalized_src, e);
+                        }
+                        return None;
+                    }
+                },
+                Err(e) => {
+                    if self.verbose {
+                        eprintln!("  Warning: {}", e);
+                    }
+                    return None;
+                }
+            }
+        };
+
+        // Transform custom tags in component (but keep component tags as-is for now)
+        let mut transformed = parser.process_html(
+            &content,
+            self.config.elements_as_is, // respect global config
+            &self.config.reserved_elements.clone(), // respect global config
+            true, // components_as_is = true (keep <component> tags for now so we can recursively resolve them)
+            &self.config.components,
+        );
+
+        // Mark this component as in-flight before recursing into its nested
+        // refs. Cycles (direct self-reference or A→B→A chains) are detected
+        // by the visiting check at the top of this function.
+        visiting.insert(normalized_src.clone());
+
+        // Recursively fetch and inline all nested components
+        let nested = self.extract_component_srcs(&transformed);
+        for nested_src in nested {
+            if let Some(nested_content) = self.fetch_component_recursive(&nested_src, parser, visiting) {
+                // Inline this nested component into the current component
+                transformed = parser.inline_single_component(&transformed, &nested_src, &nested_content);
+            }
+        }
+
+        visiting.remove(&normalized_src);
+
+        // Any `<component src>` still in `transformed` whose target is in the
+        // visiting chain (a cycle) didn't get inlined. Escape its `src=` so
+        // `inline_component_elements` won't keep re-expanding it forever when
+        // a page inlines this cached content. `process_html_with_cache`
+        // restores the attribute to plain `src=` at the end of compilation so
+        // the runtime fetches it normally.
+        for ancestor in visiting.iter() {
+            transformed = escape_recursive_src(&transformed, ancestor);
+        }
+        // Also escape direct self-references — a component pointing at itself
+        // never made it into `visiting` (the cycle check short-circuited
+        // before insertion), so handle it explicitly.
+        transformed = escape_recursive_src(&transformed, &normalized_src);
+
+        // Cache the fully resolved content
+        self.component_cache.insert(normalized_src.clone(), transformed.clone());
+
+        Some(transformed)
+    }
+
+    /// Validate that component filenames don't match reserved elements
+    fn validate_component_names(&self) -> Result<(), CompileError> {
+        let components_dir = self.config.components_path();
+
+        if !components_dir.exists() {
+            return Ok(()); // No components directory
+        }
+
+        let component_files = self.find_all_html_files(&components_dir)?;
+
+        for component_file in component_files {
+            let file_name = component_file
+                .file_stem()
+                .and_then(|s| s.to_str())
+                .unwrap_or("");
+
+            // Check if filename (case-sensitive) matches any reserved element
+            if self.config.reserved_elements.contains(&file_name.to_string()) {
+                let relative_path = component_file
+                    .strip_prefix(&self.config.source)
+                    .unwrap_or(&component_file);
+
+                return Err(CompileError::ReservedComponentName {
+                    component_name: file_name.to_string(),
+                    file_path: relative_path.display().to_string(),
+                });
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Validate HTML syntax for all files (controlled by validate flag)
+    fn validate_html_syntax(&self) -> Result<(), CompileError> {
+        // Find all HTML files in source directory
+        let html_files = self.find_all_html_files(&self.config.source)?;
+
+        for html_file in html_files {
+            let content = fs::read_to_string(&html_file).map_err(|e| CompileError::ReadError {
+                path: html_file.display().to_string(),
+                source: e,
+            })?;
+
+            // Validate HTML syntax
+            self.validate_html(&content, &html_file)?;
+        }
+
+        Ok(())
+    }
+
+    /// Fetch external component without caching (returns raw content)
+    fn fetch_external_component_raw(&self, url: &str) -> Result<String, String> {
+        match ureq::get(url).call() {
+            Ok(response) => response.into_string().map_err(|e| format!("Failed to read response body: {}", e)),
+            Err(ureq::Error::Status(code, response)) => Err(format!("HTTP {} - {}", code, response.status_text().to_string())),
+            Err(e) => Err(format!("Failed to fetch: {}", e)),
+        }
+    }
+
+    fn resolve_component_path(&self, component_src: &str) -> Result<PathBuf, String> {
+        // Normalize path (remove leading ./ or /)
+        let normalized = component_src.trim_start_matches("./").trim_start_matches('/');
+
+        // Try relative to source root
+        let path = self.config.source.join(normalized);
+        if path.exists() {
+            return Ok(path);
+        }
+
+        Err(format!("Component file not found: {}", component_src))
+    }
+
+    fn extract_component_srcs(&self, content: &str) -> Vec<String> {
+        let mut srcs = Vec::new();
+        // Match both <component src="..."> and <div class="component" src="...">
+        // After elements_as_is=false transform, <component> becomes <div class="component">
+        let re = Regex::new(r#"(?:<component|<div\s+class="component")[^>]+src\s*=\s*["']([^"']+)["']"#).unwrap();
+        for cap in re.captures_iter(content) {
+            if let Some(src) = cap.get(1) {
+                srcs.push(src.as_str().to_string());
+            }
+        }
+        srcs
+    }
+
+    fn find_all_html_files(&self, dir: &Path) -> Result<Vec<PathBuf>, CompileError> {
+        let mut html_files = Vec::new();
+        // Get output directory basename to skip nested directories with same name
+        let output_dir_name = self.config.output.file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("");
+        self.find_html_files_recursive(dir, &mut html_files, output_dir_name)?;
+        Ok(html_files)
+    }
+
+    fn find_html_files_recursive(&self, dir: &Path, files: &mut Vec<PathBuf>, output_dir_name: &str) -> Result<(), CompileError> {
+        if !dir.is_dir() {
+            return Ok(());
+        }
+
+        let entries = match fs::read_dir(dir) {
+            Ok(e) => e,
+            Err(_) => return Ok(()), // Skip directories we can't read
+        };
+
+        for entry in entries {
+            let entry = match entry {
+                Ok(e) => e,
+                Err(_) => continue,
+            };
+
+            let path = entry.path();
+            let file_name = entry.file_name();
+            let file_name_str = file_name.to_string_lossy();
+
+            // Skip specific directories/patterns (includes dotfiles via SKIP_FILES)
+            if should_skip_path(&path, &file_name_str, &self.config.skip_files) {
+                continue;
+            }
+
+            // Skip components directory during initial scan (we'll validate them when referenced)
+            if file_name_str == self.config.components {
+                continue;
+            }
+
+            // Skip nested directories with same name as output dir (from previous bad compilations)
+            if !output_dir_name.is_empty() && file_name_str == output_dir_name {
+                continue;
+            }
+
+            if path.is_dir() {
+                self.find_html_files_recursive(&path, files, output_dir_name)?;
+            } else if path.extension().and_then(|e| e.to_str()) == Some("html") {
+                files.push(path);
+            }
+        }
+
+        Ok(())
+    }
+
+    fn get_output_path(&self, path: &Path, relative_path: &str) -> Result<PathBuf, CompileError> {
+        let file_name = path.file_name().unwrap();
+
+        let output_path = if relative_path.is_empty() {
+            self.config.output.join(file_name)
+        } else {
+            let output_subdir = self.config.output.join(relative_path);
+            fs::create_dir_all(&output_subdir).map_err(|_| {
+                CompileError::CreateDirError(output_subdir.display().to_string())
+            })?;
+            output_subdir.join(file_name)
+        };
+
+        Ok(output_path)
+    }
+
+    fn validate_html(&self, content: &str, path: &Path) -> Result<(), CompileError> {
+        // Check 1: Unclosed attribute quotes
+        self.validate_quote_balance(content, path)?;
+
+        // Check 2: Tag balance (unclosed elements break slot extraction)
+        self.validate_tag_balance(content, path)
+    }
+
+    /// Quotes only matter inside tags and attribute values may span lines;
+    /// comments and raw content (script, style, pre) are skipped entirely.
+    fn validate_quote_balance(&self, content: &str, path: &Path) -> Result<(), CompileError> {
+        const RAW_CONTENT: &[&str] = &["script", "style", "pre"];
+
+        let bytes = content.as_bytes();
+        let mut i = 0;
+        let mut line = 1;
+
+        while i < bytes.len() {
+            if bytes[i] == b'\n' {
+                line += 1;
+                i += 1;
+            } else if bytes[i..].starts_with(b"<!--") {
+                match find_bytes(bytes, b"-->", i + 4) {
+                    Some(end) => {
+                        line += count_newlines(&bytes[i..end + 3]);
+                        i = end + 3;
+                    }
+                    None => break,
+                }
+            } else if bytes[i] == b'<'
+                && i + 1 < bytes.len()
+                && (bytes[i + 1].is_ascii_alphabetic() || bytes[i + 1] == b'/' || bytes[i + 1] == b'!')
+            {
+                let is_closing = bytes[i + 1] == b'/';
+                let name_start = i + if is_closing { 2 } else { 1 };
+                let name_end = bytes[name_start..]
+                    .iter()
+                    .position(|b| !(b.is_ascii_alphanumeric() || *b == b'-'))
+                    .map_or(bytes.len(), |p| name_start + p);
+                let name = content[name_start..name_end].to_ascii_lowercase();
+                i = name_end;
+
+                let mut quote: Option<(u8, usize)> = None;
+                let mut self_closing = false;
+                while i < bytes.len() {
+                    let b = bytes[i];
+                    if b == b'\n' {
+                        line += 1;
+                    }
+                    match quote {
+                        Some((q, _)) if b == q => quote = None,
+                        Some(_) => {}
+                        None => match b {
+                            b'"' | b'\'' => quote = Some((b, line)),
+                            b'>' => {
+                                self_closing = bytes[i - 1] == b'/';
+                                break;
+                            }
+                            _ => {}
+                        },
+                    }
+                    i += 1;
+                }
+
+                if let Some((_, quote_line)) = quote {
+                    return Err(CompileError::ValidationError {
+                        file: path.display().to_string(),
+                        line: quote_line,
+                        message: "Unclosed quote".to_string(),
+                    });
+                }
+                if i >= bytes.len() {
+                    break;
+                }
+                i += 1;
+
+                if !is_closing && !self_closing && RAW_CONTENT.contains(&name.as_str()) {
+                    let close = format!("</{}", name);
+                    match find_bytes_ci(bytes, close.as_bytes(), i) {
+                        Some(pos) => {
+                            line += count_newlines(&bytes[i..pos]);
+                            i = pos;
+                        }
+                        None => break, // unterminated raw block — tag balance reports it
+                    }
+                }
+            } else {
+                i += 1;
+            }
+        }
+
+        Ok(())
+    }
+
+    fn validate_tag_balance(&self, content: &str, path: &Path) -> Result<(), CompileError> {
+        const VOID_ELEMENTS: &[&str] = &[
+            "area", "base", "br", "col", "embed", "hr", "img", "input",
+            "link", "meta", "param", "source", "track", "wbr",
+        ];
+        // These are implicitly closed by the parser — don't require explicit close tags
+        const IMPLICIT_CLOSE: &[&str] = &[
+            "html", "head", "body", "p", "li", "dt", "dd", "option",
+            "optgroup", "tr", "td", "th", "thead", "tbody", "tfoot", "colgroup",
+        ];
+
+        // Strip comments, raw content blocks, and @[...] bindings before tag scanning
+        let stripped = Self::strip_for_tag_validation(content);
+
+        // Match any tag: opening, self-closing, or closing
+        let tag_re = Regex::new(r"</?([a-zA-Z][a-zA-Z0-9-]*)(?:\s[^>]*)?>").unwrap();
+
+        // Count opens vs closes per tag name; track line of first open for error reporting
+        let mut counts: HashMap<String, (i32, usize)> = HashMap::new();
+        for cap in tag_re.captures_iter(&stripped) {
+            let full = cap.get(0).unwrap().as_str();
+            let name = cap[1].to_lowercase();
+            if VOID_ELEMENTS.contains(&name.as_str()) || IMPLICIT_CLOSE.contains(&name.as_str()) {
+                continue;
+            }
+            if full.starts_with("</") {
+                counts.entry(name).and_modify(|(c, _)| *c -= 1);
+            } else if full.ends_with("/>") {
+                // self-closing — no balance change
+            } else {
+                let offset = cap.get(0).unwrap().start();
+                let line = stripped[..offset].matches('\n').count() + 1;
+                let entry = counts.entry(name).or_insert((0, line));
+                entry.0 += 1;
+            }
+        }
+
+        // Report the first unclosed tag (sorted by line for deterministic output)
+        let mut unclosed: Vec<(String, usize)> = counts.into_iter()
+            .filter(|(_, (count, _))| *count > 0)
+            .map(|(name, (_, line))| (name, line))
+            .collect();
+        unclosed.sort_by_key(|(_, line)| *line);
+
+        if let Some((name, line)) = unclosed.first() {
+            return Err(CompileError::ValidationError {
+                file: path.display().to_string(),
+                line: *line,
+                message: format!("Unclosed tag <{}>", name),
+            });
+        }
+
+        Ok(())
+    }
+
+    fn strip_for_tag_validation(content: &str) -> String {
+        // Strip HTML comments <!-- ... --> (includes Vibe syntax: each, if, else, /if, /each)
+        let comment_re = Regex::new(r"(?s)<!--.*?-->").unwrap();
+        let s = comment_re.replace_all(content, "");
+        // Strip @[...] reactive bindings (can contain < and > characters)
+        let binding_re = Regex::new(r"@\[[^\]]*\]").unwrap();
+        let s = binding_re.replace_all(&s, "");
+        // Strip content inside <script>, <style>, <pre> to avoid parsing embedded code as HTML
+        let raw_re = Regex::new(r"(?si)(<(?:script|style|pre)(?:\s[^>]*)?>).*?(</(?:script|style|pre)>)").unwrap();
+        raw_re.replace_all(&s, "$1$2").into_owned()
+    }
+
+    /// Copy an entire directory recursively
+    fn copy_directory(
+        &mut self,
+        dir: &Path,
+        relative_path: &str,
+        canonical_source: &Path,
+        stats: &mut CompileStats,
+    ) -> Result<(), CompileError> {
+        let entries = fs::read_dir(dir).map_err(|e| CompileError::ReadError {
+            path: dir.display().to_string(),
+            source: e,
+        })?;
+
+        for entry in entries.flatten() {
+            let path = entry.path();
+            let file_name = path.file_name().unwrap().to_str().unwrap();
+
+            // Skip files/directories matching skip patterns
+            if should_skip_path(&path, file_name, &self.config.skip_files) {
+                continue;
+            }
+
+            if path.is_dir() {
+                let new_relative = format!("{}/{}", relative_path, file_name);
+                self.copy_directory(&path, &new_relative, canonical_source, stats)?;
+            } else {
+                self.copy_file(&path, relative_path)?;
+                stats.files_copied += 1;
+                if let Some(ref mut logger) = self.logger {
+                    logger.log(&path, FileOperation::Copied, canonical_source);
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Copy node_modules as-is to output
+    fn copy_node_modules_as_is(&self) -> Result<(), CompileError> {
+        let src = self.config.working_dir.join("node_modules");
+        let dest = self.config.output.join("node_modules");
+
+        // Remove existing node_modules in output if it exists
+        if dest.exists() {
+            fs::remove_dir_all(&dest).map_err(|e| CompileError::WriteError {
+                path: dest.display().to_string(),
+                source: e,
+            })?;
+        }
+
+        // Copy recursively
+        copy_dir_recursive(&src, &dest)?;
+
+        Ok(())
+    }
+
+    /// Install production dependencies directly into output directory
+    fn copy_production_node_modules(&self) -> Result<(), CompileError> {
+        let pkg_manager = detect_package_manager(&self.config.working_dir)?;
+
+        if self.verbose {
+            println!("\n  Detected package manager: {}", pkg_manager);
+            println!("  Installing production dependencies to output...");
+        }
+
+        // 1. Copy package.json to output directory
+        let package_json_src = self.config.working_dir.join("package.json");
+        let package_json_dest = self.config.output.join("package.json");
+
+        fs::copy(&package_json_src, &package_json_dest).map_err(|e| CompileError::WriteError {
+            path: package_json_dest.display().to_string(),
+            source: e,
+        })?;
+
+        // 2. Copy lockfile if it exists (needed for reproducible installs)
+        let lockfile_name = match pkg_manager.as_str() {
+            "bun" => "bun.lockb",
+            "pnpm" => "pnpm-lock.yaml",
+            "yarn" => "yarn.lock",
+            "npm" => "package-lock.json",
+            _ => "",
+        };
+
+        if !lockfile_name.is_empty() {
+            let lockfile_src = self.config.working_dir.join(lockfile_name);
+            let lockfile_dest = self.config.output.join(lockfile_name);
+            if lockfile_src.exists() {
+                fs::copy(&lockfile_src, &lockfile_dest).ok();
+            }
+        }
+
+        // 3. Install production dependencies directly in output directory
+        run_command(&pkg_manager, &["install", "--production"], &self.config.output)?;
+
+        // 4. Cleanup: remove package.json and lockfile from output
+        fs::remove_file(&package_json_dest).ok();
+        if !lockfile_name.is_empty() {
+            let lockfile_dest = self.config.output.join(lockfile_name);
+            fs::remove_file(&lockfile_dest).ok();
+        }
+
+        if self.verbose {
+            println!("  Installed production dependencies to output");
+        }
+
+        Ok(())
+    }
+}
+
+/// Detect package manager from lockfiles
+fn detect_package_manager(dir: &Path) -> Result<String, CompileError> {
+    if dir.join("bun.lockb").exists() {
+        return Ok("bun".to_string());
+    }
+    if dir.join("pnpm-lock.yaml").exists() {
+        return Ok("pnpm".to_string());
+    }
+    if dir.join("yarn.lock").exists() {
+        return Ok("yarn".to_string());
+    }
+    if dir.join("package-lock.json").exists() {
+        return Ok("npm".to_string());
+    }
+
+    Err(CompileError::PackageManagerNotFound)
+}
+
+/// Run a package manager command
+fn run_command(pkg_manager: &str, args: &[&str], cwd: &Path) -> Result<(), CompileError> {
+    let output = Command::new(pkg_manager)
+        .args(args)
+        .current_dir(cwd)
+        .output()
+        .map_err(|e| CompileError::CommandError(format!("{} not found: {}", pkg_manager, e)))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(CompileError::CommandError(format!(
+            "{} {} failed: {}",
+            pkg_manager,
+            args.join(" "),
+            stderr
+        )));
+    }
+
+    Ok(())
+}
+
+/// Recursively copy a directory
+fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<(), CompileError> {
+    if !dest.exists() {
+        fs::create_dir_all(dest).map_err(|_| CompileError::CreateDirError(dest.display().to_string()))?;
+    }
+
+    for entry in fs::read_dir(src).map_err(|e| CompileError::ReadError {
+        path: src.display().to_string(),
+        source: e,
+    })? {
+        let entry = entry.map_err(|e| CompileError::ReadError {
+            path: src.display().to_string(),
+            source: e,
+        })?;
+        let path = entry.path();
+        let file_name = entry.file_name();
+        let dest_path = dest.join(&file_name);
+
+        if path.is_dir() {
+            // Cache Directory Tagging spec: a directory carrying a signed
+            // CACHEDIR.TAG (cargo target/, many build caches) declares itself
+            // regenerable and skippable for copy tools. A symlinked local
+            // package would otherwise drag gigabytes of build artifacts into
+            // the as-is node_modules copy.
+            if is_cachedir_tagged(&path) {
+                continue;
+            }
+            copy_dir_recursive(&path, &dest_path)?;
+        } else {
+            fs::copy(&path, &dest_path).map_err(|e| CompileError::WriteError {
+                path: dest_path.display().to_string(),
+                source: e,
+            })?;
+        }
+    }
+
+    Ok(())
+}
+
+fn is_cachedir_tagged(dir: &Path) -> bool {
+    fs::read(dir.join("CACHEDIR.TAG"))
+        .map(|bytes| bytes.starts_with(b"Signature: 8a477f597d28d172789f06886806bc55"))
+        .unwrap_or(false)
+}
+
+/// Basic HTML minification
+fn minify_html(html: &str) -> String {
+    let mut result = String::with_capacity(html.len());
+    let mut in_raw = false;
+    let mut last_was_space = false;
+
+    for line in html.lines() {
+        let trimmed = line.trim();
+
+        // <pre>, <script> and <style> carry significant whitespace and must
+        // survive minification verbatim: <pre> is literal text, while a JS
+        // `//` line comment or ASI in <script> breaks the moment its trailing
+        // newline is collapsed into a space (the comment swallows the rest of
+        // the script). Keep these blocks line-for-line, exactly as <pre> always
+        // did. The opening-tag line enters the block before we emit it; the
+        // closing-tag line leaves it (and collapses, which only tightens the
+        // bare `</pre>` / `</script>` / `</style>`).
+        if trimmed.contains("<pre") || trimmed.contains("<script") || trimmed.contains("<style") {
+            in_raw = true;
+        }
+        if trimmed.contains("</pre>") || trimmed.contains("</script>") || trimmed.contains("</style>") {
+            in_raw = false;
+        }
+
+        if in_raw {
+            result.push_str(line);
+            result.push('\n');
+            last_was_space = false;
+        } else {
+            // The line break preceding this line is whitespace: collapse it to a
+            // single space so attributes/text split across lines don't glue
+            // together (e.g. a multi-line <meta name=... content=...> tag).
+            // The >\s+< pass below re-tightens genuine tag boundaries.
+            if !last_was_space && !result.is_empty() {
+                result.push(' ');
+                last_was_space = true;
+            }
+            for c in trimmed.chars() {
+                if c.is_whitespace() {
+                    if !last_was_space {
+                        result.push(' ');
+                        last_was_space = true;
+                    }
+                } else {
+                    result.push(c);
+                    last_was_space = false;
+                }
+            }
+        }
+    }
+
+    // Collapse whitespace between tags to a SINGLE space — never delete it.
+    // Inter-element whitespace is significant for inline content: the browser
+    // (and the non-compiled runtime) render `<em>a</em> <em>b</em>` with a space,
+    // so dropping it (`><`) glued words onto preceding inline elements (the
+    // status-chip "💠Concussion" parity bug). One space matches both the browser's
+    // own collapsing and the non-minified/runtime output; where the space is
+    // insignificant (between block/table/list/head elements) the parser discards
+    // it anyway, exactly as it does for the non-minified newline.
+    let result = regex::Regex::new(r">\s+<")
+        .unwrap()
+        .replace_all(&result, "> <")
+        .to_string();
+
+    result.trim().to_string()
+}
+
+fn find_bytes(haystack: &[u8], needle: &[u8], from: usize) -> Option<usize> {
+    haystack[from..].windows(needle.len()).position(|w| w == needle).map(|p| p + from)
+}
+
+fn find_bytes_ci(haystack: &[u8], needle: &[u8], from: usize) -> Option<usize> {
+    haystack[from..].windows(needle.len()).position(|w| w.eq_ignore_ascii_case(needle)).map(|p| p + from)
+}
+
+fn count_newlines(bytes: &[u8]) -> usize {
+    bytes.iter().filter(|&&b| b == b'\n').count()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn minify_preserves_script_newlines_so_line_comments_dont_swallow_code() {
+        // A `//` line comment inside a component script relies on its trailing
+        // newline. If minify collapses newlines into spaces, the comment eats
+        // the rest of the script → SyntaxError at runtime (new Function).
+        let html = "<page>\n\
+            <script type=\"module\">\n\
+            \x20 const a = 1; // explain a\n\
+            \x20 // keep explaining\n\
+            \x20 const b = 2;\n\
+            </script>\n\
+            </page>";
+
+        let out = minify_html(html);
+
+        // The code after the comments must still be reachable, i.e. on its own
+        // line rather than glued behind the `//`.
+        let script = &out[out.find("<script").unwrap()..out.find("</script>").unwrap()];
+        assert!(
+            script.contains('\n'),
+            "script newlines were collapsed, // comment swallows following code: {script:?}"
+        );
+        assert!(out.contains("const b = 2"), "code after // comment lost: {out:?}");
+
+        // Surrounding HTML must still be minified (tag boundaries tightened).
+        assert!(out.contains("<page><script"), "non-script HTML not minified: {out:?}");
+    }
+
+    #[test]
+    fn minify_preserves_style_newlines() {
+        let html = "<page>\n\
+            <style>\n\
+            \x20 a { color: red; }\n\
+            \x20 b { color: blue; }\n\
+            </style>\n\
+            </page>";
+
+        let out = minify_html(html);
+        let style = &out[out.find("<style").unwrap()..out.find("</style>").unwrap()];
+        assert!(style.contains('\n'), "style newlines collapsed: {style:?}");
+    }
+
+    #[test]
+    fn atomic_write_replaces_content_without_leaving_tmp_files() {
+        let dir = std::env::temp_dir().join("vibe_atomic_write_test");
+        let _ = fs::remove_dir_all(&dir);
+        fs::create_dir_all(&dir).unwrap();
+        let target = dir.join("page.html");
+
+        atomic_write(&target, "first").unwrap();
+        assert_eq!(fs::read_to_string(&target).unwrap(), "first");
+
+        // Overwriting an existing file goes through the same tmp+rename path.
+        atomic_write(&target, "second, longer content").unwrap();
+        assert_eq!(fs::read_to_string(&target).unwrap(), "second, longer content");
+
+        let leftovers: Vec<String> = fs::read_dir(&dir)
+            .unwrap()
+            .filter_map(|e| e.ok())
+            .map(|e| e.file_name().to_string_lossy().into_owned())
+            .filter(|n| n != "page.html")
+            .collect();
+        assert!(leftovers.is_empty(), "temp artifacts left behind: {leftovers:?}");
+    }
+
+    // A minimal on-disk project: source with one page carrying a distinctive
+    // binding, empty components dir, output dir sibling. Returns (config, page
+    // source path, compiled page output path, manifest path).
+    // nodeModulesAsIs copies must skip cache-tagged directories (the Cache
+    // Directory Tagging spec: cargo target/, many build caches). A symlinked
+    // local package dragging its cargo target/ along turned a 15MB copy into
+    // gigabytes.
+    #[test]
+    fn as_is_copy_skips_cachedir_tagged_directories() {
+        let dir = std::env::temp_dir().join("vibe-cachedir-copy-test");
+        let _ = fs::remove_dir_all(&dir);
+        let src = dir.join("node_modules/pkg");
+        fs::create_dir_all(src.join("runtime")).unwrap();
+        fs::create_dir_all(src.join("build/target/release")).unwrap();
+        fs::write(src.join("index.js"), "export default 1;").unwrap();
+        fs::write(src.join("runtime/state.js"), "export const s = 1;").unwrap();
+        fs::write(
+            src.join("build/target/CACHEDIR.TAG"),
+            "Signature: 8a477f597d28d172789f06886806bc55\n",
+        )
+        .unwrap();
+        fs::write(src.join("build/target/release/artifact"), "big").unwrap();
+
+        let dest = dir.join("out/node_modules");
+        copy_dir_recursive(&dir.join("node_modules"), &dest).unwrap();
+
+        assert!(dest.join("pkg/index.js").exists());
+        assert!(dest.join("pkg/runtime/state.js").exists());
+        assert!(dest.join("pkg/build").exists());
+        assert!(!dest.join("pkg/build/target").exists(), "cache-tagged dir was copied");
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    // Watch mode re-runs compile_spa on any pages-tree change: an edited page
+    // re-transforms and the shell recomposes (title/head/route table), a
+    // removed page's fragment is pruned from the output mirror and its route
+    // leaves the table. Full-rerun semantics keep add/edit/remove one path.
+    #[test]
+    fn spa_recompile_syncs_fragments_shell_and_routes() {
+        let dir = std::env::temp_dir().join("vibe-spa-watch-test");
+        let _ = fs::remove_dir_all(&dir);
+        let source = dir.join("src");
+        fs::create_dir_all(source.join("pages")).unwrap();
+        fs::create_dir_all(source.join("components")).unwrap();
+        let page = |title: &str, body: &str| {
+            format!(
+                "<!DOCTYPE html>\n<html><head><title>{}</title></head>\n<body vibe-fouc>{}</body></html>\n",
+                title, body
+            )
+        };
+        fs::write(source.join("pages/index.html"), page("Home", "<h1>home</h1>")).unwrap();
+        fs::write(source.join("pages/about.html"), page("About", "<h1>about</h1>")).unwrap();
+
+        let config = Config {
+            source: source.clone(),
+            output: dir.join("out"),
+            _source_str: String::new(),
+            _output_str: String::new(),
+            components: "components".to_string(),
+            pages: "pages".to_string(),
+            _assets: String::new(),
+            root: None,
+            minify: false,
+            elements_as_is: true,
+            source_maps: false,
+            reserved_elements: Vec::new(),
+            skip_files: Vec::new(),
+            node_modules_as_is: false,
+            components_as_is: true,
+            runtime_as_is: false,
+            iterations_as_is: false,
+            no_clean: false,
+            fouc_as_is: false,
+            spa: true,
+            working_dir: dir.clone(),
+        };
+
+        let mut compiler = Compiler::new(config.clone(), false);
+        let mut parser = HtmlParser::new(config.components_path());
+        parser.load_elements().unwrap();
+        compiler.compile().unwrap();
+
+        let shell_path = config.output.join("index.html");
+        let fragment = config.output.join("components/vibe-spa/about.html");
+        let shell = fs::read_to_string(&shell_path).unwrap();
+        assert!(shell.contains("\"route\": \"/about\""));
+        assert!(shell.contains("<title>Home</title>"));
+        assert!(fragment.exists());
+
+        // Edited page: fragment re-transforms, shell recomposes with the new
+        // harvested title.
+        fs::write(source.join("pages/about.html"), page("Regenerated", "<h1>about v2</h1>")).unwrap();
+        compiler.compile_spa(&parser).unwrap();
+        let shell = fs::read_to_string(&shell_path).unwrap();
+        assert!(shell.contains("\"title\": \"Regenerated\""));
+        assert!(fs::read_to_string(&fragment).unwrap().contains("about v2"));
+
+        // Removed page: route leaves the table, orphan fragment is pruned.
+        fs::remove_file(source.join("pages/about.html")).unwrap();
+        compiler.compile_spa(&parser).unwrap();
+        let shell = fs::read_to_string(&shell_path).unwrap();
+        assert!(!shell.contains("\"route\": \"/about\""));
+        assert!(!fragment.exists());
+
+        let _ = fs::remove_dir_all(&dir);
+    }
+
+    fn manifest_test_project(name: &str) -> (Config, PathBuf, PathBuf, PathBuf) {
+        let dir = std::env::temp_dir().join(format!("vibe_{}_test", name));
+        let _ = fs::remove_dir_all(&dir);
+        let source = dir.join("src");
+        let output = dir.join("out");
+        fs::create_dir_all(source.join("components")).unwrap();
+        fs::write(
+            source.join("index.html"),
+            "<!doctype html>\n<html><head><title>t</title></head>\n\
+             <body vibe>\n<page-home><h1>@[uniqueMarker123]</h1></page-home>\n</body></html>\n",
+        )
+        .unwrap();
+
+        let config = Config {
+            source: source.clone(),
+            output: output.clone(),
+            _source_str: String::new(),
+            _output_str: String::new(),
+            components: "components".to_string(),
+            pages: "pages".to_string(),
+            _assets: String::new(),
+            root: None,
+            minify: false,
+            elements_as_is: false,
+            source_maps: false,
+            reserved_elements: Vec::new(),
+            skip_files: Vec::new(),
+            node_modules_as_is: false,
+            components_as_is: false,
+            runtime_as_is: false,
+            iterations_as_is: false,
+            no_clean: false,
+            fouc_as_is: false,
+            spa: false,
+            working_dir: dir.clone(),
+        };
+
+        let page_src = source.join("index.html");
+        let page_out = output.join("index.html");
+        let manifest = output.join("vibe-hyperspeed").join("index.html.manifest.js");
+        (config, page_src, page_out, manifest)
+    }
+
+    // The full build always mirrors components/ verbatim into the output —
+    // runtime-fetched components (`<component src="@[page.src]">`, iter-prop
+    // roots, components_as_is) are served from that mirror. Watch mode must
+    // keep the same contract: an edited component reaches the mirror even when
+    // NO page inlines it (zero dependents), and a deleted component leaves it.
+    #[test]
+    fn changed_component_is_remirrored_to_output() {
+        let (config, _page_src, _page_out, _manifest) = manifest_test_project("component_mirror");
+        let source_component = config.source.join("components").join("widget.html");
+        let mirrored = config.output.join("components").join("widget.html");
+        let nested_src = config.source.join("components").join("spa").join("pane.html");
+        let nested_out = config.output.join("components").join("spa").join("pane.html");
+        fs::write(&source_component, "<spa-widget>v1</spa-widget>\n").unwrap();
+
+        let mut compiler = Compiler::new(config, false);
+        compiler.compile().expect("compile should succeed");
+        assert_eq!(
+            fs::read_to_string(&mirrored).unwrap(),
+            "<spa-widget>v1</spa-widget>\n",
+            "sanity: full build mirrors the component"
+        );
+
+        // Edit the component — no page references it, so the dependency graph
+        // maps it to zero pages; the mirror must still track the change.
+        fs::write(&source_component, "<spa-widget>v2</spa-widget>\n").unwrap();
+        let copied = compiler
+            .mirror_component_files(&[source_component.clone()])
+            .expect("mirroring should succeed");
+        assert_eq!(copied, 1);
+        assert_eq!(
+            fs::read_to_string(&mirrored).unwrap(),
+            "<spa-widget>v2</spa-widget>\n",
+            "edited component did not reach the output mirror"
+        );
+
+        // A component created mid-session (parent dirs may not exist yet).
+        fs::create_dir_all(nested_src.parent().unwrap()).unwrap();
+        fs::write(&nested_src, "<spa-pane>new</spa-pane>\n").unwrap();
+        compiler
+            .mirror_component_files(&[nested_src.clone()])
+            .expect("mirroring a new nested component should succeed");
+        assert_eq!(fs::read_to_string(&nested_out).unwrap(), "<spa-pane>new</spa-pane>\n");
+
+        // Deleting the source removes the mirrored copy.
+        fs::remove_file(&source_component).unwrap();
+        compiler
+            .mirror_component_files(&[source_component])
+            .expect("mirroring a deletion should succeed");
+        assert!(!mirrored.exists(), "deleted component still present in the output mirror");
+    }
+
+    // The watcher race: another writer truncates/rewrites a compiled page on
+    // disk between our compile and our manifest pass. The manifest must be
+    // built from the HTML this compiler just produced in memory — never from a
+    // disk read-back — or a torn read yields a valid-but-empty manifest and the
+    // page hydrates to a blank screen.
+    #[test]
+    fn manifest_survives_output_corruption_between_compile_and_manifests() {
+        let (config, _page_src, page_out, manifest) =
+            manifest_test_project("manifest_memory_full");
+
+        let mut compiler = Compiler::new(config, false);
+        compiler.compile().expect("compile should succeed");
+        assert!(
+            fs::read_to_string(&page_out).unwrap().contains("uniqueMarker123"),
+            "sanity: compiled page carries the binding"
+        );
+
+        // Simulate the concurrent writer: the on-disk page is now a shell.
+        fs::write(&page_out, "<!doctype html>\n<html><head></head><body></body></html>\n").unwrap();
+
+        compiler.generate_manifests().expect("manifest generation should succeed");
+
+        let manifest_js = fs::read_to_string(&manifest).expect("manifest should exist");
+        assert!(
+            manifest_js.contains("uniqueMarker123"),
+            "manifest was built from the corrupted disk file instead of the in-memory compile output"
+        );
+    }
+
+    // Same property on the incremental watch path (generate_manifests_for_files),
+    // which is where the two-watcher race actually corrupted manifests.
+    #[test]
+    fn incremental_manifest_survives_output_corruption() {
+        let (config, page_src, page_out, manifest) =
+            manifest_test_project("manifest_memory_incremental");
+
+        let mut compiler = Compiler::new(config.clone(), false);
+        let mut parser = HtmlParser::new(config.components_path());
+        parser.load_elements().unwrap();
+
+        fs::create_dir_all(&config.output).unwrap();
+        compiler
+            .compile_specific_html_files(&[page_src.clone()], &parser)
+            .expect("incremental compile should succeed");
+
+        fs::write(&page_out, "<!doctype html>\n<html><head></head><body></body></html>\n").unwrap();
+
+        compiler
+            .generate_manifests_for_files(&[page_src])
+            .expect("incremental manifest generation should succeed");
+
+        let manifest_js = fs::read_to_string(&manifest).expect("manifest should exist");
+        assert!(
+            manifest_js.contains("uniqueMarker123"),
+            "incremental manifest was built from the corrupted disk file instead of the in-memory compile output"
+        );
+    }
+}