@ape-egg/vibe 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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/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 { 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 + '.');

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"]

package/hydrate.js

@@ -1,6 +1,7 @@
 import { updateIteration } from './iterate.js';
 import { updateConditional } from './conditionals.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
+import { evalInScope } from './utils.js';
 
 // Keep track of old state for diffing
 let previousState = {};
@@ -9,19 +10,6 @@ export const setPreviousState = (state) => {
   previousState = { ...state };
 };
 
-// Evaluate expression in the context of state
-const evalInScope = (expr, state) => {
-  try {
-    const keys = Object.keys(state);
-    const values = Object.values(state);
-    // Create a function with state keys as parameters and evaluate the expression
-    return new Function(...keys, `'use strict'; return (${expr})`)(...values);
-  } catch (e) {
-    // Fallback to undefined if evaluation fails
-    return undefined;
-  }
-};
-
 export default (affected, state, linkList = {}) => {
   affected.forEach((aff) => {
     // Handle iteration updates

package/index.js

@@ -68,15 +68,23 @@ const main = (s, attrName = 'vibe') => {
     afterDomMutation: [],
   };
 
-  // Observer reference - set after observer is created
+  // Observer reference and callback - defined here so state handler can access processMutations
   let observer = null;
+  let processMutations = null;
 
   const $ = state(s, (newState) => {
     const mergedState = deepMerge($, newState);
     const affectedElements = affected(parsedTree, previousState, mergedState);
 
-    if (observer) observer.disconnect();
+    // Capture pending mutations before disconnecting (takeRecords clears the queue)
+    let pendingMutations = [];
+    if (observer) {
+      pendingMutations = observer.takeRecords();
+      observer.disconnect();
+    }
+
     hydrate(affectedElements, mergedState, linkList);
+
     if (observer) {
       observer.observe(rootElement, {
         attributes: false,
@@ -84,6 +92,11 @@ const main = (s, attrName = 'vibe') => {
         childList: true,
         subtree: true,
       });
+
+      // Process mutations that were pending before we disconnected
+      if (pendingMutations.length > 0 && processMutations) {
+        processMutations(pendingMutations);
+      }
     }
 
     const prev = structuredClone(previousState);
@@ -112,7 +125,8 @@ const main = (s, attrName = 'vibe') => {
   renderAllIterations(parsedTree, $, linkList);
   renderAllConditionals(parsedTree, $, linkList);
 
-  observer = new MutationObserver((mutations) => {
+  // Define observer callback as named function so we can call it manually for pending mutations
+  processMutations = (mutations) => {
     // Early exit if no mutations to process (common case)
     if (mutations.length === 0) return;
 
@@ -120,7 +134,6 @@ const main = (s, attrName = 'vibe') => {
     let parsedParents = null; // Lazy init - only create Set when needed
 
     mutations.forEach(({ addedNodes, removedNodes, target }) => {
-      // Process removed nodes first (cleanup before additions)
       removedNodes.forEach((node) => {
         const entry = Object.entries(linkList).find(([_, element]) => element === node);
 
@@ -210,7 +223,9 @@ const main = (s, attrName = 'vibe') => {
     if (hadChanges) {
       hooks.afterDomMutation.forEach((callback) => callback());
     }
-  });
+  };
+
+  observer = new MutationObserver(processMutations);
 
   observer.observe(rootElement, {
     attributes: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "Runtime-first reactivity",
   "main": "index.js",

package/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