@ape-egg/vibe 2.1.22 → 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;
@@ -603,6 +669,11 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                         // 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)
@@ -619,6 +690,22 @@ 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
@@ -655,13 +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() {
+                                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);
@@ -776,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() && components_to_mirror.is_empty() {
+                        if html_files.is_empty() && asset_files.is_empty() && components_to_mirror.is_empty() && !spa_pages_changed {
                             continue;
                         }
 
@@ -803,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;
@@ -882,6 +987,32 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             }
                         }
 
+                        // 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,6 +19,7 @@ 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
@@ -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

@@ -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.22",
+  "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"
   },

package/runtime/component.js

@@ -1,4 +1,5 @@
 import { debugLog } from './debug.js';
+import { shouldCleanup } from './cleanup.js';
 import {
   PHASE_FETCH,
   PHASE_FETCH_CACHED,
@@ -305,6 +306,7 @@ export const liveComponentWrapper = (element) => {
 //   the removal pass when replaceWith drops the old wrapper.
 export const remountComponent = (el, src, debug = false) => {
   const wasFetching = pendingFetches.has(el);
+  const hadSrcAttr = el.hasAttribute('src');
   // Compare against the LATEST requested src: with a fetch in flight the src
   // attribute holds it (rapid navigation A→B→A must abort B, not no-op on A);
   // mounted and idle, the finalize-stashed value does.
@@ -314,9 +316,23 @@ export const remountComponent = (el, src, debug = false) => {
   if (src === current) return;
   abortComponentFetch(el);
   el.setAttribute('src', src);
-  // Pre-fetch element: the boot/observer processComponent pass that hasn't
-  // reached it yet will pick up the new value — nothing to redo.
-  if (el._vibeMountedSrc === undefined && !wasFetching) return;
+  // Pre-fetch element awaiting its initial processing pass: that pass reads
+  // the new value — nothing to redo. A declaration-form wrapper (bound src
+  // that resolved to nothing, carried on data-vibe-src with no src
+  // attribute) was invisible to that pass, so hydration owns its first
+  // fetch too — the observer doesn't watch attributes.
+  if (el._vibeMountedSrc === undefined && !wasFetching && hadSrcAttr) return;
+  processSingle(el, debug);
+};
+
+// Key-change remount (`key="@[page.path]"`): mount the CURRENT src fresh even
+// though it is unchanged. Only a mounted, idle wrapper has anything to redo —
+// with a fetch pending the incoming mount is already fresh (a src change in
+// the same flush started it), and an unmounted wrapper's first mount is owned
+// by the normal processing pass.
+export const forceRemount = (el, debug = false) => {
+  if (pendingFetches.has(el) || el._vibeMountedSrc === undefined) return;
+  el.setAttribute('src', el._vibeMountedSrc);
   processSingle(el, debug);
 };
 
@@ -542,8 +558,11 @@ const processSingle = (el, debug) => {
   let props = el._vibeRemountProps;
   if (!props) {
     props = {};
+    // `src` and `key` are the wrapper's own contract (what to mount / when to
+    // remount), and data-vibe-* attributes are runtime transport — none of
+    // them are authored props for the component.
     Array.from(el.attributes).forEach((attr) => {
-      if (attr.name !== 'src') {
+      if (attr.name !== 'src' && attr.name !== 'key' && !attr.name.startsWith('data-vibe-')) {
         props[attr.name] = attr.value;
       }
     });
@@ -697,6 +716,12 @@ const processSingle = (el, debug) => {
           // attribute — the DOM alone carries the knowledge across swaps.
           const srcBinding = el._vibeSrcBinding ?? el.getAttribute('data-vibe-src');
           if (srcBinding) newWrapper.setAttribute('data-vibe-src', srcBinding);
+          // The key binding and its last resolved value ride along the same
+          // way, so a later key change still finds what to compare against
+          // on the replacement wrapper.
+          const keyBinding = el._vibeKeyBinding ?? el.getAttribute('data-vibe-key');
+          if (keyBinding) newWrapper.setAttribute('data-vibe-key', keyBinding);
+          if (el._vibeMountedKey !== undefined) newWrapper._vibeMountedKey = el._vibeMountedKey;
           // Transfer iteration-prop registry ownership from the soon-to-be-
           // detached `<component src>` to the new wrapper. The detached element
           // would otherwise trigger releaseOrphanedIterationProps and free the
@@ -732,13 +757,37 @@ const processSingle = (el, debug) => {
           // renderAllConditionals/Iterations populated runtime data) is what
           // iterate.js's update path uses to re-evaluate inlined bindings on
           // each row update.
+          // The observer hydrates the inserted subtree in its NEXT batch —
+          // until then, selectors keyed on hydrated attributes (a name-bound
+          // <page @[page.name]> → page[pvp] rules) don't match and the
+          // content paints unstyled. Cover the gap with the same fouc
+          // contract pages use: hidden at insertion, revealed by the batch
+          // that parsed and hydrated this subtree.
+          newWrapper.setAttribute('vibe-fouc', '');
           el._vibeReplacedBy = newWrapper;
           el.replaceWith(newWrapper);
           debugLog(fromCache ? PHASE_FETCH_CACHED : PHASE_FETCH, src, debug);
 
+          // Build-inlined child components (compiled SPA fragments) arrive
+          // with tagged wrapper ids and vibe-module scripts — the compiled-
+          // document form. A fetched mount is the fourth delivery mode after
+          // boot, conditional branches, and iteration rows: run those
+          // scripts now so each child's component({...}) state registers
+          // under its build-tagged id and the _cN bindings hydrate.
+          executeCompiledComponentScriptsIn([newWrapper]);
+
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,
           // so the observer can find parents even inside conditional branches.
+          // Hydration can span multiple batches (nested fetched components,
+          // async scripts) with paints in between — reveal only when the
+          // subtree has settled (same predicate the page-level ready uses).
+          // A wrapper unmounted mid-hydration releases the hook.
+          const unfouc = window.$.on('afterDomMutation', () => {
+            if (newWrapper.isConnected && !shouldCleanup(newWrapper)) return;
+            newWrapper.removeAttribute('vibe-fouc');
+            unfouc();
+          });
         } else {
           // Element was detached before finalize ran (conditional unmounted
           // during fetch, parent removed, etc). Release any state component()

package/runtime/hydrate.js

@@ -1,6 +1,6 @@
 import { updateIteration } from './iterate.js';
 import { updateConditional, managedNodes } from './conditionals.js';
-import { isComponentWrapper, liveComponentWrapper, remountComponent } from './component.js';
+import { isComponentWrapper, liveComponentWrapper, remountComponent, forceRemount } from './component.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
 import { evalInScope, resolveCaseInsensitivePath } from './utils.js';
 import { RawHtml } from './raw-html.js';
@@ -91,13 +91,40 @@ export default (affected, state, manifest = {}, oldState = {}) => {
         // reparse rebuilds the knowledge from that attribute. A state change
         // landing inside the swap window still resolves through the
         // replacement chain.
+        // Keyed component (`<component src="@[page.src]" key="@[page.path]">`):
+        // a key change is a declared identity change — remount the mounted
+        // component even when the src is unchanged (param→param navigation on
+        // the same route). The first resolution just records the initial key;
+        // the mount itself is owned by the normal component pass.
+        if (attrName === 'key' && isComponentWrapper(element)) {
+          const live = liveComponentWrapper(element);
+          const newKey = attrValue.replace(BINDING_REGEX, (_, expr) =>
+            evalInScope(expr, effectiveState, live) ?? '',
+          );
+          live._vibeKeyBinding = attrValue;
+          const prevKey = live._vibeMountedKey;
+          live._vibeMountedKey = newKey;
+          if (prevKey !== undefined && newKey !== prevKey) forceRemount(live);
+          return;
+        }
+
         if (attrName === 'src' && isComponentWrapper(element)) {
           const live = liveComponentWrapper(element);
           const newSrc = attrValue.replace(BINDING_REGEX, (_, expr) =>
-            evalInScope(expr, effectiveState, live),
+            evalInScope(expr, effectiveState, live) ?? '',
           );
           live._vibeSrcBinding = attrValue;
-          remountComponent(live, newSrc);
+          if (newSrc) {
+            remountComponent(live, newSrc);
+          } else if (live.hasAttribute('src')) {
+            // Unresolved src mounts nothing (a no-match deep link leaves
+            // $.page.src unset): move the binding onto data-vibe-src — the
+            // established transport parse.js already reads — and drop the
+            // fetchable src, so component processing and cleanup treat the
+            // outlet as settled instead of fetching a stringified binding.
+            live.setAttribute('data-vibe-src', attrValue);
+            live.removeAttribute('src');
+          }
           return;
         }
 

package/runtime/index.js

@@ -571,6 +571,12 @@ const main = (s, config = {}, stringSelector = '') => {
     unmount: [],
   };
 
+  // The ready phase happens once. A listener registered after it fires
+  // immediately (parity with the late-safe $.ready promise) — late
+  // registration is the SPA norm, where fragment scripts run on mount,
+  // long after the shell booted.
+  let readyFired = false;
+
   // Page-scope 'unmount': the visitor actually leaving — pagehide (navigation
   // away, tab close). Deliberately NOT visibilitychange: a tab switch is not
   // an unmount, the visitor comes back. Inside a component script the same
@@ -689,6 +695,14 @@ const main = (s, config = {}, stringSelector = '') => {
   // snapshots or Object.keys($).
   Object.defineProperty($, 'on', {
     value: (event, callback) => {
+      if (event === 'ready' && readyFired) {
+        try {
+          callback();
+        } catch (error) {
+          console.error('[vibe] Error in ready hook:', error);
+        }
+        return () => {};
+      }
       if (hooks[event]) {
         hooks[event].push(callback);
       }
@@ -1233,6 +1247,7 @@ const main = (s, config = {}, stringSelector = '') => {
       cleanupExecuted = true;
 
       // Fire ready hook after cleanup completes
+      readyFired = true;
       hooks.ready.forEach((callback) => {
         try {
           callback();