@ape-egg/vibe 1.0.2 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [1.0.5] - 2026-01-25
+
+### Fixed
+
+- **Expression evaluation**: Normalize whitespace in `@[...]` expressions before evaluation, making bindings resilient to IDE auto-formatting that may break expressions across multiple lines
+
+### Changed
+
+- **DRY refactor**: Consolidated expression evaluation into single `evalInScope()` function in utils.js, used by hydrate.js, conditionals.js, and affected.js
+
+---
+
+## [1.0.4] - 2026-01-24
+
+### Fixed
+
+- **MutationObserver**: Use `takeRecords()` to preserve pending mutations before disconnecting during state changes, preventing queued DOM mutations (e.g., innerHTML replacements) from being lost when state updates occur simultaneously
+
+---
+
+## [1.0.3] - 2026-01-23
+
+### Added
+
+- **MutationObserver**: Now processes `<!-- if -->` and `<!-- each -->` comments when new nodes are added to DOM, enabling dynamic content to use vibe's control flow without manual processing
+
+### Fixed
+
+- **affected.js**: Only marks elements as affected when their specific bound values change, preventing unnecessary DOM updates when unrelated state changes (fixes `@[color]` in `<style>` updating on every keystroke when `@[firstName]` changes)
+
+---
+
 ## [1.0.2] - 2026-01-20
 
 ### Fixed

package/ROADMAP.md

@@ -0,0 +1,289 @@
+# Vibe Roadmap
+
+Feature proposals and improvements for Vibe's runtime-first reactive framework.
+
+---
+
+## Proposed: Manual Hydration API
+
+**Status**: Proposal
+**Priority**: Medium
+**Category**: Core Runtime
+
+### Problem
+
+Vibe's MutationObserver automatically hydrates `@[bindings]` on initial page load and incremental DOM changes, but fails when developers perform wholesale DOM replacement via `innerHTML`:
+
+```js
+// This doesn't trigger Vibe's hydration:
+element.innerHTML = '<h1>Welcome, @[race]!</h1>';
+// Result: Literal text "@[race]" instead of evaluated "human"
+```
+
+This happens because:
+1. `innerHTML` replacement destroys all old DOM nodes and creates new ones
+2. Vibe's MutationObserver is designed for incremental mutations, not complete replacement
+3. No mechanism exists to manually trigger re-hydration
+
+### Current Workaround
+
+Users must manually evaluate bindings before setting innerHTML:
+
+```js
+const evaluateBindings = (html) => {
+  return html.replace(/@\[([^\]]+)\]/g, (match, expression) => {
+    const keys = Object.keys(window.$);
+    const values = Object.values(window.$);
+    const result = new Function(...keys, `return ${expression}`)(...values);
+    return result ?? '';
+  });
+};
+
+element.innerHTML = evaluateBindings(html); // Manually evaluated
+```
+
+**Issues with this approach:**
+- Not DRY - duplicates Vibe's internal evaluation logic
+- Fragile - user's regex might not match Vibe's parser exactly
+- Knowledge burden - users need to know when manual evaluation is needed
+- Inconsistent - some bindings auto-hydrate, others need manual work
+
+### Use Cases
+
+This affects multiple real-world scenarios:
+
+1. **Dynamic content replacement** (tutorials, articles, modals)
+2. **Client-side routing** (replacing page sections with new HTML)
+3. **Lazy-loaded sections** (loading HTML from server with bindings)
+4. **Template cloning** (using `<template>` elements with `@[bindings]`)
+5. **Server-sent HTML** (SSR-like patterns where server sends HTML with bindings)
+
+### Proposed Solution
+
+Add a manual hydration API that allows users to trigger Vibe's binding evaluation:
+
+#### Option 1: Element Hydration
+```js
+vibe.hydrate(element);
+```
+
+**Usage:**
+```js
+tutorial.innerHTML = '<h1>Welcome, @[race]!</h1>';
+vibe.hydrate(tutorial); // Scan tutorial and children for @[bindings]
+```
+
+**Pros:**
+- Most flexible - works with any element
+- Matches web component patterns (`connectedCallback()`)
+- Clear intent - "scan this element"
+
+**Cons:**
+- Requires import/reference to vibe library
+- Two-step process (set innerHTML, then hydrate)
+
+#### Option 2: HTML String Evaluation
+```js
+const evaluated = vibe.evaluate(html, state);
+```
+
+**Usage:**
+```js
+const html = '<h1>Welcome, @[race]!</h1>';
+const evaluated = vibe.evaluate(html, window.$);
+tutorial.innerHTML = evaluated;
+```
+
+**Pros:**
+- Pure function - easier to test
+- Works without DOM access
+- Can be used server-side or in workers
+
+**Cons:**
+- Users must manage state passing
+- Doesn't handle nested/dynamic state updates
+
+#### Option 3: Safe innerHTML Setter
+```js
+vibe.setHTML(element, html);
+```
+
+**Usage:**
+```js
+vibe.setHTML(tutorial, '<h1>Welcome, @[race]!</h1>');
+```
+
+**Pros:**
+- Single operation - set and hydrate in one call
+- Matches platform APIs (`element.setHTML()`)
+- Simplest API surface
+
+**Cons:**
+- Yet another setter abstraction
+- Might conflict with future platform APIs
+
+### Recommendation
+
+**Implement Option 1** (`vibe.hydrate(element)`):
+- Aligns with Vibe's runtime-first philosophy
+- Gives users explicit control over hydration timing
+- Most flexible for different scenarios
+- Clear and predictable behavior
+
+### Implementation Notes
+
+```js
+// Expose on the state proxy:
+window.$ = state({ race: 'human' });
+window.$.vibe.hydrate(element); // Scan element for @[bindings]
+
+// Or as a module export:
+import state, { hydrate } from '@ape-egg/vibe';
+hydrate(element);
+```
+
+Should support:
+- Single element: `hydrate(tutorial)`
+- Multiple elements: `hydrate([el1, el2])`
+- Selector: `hydrate('tutorial')` (convenience)
+
+### Related
+
+Compare to other frameworks:
+- **Alpine.js**: `Alpine.initTree(el)` - manual initialization
+- **Vue**: `app.mount(el)` - mount to element
+- **Svelte**: Compiler handles this at build time
+- **HTMX**: `htmx.process(el)` - process element for attributes
+
+---
+
+## Known Issues
+
+### innerHTML Replacement Corrupts Conditional Branches in Iterations
+
+**Status**: Bug
+**Priority**: Low (edge case)
+**Category**: Core Runtime
+**Discovered**: 2026-01-25
+
+#### Problem
+
+When a parent element containing iterations with nested conditionals has its `innerHTML` replaced multiple times with identical HTML, the conditional's `else` branches become `null` after 2-3 replacements. This causes conditionals to fail rendering.
+
+**Root cause:**
+1. Iteration template's `branches` object is shared across all iteration instances (iterate.js:65: `branches, // Branch templates are reused`)
+2. When `innerHTML` replacement happens, something mutates the shared `branches.else` to `null`
+3. All instances reference the same corrupted branches object
+4. Subsequent renders have no `else` branch template to mount
+
+#### Reproduction
+
+Programmatic test case:
+
+```js
+// HTML structure
+const html = `
+  <item-list>
+    <!-- each items as item, i -->
+    <item-card>
+      <span>@[item]</span>
+      <!-- if i % 2 === 0 -->
+      <badge>Even</badge>
+      <!-- else -->
+      <badge secondary>Odd</badge>
+      <!-- /if -->
+    </item-card>
+    <!-- /each -->
+  </item-list>
+`;
+
+// State
+window.$ = state({ items: ['Apple', 'Banana', 'Cherry'] });
+
+// Trigger the bug
+const container = document.querySelector('[vibe]');
+
+// First replacement: works
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Second replacement: works
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Third replacement: branches.else becomes NULL
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Result: Even/Odd badges fail to render in the third iteration
+```
+
+#### Observations
+
+1. Cloning `branches` object during iteration (shallow copy) doesn't prevent the bug
+2. The mutation happens BEFORE cloning, meaning the original template is corrupted
+3. Setting a property trap on `branches.else` doesn't catch the mutation (already null when accessed)
+4. Only affects conditionals inside iterations - standalone conditionals work fine
+5. Only triggers with multiple innerHTML replacements - single replacement works
+
+#### Affected Patterns
+
+This bug only affects:
+- Replacing innerHTML multiple times with identical HTML containing iterations + conditionals
+- Demo infrastructure like tutorial.js that re-renders on state changes
+- Not representative of typical usage patterns
+
+Does NOT affect:
+- Normal reactivity (state changes)
+- Single innerHTML replacement
+- Iterations without conditionals
+- Conditionals outside iterations
+- Incremental DOM mutations (appendChild, insertBefore, etc.)
+
+#### Workaround
+
+Avoid multiple innerHTML replacements on parents containing iteration+conditional templates. Instead:
+1. Use incremental DOM APIs (appendChild, createElement)
+2. Replace innerHTML once at initialization only
+3. Use Vibe's normal reactivity for updates
+4. Don't wrap demo content in `<tutorial>` that re-renders via innerHTML
+
+#### Investigation Log
+
+Debugging attempts (2026-01-25):
+- ✓ Confirmed `branches.else` becomes `null` after 3rd innerHTML replacement
+- ✓ Added deep cloning of branches object - didn't help (already null before clone)
+- ✓ Added Object.defineProperty trap - didn't fire (already null)
+- ✓ Checked parsing logic - correctly finds else comments
+- ✗ Unable to identify where mutation occurs
+- ✗ Unable to reproduce with simpler test case (needs tutorial.js pattern)
+
+Likely related to:
+- MutationObserver's removedNodes callback cleaning up references
+- Template caching/reuse strategy in iterate.js
+- Interaction between parse → clone → hydrate → render cycle
+
+#### 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
+
+**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)
+
+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
+
+---
+
+## Future Proposals
+
+*This section reserved for additional feature proposals*

package/_vibe-compiled-iteration-batch.js

@@ -58,13 +58,13 @@ const hasNestedStructures = (tree) => {
  */
 export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
   const templateHtml = template.element.innerHTML.trim();
-  const escaped = templateHtml
-    .replace(/\\/g, '\\\\')
-    .replace(/`/g, '\\`')
-    .replace(/\$\{/g, '\\${');
+  const escaped = templateHtml.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
   const code = escaped.replace(BINDING_REGEX, (_, expr) => '${' + expr + '}');
 
-  return new Function('arr', ...stateKeys, `
+  return new Function(
+    'arr',
+    ...stateKeys,
+    `
     let html = '';
     const len = arr.length;
     for (let ${indexAlias} = 0; ${indexAlias} < len; ${indexAlias}++) {
@@ -72,7 +72,8 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
       html += \`${code}\`;
     }
     return html;
-  `);
+  `,
+  );
 };
 
 /**
@@ -92,7 +93,7 @@ export const renderFast = (iterationNode, array, state, parent, endComment) => {
   const stateKeys = iterationNode.runtime.stateKeys;
 
   // Build HTML string using batch function
-  const stateValues = stateKeys.map(k => state[k]);
+  const stateValues = stateKeys.map((k) => state[k]);
   const html = batchFn(array, ...stateValues);
 
   // Parse with reusable template element
@@ -141,7 +142,7 @@ export const updateFast = (iterationNode, newArray, state, startComment, endComm
   // Build HTML string using cached batch function
   const batchFn = iterationNode.runtime.batchFn;
   const stateKeys = iterationNode.runtime.stateKeys;
-  const stateValues = stateKeys.map(k => state[k]);
+  const stateValues = stateKeys.map((k) => state[k]);
   const html = batchFn(newArray, ...stateValues);
 
   // Parse and insert

package/affected.js

@@ -1,18 +1,10 @@
-import { resolvePath, deepEqual } from './iteration-utils.js'
-import { extractDependencies } from './conditionals.js'
-import { BINDING_REGEX } from './constants.js'
+import { resolvePath, deepEqual } from './iteration-utils.js';
+import { extractDependencies } from './conditionals.js';
+import { BINDING_REGEX } from './constants.js';
+import { evalInScope } from './utils.js';
 
 // Evaluate conditional expression
-const evaluateCondition = (expression, state) => {
-  try {
-    const keys = Object.keys(state);
-    const values = Object.values(state);
-    const result = new Function(...keys, `'use strict'; return !!(${expression})`)(...values);
-    return !!result;
-  } catch (e) {
-    return false;
-  }
-};
+const evaluateCondition = (expression, state) => !!evalInScope(expression, state);
 
 // Helper function to check if a match references a specific key
 const matchesKey = (matchStr, key) => matchStr === key || matchStr.startsWith(key + '.');
@@ -29,7 +21,7 @@ const recursive = (tree, state, newState, affected) => {
       affected.push({
         type: 'iteration',
         node: tree,
-        changeType: 'array'
+        changeType: 'array',
       });
     }
     return affected;
@@ -45,7 +37,7 @@ const recursive = (tree, state, newState, affected) => {
       affected.push({
         type: 'conditional',
         node: tree,
-        changeType: 'expression'
+        changeType: 'expression',
       });
       return affected;
     }
@@ -70,21 +62,37 @@ const recursive = (tree, state, newState, affected) => {
   if (matches.length) {
     const shallowState = Object.keys(state);
     const shallowNewState = Object.keys(newState);
+    const isInitialHydration = state === newState;
 
     let hasAffected = false;
     const checkedMatches = [];
 
     for (const m of matches) {
-      const noMatch = !shallowState.some(key => matchesKey(m.inner, key));
-      const newMatches = shallowNewState.filter(key => matchesKey(m.inner, key));
+      const noMatch = !shallowState.some((key) => matchesKey(m.inner, key));
+
+      let shouldAffect = false;
+      let relevantKeys = [];
+
+      if (isInitialHydration) {
+        // Initial hydration: affect all matched keys
+        relevantKeys = shallowNewState.filter((key) => matchesKey(m.inner, key));
+        shouldAffect = noMatch || relevantKeys.length > 0;
+      } else {
+        // Update: only affect if value changed
+        const changedKeys = shallowNewState.filter((key) =>
+          matchesKey(m.inner, key) && state[key] !== newState[key]
+        );
+        relevantKeys = changedKeys.length > 0 ? changedKeys : shallowState.filter((key) => matchesKey(m.inner, key));
+        shouldAffect = noMatch || changedKeys.length > 0;
+      }
 
-      if (noMatch || newMatches.length) {
+      if (shouldAffect) {
         hasAffected = true;
       }
 
       checkedMatches.push({
         ...m,
-        matches: newMatches.length ? newMatches : shallowState.filter(key => matchesKey(m.inner, key))
+        matches: relevantKeys,
       });
     }
 
@@ -95,7 +103,7 @@ const recursive = (tree, state, newState, affected) => {
           matchInner: m.inner,
           input: m.input,
           matches: m.matches,
-          element: tree.element
+          element: tree.element,
         });
       }
     }
@@ -105,6 +113,7 @@ const recursive = (tree, state, newState, affected) => {
   if (tree.attributes) {
     const shallowState = Object.keys(state);
     const shallowNewState = Object.keys(newState);
+    const isInitialHydration = state === newState;
 
     for (const [attrName, attrValue] of Object.entries(tree.attributes)) {
       BINDING_REGEX.lastIndex = 0;
@@ -115,17 +124,30 @@ const recursive = (tree, state, newState, affected) => {
       }
 
       for (const m of attrMatches) {
-        const noMatch = !shallowState.some(key => matchesKey(m.inner, key));
-        const newMatches = shallowNewState.filter(key => matchesKey(m.inner, key));
+        const noMatch = !shallowState.some((key) => matchesKey(m.inner, key));
+
+        let shouldAffect = false;
+
+        if (isInitialHydration) {
+          // Initial hydration: affect all matched keys
+          const newMatches = shallowNewState.filter((key) => matchesKey(m.inner, key));
+          shouldAffect = noMatch || newMatches.length > 0;
+        } else {
+          // Update: only affect if value changed
+          const changedKeys = shallowNewState.filter((key) =>
+            matchesKey(m.inner, key) && state[key] !== newState[key]
+          );
+          shouldAffect = noMatch || changedKeys.length > 0;
+        }
 
-        if (noMatch || newMatches.length) {
+        if (shouldAffect) {
           affected.push({
             type: 'attribute',
             attrName,
             attrValue,
             matchOuter: m.outer,
             matchInner: m.inner,
-            element: tree.element
+            element: tree.element,
           });
         }
       }
@@ -146,4 +168,4 @@ const recursive = (tree, state, newState, affected) => {
   return affected;
 };
 
-export default (tree, state, newState) => recursive(tree, state, newState, [])
+export default (tree, state, newState) => recursive(tree, state, newState, []);

package/conditionals.js

@@ -2,20 +2,10 @@ import parse from './parse.js';
 import affected from './affected.js';
 import hydrate from './hydrate.js';
 import { createScopedState, renderAllIterations, initializeBlock } from './iterate.js';
+import { evalInScope } from './utils.js';
 
 // Evaluate conditional expression in state context
-const evaluateCondition = (expression, state) => {
-  try {
-    const keys = Object.keys(state);
-    const values = Object.values(state);
-    // Create a function with state keys as parameters and evaluate the expression
-    const result = new Function(...keys, `'use strict'; return !!(${expression})`)(...values);
-    return !!result; // Coerce to boolean
-  } catch (e) {
-    console.warn(`Error evaluating condition "${expression}":`, e);
-    return false; // Default to false on error
-  }
-};
+const evaluateCondition = (expression, state) => !!evalInScope(expression, state);
 
 // Extract state dependencies from an expression
 // e.g., "count > 5" → ["count"]
@@ -44,7 +34,7 @@ export const renderAllConditionals = (tree, state, linkList, parentScope = {}) =
 
   // Recursively render conditionals in child nodes
   if (tree.children) {
-    Object.keys(tree.children).forEach(key => {
+    Object.keys(tree.children).forEach((key) => {
       const child = tree.children[key];
       if (typeof child === 'object' && child !== null) {
         renderAllConditionals(child, state, linkList, parentScope);
@@ -104,15 +94,18 @@ const mountBranch = (node, branchData, state, linkList, parentScope) => {
   const parent = startComment.parentNode;
 
   // Create scoped state (with parent scope if inside iteration)
-  const scopedState = Object.keys(parentScope).length > 0
-    ? createScopedState(state, parentScope)
-    : state;
+  const scopedState =
+    Object.keys(parentScope).length > 0 ? createScopedState(state, parentScope) : state;
 
   // Initialize block (clone, parse, hydrate)
-  const { element: firstElement, tree: branchTree, clonedNodes } = initializeBlock(templateContent, scopedState);
+  const {
+    element: firstElement,
+    tree: branchTree,
+    clonedNodes,
+  } = initializeBlock(templateContent, scopedState);
 
   // Insert cloned nodes into DOM
-  clonedNodes.forEach(clonedNode => parent.insertBefore(clonedNode, endComment));
+  clonedNodes.forEach((clonedNode) => parent.insertBefore(clonedNode, endComment));
 
   // Recursively render any nested iterations and conditionals
   if (branchTree) {
@@ -124,7 +117,7 @@ const mountBranch = (node, branchData, state, linkList, parentScope) => {
   node.runtime.activeInstance = {
     branch: branchData,
     nodes: clonedNodes,
-    parsedTree: branchTree
+    parsedTree: branchTree,
   };
 };
 
@@ -135,7 +128,7 @@ const unmountBranch = (node) => {
   if (!activeInstance) return;
 
   // Remove all nodes from DOM
-  activeInstance.nodes.forEach(domNode => {
+  activeInstance.nodes.forEach((domNode) => {
     if (domNode.parentNode) {
       domNode.parentNode.removeChild(domNode);
     }
@@ -170,13 +163,11 @@ export const updateConditional = (node, newState, oldState, linkList, parentScop
     const { activeInstance } = node.runtime;
 
     if (activeInstance && activeInstance.parsedTree) {
-      const scopedState = Object.keys(parentScope).length > 0
-        ? createScopedState(newState, parentScope)
-        : newState;
+      const scopedState =
+        Object.keys(parentScope).length > 0 ? createScopedState(newState, parentScope) : newState;
 
       const affectedElements = affected(activeInstance.parsedTree, oldState, scopedState);
       hydrate(affectedElements, scopedState);
     }
   }
 };
-