@ape-egg/vibe 4.0.1 → 4.1.1

package/runtime/iteration-utils.js

@@ -1,4 +1,3 @@
-// Utility functions for array iteration
 import {
   ITERATION_REGEX,
   ITERATION_START_REGEX,
@@ -8,12 +7,6 @@ import {
   FETCH_SRC_SELECTOR,
 } from './constants.js';
 
-// Move binding-valued src/srcset/poster on browser-fetchable elements to
-// data-vibe-<attr> so the literal `@[...]` text never becomes a fetchable URL.
-// Called on subtrees that are still in the inert document (component finalize)
-// — parse.js recaptures the parked binding under the real attribute name and
-// hydration writes the evaluated URL, which is the first value the browser
-// ever sees.
 export const parkFetchableSrc = (root) => {
   const elements = root.querySelectorAll(FETCH_SRC_SELECTOR);
   for (let i = 0; i < elements.length; i++) {
@@ -28,12 +21,6 @@ export const parkFetchableSrc = (root) => {
   }
 };
 
-// Parse an `each` directive body (the text inside `<!-- ... -->`, markers
-// stripped) into its parts, or null when it isn't a valid each. The index alias
-// and the (key) expression are both optional and may be written in either order
-// — `as item, i (item.id)` and `as item (item.id), i` are equivalent. Single
-// source of truth for the grammar, used by the runtime parser and (via DOM
-// re-parse of the restored markers) by compiled pages.
 export const parseIterationHeader = (text) => {
   const match = text.match(ITERATION_REGEX);
   if (!match) return null;
@@ -47,25 +34,34 @@ export const parseIterationHeader = (text) => {
   };
 };
 
-// Resolve nested paths in state (e.g., "user.items" -> state.user.items)
-// Supports bracket notation: "teams[0].combatants" -> state.teams[0].combatants
 export const resolvePath = (obj, path) => {
   if (!path || !obj) return undefined;
-  // Split on dots and brackets: "a[0].b[1].c" → ["a", "0", "b", "1", "c"]
   const parts = path.match(/[^.\[\]]+/g);
   if (!parts) return undefined;
   return parts.reduce((acc, part) => acc?.[part], obj);
 };
 
-// Clone template element preserving structure
 export const cloneTemplate = (templateElement) => {
   return templateElement.cloneNode(true);
 };
 
-// Find matching <!-- /each --> comment with depth tracking. The index form
-// returns -1 when unmatched — parse.js probes with it to tell an authored
-// (but malformed) directive from a prose comment that merely starts with
-// "each".
+export const markBoundValues = (root, html) => {
+  if (!html.includes('@[')) return;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    if (node.nodeType === 3) {
+      if (node.textContent.includes('@[')) node._vibeBoundValue = true;
+      continue;
+    }
+    for (const attr of node.attributes) {
+      if (!attr.name.startsWith('data-vibe-') && attr.value.includes('@[')) {
+        (node._vibeBoundAttrs ??= new Set()).add(attr.name);
+      }
+    }
+  }
+};
+
 export const findEndCommentIndex = (nodes, startIndex) => {
   let depth = 1;
   for (let i = startIndex; i < nodes.length; i++) {
@@ -90,12 +86,6 @@ export const findEndComment = (nodes, startIndex) => {
   return i;
 };
 
-// Find matching <!-- /if --> and optional <!-- else --> / <!-- else if -->
-// with depth tracking. Returns { elseIndex, endIndex, elseText } — elseText
-// is the boundary comment's trimmed text ('else' or 'else if <expr>'), so
-// parse.js can desugar a chain: only the FIRST boundary at depth 1 is
-// captured; the rest of the chain lives inside the false-branch span and
-// desugars recursively into nested conditionals.
 export const findConditionalEnd = (nodes, startIndex) => {
   let depth = 1;
   let elseIndex = null;
@@ -105,11 +95,9 @@ export const findConditionalEnd = (nodes, startIndex) => {
     if (nodes[i].nodeName === '#comment') {
       const text = nodes[i].textContent.trim();
 
-      // Check for nested if
       if (CONDITIONAL_START_REGEX.test(text)) {
         depth++;
       }
-      // Check for else / else-if at current depth
       else if (
         depth === 1 &&
         elseIndex === null &&
@@ -118,7 +106,6 @@ export const findConditionalEnd = (nodes, startIndex) => {
         elseIndex = i;
         elseText = text;
       }
-      // Check for /if
       else if (text === '/if') {
         depth--;
         if (depth === 0) {
@@ -128,7 +115,6 @@ export const findConditionalEnd = (nodes, startIndex) => {
     }
   }
 
-  // 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 ? '→ ' : '  ';
@@ -141,33 +127,28 @@ export const findConditionalEnd = (nodes, startIndex) => {
   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
 export const stableHash = (obj) => {
   if (obj === null || obj === undefined) return 'null';
   if (typeof obj !== 'object') return String(obj);
 
   try {
-    // Sort keys for stable hashing
     const str = JSON.stringify(obj, Object.keys(obj).sort());
     return simpleHash(str);
   } catch (e) {
-    // Fallback for circular references
     return simpleHash(String(obj));
   }
 };
 
-// Simple hash function
 const simpleHash = (str) => {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
     const char = str.charCodeAt(i);
     hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32-bit integer
+    hash = hash & hash;
   }
   return Math.abs(hash).toString(36);
 };
 
-// Deep equality check
 export const deepEqual = (a, b) => {
   if (a === b) return true;
 
@@ -204,7 +185,6 @@ export const deepEqual = (a, b) => {
   return true;
 };
 
-// Longest Common Subsequence algorithm
 export const longestCommonSubsequence = (arr1, arr2) => {
   const m = arr1.length;
   const n = arr2.length;
@@ -212,7 +192,6 @@ export const longestCommonSubsequence = (arr1, arr2) => {
     .fill(null)
     .map(() => Array(n + 1).fill(0));
 
-  // Build LCS table
   for (let i = 1; i <= m; i++) {
     for (let j = 1; j <= n; j++) {
       if (arr1[i - 1] === arr2[j - 1]) {
@@ -223,7 +202,6 @@ export const longestCommonSubsequence = (arr1, arr2) => {
     }
   }
 
-  // Backtrack to find LCS
   const lcs = [];
   let i = m,
     j = n;
@@ -242,16 +220,6 @@ export const longestCommonSubsequence = (arr1, arr2) => {
   return lcs;
 };
 
-// The affected walk and the iteration update path both ask "which
-// [data-vibe-iter-prop] wrappers live under this row node?" for every row on
-// every flush — re-querying each time dominated flush cost on iteration-heavy
-// pages (~24k querySelectorAll calls per flush on the game's armory, nearly all
-// returning nothing). The wrapper set only changes when a mount path stamps the
-// attribute, so each stamp site bumps a global generation and the query result
-// is cached per node against it. A cache hit still prunes wrappers whose
-// subtree was torn down since (nested each/if removals keep the row node but
-// drop descendants) — additions always arrive through a stamp ⇒ a bump ⇒ a
-// fresh query.
 let iterPropGeneration = 0;
 
 export const bumpIterPropGeneration = () => {
@@ -274,52 +242,39 @@ export const iterPropWrappersOf = (node) => {
   return list;
 };
 
-// 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}`;
   }
 
-  // 2. If item is primitive, use value + index
   if (typeof item !== 'object' || item === null) {
     return `val_${item}_${index}`;
   }
 
-  // 3. For objects without id, use stable hash
   return `hash_${stableHash(item)}_${index}`;
 };
 
-// Compute diff operations between old and new arrays
 export const computeDiff = (oldKeys, newKeys, oldArray, newArray) => {
   const operations = [];
 
-  // Use LCS to find common elements
   const common = longestCommonSubsequence(oldKeys, newKeys);
 
-  // Build index maps for quick lookup
   const newKeyMap = new Map(newKeys.map((key, idx) => [key, idx]));
   const oldKeyMap = new Map(oldKeys.map((key, idx) => [key, idx]));
 
-  // Track which keys we've processed
   const processedOld = new Set();
   const processedNew = new Set();
 
-  // First pass: identify items to keep and check for updates
   common.forEach((key) => {
     const oldIdx = oldKeyMap.get(key);
     const newIdx = newKeyMap.get(key);
     processedOld.add(oldIdx);
     processedNew.add(newIdx);
 
-    // Check if item content changed
     if (!deepEqual(oldArray[oldIdx], newArray[newIdx])) {
       operations.push({
         type: 'UPDATE',
@@ -329,12 +284,8 @@ export const computeDiff = (oldKeys, newKeys, oldArray, newArray) => {
       });
     }
 
-    // Note: We don't generate MOVE for index changes here.
-    // Items in LCS maintain relative order - after REMOVEs and ADDs,
-    // they'll naturally be in correct positions.
   });
 
-  // Second pass: identify removals
   oldKeys.forEach((key, idx) => {
     if (!processedOld.has(idx)) {
       operations.push({
@@ -345,7 +296,6 @@ export const computeDiff = (oldKeys, newKeys, oldArray, newArray) => {
     }
   });
 
-  // Third pass: identify additions
   newKeys.forEach((key, idx) => {
     if (!processedNew.has(idx)) {
       operations.push({
@@ -357,17 +307,14 @@ export const computeDiff = (oldKeys, newKeys, oldArray, newArray) => {
     }
   });
 
-  // Sort operations: REMOVE first (from end), then MOVE, then ADD, then UPDATE
   return operations.sort((a, b) => {
     const priority = { REMOVE: 0, MOVE: 1, ADD: 2, UPDATE: 3 };
     if (priority[a.type] !== priority[b.type]) {
       return priority[a.type] - priority[b.type];
     }
-    // For REMOVE, process from end to beginning
     if (a.type === 'REMOVE') {
       return b.index - a.index;
     }
-    // For others, process in order
     return a.index - b.index;
   });
 };

package/runtime/loop-scope.js

@@ -1,20 +1,6 @@
-// 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];
@@ -23,8 +9,6 @@ const lastNonSpace = (s) => {
   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);
@@ -48,14 +32,6 @@ const copyString = (value, i, push) => {
   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,
-// member accesses, and object-literal keys (`{ alias: x }` keeps its key; the
-// shorthand `{ alias }` expands to `{ alias: $scope(this,'alias') }`), so only
-// identifiers that genuinely name a loop alias are touched. Bracket frames carry
-// a pending-ternary count per nesting level, which is what tells an object key's
-// `:` apart from a ternary's.
 export const rewriteHandlerAliases = (value, aliasSet) => {
   if (!aliasSet || aliasSet.size === 0 || typeof value !== 'string') return value;
 
@@ -71,8 +47,6 @@ export const rewriteHandlerAliases = (value, aliasSet) => {
   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;
@@ -91,7 +65,6 @@ export const rewriteHandlerAliases = (value, aliasSet) => {
       continue;
     }
 
-    // String literal — copy verbatim.
     if (ch === "'" || ch === '"' || ch === '`') {
       i = copyString(value, i, push);
       continue;
@@ -128,7 +101,6 @@ export const rewriteHandlerAliases = (value, aliasSet) => {
       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++;
@@ -160,10 +132,6 @@ export const rewriteHandlerAliases = (value, aliasSet) => {
   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) {
@@ -174,16 +142,6 @@ export const resolveScope = (el, name) => {
   return undefined;
 };
 
-// Re-stamp the instance scope onto conditional-branch roots mounted inside a
-// row. A `<!-- if -->` within a loop mounts its branch content separately from
-// the iteration's own clonedNodes and stamps it once, at mount time
-// (conditionals.js). When the row later updates in place — its DOM node reused
-// for a new item — the iteration refreshes its own root stamp, but the branch
-// root keeps the stale mount-time stamp, and `resolveScope` hits that first on
-// the walk up (so a handler inside the conditional resolves the previous item).
-// Walking the instance's parsed tree and re-stamping every active conditional
-// branch root with the same fresh `scope` object closes that gap. Nested loops
-// are skipped: each iteration node manages its own instances' scopes.
 const restampConditionalBranches = (tree, scope) => {
   if (!tree || typeof tree !== 'object') return;
   if (tree.type === 'iteration') return;
@@ -203,22 +161,11 @@ const restampConditionalBranches = (tree, scope) => {
   }
 };
 
-// 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];
-    // `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] : []);
@@ -226,15 +173,10 @@ export const stampInstanceScopes = (iterationNode, parentScope = {}) => {
       const node = roots[r];
       if (node && node.nodeType === 1) node.__vibeScope = scope;
     }
-    // Conditional branches inside the row carry their own stamp from mount time;
-    // refresh them with the same fresh scope so in-place row updates don't leave
-    // a handler inside an `<!-- if -->` resolving the previous item.
     if (inst.tree) restampConditionalBranches(inst.tree, 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/manifest.js

@@ -1,11 +1,3 @@
-// The manifest is the one-way dotPath→element map the runtime hangs DOM
-// bookkeeping on. Three hot paths need the REVERSE direction (element→path):
-// conditional branch mounts and the mutation observer's add/remove tracking.
-// Scanning Object.entries per lookup is O(manifest) per node — quadratic as
-// pages grow, and the dominant cost of mounting conditional-heavy pages. A
-// WeakMap rides on the manifest object (non-enumerable, like __live/__tree)
-// and is maintained by every write; lookups validate against the forward map
-// so a deleted entry can never resolve stale.
 const indexOf = (manifest) => {
   if (!manifest.__paths) {
     Object.defineProperty(manifest, '__paths', {
@@ -17,13 +9,6 @@ const indexOf = (manifest) => {
   return manifest.__paths;
 };
 
-// Single write point: forward map + reverse index together. Non-object
-// "elements" (text nodes stored as strings, null placeholders) can't be
-// WeakMap keys and are never reverse-looked-up — forward map only. An
-// element can legitimately hold MORE than one path (its own node plus an
-// inlined-slot alias, branch-graft re-registrations); the index keeps every
-// registered path shortest-first, so lookups answer with the subtree ROOT —
-// removal-time pruning must sweep the whole region, not a deeper alias.
 export const setManifestEntry = (manifest, path, element) => {
   manifest[path] = element;
   if (element !== null && typeof element === 'object') {
@@ -39,10 +24,6 @@ export const setManifestEntry = (manifest, path, element) => {
   }
 };
 
-// O(paths-per-element) reverse lookup, validated: entries whose forward
-// mapping was deleted (branch unmounts, subtree pruning) compact away; the
-// first path the forward map still agrees with — the shortest live one —
-// wins. Null when none survive.
 export const manifestPathOf = (manifest, element) => {
   if (element === null || typeof element !== 'object') return null;
   const paths = manifest.__paths?.get(element);
@@ -57,14 +38,6 @@ export const manifestPathOf = (manifest, element) => {
   return null;
 };
 
-// Removal counterpart of addToManifest (index.js): drop the root entry and
-// every entry under its dot-scope. A PREFIX SWEEP over the manifest keys, not
-// a tree walk — branch mounts register alias paths a tree walk can't reach,
-// and the sweep stays correct through any tree/manifest drift. Deleting only
-// the root entry leaked the rest: an SPA outlet swap left ~4,400
-// detached-element entries behind per navigation, pinning the DOM of every
-// page ever visited. The manifest stays bounded, so O(manifest) per removal
-// batch is cheap. An empty root path is never a legitimate removal target.
 export const removeManifestSubtree = (manifest, dotPath) => {
   if (!dotPath) return;
   delete manifest[dotPath];