@ape-egg/vibe 3.0.2 → 3.0.4

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 3.0.2** — Runtime-first reactivity for plain HTML. Drop a script tag into any page and get reactive bindings, control flow, and URL-loaded components — no build step required. Compile later if you want; the compiler is a separate, optional package (`@ape-egg/vibe-compiler`).
+**Version 3.0.4** — Runtime-first reactivity for plain HTML. Drop a script tag into any page and get reactive bindings, control flow, and URL-loaded components — no build step required. Compile later if you want; the compiler is a separate, optional package (`@ape-egg/vibe-compiler`).
 
 ## Security model & CSP
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "type": "module",
   "description": "Runtime-first reactivity for plain HTML — no build step, no virtual DOM, no new syntax to learn",
   "main": "index.js",

package/runtime/affected.js

@@ -309,18 +309,29 @@ const recursive = (
     // catches outer-state bindings inside rows. Plain paths keep pure ref
     // semantics — `$.items = [...$.items]` after an in-place item mutation must
     // still refresh every row (the documented reassign-to-rerender pattern).
+    //
+    // "Already right" additionally requires the RENDERED rows to correspond to
+    // the array: an iteration whose initial render evaluated before its
+    // component's script settled (a fetched compiled fragment defining the
+    // helper) bailed with zero instances — its two evals now agree ("2, 6"
+    // literals produce equal fresh arrays every flush) but nothing is on
+    // screen, and skipping here would strand it empty forever (the game's
+    // "# Teams" BoxRange). Instance count vs array length is that invariant.
     if (oldArray !== newArray) {
       const freshRefArtifact =
         CALL_EXPR_REGEX.test(resolvedExpr) &&
         Array.isArray(oldArray) &&
         Array.isArray(newArray) &&
         oldArray.length === newArray.length &&
+        (tree.runtime.instances?.length ?? 0) === newArray.length &&
         oldArray.every((item, i) => item === newArray[i]);
       if (!freshRefArtifact) {
         affected.push({
           type: "iteration",
           node: tree,
           changeType: "array",
+          scopedState: newState,
+          oldScopedState: state,
         });
         return affected;
       }
@@ -351,6 +362,8 @@ const recursive = (
               type: "iteration",
               node: tree,
               changeType: "array",
+              scopedState: newState,
+              oldScopedState: state,
             });
             return affected;
           }

package/runtime/hydrate.js

@@ -3,7 +3,12 @@ import { updateConditional, managedNodes } from './conditionals.js';
 import { liveComponentWrapper, remountComponent, forceRemount } from './component.js';
 import { isComponentWrapper, parkRootFor, parkBinding } from './staging.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
-import { evalInScope, resolveCaseInsensitivePath, overlayKeysOf } from './utils.js';
+import {
+  evalInScope,
+  resolveCaseInsensitivePath,
+  overlayKeysOf,
+  scopedOverlayOf,
+} from './utils.js';
 import { RawHtml } from './raw-html.js';
 import { beginTracking, endTracking } from './tracking.js';
 import { reportEvalError } from './debug.js';
@@ -199,9 +204,24 @@ export default (affected, state, manifest = {}, oldState = {}) => {
     // Use scoped state if provided (from iteration instances)
     const effectiveState = aff.scopedState || state;
 
-    // Handle iteration updates
+    // Handle iteration updates. Same scoped-pair contract as conditionals
+    // below: a NESTED iteration re-renders its rows against the enclosing
+    // row's scope, so bindings reading the outer alias (`@[ability.healing]`
+    // inside `<!-- each ability.chainDividers as d -->`) still resolve. The
+    // overlay doubles as the nested parentScope — exactly what the initial
+    // render passes (renderAllIterations with `{...parentScope, ...localVars}`).
+    // Top-level iterations carry the cycle's state and no overlay, so they
+    // keep resolving against globals.
     if (aff.type === 'iteration') {
-      updateIteration(aff.node, state, oldState, manifest);
+      const iterNewState = aff.scopedState || state;
+      const iterOldState = aff.oldScopedState || oldState;
+      updateIteration(
+        aff.node,
+        iterNewState,
+        iterOldState,
+        manifest,
+        scopedOverlayOf(iterNewState) || {},
+      );
       return;
     }
 
@@ -338,7 +358,11 @@ export default (affected, state, manifest = {}, oldState = {}) => {
       // Function replacer: a string replacement would run GetSubstitution on
       // the VALUE — `$$` collapses, `$&` re-inserts the binding text into the
       // DOM (which the settle gates then read as an unhydrated binding).
-      const toReplace = input.replaceAll(matchOuter, () => evaluated).trim();
+      // No trim: the text node's source whitespace is significant — a
+      // prettier line-wrap after an inline end tag (`</strong>\n  remain`)
+      // is that word's boundary, and the compiled SPA shell stamps values
+      // untrimmed, so trimming here glued words and diverged from the shell.
+      const toReplace = input.replaceAll(matchOuter, () => evaluated);
 
       affected.forEach((innerAff) => {
         if (innerAff.element === element) {

package/runtime/iterate.js

@@ -190,17 +190,6 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
   const componentId = anchorEl ? findComponentIdForElement(anchorEl) : null;
   const domPropertyWrites = [];
 
-  // Trim binding-bearing text nodes — the clone path writes the interpolated
-  // text node content trimmed (hydrate.js), so the batch template must not
-  // carry the author's indentation around a binding that sits on its own line.
-  const textWalker = document.createTreeWalker(tplClone, NodeFilter.SHOW_TEXT);
-  while (textWalker.nextNode()) {
-    const textNode = textWalker.currentNode;
-    if (textNode.textContent.includes('@[')) {
-      textNode.textContent = textNode.textContent.trim();
-    }
-  }
-
   const allEls = tplClone.querySelectorAll('*');
   for (let n = 0; n < allEls.length; n++) {
     const el = allEls[n];
@@ -412,33 +401,91 @@ export const releaseOrphanedIterationProps = (nodes) => {
 // inherits `_vibeIterPropExprs`/`data-vibe-iter-prop`, so refreshIterationComponentProps
 // re-evaluates them on each item change). Globals-only bindings are left raw; they
 // resolve through the normal reactive path against the inlined component's scope.
+const SLOT_DIRECTIVE_REGEX = /<!--\s*(if|else if|each)\s+([^]*?)\s*-->/g;
+
+// Substitute an identifier only outside string literals — the same contract as
+// component.js's prop substitution: an alias that also appears inside a quoted
+// string ('materials' containing the alias name) must be left intact.
+const STRING_LITERAL_REGEX = /(['"`])(?:\\.|(?!\1)[^\\])*\1/g;
+const substituteOutsideStrings = (expr, idRegex, replacement) => {
+  let out = '';
+  let last = 0;
+  let m;
+  STRING_LITERAL_REGEX.lastIndex = 0;
+  while ((m = STRING_LITERAL_REGEX.exec(expr))) {
+    out += expr.slice(last, m.index).replace(idRegex, replacement) + m[0];
+    last = m.index + m[0].length;
+  }
+  return out + expr.slice(last).replace(idRegex, replacement);
+};
+
 const resolveSlotContentBindings = (el, scopedState, aliases) => {
   const html = el._vibeSlotContent;
-  if (!html || !html.includes('@[')) return;
+  if (!html || (!html.includes('@[') && !html.includes('<!--'))) return;
   const registry = ensureIterPropsRegistry();
   const idByExpr = new Map();
-  const rewritten = html.replace(BINDING_REGEX, (whole, expr) => {
-    const usesLocalScope =
-      /\bthis\b/.test(expr) ||
-      (aliases && extractDependencies(expr).some((d) => aliases.has(d)));
-    if (!usesLocalScope) return whole;
+  // Snapshot one expression into a registry slot, reusing the slot for repeat
+  // occurrences. Returns undefined (leave raw) when evaluation fails or yields
+  // undefined — same fail-safe as resolveIterationComponentProps.
+  const snapshot = (expr) => {
     let id = idByExpr.get(expr);
     if (id === undefined) {
       let value;
       try {
         value = evalInScope(expr, scopedState, el);
       } catch {
-        return whole;
+        return undefined;
       }
-      if (value === undefined) return whole;
+      if (value === undefined) return undefined;
       id = `_p${__vibeIterPropCounter++}`;
       registry[id] = value;
       idByExpr.set(expr, id);
       (el._vibeIterPropExprs = el._vibeIterPropExprs || []).push({ id, attrName: null, expr });
       (el._vibeIterPropIds = el._vibeIterPropIds || []).push(id);
     }
-    return `@[window.__vibe.iterProps.${id}]`;
+    return id;
+  };
+  let rewritten = html.replace(BINDING_REGEX, (whole, expr) => {
+    const usesLocalScope =
+      /\bthis\b/.test(expr) ||
+      (aliases && extractDependencies(expr).some((d) => aliases.has(d)));
+    if (!usesLocalScope) return whole;
+    const id = snapshot(expr);
+    return id === undefined ? whole : `@[window.__vibe.iterProps.${id}]`;
   });
+  // Directive comments in slot content — <!-- if -->, <!-- else if -->,
+  // <!-- each --> — hit the same wall as @[...] bindings: after processComponent
+  // inlines the template, the wrapper's subtree is re-processed against global
+  // state, where the loop aliases don't resolve and every branch renders empty
+  // (the battleborn rewards-window icons). Route each alias the expression
+  // reads through its own registry slot (`drop.kind === 'materials'` →
+  // `window.__vibe.iterProps._pN.kind === ...`), so the inlined directive
+  // evaluates against the row's values in any scope. Updates need no extra
+  // wiring: refreshIterationComponentProps re-snapshots the alias per row
+  // update, the rewritten expression records no state read so its subscriber
+  // re-dispatches from the tracking always-bucket on every flush, and the
+  // affected() pass over the wrapper's tree stamps that subscriber's lastScope
+  // with the row's merged scope — so a branch flip mounts with the loop
+  // aliases reachable. A registry-backed <!-- each --> is driven by
+  // forceRegistryBackedIterationUpdates like any other registry iteration.
+  if (aliases?.size) {
+    rewritten = rewritten.replace(SLOT_DIRECTIVE_REGEX, (whole, kw, expr) => {
+      // An each's alias clause introduces fresh names — only its array
+      // expression is rewritable.
+      const asMatch = kw === 'each' && expr.match(/^([^]*?)\s+as\s+([^]*)$/);
+      const original = asMatch ? asMatch[1] : expr;
+      let code = original;
+      for (const dep of extractDependencies(code)) {
+        if (!aliases.has(dep)) continue;
+        const id = snapshot(dep);
+        if (id === undefined) continue;
+        const idRegex = new RegExp(`(?<![\\w$.])${dep}(?![\\w$])`, 'g');
+        code = substituteOutsideStrings(code, idRegex, `window.__vibe.iterProps.${id}`);
+      }
+      if (code === original) return whole;
+      return `<!-- ${kw} ${asMatch ? `${code} as ${asMatch[2]}` : code} -->`;
+    });
+  }
   if (idByExpr.size) {
     el._vibeSlotContent = rewritten;
     el.setAttribute('data-vibe-iter-prop', '');
@@ -588,6 +635,13 @@ const refreshIterationComponentProps = (clonedNodes, scopedState) => {
 // in sync. Without this, an `<inner-component>` whose template iterates over
 // an array prop stays frozen on its initial-render items when the prop's
 // contents change.
+// Registry-backed CONDITIONALS (rewritten by resolveSlotContentBindings) need
+// no counterpart here: their evaluation records no state read, so they sit in
+// the tracking always-bucket and re-dispatch on every flush — and the
+// affected() pass below stamps their subscriber's lastScope with this row's
+// merged scope, so the dispatch flips the branch with the loop aliases in
+// reach (letting the mounting branch hydrate alias bindings whose build-time
+// snapshot was undefined, e.g. drop.item.icon before an icon exists).
 const REGISTRY_SLOT_REGEX = /__vibe\.iterProps\.(_p\d+)/;
 const forceRegistryBackedIterationUpdates = (tree, state, manifest, parentScope, changedSlots) => {
   if (!tree) return;

package/runtime/pre-compiled-manifest.js

@@ -411,43 +411,53 @@ export const restoreMarkersFromManifest = (
 
     // IMPORTANT: Restore text nodes BEFORE processing conditionals/iterations
     // Text nodes use childNodes indices which become invalid after DOM modifications
+    // Ascending index order, same invariant the directive restoration below
+    // relies on: each text node is returned to its pre-stamp state before a
+    // later index is consulted, so every index stays valid as we go.
     if (tree.children) {
-      for (const key in tree.children) {
-        if (key.startsWith("text_")) {
-          const childTree = tree.children[key];
-          const restoration = childTree.compiled?.restoration;
-
-          if (restoration?.parsed && Array.isArray(restoration.parsed)) {
-            const hasBindings = restoration.parsed.some(
-              (item) => typeof item === "string" && item.includes("@["),
-            );
-
-            if (hasBindings) {
-              // Transform component-scoped bindings back to this. format
-              let originalContent = restoration.parsed.join("");
-              originalContent = originalContent.replace(
-                /@\[_c\d+\./g,
-                "@[this.",
-              );
+      const texts = Object.keys(tree.children)
+        .filter((key) => key.startsWith("text_"))
+        .map((key) => ({ key, index: Number(key.match(/_(\d+)$/)?.[1]) }))
+        .filter(({ index }) => Number.isInteger(index))
+        .sort((a, b) => a.index - b.index);
 
-              // Extract index from key (e.g., text_0 -> 0)
-              const match = key.match(/_(\d+)$/);
-              if (match) {
-                const index = parseInt(match[1], 10);
-
-                if (index < element.childNodes.length) {
-                  const textNode = element.childNodes[index];
-                  if (textNode && textNode.nodeType === Node.TEXT_NODE) {
-                    textNode.textContent = originalContent;
-                  }
-                }
-              }
+      for (const { key, index } of texts) {
+        const childTree = tree.children[key];
+        const restoration = childTree.compiled?.restoration;
+
+        if (restoration?.parsed && Array.isArray(restoration.parsed)) {
+          const hasBindings = restoration.parsed.some(
+            (item) => typeof item === "string" && item.includes("@["),
+          );
+
+          if (hasBindings) {
+            // Transform component-scoped bindings back to this. format
+            const originalContent = restoration.parsed
+              .join("")
+              .replace(/@\[_c\d+\./g, "@[this.");
+
+            const node = element.childNodes[index];
+            if (node && node.nodeType === Node.TEXT_NODE) {
+              node.textContent = originalContent;
+            } else {
+              // The stamp ELIDED this text node: every binding in it rendered
+              // to an empty string, and an empty text node has no HTML
+              // serialization, so the compiled page carries no node here at all
+              // (`<out>@[removed.join(',')]</out>` with an empty array stamps to
+              // `<out></out>`). Recreate it at its recorded index — otherwise
+              // the marker never returns and the binding is dead for the page's
+              // lifetime, and every later sibling index at this level is off by
+              // one, so their restorations silently miss too.
+              element.insertBefore(
+                document.createTextNode(originalContent),
+                node ?? null,
+              );
             }
           }
+        }
 
-          if (childTree.compiled) {
-            delete childTree.compiled.restoration;
-          }
+        if (childTree.compiled) {
+          delete childTree.compiled.restoration;
         }
       }
     }

package/runtime/state.js

@@ -1,4 +1,4 @@
-import { recordRead } from './tracking.js';
+import { recordRead, recordAbsentRead, isTracking } from './tracking.js';
 
 // Track which objects are already proxied to avoid double-wrapping
 const proxyCache = new WeakMap();
@@ -124,7 +124,18 @@ const createDeepProxy = (target, rerender, rootState = null, rootProp = null) =>
       // the ROOT key it descended from. This is what makes helper bodies
       // truthful dependencies — `isPremium()` reading `$.premiumUntil` via
       // closure lands here mid-evaluation. One null check when inactive.
-      recordRead(rootProp === null ? prop : rootProp);
+      // A root-level read of a key the state does NOT have is an ABSENT read
+      // — same discipline as dollarFor's snapshot wrapper. Counting it live
+      // denies the subscriber the always-bucket and indexes it under a key
+      // that may never change: resolvePath fed a whole call expression
+      // (`literalRangeCells(2, 6)` — the eval-failed fallback treats it as a
+      // path) records one garbage "live" dep and the iteration is never
+      // re-selected (the game's "# Teams" BoxRange stranding empty).
+      if (rootProp === null && isTracking() && typeof prop === 'string' && !(prop in target)) {
+        recordAbsentRead(prop);
+      } else {
+        recordRead(rootProp === null ? prop : rootProp);
+      }
 
       const value = Reflect.get(target, prop);
 

package/runtime/tracking.js

@@ -58,6 +58,7 @@ const dropFromBuckets = (sub, deps) => {
   }
 };
 
+
 const commit = ({ sub, reads, absent, sawScope }) => {
   const prev = subDeps.get(sub);
   if (prev) dropFromBuckets(sub, prev);
@@ -83,6 +84,11 @@ const commit = ({ sub, reads, absent, sawScope }) => {
   subDeps.set(sub, deps);
 };
 
+// Whether a tracking window is open — state.js's get trap consults this so
+// its own-key presence test (recordRead vs recordAbsentRead) only runs while
+// an evaluation is actually being tracked.
+export const isTracking = () => active !== null;
+
 // The single recording entry point — called from state.js's get trap,
 // evalInScope's parameter resolution, dollarFor's snapshot wrapper, and
 // createScopedState's global fallthrough. One null check when inactive.