@ape-egg/vibe 1.9.5 → 1.9.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.9.6] - 2026-05-25
+
+### Fixed
+
+- **Loop item lost reference identity across mutations** (`runtime/state.js`, `runtime/iterate.js`, `runtime/index.js`, `runtime/loop-scope.js`) — the object a loop handed its `on*` handlers was no longer `=== $.arr[i]` after a `splice`/`push`, so identity-based code (`$.arr.indexOf(item)`, `item === $.arr[i]`) targeted the wrong row — e.g. removing two items by identity in a row would delete the wrong second row. Two compounding causes:
+  - **Proxy double-wrapping** (`state.js`) — the deep proxy's `get` handed back a fresh proxy for nested elements, and array methods/assignments wrote that proxy back into the tree; the next read wrapped it *again*, minting a new proxy identity for the same underlying object (and making change detection compare a stored proxy against a raw, never equal). Added a `RAW` symbol so any of our proxies can expose its raw target, plus an `unwrap` helper used in `set` (never store a proxy in the raw tree) and at `createDeepProxy` entry (collapse a proxy that slipped in nested inside an assigned object literal). The cache now always returns the single canonical proxy per object.
+  - **Loop var was a diff-snapshot clone** (`iterate.js`, `index.js`, `loop-scope.js`) — iterations render against `extractPlainValue($)` plain clones, which are never reference-identical to the proxy elements the app sees through `$`. The runtime now exposes the live proxy as `manifest.__live`; `resolveLiveArray` re-resolves the loop's array against it and each instance carries a `liveItem` that `stampInstanceScopes` prefers, so `$scope(this,'alias')` handlers (and nested conditionals stamping `__vibeScope`) receive live identity. Diffing still keys off the plain `inst.item`; only the handler-facing value is live. Falls back to the plain item when the live array can't be resolved (no worse than before).
+  - Test: `tests/e2e/iteration-item-identity.spec.js` (handler receives the exact state-array element; identity-based removal targets the right item twice in a row across splices)
+
+---
+
 ## [1.9.5] - 2026-05-23
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.9.5",
+  "version": "1.9.6",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",

package/runtime/component.js

@@ -397,6 +397,11 @@ const processSingle = (el, debug) => {
           if (!registeredComponentIds.includes(componentId)) {
             registeredComponentIds.push(componentId);
           }
+          // Return the id so consumers can reach their reactive state via
+          // `$[id]` — matches the public component.js contract. Without this,
+          // `const id = component(state)` is undefined for src-fetched
+          // components and `$[id]` silently resolves to nothing.
+          return componentId;
         };
 
         // Re-running the script for a reused componentId (HMR remount) must

package/runtime/index.js

@@ -665,6 +665,13 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
 
+  // Expose the live reactive proxy to the iteration stamper so loop-scoped
+  // `on*` handlers (`$scope`) resolve the SAME object identity the app sees via
+  // `$`, instead of the plain diff-snapshot clones iterations render against
+  // (see extractPlainValue below). Non-enumerable so it never shows up in the
+  // manifest's node-path entry iteration.
+  Object.defineProperty(manifest, '__live', { value: $, enumerable: false, configurable: true });
+
   // Initial hydration - pass plain values so iteration can do reference comparison
   const initialState = extractPlainValue($);
   const affectedElements = affected(parsedTree, initialState, initialState);

package/runtime/iterate.js

@@ -476,7 +476,48 @@ const applyDomPropertyWrites = (instances, array, state, itemAlias, indexAlias,
   }
 };
 
-const renderBatch = (iterationNode, array, state, parent, endComment, parentScope = {}) => {
+// Resolve the loop's array against the LIVE `$` proxy root (not the plain
+// diff-snapshot the pipeline renders against — see extractPlainValue in
+// index.js). The plain clones are never reference-identical to the proxy
+// elements the app sees through `$`, so a loop var that flows into an `on*`
+// handler must come from here for `item === $.arr[i]` to hold. Returns null
+// when unresolvable (no live root yet, a derivation that builds fresh objects,
+// or a nested loop whose source hangs off an outer plain item) — callers fall
+// back to the plain item, which is no worse than the pre-fix behavior.
+const resolveLiveArray = (iterationNode, manifest, parentScope = {}) => {
+  const liveRoot = (manifest && manifest.__live) || globalThis.$;
+  if (!liveRoot) return null;
+  try {
+    const { arrayPath, startComment } = iterationNode.meta;
+    const parentEl = startComment.parentElement;
+    const resolved = resolveThisPath(arrayPath, parentEl);
+    const liveScoped = createScopedState(liveRoot, {}, parentScope);
+    const a = evalInScope(resolved, liveScoped, parentEl) ?? resolvePath(liveScoped, resolved);
+    return Array.isArray(a) ? a : null;
+  } catch {
+    return null;
+  }
+};
+
+const liveItemAt = (liveArray, index, fallback) =>
+  liveArray && index < liveArray.length ? liveArray[index] : fallback;
+
+// Refresh each instance's `liveItem` (the live `$`-proxy element handed to
+// loop-scoped `$scope` handlers, set when the instance was built) and stamp
+// scope. Re-resolving here keeps `liveItem` correct after the diff reorders or
+// updates instances. Diffing still keys off the plain `inst.item`; only the
+// handler-facing `$scope` value is live.
+const stampScopes = (iterationNode, manifest, parentScope = {}) => {
+  const liveArray = resolveLiveArray(iterationNode, manifest, parentScope);
+  const instances = iterationNode.runtime.instances;
+  for (let k = 0; k < instances.length; k++) {
+    const inst = instances[k];
+    inst.liveItem = liveItemAt(liveArray, inst.index, inst.item);
+  }
+  stampInstanceScopes(iterationNode, parentScope);
+};
+
+const renderBatch = (iterationNode, array, state, parent, endComment, parentScope = {}, manifest) => {
   const { itemAlias, indexAlias, template } = iterationNode.meta;
 
   if (!iterationNode.runtime.batchFn) {
@@ -512,7 +553,7 @@ const renderBatch = (iterationNode, array, state, parent, endComment, parentScop
   }
 
   // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
-  stampInstanceScopes(iterationNode, parentScope);
+  stampScopes(iterationNode, manifest, parentScope);
 };
 
 /**
@@ -866,9 +907,16 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   // detached during hydrate (see findComponentIdForElement's detached fallback).
   const componentId = findComponentIdForElement(startComment.parentElement);
 
+  // Live `$`-proxy elements for the loop alias, so nested conditionals (which
+  // stamp `__vibeScope` from this scoped state) and `$scope` handlers receive
+  // the same identity the app sees through `$`. `inst.item` stays the plain
+  // snapshot value for the diff.
+  const liveArray = resolveLiveArray(iterationNode, manifest, parentScope);
+
   for (let i = 0; i < array.length; i++) {
     const item = array[i];
-    const localVars = { [itemAlias]: item, [indexAlias]: i };
+    const liveItem = liveItemAt(liveArray, i, item);
+    const localVars = { [itemAlias]: liveItem, [indexAlias]: i };
     const scopedState = createScopedState(state, localVars, parentScope);
 
     // Clone, parse, hydrate
@@ -890,7 +938,7 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
       _renderAllConditionals(tree, scopedState, manifest, nestedScope);
     }
 
-    instances.push({ element, tree, item, index: i, clonedNodes, scopedState });
+    instances.push({ element, tree, item, liveItem, index: i, clonedNodes, scopedState });
   }
 
   // Single DOM insertion for all items
@@ -898,7 +946,7 @@ export const renderIteration = (iterationNode, state, manifest, parentScope = {}
   iterationNode.runtime.instances = instances;
 
   // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
-  stampInstanceScopes(iterationNode, parentScope);
+  stampScopes(iterationNode, manifest, parentScope);
 
   // Mark comment as rendered (survives re-parsing since comment nodes persist in DOM)
   // Also store runtime data on the DOM node so it persists across re-parses
@@ -1071,7 +1119,7 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
 
   // Re-stamp after the diff settles: moved/updated instances now carry their
   // current item + index, so `$scope` handlers resolve correctly post-reorder.
-  stampInstanceScopes(iterationNode, parentScope);
+  stampScopes(iterationNode, manifest, parentScope);
 };
 
 // Bulk replacement: clear all DOM and re-render from scratch
@@ -1096,7 +1144,7 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
   // For simple templates (no nested iterations/conditionals, single root element),
   // use batch string rendering: one string concatenation loop + one innerHTML parse
   if (canUseBatchRender(template)) {
-    renderBatch(iterationNode, newArray, state, parent, endComment, parentScope);
+    renderBatch(iterationNode, newArray, state, parent, endComment, parentScope, manifest);
     const instances = iterationNode.runtime.instances;
     for (let i = 0; i < instances.length; i++) {
       if (instances[i].element?.nodeType === 1) managedNodes.add(instances[i].element);
@@ -1109,12 +1157,13 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
   // parent.insertBefore call.
   const instances = [];
   const frag = document.createDocumentFragment();
+  const liveArray = resolveLiveArray(iterationNode, manifest, parentScope);
   for (let i = 0; i < newArray.length; i++) {
-    const built = buildInstance(iterationNode, newArray[i], i, state, parentScope);
+    const built = buildInstance(iterationNode, newArray[i], i, state, parentScope, liveItemAt(liveArray, i, newArray[i]));
     for (let j = 0; j < built.clonedNodes.length; j++) frag.appendChild(built.clonedNodes[j]);
     finalizeInstance(built, manifest, parentScope);
     instances.push({
-      element: built.element, tree: built.tree, item: newArray[i], index: i,
+      element: built.element, tree: built.tree, item: newArray[i], liveItem: built.liveItem, index: i,
       clonedNodes: built.clonedNodes, scopedState: built.scopedState,
     });
   }
@@ -1122,7 +1171,7 @@ const bulkReplace = (iterationNode, newArray, state, manifest, parentScope) => {
   iterationNode.runtime.instances = instances;
 
   // Stamp loop scope so `$scope(this,'alias')` handlers resolve the live item.
-  stampInstanceScopes(iterationNode, parentScope);
+  stampScopes(iterationNode, manifest, parentScope);
 };
 
 // Find an instance's canonical in-DOM anchor (the first of its cloned nodes
@@ -1191,14 +1240,19 @@ const detachInstanceDom = (iterationNode, index, parent) => {
 // Build a fresh instance's DOM + tree + scope from the iteration template.
 // Pure function — no DOM insertion, no side effects on iteration state.
 // Callers decide where the clones go (iteration parent, DocumentFragment).
-const buildInstance = (iterationNode, item, index, state, parentScope) => {
+// `liveItem` (resolved by the caller via resolveLiveArray, so a derived-array
+// loop evaluates the expression once per render, not once per row) is the live
+// `$`-proxy element for this index. Building scope from it gives nested
+// conditional stamps and `$scope` handlers the app-visible identity; `item`
+// (plain snapshot) is still tracked for the diff.
+const buildInstance = (iterationNode, item, index, state, parentScope, liveItem) => {
   const { itemAlias, indexAlias, template, startComment } = iterationNode.meta;
-  const localVars = { [itemAlias]: item, [indexAlias]: index };
+  const localVars = { [itemAlias]: liveItem, [indexAlias]: index };
   const scopedState = createScopedState(state, localVars, parentScope);
   const componentId = findComponentIdForElement(startComment.parentElement);
   const built = initializeBlock([...template.element.childNodes], scopedState, template, componentId, new Set(iterationNode.meta.scopeAliases));
   resolveIterationComponentProps(built.clonedNodes, scopedState);
-  return { ...built, scopedState, localVars };
+  return { ...built, scopedState, localVars, liveItem };
 };
 
 // After a built instance's clones are placed in the DOM (directly or via a
@@ -1220,12 +1274,13 @@ const finalizeInstance = (built, manifest, parentScope) => {
 
 const addInstance = (iterationNode, item, index, state, manifest, parentScope) => {
   const parent = iterationNode.meta.startComment.parentNode;
-  const built = buildInstance(iterationNode, item, index, state, parentScope);
+  const liveItem = liveItemAt(resolveLiveArray(iterationNode, manifest, parentScope), index, item);
+  const built = buildInstance(iterationNode, item, index, state, parentScope, liveItem);
   const insertBefore = resolveInsertBefore(iterationNode, index, parent);
   for (let i = 0; i < built.clonedNodes.length; i++) parent.insertBefore(built.clonedNodes[i], insertBefore);
   finalizeInstance(built, manifest, parentScope);
   iterationNode.runtime.instances.splice(index, 0, {
-    element: built.element, tree: built.tree, item, index, clonedNodes: built.clonedNodes,
+    element: built.element, tree: built.tree, item, liveItem: built.liveItem, index, clonedNodes: built.clonedNodes,
   });
 };
 
@@ -1267,7 +1322,8 @@ const updateInstanceRebuild = (iterationNode, index, newItem, state, manifest, p
   const parent = iterationNode.meta.startComment.parentNode;
   const instance = iterationNode.runtime.instances[index];
 
-  const built = buildInstance(iterationNode, newItem, index, state, parentScope);
+  const liveItem = liveItemAt(resolveLiveArray(iterationNode, manifest, parentScope), index, newItem);
+  const built = buildInstance(iterationNode, newItem, index, state, parentScope, liveItem);
   detachInstanceDom(iterationNode, index, parent);
   const insertBefore = resolveInsertBefore(iterationNode, index + 1, parent);
   for (let i = 0; i < built.clonedNodes.length; i++) parent.insertBefore(built.clonedNodes[i], insertBefore);
@@ -1276,6 +1332,7 @@ const updateInstanceRebuild = (iterationNode, index, newItem, state, manifest, p
   instance.element = built.element;
   instance.tree = built.tree;
   instance.item = newItem;
+  instance.liveItem = built.liveItem;
   instance.clonedNodes = built.clonedNodes;
   instance.scopedState = built.scopedState;
 };

package/runtime/loop-scope.js

@@ -141,7 +141,11 @@ export const stampInstanceScopes = (iterationNode, parentScope = {}) => {
   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 };
+    // `liveItem` (set by stampScopes in iterate.js) is the live `$`-proxy
+    // element so handlers get the identity the app sees; `item` is the plain
+    // diff-snapshot clone used for rendering. Prefer live when available.
+    const item = inst.liveItem !== undefined ? inst.liveItem : inst.item;
+    const scope = { ...parentScope, [itemAlias]: item, [indexAlias]: inst.index };
     const roots = inst.clonedNodes || (inst.element ? [inst.element] : []);
     for (let r = 0; r < roots.length; r++) {
       const node = roots[r];

package/runtime/state.js

@@ -1,6 +1,20 @@
 // Track which objects are already proxied to avoid double-wrapping
 const proxyCache = new WeakMap();
 
+// Reading this symbol off any of our reactive proxies returns its raw
+// (unproxied) target; on anything else it's undefined. `unwrap` uses it to
+// collapse a proxy back to its raw object. This keeps object identity stable
+// across mutations: array methods (splice/push) and assignments read an element
+// — which `get` hands back as a proxy — and write it back into the tree; if we
+// stored the proxy, the next read would wrap it AGAIN, minting a fresh proxy
+// identity for the same underlying object. That would break reference identity
+// (a loop item would no longer be `=== $.arr[i]` after a splice) and make change
+// detection fire forever (a stored proxy never `===` the raw it's compared to).
+const RAW = Symbol('vibeRaw');
+
+const unwrap = (value) =>
+  value !== null && typeof value === 'object' && value[RAW] !== undefined ? value[RAW] : value;
+
 // Batching: collect mutations and flush once per microtask
 let pendingFlush = false;
 let flushCallback = null;
@@ -20,6 +34,12 @@ const scheduleFlush = () => {
 
 // Deep proxy: recursively wrap nested objects and arrays
 const createDeepProxy = (target, rerender, rootState = null, rootProp = null) => {
+  // Never wrap one of our own proxies — collapse to its raw target so the cache
+  // returns the single canonical proxy. Covers a proxy that slipped into the
+  // tree nested inside an assigned object literal (set only unwraps the
+  // top-level value), which would otherwise double-wrap on read.
+  target = unwrap(target);
+
   // For root level, rootState is the target itself
   if (rootState === null) {
     rootState = target;
@@ -33,6 +53,9 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
 
   const proxy = new Proxy(target, {
     set(obj, prop, value) {
+      // Never store one of our proxies in the raw tree — store its raw target,
+      // so element identity stays stable across mutations (see RAW comment).
+      value = unwrap(value);
       const oldValue = obj[prop];
 
       // Only trigger rerender if value actually changed
@@ -68,6 +91,10 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
     },
 
     get(target, prop) {
+      // Expose the raw target so `unwrap` (and external identity checks) can
+      // recover the unproxied object from any of our proxies.
+      if (prop === RAW) return target;
+
       const value = Reflect.get(target, prop);
 
       // Don't proxy non-objects, functions, null, or Promises.