@ape-egg/vibe 4.2.1 → 4.3.1

package/README.md

@@ -1,6 +1,6 @@
 # Vibe
 
-**Version 4.2.1** — 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.1** — 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
 
@@ -291,7 +291,7 @@ A standalone client-side router built on one contract: `$.page = { path, route,
 
 **Keyed outlet**: `key` on a fetched `<component>` declares its identity — when the resolved key changes, the component remounts even if `src` is unchanged. With `key="@[page.path]"`, param→param navigation on the same route (`/brawlers/0 → /brawlers/1` — same fragment src) mounts fresh, exactly like an MPA reload on the new URL. `src` and `key` are the wrapper's own contract and are never passed to the component as props.
 
-**Link claiming**: one document-level click listener claims same-origin, unmodified, untargeted clicks whose pathname matches a **real** route — pushState + a fresh `$.page` assignment + `document.title` swap when the route carries one, scroll to top. Everything else navigates natively: other origins, modified clicks, `target`/`download` links, same-page hash anchors, and unrouted paths — which is what makes mixed MPA/SPA output work. `'*'` never claims a click; it only resolves deep-link entries and popstate. `popstate` re-resolves (including `'*'`) without scrolling — the browser restores position.
+**Link claiming**: one document-level click listener claims same-origin, unmodified, untargeted clicks whose pathname matches a **real** route — pushState + a fresh `$.page` assignment + `document.title` swap when the route carries one, scroll to top. The entry route gets the same title swap when `setupSpa` runs, so a deep link never shows the shell's title. Everything else navigates natively: other origins, modified clicks, `target`/`download` links, same-page hash anchors, and unrouted paths — which is what makes mixed MPA/SPA output work. `'*'` never claims a click; it only resolves deep-link entries and popstate. `popstate` re-resolves (including `'*'`) without scrolling — the browser restores position.
 
 **No match, no `'*'`**: `$.page.src` stays unset and the outlet mounts nothing. There is no built-in 404.
 
@@ -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
 
@@ -525,7 +525,7 @@ The pages tree becomes three things:
 
 1. **Page fragments** at `/components/vibe-spa/<pages-relative-path>` — each page's body content, with its head `<style>` tags prepended and its `<script type="module">` carried along byte-identical. No rewrites: `vibe()` itself applies defaults semantics once booted (see App-Lifetime State Defaults above), so page state gets app-lifetime behavior with the page's own import.
 2. **A generated route table** — `pages/brawlers/$index.html` → `{ route: '/brawlers/:index', src: '/components/vibe-spa/brawlers/$index.html', title: <harvested from the page's <title>> }`. `$param` → `:param`, terminal `$$name` → `:name*`, terminal `index` serves its directory path. Sorted most-specific-first.
-3. **A composed shell** at the output root `/index.html` — plain runtime-Vibe code: the deduped union of every page's head resources (`<meta>` keeps only the set common to all pages; page-specific meta is dropped with a verbose note), the `/` route's title, the union of page body attributes minus `vibe-fouc`, one generated boot script (`resolve` seeds `$.page`, `setupSpa` wires navigation — imports reuse the pages' own import style), and the keyed route outlet: `<component src="@[page.src]" key="@[page.path]"></component>` (a path change remounts the fragment even when the route — and so the src — is unchanged: param→param navigation mounts fresh, like the MPA reload it replaces).
+3. **A composed shell** at the output root `/index.html` — plain runtime-Vibe code: the deduped union of every page's head resources (`<meta>` keeps only the set common to all pages; page-specific meta is dropped with a verbose note), the `/` route's title, the union of page body attributes minus `vibe-fouc`, a `window.__MANIFEST__` hint naming the shell's own hyperspeed manifest (the shell is the document at every route, so the runtime loads that one manifest directly instead of probing paths derived from the URL), one generated boot script (`resolve` seeds `$.page`, `setupSpa` wires navigation — imports reuse the pages' own import style), and the keyed route outlet: `<component src="@[page.src]" key="@[page.path]"></component>` (a path change remounts the fragment even when the route — and so the src — is unchanged: param→param navigation mounts fresh, like the MPA reload it replaces).
 
 **What SPA mode skips**: per-page stamped HTML, per-page manifests, and the `pages/` output directory. Fragments are runtime-parsed on mount (per-route lazy loading falls out of the reactive src for free); the shell itself gets a manifest but is deliberately left unstamped — it is served at every route path, so its first paint is location-dependent by nature. The shell ships **without** `vibe-fouc`: its absence is the compiled-mode marker (it gates hyperspeed manifest loading), and there is nothing to flash — the outlet is empty and fragments hydrate off-DOM before insertion.
 
@@ -539,7 +539,7 @@ The pages tree becomes three things:
 }
 ```
 
-Dev-server equivalents: any "history API fallback" option (`http-server` can't rewrite; `vite preview`, `serve -s`, and Caddy `try_files` all can).
+Dev-server equivalents: any "history API fallback" option (`vite preview`, `serve -s`, Caddy `try_files`, or `http-server -P http://localhost:8080?` — the trailing `?` proxies unresolved paths to the root).
 
 **Watch mode**: `--spa --watch` re-runs the SPA pass on any pages-tree change — edited pages re-transform, added/removed pages resync the route table and prune orphan fragments, title/head edits recompose the shell, and the shell's manifest refreshes.
 

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.1",
+  "version": "4.3.1",
   "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.1';
+export const VERSION = '4.3.1';
 
 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

@@ -690,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 = [];
@@ -708,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]);
@@ -1027,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);
     }