@ape-egg/vibe 2.1.7 → 2.1.9

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [2.1.9] - 2026-06-20
+
+### Fixed
+
+- **Compiler 1.9.4 → 1.9.5 — array-literal each-root components broke when inlined** (`compiler/src/parser/html.rs`, `compile.rs`) — a component whose root is `<!-- each [prop] as a -->` receives its iterable as a prop and relies on the runtime's `__vibeiterprops` indirection: the runtime evaluates the prop binding in the *enclosing* loop scope, stashes the value in a global registry slot, and iterates that slot. Inlining instead baked the call-site's parent-loop alias straight into the each (`[card.signatureAbility]`); the runtime evaluates an array-literal iterable in global scope, where that alias is undefined, so the loop yielded zero items (the empty `AbilityCell` / status-chip bug in compiled mode). Such components (`is_iter_prop_root`) are now left as runtime `<component src>` tags instead of being inlined — in both the `src=` and custom-element inlining paths — and the `components/` directory is always mirrored to the output so the runtime can fetch their source, exactly as in non-compiled mode. Tests: `each_root_component_is_left_for_runtime`, `ordinary_component_still_inlines` (`html.rs`), and `tests/compiler/components`.
+- **Compiler 1.9.4 → 1.9.5 — a stateful component nested inside another stole the inner's `this.` bindings** (`compiler/src/compiler/component_tagger.rs`) — the outer component's build-time `this.` → component-id rewrite descended through a nested component that registers its OWN `component({...})` state, claiming the inner's bindings and `if`/`each` directives with the outer id before the inner was reached. The inner's live state (registered under its own runtime id) then never reached its markup → empty each-loops and dead bindings (the `DebugContent` → `ScalingModal` empty-legend bug). The rewrite now stops at any nested state-registering component (`is_state_registering_component`); each component owns the `this.` inside it and gets its own id + rewrite when `walk_tag_and_extract` reaches it. Test: `nested_component_this_resolves_to_own_id`.
+
+## [2.1.8] - 2026-06-19
+
+### Changed
+
+- **Compiler 1.9.3 → 1.9.4 — watch-mode recompiles are incremental at the component-cache level** (`compiler/src/compiler/watcher.rs`, `compile.rs`) — on a component edit the watcher previously cleared the *entire* component cache, so every affected page re-expanded its whole component tree even though one leaf changed. It now invalidates only the edited component plus the components whose cached inlined content embeds it — its transitive inlining ancestors, via `DependencyGraph::get_all_dependent_components` — while every unrelated component stays cached and is reused. Supporting changes: the watcher adopts the initial full-compile's warm cache (`adopt_component_cache`) so even the first edit is incremental; cache keys are resolved source-relative (`component_cache_key`, matching the `<component src>` form, with paths outside the source root excluded so external-URL components are never wrongly invalidated); and incremental manifest generation (`generate_manifests_for_files`) now runs in parallel with rayon like the full build, since per-page static analysis dominates watch latency. A page-only edit invalidates no component caches at all. Unit tests cover the stale-ancestor set and cache-key normalization (`watcher.rs` tests).
+
 ## [2.1.7] - 2026-06-19
 
 ### Fixed

package/ROADMAP.md

@@ -323,6 +323,75 @@ Hand-roll the idle wait at the call site with `requestIdleCallback`. See `webdev
 
 ---
 
+## Proposed: Surgical HMR in Compiled (Hyperspeed) Mode
+
+**Status**: Proposal
+**Priority**: High (developer experience)
+**Category**: Compiler + Core Runtime (orchestrated by vite-plugin-vibe)
+**Discovered**: 2026-06-19 (battle-brawlers `dev:compiled` loop — a one-line edit to a leaf component recompiles every page that inlines it)
+
+### Problem
+
+Runtime mode already has surgical component HMR: vite-plugin-vibe refetches the changed component's source, calls `$.renderComponent(...)` + `$.reconcile(...)`, and patches **only the live instances** of that component — no page-level work. State is preserved by reusing the component ids.
+
+Compiled (hyperspeed) mode cannot do this today. The compiler **inlines components into each page's HTML and per-page manifest**, which *dissolves component identity*: the page manifest tree keeps the boundary as an anonymous positional node (`…→ component_1 → game-layout_0 → component_0 → …`) but nothing records *which source file produced it*. So the only invalidation the compiler can compute on a file save is the inverse graph — **component → dependent pages** — and it recompiles all of them.
+
+Concrete cost: `AccountProgression.html` is included by `Sidebar` and `Overlay`, both of which live in `Layout`, which **every** page mounts. One leaf edit → all 27 pages + 27 manifests recompiled (~2.7s), versus runtime mode's ~instant single-boundary patch.
+
+### Key realization — this is *not* "teach the compiler the runtime engine"
+
+The instinct is that surgical HMR means giving the Rust compiler the engine's runtime awareness (component instantiation, props, slots, live DOM) just to know what to recompile. It does **not**. Two things are already in place:
+
+1. **The runtime already ships the surgical engine** — `runtime/reconcile.js`, `runtime/component.js`, `runtime/component-cache.js`. Compiled pages boot the *same* runtime, so the patching machinery is already in the browser in compiled mode.
+2. **The compiler already builds the static include-graph** ("Building dependency graph…") and already knows component identity *during* inlining — it simply discards it in the output.
+
+What's missing is purely **emission + addressing**, not awareness:
+
+- The compiler needs to **stamp each boundary with its `src`** and (Option A) **emit each component's compiled subtree as its own small unit** that pages *reference* rather than absorb.
+- The runtime needs a **public boundary-swap API** built on the existing `reconcile` + `component-cache`, taking a recompiled unit + the live boundary and re-rendering just that subtree (live props/state stay the runtime's job — the compiler never needs them).
+
+The compiler and the engine have *converged on the same structural model from opposite ends* (both understand `<component src>` and the component tree). Surgical HMR **connects** those two seams through the tooling layer; it does not merge them, and it does not give the compiler runtime DOM awareness. The compiler's job stays build-time-static (include graph + boundary metadata); the runtime's job stays runtime-dynamic (props, state, DOM).
+
+### Layering constraint (non-negotiable)
+
+`vite-plugin-vibe` is **sugar on top**. The dependency direction is one-way:
+
+```
+vite-plugin-vibe  ──imports──▶  Vibe (compiler output + runtime public APIs)
+Vibe              ──never───▶   vite-plugin-vibe
+```
+
+- **Capabilities live in Vibe**, transport-agnostic:
+  - Compiler: emit boundary `src` identity; recompile a single component to its unit (`--watch` already incremental).
+  - Runtime: a public `swap(boundary, unit)` / `patchComponent(...)` API (reusing `reconcile`, `component-cache`, and component-id reuse for state preservation). Knows nothing about websockets or HMR.
+- **Orchestration lives in the plugin**: watch the compiler's `--watch` output, carry the recompiled unit over the dev websocket, call the runtime's swap API. The plugin already sends a `vibe:component-update` event in runtime mode — the compiled path emits the *same* event with a compiled payload.
+
+Neither the compiler nor the runtime gains a dependency on the plugin. The plugin remains optional sugar that delivers true HMR to **both** runtime dev and compiled dev.
+
+### Two implementation paths
+
+**Option A — per-component compiled units (full).**
+Compiler tags `component_N` boundaries with `src` and modularizes manifests so each component's subtree is a separately-emittable, separately-loadable module; pages reference units instead of inlining them. Repurpose the dep graph from *component→pages* to *component→its unit*. An edit recompiles one small unit. Runtime swaps boundaries from the new unit. **Manifest modularization is the bulk of the work** (today a page manifest is one ~440KB blob).
+
+**Option B — hybrid, recommended first (small lift).**
+In dev only, the compiler **keeps the boundary markers + the call-site props/slot** in the compiled output instead of fully dissolving them. On a component edit, the plugin treats *just that boundary* like a **runtime** component — refetch source → `renderComponent` + `reconcile` that one subtree — and leaves the rest of the page compiled. This reuses vite-plugin-vibe's existing runtime-HMR path almost verbatim; the **only** compiler change is "don't throw away boundary + props/slot metadata in a dev compiled build." Gets ~90% of the benefit; the edited boundary is re-expanded by the runtime engine rather than from a compiled unit (fine for dev).
+
+### Trade-offs
+
+- **Dev/prod divergence.** Inlining *is* hyperspeed; a boundary-preserving dev build is structurally different from the inlined prod build, so compiled-specific bugs (cross-boundary manifest merging, minified inlined scripts) may not reproduce in surgical-dev. Every framework lives with this (dev HMR builds ≠ prod). Keep **both** modes — surgical dev for iteration, full-inline compile for fidelity passes — and pick per task.
+- **Only internal edits go surgical.** Changing a *call site* (props/slot a page passes) still recompiles that page — same as runtime HMR re-mounting on a prop change.
+
+### Related (precedents — all do exactly this shape)
+
+- **Svelte** (`svelte-hmr` / Vite plugin): each component compiles to a module with an HMR proxy; a changed component hot-swaps its instances, preserving state where it can.
+- **Vue SFC HMR**: compiler stamps `__hmrId`; runtime `rerender`/`reload` patches just that component's instances.
+- **React Fast Refresh**: components compile with register/signature metadata + module boundaries; the refresh runtime re-renders only affected components, preserving hook state.
+- **Vite HMR boundaries**: `import.meta.hot.accept` — module-scoped patching instead of full reload.
+
+All three compile components into **independently-addressable, hot-swappable units with HMR boundaries**, then patch via a runtime accept API. This proposal is the same pattern adapted to Vibe's manifest model, with the orchestration deliberately kept in the (one-way-dependent) plugin.
+
+---
+
 ## Future Proposals
 
 *This section reserved for additional feature proposals*

package/compiler/src/Cargo.lock

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

package/compiler/src/Cargo.toml

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

package/compiler/src/compiler/compile.rs

@@ -558,9 +558,29 @@ impl Compiler {
         }
     }
 
-    /// Clear all cached component content (forces re-fetch on next compile)
-    pub fn clear_component_cache(&mut self) {
-        self.component_cache.clear();
+    /// Drop only the named cache entries, forcing those components to be
+    /// re-read + re-inlined on the next compile while every other component is
+    /// reused from cache. `keys` are normalized component srcs (e.g.
+    /// `/components/Sidebar.html`). Returns how many entries were actually
+    /// removed. This is the incremental-watch path: invalidate the edited
+    /// component and its inlining ancestors, nothing else.
+    pub fn invalidate_components(&mut self, keys: &std::collections::HashSet<String>) -> usize {
+        let before = self.component_cache.len();
+        self.component_cache.retain(|key, _| !keys.contains(key));
+        before - self.component_cache.len()
+    }
+
+    /// Number of components currently held in the inlining cache.
+    pub fn cached_component_count(&self) -> usize {
+        self.component_cache.len()
+    }
+
+    /// Take over another compiler's warm component cache, leaving it empty.
+    /// The watch loop uses this to carry the initial full-compile cache into the
+    /// incremental compiler, so even the first edit reuses everything unchanged
+    /// instead of re-fetching the whole tree.
+    pub fn adopt_component_cache(&mut self, other: &mut Compiler) {
+        self.component_cache = std::mem::take(&mut other.component_cache);
     }
 
     pub fn compile(&mut self) -> Result<CompileStats, CompileError> {
@@ -864,56 +884,63 @@ impl Compiler {
     /// Generate manifests for specific HTML files (incremental compilation for watch mode)
     pub fn generate_manifests_for_files(&self, files: &[PathBuf]) -> Result<ManifestStats, CompileError> {
         let start = Instant::now();
-        let mut pages_processed = 0;
-        let mut pages_skipped = 0;
+
+        // Mirror generate_manifests: process each page's manifest in parallel.
+        // Manifest generation is the bulk of an incremental recompile (static
+        // analysis + serialization per page), so a sequential loop over the
+        // affected pages left most cores idle and dominated watch latency.
+        let output_dir = self.config.output.clone();
+        let source_root = self.config.source.clone();
+        let verbose = self.verbose;
+        let iterations_as_is = self.config.iterations_as_is;
+        let components_as_is = self.config.components_as_is;
+        let manifest_root = self.config.root.clone();
+        // Resolve constant global-state keys once, shared read-only across pages.
         let global_constants = self.compute_global_constants();
 
-        for file_path in files {
-            // Convert source path to output path
-            let relative_path = file_path
-                .strip_prefix(&self.config.source)
-                .unwrap_or(file_path)
-                .to_str()
-                .unwrap();
+        let results: Vec<bool> = files
+            .par_iter()
+            .map(|file_path| {
+                let relative_path = match file_path.strip_prefix(&source_root).unwrap_or(file_path).to_str() {
+                    Some(r) => r,
+                    None => return false,
+                };
 
-            let output_path = self.config.output.join(relative_path);
+                let output_path = output_dir.join(relative_path);
+                if !output_path.exists() {
+                    return false;
+                }
 
-            if !output_path.exists() {
-                pages_skipped += 1;
-                continue;
-            }
+                let html = match fs::read_to_string(&output_path) {
+                    Ok(h) => h,
+                    Err(_) => return false,
+                };
 
-            // Read compiled HTML from output
-            let html = fs::read_to_string(&output_path)
-                .map_err(|e| CompileError::ReadError {
-                    path: output_path.display().to_string(),
-                    source: e,
-                })?;
-
-            // Try to generate manifest for this file (skip on error)
-            match Self::generate_file_manifest(
-                &html,
-                &output_path,
-                &self.config.output,
-                relative_path,
-                self.verbose,
-                self.config.iterations_as_is,
-                self.config.components_as_is,
-                &self.config.source,
-                self.config.root.as_deref(),
-                &global_constants,
-            ) {
-                Ok(()) => {
-                    pages_processed += 1;
-                }
-                Err(e) => {
-                    pages_skipped += 1;
-                    if self.verbose {
-                        println!("  Skipped ({}): {}", e, relative_path);
+                match Self::generate_file_manifest(
+                    &html,
+                    &output_path,
+                    &output_dir,
+                    relative_path,
+                    verbose,
+                    iterations_as_is,
+                    components_as_is,
+                    &source_root,
+                    manifest_root.as_deref(),
+                    &global_constants,
+                ) {
+                    Ok(()) => true,
+                    Err(e) => {
+                        if verbose {
+                            eprintln!("  Skipped ({}): {}", e, relative_path);
+                        }
+                        false
                     }
                 }
-            }
-        }
+            })
+            .collect();
+
+        let pages_processed = results.iter().filter(|&&ok| ok).count();
+        let pages_skipped = results.len() - pages_processed;
 
         let total_time_ms = start.elapsed().as_millis() as f64;
 
@@ -1243,17 +1270,19 @@ impl Compiler {
                     continue;
                 }
 
-                // Handle components directory based on components_as_is flag
+                // The components directory is always mirrored to the output. With
+                // components_as_is every component is loaded at runtime; otherwise
+                // most are inlined at build time, but iter-prop each-root components
+                // are deliberately left as runtime `<component src>` tags (see
+                // is_iter_prop_root in parser/html.rs) and the runtime fetches their
+                // source from here — exactly as it does in non-compiled mode.
                 if file_name == self.config.components {
-                    if self.config.components_as_is {
-                        // Copy components directory to output for runtime
-                        let new_relative = if relative_path.is_empty() {
-                            file_name.to_string()
-                        } else {
-                            format!("{}/{}", relative_path, file_name)
-                        };
-                        self.copy_directory(&path, &new_relative, canonical_source, stats)?;
-                    }
+                    let new_relative = if relative_path.is_empty() {
+                        file_name.to_string()
+                    } else {
+                        format!("{}/{}", relative_path, file_name)
+                    };
+                    self.copy_directory(&path, &new_relative, canonical_source, stats)?;
                     // Skip further processing (don't recurse into components)
                     continue;
                 }

package/compiler/src/compiler/component_tagger.rs

@@ -142,33 +142,7 @@ impl ComponentTagger {
                 // treated as a stateful component with the merged state of all its descendants.
                 // That made rewrite_this_to_component_id rewrite every @[this.xxx] in the page
                 // to @[_c0.xxx] before child components could claim their own bindings.
-                let mut direct_scripts_html = String::new();
-                for child in node.children.borrow().iter() {
-                    if let NodeData::Element { name: ref child_name, .. } = child.data {
-                        if child_name.local.as_ref() == "script" {
-                            // Read the script's raw text directly. Serializing the
-                            // element would HTML-escape JS operators (`>` -> `>`,
-                            // `&&` -> `&&`) because the serializer loses the
-                            // rawtext context when it starts at the script's children;
-                            // the escaped source then fails to parse, dropping a
-                            // `component(stateVar)` component to the regex fallback
-                            // (which only matches `component({` literals) and leaving
-                            // it untagged.
-                            let mut script_text = String::new();
-                            for grandchild in child.children.borrow().iter() {
-                                if let NodeData::Text { ref contents } = grandchild.data {
-                                    script_text.push_str(&contents.borrow());
-                                }
-                            }
-                            // Wrap in <script> so extract_from_html routes it through
-                            // the JS AST analyzer, which resolves `component(stateVar)`
-                            // via its declaration (the regex fallback can't).
-                            direct_scripts_html.push_str("<script>");
-                            direct_scripts_html.push_str(&script_text);
-                            direct_scripts_html.push_str("</script>");
-                        }
-                    }
-                }
+                let direct_scripts_html = Self::direct_scripts_html(node);
 
                 // A component must be tagged whenever it REGISTERS local state via a
                 // `component(...)` call — that is what makes `this.X` in its markup
@@ -237,6 +211,53 @@ impl ComponentTagger {
         })
     }
 
+    /// Concatenate a node's DIRECT `<script>` children as `<script>…</script>`.
+    /// Reads raw text (not serialized) so JS operators (`>`, `&&`) aren't
+    /// HTML-escaped — the escaped source would fail the AST parse and drop a
+    /// `component(stateVar)` call to the regex fallback. Used both to extract a
+    /// wrapper's own state and to detect nested component boundaries.
+    fn direct_scripts_html(node: &Handle) -> String {
+        let mut out = String::new();
+        for child in node.children.borrow().iter() {
+            if let NodeData::Element { name: ref child_name, .. } = child.data {
+                if child_name.local.as_ref() == "script" {
+                    let mut script_text = String::new();
+                    for grandchild in child.children.borrow().iter() {
+                        if let NodeData::Text { ref contents } = grandchild.data {
+                            script_text.push_str(&contents.borrow());
+                        }
+                    }
+                    out.push_str("<script>");
+                    out.push_str(&script_text);
+                    out.push_str("</script>");
+                }
+            }
+        }
+        out
+    }
+
+    /// Is this node a component wrapper that registers its OWN local state? Such
+    /// a node gets its own `_cN` id and `this.`→id pass when `walk_tag_and_extract`
+    /// reaches it, so an ancestor's rewrite must stop here — descending would let
+    /// the ancestor claim the nested component's bindings with the wrong id (the
+    /// DebugContent→ScalingModal empty-legend bug).
+    fn is_state_registering_component(node: &Handle) -> bool {
+        if let NodeData::Element { name, attrs, .. } = &node.data {
+            let tag_name = name.local.as_ref();
+            let borrowed = attrs.borrow();
+            let is_component = tag_name == "component" && !Self::has_src_attr(&borrowed);
+            let is_div_component = tag_name == "div"
+                && Self::has_class_component(&borrowed)
+                && !Self::has_src_attr(&borrowed);
+            if !(is_component || is_div_component) {
+                return false;
+            }
+            drop(borrowed);
+            return component_call_regex().is_match(&Self::direct_scripts_html(node));
+        }
+        false
+    }
+
     /// Rewrite `this.X` to `componentId.X` throughout a component's subtree:
     /// inside `@[...]` bindings (text + attributes, nested paths and multi-ref
     /// expressions) and inside if/each/else-if directive comments. Resolving the
@@ -312,8 +333,14 @@ impl ComponentTagger {
             }
         }
 
-        // Recurse into children
+        // Recurse into children — but STOP at a nested component that registers
+        // its own state. It owns the `this.` inside it and gets its own id +
+        // rewrite when walk_tag_and_extract reaches it; descending here would
+        // claim its bindings with this ancestor's id (the empty-legend bug).
         for child in node.children.borrow().iter() {
+            if Self::is_state_registering_component(child) {
+                continue;
+            }
             Self::rewrite_node_recursive(child, binding_regex, this_prop, state_this_prop, component_id);
         }
     }
@@ -394,6 +421,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn nested_component_this_resolves_to_own_id() {
+        // DebugContent → ScalingModal shape: a stateful component nested inside
+        // another stateful component, each owning its own `this.`. The outer's
+        // this.→id rewrite must STOP at the inner component boundary — otherwise
+        // it claims the inner's bindings/directives with the OUTER id before the
+        // inner is reached, and the inner's live state (registered under its own
+        // runtime id) never reaches the markup → empty each-loops, dead bindings.
+        let html = r#"<!DOCTYPE html><html><body><component><script>component({ outer: 1 })</script><outer-mark>@[this.outer]</outer-mark><component><script>component({ inner: 2, items: [] })</script><modal-root open="@[this.open]"><!-- each this.items as it --><inner-mark>@[this.inner]</inner-mark><!-- /each --></modal-root></component></component></body></html>"#;
+
+        let result = ComponentTagger::tag_components(html, &PathBuf::from(".")).unwrap();
+
+        // Outer is _c0 (visited first), inner is _c1 (reached on recursion).
+        assert!(result.html.contains("@[_c0.outer]"), "outer binding wrong: {}", result.html);
+        assert!(result.html.contains("@[_c1.inner]"), "inner binding not rewritten to own id: {}", result.html);
+        assert!(result.html.contains("each _c1.items as it"), "inner each not rewritten to own id: {}", result.html);
+        assert!(result.html.contains("open=\"@[_c1.open]\""), "inner attr binding not rewritten to own id: {}", result.html);
+        // The outer must NOT have claimed any of the inner's bindings/directives.
+        assert!(!result.html.contains("@[_c0.inner]"), "outer claimed inner text binding: {}", result.html);
+        assert!(!result.html.contains("each _c0.items"), "outer claimed inner each: {}", result.html);
+        assert!(!result.html.contains("@[_c0.open]"), "outer claimed inner attr binding: {}", result.html);
+    }
+
     #[test]
     fn tag_multiple_components() {
         // Each wrapper registers component-local state, so all three are tagged

package/compiler/src/compiler/watcher.rs

@@ -81,6 +81,30 @@ impl DependencyGraph {
             }
         }
     }
+
+    /// Get the edited component itself plus every component that transitively
+    /// inlines it. These are exactly the component caches that go stale on an
+    /// edit: a parent's cached content is the *fully inlined* child, so when the
+    /// child changes the parent's cache is stale too. Unrelated components keep
+    /// their cache. The returned set always includes `component` itself.
+    pub fn get_all_dependent_components(&self, component: &Path) -> HashSet<PathBuf> {
+        let mut all = HashSet::new();
+        self.collect_dependent_components(component, &mut all);
+        all
+    }
+
+    fn collect_dependent_components(&self, component: &Path, all: &mut HashSet<PathBuf>) {
+        // insert() == false → already seen: doubles as the cycle guard.
+        if !all.insert(component.to_path_buf()) {
+            return;
+        }
+
+        if let Some(users) = self.component_to_components.get(component) {
+            for user in users {
+                self.collect_dependent_components(user, all);
+            }
+        }
+    }
 }
 
 /// Extract component references from HTML content
@@ -126,6 +150,19 @@ fn to_kebab_case(s: &str) -> String {
     result
 }
 
+/// Map a component's source path to the normalized key under which its inlined
+/// content is cached (e.g. `/components/Sidebar.html`). The cache key is the
+/// component's path relative to the source root, with a leading slash — the same
+/// form `<component src>` resolves to. Returns None for paths outside the source
+/// root (e.g. external URL components, which never go stale on a local edit).
+fn component_cache_key(component: &Path, canonical_source: &Path) -> Option<String> {
+    component
+        .strip_prefix(canonical_source)
+        .ok()
+        .and_then(|rel| rel.to_str())
+        .map(|rel| format!("/{}", rel.replace('\\', "/")))
+}
+
 /// 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 {
@@ -326,9 +363,16 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
     // Canonicalize output path for reliable comparison
     let canonical_output = config.output.canonicalize()
         .unwrap_or_else(|_| config.output.clone());
+    // Canonical source root: dependency-graph paths are canonical, so map them to
+    // cache keys against the same base.
+    let canonical_source = config.source.canonicalize()
+        .unwrap_or_else(|_| config.source.clone());
 
     // Keep compiler and parser alive to reuse component cache across incremental compilations
     let mut watch_compiler = Compiler::new(config.clone(), false);
+    // Carry the initial compile's warm component cache into the watcher so the
+    // first edit is already incremental (only the edited subtree re-expands).
+    watch_compiler.adopt_component_cache(&mut compiler);
     let mut parser = {
         use crate::parser::HtmlParser;
         let mut p = HtmlParser::new(config.components_path());
@@ -373,6 +417,10 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
 
                         // Determine what needs recompiling
                         let mut pages_to_recompile: HashSet<PathBuf> = HashSet::new();
+                        // Component caches that go stale this batch: each edited
+                        // component plus the ancestors that inline it. Everything
+                        // else stays cached and is reused.
+                        let mut stale_component_keys: HashSet<String> = HashSet::new();
 
                         for path in &changed_paths {
                             // Skip files in output directory (avoid infinite loop)
@@ -398,8 +446,16 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                                 if !dependent_pages.is_empty() {
                                     println!("{} {} changed", "[watch]".cyan(), relative_path.display());
 
-                                    // Invalidate component cache so stale content isn't used
-                                    watch_compiler.clear_component_cache();
+                                    // 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.
+                                    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);
+                                        }
+                                    }
 
                                     // Reload the changed component in the parser's element cache
                                     // (used for custom element syntax like <Layout>)
@@ -546,9 +602,19 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
 
                         // Compile HTML files
                         if !html_files.is_empty() {
-                                // Always clear component cache before recompiling so components
-                                // are read fresh from disk (prevents stale cache from previous triggers)
-                                watch_compiler.clear_component_cache();
+                                // 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) => {
@@ -645,3 +711,77 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // leaf <- mid <- layout <- page, with `sibling` an unrelated component that
+    // layout also uses. Editing `leaf` invalidates the cached, fully-inlined
+    // content of leaf and every component whose cache embeds it (mid, layout) —
+    // but NOT `sibling` (its cache never contained leaf) and NOT pages (they are
+    // recompiled, not cache entries).
+    fn chain_graph() -> (DependencyGraph, [PathBuf; 5]) {
+        let leaf = PathBuf::from("/src/components/AccountProgression.html");
+        let mid = PathBuf::from("/src/components/Sidebar.html");
+        let layout = PathBuf::from("/src/components/Layout.html");
+        let sibling = PathBuf::from("/src/components/Topbar.html");
+        let page = PathBuf::from("/src/pages/index.html");
+
+        let mut graph = DependencyGraph::new();
+        graph.add_dependency(mid.clone(), leaf.clone(), true); // mid uses leaf
+        graph.add_dependency(layout.clone(), mid.clone(), true); // layout uses mid
+        graph.add_dependency(layout.clone(), sibling.clone(), true); // layout uses sibling
+        graph.add_dependency(page.clone(), layout.clone(), false); // page uses layout
+
+        (graph, [leaf, mid, layout, sibling, page])
+    }
+
+    #[test]
+    fn dependent_components_are_just_the_stale_ancestor_chain() {
+        let (graph, [leaf, mid, layout, sibling, page]) = chain_graph();
+
+        let stale = graph.get_all_dependent_components(&leaf);
+
+        // The edited component itself, plus every component that inlines it.
+        assert!(stale.contains(&leaf), "leaf itself must be invalidated");
+        assert!(stale.contains(&mid), "mid inlines leaf — stale");
+        assert!(stale.contains(&layout), "layout transitively inlines leaf — stale");
+        // A sibling that does not contain leaf keeps its cache.
+        assert!(!stale.contains(&sibling), "sibling never inlined leaf — must stay cached");
+        // Pages are recompiled, not component-cache entries.
+        assert!(!stale.contains(&page), "pages are not in the component set");
+        assert_eq!(stale.len(), 3, "exactly leaf + mid + layout go stale");
+    }
+
+    #[test]
+    fn editing_a_leaf_invalidates_far_fewer_than_the_dependent_pages() {
+        let (graph, [leaf, _mid, _layout, _sibling, _page]) = chain_graph();
+
+        // dependent-pages drives which output files recompile; dependent-
+        // components drives which caches to drop — the minimal stale set, which
+        // never includes unrelated siblings.
+        let stale_components = graph.get_all_dependent_components(&leaf);
+        let dependent_pages = graph.get_all_dependent_pages(&leaf);
+
+        assert_eq!(dependent_pages.len(), 1, "one page inlines leaf");
+        assert!(stale_components.iter().all(|c| c.starts_with("/src/components")));
+    }
+
+    #[test]
+    fn cache_key_is_source_relative_with_leading_slash() {
+        let source = PathBuf::from("/proj/src");
+        // Must match the key form fetch_component_recursive stores.
+        assert_eq!(
+            component_cache_key(&PathBuf::from("/proj/src/components/Sidebar.html"), &source)
+                .as_deref(),
+            Some("/components/Sidebar.html"),
+        );
+        // A path outside the source root (e.g. an external URL component's
+        // resolved path) yields no key, so it's never wrongly invalidated.
+        assert_eq!(
+            component_cache_key(&PathBuf::from("/elsewhere/x.html"), &source),
+            None,
+        );
+    }
+}

package/compiler/src/parser/html.rs

@@ -367,6 +367,12 @@ impl HtmlParser {
             Some((open_tag.start(), close_end, props, slot_content))
         }).collect();
 
+        // Iter-prop components stay as runtime `<component src>` tags (see
+        // is_iter_prop_root). The content is the same for every match, so skip all.
+        if is_iter_prop_root(component_content) {
+            return result;
+        }
+
         // Replace from end to start (sorted descending by start position)
         let mut sorted = matches;
         sorted.sort_by(|a, b| b.0.cmp(&a.0));
@@ -449,6 +455,12 @@ impl HtmlParser {
                 };
 
                 if let Some(template) = external_cache.get(&normalized_src) {
+                    // Iter-prop components stay as runtime `<component src>` tags so the
+                    // runtime renders them via its __vibeiterprops path — inlining
+                    // breaks the enclosing loop's scope (see is_iter_prop_root).
+                    if is_iter_prop_root(template) {
+                        continue;
+                    }
                     let mut replacement = substitute_props(template, &props);
                     replacement = neuter_component_scripts(&replacement);
 
@@ -578,6 +590,30 @@ fn substitute_state_ref(body: &str, name: &str, replacement: &str) -> String {
 /// runtime's renderPropsAndSlot (runtime/component.js). Both sides must
 /// transform identically:
 ///   - exact `@[propName]` bindings (case-insensitive)
+/// Whether a component template's ROOT is an array-literal each
+/// (`<!-- each [expr] as a -->`). Such a component receives its iterable as a prop
+/// and depends on the runtime's `__vibeiterprops` indirection: the runtime
+/// evaluates the prop binding in the *enclosing* loop scope, stores the value in a
+/// global registry slot, and rewrites the each to iterate that slot. Inlining
+/// instead bakes the call-site's parent-loop alias straight into the each
+/// (`[card.signatureAbility]`); the runtime evaluates an array-literal iterable in
+/// GLOBAL scope (that's the registry-slot pattern), where the alias is undefined →
+/// the loop yields zero items (the empty AbilityCell / status-chip bug in compiled
+/// mode). So such components are NOT inlined — they stay as runtime
+/// `<component src>` tags, and the compiler ships their source so the runtime can
+/// fetch and instantiate them exactly as it does in non-compiled mode.
+fn is_iter_prop_root(template: &str) -> bool {
+    let t = template.trim_start();
+    t.strip_prefix("<!--")
+        .map(str::trim_start)
+        .and_then(|r| r.strip_prefix("each"))
+        .map(str::trim_start)
+        .is_some_and(|after| after.starts_with('['))
+}
+
+/// Substitute component props into a template.
+///
+/// Rewrites:
 ///   - prop identifiers inside other `@[expr]` bindings
 ///   - prop identifiers inside directive comments (`if` / `else if` / `each`)
 ///   - `$.propName` references inside event-handler attribute bodies
@@ -853,4 +889,59 @@ mod tests {
         // A literal prop after the `>=` prop still substitutes → tag parsed fully.
         assert!(out.contains(r#"n="7""#), "count not substituted: {out}");
     }
+
+    #[test]
+    fn each_root_component_is_left_for_runtime() {
+        // A component whose ROOT is an array-literal each (`<!-- each [prop] as a -->`)
+        // depends on the runtime's __vibeiterprops indirection (the runtime evaluates
+        // the prop in the enclosing loop scope and stashes it in a global registry
+        // slot the each iterates). Inlining bakes the parent-loop alias into the each
+        // (`[card.signatureAbility]`); the runtime evaluates array-literal iterables
+        // in GLOBAL scope, where that alias is undefined → zero items (the empty
+        // AbilityCell / status-chip bug). So such a component must NOT be inlined:
+        // leave the `<component src=...>` tag for the runtime to fetch and instantiate.
+        let parser = HtmlParser::new(std::path::PathBuf::from("."));
+        let page = concat!(
+            r#"<!-- each cards as card --><card-section>"#,
+            r#"<component src="/components/AbilityCell.html" ability="@[card.signatureAbility]"></component>"#,
+            r#"</card-section><!-- /each -->"#,
+        );
+        // AbilityCell's root is an each over the `[ability]` array-literal prop.
+        let template = r#"<!-- each [ability] as a --><ability-tile><icon @[a.icon]></icon></ability-tile><!-- /each -->"#;
+        let mut cache = HashMap::new();
+        cache.insert("/components/AbilityCell.html".to_string(), template.to_string());
+
+        let out = parser.inline_component_elements(page, &cache);
+
+        // Left un-inlined for the runtime, with its prop binding intact…
+        assert!(
+            out.contains(r#"<component src="/components/AbilityCell.html""#),
+            "each-root component must be left un-inlined for the runtime: {out}"
+        );
+        assert!(
+            out.contains(r#"ability="@[card.signatureAbility]""#),
+            "prop binding lost on un-inlined component: {out}"
+        );
+        // …and the parent-loop alias must NOT have been baked into an each iterable.
+        assert!(
+            !out.contains("each [card.signatureAbility]"),
+            "parent-loop alias was inlined into the component each (the bug): {out}"
+        );
+    }
+
+    #[test]
+    fn ordinary_component_still_inlines() {
+        // Guard: a normal component (root is NOT an array-literal each) must still
+        // inline as before — the skip is scoped to the iter-prop pattern only.
+        let parser = HtmlParser::new(std::path::PathBuf::from("."));
+        let page = r#"<page><component src="/components/Badge.html" label="@[title]"></component></page>"#;
+        let template = r#"<badge-pill>@[label]</badge-pill>"#;
+        let mut cache = HashMap::new();
+        cache.insert("/components/Badge.html".to_string(), template.to_string());
+
+        let out = parser.inline_component_elements(page, &cache);
+
+        assert!(out.contains("<badge-pill>"), "ordinary component should inline: {out}");
+        assert!(!out.contains(r#"src="/components/Badge.html""#), "ordinary component src should be gone: {out}");
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.1.7",
+  "version": "2.1.9",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",