@ape-egg/vibe 1.0.5 → 1.1.2

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/ROADMAP.md

@@ -1,289 +0,0 @@
-# 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*