@ape-egg/vibe 2.1.21 → 2.3.0

package/compiler/src/compiler/compile.rs

@@ -281,6 +281,8 @@ pub enum CompileError {
         component_name: String,
         file_path: String,
     },
+    #[error("SPA mode: {0}")]
+    SpaError(String),
 }
 
 pub struct CompileStats {
@@ -695,6 +697,13 @@ impl Compiler {
         // 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)
@@ -912,6 +921,7 @@ impl Compiler {
         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();
 
@@ -956,6 +966,7 @@ impl Compiler {
                     &source_root,
                     manifest_root.as_deref(),
                     &global_constants,
+                    !(spa && relative_path == "index.html"),
                 ) {
                     Ok(()) => true,
                     Err(e) => {
@@ -992,6 +1003,7 @@ impl Compiler {
         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;
@@ -1047,13 +1059,22 @@ impl Compiler {
         // - 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.
-        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))?;
+        //
+        // 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(())
     }
@@ -1133,6 +1154,7 @@ impl Compiler {
         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();
@@ -1162,8 +1184,10 @@ impl Compiler {
                     }
                 };
 
-                // Try to generate manifest for this file (skip on error)
-                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) {
+                // 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 {
@@ -1229,6 +1253,12 @@ impl Compiler {
                     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()
@@ -1413,6 +1443,214 @@ impl Compiler {
         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()
+            )));
+        }
+
+        let mut 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 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 tagged =
+                crate::compiler::component_tagger::ComponentTagger::tag_components(
+                    &protected,
+                    &self.config.source,
+                )
+                .map_err(CompileError::SpaError)?;
+            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);
+        }
+
+        // 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);
+        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()
+            );
+        }
+
+        let shell_html = if self.config.minify {
+            minify_html(&shell.html)
+        } else {
+            shell.html
+        };
+        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;
@@ -1493,6 +1731,47 @@ impl Compiler {
         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 {
@@ -2165,6 +2444,14 @@ fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<(), CompileError> {
         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 {
@@ -2177,6 +2464,12 @@ fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<(), CompileError> {
     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());
@@ -2328,6 +2621,111 @@ mod tests {
     // 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);
@@ -2361,6 +2759,7 @@ mod tests {
             iterations_as_is: false,
             no_clean: false,
             fouc_as_is: false,
+            spa: false,
             working_dir: dir.clone(),
         };
 
@@ -2370,6 +2769,57 @@ mod tests {
         (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

package/compiler/src/compiler/mod.rs

@@ -1,4 +1,5 @@
 pub mod compile;
+pub mod spa;
 mod state_extractor;
 mod manifest_builder;
 mod value_stamper;