@ape-egg/vibe 2.1.19 → 2.1.21

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [2.1.21] - 2026-07-01
+
+### Fixed
+
+- **An orphaned `--watch` compiler held its lock forever, blocking every future watch on the same output** (`compiler/bin/vibe-compile.js`, `compiler/src/compiler/watcher.rs`, compiler 2.0.2) — the watch lock added below is only released on clean shutdown (Drop), but the compiler is a native child spawned by the `vibe-compile.js` wrapper, and killing the wrapper (Ctrl+C, a dev server's `child.kill()`, a process manager) left that child alive as an orphan still holding the lock — so the next `--watch` exited loudly naming a holder pid that was long gone. Two coordinated fixes close both escape routes: **(1)** the wrapper now forwards `SIGINT`/`SIGTERM`/`SIGHUP` and its own `exit` to the spawned child (`wireLifecycle`), so a graceful kill of the wrapper unwinds the watcher's Drop and frees the lock normally; **(2)** for the ungraceful case (`SIGKILL`, a crashed parent) where no signal is forwarded, the watcher polls its own parent pid on a background thread (`exit_when_orphaned`, unix-only) and, the moment it's reparented to init/a reaper — the unambiguous orphan signal — removes its lockfile and `process::exit`s, since `exit` skips Drop. Together they guarantee a dead owner never leaves a lock behind, complementing the stale-lock stealing the next watcher already does.
+- **Concurrent compilers corrupted hyperspeed manifests → pages hydrated blank with no errors** (`compiler/src/compiler/compile.rs`, `compiler/src/compiler/watcher.rs`, compiler 2.0.1 → 2.0.2) — manifest generation re-read each compiled page **from disk** after writing it, so when two `vibe compile --watch` processes shared one output directory (a leaked dev-server session next to a live one), one watcher's manifest pass could read a page the other was mid-rewrite. html5ever parses the torn prefix into a well-formed shell, producing a *valid but content-less* manifest that doesn't match its HTML — hydration mounts nothing, `vibe-fouc` never releases, and the page renders blank with zero console errors (observed in Battle Brawlers: a random subset of pages broke on every save of a widely-used component). Three-layer fix: **(1)** the compiler keeps each page's compiled HTML in memory (`Compiler.compiled_html`) and both manifest passes (`generate_manifests`, `generate_manifests_for_files`) build from those exact bytes — disk is only a fallback for pages the running compiler never produced (no-clean leftovers); **(2)** compiled HTML, stamped HTML, and manifests are written atomically (same-directory pid-tagged temp file + `rename`) so no reader — dev server, browser, or another process — can ever observe a partial file; **(3)** `watch` takes a per-output-directory lockfile (OS temp dir, keyed by canonicalized output path, holding the owner pid): a second watcher on the same output now exits loudly naming the holder instead of silently double-compiling and racing, and a lock whose process is dead (Ctrl+C/SIGTERM never unwind) is stolen. Tests: `compile.rs` (`manifest_survives_output_corruption_between_compile_and_manifests`, `incremental_manifest_survives_output_corruption`, `atomic_write_replaces_content_without_leaving_tmp_files`), `watcher.rs` (`second_watch_lock_on_same_output_fails_while_held`, `stale_lock_from_dead_process_is_stolen`, `locks_on_different_outputs_do_not_conflict`).
+
+## [2.1.20] - 2026-06-25
+
+### Added
+
+- **`@ape-egg/vibe/hot-module-refresh` — transport-agnostic browser HMR client** (`hot-module-refresh.js` (new), exported from `package.json`) — the surgical-HMR "brain" that reconciles a code edit into the live DOM instead of reloading the page is extracted out of `vite-plugin-vibe` into a standalone flat module the vibe package now exports. It's a *soft dependency*: nothing in the runtime imports it and it imports nothing from the runtime, depending only on the public `window.$` surface (`reconcile` / `renderComponent` / `clearComponentCache`), so a plain static server can serve it as-is — no bundler, no Vite. A transport adapter wires its channel to the brain through a single seam, `setupHotModuleRefresh({ debug, subscribe })`, where `subscribe` delivers two callbacks: `componentUpdate(path)` — re-fetch a changed component template and, for each live instance, reconcile surgically when its scripts are unchanged or re-mount otherwise (runtime mode only, since compiled output inlines components into pages) — and `pageUpdate(payload)` — re-fetch the current page and reconcile the `[vibe]` root (mode-agnostic; raw and compiled pages reconcile the same way). This lets the Vite plugin and any other dev transport share one HMR implementation. Tests: `e2e-runtime/hot-module-refresh.html`, `tests/e2e/hot-module-refresh.spec.js`.
+
 ## [2.1.19] - 2026-06-25
 
 ### Fixed

package/compiler/bin/vibe-compile.js

@@ -35,6 +35,16 @@ const getPlatformBinary = () => {
   return binary;
 };
 
+// The wrapper is what gets killed (Ctrl+C, a dev server's child.kill(), a
+// process manager) — without forwarding, the compiler child survives as an
+// orphan whose watch lock blocks every future `--watch` on the same output.
+const wireLifecycle = (child) => {
+  ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach((signal) =>
+    process.on(signal, () => child.kill(signal)),
+  );
+  process.on('exit', () => child.kill());
+};
+
 const run = () => {
   const binary = getPlatformBinary();
   const binaryPath = join(nativeDir, binary);
@@ -74,6 +84,7 @@ const run = () => {
       cwd: srcDir,
       stdio: 'inherit',
     });
+    wireLifecycle(cargo);
 
     cargo.on('error', (err) => {
       if (err.code === 'ENOENT') {
@@ -95,6 +106,7 @@ const run = () => {
   const child = spawn(binaryPath, userArgs, {
     stdio: 'inherit',
   });
+  wireLifecycle(child);
 
   child.on('error', (err) => {
     console.error('Failed to run vibe-compiler:', err.message);

package/compiler/src/Cargo.lock

@@ -1599,7 +1599,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "vibe-compiler"
-version = "2.0.1"
+version = "2.0.2"
 dependencies = [
  "clap",
  "colored",

package/compiler/src/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vibe-compiler"
-version = "2.0.1"
+version = "2.0.2"
 edition = "2021"
 description = "Vibe framework compiler - compiles Vibe source files into optimized output"
 authors = ["Kim Korte"]

package/compiler/src/compiler/compile.rs

@@ -39,6 +39,17 @@ fn manifest_url_path(relative_path: &str, root: Option<&str>) -> String {
         .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.
@@ -544,6 +555,11 @@ pub struct Compiler {
     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 {
@@ -555,6 +571,7 @@ impl Compiler {
             logger,
             unique_components: HashSet::new(),
             component_cache: HashMap::new(),
+            compiled_html: HashMap::new(),
         }
     }
 
@@ -898,6 +915,7 @@ impl Compiler {
         // 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| {
@@ -911,13 +929,24 @@ impl Compiler {
                     return false;
                 }
 
-                let html = match fs::read_to_string(&output_path) {
-                    Ok(h) => h,
-                    Err(_) => 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,
+                    html,
                     &output_path,
                     &output_dir,
                     relative_path,
@@ -1009,7 +1038,7 @@ impl Compiler {
             manifest_json
         );
 
-        fs::write(&manifest_path, manifest_js)
+        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:
@@ -1023,7 +1052,7 @@ impl Compiler {
         let stamped = stamper.stamp_html(html.to_string())
             .map_err(|e| format!("Failed to stamp HTML: {}", e))?;
 
-        fs::write(html_path, stamped)
+        atomic_write(html_path, &stamped)
             .map_err(|e| format!("Failed to write stamped HTML: {}", e))?;
 
         Ok(())
@@ -1108,6 +1137,7 @@ impl Compiler {
         // 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| {
@@ -1116,14 +1146,24 @@ impl Compiler {
                     .to_str()
                     .unwrap();
 
-                // Read compiled HTML
-                let html = match fs::read_to_string(html_path) {
-                    Ok(h) => h,
-                    Err(_) => return (false, Some(relative_path.to_string())),
+                // 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)
-                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) {
+                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) {
                     Ok(()) => (true, None),
                     Err(e) => {
                         if verbose {
@@ -1320,7 +1360,7 @@ impl Compiler {
     }
 
     fn compile_html_file(
-        &self,
+        &mut self,
         path: &Path,
         parser: &HtmlParser,
         relative_path: &str,
@@ -1361,11 +1401,14 @@ impl Compiler {
 
         // Write to output
         let output_path = self.get_output_path(path, relative_path)?;
-        fs::write(&output_path, output).map_err(|e| CompileError::WriteError {
+        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))
     }
@@ -2258,4 +2301,130 @@ mod tests {
         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).
+    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,
+            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 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"
+        );
+    }
 }

package/compiler/src/compiler/watcher.rs

@@ -206,6 +206,114 @@ fn component_cache_key(component: &Path, canonical_source: &Path) -> Option<Stri
         .map(|rel| format!("/{}", rel.replace('\\', "/")))
 }
 
+/// Cross-process guard: exactly one `vibe compile --watch` per output
+/// directory. Two concurrent watchers double-compile every save and race each
+/// other's output writes — the loser reads a torn file back and emits a
+/// valid-but-empty manifest, so the page hydrates blank with no errors. The
+/// lock lives in the OS temp dir keyed by the output path, holds the owner's
+/// pid, and a lock whose process is gone is stolen (a killed watcher never
+/// unwinds, so Drop alone can't be trusted to clean up).
+#[derive(Debug)]
+pub struct WatchLock {
+    path: PathBuf,
+}
+
+impl WatchLock {
+    /// Deterministic lock path for an output dir, stable whether or not the
+    /// output exists yet: canonicalize the output itself when possible, else
+    /// its (existing) parent — so a watcher that locked before the first
+    /// compile created the output still collides with one that locked after.
+    fn lock_path_for(output: &Path) -> PathBuf {
+        use std::collections::hash_map::DefaultHasher;
+        use std::hash::{Hash, Hasher};
+
+        let canonical = output.canonicalize().unwrap_or_else(|_| {
+            let parent = output.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or(Path::new("."));
+            let name = output.file_name().map(PathBuf::from).unwrap_or_default();
+            parent
+                .canonicalize()
+                .unwrap_or_else(|_| parent.to_path_buf())
+                .join(name)
+        });
+
+        let mut hasher = DefaultHasher::new();
+        canonical.hash(&mut hasher);
+        std::env::temp_dir().join(format!("vibe-watch-{:016x}.lock", hasher.finish()))
+    }
+
+    pub fn acquire(output: &Path) -> Result<Self, String> {
+        let path = Self::lock_path_for(output);
+
+        // Two attempts: the second runs only after a stale lock was removed.
+        for _ in 0..2 {
+            match std::fs::OpenOptions::new().write(true).create_new(true).open(&path) {
+                Ok(mut file) => {
+                    use std::io::Write;
+                    let _ = write!(file, "{}", std::process::id());
+                    return Ok(Self { path });
+                }
+                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
+                    let holder = std::fs::read_to_string(&path)
+                        .ok()
+                        .and_then(|s| s.trim().parse::<u32>().ok());
+                    match holder {
+                        Some(pid) if process_alive(pid) => {
+                            return Err(format!(
+                                "another `vibe compile --watch` (pid {}) is already watching this output directory. \
+                                 Concurrent watchers race each other's writes and corrupt manifests — stop the other one first. \
+                                 (lock: {})",
+                                pid,
+                                path.display()
+                            ));
+                        }
+                        // Dead owner or unreadable lock: stale, steal it.
+                        _ => {
+                            let _ = std::fs::remove_file(&path);
+                        }
+                    }
+                }
+                Err(e) => {
+                    return Err(format!(
+                        "failed to create watch lock {}: {}",
+                        path.display(),
+                        e
+                    ));
+                }
+            }
+        }
+
+        Err(format!(
+            "could not acquire watch lock {} — still held after stale-lock cleanup",
+            path.display()
+        ))
+    }
+}
+
+impl Drop for WatchLock {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_file(&self.path);
+    }
+}
+
+#[cfg(unix)]
+fn process_alive(pid: u32) -> bool {
+    std::process::Command::new("kill")
+        .arg("-0")
+        .arg(pid.to_string())
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status()
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+/// Without a portable liveness probe, treat an existing lock as live — failing
+/// loudly (with the lock path in the message) beats silently racing.
+#[cfg(not(unix))]
+fn process_alive(_pid: u32) -> bool {
+    true
+}
+
 /// Check if a path should be blacklisted based on SKIP_FILES patterns
 /// This checks both the filename and all path components relative to source root
 fn is_path_blacklisted(path: &Path, source_root: &Path, skip_files: &[String]) -> bool {
@@ -297,8 +405,34 @@ fn scan_directory(
     Ok(())
 }
 
+/// A watcher whose spawning wrapper dies without unwinding (SIGKILL, crashed
+/// dev server) is orphaned: it keeps watching and its lock blocks every future
+/// `--watch` on the same output. Reparenting is the orphan signal — when the
+/// parent pid changes (to init or a reaper), the owner is gone, so release the
+/// lock and exit. `std::process::exit` skips Drop, hence the explicit remove.
+#[cfg(unix)]
+fn exit_when_orphaned(lock_path: PathBuf) {
+    let parent = std::os::unix::process::parent_id();
+    std::thread::spawn(move || loop {
+        std::thread::sleep(Duration::from_secs(2));
+        if std::os::unix::process::parent_id() != parent {
+            eprintln!("parent process exited — shutting down watcher");
+            let _ = std::fs::remove_file(&lock_path);
+            std::process::exit(0);
+        }
+    });
+}
+
+#[cfg(not(unix))]
+fn exit_when_orphaned(_lock_path: PathBuf) {}
+
 /// 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
+    // output exits loudly instead of silently racing this one.
+    let _watch_lock = WatchLock::acquire(&config.output)?;
+    exit_when_orphaned(_watch_lock.path.clone());
+
     println!("{}", "Building dependency graph...".cyan());
     let mut graph = build_dependency_graph(&config)?;
 
@@ -912,6 +1046,57 @@ mod tests {
         );
     }
 
+    fn lock_test_output(name: &str) -> PathBuf {
+        let out = std::env::temp_dir().join(format!("vibe_watch_lock_{}_out", name));
+        let _ = std::fs::remove_dir_all(&out);
+        std::fs::create_dir_all(&out).unwrap();
+        // A previous crashed test run may have left a lock behind.
+        let _ = std::fs::remove_file(WatchLock::lock_path_for(&out));
+        out
+    }
+
+    // Two concurrent watchers on one output dir double-compile every save and
+    // race each other's writes (torn manifest reads → blank pages). The second
+    // watcher must refuse to start while the first holds the lock.
+    #[test]
+    fn second_watch_lock_on_same_output_fails_while_held() {
+        let out = lock_test_output("same");
+
+        let first = WatchLock::acquire(&out).expect("first lock acquires");
+        let second = WatchLock::acquire(&out);
+        let msg = second.expect_err("second watcher on the same output must fail loudly");
+        assert!(
+            msg.contains("vibe compile --watch"),
+            "error should explain the conflict: {msg}"
+        );
+
+        drop(first);
+        WatchLock::acquire(&out).expect("released lock can be re-acquired");
+    }
+
+    // A watcher killed without unwinding (Ctrl+C, SIGTERM from dev tooling)
+    // leaves its lock file behind; the pid inside is dead, so the next watcher
+    // steals the lock instead of being locked out forever.
+    #[test]
+    fn stale_lock_from_dead_process_is_stolen() {
+        let out = lock_test_output("stale");
+
+        // No live process can have this pid (pid_max is 99998 on macOS,
+        // ≤ 4194304 on Linux).
+        std::fs::write(WatchLock::lock_path_for(&out), "4294967295").unwrap();
+
+        WatchLock::acquire(&out).expect("stale lock from a dead process must be stolen");
+    }
+
+    #[test]
+    fn locks_on_different_outputs_do_not_conflict() {
+        let out_a = lock_test_output("indep_a");
+        let out_b = lock_test_output("indep_b");
+
+        let _a = WatchLock::acquire(&out_a).expect("lock a");
+        WatchLock::acquire(&out_b).expect("an unrelated output dir must not be blocked");
+    }
+
     #[test]
     fn cache_key_is_source_relative_with_leading_slash() {
         let source = PathBuf::from("/proj/src");

package/hot-module-refresh.js

@@ -0,0 +1,384 @@
+// @ape-egg/vibe/hot-module-refresh
+//
+// Transport-agnostic browser HMR client — the "brain" that reconciles a code
+// edit into the live DOM instead of reloading the page. Extracted out of
+// vite-plugin-vibe so both dev modes share one implementation.
+//
+// SOFT DEPENDENCY: nothing in Vibe's runtime imports this, it imports nothing
+// from Vibe, and deleting it leaves a working framework. It depends solely on
+// the runtime global `window.$` (reconcile / renderComponent /
+// clearComponentCache), so it ships as a flat module a plain static server can
+// serve as-is — no bundler, no Vite.
+//
+// A transport adapter wires its channel to the brain through one seam:
+//
+//   setupHotModuleRefresh({ debug, subscribe })
+//   subscribe({ componentUpdate, pageUpdate })
+//
+//   • componentUpdate(path)  — a component template changed. Fetch the raw
+//       template; for every live instance, reconcile surgically when scripts
+//       are unchanged, else re-mount. Runtime-mode only — compiled output
+//       inlines components into pages, so its adapter never calls this.
+//   • pageUpdate(payload)    — the current page changed. Fetch it and reconcile
+//       the [vibe] root. Mode-agnostic: a raw page (runtime) and a compiled
+//       page (compiled) reconcile the same way.
+
+export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
+  const dbg = {
+    info: (...a) => { if (debug) console.info(...a); },
+    group: (...a) => { if (debug) console.group(...a); },
+    groupEnd: () => { if (debug) console.groupEnd(); },
+  };
+
+  // Track which live <component> wrappers correspond to which source file.
+  // Vibe's component.js replaces <component src='X'> with a fresh <component>
+  // (no src). The spy below tags the new wrapper with _vibeSrc + the slot
+  // content, so on a component-update we can find every live instance and
+  // hand the slot back to Vibe verbatim during re-mount.
+  const liveBySrc = new Map();
+
+  const isComponentSrc = (n) =>
+    n?.nodeType === 1 && n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+  const isProcessedComponent = (n) =>
+    n?.nodeType === 1 && !n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+
+  // Snapshot slot innerHTML on a <component src> BEFORE vibe strips iteration/
+  // conditional templates from its subtree. vibe's renderAllIterations removes
+  // nodes between <!-- each -->/<!-- /each --> comments synchronously after
+  // hydrate; if we wait until the component is swapped out (spy's removedNodes
+  // path) and read innerHTML then, the templates are gone and HMR re-mounts
+  // receive an empty slot. setup runs before the page's boot script calls into
+  // vibe — the initial pass captures everything present at parse time.
+  const captureSlot = (el) => {
+    if (el._vibePluginSlot === undefined) el._vibePluginSlot = el.innerHTML;
+  };
+  document.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+
+  // Mirrors vibe/runtime/cleanup.js#shouldCleanup: a subtree is 'done' once
+  // no <component[src]> remains pending and no literal @[...] sits in a
+  // text node. Used to release vibe-fouc once Vibe finishes processing the
+  // re-mounted component subtree.
+  const waitForVibeReady = (target, timeout = 2000) => new Promise((done) => {
+    const deadline = performance.now() + timeout;
+    const tick = () => {
+      if (!target.isConnected) return done();
+      if (!target.querySelector('component[src], div.component[src]')) {
+        const walker = document.createTreeWalker(target, NodeFilter.SHOW_TEXT);
+        let pending = false;
+        let n;
+        while ((n = walker.nextNode())) {
+          if (/@\[.+?\]/.test(n.textContent)) { pending = true; break; }
+        }
+        if (!pending) return done();
+      }
+      if (performance.now() > deadline) return done();
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+
+  new MutationObserver((mutations) => {
+    // First pass: capture slot content on any <component src> that gets
+    // added dynamically (conditional/iteration branches mounting nested
+    // components). Must happen before the removal/addition logic runs, so
+    // that if a subsequent mutation re-mounts or strips this element, the
+    // snapshot is already in place.
+    for (const { addedNodes } of mutations) {
+      for (const n of addedNodes) {
+        if (isComponentSrc(n)) captureSlot(n);
+        if (n?.nodeType === 1 && n.querySelectorAll) {
+          n.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+        }
+      }
+    }
+    for (const { addedNodes, removedNodes } of mutations) {
+      let src = null;
+      let slotContent = '';
+      let hadFouc = false;
+      let props = null;
+      let scriptHash;
+      for (const n of removedNodes) {
+        if (isComponentSrc(n)) {
+          src = n.getAttribute('src');
+          // vibe's component.js deletes _vibeSlotContent synchronously after
+          // reading it, so on re-mount transitions the prop is already gone
+          // by the time we see the removal. _vibePluginSlot is our own
+          // mirror that vibe never touches — read it preferentially, fall
+          // back to vibe's prop (initial page load), then innerHTML (also
+          // initial, when source was authored inline).
+          slotContent = (
+            n._vibePluginSlot !== undefined ? n._vibePluginSlot :
+            n._vibeSlotContent !== undefined ? n._vibeSlotContent :
+            n.innerHTML
+          ).trim();
+          hadFouc = n.hasAttribute('vibe-fouc');
+          // Script hash is set by remount() on the <component src> before it
+          // hits the DOM, OR carried from a previous wrapper via this same
+          // forward path. Either way, stash it so the processed wrapper can
+          // use it as baseline for future surgical reconciles.
+          scriptHash = n._vibeScriptHash;
+          // Capture all authored attrs so reconcile can detect prop changes
+          // on the callsite and re-mount when they differ. vibe-fouc is a
+          // transient HMR marker — in either attribute or class form — and
+          // must never end up in the authored set or every FOUC flip would
+          // falsely look like a prop change.
+          props = {};
+          for (const a of n.attributes) {
+            if (a.name === 'vibe-fouc') continue;
+            if (a.name === 'class') {
+              const kept = a.value.split(/\s+/).filter((t) => t && t !== 'vibe-fouc');
+              if (kept.length) props.class = kept.join(' ');
+              continue;
+            }
+            props[a.name] = a.value;
+          }
+          break;
+        }
+      }
+      if (!src) continue;
+      for (const n of addedNodes) {
+        if (isProcessedComponent(n)) {
+          n._vibeSrc = src;
+          n._vibeSlotContent = slotContent;
+          // Brain-owned mirror so we can recover slot content after vibe's
+          // processSingle deletes _vibeSlotContent on the next re-mount.
+          n._vibePluginSlot = slotContent;
+          n._vibeProps = props;
+          if (scriptHash !== undefined) n._vibeScriptHash = scriptHash;
+          if (!liveBySrc.has(src)) liveBySrc.set(src, new Set());
+          liveBySrc.get(src).add(n);
+          if (hadFouc) {
+            n.setAttribute('vibe-fouc', '');
+            waitForVibeReady(n).then(() => n.removeAttribute('vibe-fouc'));
+          }
+          break;
+        }
+      }
+    }
+  }).observe(document.body, { childList: true, subtree: true });
+
+  // Cheap string hash (djb2). Used to detect <script type="module"> changes
+  // between HMR fetches — unchanged scripts mean registered component state
+  // is still valid, so we can reconcile in place instead of re-mounting.
+  const hashString = (s) => {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) h = (((h << 5) + h) + s.charCodeAt(i)) | 0;
+    return h;
+  };
+  const hashScripts = (rawHtml) => {
+    const temp = document.createElement('div');
+    temp.innerHTML = rawHtml;
+    const scripts = temp.querySelectorAll('script[type="module"]');
+    return hashString([...scripts].map((s) => s.textContent || '').join(''));
+  };
+
+  // Return the baseline script hash for a live wrapper. On initial mount,
+  // vibe's component.js stashes the raw fetched HTML on the wrapper as
+  // _vibeRawSource. We hash it lazily on first HMR check and cache the
+  // result. This makes the very first save after page load surgical
+  // (assuming the script body hasn't changed) rather than always falling
+  // back to re-mount.
+  const getBaselineScriptHash = (el) => {
+    if (el._vibeScriptHash !== undefined) return el._vibeScriptHash;
+    if (el._vibeRawSource) {
+      el._vibeScriptHash = hashScripts(el._vibeRawSource);
+      return el._vibeScriptHash;
+    }
+    return undefined;
+  };
+
+  // Collect data-vibe-component-id values from the live wrapper's subtree in
+  // DOM order. Script processing inside the component assigns ids in script
+  // order → DOM order (each script's sibling group follows it), so reusing
+  // ids in DOM order keeps state bindings aligned across HMR renders.
+  const collectIdsInOrder = (el) => {
+    const ids = [];
+    const seen = new Set();
+    el.querySelectorAll('[data-vibe-component-id]').forEach((node) => {
+      const id = node.getAttribute('data-vibe-component-id');
+      if (id && !seen.has(id)) { seen.add(id); ids.push(id); }
+    });
+    return ids;
+  };
+
+  // True when an element lives inside a vibe iteration region (between
+  // <!-- each ... --> and <!-- /each -->). Iterations materialize the
+  // template N times with pre-resolved props; iterate.js caches the template
+  // at mount time, so surgical changes to one instance would be clobbered on
+  // the next array mutation. Fall back to re-mount in that case.
+  const isInsideIteration = (el) => {
+    let cur = el;
+    while (cur && cur.parentNode) {
+      let depth = 0;
+      let sib = cur.previousSibling;
+      while (sib) {
+        if (sib.nodeType === 8) {
+          const t = sib.textContent.trim();
+          if (t === '/each') depth++;
+          else if (t.startsWith('each ')) {
+            if (depth === 0) return true;
+            depth--;
+          }
+        }
+        sib = sib.previousSibling;
+      }
+      cur = cur.parentNode;
+      if (!cur || cur === document.body) return false;
+    }
+    return false;
+  };
+
+  // Re-mount a single live instance by swapping its wrapper for a fresh
+  // <component src>. Vibe re-fetches, re-executes scripts, and re-inlines
+  // the template. Used for first-HMR (no baseline hash), script changes,
+  // iteration-nested instances, and as a failure fallback.
+  const remount = (el, path, scriptHash) => {
+    const oldComponentIds = collectIdsInOrder(el);
+    const fresh = document.createElement(el.tagName);
+    if (el.tagName === 'DIV') fresh.className = 'component';
+    const props = el._vibeProps || { src: path };
+    for (const [name, value] of Object.entries(props)) {
+      fresh.setAttribute(name, value);
+    }
+    fresh.setAttribute('vibe-fouc', '');
+    const slot = el._vibePluginSlot !== undefined
+      ? el._vibePluginSlot
+      : (el._vibeSlotContent || '');
+    fresh._vibeSlotContent = slot;
+    fresh._vibePluginSlot = slot;
+    fresh._vibeScriptHash = scriptHash;
+    if (oldComponentIds.length) fresh._vibeReuseComponentIds = oldComponentIds;
+    // Transfer iteration-prop registry ownership from the soon-to-be-detached
+    // wrapper to the fresh one. The detach would otherwise trigger Vibe's
+    // releaseOrphanedIterationProps and free the registry slots that the
+    // copied prop attributes (e.g. node='@[window.__vibeIterProps._pN]') still
+    // reference, leaving every binding to render undefined after the HMR swap.
+    if (el._vibeIterPropIds) {
+      fresh._vibeIterPropIds = el._vibeIterPropIds;
+      fresh.setAttribute('data-vibe-iter-prop', '');
+      el._vibeIterPropIds = null;
+      el.removeAttribute('data-vibe-iter-prop');
+    }
+    el.replaceWith(fresh);
+  };
+
+  // Component file changed. Strategy:
+  //   1. Fetch the raw template once per update; hash its <script type="module">
+  //      contents. Script hash unchanged + not inside an iteration → surgical
+  //      path: $.renderComponent produces the processed HTML (props + slot
+  //      substituted, componentIds reused) and $.reconcile diffs it against
+  //      the live wrapper's children. DOM identity, focus, and component
+  //      state are preserved.
+  //   2. First HMR for any instance (no baseline hash stored), script changes,
+  //      or iteration-scoped callsites → full re-mount (same path as before
+  //      the surgical rewrite). vibe-fouc hides the subtree until ready.
+  //
+  // Props and slot content always come from the spy's _vibeProps /
+  // _vibePluginSlot snapshot.
+  let componentUpdateCount = 0;
+  const componentUpdate = async (path) => {
+    const n = ++componentUpdateCount;
+    // Drop the runtime's cached template for this file so any component
+    // mounted *after* this edit fetches the fresh version. Already-mounted
+    // instances are refreshed surgically below; this covers future mounts.
+    window.$?.clearComponentCache?.(path);
+    const instances = liveBySrc.get(path);
+    dbg.group('[vibe-hmr] component-update #' + n, path,
+      '— instances:', instances?.size || 0);
+    try {
+      if (!instances || !instances.size) {
+        dbg.info('[vibe-hmr]   no live instances; nothing to do');
+        return;
+      }
+      const rawUrl = path + (path.includes('?') ? '&' : '?') + '_t=' + Date.now();
+      const rawHtml = await fetch(rawUrl, { cache: 'no-store' }).then((r) => r.text());
+      const scriptHash = hashScripts(rawHtml);
+      const canSurgical = typeof window.$?.renderComponent === 'function'
+        && typeof window.$?.reconcile === 'function';
+
+      let surgical = 0;
+      let remounted = 0;
+      for (const el of [...instances]) {
+        instances.delete(el);
+        if (!el.parentNode) continue;
+
+        const oldHash = getBaselineScriptHash(el);
+        const inIter = isInsideIteration(el);
+
+        if (canSurgical && oldHash !== undefined && oldHash === scriptHash && !inIter) {
+          try {
+            const componentIds = collectIdsInOrder(el);
+            const slot = el._vibePluginSlot !== undefined
+              ? el._vibePluginSlot
+              : (el._vibeSlotContent || '');
+            const props = el._vibeProps || {};
+            const processedHtml = window.$.renderComponent(rawHtml, props, slot, { componentIds });
+            const summary = await window.$.reconcile(el, processedHtml);
+            el._vibeScriptHash = scriptHash;
+            el._vibeRawSource = rawHtml;
+            if (!liveBySrc.has(path)) liveBySrc.set(path, new Set());
+            liveBySrc.get(path).add(el);
+            surgical++;
+            dbg.info('[vibe-hmr]   surgical reconcile:', summary);
+            continue;
+          } catch (err) {
+            console.warn('[vibe-hmr]   surgical failed, falling back to re-mount:', err);
+          }
+        }
+
+        remount(el, path, scriptHash);
+        remounted++;
+      }
+      dbg.info('[vibe-hmr]   surgical:', surgical, 'remounted:', remounted);
+    } catch (err) {
+      console.error('[vibe-hmr]   component-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  // Page file changed — fetch new HTML and hand the [vibe] root + new inner
+  // content to $.reconcile. Vibe walks live vs. source and applies the
+  // minimal mutation; iteration / conditional / component regions are
+  // opaque (their interiors are state-driven). Page-level JS state on $
+  // is preserved (no full reload).
+  let pageUpdateCount = 0;
+  const pageUpdate = async (payload) => {
+    const n = ++pageUpdateCount;
+    dbg.group('[vibe-hmr] page-update #' + n, payload?.path || '(no path)');
+    try {
+      if (!window.$ || typeof window.$.reconcile !== 'function') {
+        console.warn('[vibe-hmr]   $.reconcile not available — skipped');
+        return;
+      }
+      const url = location.href + (location.href.includes('?') ? '&' : '?') + '_t=' + Date.now();
+      const t0 = performance.now();
+      const html = await fetch(url).then((r) => r.text());
+      dbg.info('[vibe-hmr]   fetched', html.length, 'bytes in', (performance.now() - t0).toFixed(1) + 'ms');
+      const doc = new DOMParser().parseFromString(html, 'text/html');
+      const newRoot = doc.querySelector('[vibe]') || doc.body;
+      const liveRoot = document.querySelector('[vibe]') || document.body;
+      dbg.info('[vibe-hmr]   target [vibe] root:', liveRoot, 'isConnected=', liveRoot.isConnected);
+      // Note: we no longer strip <script type='module'> from source. Stripping
+      // misaligned source vs. live and caused cascading replaces. Reconcile's
+      // tag-aligned walk now matches scripts at their position; updating a
+      // script's textContent doesn't re-execute it (a known limitation —
+      // editing inline page scripts requires a real reload to take effect).
+      const summary = await window.$.reconcile(liveRoot, newRoot.innerHTML);
+      dbg.info('[vibe-hmr]   summary:', summary);
+      if (summary?.changes?.length) {
+        for (const c of summary.changes) dbg.info('[vibe-hmr]     ·', c);
+      } else {
+        dbg.info('[vibe-hmr]   no changes — source matches live');
+      }
+    } catch (err) {
+      console.error('[vibe-hmr]   page-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  subscribe({ componentUpdate, pageUpdate });
+};

package/package.json

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