@ape-egg/vibe 1.9.1 → 1.9.5

package/runtime/iteration-utils.js

@@ -177,8 +177,15 @@ export const longestCommonSubsequence = (arr1, arr2) => {
   return lcs;
 };
 
-// Generate unique key for array items
-export const getItemKey = (item, index) => {
+// Generate unique key for array items.
+// `customKey` (when defined and not null) wins over every default heuristic —
+// the developer has declared identity explicitly via `<!-- each xs as x (expr) -->`.
+// The default heuristic only runs when no custom key was provided.
+export const getItemKey = (item, index, customKey) => {
+  if (customKey !== undefined && customKey !== null) {
+    return `key_${customKey}`;
+  }
+
   // 1. If item has 'id' property, use it
   if (item && typeof item === 'object' && 'id' in item) {
     return `id_${item.id}`;

package/runtime/loop-scope.js

@@ -0,0 +1,157 @@
+// Loop-scoped event handlers.
+//
+// An `on*` handler written inside a `<!-- each X as alias -->` loop can reference
+// the bare loop variable directly, e.g. `onclick="pick(ability)"`. At parse time
+// the alias token is rewritten to `$scope(this,'alias')`; at fire time that
+// global resolver walks up the DOM to the nearest instance root stamped with the
+// live item/index and returns it. This passes the *live object* (identity, not a
+// stringified copy), works for derived-source loops, and survives reorders — all
+// while keeping the handler a visible native `on*` attribute.
+//
+// See implement-loop-scoped-event-handlers.md for the full rationale.
+
+const IDENT_START = /[A-Za-z_$]/;
+const IDENT_PART = /[A-Za-z0-9_$]/;
+
+// Last non-whitespace character already emitted — lets us tell a standalone
+// identifier (rewrite) from a member access like `foo.alias` (leave alone).
+const lastNonSpace = (s) => {
+  for (let i = s.length - 1; i >= 0; i--) {
+    const c = s[i];
+    if (c !== ' ' && c !== '\t' && c !== '\n' && c !== '\r') return c;
+  }
+  return '';
+};
+
+// Copy a quoted string literal beginning at `i` (value[i] is the opening quote)
+// verbatim, honoring backslash escapes. Returns the index just past the closer.
+const copyString = (value, i, push) => {
+  const quote = value[i];
+  push(quote);
+  i++;
+  const n = value.length;
+  while (i < n) {
+    const c = value[i];
+    if (c === '\\') {
+      push(c);
+      i++;
+      if (i < n) {
+        push(value[i]);
+        i++;
+      }
+      continue;
+    }
+    push(c);
+    i++;
+    if (c === quote) break;
+  }
+  return i;
+};
+
+// Rewrite standalone references to loop-variable aliases inside an event-handler
+// expression into `$scope(this,'alias')` calls. Skips `@[...]` binding spans
+// (they keep their existing hydrate-time stringifying behavior), string literals,
+// and member accesses, so only identifiers that genuinely name a loop alias are
+// touched.
+export const rewriteHandlerAliases = (value, aliasSet) => {
+  if (!aliasSet || aliasSet.size === 0 || typeof value !== 'string') return value;
+
+  let out = '';
+  const push = (s) => {
+    out += s;
+  };
+  let i = 0;
+  const n = value.length;
+
+  while (i < n) {
+    const ch = value[i];
+
+    // @[...] binding span — copy verbatim. Track bracket depth and skip inner
+    // strings so a `]` inside a quoted expression doesn't close the span early.
+    if (ch === '@' && value[i + 1] === '[') {
+      push('@[');
+      i += 2;
+      let depth = 1;
+      while (i < n && depth > 0) {
+        const c = value[i];
+        if (c === "'" || c === '"') {
+          i = copyString(value, i, push);
+          continue;
+        }
+        if (c === '[') depth++;
+        else if (c === ']') depth--;
+        push(c);
+        i++;
+      }
+      continue;
+    }
+
+    // String literal — copy verbatim.
+    if (ch === "'" || ch === '"' || ch === '`') {
+      i = copyString(value, i, push);
+      continue;
+    }
+
+    // Identifier — rewrite when it's a standalone alias reference.
+    if (IDENT_START.test(ch)) {
+      let j = i + 1;
+      while (j < n && IDENT_PART.test(value[j])) j++;
+      const ident = value.slice(i, j);
+      const isMember = lastNonSpace(out) === '.';
+      if (!isMember && aliasSet.has(ident)) {
+        push(`$scope(this,'${ident}')`);
+      } else {
+        push(ident);
+      }
+      i = j;
+      continue;
+    }
+
+    push(ch);
+    i++;
+  }
+
+  return out;
+};
+
+// Walk up from `el` to the nearest ancestor stamped with a scope that defines
+// `name`, returning the live value. Returns undefined if no enclosing loop
+// defines the alias. Nested loops resolve naturally: the innermost stamp is hit
+// first; an outer alias is found by continuing up past inner stamps.
+export const resolveScope = (el, name) => {
+  let node = el;
+  while (node) {
+    const scope = node.__vibeScope;
+    if (scope && name in scope) return scope[name];
+    node = node.parentNode;
+  }
+  return undefined;
+};
+
+// Stamp the in-scope loop vars onto every iteration instance's root element
+// node(s). The stamp accumulates the enclosing loop vars (`parentScope`) plus
+// this loop's item/index, so a single innermost stamp resolves every alias in
+// scope — which is what makes arbitrarily nested `each`/`if` combinations work
+// even when a loop's template is purely another loop (no wrapper element to walk
+// up to). Re-applied after each render and update so a stamp always reflects the
+// current item/index — including after keyed reorders, where instance objects
+// keep current `.item`/`.index`.
+export const stampInstanceScopes = (iterationNode, parentScope = {}) => {
+  const { itemAlias, indexAlias } = iterationNode.meta;
+  const instances = iterationNode.runtime.instances;
+  for (let k = 0; k < instances.length; k++) {
+    const inst = instances[k];
+    const scope = { ...parentScope, [itemAlias]: inst.item, [indexAlias]: inst.index };
+    const roots = inst.clonedNodes || (inst.element ? [inst.element] : []);
+    for (let r = 0; r < roots.length; r++) {
+      const node = roots[r];
+      if (node && node.nodeType === 1) node.__vibeScope = scope;
+    }
+  }
+};
+
+// Install the global `$scope` resolver so native inline handlers (which run in
+// global scope at fire time) can call it. Idempotent across boots.
+export const installScopeResolver = () => {
+  globalThis.$scope = resolveScope;
+};

package/runtime/parse.js

@@ -8,6 +8,7 @@ import {
   DEHYDRATE_CLASS_OR_ATTR,
   THIS_PROP_REGEX,
 } from './constants.js';
+import { rewriteHandlerAliases } from './loop-scope.js';
 
 // Walks up the DOM for the nearest component wrapper tagged by component.js.
 // Used to rewrite `this.property` in event handlers to the component's state path.
@@ -23,7 +24,7 @@ const findComponentIdForElement = (element) => {
 // `<div class="component" src>`) returns nulls — its attributes are props
 // owned by processComponent and must stay raw; hydrating them would coerce
 // objects to "[object Object]" or strip boolean-like attrs to empty.
-const captureAttributeBindings = (element) => {
+const captureAttributeBindings = (element, aliasSet) => {
   const nodeName = element.nodeName;
   const isFetchedComponent =
     (nodeName === 'COMPONENT' || (nodeName === 'DIV' && element.classList?.contains('component'))) &&
@@ -46,15 +47,25 @@ const captureAttributeBindings = (element) => {
       continue;
     }
 
-    // Rewrite `this.property` inside event handlers to the component's state path.
-    if (attr.name.startsWith('on') && attr.value.includes('this.')) {
-      const componentId = findComponentIdForElement(element);
-      if (componentId) {
-        const rewritten = attr.value.replace(THIS_PROP_REGEX, (match, prop) => {
-          return DOM_ELEMENT_PROPERTIES.has(prop) ? match : `$['${componentId}'].${prop}`;
-        });
-        element.setAttribute(attr.name, rewritten);
+    // Event handlers get two compile-time rewrites, computed off the original
+    // value and written once:
+    //   1. `this.property` → the component's state path (component-local state).
+    //   2. bare loop-variable aliases → `$scope(this,'alias')` (loop-scoped
+    //      handlers — only when an enclosing <!-- each --> alias is in scope).
+    if (attr.name.startsWith('on')) {
+      let v = attr.value;
+      if (v.includes('this.')) {
+        const componentId = findComponentIdForElement(element);
+        if (componentId) {
+          v = v.replace(THIS_PROP_REGEX, (match, prop) =>
+            DOM_ELEMENT_PROPERTIES.has(prop) ? match : `$['${componentId}'].${prop}`,
+          );
+        }
+      }
+      if (aliasSet && aliasSet.size > 0) {
+        v = rewriteHandlerAliases(v, aliasSet);
       }
+      if (v !== attr.value) element.setAttribute(attr.name, v);
     }
 
     BINDING_REGEX.lastIndex = 0;
@@ -69,6 +80,29 @@ const captureAttributeBindings = (element) => {
   };
 };
 
+// Walk a parsed children map for any iteration node carrying scoped handlers.
+// Each iteration node's own flag already aggregates its descendants, so we take
+// the flag without re-descending into its template; we still recurse through
+// elements and conditional branches to reach nested iteration nodes.
+const subtreeHasScopedHandlers = (nodes) => {
+  for (const key in nodes) {
+    const node = nodes[key];
+    if (!node || typeof node !== 'object') continue;
+    if (node.type === 'iteration') {
+      if (node.meta?.hasScopedHandlers) return true;
+      continue;
+    }
+    if (node.type === 'conditional') {
+      const branches = node.meta?.branches;
+      if (branches?.if?.children && subtreeHasScopedHandlers(branches.if.children)) return true;
+      if (branches?.else?.children && subtreeHasScopedHandlers(branches.else.children)) return true;
+      continue;
+    }
+    if (node.children && subtreeHasScopedHandlers(node.children)) return true;
+  }
+  return false;
+};
+
 const parseHTML = (children, rootKey = undefined) =>
   children.reduce((s, element, i) => {
     const { nodeName, textContent } = element;
@@ -81,7 +115,7 @@ const parseHTML = (children, rootKey = undefined) =>
     return rootKey || `${s}${`\$[${innerNodeIdentifier}]`}`;
   }, '');
 
-const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats = { skipped: 0 }) => {
+const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats = { skipped: 0 }, aliasSet = new Set()) => {
   let result = {};
 
   for (let i = 0; i < children.length; i++) {
@@ -103,7 +137,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
       const iterationMatch = textContent.trim().match(ITERATION_REGEX);
 
       if (iterationMatch) {
-        const [_, arrayPath, itemAlias, indexAlias] = iterationMatch;
+        const [_, arrayPath, itemAlias, keyExpr, indexAlias] = iterationMatch;
 
         try {
           // Find matching end comment
@@ -118,8 +152,35 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
             templateContainer.appendChild(node.cloneNode(true));
           });
 
+          // Aliases in scope inside this loop's template = enclosing aliases plus
+          // this loop's item alias and (only when explicitly declared) its index
+          // alias. The implicit default index name is never auto-rewritten.
+          const childAliases = new Set(aliasSet);
+          childAliases.add(itemAlias);
+          if (indexAlias) childAliases.add(indexAlias);
+
           // Parse the template recursively
-          const templateParsed = recursive([...templateContainer.childNodes], undefined, new Set(), stats);
+          const templateParsed = recursive([...templateContainer.childNodes], undefined, new Set(), stats, childAliases);
+
+          // A handler rewritten to `$scope(this,'alias')` only exists in this
+          // freshly-parsed runtime template — the manifest's compiled batchFn was
+          // generated from the original (unrewritten) template, so it must be
+          // bypassed for this iteration (see canUseCompiled). True when a direct
+          // handler in this template was rewritten, OR a nested iteration carries
+          // scoped handlers (its inlined batchFn would be wrong too). The runtime
+          // clone / batch / diff paths all read the rewritten template correctly.
+          const hasScopedHandlers =
+            (childAliases.size > 0 && templateContainer.innerHTML.includes("$scope(this,")) ||
+            subtreeHasScopedHandlers(templateParsed);
+
+          // All aliases in scope inside this loop (enclosing + this loop's own) —
+          // passed back to parse() by iterate.js when it re-parses a cloned
+          // instance. Must be the ACCUMULATED set, not just this loop's own: a
+          // handler nested in a further if/each inside the loop can reference an
+          // outer alias that wasn't rewritten in this loop's own template (the
+          // inner structure's branch was extracted to a separate container), so
+          // the re-parse needs every enclosing alias to rewrite it.
+          const scopeAliases = [...childAliases];
 
           // Store iteration metadata (use index for deterministic keys)
           const iterationKey = `iteration_${i}`;
@@ -129,6 +190,9 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
               arrayPath,
               itemAlias,
               indexAlias: indexAlias || 'index',
+              keyExpr: keyExpr || null,
+              hasScopedHandlers,
+              scopeAliases,
               startComment: element,
               endComment: children[endIndex],
               template: {
@@ -183,8 +247,9 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
             trueBranchContainer.appendChild(node.cloneNode(true));
           });
 
-          // Parse the true branch recursively
-          const trueBranchParsed = recursive([...trueBranchContainer.childNodes], undefined, new Set(), stats);
+          // Parse the true branch recursively (loop aliases stay in scope
+          // inside a conditional nested within an iteration).
+          const trueBranchParsed = recursive([...trueBranchContainer.childNodes], undefined, new Set(), stats, aliasSet);
 
           // Extract false branch nodes if else exists
           let falseBranchParsed = null;
@@ -195,7 +260,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
             falseBranchNodes.forEach((node) => {
               falseBranchContainer.appendChild(node.cloneNode(true));
             });
-            falseBranchParsed = recursive([...falseBranchContainer.childNodes], undefined, new Set(), stats);
+            falseBranchParsed = recursive([...falseBranchContainer.childNodes], undefined, new Set(), stats, aliasSet);
           }
 
           // Store conditional metadata (use index for deterministic keys)
@@ -205,6 +270,10 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
             type: 'conditional',
             meta: {
               expression,
+              // Enclosing loop aliases — threaded back into parse() when
+              // mountBranch re-parses this branch, so loop-scoped handlers
+              // (including those nested deeper in further conditionals) rewrite.
+              scopeAliases: [...aliasSet],
               startComment: element,
               elseComment: elseIndex !== null ? children[elseIndex] : null,
               endComment: children[endIndex],
@@ -257,7 +326,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
     const elementForBindings = isTextNode ? element.parentElement : element;
     const textNodeRef = isTextNode ? element : null; // Store reference to actual text node
 
-    const { attributes, nameBindings } = captureAttributeBindings(element);
+    const { attributes, nameBindings } = captureAttributeBindings(element, aliasSet);
     const hasChildren = childNodes.length;
 
     if (hasChildren) {
@@ -267,7 +336,7 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
       result[rootKey || nodeIdentifier] = {
         parsed,
         element: elementForBindings,
-        children: recursive(iteratableChildren, undefined, new Set(), stats),
+        children: recursive(iteratableChildren, undefined, new Set(), stats, aliasSet),
         ...(attributes && { attributes }),
         ...(nameBindings && { nameBindings }),
         ...(textNodeRef && { textNode: textNodeRef }),
@@ -287,17 +356,22 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
   return result;
 };
 
-export default (root, rootKey = undefined) => {
+// `aliasSet` carries enclosing `<!-- each -->` aliases into the parse. The root
+// page parse passes none; iterate.js passes a loop's own aliases when it
+// re-parses a cloned instance subtree, so loop-scoped `on*` handlers (including
+// those in nested loops, via child-alias accumulation in recursive) rewrite to
+// `$scope(this,'alias')`.
+export default (root, rootKey = undefined, aliasSet = new Set()) => {
   const { childNodes } = root;
   const stats = { skipped: 0 };
 
-  const { attributes, nameBindings } = captureAttributeBindings(root);
+  const { attributes, nameBindings } = captureAttributeBindings(root, aliasSet);
 
   return {
     // html: root.outerHTML,
     parsed: parseHTML([...childNodes], rootKey),
     element: root,
-    children: recursive(Array.from(childNodes), rootKey, new Set(), stats),
+    children: recursive(Array.from(childNodes), rootKey, new Set(), stats, aliasSet),
     ...(attributes && { attributes }),
     ...(nameBindings && { nameBindings }),
     stats,

package/runtime/pre-compiled-iterations.js

@@ -8,6 +8,8 @@
  * Based on the prototype in _vibe-compiled-iteration-batch.js
  */
 
+import { stampInstanceScopes } from './loop-scope.js';
+
 // Reusable template element for parsing compiled HTML
 const parseTemplate = typeof document !== 'undefined' ? document.createElement('template') : null;
 
@@ -33,6 +35,14 @@ export const canUseCompiled = (iterationNode) => {
     return false;
   }
 
+  // A template with a loop-scoped `$scope(this,'alias')` handler was rewritten at
+  // parse time; the manifest's compiled batchFn predates that rewrite and would
+  // emit the bare, unresolvable alias. Fall back to the runtime path, which reads
+  // the rewritten template.
+  if (iterationNode.meta.hasScopedHandlers) {
+    return false;
+  }
+
   // Check compiled data from manifest merge
   const compiled = iterationNode.compiled;
   if (!compiled || !compiled.iterations || !compiled.iterations.batchFn) {
@@ -116,6 +126,7 @@ export const renderCompiled = (iterationNode, array, state, compiledMeta, parent
 
     parent.insertBefore(frag, endComment);
     iterationNode.runtime.instances = instances;
+    stampInstanceScopes(iterationNode);
     return true;
   }
 
@@ -159,6 +170,7 @@ export const updateCompiled = (iterationNode, newArray, state, compiledMeta, sta
 
     parent.insertBefore(frag, endComment);
     iterationNode.runtime.instances = instances;
+    stampInstanceScopes(iterationNode);
     return true;
   }
 

package/runtime/state.js

@@ -23,7 +23,7 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
   // For root level, rootState is the target itself
   if (rootState === null) {
     rootState = target;
-    flushCallback = (props) => rerender(props);
+    flushCallback = typeof rerender === 'function' ? (props) => rerender(props) : null;
   }
 
   // Check cache first
@@ -50,6 +50,23 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
       return Reflect.set(obj, prop, value);
     },
 
+    deleteProperty(obj, prop) {
+      // Without notifying changedProps + scheduleFlush, `delete $.foo` is
+      // invisible to the reactive pipeline — bindings depending on `foo` (or
+      // on `Object.keys($)`) keep showing the deleted value. Critical for
+      // component state cleanup: releaseOrphanedComponentState calls
+      // `delete window.$[id]` and downstream consumers (e.g. a state
+      // inspector iterating root keys) need to re-render.
+      if (!(prop in obj)) return Reflect.deleteProperty(obj, prop);
+
+      const ref = Reflect.deleteProperty(obj, prop);
+      if (ref) {
+        changedProps.add(rootProp || prop);
+        scheduleFlush();
+      }
+      return ref;
+    },
+
     get(target, prop) {
       const value = Reflect.get(target, prop);
 

package/runtime/utils.js

@@ -143,13 +143,48 @@ export const evalInScope = (expr, state, element = null) => {
   }
 };
 
+// Walk a dotted path against a state-like object, falling back to
+// case-insensitive key matching at each segment. Used by name-binding
+// hydration (clone + batch) to recover camelCase property names that the
+// HTML parser lowercased — `<icon @[fx.convertsIcon]>` arrives at the
+// runtime as `@[fx.convertsicon]`, which doesn't match `convertsIcon` on
+// `fx`. Bails on bracket/call expressions because those need a real
+// evaluator (and `evalInScope` already handled them).
+export const resolveCaseInsensitivePath = (state, path) => {
+  if (path.includes('[') || path.includes('(')) return undefined;
+  const segments = path.split('.');
+  let current = state;
+  for (const seg of segments) {
+    if (current == null) return undefined;
+    // Direct first — handles proxies (scoped iteration state) and plain objects.
+    if (Reflect.has(Object(current), seg)) {
+      current = current[seg];
+      continue;
+    }
+    if (typeof current !== 'object') return undefined;
+    const ci = Object.keys(current).find((k) => k.toLowerCase() === seg.toLowerCase());
+    if (!ci) return undefined;
+    current = current[ci];
+  }
+  return current;
+};
+
 // Helper to find component ID for an element
 // Walks up DOM tree to find nearest component wrapper
 export const findComponentIdForElement = (element) => {
   if (!element || !element.closest) return null;
 
   const wrapper = element.closest('[data-vibe-component-id]');
-  return wrapper ? wrapper.getAttribute('data-vibe-component-id') : null;
+  if (wrapper) return wrapper.getAttribute('data-vibe-component-id');
+  // Detached fallback: cloned-but-not-yet-attached subtrees (iteration row
+  // construction in `initializeBlock` parses + hydrates inside a fresh
+  // parseContainer before insertion). Walk back to the root and consult
+  // _vibeComponentId, which iteration code can stash on the parseContainer
+  // when it knows the row's owning component up front.
+  let root = element;
+  while (root.parentNode) root = root.parentNode;
+  if (root._vibeComponentId) return root._vibeComponentId;
+  return null;
 };
 
 // Helper to resolve this.property paths to componentId.property