@ape-egg/vibe 4.2.0 → 4.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 4.2.0** — 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 4.3.0** — 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
 
@@ -312,7 +312,7 @@ Pre-boot, state accumulates and boot is queued as always — on a fresh document
 
 ### Subtree Reconciliation (advanced)
 
-`$.reconcile(el, html)` and `$.renderComponent(rawHtml, props, slot, opts)` are public-but-advanced APIs used by the vite plugin's HMR path. Their shape may evolve; treat them as plumbing rather than application code for now.
+`$.reconcile(el, html)` is the template-aware subtree reconciliation the vite plugin's HMR path runs on: the fresh `html` is parsed by the same parser that built the page, and every paired node updates the runtime's knowledge before the DOM — a changed text or attribute template is re-hydrated in place, an iteration or conditional swaps its stored template so later renders follow it, structural inserts are hydrated under the right scope — while DOM identity, focus, selection and scroll position survive. The underscore-prefixed helpers beside it (`$._refreshComponent(el, rawHtml)`, `$._remountComponent(el)`, `$._renderComponent(...)`) are tooling plumbing, not application API; all of it may still evolve.
 
 ### Dehydrate
 

package/llms.txt

@@ -338,7 +338,7 @@ A Promise that resolves once vibe has finished initial parse + hydrate + compone
 
 ### `$.reconcile(el, html)` (advanced)
 
-Subtree reconciliation used by `@ape-egg/vite-plugin-vibe` for surgical HMR: diffs `el`'s children against fresh `html` while preserving DOM identity, focus, and selection; vibe-managed regions (iterations, conditionals, components, slot pairs) are treated as opaque. Treat as plumbing — shape may evolve. (Internal renders/registration live on underscore-prefixed `$` members and are not API.)
+Template-aware subtree reconciliation used by `@ape-egg/vite-plugin-vibe` for surgical HMR: the fresh `html` is parsed by the same parser that built the page and diffed against `el`'s children together with the runtime's own tree, so a changed text or attribute template is re-hydrated in place, an iteration or conditional swaps its stored template (later renders follow it), and DOM identity, focus, selection and scroll position survive; component wrappers re-mount only when their src or props changed. Treat as plumbing — shape may evolve. (`$._refreshComponent`, `$._remountComponent` and other underscore-prefixed `$` members are tooling internals, not API.)
 
 ## Scoped Variables in Iterations
 

package/package.json

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

package/runtime/affected.js

@@ -67,7 +67,7 @@ const nameBindingsOf = (tree) => {
   if (tree._nbSrc === tree.nameBindings && tree._nbEl === tree.element) return tree._nb;
   unsubscribeBindings(tree._nb);
   const out = [];
-  for (const nameBinding of tree.nameBindings) {
+  for (const nameBinding of tree.nameBindings ?? []) {
     BINDING_REGEX.lastIndex = 0;
     let m;
     while ((m = BINDING_REGEX.exec(nameBinding))) {
@@ -87,6 +87,61 @@ const evaluateCondition = (expression, state, element = null) =>
 export const nodeSubscriberOf = (tree, kind) =>
   (tree._sub ??= { kind, node: tree, anchor: tree.meta.startComment });
 
+export const ownBindingsOf = (tree, scope) => {
+  const out = [];
+  for (const m of textBindingsOf(tree)) {
+    out.push({
+      matchOuter: m.outer,
+      matchInner: m.inner,
+      input: m.input,
+      element: tree.element,
+      textNode: tree.textNode,
+      scopedState: scope,
+      binding: m,
+    });
+  }
+  for (const { attrName, matches } of attrBindingsOf(tree)) {
+    const attrValue = tree.attributes[attrName];
+    if (!matches.length) {
+      out.push({
+        type: "attribute",
+        attrName,
+        attrValue,
+        matchOuter: null,
+        matchInner: null,
+        element: tree.element,
+        scopedState: scope,
+        binding: null,
+      });
+      continue;
+    }
+    for (const m of matches) {
+      out.push({
+        type: "attribute",
+        attrName,
+        attrValue,
+        matchOuter: m.outer,
+        matchInner: m.inner,
+        element: tree.element,
+        scopedState: scope,
+        binding: m,
+      });
+    }
+  }
+  for (const m of nameBindingsOf(tree)) {
+    out.push({
+      type: "nameBinding",
+      nameBinding: m.nameBinding,
+      matchOuter: m.outer,
+      matchInner: m.inner,
+      element: tree.element,
+      scopedState: scope,
+      binding: m,
+    });
+  }
+  return out;
+};
+
 const isIdentChar = (c) =>
   (c >= "a" && c <= "z") ||
   (c >= "A" && c <= "Z") ||

package/runtime/conditionals.js

@@ -262,6 +262,18 @@ export const dispatchConditional = (node, newState, manifest, parentScope = {})
   }
 };
 
+export const remountBranch = (node, state, manifest, parentScope = {}) => {
+  if (!node.runtime.templateRemoved) return;
+  const sub = nodeSubscriberOf(node, 'conditional');
+  sub.lastScope = state;
+  beginTracking(sub, overlayKeysOf(state));
+  const result = evaluateCondition(node.meta.expression, state, node.meta.startComment?.parentElement);
+  endTracking();
+  const branch = result ? node.meta.branches.if : node.meta.branches.else;
+  mountBranch(node, branch, state, manifest, parentScope);
+  node.runtime.activeBranch = branch;
+};
+
 export const updateConditional = (node, newState, oldState, manifest, parentScope = {}) => {
   const { expression, branches, startComment } = node.meta;
 

package/runtime/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = '4.2.0';
+export const VERSION = '4.3.0';
 
 export const DEBUGGER_NAME = '[vibe-debug]:';
 export const FOUC_CLASS_OR_ATTR = 'vibe-fouc';

package/runtime/index.js

@@ -1,6 +1,12 @@
 import state, { silentSet } from './state.js';
 import parse from './parse.js';
-import createManifest, { setManifestEntry, manifestPathOf, removeManifestSubtree } from './manifest.js';
+import createManifest, {
+  setManifestEntry,
+  manifestPathOf,
+  removeManifestSubtree,
+  findNodeByElement,
+  addToManifest,
+} from './manifest.js';
 import hydrate from './hydrate.js';
 import affected from './affected.js';
 import { deepMerge, hash, setRootState } from './utils.js';
@@ -25,13 +31,13 @@ import {
   STAGED_ATTR,
   FOUC_CLASS_OR_ATTR,
 } from './constants.js';
-import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate, executeCompiledComponentScripts } from './component.js';
+import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate, executeCompiledComponentScripts, forceRemount } from './component.js';
 import { configureComponentCache, clearComponentCache } from './component-cache.js';
 import { debugLog } from './debug.js';
 import { pruneDisconnected, beginFlush } from './tracking.js';
 import dispatchFlush from './dispatch.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
-import { reconcile } from './reconcile.js';
+import { reconcile, refreshComponent } from './reconcile.js';
 import {
   buildHyperspeedManifest,
   hyperspeedManifest,
@@ -66,38 +72,6 @@ const navigateTree = (tree, path) => {
   return path.split('.').filter(k => k).reduce((node, key) => node?.children?.[key], tree);
 };
 
-const findNodeByElement = (tree, target) => {
-  if (!target) return null;
-  const seen = new Set();
-  const walk = (node) => {
-    if (!node || typeof node !== 'object' || seen.has(node)) return null;
-    seen.add(node);
-    if (node.element === target) return node;
-    if (node.children) {
-      for (const key in node.children) {
-        const hit = walk(node.children[key]);
-        if (hit) return hit;
-      }
-    }
-    const branchTree = node.runtime?.activeInstance?.parsedTree;
-    if (branchTree) {
-      const hit = walk(branchTree);
-      if (hit) return hit;
-    }
-    const instances = node.runtime?.instances;
-    if (instances) {
-      for (let i = 0; i < instances.length; i++) {
-        if (instances[i]?.tree) {
-          const hit = walk(instances[i].tree);
-          if (hit) return hit;
-        }
-      }
-    }
-    return null;
-  };
-  return walk(tree);
-};
-
 const ensureNode = (tree, path) => {
   const keys = path.split('.').filter(k => k);
   return keys.reduce((node, key) => {
@@ -108,16 +82,6 @@ const ensureNode = (tree, path) => {
   }, tree);
 };
 
-const addToManifest = (tree, manifest, dotPath) => {
-  setManifestEntry(manifest, dotPath, tree.element);
-
-  if (tree.children && Object.keys(tree.children).length > 0) {
-    Object.keys(tree.children).forEach((childKey) => {
-      addToManifest(tree.children[childKey], manifest, `${dotPath}.${childKey}`);
-    });
-  }
-};
-
 const processCoreLoop = (node, parsedNode, state, manifest, isNewNode, debug) => {
   let hydratedCount = 0;
   let iteratedCount = 0;
@@ -593,7 +557,17 @@ const main = (s, config = {}, stringSelector = '') => {
   });
 
   Object.defineProperty($, 'reconcile', {
-    value: reconcile,
+    value: (target, source) => reconcile(target, source, manifest),
+    enumerable: false,
+  });
+
+  Object.defineProperty($, '_refreshComponent', {
+    value: (el, rawHtml) => refreshComponent(el, rawHtml, manifest),
+    enumerable: false,
+  });
+
+  Object.defineProperty($, '_remountComponent', {
+    value: (el) => forceRemount(el, debug),
     enumerable: false,
   });
 
@@ -779,6 +753,7 @@ const main = (s, config = {}, stringSelector = '') => {
         const dotAnnotation = manifestPathOf(manifest, target);
 
         const parsedNode = parse(node);
+        node._vibeTree = parsedNode;
 
         if (parsedNode.stats?.skipped) {
           totalSkipped += parsedNode.stats.skipped;

package/runtime/iterate.js

@@ -23,6 +23,8 @@ import {
   ITER_PROP_PATH,
   COMPONENT_ID_ATTR,
   COMPONENT_SRC_SELECTOR,
+  DEFER_ATTR_PREFIX,
+  INTERNAL_ATTR_PREFIX,
 } from './constants.js';
 
 import * as compiled from './pre-compiled-iterations.js';
@@ -71,6 +73,14 @@ const BATCH_ATTR_BINDING_REGEX = new RegExp(
   String.raw`(\s)([\w-]+)="@\[(${BATCH_BINDING_INNER})\]"`,
   'g',
 );
+const DEFERRED_ATTR_REGEX = new RegExp(
+  String.raw`(\s)${DEFER_ATTR_PREFIX}(?!${INTERNAL_ATTR_PREFIX.slice(DEFER_ATTR_PREFIX.length)})(?=[\w-])`,
+  'g',
+);
+const realAttrName = (name) =>
+  name.startsWith(DEFER_ATTR_PREFIX) && !name.startsWith(INTERNAL_ATTR_PREFIX)
+    ? name.slice(DEFER_ATTR_PREFIX.length)
+    : name;
 
 const mapTagSpans = (html, fn) => {
   let out = '';
@@ -131,13 +141,14 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
     const attrs = [...el.attributes];
     for (let a = 0; a < attrs.length; a++) {
       const attr = attrs[a];
-      if (!DOM_PROPERTIES.includes(attr.name)) continue;
+      const prop = realAttrName(attr.name);
+      if (!DOM_PROPERTIES.includes(prop)) continue;
       const m = attr.value.match(PURE_BINDING_REGEX);
       if (!m) continue;
       let expr = m[1];
       if (componentId) expr = expr.replace(THIS_PROP_REGEX, `$['${componentId}'].$1`);
       indexes.push(domPropertyWrites.length);
-      domPropertyWrites.push({ prop: attr.name, expr });
+      domPropertyWrites.push({ prop, expr });
     }
     if (indexes.length > 0) {
       el.setAttribute(BATCH_ATTR, indexes.join(','));
@@ -172,7 +183,7 @@ export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys, ancho
   let code = escaped;
 
   let needsCiWalker = false;
-  code = mapTagSpans(code, (tag) => tag.replace(BATCH_NAME_BINDING_REGEX, (_, _ws, expr) => {
+  code = mapTagSpans(code, (tag) => tag.replace(DEFERRED_ATTR_REGEX, '$1').replace(BATCH_NAME_BINDING_REGEX, (_, _ws, expr) => {
     let decExpr = decodeEntities(expr);
     if (decExpr.includes('[') || decExpr.includes('(')) {
       return nameBindingEmit(decExpr);
@@ -679,6 +690,16 @@ const isolateInlinedComponentIds = (container) => {
   return true;
 };
 
+export const prepareTemplateComponents = (container, scopedState) => {
+  const components = container.querySelectorAll(COMPONENT_SRC_SELECTOR);
+  const scopeKeys = overlayKeysOf(scopedState);
+  for (let i = 0; i < components.length; i++) {
+    const el = components[i];
+    if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
+    if (scopeKeys) resolveScopedSrc(el, scopedState, scopeKeys);
+  }
+};
+
 export const initializeBlock = (templateNodes, scopedState, cachedTree = null, componentId = null, aliasSet = undefined, isolateComponents = false) => {
   let tree;
   let clonedNodes = [];
@@ -697,13 +718,7 @@ export const initializeBlock = (templateNodes, scopedState, cachedTree = null, c
     }
   }
 
-  const components = parseContainer.querySelectorAll(COMPONENT_SRC_SELECTOR);
-  const scopeKeys = overlayKeysOf(scopedState);
-  for (let i = 0; i < components.length; i++) {
-    const el = components[i];
-    if (el._vibeSlotContent === undefined) el._vibeSlotContent = el.innerHTML;
-    if (scopeKeys) resolveScopedSrc(el, scopedState, scopeKeys);
-  }
+  prepareTemplateComponents(parseContainer, scopedState);
 
   if (isolateComponents && isolateInlinedComponentIds(parseContainer)) {
     executeCompiledComponentScriptsIn([...parseContainer.childNodes]);
@@ -1016,6 +1031,71 @@ export const updateIteration = (iterationNode, newState, oldState, manifest, par
   stampScopes(iterationNode, manifest, parentScope);
 };
 
+export const swapIterationTemplate = (iterationNode, meta) => {
+  const { arrayPath, itemAlias, indexAlias, keyExpr, hasScopedHandlers, scopeAliases, template } = meta;
+  Object.assign(iterationNode.meta, { arrayPath, itemAlias, indexAlias, keyExpr, hasScopedHandlers, scopeAliases, template });
+  delete iterationNode.compiled;
+  const rt = iterationNode.runtime;
+  rt.batchFn = null;
+  rt.lastBatchHtml = undefined;
+  rt.domPropertyWrites = null;
+  rt.stateKeys = null;
+};
+
+export const rerenderIteration = (iterationNode, state, manifest, parentScope = {}) => {
+  if (!iterationNode.runtime.templateRemoved) return;
+  const { arrayPath, startComment } = iterationNode.meta;
+  const resolvedExpr = resolveThisPath(arrayPath, startComment.parentElement);
+  const trackSub = nodeSubscriberOf(iterationNode, 'iteration');
+  trackSub.lastScope = state;
+  beginTracking(trackSub, overlayKeysOf(state));
+  const array = evalInScope(resolvedExpr, state, startComment.parentElement) ?? resolvePath(state, resolvedExpr);
+  endTracking();
+  bulkReplace(iterationNode, Array.isArray(array) ? array : [], state, manifest, parentScope);
+};
+
+export const instanceRange = (iterationNode, index) => {
+  const parent = iterationNode.meta.startComment.parentNode;
+  const start = findInstanceAnchor(iterationNode.runtime.instances[index], parent);
+  const anchor = resolveInsertBefore(iterationNode, index + 1, parent);
+  const nodes = [];
+  for (let cur = start; cur && cur !== anchor; cur = cur.nextSibling) nodes.push(cur);
+  return { nodes, anchor };
+};
+
+export const patchTreelessInstances = (iterationNode, state, manifest, parentScope, patchRow) => {
+  const { itemAlias, indexAlias, template, startComment } = iterationNode.meta;
+  const rt = iterationNode.runtime;
+  const array = rt.instances.map((inst) => inst.item);
+
+  if (!canUseBatchRender(template)) {
+    bulkReplace(iterationNode, array, state, manifest, parentScope);
+    return;
+  }
+
+  const stateKeys = Object.keys(state);
+  const compiledBatch = compileBatchFn(template, itemAlias, indexAlias, stateKeys, startComment.parentNode);
+  rt.batchFn = compiledBatch.fn;
+  rt.domPropertyWrites = compiledBatch.domPropertyWrites;
+  rt.stateKeys = stateKeys;
+  const html = rt.batchFn(array, ...stateKeys.map((k) => state[k]), state);
+  rt.lastBatchHtml = html;
+
+  batchParseTemplate.innerHTML = html;
+  const frag = batchParseTemplate.content;
+  markBoundValues(frag, html);
+  const fresh = [...frag.children];
+  if (fresh.length !== rt.instances.length) {
+    bulkReplace(iterationNode, array, state, manifest, parentScope);
+    return;
+  }
+
+  const freshInstances = fresh.map((element, i) => ({ element, item: array[i], index: i }));
+  applyDomPropertyWrites(freshInstances, array, state, itemAlias, indexAlias, rt.domPropertyWrites);
+  for (let i = 0; i < fresh.length; i++) patchRow(rt.instances[i].element, fresh[i]);
+  stampScopes(iterationNode, manifest, parentScope);
+};
+
 const releaseRemovedSubtrees = (removedRoots, manifest) => {
   if (!manifest || removedRoots.length === 0) return;
   const tree = manifest.__tree;

package/runtime/manifest.js

@@ -47,6 +47,48 @@ export const removeManifestSubtree = (manifest, dotPath) => {
   }
 };
 
+export const findNodeByElement = (tree, target) => {
+  if (!target) return null;
+  const seen = new Set();
+  const walk = (node) => {
+    if (!node || typeof node !== 'object' || seen.has(node)) return null;
+    seen.add(node);
+    if (node.element === target) return node;
+    if (node.children) {
+      for (const key in node.children) {
+        const hit = walk(node.children[key]);
+        if (hit) return hit;
+      }
+    }
+    const branchTree = node.runtime?.activeInstance?.parsedTree;
+    if (branchTree) {
+      const hit = walk(branchTree);
+      if (hit) return hit;
+    }
+    const instances = node.runtime?.instances;
+    if (instances) {
+      for (let i = 0; i < instances.length; i++) {
+        if (instances[i]?.tree) {
+          const hit = walk(instances[i].tree);
+          if (hit) return hit;
+        }
+      }
+    }
+    return null;
+  };
+  return walk(tree);
+};
+
+export const addToManifest = (tree, manifest, dotPath) => {
+  setManifestEntry(manifest, dotPath, tree.element);
+
+  if (tree.children && Object.keys(tree.children).length > 0) {
+    Object.keys(tree.children).forEach((childKey) => {
+      addToManifest(tree.children[childKey], manifest, `${dotPath}.${childKey}`);
+    });
+  }
+};
+
 const recursive = (tree, results, tagChain) => {
   setManifestEntry(results, tagChain.join('.'), tree.element);
 

package/runtime/parse.js

@@ -26,6 +26,19 @@ import './this-scope.js';
 
 const findComponentIdForElement = (element) => closestComponentId(element);
 
+export const rewriteHandler = (value, element, aliasSet) => {
+  let v = value;
+  if (v.includes('this.')) {
+    const componentId = findComponentIdForElement(element);
+    if (componentId) {
+      v = v.replace(STATE_THIS_PROP_REGEX, (_, prop) => `$['${componentId}'].${prop}`);
+      v = v.replace(THIS_PROP_REGEX, (_, prop) => `$this(this).${prop}`);
+    }
+  }
+  if (aliasSet && aliasSet.size > 0) v = rewriteHandlerAliases(v, aliasSet);
+  return v;
+};
+
 const warnedStaticKeys = new Set();
 const warnStaticKey = (key) => {
   if (warnedStaticKeys.has(key)) return;
@@ -97,17 +110,7 @@ const captureAttributeBindings = (element, aliasSet) => {
     }
 
     if (attr.name.startsWith('on')) {
-      let v = attr.value;
-      if (v.includes('this.')) {
-        const componentId = findComponentIdForElement(element);
-        if (componentId) {
-          v = v.replace(STATE_THIS_PROP_REGEX, (_, prop) => `$['${componentId}'].${prop}`);
-          v = v.replace(THIS_PROP_REGEX, (_, prop) => `$this(this).${prop}`);
-        }
-      }
-      if (aliasSet && aliasSet.size > 0) {
-        v = rewriteHandlerAliases(v, aliasSet);
-      }
+      const v = rewriteHandler(attr.value, element, aliasSet);
       if (v !== attr.value) element.setAttribute(attr.name, v);
     }