@ape-egg/vibe 1.0.3 → 1.1.1

package/{iterate.js → runtime/iterate.js}

@@ -126,37 +126,30 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null) =
   let clonedNodes = [];
   let firstElement = null;
 
-  // Fast path: clone cached tree with new element references
-  if (cachedTree) {
-    // Clone nodes directly
-    for (let i = 0; i < templateNodes.length; i++) {
-      const cloned = templateNodes[i].cloneNode(true);
-      clonedNodes.push(cloned);
-      if (!firstElement && cloned.nodeType === 1) {
-        firstElement = cloned;
-      }
-    }
-    // Use virtual root to match template structure (avoids creating DOM container)
-    // cloneTreeWithElements only needs childNodes property
-    tree = cloneTreeWithElements(cachedTree, { childNodes: clonedNodes });
-  } else {
-    // Slow path: clone and parse from scratch
-    for (let i = 0; i < templateNodes.length; i++) {
-      const cloned = templateNodes[i].cloneNode(true);
-      clonedNodes.push(cloned);
-      if (!firstElement && cloned.nodeType === 1) {
-        firstElement = cloned;
-      }
+  // Always use slow path: clone and parse from scratch
+  // TODO: Re-enable fast path once cloneTreeWithElements properly handles nested conditionals
+
+  // Create a container for parsing (to capture all nodes including comment nodes like <!-- if -->)
+  const parseContainer = document.createElement('div');
+
+  // Clone all template nodes into the container
+  for (let i = 0; i < templateNodes.length; i++) {
+    const cloned = templateNodes[i].cloneNode(true);
+    parseContainer.appendChild(cloned);
+    if (!firstElement && cloned.nodeType === 1) {
+      firstElement = cloned;
     }
+  }
 
-    // Fallback for text-only templates
-    if (!firstElement && clonedNodes.length > 0) {
-      const container = document.createElement('span');
-      clonedNodes.forEach((node) => container.appendChild(node.cloneNode(true)));
-      firstElement = container;
-    }
+  // Parse the entire container (includes all nodes + conditionals)
+  tree = parse(parseContainer);
+
+  // Extract the cloned nodes from the container (these are the same nodes the tree references)
+  clonedNodes = Array.from(parseContainer.childNodes);
 
-    tree = firstElement ? parse(firstElement) : null;
+  // If no firstElement found, use parseContainer as fallback
+  if (!firstElement) {
+    firstElement = parseContainer;
   }
 
   if (tree) {
@@ -229,11 +222,13 @@ export const createScopedState = (globalState, localVars, parentScope = {}) => {
 };
 
 // Render all iterations in the parsed tree
-export const renderAllIterations = (tree, state, linkList, parentScope = {}) => {
+export const renderAllIterations = (tree, state, manifest, parentScope = {}) => {
+  let count = 0;
+
   // If this is an iteration node, render it
   if (tree.type === 'iteration') {
-    renderIteration(tree, state, linkList, parentScope);
-    return;
+    renderIteration(tree, state, manifest, parentScope);
+    return 1;
   }
 
   // Recursively render iterations in child nodes
@@ -241,10 +236,12 @@ export const renderAllIterations = (tree, state, linkList, parentScope = {}) =>
     for (const key in tree.children) {
       const child = tree.children[key];
       if (child && typeof child === 'object') {
-        renderAllIterations(child, state, linkList, parentScope);
+        count += renderAllIterations(child, state, manifest, parentScope);
       }
     }
   }
+
+  return count;
 };
 
 // Callback for rendering conditionals - set by conditionals.js to avoid circular import
@@ -254,13 +251,20 @@ export const setRenderAllConditionals = (fn) => {
 };
 
 // Initial render of an iteration block
-export const renderIteration = (iterationNode, state, linkList, parentScope = {}) => {
+export const renderIteration = (iterationNode, state, manifest, parentScope = {}) => {
   const { arrayPath, itemAlias, indexAlias, template, startComment, endComment } =
     iterationNode.meta;
 
   // Already rendered - updates go through updateIteration
   if (iterationNode.runtime.instances?.length > 0) return;
 
+  // Check if this iteration has already been rendered
+  // We use a marker on the startComment node itself (survives re-parsing)
+  // @ts-ignore - adding custom property to comment node
+  if (startComment.__vibeRendered) {
+    return;
+  }
+
   // Remove template nodes from DOM on first render
   if (!iterationNode.runtime.templateRemoved) {
     let node = startComment.nextSibling;
@@ -304,18 +308,22 @@ export const renderIteration = (iterationNode, state, linkList, parentScope = {}
     // Recursively render nested iterations and conditionals
     if (tree) {
       const nestedScope = { ...parentScope, ...localVars };
-      renderAllIterations(tree, scopedState, linkList, nestedScope);
-      _renderAllConditionals(tree, scopedState, linkList, nestedScope);
+      renderAllIterations(tree, scopedState, manifest, nestedScope);
+      _renderAllConditionals(tree, scopedState, manifest, nestedScope);
     }
 
-    instances.push({ element, tree, item, index: i, clonedNodes });
+    instances.push({ element, tree, item, index: i, clonedNodes, scopedState });
   }
 
   iterationNode.runtime.instances = instances;
+
+  // Mark comment as rendered (survives re-parsing since comment nodes persist in DOM)
+  // @ts-ignore - adding custom property to comment node
+  startComment.__vibeRendered = true;
 };
 
 // Update an iteration block when array changes
-export const updateIteration = (iterationNode, newState, oldState, linkList, parentScope = {}) => {
+export const updateIteration = (iterationNode, newState, oldState, manifest, parentScope = {}) => {
   if (!iterationNode.runtime.instances || !iterationNode.runtime.templateRemoved) return;
 
   const { arrayPath, template, startComment, endComment } = iterationNode.meta;
@@ -348,13 +356,13 @@ export const updateIteration = (iterationNode, newState, oldState, linkList, par
         removeInstance(iterationNode, op.index);
         break;
       case 'ADD':
-        addInstance(iterationNode, op.item, op.index, newState, linkList, parentScope);
+        addInstance(iterationNode, op.item, op.index, newState, manifest, parentScope);
         break;
       case 'MOVE':
         moveInstance(iterationNode, op.from, op.to);
         break;
       case 'UPDATE':
-        updateInstance(iterationNode, op.index, op.item, newState, linkList, parentScope);
+        updateInstance(iterationNode, op.index, op.item, newState, manifest, parentScope);
         break;
     }
   });
@@ -365,7 +373,7 @@ export const updateIteration = (iterationNode, newState, oldState, linkList, par
 };
 
 // Add a new instance at the specified index
-const addInstance = (iterationNode, item, index, state, linkList, parentScope) => {
+const addInstance = (iterationNode, item, index, state, manifest, parentScope) => {
   const { itemAlias, indexAlias, template, startComment, endComment } = iterationNode.meta;
 
   const localVars = { [itemAlias]: item, [indexAlias]: index };
@@ -387,8 +395,8 @@ const addInstance = (iterationNode, item, index, state, linkList, parentScope) =
   // Recursively render nested iterations and conditionals
   if (tree) {
     const nestedScope = { ...parentScope, ...localVars };
-    renderAllIterations(tree, scopedState, linkList, nestedScope);
-    _renderAllConditionals(tree, scopedState, linkList, nestedScope);
+    renderAllIterations(tree, scopedState, manifest, nestedScope);
+    _renderAllConditionals(tree, scopedState, manifest, nestedScope);
   }
 
   iterationNode.runtime.instances.splice(index, 0, { element, tree, item, index, clonedNodes });
@@ -432,7 +440,7 @@ const moveInstance = (iterationNode, fromIndex, toIndex) => {
 };
 
 // Update an instance with new item data
-const updateInstance = (iterationNode, index, newItem, state, linkList, parentScope = {}) => {
+const updateInstance = (iterationNode, index, newItem, state, manifest, parentScope = {}) => {
   if (index < 0 || index >= iterationNode.runtime.instances.length) return;
 
   const { itemAlias, indexAlias, template } = iterationNode.meta;
@@ -455,8 +463,8 @@ const updateInstance = (iterationNode, index, newItem, state, linkList, parentSc
   // Recursively render nested iterations and conditionals
   if (tree) {
     const nestedScope = { ...parentScope, ...localVars };
-    renderAllIterations(tree, scopedState, linkList, nestedScope);
-    _renderAllConditionals(tree, scopedState, linkList, nestedScope);
+    renderAllIterations(tree, scopedState, manifest, nestedScope);
+    _renderAllConditionals(tree, scopedState, manifest, nestedScope);
   }
 
   // Update instance

package/{iteration-utils.js → runtime/iteration-utils.js}

@@ -59,7 +59,17 @@ export const findConditionalEnd = (nodes, startIndex) => {
     }
   }
 
-  throw new Error('Unmatched <!-- if --> comment: missing <!-- /if -->');
+  // Build error message with context
+  const nodeTypes = nodes.slice(startIndex - 1, Math.min(startIndex + 10, nodes.length)).map((n, idx) => {
+    const actualIdx = startIndex - 1 + idx;
+    const prefix = actualIdx === startIndex - 1 ? '→ ' : '  ';
+    if (n.nodeName === '#comment') {
+      return `${prefix}[${actualIdx}] #comment: "${n.textContent.trim()}"`;
+    }
+    return `${prefix}[${actualIdx}] ${n.nodeName}`;
+  });
+
+  throw new Error(`Unmatched <!-- if --> comment: missing <!-- /if -->\nSearching from index ${startIndex} in ${nodes.length} nodes\nContext:\n${nodeTypes.join('\n')}`);
 };
 
 // Generate stable hash for objects

package/{parse.js → runtime/parse.js}

@@ -19,7 +19,7 @@ const parseHTML = (children, rootKey = undefined) =>
     return rootKey || `${s}${`\$[${innerNodeIdentifier}]`}`;
   }, '');
 
-const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
+const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats = { skipped: 0 }) => {
   let result = {};
 
   for (let i = 0; i < children.length; i++) {
@@ -31,7 +31,10 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
 
     // Skip non-reactive elements and dehydrated elements
     if (NON_REACTIVE_ELEMENTS.includes(nodeName)) continue;
-    if (element.hasAttribute?.('dehydrate')) continue;
+    if (element.hasAttribute?.('dehydrate')) {
+      stats.skipped++;
+      continue;
+    }
 
     // Handle iteration comments
     if (nodeName === '#comment') {
@@ -54,7 +57,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
           });
 
           // Parse the template recursively
-          const templateParsed = recursive([...templateContainer.childNodes]);
+          const templateParsed = recursive([...templateContainer.childNodes], undefined, new Set(), stats);
 
           // Store iteration metadata
           const iterationKey = `iteration_${hash()}`;
@@ -115,7 +118,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
           });
 
           // Parse the true branch recursively
-          const trueBranchParsed = recursive([...trueBranchContainer.childNodes]);
+          const trueBranchParsed = recursive([...trueBranchContainer.childNodes], undefined, new Set(), stats);
 
           // Extract false branch nodes if else exists
           let falseBranchParsed = null;
@@ -126,7 +129,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
             falseBranchNodes.forEach((node) => {
               falseBranchContainer.appendChild(node.cloneNode(true));
             });
-            falseBranchParsed = recursive([...falseBranchContainer.childNodes]);
+            falseBranchParsed = recursive([...falseBranchContainer.childNodes], undefined, new Set(), stats);
           }
 
           // Store conditional metadata
@@ -184,17 +187,28 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
 
     // Check for attribute bindings
     const attributes = {};
+    const nameBindings = [];
     if (element.attributes) {
       for (let j = 0; j < element.attributes.length; j++) {
         const attr = element.attributes[j];
         // Reset lastIndex before test - BINDING_REGEX has 'g' flag which persists state
         BINDING_REGEX.lastIndex = 0;
+
+        // Check if attribute name contains binding (e.g., @[section.icon])
+        if (BINDING_REGEX.test(attr.name)) {
+          nameBindings.push(attr.name);
+          continue; // Don't process as regular attribute
+        }
+
+        // Check if attribute value contains binding
+        BINDING_REGEX.lastIndex = 0;
         if (BINDING_REGEX.test(attr.value)) {
           attributes[attr.name] = attr.value;
         }
       }
     }
     const hasAttributeBindings = Object.keys(attributes).length > 0;
+    const hasNameBindings = nameBindings.length > 0;
 
     const hasChildren = childNodes.length;
 
@@ -205,8 +219,9 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
       result[rootKey || nodeIdentifier] = {
         parsed,
         element,
-        children: recursive(iteratableChildren),
+        children: recursive(iteratableChildren, undefined, new Set(), stats),
         ...(hasAttributeBindings && { attributes }),
+        ...(hasNameBindings && { nameBindings }),
       };
     } else {
       result[nodeIdentifier] = {
@@ -214,6 +229,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
         element,
         children: {},
         ...(hasAttributeBindings && { attributes }),
+        ...(hasNameBindings && { nameBindings }),
       };
     }
   }
@@ -223,13 +239,25 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set()) => {
 
 export default (root, rootKey = undefined) => {
   const { childNodes } = root;
+  const stats = { skipped: 0 };
 
   // Check for attribute bindings on the root element itself (only if element has attributes)
   let attributes = null;
+  let nameBindings = null;
   if (root.attributes && root.attributes.length > 0) {
     for (let j = 0; j < root.attributes.length; j++) {
       const attr = root.attributes[j];
       BINDING_REGEX.lastIndex = 0;
+
+      // Check if attribute name contains binding
+      if (BINDING_REGEX.test(attr.name)) {
+        if (!nameBindings) nameBindings = [];
+        nameBindings.push(attr.name);
+        continue;
+      }
+
+      // Check if attribute value contains binding
+      BINDING_REGEX.lastIndex = 0;
       if (BINDING_REGEX.test(attr.value)) {
         if (!attributes) attributes = {};
         attributes[attr.name] = attr.value;
@@ -241,7 +269,9 @@ export default (root, rootKey = undefined) => {
     // html: root.outerHTML,
     parsed: parseHTML([...childNodes], rootKey),
     element: root,
-    children: recursive(Array.from(childNodes), rootKey),
+    children: recursive(Array.from(childNodes), rootKey, new Set(), stats),
     ...(attributes && { attributes }),
+    ...(nameBindings && { nameBindings }),
+    stats,
   };
 };

package/runtime/state.js

@@ -0,0 +1,52 @@
+// Track which objects are already proxied to avoid double-wrapping
+const proxyCache = new WeakMap();
+
+// Deep proxy: recursively wrap nested objects and arrays
+const createDeepProxy = (target, rerender, rootState = null, rootProp = null) => {
+  // For root level, rootState is the target itself
+  if (rootState === null) {
+    rootState = target;
+  }
+
+  // Check cache first
+  if (proxyCache.has(target)) {
+    return proxyCache.get(target);
+  }
+
+  const proxy = new Proxy(target, {
+    set(obj, prop, value) {
+      const oldValue = obj[prop];
+      const ref = Reflect.set(obj, prop, value);
+
+      // Only trigger rerender if value actually changed
+      if (oldValue !== value) {
+        // If we're at root level, use the prop being set
+        // If we're nested, use the root prop that contains this nested object
+        const changedProp = rootProp || prop;
+        rerender({ [changedProp]: rootState[changedProp] });
+      }
+
+      return ref;
+    },
+
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      // Don't proxy non-objects, functions, or null
+      if (value === null || typeof value !== 'object' || typeof value === 'function') {
+        return value;
+      }
+
+      // Recursively wrap nested objects/arrays
+      // If rootProp is null (we're at root level), set it to current prop
+      // Otherwise keep passing down the same rootProp
+      const topProp = rootProp === null ? prop : rootProp;
+      return createDeepProxy(value, rerender, rootState, topProp);
+    },
+  });
+
+  proxyCache.set(target, proxy);
+  return proxy;
+};
+
+export default (state, rerender) => createDeepProxy(state, rerender);

package/{utils.js → runtime/utils.js}

@@ -2,6 +2,19 @@
 let hashCounter = 0;
 export const hash = () => `_${hashCounter++}`;
 
+// Evaluate expression in the context of state
+export const evalInScope = (expr, state) => {
+  try {
+    // Normalize whitespace - collapse newlines/spaces to single space (resilient to IDE formatting)
+    const normalized = expr.replace(/\s+/g, ' ').trim();
+    const keys = Object.keys(state);
+    const values = Object.values(state);
+    return new Function(...keys, `'use strict'; return (${normalized})`)(...values);
+  } catch (e) {
+    return undefined;
+  }
+};
+
 // Instead of using lodash-es as a dependency, we run our own deepMerge (mergeWith in lodash)
 export const deepMerge = (target, source) => {
   // Handle null/undefined

package/llms.txt

@@ -1,279 +0,0 @@
-# Vibe - Complete Documentation
-
-> Runtime-first reactivity. No virtual DOM. No build step.
-
-## Overview
-
-Vibe is a lightweight reactive library that uses Proxy-based state and MutationObserver for fine-grained DOM updates. It works directly in the browser with zero compilation required.
-
-**Key characteristics:**
-- Proxy-based reactive state (`window.$`)
-- Surgical DOM updates (only affected elements re-render)
-- MutationObserver for dynamic element tracking
-- Works with vanilla HTML - no special file format
-
-## Installation
-
-```bash
-npm install @ape-egg/vibe
-```
-
-## Quick Start
-
-```html
-<script type="module">
-  import state from "@ape-egg/vibe";
-  window.$ = state({ name: "World", count: 0 });
-</script>
-
-<h1>Hello, @[name]!</h1>
-<button onclick="$.count++">Clicked @[count] times</button>
-```
-
-## Core Syntax
-
-### Reactive Bindings
-
-Use `@[property]` syntax anywhere in HTML or CSS:
-
-```html
-<!-- Text content -->
-<div>@[firstName]</div>
-
-<!-- Expressions -->
-<div>@[firstName + ' ' + lastName]</div>
-<div>@[count * 2]</div>
-
-<!-- Attributes -->
-<input value="@[inputValue]">
-<button disabled="@[isLoading]">Submit</button>
-
-<!-- CSS -->
-<style>
-  .box { background: @[themeColor]; }
-</style>
-```
-
-⚠️ **Important**: Bindings are evaluated using `new Function()`. Do not bind untrusted user input.
-
-### State Access
-
-State is accessed globally via `window.$`:
-
-```javascript
-// Read
-console.log($.firstName);
-
-// Write (triggers re-render)
-$.firstName = "John";
-
-// Increment
-$.count++;
-```
-
-## Control Flow
-
-### Iteration
-
-```html
-<!-- each items as item -->
-  <li>@[item]</li>
-<!-- /each -->
-```
-
-With index:
-
-```html
-<!-- each items as item, index -->
-  <li>@[index]: @[item]</li>
-<!-- /each -->
-```
-
-### Nested Iteration
-
-Use dot paths for nested arrays:
-
-```html
-<!-- each categories as category -->
-  <h2>@[category.name]</h2>
-  <!-- each category.items as item -->
-    <span>@[item.name]</span>
-  <!-- /each -->
-<!-- /each -->
-```
-
-### Conditionals
-
-```html
-<!-- if isLoggedIn -->
-  <span>Welcome, @[username]!</span>
-<!-- else -->
-  <span>Please log in</span>
-<!-- /if -->
-```
-
-Conditionals can be nested inside iterations and vice versa.
-
-## Special Attributes
-
-### Dehydrate
-
-Skip reactive processing for an element and its children:
-
-```html
-<code dehydrate>@[this] displays literally, not parsed</code>
-```
-
-Use cases:
-- Displaying `@[...]` syntax in documentation
-- Static content that shouldn't be reactive
-- Performance optimization for large static sections
-
-### Boolean Attributes
-
-Attributes not in the value whitelist are removed when falsy:
-
-```html
-<button disabled="@[isLoading]">Submit</button>
-<!-- When isLoading is false, disabled attribute is removed entirely -->
-```
-
-## Events
-
-Use standard inline event handlers:
-
-```html
-<button onclick="$.count++">Increment</button>
-<input oninput="$.text = this.value">
-<form onsubmit="event.preventDefault(); handleSubmit()">
-```
-
-## Styling
-
-### CSS Bindings
-
-Reactive values work inside `<style>` tags:
-
-```html
-<style>
-  .box {
-    background: @[backgroundColor];
-    color: @[textColor];
-    width: @[width]px;
-  }
-</style>
-```
-
-### Preventing FOUC
-
-Hide content until hydration completes:
-
-```html
-<body style="visibility: hidden;">
-```
-
-Or use the included CSS:
-
-```html
-<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
-<body vibe>
-```
-
-## Dynamic Elements
-
-Elements added via JavaScript are automatically hydrated through MutationObserver:
-
-```javascript
-const div = document.createElement('div');
-div.innerHTML = '<span>Hello, @[name]!</span>';
-document.body.appendChild(div);
-// Automatically becomes reactive
-```
-
-## API Reference
-
-### `state(initialState, afterUpdate?)`
-
-Creates reactive state and initializes the framework.
-
-```javascript
-import state from "@ape-egg/vibe";
-
-window.$ = state(
-  { count: 0, user: { name: "Alice" } },
-  (newState, oldState) => {
-    console.log("State updated:", newState);
-  }
-);
-```
-
-**Parameters:**
-- `initialState` - Object containing initial state values
-- `afterUpdate` - Optional callback after each state change (receives read-only snapshots)
-
-**Returns:** Proxy object for reactive state access
-
-## Scoped Variables
-
-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 `$`
-
-```html
-<!-- each users as user, i -->
-  <div>@[i]: @[user.name] (total: @[users.length])</div>
-<!-- /each -->
-```
-
-## Architecture
-
-Vibe consists of these core modules:
-
-- **state.js** - Proxy-based reactive state container
-- **parse.js** - DOM parser that finds `@[...]` bindings
-- **link.js** - Maps elements to parsed tree nodes
-- **hydrate.js** - Updates DOM with current state values
-- **affected.js** - Determines which elements need updating
-- **iterate.js** - Array rendering with efficient diffing
-- **conditionals.js** - Conditional block rendering
-
-## 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
-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
-```
-
-## Current Limitations
-
-- **Top-level reactivity only**: `$.nested.prop = value` doesn't trigger updates (must replace parent object)
-- **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
-
-## 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. **Replace objects for deep updates**: `$.user = { ...$.user, name: "New" }`
-
-## Browser Support
-
-Modern browsers with:
-- Proxy (ES6)
-- MutationObserver
-- ES Modules
-
-## Resources
-
-- **Homepage**: https://vibe.korte.kim
-- **npm**: https://www.npmjs.com/package/@ape-egg/vibe