@ape-egg/vibe 2.1.21 → 2.3.0

package/compiler/src/compiler/watcher.rs

@@ -426,6 +426,39 @@ fn exit_when_orphaned(lock_path: PathBuf) {
 #[cfg(not(unix))]
 fn exit_when_orphaned(_lock_path: PathBuf) {}
 
+/// A config change invalidates every piece of watcher state — dependency
+/// graph, compiler, parser, watch roots, output lock. The cleanest
+/// expression is a fresh start: release the lock and exec the same binary
+/// with the same argv, so CLI flag overrides re-apply with perfect parity.
+/// Same pid — a parent process watching this child never sees an exit.
+fn restart_with_fresh_config(lock: WatchLock) -> ! {
+    println!(
+        "{} package.json changed — restarting with fresh config",
+        "[watch]".cyan()
+    );
+    drop(lock);
+    let exe = std::env::current_exe()
+        .unwrap_or_else(|_| PathBuf::from(std::env::args().next().unwrap_or_default()));
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::CommandExt;
+        let err = std::process::Command::new(&exe).args(&args).exec();
+        eprintln!("{}: watcher restart failed: {}", "Error".red(), err);
+        std::process::exit(1);
+    }
+    #[cfg(not(unix))]
+    {
+        let code = std::process::Command::new(&exe)
+            .args(&args)
+            .status()
+            .ok()
+            .and_then(|status| status.code())
+            .unwrap_or(1);
+        std::process::exit(code);
+    }
+}
+
 /// Start watching for file changes
 pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn std::error::Error>> {
     // Held for the watcher's whole lifetime; a second watcher on the same
@@ -544,6 +577,12 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
     // cache keys against the same base.
     let canonical_source = config.source.canonicalize()
         .unwrap_or_else(|_| config.source.clone());
+    // Canonical pages root: notify events carry absolute paths, so a relative
+    // --cwd would never prefix-match without canonicalizing the base.
+    let canonical_pages = {
+        let pages = config.source.join(&config.pages);
+        pages.canonicalize().unwrap_or(pages)
+    };
 
     // Keep compiler and parser alive to reuse component cache across incremental compilations
     let mut watch_compiler = Compiler::new(config.clone(), false);
@@ -565,6 +604,19 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
 
     debouncer.watcher().watch(&config.source, RecursiveMode::Recursive)?;
 
+    // Hot config: package.json is the compiler's config file — a change to
+    // any vibe-compiler option (spa, minify, paths) takes effect live via a
+    // watcher self-restart. Watched explicitly: it can sit outside the source
+    // tree, and skip_files (which routinely lists package.json for copying)
+    // must not silence it. The raw baseline is compared on each event so
+    // formatting-only writes don't restart anything.
+    let config_file = config.working_dir.join("package.json");
+    let canonical_config_file = config_file.canonicalize().unwrap_or_else(|_| config_file.clone());
+    let config_baseline = Config::load(config.working_dir.clone());
+    if config_file.exists() {
+        debouncer.watcher().watch(&config_file, RecursiveMode::NonRecursive)?;
+    }
+
     loop {
         match rx.recv() {
             Ok(result) => {
@@ -575,6 +627,20 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
 
                         for event in events {
                             for path in &event.paths {
+                                // Config file first, before any filter: a changed
+                                // vibe-compiler section restarts the watcher in
+                                // place with the fresh config.
+                                let is_config_file = path
+                                    .canonicalize()
+                                    .map(|p| p == canonical_config_file)
+                                    .unwrap_or(*path == config_file);
+                                if is_config_file {
+                                    if Config::load(config.working_dir.clone()) != config_baseline {
+                                        restart_with_fresh_config(_watch_lock);
+                                    }
+                                    continue;
+                                }
+
                                 // Skip blacklisted files/directories (check entire path, not just filename)
                                 if is_path_blacklisted(path, &config.source, &config.skip_files) {
                                     continue;
@@ -598,6 +664,16 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                         // component plus the ancestors that inline it. Everything
                         // else stays cached and is reused.
                         let mut stale_component_keys: HashSet<String> = HashSet::new();
+                        // Changed component files to re-mirror into the output —
+                        // runtime-fetched components are served from that mirror,
+                        // so it must track every edit/deletion even when no page
+                        // inlines the component (zero graph dependents).
+                        let mut components_to_mirror: Vec<PathBuf> = Vec::new();
+                        // SPA mode: any pages-tree change (edit, add, delete) or a
+                        // component edit with page dependents re-runs the whole SPA
+                        // pass after this batch — fragments re-transform, the shell
+                        // recomposes, routes resync, orphans prune.
+                        let mut spa_pages_changed = false;
 
                         for path in &changed_paths {
                             // Skip files in output directory (avoid infinite loop)
@@ -614,12 +690,39 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             let relative_path = path.strip_prefix(&config.source)
                                 .unwrap_or(path);
 
+                            // SPA pages never take the MPA per-page path — the
+                            // batch-level SPA pass owns them. Deleted files can't
+                            // canonicalize; their event path is already absolute.
+                            if config.spa
+                                && path.extension().and_then(|e| e.to_str()) == Some("html")
+                                && canonical_path.starts_with(&canonical_pages)
+                            {
+                                if path.exists() {
+                                    println!("{} {} changed", "[watch]".cyan(), relative_path.display());
+                                } else {
+                                    println!("{} {} deleted", "[watch]".yellow(), relative_path.display());
+                                }
+                                spa_pages_changed = true;
+                                continue;
+                            }
+
                             // Check if it's a component
                             if path.starts_with(&config.source.join(&config.components)) {
                                 // Component changed - recompile all transitively dependent pages
                                 // Canonicalize to match how dependencies were stored (handles case sensitivity)
                                 let path_canonical = path.canonicalize().unwrap_or_else(|_| path.clone());
 
+                                // The output's components mirror tracks every change,
+                                // dependents or not: a component nothing inlines is
+                                // still fetched from the mirror at runtime
+                                // (`<component src="@[page.src]">`, iter-prop roots).
+                                if path.exists() {
+                                    println!("{} {} changed", "[watch]".cyan(), relative_path.display());
+                                } else {
+                                    println!("{} {} deleted", "[watch]".yellow(), relative_path.display());
+                                }
+                                components_to_mirror.push(path.clone());
+
                                 // Refresh this component's own dependency edges so a
                                 // newly-added <component src> (e.g. a child file created
                                 // mid-session) is learned. Without this the new child maps
@@ -639,15 +742,29 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                                     }
                                 }
 
-                                let dependent_pages = graph.get_all_dependent_pages(&path_canonical);
-                                if !dependent_pages.is_empty() {
-                                    println!("{} {} changed", "[watch]".cyan(), relative_path.display());
-
+                                let mut dependent_pages = graph.get_all_dependent_pages(&path_canonical);
+                                // SPA pages re-transform through the SPA pass, not
+                                // the MPA per-page compile (graph paths are
+                                // canonical — compare against the canonical root).
+                                let mut has_spa_dependents = false;
+                                if config.spa {
+                                    let (spa_pages, mpa_pages): (HashSet<_>, HashSet<_>) = dependent_pages
+                                        .into_iter()
+                                        .partition(|page| page.starts_with(&canonical_pages));
+                                    if !spa_pages.is_empty() {
+                                        spa_pages_changed = true;
+                                        has_spa_dependents = true;
+                                    }
+                                    dependent_pages = mpa_pages;
+                                }
+                                if !dependent_pages.is_empty() || has_spa_dependents {
                                     // Invalidate only the edited component and the
                                     // components whose cached inlined content embeds it
                                     // (its ancestors). Every other component stays cached,
                                     // so each affected page re-expands just the changed
-                                    // subtree instead of its whole component tree.
+                                    // subtree instead of its whole component tree. The
+                                    // SPA pass re-expands through the same cache, so
+                                    // spa-dependent pages need this too.
                                     for stale in graph.get_all_dependent_components(&path_canonical) {
                                         if let Some(key) = component_cache_key(&stale, &canonical_source) {
                                             stale_component_keys.insert(key);
@@ -762,7 +879,7 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             }
                         }
 
-                        if html_files.is_empty() && asset_files.is_empty() {
+                        if html_files.is_empty() && asset_files.is_empty() && components_to_mirror.is_empty() && !spa_pages_changed {
                             continue;
                         }
 
@@ -789,22 +906,24 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                         let mut manifest_stats_result = None;
                         let mut had_errors = false;
 
+                        // Drop only the stale component caches (edited components +
+                        // their inlining ancestors); unchanged components are reused.
+                        // A page-only edit invalidates nothing here — its components
+                        // are still valid — so the whole cache is reused as-is. Runs
+                        // before BOTH the per-page compile and the SPA pass: either
+                        // may re-expand through this cache.
+                        let invalidated = watch_compiler.invalidate_components(&stale_component_keys);
+                        if invalidated > 0 {
+                            println!("{} {} component{} re-expanded, {} reused from cache",
+                                "↻".cyan(),
+                                invalidated,
+                                if invalidated == 1 { "" } else { "s" },
+                                watch_compiler.cached_component_count(),
+                            );
+                        }
+
                         // Compile HTML files
                         if !html_files.is_empty() {
-                                // Drop only the stale component caches (edited components +
-                                // their inlining ancestors); unchanged components are reused.
-                                // A page-only edit invalidates nothing here — its components
-                                // are still valid — so the whole cache is reused as-is.
-                                let invalidated = watch_compiler.invalidate_components(&stale_component_keys);
-                                if invalidated > 0 {
-                                    println!("{} {} component{} re-expanded, {} reused from cache",
-                                        "↻".cyan(),
-                                        invalidated,
-                                        if invalidated == 1 { "" } else { "s" },
-                                        watch_compiler.cached_component_count(),
-                                    );
-                                }
-
                                 match watch_compiler.compile_specific_html_files(&html_files, &parser) {
                                     Ok(stats) => {
                                         total_stats.files_compiled = stats.files_compiled;
@@ -851,6 +970,49 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             }
                         }
 
+                        // Keep the output's components mirror in sync — changed
+                        // components reach it even with zero dependent pages, and
+                        // deleted ones leave it (see mirror_component_files).
+                        if !components_to_mirror.is_empty() && !had_errors {
+                            match watch_compiler.mirror_component_files(&components_to_mirror) {
+                                Ok(copied) => {
+                                    total_stats.files_copied += copied;
+                                }
+                                Err(e) => {
+                                    eprintln!("{}: {}", "Error".red(), e);
+                                    eprintln!("Fix the errors and save to retry.");
+                                    println!();
+                                    had_errors = true;
+                                }
+                            }
+                        }
+
+                        // SPA pass: re-transform fragments, recompose the shell,
+                        // resync the route table, prune orphans, refresh the
+                        // shell's manifest.
+                        if spa_pages_changed && !had_errors {
+                            match watch_compiler.compile_spa(&parser) {
+                                Ok(count) => {
+                                    if !config.runtime_as_is {
+                                        if let Err(e) = watch_compiler.generate_shell_manifest() {
+                                            eprintln!("{}: Shell manifest failed: {}", "Warning".yellow(), e);
+                                        }
+                                    }
+                                    println!("{} Recompiled SPA ({} fragment{} + shell)",
+                                        "✓".green(),
+                                        count - 1,
+                                        if count == 2 { "" } else { "s" }
+                                    );
+                                }
+                                Err(e) => {
+                                    eprintln!("{}: {}", "Error".red(), e);
+                                    eprintln!("Fix the errors and save to retry.");
+                                    println!();
+                                    had_errors = true;
+                                }
+                            }
+                        }
+
                         if !had_errors {
                             // Show what was updated
                             if total_stats.files_compiled > 0 {

package/compiler/src/config.rs

@@ -48,6 +48,19 @@ pub struct VibeCompilerConfig {
     pub no_clean: bool,
     #[serde(default)]
     pub fouc_as_is: bool,
+    #[serde(default, deserialize_with = "deserialize_spa")]
+    pub spa: bool,
+}
+
+// "spa": true is a boolean today; the future per-page selection form is an
+// object. Parse tolerantly so a newer config never silently resets the whole
+// vibe-compiler section to defaults on an older compiler.
+fn deserialize_spa<'de, D: serde::Deserializer<'de>>(deserializer: D) -> Result<bool, D::Error> {
+    Ok(match serde_json::Value::deserialize(deserializer)? {
+        serde_json::Value::Bool(enabled) => enabled,
+        serde_json::Value::Object(_) => true,
+        _ => false,
+    })
 }
 
 fn default_source() -> String { "./".to_string() }
@@ -105,11 +118,12 @@ impl Default for VibeCompilerConfig {
             iterations_as_is: false,
             no_clean: false,
             fouc_as_is: false,
+            spa: false,
         }
     }
 }
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq)]
 pub struct Config {
     pub source: PathBuf,
     pub output: PathBuf,
@@ -130,12 +144,19 @@ pub struct Config {
     pub iterations_as_is: bool,
     pub no_clean: bool,
     pub fouc_as_is: bool,
+    pub spa: bool,
     pub working_dir: PathBuf,
 }
 
 impl Config {
     /// Load config from package.json, or use defaults if not found
     pub fn load(working_dir: PathBuf) -> Self {
+        // A relative --cwd must become absolute HERE: every derived path
+        // (source, output, pages) joins from working_dir, and downstream
+        // strip_prefix against filesystem-event paths (always absolute)
+        // otherwise fails — in watch mode that once routed a manifest write
+        // and a stamped page INTO the source tree.
+        let working_dir = working_dir.canonicalize().unwrap_or(working_dir);
         let package_path = working_dir.join("package.json");
 
         let config = if package_path.exists() {
@@ -185,6 +206,7 @@ impl Config {
             iterations_as_is: config.iterations_as_is,
             no_clean: config.no_clean,
             fouc_as_is: config.fouc_as_is,
+            spa: config.spa,
             working_dir,
         }
     }
@@ -202,6 +224,24 @@ impl Config {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn parse(json: &str) -> VibeCompilerConfig {
+        serde_json::from_str(json).unwrap()
+    }
+
+    #[test]
+    fn spa_parses_bool_and_tolerates_the_future_object_form() {
+        assert!(!parse(r#"{}"#).spa);
+        assert!(parse(r#"{"spa": true}"#).spa);
+        assert!(!parse(r#"{"spa": false}"#).spa);
+        // Future per-page selection form must not break older compilers.
+        assert!(parse(r#"{"spa": {"pages": ["docs"]}}"#).spa);
+    }
+}
+
 pub fn init_config(working_dir: &PathBuf) -> Result<(), ConfigError> {
     let package_path = working_dir.join("package.json");
 

package/compiler/src/main.rs

@@ -19,13 +19,14 @@ struct ConfigOverrides {
     components_as_is: bool,
     runtime_as_is: bool,
     iterations_as_is: bool,
+    spa: bool,
 }
 
 /// Vibe Compiler - Compiles Vibe source files into optimized output
 #[derive(ClapParser, Debug)]
 #[command(name = "vibe-compile")]
 #[command(author = "Kim Korte")]
-#[command(version = "1.6.1")]
+#[command(version)]
 #[command(about = "Compiles Vibe source files into optimized output")]
 struct Args {
     /// Working directory (defaults to current directory)
@@ -87,6 +88,10 @@ struct Args {
     /// Keep FOUC prevention class/attribute in compiled output
     #[arg(long, name = "fouc-as-is")]
     fouc_as_is: bool,
+
+    /// Compile the pages tree to SPA output: fragments + route table + shell
+    #[arg(long)]
+    spa: bool,
 }
 
 fn main() {
@@ -127,6 +132,7 @@ fn main() {
     let original_components_as_is = config.components_as_is;
     let original_runtime_as_is = config.runtime_as_is;
     let original_iterations_as_is = config.iterations_as_is;
+    let original_spa = config.spa;
 
     // Track overrides for verbose output
     let mut overrides = ConfigOverrides::default();
@@ -165,6 +171,10 @@ fn main() {
     if args.fouc_as_is {
         config.fouc_as_is = true;
     }
+    if args.spa {
+        overrides.spa = !original_spa;
+        config.spa = true;
+    }
 
     if args.verbose {
         println!("{}", format!("Vibe Compiler v{}", env!("CARGO_PKG_VERSION")).cyan().bold());
@@ -228,6 +238,7 @@ fn main() {
         println!("  {}: {}", format!("{:<16}", "skipFiles").cyan(), format_value_no_flag(format_list_preview(&config.skip_files)));
         println!("  {}: {}", format!("{:<16}", "source").cyan(), format_value_no_flag(&config._source_str));
         println!("  {}: {}", format!("{:<16}", "sourceMaps").cyan(), format_bool_with_flag(config.source_maps, overrides.source_maps, original_source_maps));
+        println!("  {}: {}", format!("{:<16}", "spa").cyan(), format_bool_with_flag(config.spa, overrides.spa, original_spa));
         println!();
     } else {
         // Show version in non-verbose mode

package/index.js

@@ -8,7 +8,7 @@ let vibeInstance = null;
 let resolveInstanceReady = null;
 
 const createVibeInstance = () => ({
-  _pendingListeners: { afterUpdate: [], afterDomMutation: [], ready: [] },
+  _pendingListeners: { afterUpdate: [], afterDomMutation: [], ready: [], unmount: [] },
   // Promise that resolves when the real $.ready resolves post-boot. Lets
   // consumers holding the pre-boot placeholder (e.g. tests awaiting
   // `window.$.ready` before boot has replaced $ with the reactive proxy)
@@ -31,10 +31,24 @@ const createVibeInstance = () => ({
   }
 });
 
+// Shallow, key-level defaults: set only keys `target` does not have yet.
+// This is what "initial state, declared again" means once the app is live —
+// a re-mounted SPA page fragment's vibe({ ... }) seeds on first mount and
+// never clobbers live state after (vibe() state is app-lifetime; per-visit
+// state belongs in a component()).
+export const applyDefaults = (target, state) => {
+  for (const key in state) {
+    if (!(key in target)) target[key] = state[key];
+  }
+  return target;
+};
+
 const vibe = (state = {}, config, targetSelector) => {
   if (isBooted()) {
-    // Already booted - merge state into live proxy
-    Object.assign(window.$, state);
+    // Already booted: initial state declared late seeds missing keys only —
+    // on a fresh document load this branch never runs, so MPA behavior is
+    // byte-identical.
+    applyDefaults(window.$, state);
     return window.$;
   }
 

package/llms.txt

@@ -214,10 +214,39 @@ This makes vibe usable as a "sprinkle of reactivity" library: paste a snippet in
 $.on('ready', () => {});                  // once, after initial parse + hydrate + components mounted
 $.on('afterUpdate', (cur, prev) => {});   // every state change (batched per microtask)
 $.on('afterDomMutation', () => {});       // after every MutationObserver batch
+$.on('unmount', () => {});                // scope-resolved teardown: in a component script, fires when
+                                          // THAT component unmounts; at page level, fires on pagehide
 ```
 
 Also: `await $.ready` resolves after boot, useful when calling code captured `window.$` before vibe finished initializing.
 
+## SPA Routing (`@ape-egg/vibe/spa`)
+
+A standalone router maintaining `$.page = { path, route, params, src }`; a reactive component src is the route outlet:
+
+```html
+<script type="module">
+  import vibe from '@ape-egg/vibe';
+  import { setupSpa, resolve } from '@ape-egg/vibe/spa';
+
+  const routes = [
+    { route: '/brawlers/:index', src: '/components/brawler.html', title: 'Brawler' }, // :param = one segment
+    { route: '/docs/:rest*',     src: '/components/docs.html' },                      // trailing :name* = zero or more
+    { route: '/',                src: '/components/home.html', title: 'Home' },
+    { route: '*',                src: '/components/lost.html' },                      // no-match fallback (deep links/popstate only)
+  ];
+
+  window.$ = vibe({ page: resolve(location, routes) ?? {} });
+  setupSpa({ routes }); // returns { navigate, dispose }
+</script>
+
+<component src="@[page.src]"></component>
+```
+
+Rules: tables are pre-sorted most-specific-first, first match wins. Clicks are claimed only for same-origin, unmodified, untargeted links whose pathname matches a real route (`'*'` never claims) — everything else navigates natively, so mixed MPA/SPA output works. Route titles swap `document.title`. `resolve(location, routes)` is pure. A custom `onNavigate` makes it a pure router without Vibe.
+
+State semantics under SPA: `vibe()` state is app-lifetime, `component()` state is mount-lifetime (resets per visit). `@ape-egg/vibe/defaults` is the vibe entry with defaults semantics — already booted, it sets only keys that don't exist yet on `$`, so re-running page scripts never clobber live state. The compiler's SPA mode (`"spa": true` in `vibe-compiler` config, or `--spa`) compiles an MPA `pages/` tree into page fragments under `/components/vibe-spa/`, a generated route table, and a composed `/index.html` shell wired to this router — deploy with one rewrite: every route → `/index.html`.
+
 ## Special Attributes
 
 ### vibe-fouc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.1.21",
+  "version": "2.3.0",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
@@ -10,6 +10,7 @@
     "./boot": "./boot.js",
     "./component": "./component.js",
     "./hot-module-refresh": "./hot-module-refresh.js",
+    "./spa": "./spa.js",
     "./runtime": "./runtime/index.js",
     "./compiler": "./compiler/bin/vibe-compile.js"
   },