@ape-egg/vibe 1.9.1 → 1.9.5

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [1.9.5] - 2026-05-23
+
+### Added
+
+- **Loop-scoped `on*` event handlers** (`runtime/loop-scope.js` (new), `runtime/parse.js`, `runtime/iterate.js`, `runtime/conditionals.js`, `runtime/pre-compiled-iterations.js`, `runtime/index.js`) — inside a `<!-- each X as alias -->` loop, an event handler can reference the bare loop variable and receive the **live object** at fire time: `onclick="pick(ability)"` instead of flattening fields into `@[ability.id]`/`@[ability.ticks]`/…. The handler stays a visible native `on*` attribute (no hidden `addEventListener`), preserving the truthful-DOM / `outerHTML`-snapshot model.
+  - At parse time a token-aware scanner rewrites a bare alias `ability` → `$scope(this,'ability')`, skipping `@[…]` binding spans, string literals, and member access (`foo.ability`). `$`, `this`, `event`, and bare function names are left untouched, so `$.state` and plain native handlers are never affected; `@[…]` handlers keep their existing stringifying behavior (backward compatible).
+  - A global `$scope(el, name)` resolver (installed by the runtime) walks up the DOM to the nearest `__vibeScope` stamp and returns the live item — resolution is by **identity**, not array position, so it works for derived-source loops (`.filter` / `.map` / `(x || [])`) and survives keyed reorders.
+  - Resolves recursively through **arbitrary-depth, arbitrary-combination `each` / `if` nesting** (e.g. `each > if > each > if`), including wrapper-less loops and handlers that first mount via a later state change (the update path). Achieved by persisting the full *accumulated* enclosing alias set on each iteration/conditional node (`meta.scopeAliases`) and threading it back into the render-time re-parse, and by stamping each instance/branch with the accumulated in-scope loop vars.
+  - The Rust AOT compiler needs no changes: iterations carrying loop-scoped handlers bypass the manifest `batchFn` (which predates the rewrite) and use the runtime path that reads the rewritten template, so behavior is identical in runtime and compiled modes.
+  - Test: `tests/unit/loop-scope.test.js` (rewriter, resolver, stamper) and `tests/e2e/loop-scoped-handlers.spec.js` (live object passed, derived source, nested aliases, keyed reorder, conditional-in-loop, deep `each/if/each/if`, wrapper-less loops, update-path mount, `$`/native handlers unaffected — runtime + compiled)
+
+---
+
+## [1.9.4] - 2026-05-22
+
+### Fixed
+
+- **Binding-less `<!-- each -->` rendered only one item** (`runtime/iterate.js`) — an iteration whose repeated template contained no reactive binding referencing the loop scope (e.g. `<coin></coin>`) was never expanded: the runtime left the authored template untouched and rendered exactly one copy regardless of array length, and one copy even for an empty array. Adding any loop-scope binding (`@[i]`, `@[item.foo]`, …) made it work, which is why it stayed hidden — every working `each` happened to interpolate the loop var.
+  - Root cause was `renderIteration`'s fallback "already rendered" check, which concluded a region was rendered when no element between the comments contained `@[...]` syntax. That heuristic conflates *already-rendered output* (no bindings left to hydrate) with *a binding-less authored template* (never had bindings to begin with), so binding-less templates were always skipped.
+  - The fallback now keys off `managedNodes` — Vibe's authoritative DOM-ownership signal (a node lands there only when a render path produced it) — instead of the absence of `@[...]`. Detection is binding-agnostic, so a binding-less template expands to N clones (and 0 for an empty array) in both runtime and compiled modes, while the original "comment markers replaced by component re-processing" case it guarded still bails correctly.
+  - Test: `tests/e2e/binding-less-iteration.spec.js` (binding-less body renders N, empty renders 0, bound body still renders N, reactivity grows both lists)
+
+---
+
+## [1.9.3] - 2026-05-18
+
+### Fixed
+
+- **Compiler stack overflow on self-referencing components** (`compiler/src/compiler/compile.rs`, `compiler/src/parser/html.rs`) — `bun vibe:compile` aborted with `fatal runtime error: stack overflow` when any component referenced itself (e.g. `recursive-tree-node.html` containing a `<component src="/components/recursive-tree-node.html">` for runtime-bounded tree rendering). Two compounding bugs: `fetch_component_recursive` had no cycle guard so direct or transitive cycles (A → A, A → B → A) recursed until the stack overflowed; and even if recursion had been bounded, the cached content still carried the self-reference so `inline_component_elements`'s `src=` regex would keep re-expanding it forever, growing the document on every loop iteration.
+  - `fetch_component_recursive` now takes a `visiting: &mut HashSet<String>` representing the live fetch chain. The src is inserted before recursing into nested components and removed after, so the set tracks "what's currently being resolved," not "everything ever fetched." When a recursive call sees its own src already in `visiting`, it returns `None` and the caller leaves the `<component src>` tag intact for runtime to handle.
+  - Before caching, any `<component src="X">` in the resolved content whose `X` points back into the chain (or to the component itself) has its `src=` renamed to `data-vibe-recursive-src=` by a new module-level helper `escape_recursive_src`. The inliner's regex doesn't match the renamed attribute, so it stops re-expanding. `process_html_with_cache` restores the attribute to plain `src=` at the very end of compilation so the runtime fetches the recursion normally — escape is a compile-time-only mechanism.
+
+---
+
+## [1.9.2] - 2026-05-08
+
+### Fixed
+
+- **Batch iteration path divergences from clone+hydrate** (`runtime/iterate.js`) — `renderBatch`'s template-literal compiler now produces DOM identical to the clone path for every supported binding form. Previously, simple-template iterations (single root, no nested directives, no `<component src>`) routed through batch but four binding shapes diverged silently from clone:
+  - **`this.X` rewriting** — pre-resolved at compile time using the iteration's anchor element. Previously `this.X` was inlined literally into the `new Function()` body where `this` is `globalThis`, so component-scoped expressions evaluated to `undefined`.
+  - **Boolean-coerced attributes** — emit a conditional template-literal segment so the attribute is *absent* when the binding is falsy, matching `hydrate.js`'s remove-when-falsy semantics. Previously batch always emitted `attr="${expr}"`, leaving `attr="false"` in the DOM when clone would have removed it.
+  - **DOM properties** (`value` / `checked` / `selected`) — collected at compile time into a sidecar list with a transient `data-vibe-batch="…"` marker on the element, then applied in a small post-stamp loop that mirrors `hydrate.js`'s DOM-property branch (sets the property AND the attribute, removes attribute when value is `undefined`/`null`). The attribute alone isn't enough — `<option selected="false">` is still selected by HTML semantics, only the property write makes it correct.
+  - **Name bindings** (`<el @[expr]>`) — emit a conditional template-literal segment that produces ` resolvedName=""` when truthy / nothing when falsy, with HTML-lowercase fallback so `<icon @[attrName]>` still resolves the camelCase state key after the browser parses it as `@[attrname]`.
+  - The compiled batch function now also receives `$` as its last parameter so component-scoped expressions like `$['_c0'].chosen` (produced by the `this.X` rewrite) resolve against live state.
+  - New equivalence harness: `tests/e2e/batch-vs-clone-equivalence.spec.js` flips a `__vibeForceClonePath` debug flag and compares region-by-region across both paths. 13 regions cover all four gaps plus regression cases for the binding forms that already worked.
+
+- **`this.X` inside iteration rows didn't resolve in the clone path either** (`runtime/utils.js`, `runtime/iterate.js`) — `findComponentIdForElement` walked from the row's cloned element up to the detached `parseContainer` and stopped, returning `null`. Hydrate then evaluated `this.X` against `globalThis`, producing `undefined`. Added a fallback: when `closest('[data-vibe-component-id]')` finds nothing, walk to the root and check a `_vibeComponentId` expando. `initializeBlock` now stashes the iteration's owning component id on the parseContainer (set from `findComponentIdForElement(startComment.parentElement)` in `renderIteration` and `buildInstance`), so detached hydrate sees the right component context. Latent bug that didn't surface until the equivalence harness above exercised `@[item === this.chosen]` and `@[item.toUpperCase() === this.chosen.toUpperCase()]` inside iteration rows.
+
+- **Combined default + named imports in component scripts** (`runtime/component.js`) — `<script type="module">` blocks that mix default and named imports (e.g. `import component, { foo } from '...'`) are now rewritten to two separate `await import()` calls (one for the default binding, one for the named bindings). Previously only one form was supported per import statement.
+
+---
+
 ## [1.9.1] - 2026-04-29
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 1.9.1 (Alpha)** — A runtime-first reactive framework with optional compilation.
+**Version 1.9.2 (Beta)** — A runtime-first reactive framework with optional compilation.
 
 No virtual DOM. No build step required. Just modern JavaScript. When you need production optimizations, add the optional Rust-based compiler.
 
@@ -35,14 +35,31 @@ The core reactive runtime. Works directly in the browser without any build tools
 </html>
 ```
 
+### The `vibe()` Signature
+
+```js
+window.$ = vibe(state, config?, targetSelector?);
+```
+
+- **`state`** *(object, required)* — initial reactive state. Becomes `window.$`. Mutate freely (`$.count++`, `$.user.name = 'Alice'`); deep mutations trigger updates automatically. Methods on the object are preserved.
+
+- **`config`** *(object, optional)* — runtime configuration. Currently supported keys:
+  - `debug` *(boolean, default `false`)* — colored console logs for every lifecycle phase (parse, hydrate, iterate, mutate, …). Useful for debugging reactivity issues.
+
+- **`targetSelector`** *(string, optional)* — CSS selector for the root element vibe attaches to. **Defaults to `document.body`.** Vibe parses, hydrates, and observes mutations only inside this root — anything outside (e.g. `<head>`, sibling `<aside>` elements) is ignored. If the selector matches nothing, vibe silently falls back to `document.body`. Pass `'html'` to include `<head>` (e.g. for binding `<title>@[pageTitle]</title>`).
+
+```js
+window.$ = vibe({ count: 0 }, { debug: true }, '#app');
+```
+
 ### Prevent FOUC
 
 To prevent a flash of unstyled content while Vibe hydrates:
 
 1. Include `vibe.css` in your HTML
-2. Add the `vibe` attribute to an element (typically `<body>`) to mark the hydration boundary
+2. Add the `vibe-fouc` attribute (or `class="vibe-fouc"`) to an element — typically `<body>`
 
-The CSS targets `[vibe]` and hides it until hydration completes. Once Vibe finishes processing, it removes the attribute, revealing your content.
+`vibe.css` hides `[vibe-fouc]` and `.vibe-fouc` until hydration completes; Vibe removes the attribute/class once it's done.
 
 ### Reactive Bindings
 
@@ -110,14 +127,23 @@ Nested iteration with dot paths:
 
 ### Components
 
-Runtime component loading with props and slots:
+Runtime component loading with props and slots. Slot content (between the tags) replaces `<slot></slot>` inside the component template:
 
 ```html
+<!-- /components/card.html -->
+<div class="card">
+  <h3>@[title]</h3>
+  <slot></slot>
+</div>
+
+<!-- usage -->
 <component src="/components/card.html" title="@[pageTitle]" theme="dark">
   <p>Content passed as slot</p>
 </component>
 ```
 
+`<div class="component" src="...">` is an equivalent alternative to `<component src="...">` for cases where standard HTML elements are required (validation, accessibility tooling).
+
 Props can be reactive bindings (`title="@[pageTitle]"`), static literals (`theme="dark"`), or live objects/arrays passed through iteration scope (`<component src="/card.html" card="@[card]">` inside `<!-- each cards as card -->`). Non-primitive props are stashed in an internal registry so the child template can dot/iterate into them (`@[card.name]`, `<!-- each card.abilities as a -->`).
 
 ### Component-Local State
@@ -146,6 +172,30 @@ How it works:
 
 Multi-segment paths (`@[this.user.profile.name]`), conditionals (`<!-- if this.editing -->`), and iterations (`<!-- each this.items as item -->`) all resolve against the component's bucket. Global `$` and component `this.X` coexist freely.
 
+### Drop-In Components (no `vibe()` needed)
+
+`component()` auto-boots the runtime. You can drop a self-contained reactive block into any HTML page — no top-level `vibe(...)` call, no global state setup, no build step. Import directly from a CDN and the runtime wires itself up:
+
+```html
+<component>
+  <script type="module">
+    import component from 'https://esm.sh/@ape-egg/vibe/component.js';
+    component({ count: 0 });
+  </script>
+  <button onclick="this.count--">-</button>
+  <span>Count: <strong>@[this.count]</strong></span>
+  <button onclick="this.count++">+</button>
+</component>
+```
+
+How it works:
+
+1. `component({...})` claims the nearest unprocessed `<component>` (or `<div class="component">`) wrapper, registers state at `$[id]`, and tags the wrapper with `data-vibe-component-id`
+2. Internally it calls `ensureBoot()` (from `@ape-egg/vibe/boot`), which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once, even if multiple `<component>` blocks call `component()`
+3. From there, `@[this.X]`, `onclick="this.fn()"`, and `<!-- if this.X -->` work as documented
+
+Multiple drop-in blocks on the same page each get their own state bucket. They can read each other's state via global `$['_c0'].count` if they need to coordinate, but in most drop-in cases they're independent.
+
 ### Lifecycle Hooks
 
 ```javascript
@@ -168,112 +218,12 @@ Skip reactive processing for an element:
 <code vibe-dehydrate>@[this] displays literally</code>
 ```
 
-### Reserved Words & Gotchas
-
-Vibe uses specific patterns and keywords that have special meaning. Avoid using these for other purposes to prevent unexpected behavior:
-
-#### Classes & Attributes
-
-- **`vibe-fouc`** — Class or attribute for FOUC (Flash of Unstyled Content) prevention. Automatically removed after hydration completes.
-
-  ```html
-  <body vibe-fouc>
-    <!-- or class="vibe-fouc" -->
-  </body>
-  ```
-
-- **`vibe-dehydrate`** — Class or attribute to skip reactive processing. Useful for displaying literal `@[...]` syntax in documentation.
-  ```html
-  <code vibe-dehydrate>@[variable]</code>
-  <!-- or class="vibe-dehydrate" -->
-  ```
-
-#### Element Names & Classes
-
-- **`<component>`** — Element name for component system. Used with `src` attribute for runtime component loading, or as a wrapper for inlined components.
-
-  ```html
-  <component src="/path/to/component.html"></component>
-  ```
-
-- **`class="component"`** — Alternative syntax for components using standard HTML elements. Useful for HTML validation or accessibility.
-
-  ```html
-  <div class="component" src="/path/to/component.html"></div>
-  ```
-
-- **`<slot>`** — Element name for component content injection. Gets replaced with content passed between component tags.
-
-  ```html
-  <!-- In component file -->
-  <slot></slot>
-
-  <!-- Usage -->
-  <component src="...">
-    <p>This replaces the slot</p>
-  </component>
-  ```
-
-#### Comment Syntax
-
-- **`<!-- each -->`** / **`<!-- /each -->`** — Iteration block markers.
-
-  ```html
-  <!-- each items as item -->
-  <!-- /each -->
-  ```
-
-- **`<!-- if -->`** / **`<!-- else -->`** / **`<!-- /if -->`** — Conditional block markers.
-  ```html
-  <!-- if condition -->
-  <!-- else -->
-  <!-- /if -->
-  ```
-
-#### Binding Syntax
-
-- **`@[...]`** — Reactive binding syntax. Reserved for state references.
-  ```html
-  <div>@[variable]</div>
-  ```
-
-#### Global Properties
-
-- **`window.$`** — Global reactive state object. All reactive data should be accessed through this.
-
-  ```javascript
-  window.$ = state({ count: 0 });
-  $.count++; // Triggers reactive updates
-  ```
-
-- **`window.__vibeManifest`** — Internal manifest data. Used by the compiler for optimization. Don't modify.
-
-- **`window.__vibeCompiling`** — Internal flag. Set to `true` when running in compiler context.
-
-#### Data Attributes
-
-- **`data-vibe-component-id`** — Internal attribute for component scoping. Automatically added to component elements. Don't use manually.
-
-#### Event Names
-
-- **`vibe:ready`** — Custom event fired when Vibe completes initial hydration.
-  ```javascript
-  document.addEventListener('vibe:ready', () => {
-    console.info('Vibe is ready');
-  });
-  ```
-
-#### Special Attribute Meanings
-
-- **`src`** on **`<component>`** or **`<div class="component">`** — Triggers runtime component fetching. Components without `src` are treated as inline wrappers.
+### Internal Names (don't collide)
 
-  ```html
-  <!-- Both work the same way -->
-  <component src="/components/card.html"></component>
-  <div class="component" src="/components/card.html"></div>
-  ```
+These are used by the runtime — don't repurpose them in your code:
 
-- **`dehydrate`** — Attribute or class name to skip reactive processing (alias for `vibe-dehydrate`).
+- `window.__vibeManifest`, `window.__vibeCompiling`, `window.__vibeComponents`, `window.__vibeIterProps` — internal registries
+- `data-vibe-component-id`, `data-vibe-iter-prop` — element-level bookkeeping attributes (set automatically)
 
 ### Deep Reactivity
 
@@ -586,11 +536,12 @@ Every time `matchesKey` can't prove an expression is unrelated to a state change
 
 The browser lowercases all attribute names during HTML parsing. `<page @[pageName]>` becomes `@[pagename]` in the DOM. Every value hydrated into an attribute NAME position loses its case. `@[myCoolPage]` → DOM stores `@[mycoolpage]`, causing comparison mismatches against camelCase state keys.
 
-Handled today by case-insensitive fallbacks in two places:
-- `runtime/hydrate.js:~32` — case-insensitive state key lookup when evaluating name bindings
+Handled today by case-insensitive fallbacks in three places:
+- `runtime/hydrate.js:~32` — case-insensitive state key lookup when evaluating name bindings (clone path)
 - `runtime/affected.js:~235` — case-insensitive `matchesKey` wrapper for name bindings
+- `runtime/iterate.js` — case-insensitive lookup against `stateKeys` inside `compileBatchFn`'s name-binding emission (batch path)
 
-Both are workarounds for HTML's behavior. A cleaner architecture would centralize the case-insensitive state key resolution into one helper, or normalize the name binding expression to canonical state-key case at first evaluation and cache it on the tree node.
+All three are workarounds for HTML's behavior. A cleaner architecture would centralize the case-insensitive state key resolution into one helper, or normalize the name binding expression to canonical state-key case at first evaluation and cache it on the tree node.
 
 ### Related: value hydration into attribute values is case-preserving
 

package/ROADMAP.md

@@ -6,7 +6,8 @@ Feature proposals and improvements for Vibe's runtime-first reactive framework.
 
 ## Proposed: Manual Hydration API
 
-**Status**: Proposal
+**Status**: Superseded by `$.reconcile()` (shipped in 1.9.0). See `runtime/reconcile.js` and the changelog entry. The reconciliation API solves the wholesale-replacement use cases listed below by walking the new source HTML against the live tree with a two-pointer aligner, preserving DOM identity, focus, and selection. Vibe-managed regions (iterations, conditionals, components, `<slot>` pairs) stay opaque. The shapes proposed below (`vibe.hydrate(el)` / `vibe.evaluate(html, state)` / `vibe.setHTML(el, html)`) were not implemented; `$.reconcile(target, source)` covers the same scenarios with a different ergonomic.
+**Original status**: Proposal
 **Priority**: Medium
 **Category**: Core Runtime
 
@@ -265,22 +266,15 @@ Likely related to:
 
 #### Resolution Path
 
-**Phase 1 (Current)**: Document and work around
-- Remove `<tutorial>` wrapper from demos
-- Add note in CLAUDE.md about limitation
-- Tests validate core reactivity works correctly
+**Recommended workaround today**: use `$.reconcile(target, source)` (shipped 1.9.0) instead of multiple raw `innerHTML` replacements. Reconcile is the supported path for wholesale HTML swaps and preserves vibe-managed regions cleanly. The original `innerHTML`-based reproduction is an unsupported pattern.
 
-**Phase 2+**: Consider fixing if real-world need emerges
-- Deep investigation into branch reference lifecycle
-- Possibly: deep clone branches instead of sharing reference
-- Possibly: rebuild conditional metadata on each innerHTML replacement
-- Possibly: manual hydration API (see "Manual Hydration API" proposal above)
+**If the bug needs a proper fix** (not yet scheduled): deep investigation into branch reference lifecycle, deep-clone the branches metadata instead of sharing references, or rebuild conditional metadata on each replacement.
 
 This is acceptable technical debt since:
 1. Edge case not representative of normal usage
 2. Core reactivity (the 99% case) works correctly
-3. Can be addressed when/if users report needing this pattern
-4. Phase 1 goals (iteration + conditionals) are met
+3. `$.reconcile` covers the wholesale-replacement scenarios that motivated this report
+4. Can be addressed if/when a real-world need to use raw `innerHTML` replacement surfaces
 
 ---
 

package/compiler/src/compiler/PRE-RENDERING-IMPLEMENTATION.md

@@ -173,7 +173,7 @@ while (walker.nextNode()) {
 - `depth = 1` when we exit nested `section.items` (line 98)
 - `depth = 0` when we exit `menuSections` (line 483) - **this is our match**
 
-**Files Modified**: `pre-compiled-manifest.rs`
+**Files Modified**: `pre-compiled-manifest.js`
 
 ---
 

package/compiler/src/compiler/compile.rs

@@ -86,6 +86,22 @@ pub fn should_skip_path(path: &Path, name: &str) -> bool {
     false
 }
 
+/// Rename `src="{component_src}"` to `data-vibe-recursive-src="{component_src}"`
+/// on `<component>` / `<div class="component">` tags. Used during cache build
+/// to neutralize cyclic refs before they reach `inline_component_elements` —
+/// the inliner's `src=` regex won't match the renamed attribute, so it stops
+/// re-expanding. `process_html_with_cache` restores the attribute to plain
+/// `src=` at the end of compilation so the runtime fetches it normally.
+fn escape_recursive_src(content: &str, component_src: &str) -> String {
+    let pattern = format!(
+        r#"(<(?:component|div)\s+[^>]*\b)src="{}""#,
+        regex::escape(component_src),
+    );
+    let re = Regex::new(&pattern).unwrap();
+    re.replace_all(content, format!(r#"$1data-vibe-recursive-src="{}""#, component_src))
+        .into_owned()
+}
+
 /// Remove FOUC prevention class and/or attribute from compiled HTML
 /// Since HTML is pre-rendered, there's no need for FOUC prevention
 fn remove_fouc_prevention(html: String) -> String {
@@ -1251,7 +1267,8 @@ impl Compiler {
             // Extract and fetch components recursively
             let components = self.extract_component_srcs(&transformed);
             for component_src in components {
-                self.fetch_component_recursive(&component_src, parser);
+                let mut visiting = std::collections::HashSet::new();
+                self.fetch_component_recursive(&component_src, parser, &mut visiting);
             }
         }
 
@@ -1288,16 +1305,31 @@ impl Compiler {
             // Extract and fetch components recursively
             let components = self.extract_component_srcs(&transformed);
             for component_src in components {
-                self.fetch_component_recursive(&component_src, parser);
+                let mut visiting = std::collections::HashSet::new();
+                self.fetch_component_recursive(&component_src, parser, &mut visiting);
             }
         }
 
         Ok(())
     }
 
-    /// Recursively fetch a component and its nested components (for inlining)
-    /// Returns the fully inlined content (all nested components resolved)
-    fn fetch_component_recursive(&mut self, component_src: &str, parser: &HtmlParser) -> Option<String> {
+    /// Recursively fetch a component and its nested components (for inlining).
+    /// Returns the fully inlined content (all nested components resolved).
+    ///
+    /// `visiting` tracks the chain of components currently being fetched. A
+    /// `<component src>` that points back into the chain is a cycle (direct
+    /// self-reference, or A→B→A) — those are valid runtime patterns (recursive
+    /// tree components bounded by data depth) but would expand infinitely at
+    /// compile time. Cycle references are escaped to `data-vibe-recursive-src`
+    /// in the cached content so the inliner's `src=` regex won't keep matching
+    /// them; `process_html_with_cache` restores the attribute name at the end
+    /// of compilation so the runtime sees a normal `<component src>` tag.
+    fn fetch_component_recursive(
+        &mut self,
+        component_src: &str,
+        parser: &HtmlParser,
+        visiting: &mut std::collections::HashSet<String>,
+    ) -> Option<String> {
         // Normalize path: ensure it starts with / (unless it's a URL)
         let normalized_src = if component_src.starts_with("http://") || component_src.starts_with("https://") {
             component_src.to_string()
@@ -1315,6 +1347,13 @@ impl Compiler {
             return Some(cached.clone());
         }
 
+        // Cycle: this component is already higher in the fetch chain. Don't
+        // recurse — the caller will leave the `<component src>` tag as-is and
+        // the runtime handles the recursion with real data bounds.
+        if visiting.contains(&normalized_src) {
+            return None;
+        }
+
         // Fetch external or read internal component (raw content)
         let content = if normalized_src.starts_with("http://") || normalized_src.starts_with("https://") {
             match self.fetch_external_component_raw(&normalized_src) {
@@ -1355,15 +1394,36 @@ impl Compiler {
             &self.config.components,
         );
 
+        // Mark this component as in-flight before recursing into its nested
+        // refs. Cycles (direct self-reference or A→B→A chains) are detected
+        // by the visiting check at the top of this function.
+        visiting.insert(normalized_src.clone());
+
         // Recursively fetch and inline all nested components
         let nested = self.extract_component_srcs(&transformed);
         for nested_src in nested {
-            if let Some(nested_content) = self.fetch_component_recursive(&nested_src, parser) {
+            if let Some(nested_content) = self.fetch_component_recursive(&nested_src, parser, visiting) {
                 // Inline this nested component into the current component
                 transformed = parser.inline_single_component(&transformed, &nested_src, &nested_content);
             }
         }
 
+        visiting.remove(&normalized_src);
+
+        // Any `<component src>` still in `transformed` whose target is in the
+        // visiting chain (a cycle) didn't get inlined. Escape its `src=` so
+        // `inline_component_elements` won't keep re-expanding it forever when
+        // a page inlines this cached content. `process_html_with_cache`
+        // restores the attribute to plain `src=` at the end of compilation so
+        // the runtime fetches it normally.
+        for ancestor in visiting.iter() {
+            transformed = escape_recursive_src(&transformed, ancestor);
+        }
+        // Also escape direct self-references — a component pointing at itself
+        // never made it into `visiting` (the cycle check short-circuited
+        // before insertion), so handle it explicitly.
+        transformed = escape_recursive_src(&transformed, &normalized_src);
+
         // Cache the fully resolved content
         self.component_cache.insert(normalized_src.clone(), transformed.clone());
 

package/compiler/src/parser/html.rs

@@ -154,7 +154,13 @@ impl HtmlParser {
             result = transform_custom_tags_to_divs(&result, reserved_elements);
         }
 
-        // Step 4: Restore DOCTYPE if it was present
+        // Step 4: Restore cyclic `<component src>` references that were
+        // escaped during cache build (see compile.rs::escape_recursive_src).
+        // These are runtime-handled component references that the inliner
+        // had to skip; the runtime needs them as real `src=` attributes.
+        result = result.replace("data-vibe-recursive-src=", "src=");
+
+        // Step 5: Restore DOCTYPE if it was present
         if let Some(dt) = doctype {
             // Remove any existing DOCTYPE that might have been left behind
             result = doctype_re.replace(&result, "").to_string();

package/llms.txt

@@ -183,6 +183,31 @@ How it works:
 
 Multi-segment paths, conditionals (`<!-- if this.editing -->`), and iterations (`<!-- each this.items as item -->`) all work. Global `$` and component-local `this.X` coexist within the same template.
 
+## Drop-In Components (Standalone Usage)
+
+`component()` auto-boots the runtime, so a `<component>` block is a fully self-contained reactive unit. Drop it into any HTML page — no top-level `vibe(...)` call, no build step, no global state setup. Import directly from a CDN:
+
+```html
+<component>
+  <script type="module">
+    import component from 'https://esm.sh/@ape-egg/vibe/component.js';
+    component({ count: 0 });
+  </script>
+  <button onclick="this.count--">-</button>
+  <span>Count: @[this.count]</span>
+  <button onclick="this.count++">+</button>
+</component>
+```
+
+Mechanism:
+1. `component({...})` claims the nearest unprocessed `<component>` (or `<div class="component">`) wrapper
+2. It calls `ensureBoot()` from `@ape-egg/vibe/boot`, which initializes `window.$`, parses the DOM, hydrates bindings, and starts the MutationObserver — exactly once per page, even if multiple drop-in blocks call `component()`
+3. `@[this.X]`, `onclick="this.fn()"`, `<!-- if this.X -->`, etc. resolve against that block's bucket
+
+Multiple drop-in blocks on the same page each get their own state and run independently. They can still read each other's state via global `$['<id>']` if coordination is needed.
+
+This makes vibe usable as a "sprinkle of reactivity" library: paste a snippet into a static site, blog post, CMS-rendered page, or third-party HTML, and it just works.
+
 ## Lifecycle Hooks
 
 ```javascript

package/package.json

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