npm - @ape-egg/vibe - Versions diffs - 1.9.0 → 1.9.1 - Mend

@ape-egg/vibe 1.9.0 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,24 @@
 # Changelog
+## [1.9.1] - 2026-04-29
+### Added
+- **Non-primitive iteration props** (`runtime/iterate.js`) — `<component src>` props inside `<!-- each -->` can now receive objects and arrays. Primitives stringify as before; non-primitives snapshot into `window.__vibeIterProps` and the attribute becomes `@[window.__vibeIterProps._pN]`, so child templates can dot/iterate into the value (`@[card.name]`, `<!-- each card.abilities as a -->`). Slots are released on wrapper detach via `releaseOrphanedIterationProps`.
+  - Test: `tests/e2e/component-in-iteration-rich-props.spec.js`
+- **Idempotent hydrate writes** (`runtime/hydrate.js`) — attribute, boolean-attribute, and text writes now compare current vs. new value and skip the write when unchanged. Eliminates needless paints and CSS-transition jitter on every re-hydrate (e.g. 4 Hz client-clock tick re-running unrelated bindings).
+  - Test: `tests/e2e/idempotent-hydrate.spec.js`
+- **Multi-segment `this.X.Y` rewriting** (`runtime/component.js`, `runtime/constants.js`) — `@[this.user.name]`, `@[this.x + 1]`, etc. inside a component now rewrite the whole `this.X` head consistently. Centralized via `THIS_PROP_REGEX` / `STATE_THIS_PROP_REGEX` so `parse.js`, `utils.js`, and `component.js` share one definition.
+- **`$.renderComponent` — pure-render path for surgical HMR** (`runtime/component.js`, `runtime/index.js`) — extracted prop substitution + slot inlining into a non-executing helper. The vite plugin uses this with `$.reconcile` to update components in place when only the template changes; scripts are not re-run, so registered component state survives.
+- **`./boot` package export** (`package.json`) — `import { boot } from '@ape-egg/vibe/boot'` is now usable from consumers.
+### Fixed
+- **Iteration-prop registry slots freed prematurely on wrapper swap** (`runtime/component.js`, `runtime/iterate.js`) — `processSingle.finalize` and the plugin's `remount` now transfer `_vibeIterPropIds` from the soon-to-be-detached element to its replacement. Without the transfer, `releaseOrphanedIterationProps` would clear registry entries that the new wrapper's bindings still reference, rendering them as `undefined`.
+- **Batch-render path stringified `<component src>` props** (`runtime/iterate.js`) — `canUseBatchRender` now skips templates containing `<component src>` so iteration items with rich props go through the clone+hydrate path that resolves them via the registry instead of through template-literal interpolation that coerces objects to `[object Object]`.
+---
 ## [1.9.0] - 2026-04-18
 ### Added

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Vibe
-**Version 1.6.0 (Alpha)** — A runtime-first reactive framework with optional compilation.
+**Version 1.9.1 (Alpha)** — 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.
@@ -25,7 +25,7 @@ The core reactive runtime. Works directly in the browser without any build tools
     <script type="module">
       import vibe from './node_modules/@ape-egg/vibe/index.js';
-      vibe({ name: 'World', count: 0 });
+      window.$ = vibe({ name: 'World', count: 0 });
     </script>
   </head>
   <body vibe-fouc>
@@ -118,6 +118,48 @@ Runtime component loading with props and slots:
 </component>
 ```
+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
+For state scoped to a single component, import `component` from `@ape-egg/vibe/component` and call it from a `<script type="module">` inside the component file:
+```html
+<!-- /components/Counter.html -->
+<script type="module">
+  import component from '@ape-egg/vibe/component';
+  component({
+    count: 0,
+    increment() { this.count++; }
+  });
+</script>
+<button onclick="this.increment()">Clicked @[this.count] times</button>
+```
+How it works:
+1. `component({...})` generates a unique id (e.g. `_c0`, `_c1`) and registers the state at `$[id]`
+2. The `<script>` and every following sibling is tagged with `data-vibe-component-id="<id>"`
+3. Inside that subtree, `@[this.X.Y]` is rewritten to `@[_c0.X.Y]` and event handlers like `onclick="this.method()"` or `oninput="$.this.value = ..."` are rewritten to address `$[id]`
+4. When the component leaves the DOM, its state entry is freed automatically
+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.
+### Lifecycle Hooks
+```javascript
+$.on('ready', () => {});            // once, after initial parse + first hydrate + all components mounted
+$.on('afterUpdate', (cur, prev) => {}); // every state change (batched per microtask)
+$.on('afterDomMutation', () => {});  // after every MutationObserver batch
+```
+`$.ready` is also exposed as a Promise (`await $.ready`), useful for code that captured `window.$` before boot.
+### Subtree Reconciliation (advanced)
+`$.reconcile(el, html)` and `$.renderComponent(rawHtml, props, slot, opts)` are public-but-advanced APIs used by the vite plugin's HMR path. Their shape may evolve; treat them as plumbing rather than application code for now.
 ### Dehydrate
 Skip reactive processing for an element:

package/llms.txt CHANGED Viewed

@@ -9,9 +9,12 @@ Vibe is a lightweight reactive library that uses Proxy-based state and MutationO
 **Key characteristics:**
 - Proxy-based reactive state (`window.$`)
 - Deep reactivity (nested mutations automatically trigger updates)
-- Surgical DOM updates (only affected elements re-render)
+- Surgical DOM updates (only affected elements re-render; idempotent writes skip no-op DOM mutations)
+- State batching (multiple `$.x = y` writes in the same microtask flush as one update)
 - MutationObserver for dynamic element tracking
-- Works with vanilla HTML - no special file format
+- Works with vanilla HTML — no special file format
+- Component-local state via `component({...})` + `this.X`
+- Component composition via `<component src>` with reactive props (objects/arrays/primitives) and slots
 ## Installation
@@ -23,19 +26,21 @@ npm install @ape-egg/vibe
 ```html
 <script type="module">
-  import state from "@ape-egg/vibe";
-  window.$ = state({ name: "World", count: 0 });
+  import vibe from "@ape-egg/vibe";
+  window.$ = vibe({ name: "World", count: 0 });
 </script>
-<h1>Hello, @[name]!</h1>
-<button onclick="$.count++">Clicked @[count] times</button>
+<body vibe-fouc>
+  <h1>Hello, @[name]!</h1>
+  <button onclick="$.count++">Clicked @[count] times</button>
+</body>
 ```
 ## Core Syntax
 ### Reactive Bindings
-Use `@[property]` syntax anywhere in HTML or CSS:
+Use `@[expression]` syntax anywhere in HTML or CSS:
 ```html
 <!-- Text content -->
@@ -44,11 +49,15 @@ Use `@[property]` syntax anywhere in HTML or CSS:
 <!-- Expressions -->
 <div>@[firstName + ' ' + lastName]</div>
 <div>@[count * 2]</div>
+<div>@[items.filter(x => x.active).length]</div>
 <!-- Attributes -->
 <input value="@[inputValue]">
 <button disabled="@[isLoading]">Submit</button>
+<!-- Attribute names (name bindings) -->
+<icon @[iconName]></icon>
 <!-- CSS -->
 <style>
   .box { background: @[themeColor]; }
@@ -65,7 +74,7 @@ State is accessed globally via `window.$`:
 // Read
 console.log($.firstName);
-// Write (triggers re-render)
+// Write (triggers re-render — batched per microtask)
 $.firstName = "John";
 // Increment
@@ -97,9 +106,17 @@ With index:
 <!-- /each -->
 ```
+The expression after `each` is any JavaScript that returns an array or array-like:
+```html
+<!-- each items.filter(x => x.active) as item -->
+<!-- each Array.from({length: 10}, (_, i) => i) as n -->
+<!-- each Object.values(users) as user, i -->
+```
 ### Nested Iteration
-Use dot paths for nested arrays:
+Use dot paths or any expression:
 ```html
 <!-- each categories as category -->
@@ -122,71 +139,103 @@ Use dot paths for nested arrays:
 Conditionals can be nested inside iterations and vice versa.
-## Special Attributes
+## Components
-### Dehydrate
+```html
+<component src="/components/card.html" title="@[pageTitle]" theme="dark">
+  <p>This content replaces &lt;slot&gt;&lt;/slot&gt;</p>
+</component>
+```
-Skip reactive processing for an element and its children:
+**Behavior:**
+1. Vibe finds `<component src="...">` elements (also `<div class="component" src="...">`)
+2. Fetches the source HTML
+3. Substitutes props (`@[title]` in the template becomes `@[pageTitle]`)
+4. Inserts slot content (between the tags) into `<slot></slot>`
+5. Removes `src`; the `<component>` wrapper remains as a boundary marker
+**Reactive props** (`title="@[pageTitle]"`) keep tracking the parent's state. **Static props** (`theme="dark"`) inline as literals. **Object/array props** through iteration scope (`<component card="@[card]">` inside `<!-- each cards as card -->`) are stashed in an internal registry so child templates can `@[card.name]` or `<!-- each card.abilities as a -->`.
+**Two-way binding** falls out for free: a child component that writes `$.value = x` in an event handler has that `$.value` rewritten to the parent's bound path, so the parent's state actually updates.
+**Slot content** that itself contains `<component src>` is also processed recursively.
+## Component-Local State
+For state scoped to a single component (form drafts, toggles, derived view-state) instead of global `$`:
 ```html
-<code vibe-dehydrate>@[this] displays literally, not parsed</code>
+<!-- /components/Counter.html -->
+<script type="module">
+  import component from '@ape-egg/vibe/component';
+  component({ count: 0, increment() { this.count++; } });
+</script>
+<button onclick="this.increment()">Clicked @[this.count] times</button>
 ```
-Use cases:
-- Displaying `@[...]` syntax in documentation
-- Static content that shouldn't be reactive
-- Performance optimization for large static sections
+How it works:
-### Boolean Attributes
+1. `component({...})` generates a unique id (e.g. `_c0`) and stores state at `$[id]`
+2. The `<script>` and every following sibling get `data-vibe-component-id="<id>"`
+3. Inside that subtree, `@[this.X.Y]` is rewritten to `@[_c0.X.Y]`; `onclick="this.fn()"` becomes `onclick="$['_c0'].fn()"`; `$.this.x = v` (in event handlers) becomes `$['_c0'].x = v`
+4. When the component leaves the DOM, its bucket is freed automatically
-Attributes not in the value whitelist are removed when falsy:
+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.
-```html
-<button disabled="@[isLoading]">Submit</button>
-<!-- When isLoading is false, disabled attribute is removed entirely -->
+## Lifecycle Hooks
+```javascript
+$.on('ready', () => {});                  // once, after initial parse + hydrate + components mounted
+$.on('afterUpdate', (cur, prev) => {});   // every state change (batched per microtask)
+$.on('afterDomMutation', () => {});       // after every MutationObserver batch
 ```
-## Events
+Also: `await $.ready` resolves after boot, useful when calling code captured `window.$` before vibe finished initializing.
+## Special Attributes
+### vibe-fouc
-Use standard inline event handlers:
+Add to an element (typically `<body>`) to hide it until Vibe's first hydration completes. Vibe removes the attribute when ready.
 ```html
-<button onclick="$.count++">Increment</button>
-<input oninput="$.text = this.value">
-<form onsubmit="event.preventDefault(); handleSubmit()">
+<body vibe-fouc>
 ```
-## Styling
+Pair with `vibe.css` (`<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">`) which targets `[vibe-fouc]` with `visibility: hidden`.
-### CSS Bindings
+### vibe-dehydrate
-Reactive values work inside `<style>` tags:
+Skip reactive processing for an element and its children:
 ```html
-<style>
-  .box {
-    background: @[backgroundColor];
-    color: @[textColor];
-    width: @[width]px;
-  }
-</style>
+<code vibe-dehydrate>@[this] displays literally, not parsed</code>
 ```
-### Preventing FOUC
+Use cases: documenting `@[...]` syntax, large static sections, content that must not be evaluated.
+### Boolean Attributes
-Hide content until hydration completes:
+Pure-binding attributes that aren't in the value whitelist (e.g. `disabled`, `checked`, `active`) are added when truthy and removed when falsy:
 ```html
-<body style="visibility: hidden;">
+<button disabled="@[isLoading]">Submit</button>
+<!-- isLoading=false → attribute removed entirely -->
 ```
-Or use the included CSS:
+## Events
+Use standard inline event handlers — they execute against `$` directly:
 ```html
-<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
-<body vibe-fouc>
+<button onclick="$.count++">Increment</button>
+<input oninput="$.text = this.value">
+<form onsubmit="event.preventDefault(); handleSubmit()">
 ```
+Inside a component, `this.X` references the component's bucket (rewritten at parse time); `this.value`, `this.checked`, `this.dataset` etc. still reach the DOM element since DOM properties are preserved.
 ## Dynamic Elements
 Elements added via JavaScript are automatically hydrated through MutationObserver:
@@ -200,33 +249,47 @@ document.body.appendChild(div);
 ## API Reference
-### `state(initialState, afterUpdate?)`
+### `vibe(initialState, config?)`
-Creates reactive state and initializes the framework.
+Initializes the framework and returns the reactive state proxy.
 ```javascript
-import state from "@ape-egg/vibe";
+import vibe from "@ape-egg/vibe";
-window.$ = state(
+window.$ = vibe(
   { count: 0, user: { name: "Alice" } },
-  (newState, oldState) => {
-    console.log("State updated:", newState);
-  }
+  { debug: false }
 );
 ```
 **Parameters:**
-- `initialState` - Object containing initial state values
-- `afterUpdate` - Optional callback after each state change (receives read-only snapshots)
+- `initialState` — object containing initial state values
+- `config` — optional object. Currently supports `{ debug: boolean }`. A third positional argument can pass a target selector (defaults to `body`).
+**Returns:** Reactive proxy. Assign it to `window.$` so inline event handlers and bindings can find it.
+### `component(initialState)`
+Imported from `@ape-egg/vibe/component`. Registers a component-local state bucket; called from inside a `<script type="module">` in a component file. See [Component-Local State](#component-local-state).
-**Returns:** Proxy object for reactive state access
+### `$.on(event, callback)`
-## Scoped Variables
+Register a lifecycle listener. Events: `'ready'`, `'afterUpdate'`, `'afterDomMutation'`. Listeners registered before boot are queued and replayed once vibe is ready.
+### `$.ready`
+A Promise that resolves once vibe has finished initial parse + hydrate + component loading.
+### `$.reconcile(el, html)` and `$.renderComponent(rawHtml, props, slot, opts)` (advanced)
+Subtree reconciliation primitives used by `@ape-egg/vite-plugin-vibe` for surgical HMR. `$.reconcile` diffs `el`'s children against fresh `html` while preserving DOM identity, focus, and selection; vibe-managed regions (iterations, conditionals, components, slot pairs) are treated as opaque. Treat these as plumbing — shape may evolve.
+## Scoped Variables in Iterations
 Inside `<!-- each -->` blocks, these variables are available:
-- `item` (or custom name) - current array element
-- `index` (or custom name) - current index
-- Parent state remains accessible via `$`
+- `item` (or custom name) — current array element
+- `index` (or custom name) — current index
+- Parent state remains accessible via `$` and via free identifiers (e.g. `tutorialProgress`)
 ```html
 <!-- each users as user, i -->
@@ -236,7 +299,7 @@ Inside `<!-- each -->` blocks, these variables are available:
 ### Scoped State (Internal)
-Each iteration instance stores a `scopedState` - a Proxy wrapper that provides access to both local variables (`item`, `index`) and global state. This enables reactive updates inside iterations:
+Each iteration instance stores a `scopedState` Proxy that combines local variables (`item`, `index`) with global state. This lets bindings inside iterations react to global state changes:
 ```html
 <!-- each menuItems as item -->
@@ -246,50 +309,50 @@ Each iteration instance stores a `scopedState` - a Proxy wrapper that provides a
 <!-- /each -->
 ```
-When `tutorialProgress` changes, Vibe:
-1. Finds affected elements inside iteration instances
-2. Uses that instance's `scopedState` for evaluation
-3. Can access both `item` (local) and `tutorialProgress` (global)
-4. Updates only the affected elements without re-rendering the entire iteration
+When `tutorialProgress` changes, vibe finds affected elements inside iteration instances, evaluates against that instance's `scopedState`, and updates only the changed elements without re-rendering the whole list.
 ## Architecture
-Vibe consists of these core modules:
+Vibe consists of these core runtime modules (in `runtime/`):
-- **state.js** - Proxy-based reactive state container with recursive proxies for deep reactivity
-- **parse.js** - DOM parser that finds `@[...]` bindings
-- **link.js** - Maps elements to parsed tree nodes
-- **hydrate.js** - Updates DOM with current state values (supports scoped state for iterations)
-- **affected.js** - Determines which elements need updating (walks iteration instances with scoped state)
-- **iterate.js** - Array rendering with efficient diffing (stores scoped state per instance)
-- **conditionals.js** - Conditional block rendering
+- **state.js** — Proxy-based reactive state, recursive proxies for deep reactivity, batched flush via `queueMicrotask`
+- **parse.js** — DOM parser that finds `@[...]` bindings, iteration/conditional comments, and `<component src>` elements
+- **manifest.js** — Maps DOM elements to parsed-tree nodes (was `link.js` in older versions)
+- **hydrate.js** — Updates DOM with current state values; idempotent (skips no-op writes)
+- **affected.js** — Determines which bindings need re-evaluation when state changes
+- **iterate.js** — Array rendering with diffing; bulk-replacement fast path; iteration-prop registry for non-primitive component props
+- **conditionals.js** — Conditional block rendering; preserves both branches in the manifest for reactive switching
+- **component.js** — `<component src>` fetching, prop substitution, slot inlining, component-local state setup, `this.X` rewriting
+- **reconcile.js** — Subtree reconciliation primitive (`$.reconcile`)
+- **cleanup.js** — `vibe-fouc` release once a subtree is fully processed
 ## How It Works
 ```
-1. state() initializes the Proxy and framework
-2. parse.js scans DOM for @[...], <!-- each -->, <!-- if -->
-3. link.js maps elements to the parsed tree
+1. vibe(initialState) creates the Proxy and starts the runtime
+2. parse.js scans DOM for @[...], <!-- each -->, <!-- if -->, <component src>
+3. manifest.js maps elements → parsed tree
 4. hydrate.js replaces bindings with values
 5. iterate.js renders <!-- each --> loops
 6. conditionals.js renders <!-- if --> blocks
-7. MutationObserver watches for new elements
-8. On state change: affected.js finds changed elements → hydrate.js updates them
+7. component.js fetches <component src> templates, substitutes props, inlines slots
+8. MutationObserver watches for new/removed elements; affected.js + hydrate.js handle state changes
 ```
 ## Current Limitations
-- **No computed values**: Derived state must be calculated manually
-- **No two-way binding sugar**: Must wire input events manually
-- **Expression security**: `new Function()` evaluation - don't bind untrusted input
+- **No computed values primitive**: derived state can be done with `Object.defineProperty($, 'x', { get })` or with `afterUpdate` listeners; a first-class `computed` API isn't shipped
+- **Expression security**: `new Function()` evaluation — don't bind untrusted input
+- **HTML binding**: `@[expr]` always sets `textContent` (escape-safe). A first-class opt-in for trusted HTML is planned but not finalized
 ## Best Practices
-1. **Initialize state before DOM**: Place `<script>` in `<head>` or before reactive elements
-2. **Use dehydrate for docs**: When showing `@[...]` syntax examples
-3. **Prevent FOUC**: Use `visibility: hidden` on body until hydration
-4. **Keep expressions simple**: Complex logic belongs in JavaScript, not templates
-5. **Mutate freely**: Deep reactivity means `$.user.name = "New"` just works - no spread operators needed
+1. **Initialize state in `<head>`** before reactive elements; pair with `vibe-fouc` on `<body>`
+2. **Mutate freely** — deep reactivity means `$.user.name = "New"` just works; no spread operators needed
+3. **Use lifecycle hooks instead of `setTimeout` / `requestAnimationFrame`** when you need to wait for vibe to finish work
+4. **Use `component({...})` for state that's local to one piece of UI** (form draft, toggle); keep cross-cutting state on global `$`
+5. **Use `vibe-dehydrate` when you need to display `@[...]` literally** (docs, code examples)
+6. **Keep expressions simple** — complex logic belongs in JavaScript; templates should read like HTML
 ## Browser Support
@@ -298,6 +361,10 @@ Modern browsers with:
 - MutationObserver
 - ES Modules
+## Related Packages
+- **`@ape-egg/vite-plugin-vibe`** — Vite plugin with surgical component HMR (template-only edits reconcile in place; script edits re-mount)
 ## Resources
 - **Homepage**: https://vibe.korte.kim

package/package.json CHANGED Viewed

@@ -1,12 +1,13 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
   "homepage": "https://vibe.korte.kim",
   "exports": {
     ".": "./index.js",
+    "./boot": "./boot.js",
     "./component": "./component.js",
     "./runtime": "./runtime/index.js",
     "./compiler": "./compiler/bin/vibe-compile.js"

package/runtime/component.js CHANGED Viewed

@@ -1,5 +1,11 @@
 import { debugLog } from './debug.js';
-import { PHASE_FETCH, DEHYDRATE_CLASS_OR_ATTR, BINDING_REGEX } from './constants.js';
+import {
+  PHASE_FETCH,
+  DEHYDRATE_CLASS_OR_ATTR,
+  BINDING_REGEX,
+  THIS_PROP_REGEX,
+  STATE_THIS_PROP_REGEX,
+} from './constants.js';
 import { evalInScope } from './utils.js';
 // Deterministic component counter
@@ -79,6 +85,162 @@ const isNestedInUnprocessedComponent = (el, rootElement) => {
   return false;
 };
+// Rewrite `@[this.x...]` and `$.this.x...` inside element's text/attrs to use
+// componentId. Shared between script-execution path and pure-render path.
+//
+// Within `@[...]` bindings we rewrite every `this.X` reference (preserving
+// any trailing `.Y.Z` chain), so `@[this.user.name]` and `@[this.x + 1]` both
+// resolve correctly. Outside bindings — i.e. event handler attribute bodies
+// like `onclick="$.this.mode = 'edit'"` — only `$.this.X` writes are
+// rewritten; bare `this.X` reads in event handlers are handled later by
+// parse.js (which preserves DOM properties like `this.value`).
+const rewriteBindingsInString = (str, componentId) =>
+  str.replace(BINDING_REGEX, (match, expr) => {
+    const rewritten = expr.replace(THIS_PROP_REGEX, `${componentId}.$1`);
+    return rewritten === expr ? match : `@[${rewritten}]`;
+  });
+const rewriteThisBindings = (element, componentId) => {
+  Array.from(element.childNodes).forEach((node) => {
+    if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('@[this.')) {
+      node.textContent = rewriteBindingsInString(node.textContent, componentId);
+    }
+  });
+  Array.from(element.attributes || []).forEach((attr) => {
+    if (attr.value.includes('@[this.')) {
+      attr.value = rewriteBindingsInString(attr.value, componentId);
+    }
+    if (attr.value.includes('$.this.')) {
+      attr.value = attr.value.replace(STATE_THIS_PROP_REGEX, `$.${componentId}.$1`);
+    }
+  });
+  Array.from(element.children).forEach((child) => {
+    rewriteThisBindings(child, componentId);
+  });
+};
+// Tag siblings of a <script> with componentId and rewrite `this.` bindings.
+// Runs BEFORE script.remove() so nextElementSibling is valid. Shared by
+// processSingle (executing path) and renderComponentTemplate (pure path).
+const tagScriptSiblings = (script, componentId) => {
+  let sibling = script.nextElementSibling;
+  while (sibling) {
+    if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
+      break;
+    }
+    sibling.setAttribute('data-vibe-component-id', componentId);
+    rewriteThisBindings(sibling, componentId);
+    sibling = sibling.nextElementSibling;
+  }
+};
+// Substitute props + inline slot content into a pre-processed temp container.
+// Returns the final processed HTML string. Shared by processSingle.finalize()
+// (runtime mount) and renderComponentTemplate (surgical HMR).
+const renderPropsAndSlot = (temp, props, slotHtml) => {
+  let transformedHtml = temp.innerHTML;
+  const DIRECTIVE_COMMENT_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
+  const EVENT_ATTR_REGEX = /\bon(\w+)="([^"]*)"/g;
+  Object.entries(props).forEach(([propName, propValue]) => {
+    const bindingMatch = propValue.match(/^@\[(.+)\]$/);
+    const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
+    const idRegex = new RegExp(
+      `(?<![a-zA-Z0-9_$\\.])${escapeRegex(propName)}(?![a-zA-Z0-9_$])`,
+      'g'
+    );
+    const substituteInExpr = (expr, replacement) => expr.replace(idRegex, replacement);
+    if (bindingMatch) {
+      const path = bindingMatch[1];
+      transformedHtml = transformedHtml.replace(exactPattern, `@[${path}]`);
+      transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
+        const rewritten = substituteInExpr(expr, `(${path})`);
+        return rewritten === expr ? match : `@[${rewritten}]`;
+      });
+      transformedHtml = transformedHtml.replace(
+        DIRECTIVE_COMMENT_REGEX,
+        (match, kw, expr) => {
+          const replacement = kw === 'each' ? path : `(${path})`;
+          const rewritten = substituteInExpr(expr, replacement);
+          return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
+        }
+      );
+      const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
+      transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
+        const rewritten = body.replace(stateRegex, `$.${path}`);
+        return rewritten === body ? match : `on${evName}="${rewritten}"`;
+      });
+    } else {
+      transformedHtml = transformedHtml.replace(exactPattern, propValue);
+      const isNumeric =
+        typeof propValue === 'string' && /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i.test(propValue);
+      const isBooleanAttr = propValue === '';
+      const literal = isBooleanAttr
+        ? 'true'
+        : typeof propValue === 'string' && !isNumeric
+          ? JSON.stringify(propValue)
+          : String(propValue);
+      transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
+        const rewritten = substituteInExpr(expr, literal);
+        return rewritten === expr ? match : `@[${rewritten}]`;
+      });
+      transformedHtml = transformedHtml.replace(
+        DIRECTIVE_COMMENT_REGEX,
+        (match, kw, expr) => {
+          const rewritten = substituteInExpr(expr, literal);
+          return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
+        }
+      );
+      const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
+      transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
+        const rewritten = body.replace(stateRegex, `$.${literal}`);
+        return rewritten === body ? match : `on${evName}="${rewritten}"`;
+      });
+    }
+  });
+  const children = (slotHtml || '').trim();
+  if (children) {
+    transformedHtml = transformedHtml.replace(
+      /<slot(\s[^>]*)?>\s*<\/slot>/g,
+      (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
+    );
+    transformedHtml = transformedHtml.replace(
+      /<slot(\s[^>]*)?\/>/g,
+      (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
+    );
+  }
+  return transformedHtml;
+};
+// Pure-render path for surgical HMR. Takes a component's raw template HTML
+// plus the live instance's props, slot, and existing componentIds. Returns
+// the processed HTML string that $.reconcile can diff against the live
+// wrapper's children. Scripts are NOT executed — callers are responsible
+// for deciding whether to preserve the existing state (reuse componentIds)
+// or trigger a full re-mount (new componentIds).
+export const renderComponentTemplate = (rawHtml, props = {}, slotHtml = '', options = {}) => {
+  const { componentIds = [] } = options;
+  const temp = document.createElement('div');
+  temp.innerHTML = rawHtml;
+  const idsToReuse = [...componentIds];
+  const moduleScripts = temp.querySelectorAll('script[type="module"]');
+  for (const script of moduleScripts) {
+    const componentId = idsToReuse.shift() || generateComponentId();
+    tagScriptSiblings(script, componentId);
+    script.remove();
+  }
+  return renderPropsAndSlot(temp, props, slotHtml);
+};
 // Process a single component element: fetch HTML, execute scripts, replace DOM
 const processSingle = (el, debug) => {
   // Skip dehydrated components
@@ -182,49 +344,9 @@ const processSingle = (el, debug) => {
           console.warn('[vibe] Failed to execute component script:', e);
         }
-        // Rewrite this.property to componentId.property in siblings.
-        // Handles both reads (@[this.x]) and writes ($.this.x in event handlers)
-        // so component() state is fully accessible from the component's own template.
-        const rewriteThisBindings = (element) => {
-          const bindingRegex = /@\[this\.(\w+)\]/g;
-          const writeRegex = /\$\.this\.(\w+)/g;
-          // Rewrite in text nodes
-          Array.from(element.childNodes).forEach((node) => {
-            if (node.nodeType === Node.TEXT_NODE && node.textContent.includes('@[this.')) {
-              node.textContent = node.textContent.replace(bindingRegex, `@[${componentId}.$1]`);
-            }
-          });
-          // Rewrite in attributes — both @[this.x] bindings and $.this.x in event handlers
-          Array.from(element.attributes || []).forEach((attr) => {
-            if (attr.value.includes('@[this.')) {
-              attr.value = attr.value.replace(bindingRegex, `@[${componentId}.$1]`);
-            }
-            if (attr.value.includes('$.this.')) {
-              attr.value = attr.value.replace(writeRegex, `$.${componentId}.$1`);
-            }
-          });
-          // Recurse into children
-          Array.from(element.children).forEach((child) => {
-            rewriteThisBindings(child);
-          });
-        };
-        // Tag siblings with componentId and rewrite this. bindings.
-        // This runs BEFORE script.remove() so nextElementSibling is valid.
-        // For async scripts, componentFn runs later (after removal) and can't
-        // find siblings — so we tag here instead.
-        let sibling = script.nextElementSibling;
-        while (sibling) {
-          if (sibling.tagName === 'SCRIPT' && sibling.getAttribute('type') === 'module') {
-            break;
-          }
-          sibling.setAttribute('data-vibe-component-id', componentId);
-          rewriteThisBindings(sibling);
-          sibling = sibling.nextElementSibling;
-        }
+        // Tag siblings + rewrite this. bindings using shared helper. Runs
+        // BEFORE script.remove() so nextElementSibling is valid.
+        tagScriptSiblings(script, componentId);
         // Remove script from temp (we executed it manually)
         script.remove();
@@ -232,106 +354,8 @@ const processSingle = (el, debug) => {
       // Finalize: props, slots, DOM replacement
       const finalize = () => {
-        // Get transformed HTML from temp container (scripts removed)
-        let transformedHtml = temp.innerHTML;
-        // Replace props — both exact @[propName] bindings and identifiers
-        // appearing inside larger expressions like @[Math.floor(propName / 100)]
-        // or conditional/iteration comment expressions like <!-- if propName -->.
-        // Matches any <!-- if ... -->, <!-- else if ... -->, or <!-- each ... -->
-        // so prop identifiers resolve there the same way they do inside @[...].
-        const DIRECTIVE_COMMENT_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
-        // Event handler attributes (onclick, oninput, onchange, …). Prop
-        // identifiers inside these are JS expressions that read/write state —
-        // substituting them gives components natural two-way binding:
-        // child writes `$.value = x`, parent passed `value="@[email]"`,
-        // substitution turns it into `$.email = x`.
-        const EVENT_ATTR_REGEX = /\bon(\w+)="([^"]*)"/g;
-        Object.entries(props).forEach(([propName, propValue]) => {
-          const bindingMatch = propValue.match(/^@\[(.+)\]$/);
-          const exactPattern = new RegExp(`@\\[${escapeRegex(propName)}\\]`, 'g');
-          // Word-boundary identifier match for substitution inside expressions.
-          // The lookbehind also excludes `.` so property accesses like `_c0.email`
-          // aren't double-substituted when the prop name is `email` — only
-          // standalone identifiers match, not property tails.
-          const idRegex = new RegExp(
-            `(?<![a-zA-Z0-9_$\\.])${escapeRegex(propName)}(?![a-zA-Z0-9_$])`,
-            'g'
-          );
-          const substituteInExpr = (expr, replacement) => expr.replace(idRegex, replacement);
-          if (bindingMatch) {
-            // Reactive prop: @[propName] → @[path], identifiers inside expressions → (path)
-            const path = bindingMatch[1];
-            transformedHtml = transformedHtml.replace(exactPattern, `@[${path}]`);
-            transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
-              const rewritten = substituteInExpr(expr, `(${path})`);
-              return rewritten === expr ? match : `@[${rewritten}]`;
-            });
-            transformedHtml = transformedHtml.replace(
-              DIRECTIVE_COMMENT_REGEX,
-              (match, kw, expr) => {
-                const replacement = kw === 'each' ? path : `(${path})`;
-                const rewritten = substituteInExpr(expr, replacement);
-                return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
-              }
-            );
-            // Event handlers: rewrite `$.propName` → `$.path` for two-way
-            // binding. Only targets state access (`$.xxx`) so DOM properties
-            // like `this.value` stay untouched.
-            const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
-            transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
-              const rewritten = body.replace(stateRegex, `$.${path}`);
-              return rewritten === body ? match : `on${evName}="${rewritten}"`;
-            });
-          } else {
-            // Static prop: @[propName] → literal value (raw),
-            // identifiers inside expressions → JS literal.
-            transformedHtml = transformedHtml.replace(exactPattern, propValue);
-            const isNumeric =
-              typeof propValue === 'string' && /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i.test(propValue);
-            const isBooleanAttr = propValue === '';
-            const literal = isBooleanAttr
-              ? 'true'
-              : typeof propValue === 'string' && !isNumeric
-                ? JSON.stringify(propValue)
-                : String(propValue);
-            transformedHtml = transformedHtml.replace(BINDING_REGEX, (match, expr) => {
-              const rewritten = substituteInExpr(expr, literal);
-              return rewritten === expr ? match : `@[${rewritten}]`;
-            });
-            transformedHtml = transformedHtml.replace(
-              DIRECTIVE_COMMENT_REGEX,
-              (match, kw, expr) => {
-                const rewritten = substituteInExpr(expr, literal);
-                return rewritten === expr ? match : `<!-- ${kw} ${rewritten} -->`;
-              }
-            );
-            // Event handlers: rewrite `$.propName` → `$.literal` for static props
-            const stateRegex = new RegExp(`\\$\\.${escapeRegex(propName)}(?![a-zA-Z0-9_$])`, 'g');
-            transformedHtml = transformedHtml.replace(EVENT_ATTR_REGEX, (match, evName, body) => {
-              const rewritten = body.replace(stateRegex, `$.${literal}`);
-              return rewritten === body ? match : `on${evName}="${rewritten}"`;
-            });
-          }
-        });
-        // Replace <slot> with children wrapped in <slot> boundary.
-        // Allow attributes on the slot (e.g. data-vibe-component-id added by
-        // sibling tagging when a <slot> happens to be a direct sibling of the
-        // component's <script>).
-        if (children) {
-          transformedHtml = transformedHtml.replace(
-            /<slot(\s[^>]*)?>\s*<\/slot>/g,
-            (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
-          );
-          transformedHtml = transformedHtml.replace(
-            /<slot(\s[^>]*)?\/>/g,
-            (_, attrs) => `<slot${attrs || ''}>${children}</slot>`
-          );
-        }
+        // Delegate prop substitution + slot inlining to shared helper.
+        const transformedHtml = renderPropsAndSlot(temp, props, children);
         // Clean up pending fetch tracker
         pendingFetches.delete(el);
@@ -350,6 +374,24 @@ const processSingle = (el, debug) => {
           }
           newWrapper.innerHTML = transformedHtml;
+          // Stash the raw source so the HMR plugin can establish a baseline
+          // script hash on the very first update — without this, the first
+          // save after page load would always fall back to re-mount (since
+          // the plugin would have nothing to compare against). Vibe itself
+          // never reads this; it's purely for the plugin spy.
+          newWrapper._vibeRawSource = html;
+          // Transfer iteration-prop registry ownership from the soon-to-be-
+          // detached `<component src>` to the new wrapper. The detached element
+          // would otherwise trigger releaseOrphanedIterationProps and free the
+          // registry slots that the inlined template's bindings still reference,
+          // causing every `@[window.__vibeIterProps._pN]` to resolve to undefined
+          // on the next hydrate.
+          if (el._vibeIterPropIds) {
+            newWrapper._vibeIterPropIds = el._vibeIterPropIds;
+            newWrapper.setAttribute('data-vibe-iter-prop', '');
+            el._vibeIterPropIds = null;
+            el.removeAttribute('data-vibe-iter-prop');
+          }
           el.replaceWith(newWrapper);
           debugLog(PHASE_FETCH, src, debug);

package/runtime/constants.js CHANGED Viewed

@@ -224,3 +224,15 @@ export const CONDITIONAL_REGEX = /^if\s+(.+)$/;
 // Regex for detecting start of conditional comment
 export const CONDITIONAL_START_REGEX = /^if\s+/;
+// Regex for rewriting component-local `this.X` references to the component's
+// state path. Captures the leading identifier only — any trailing `.Y.Z`
+// chain stays attached after replacement, so `this.user.name` becomes
+// `<componentId>.user.name`. Used in expression bodies (bindings, event
+// handlers, conditional/iteration directives).
+export const THIS_PROP_REGEX = /\bthis\.(\w+)/g;
+// Regex for rewriting `$.this.X` writes (proxy assignment from event handlers)
+// to the component's write path. Same prefix-only semantics as THIS_PROP_REGEX
+// — `$.this.user.name = x` becomes `$.<componentId>.user.name = x`.
+export const STATE_THIS_PROP_REGEX = /\$\.this\.(\w+)/g;

package/runtime/hydrate.js CHANGED Viewed

@@ -87,17 +87,24 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           // Attribute: Truthful DOM representation, enables compiler snapshots via outerHTML
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
-          element[attrName] = value;
+          if (element[attrName] !== value) element[attrName] = value;
           if (value !== undefined && value !== null) {
-            element.setAttribute(attrName, String(value));
+            const str = String(value);
+            if (element.getAttribute(attrName) !== str) element.setAttribute(attrName, str);
           }
         } else if (!isValueAttr && isPureBinding) {
-          // Boolean-like attributes: add or remove based on truthiness
+          // Boolean-like attributes: add or remove based on truthiness.
+          // Compare both presence AND value — initial hydration starts with
+          // the raw `@[...]` binding text as the attribute value, so
+          // `hasAttribute` alone isn't enough to know the canonical state is
+          // already set.
           const expr = isPureBinding[1];
           const value = evalInScope(expr, effectiveState, element);
           if (value) {
-            element.setAttribute(attrName, '');
-          } else {
+            if (element.getAttribute(attrName) !== '') {
+              element.setAttribute(attrName, '');
+            }
+          } else if (element.hasAttribute(attrName)) {
             element.removeAttribute(attrName);
           }
         } else {
@@ -105,7 +112,9 @@ export default (affected, state, manifest = {}, oldState = {}) => {
           const newValue = attrValue.replace(BINDING_REGEX, (_, expr) => {
             return evalInScope(expr, effectiveState, element);
           });
-          element.setAttribute(attrName, newValue);
+          if (element.getAttribute(attrName) !== newValue) {
+            element.setAttribute(attrName, newValue);
+          }
         }
       } catch (e) {}
       return;
@@ -128,11 +137,19 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       });
       // If we have a direct reference to the text node, update it specifically
-      // This prevents wiping child elements when parent has both text and element children
+      // This prevents wiping child elements when parent has both text and element children.
+      // Skip the write when the value is already correct — the browser would repaint
+      // (and any in-flight CSS transition on the row would jitter) even when no value
+      // actually changed. Reactivity coverage is unchanged: the only state changes that
+      // hit this path either produce a new value (still applied) or don't (now no-op).
+      // Skip the write when the value is already correct — the browser would
+      // repaint (and any in-flight CSS transition would jitter) even when no
+      // value actually changed. Reactivity coverage is unchanged: state changes
+      // that produce a new value still apply; state changes that don't are now
+      // proper no-ops at the DOM layer.
       if (textNode && textNode.nodeType === 3) {
-        textNode.textContent = toReplace;
-      } else {
-        // Fallback: element has no children or is just a text container
+        if (textNode.textContent !== toReplace) textNode.textContent = toReplace;
+      } else if (element.textContent !== toReplace) {
         element.textContent = toReplace;
       }
     } catch (e) {}

package/runtime/index.js CHANGED Viewed

@@ -4,7 +4,7 @@ import createManifest from './manifest.js';
 import hydrate from './hydrate.js';
 import affected from './affected.js';
 import { deepMerge, hash } from './utils.js';
-import { renderAllIterations, setRenderAllConditionals } from './iterate.js';
+import { renderAllIterations, setRenderAllConditionals, releaseOrphanedIterationProps } from './iterate.js';
 import { renderAllConditionals, branchNodeRegistry, managedNodes } from './conditionals.js';
 import {
   NON_REACTIVE_ELEMENTS,
@@ -21,7 +21,7 @@ import {
   PHASE_READY,
   DEHYDRATE_CLASS_OR_ATTR,
 } from './constants.js';
-import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState } from './component.js';
+import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate } from './component.js';
 import { debugLog } from './debug.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
 import { reconcile } from './reconcile.js';
@@ -634,6 +634,16 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
+  // Pure-render path for surgical component HMR. Given raw component template
+  // HTML, callsite props, slot HTML, and existing componentIds, returns the
+  // processed HTML string the plugin's HMR handler can hand to $.reconcile.
+  // Scripts are NOT executed — callers use this only when they've verified
+  // script contents haven't changed (so registered state is still valid).
+  Object.defineProperty($, 'renderComponent', {
+    value: renderComponentTemplate,
+    enumerable: false,
+  });
   // Initial hydration - pass plain values so iteration can do reference comparison
   const initialState = extractPlainValue($);
   const affectedElements = affected(parsedTree, initialState, initialState);
@@ -864,6 +874,9 @@ const main = (s, config = {}, stringSelector = '') => {
     // CLEANUP OF CURRENT STATE
     releaseOrphanedComponentState(removedComponentIds);
+    mutations.forEach(({ removedNodes: removedNodesList }) => {
+      releaseOrphanedIterationProps(removedNodesList);
+    });
     // Fire hooks once after all mutations are processed (not per-node)
     if (hadChanges) {

package/runtime/iterate.js CHANGED Viewed

@@ -35,8 +35,18 @@ const hasNestedStructures = (tree) => {
   return false;
 };
+// Batch render template-literal-interpolates `@[expr]` as `${expr}` — that
+// stringifies object/array values, which breaks `<component src>` props that
+// rely on resolveIterationComponentProps to stash non-primitives in the
+// registry. Templates carrying any `<component src>` go through the
+// clone+hydrate path instead.
+const hasComponentSrc = (templateEl) =>
+  !!templateEl.querySelector?.('component[src], div.component[src]');
 const canUseBatchRender = (template) =>
-  !hasNestedStructures(template) && template.element.children.length <= 1;
+  !hasNestedStructures(template) &&
+  template.element.children.length <= 1 &&
+  !hasComponentSrc(template.element);
 const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
   const templateHtml = template.element.innerHTML.trim();
@@ -58,14 +68,49 @@ const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
   );
 };
+// Registry for non-primitive iteration prop snapshots. Lives on `window` (not
+// on `$`) so it doesn't pollute user-visible state enumeration, but is still
+// reachable from binding expressions because `window` is in evalInScope's
+// known-globals list. Each entry is freed when the owning component element
+// is detached (see releaseOrphanedIterationProps).
+let __vibeIterPropCounter = 0;
+const ensureIterPropsRegistry = () => {
+  if (!window.__vibeIterProps) window.__vibeIterProps = {};
+  return window.__vibeIterProps;
+};
+// Walk a removed subtree and free any iteration-prop registry slots stashed
+// on `<component>` elements inside it. Called from the mutation-observer
+// cleanup path after DOM detachment.
+export const releaseOrphanedIterationProps = (nodes) => {
+  if (!window.__vibeIterProps) return;
+  for (const node of nodes) {
+    if (node.nodeType !== 1) continue;
+    const free = (el) => {
+      const ids = el._vibeIterPropIds;
+      if (!ids) return;
+      for (const id of ids) delete window.__vibeIterProps[id];
+      el._vibeIterPropIds = null;
+    };
+    free(node);
+    node.querySelectorAll?.('[data-vibe-iter-prop]').forEach(free);
+  }
+};
 // For <component src> elements inside an iteration instance, evaluate any
 // `@[expr]` attribute bindings against the iteration's scoped state and replace
-// them with the resolved literal value. Component[src] attributes intentionally
-// bypass hydrate (parse.js) so they reach processComponent as bindings — but
-// bindings that depend on iteration-local vars (item, index) can't resolve later
-// when processComponent inlines the component, since by then iteration scope is gone.
-// Only called from iteration code paths; conditionals don't need this because their
-// branch content is registered in the global manifest and reacts to state updates.
+// them with the resolved value. Primitives stringify into the attribute as
+// before. Non-primitives (objects, arrays) snapshot into the registry and the
+// attribute becomes a binding into that slot — preserving live object/array
+// access for the child component's template (`@[prop.x]`,
+// `<!-- each prop as item -->`, etc.).
+//
+// Component[src] attributes intentionally bypass hydrate (parse.js) so they
+// reach processComponent as bindings — but bindings that depend on
+// iteration-local vars (item, index) can't resolve later when processComponent
+// inlines the component, since by then iteration scope is gone. Only called
+// from iteration code paths; conditionals don't need this because their branch
+// content is registered in the global manifest and reacts to state updates.
 const resolveIterationComponentProps = (nodes, scopedState) => {
   for (let n = 0; n < nodes.length; n++) {
     const node = nodes[n];
@@ -83,8 +128,16 @@ const resolveIterationComponentProps = (nodes, scopedState) => {
         if (!match) continue;
         try {
           const value = evalInScope(match[1], scopedState, el);
-          if (value !== undefined) {
+          if (value === undefined) continue;
+          if (value === null || (typeof value !== 'object' && typeof value !== 'function')) {
             el.setAttribute(attr.name, String(value));
+          } else {
+            const registry = ensureIterPropsRegistry();
+            const id = `_p${__vibeIterPropCounter++}`;
+            registry[id] = value;
+            el.setAttribute(attr.name, `@[window.__vibeIterProps.${id}]`);
+            el.setAttribute('data-vibe-iter-prop', '');
+            (el._vibeIterPropIds = el._vibeIterPropIds || []).push(id);
           }
         } catch {
           // Leave binding raw — processComponent will handle it as a binding

package/runtime/parse.js CHANGED Viewed

@@ -6,6 +6,7 @@ import {
   CONDITIONAL_REGEX,
   DOM_ELEMENT_PROPERTIES,
   DEHYDRATE_CLASS_OR_ATTR,
+  THIS_PROP_REGEX,
 } from './constants.js';
 // Walks up the DOM for the nearest component wrapper tagged by component.js.
@@ -49,7 +50,7 @@ const captureAttributeBindings = (element) => {
     if (attr.name.startsWith('on') && attr.value.includes('this.')) {
       const componentId = findComponentIdForElement(element);
       if (componentId) {
-        const rewritten = attr.value.replace(/\bthis\.(\w+)/g, (match, prop) => {
+        const rewritten = attr.value.replace(THIS_PROP_REGEX, (match, prop) => {
           return DOM_ELEMENT_PROPERTIES.has(prop) ? match : `$['${componentId}'].${prop}`;
         });
         element.setAttribute(attr.name, rewritten);

package/runtime/utils.js CHANGED Viewed

@@ -1,3 +1,5 @@
+import { THIS_PROP_REGEX } from './constants.js';
 // Fast incrementing counter instead of expensive random hash
 let hashCounter = 0;
 export const hash = () => `_${hashCounter++}`;
@@ -43,7 +45,7 @@ export const evalInScope = (expr, state, element = null) => {
       const componentId = findComponentIdForElement(element);
       if (componentId) {
         // Replace this.property with $['componentId'].property
-        normalized = normalized.replace(/\bthis\.(\w+)/g, `$['${componentId}'].$1`);
+        normalized = normalized.replace(THIS_PROP_REGEX, `$['${componentId}'].$1`);
       }
     }