@ape-egg/vibe 2.1.18 → 2.1.20

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [2.1.20] - 2026-06-25
+
+### Added
+
+- **`@ape-egg/vibe/hot-module-refresh` — transport-agnostic browser HMR client** (`hot-module-refresh.js` (new), exported from `package.json`) — the surgical-HMR "brain" that reconciles a code edit into the live DOM instead of reloading the page is extracted out of `vite-plugin-vibe` into a standalone flat module the vibe package now exports. It's a *soft dependency*: nothing in the runtime imports it and it imports nothing from the runtime, depending only on the public `window.$` surface (`reconcile` / `renderComponent` / `clearComponentCache`), so a plain static server can serve it as-is — no bundler, no Vite. A transport adapter wires its channel to the brain through a single seam, `setupHotModuleRefresh({ debug, subscribe })`, where `subscribe` delivers two callbacks: `componentUpdate(path)` — re-fetch a changed component template and, for each live instance, reconcile surgically when its scripts are unchanged or re-mount otherwise (runtime mode only, since compiled output inlines components into pages) — and `pageUpdate(payload)` — re-fetch the current page and reconcile the `[vibe]` root (mode-agnostic; raw and compiled pages reconcile the same way). This lets the Vite plugin and any other dev transport share one HMR implementation. Tests: `e2e-runtime/hot-module-refresh.html`, `tests/e2e/hot-module-refresh.spec.js`.
+
+## [2.1.19] - 2026-06-25
+
+### Fixed
+
+- **`<!-- each list as item, i (item.id) -->` (index alias before the key) silently failed to iterate** (`runtime/constants.js`, `runtime/iteration-utils.js`, `runtime/parse.js`, `compiler/src/compiler/manifest_builder.rs`) — the iteration header grammar only accepted the key before the index (`as item (item.id), i`). When the index came first, the trailing `(item.id)` made `ITERATION_REGEX` fail to match, so `parse.js` skipped the comment entirely and the body rendered once with an undefined alias instead of iterating. `ITERATION_REGEX` now accepts the `(key)` expression in either position (a second optional key group), and a new `parseIterationHeader` helper coalesces the two and is the single source of truth used by `parse.js`. Compiled pages re-parse the preserved each comment through the same helper, so they were fixed by the runtime change; additionally the Rust `manifest_builder` (compiler 2.0.0 → 2.0.1) now strips the key before the item/index split so the emitted manifest carries a clean `indexAlias` (was `"i (item.id)"`) for both orderings. Tests: `tests/unit/iteration-utils.test.js` (parseIterationHeader), `tests/compiler/iterations-index-key/`, `e2e-runtime/iteration-index-key.html` + `tests/e2e/iteration-index-key.spec.js` (runtime + compiled).
+
 ## [2.1.18] - 2026-06-22
 
 ### Fixed

package/compiler/src/Cargo.lock

@@ -1599,7 +1599,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "vibe-compiler"
-version = "2.0.0"
+version = "2.0.1"
 dependencies = [
  "clap",
  "colored",

package/compiler/src/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vibe-compiler"
-version = "2.0.0"
+version = "2.0.1"
 edition = "2021"
 description = "Vibe framework compiler - compiles Vibe source files into optimized output"
 authors = ["Kim Korte"]

package/compiler/src/compiler/manifest_builder.rs

@@ -202,16 +202,26 @@ impl ManifestBuilder {
                     // Extract expression: "each items as item" -> "items as item"
                     let expression = trimmed.strip_prefix("each ").unwrap_or("").to_string();
 
-                    // Parse expression to extract parts: "items as item, index" or "items as item"
+                    // Parse expression to extract parts: "items as item, index" or "items as item".
+                    // The optional (key) expression may sit before or after the index — strip it
+                    // first so the item/index split isn't polluted by it. The key itself isn't
+                    // stored here; the runtime re-derives it from the preserved comment.
                     let parts: Vec<&str> = expression.split(" as ").collect();
                     let array_path = parts.get(0).unwrap_or(&"").trim().to_string();
                     let alias_part = parts.get(1).unwrap_or(&"").trim();
-                    let (item_alias, index_alias) = if let Some(comma_pos) = alias_part.find(',') {
-                        let item = alias_part[..comma_pos].trim().to_string();
-                        let index = alias_part[comma_pos + 1..].trim().to_string();
+                    let alias_without_key = match (alias_part.find('('), alias_part.rfind(')')) {
+                        (Some(open), Some(close)) if close > open => {
+                            format!("{}{}", &alias_part[..open], &alias_part[close + 1..])
+                        }
+                        _ => alias_part.to_string(),
+                    };
+                    let alias_without_key = alias_without_key.trim();
+                    let (item_alias, index_alias) = if let Some(comma_pos) = alias_without_key.find(',') {
+                        let item = alias_without_key[..comma_pos].trim().to_string();
+                        let index = alias_without_key[comma_pos + 1..].trim().to_string();
                         (item, index)
                     } else {
-                        (alias_part.to_string(), "index".to_string())
+                        (alias_without_key.to_string(), "index".to_string())
                     };
 
                     // Find node index in siblings

package/hot-module-refresh.js

@@ -0,0 +1,384 @@
+// @ape-egg/vibe/hot-module-refresh
+//
+// Transport-agnostic browser HMR client — the "brain" that reconciles a code
+// edit into the live DOM instead of reloading the page. Extracted out of
+// vite-plugin-vibe so both dev modes share one implementation.
+//
+// SOFT DEPENDENCY: nothing in Vibe's runtime imports this, it imports nothing
+// from Vibe, and deleting it leaves a working framework. It depends solely on
+// the runtime global `window.$` (reconcile / renderComponent /
+// clearComponentCache), so it ships as a flat module a plain static server can
+// serve as-is — no bundler, no Vite.
+//
+// A transport adapter wires its channel to the brain through one seam:
+//
+//   setupHotModuleRefresh({ debug, subscribe })
+//   subscribe({ componentUpdate, pageUpdate })
+//
+//   • componentUpdate(path)  — a component template changed. Fetch the raw
+//       template; for every live instance, reconcile surgically when scripts
+//       are unchanged, else re-mount. Runtime-mode only — compiled output
+//       inlines components into pages, so its adapter never calls this.
+//   • pageUpdate(payload)    — the current page changed. Fetch it and reconcile
+//       the [vibe] root. Mode-agnostic: a raw page (runtime) and a compiled
+//       page (compiled) reconcile the same way.
+
+export const setupHotModuleRefresh = ({ debug = false, subscribe }) => {
+  const dbg = {
+    info: (...a) => { if (debug) console.info(...a); },
+    group: (...a) => { if (debug) console.group(...a); },
+    groupEnd: () => { if (debug) console.groupEnd(); },
+  };
+
+  // Track which live <component> wrappers correspond to which source file.
+  // Vibe's component.js replaces <component src='X'> with a fresh <component>
+  // (no src). The spy below tags the new wrapper with _vibeSrc + the slot
+  // content, so on a component-update we can find every live instance and
+  // hand the slot back to Vibe verbatim during re-mount.
+  const liveBySrc = new Map();
+
+  const isComponentSrc = (n) =>
+    n?.nodeType === 1 && n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+  const isProcessedComponent = (n) =>
+    n?.nodeType === 1 && !n.hasAttribute?.('src') &&
+    (n.nodeName === 'COMPONENT' || (n.nodeName === 'DIV' && n.classList?.contains?.('component')));
+
+  // Snapshot slot innerHTML on a <component src> BEFORE vibe strips iteration/
+  // conditional templates from its subtree. vibe's renderAllIterations removes
+  // nodes between <!-- each -->/<!-- /each --> comments synchronously after
+  // hydrate; if we wait until the component is swapped out (spy's removedNodes
+  // path) and read innerHTML then, the templates are gone and HMR re-mounts
+  // receive an empty slot. setup runs before the page's boot script calls into
+  // vibe — the initial pass captures everything present at parse time.
+  const captureSlot = (el) => {
+    if (el._vibePluginSlot === undefined) el._vibePluginSlot = el.innerHTML;
+  };
+  document.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+
+  // Mirrors vibe/runtime/cleanup.js#shouldCleanup: a subtree is 'done' once
+  // no <component[src]> remains pending and no literal @[...] sits in a
+  // text node. Used to release vibe-fouc once Vibe finishes processing the
+  // re-mounted component subtree.
+  const waitForVibeReady = (target, timeout = 2000) => new Promise((done) => {
+    const deadline = performance.now() + timeout;
+    const tick = () => {
+      if (!target.isConnected) return done();
+      if (!target.querySelector('component[src], div.component[src]')) {
+        const walker = document.createTreeWalker(target, NodeFilter.SHOW_TEXT);
+        let pending = false;
+        let n;
+        while ((n = walker.nextNode())) {
+          if (/@\[.+?\]/.test(n.textContent)) { pending = true; break; }
+        }
+        if (!pending) return done();
+      }
+      if (performance.now() > deadline) return done();
+      requestAnimationFrame(tick);
+    };
+    requestAnimationFrame(tick);
+  });
+
+  new MutationObserver((mutations) => {
+    // First pass: capture slot content on any <component src> that gets
+    // added dynamically (conditional/iteration branches mounting nested
+    // components). Must happen before the removal/addition logic runs, so
+    // that if a subsequent mutation re-mounts or strips this element, the
+    // snapshot is already in place.
+    for (const { addedNodes } of mutations) {
+      for (const n of addedNodes) {
+        if (isComponentSrc(n)) captureSlot(n);
+        if (n?.nodeType === 1 && n.querySelectorAll) {
+          n.querySelectorAll('component[src], div.component[src]').forEach(captureSlot);
+        }
+      }
+    }
+    for (const { addedNodes, removedNodes } of mutations) {
+      let src = null;
+      let slotContent = '';
+      let hadFouc = false;
+      let props = null;
+      let scriptHash;
+      for (const n of removedNodes) {
+        if (isComponentSrc(n)) {
+          src = n.getAttribute('src');
+          // vibe's component.js deletes _vibeSlotContent synchronously after
+          // reading it, so on re-mount transitions the prop is already gone
+          // by the time we see the removal. _vibePluginSlot is our own
+          // mirror that vibe never touches — read it preferentially, fall
+          // back to vibe's prop (initial page load), then innerHTML (also
+          // initial, when source was authored inline).
+          slotContent = (
+            n._vibePluginSlot !== undefined ? n._vibePluginSlot :
+            n._vibeSlotContent !== undefined ? n._vibeSlotContent :
+            n.innerHTML
+          ).trim();
+          hadFouc = n.hasAttribute('vibe-fouc');
+          // Script hash is set by remount() on the <component src> before it
+          // hits the DOM, OR carried from a previous wrapper via this same
+          // forward path. Either way, stash it so the processed wrapper can
+          // use it as baseline for future surgical reconciles.
+          scriptHash = n._vibeScriptHash;
+          // Capture all authored attrs so reconcile can detect prop changes
+          // on the callsite and re-mount when they differ. vibe-fouc is a
+          // transient HMR marker — in either attribute or class form — and
+          // must never end up in the authored set or every FOUC flip would
+          // falsely look like a prop change.
+          props = {};
+          for (const a of n.attributes) {
+            if (a.name === 'vibe-fouc') continue;
+            if (a.name === 'class') {
+              const kept = a.value.split(/\s+/).filter((t) => t && t !== 'vibe-fouc');
+              if (kept.length) props.class = kept.join(' ');
+              continue;
+            }
+            props[a.name] = a.value;
+          }
+          break;
+        }
+      }
+      if (!src) continue;
+      for (const n of addedNodes) {
+        if (isProcessedComponent(n)) {
+          n._vibeSrc = src;
+          n._vibeSlotContent = slotContent;
+          // Brain-owned mirror so we can recover slot content after vibe's
+          // processSingle deletes _vibeSlotContent on the next re-mount.
+          n._vibePluginSlot = slotContent;
+          n._vibeProps = props;
+          if (scriptHash !== undefined) n._vibeScriptHash = scriptHash;
+          if (!liveBySrc.has(src)) liveBySrc.set(src, new Set());
+          liveBySrc.get(src).add(n);
+          if (hadFouc) {
+            n.setAttribute('vibe-fouc', '');
+            waitForVibeReady(n).then(() => n.removeAttribute('vibe-fouc'));
+          }
+          break;
+        }
+      }
+    }
+  }).observe(document.body, { childList: true, subtree: true });
+
+  // Cheap string hash (djb2). Used to detect <script type="module"> changes
+  // between HMR fetches — unchanged scripts mean registered component state
+  // is still valid, so we can reconcile in place instead of re-mounting.
+  const hashString = (s) => {
+    let h = 5381;
+    for (let i = 0; i < s.length; i++) h = (((h << 5) + h) + s.charCodeAt(i)) | 0;
+    return h;
+  };
+  const hashScripts = (rawHtml) => {
+    const temp = document.createElement('div');
+    temp.innerHTML = rawHtml;
+    const scripts = temp.querySelectorAll('script[type="module"]');
+    return hashString([...scripts].map((s) => s.textContent || '').join(''));
+  };
+
+  // Return the baseline script hash for a live wrapper. On initial mount,
+  // vibe's component.js stashes the raw fetched HTML on the wrapper as
+  // _vibeRawSource. We hash it lazily on first HMR check and cache the
+  // result. This makes the very first save after page load surgical
+  // (assuming the script body hasn't changed) rather than always falling
+  // back to re-mount.
+  const getBaselineScriptHash = (el) => {
+    if (el._vibeScriptHash !== undefined) return el._vibeScriptHash;
+    if (el._vibeRawSource) {
+      el._vibeScriptHash = hashScripts(el._vibeRawSource);
+      return el._vibeScriptHash;
+    }
+    return undefined;
+  };
+
+  // Collect data-vibe-component-id values from the live wrapper's subtree in
+  // DOM order. Script processing inside the component assigns ids in script
+  // order → DOM order (each script's sibling group follows it), so reusing
+  // ids in DOM order keeps state bindings aligned across HMR renders.
+  const collectIdsInOrder = (el) => {
+    const ids = [];
+    const seen = new Set();
+    el.querySelectorAll('[data-vibe-component-id]').forEach((node) => {
+      const id = node.getAttribute('data-vibe-component-id');
+      if (id && !seen.has(id)) { seen.add(id); ids.push(id); }
+    });
+    return ids;
+  };
+
+  // True when an element lives inside a vibe iteration region (between
+  // <!-- each ... --> and <!-- /each -->). Iterations materialize the
+  // template N times with pre-resolved props; iterate.js caches the template
+  // at mount time, so surgical changes to one instance would be clobbered on
+  // the next array mutation. Fall back to re-mount in that case.
+  const isInsideIteration = (el) => {
+    let cur = el;
+    while (cur && cur.parentNode) {
+      let depth = 0;
+      let sib = cur.previousSibling;
+      while (sib) {
+        if (sib.nodeType === 8) {
+          const t = sib.textContent.trim();
+          if (t === '/each') depth++;
+          else if (t.startsWith('each ')) {
+            if (depth === 0) return true;
+            depth--;
+          }
+        }
+        sib = sib.previousSibling;
+      }
+      cur = cur.parentNode;
+      if (!cur || cur === document.body) return false;
+    }
+    return false;
+  };
+
+  // Re-mount a single live instance by swapping its wrapper for a fresh
+  // <component src>. Vibe re-fetches, re-executes scripts, and re-inlines
+  // the template. Used for first-HMR (no baseline hash), script changes,
+  // iteration-nested instances, and as a failure fallback.
+  const remount = (el, path, scriptHash) => {
+    const oldComponentIds = collectIdsInOrder(el);
+    const fresh = document.createElement(el.tagName);
+    if (el.tagName === 'DIV') fresh.className = 'component';
+    const props = el._vibeProps || { src: path };
+    for (const [name, value] of Object.entries(props)) {
+      fresh.setAttribute(name, value);
+    }
+    fresh.setAttribute('vibe-fouc', '');
+    const slot = el._vibePluginSlot !== undefined
+      ? el._vibePluginSlot
+      : (el._vibeSlotContent || '');
+    fresh._vibeSlotContent = slot;
+    fresh._vibePluginSlot = slot;
+    fresh._vibeScriptHash = scriptHash;
+    if (oldComponentIds.length) fresh._vibeReuseComponentIds = oldComponentIds;
+    // Transfer iteration-prop registry ownership from the soon-to-be-detached
+    // wrapper to the fresh one. The detach would otherwise trigger Vibe's
+    // releaseOrphanedIterationProps and free the registry slots that the
+    // copied prop attributes (e.g. node='@[window.__vibeIterProps._pN]') still
+    // reference, leaving every binding to render undefined after the HMR swap.
+    if (el._vibeIterPropIds) {
+      fresh._vibeIterPropIds = el._vibeIterPropIds;
+      fresh.setAttribute('data-vibe-iter-prop', '');
+      el._vibeIterPropIds = null;
+      el.removeAttribute('data-vibe-iter-prop');
+    }
+    el.replaceWith(fresh);
+  };
+
+  // Component file changed. Strategy:
+  //   1. Fetch the raw template once per update; hash its <script type="module">
+  //      contents. Script hash unchanged + not inside an iteration → surgical
+  //      path: $.renderComponent produces the processed HTML (props + slot
+  //      substituted, componentIds reused) and $.reconcile diffs it against
+  //      the live wrapper's children. DOM identity, focus, and component
+  //      state are preserved.
+  //   2. First HMR for any instance (no baseline hash stored), script changes,
+  //      or iteration-scoped callsites → full re-mount (same path as before
+  //      the surgical rewrite). vibe-fouc hides the subtree until ready.
+  //
+  // Props and slot content always come from the spy's _vibeProps /
+  // _vibePluginSlot snapshot.
+  let componentUpdateCount = 0;
+  const componentUpdate = async (path) => {
+    const n = ++componentUpdateCount;
+    // Drop the runtime's cached template for this file so any component
+    // mounted *after* this edit fetches the fresh version. Already-mounted
+    // instances are refreshed surgically below; this covers future mounts.
+    window.$?.clearComponentCache?.(path);
+    const instances = liveBySrc.get(path);
+    dbg.group('[vibe-hmr] component-update #' + n, path,
+      '— instances:', instances?.size || 0);
+    try {
+      if (!instances || !instances.size) {
+        dbg.info('[vibe-hmr]   no live instances; nothing to do');
+        return;
+      }
+      const rawUrl = path + (path.includes('?') ? '&' : '?') + '_t=' + Date.now();
+      const rawHtml = await fetch(rawUrl, { cache: 'no-store' }).then((r) => r.text());
+      const scriptHash = hashScripts(rawHtml);
+      const canSurgical = typeof window.$?.renderComponent === 'function'
+        && typeof window.$?.reconcile === 'function';
+
+      let surgical = 0;
+      let remounted = 0;
+      for (const el of [...instances]) {
+        instances.delete(el);
+        if (!el.parentNode) continue;
+
+        const oldHash = getBaselineScriptHash(el);
+        const inIter = isInsideIteration(el);
+
+        if (canSurgical && oldHash !== undefined && oldHash === scriptHash && !inIter) {
+          try {
+            const componentIds = collectIdsInOrder(el);
+            const slot = el._vibePluginSlot !== undefined
+              ? el._vibePluginSlot
+              : (el._vibeSlotContent || '');
+            const props = el._vibeProps || {};
+            const processedHtml = window.$.renderComponent(rawHtml, props, slot, { componentIds });
+            const summary = await window.$.reconcile(el, processedHtml);
+            el._vibeScriptHash = scriptHash;
+            el._vibeRawSource = rawHtml;
+            if (!liveBySrc.has(path)) liveBySrc.set(path, new Set());
+            liveBySrc.get(path).add(el);
+            surgical++;
+            dbg.info('[vibe-hmr]   surgical reconcile:', summary);
+            continue;
+          } catch (err) {
+            console.warn('[vibe-hmr]   surgical failed, falling back to re-mount:', err);
+          }
+        }
+
+        remount(el, path, scriptHash);
+        remounted++;
+      }
+      dbg.info('[vibe-hmr]   surgical:', surgical, 'remounted:', remounted);
+    } catch (err) {
+      console.error('[vibe-hmr]   component-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  // Page file changed — fetch new HTML and hand the [vibe] root + new inner
+  // content to $.reconcile. Vibe walks live vs. source and applies the
+  // minimal mutation; iteration / conditional / component regions are
+  // opaque (their interiors are state-driven). Page-level JS state on $
+  // is preserved (no full reload).
+  let pageUpdateCount = 0;
+  const pageUpdate = async (payload) => {
+    const n = ++pageUpdateCount;
+    dbg.group('[vibe-hmr] page-update #' + n, payload?.path || '(no path)');
+    try {
+      if (!window.$ || typeof window.$.reconcile !== 'function') {
+        console.warn('[vibe-hmr]   $.reconcile not available — skipped');
+        return;
+      }
+      const url = location.href + (location.href.includes('?') ? '&' : '?') + '_t=' + Date.now();
+      const t0 = performance.now();
+      const html = await fetch(url).then((r) => r.text());
+      dbg.info('[vibe-hmr]   fetched', html.length, 'bytes in', (performance.now() - t0).toFixed(1) + 'ms');
+      const doc = new DOMParser().parseFromString(html, 'text/html');
+      const newRoot = doc.querySelector('[vibe]') || doc.body;
+      const liveRoot = document.querySelector('[vibe]') || document.body;
+      dbg.info('[vibe-hmr]   target [vibe] root:', liveRoot, 'isConnected=', liveRoot.isConnected);
+      // Note: we no longer strip <script type='module'> from source. Stripping
+      // misaligned source vs. live and caused cascading replaces. Reconcile's
+      // tag-aligned walk now matches scripts at their position; updating a
+      // script's textContent doesn't re-execute it (a known limitation —
+      // editing inline page scripts requires a real reload to take effect).
+      const summary = await window.$.reconcile(liveRoot, newRoot.innerHTML);
+      dbg.info('[vibe-hmr]   summary:', summary);
+      if (summary?.changes?.length) {
+        for (const c of summary.changes) dbg.info('[vibe-hmr]     ·', c);
+      } else {
+        dbg.info('[vibe-hmr]   no changes — source matches live');
+      }
+    } catch (err) {
+      console.error('[vibe-hmr]   page-update failed:', err);
+    } finally {
+      dbg.groupEnd();
+    }
+  };
+
+  subscribe({ componentUpdate, pageUpdate });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.1.18",
+  "version": "2.1.20",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
@@ -9,6 +9,7 @@
     ".": "./index.js",
     "./boot": "./boot.js",
     "./component": "./component.js",
+    "./hot-module-refresh": "./hot-module-refresh.js",
     "./runtime": "./runtime/index.js",
     "./compiler": "./compiler/bin/vibe-compile.js"
   },

package/runtime/constants.js

@@ -211,18 +211,23 @@ export const BINDING_REGEX = new RegExp(String.raw`\@\[(${BINDING_INNER})\]`, 'g
 // Regex for detecting a pure binding (entire value is just @[expression])
 export const PURE_BINDING_REGEX = new RegExp(String.raw`^\@\[(${BINDING_INNER})\]$`);
 
-// Regex for parsing iteration comment syntax. Supported forms:
+// Regex for parsing iteration comment syntax. Supported forms — the index and
+// the key are each optional and may appear in EITHER order:
 //   <!-- each items as item -->
 //   <!-- each items as item, index -->
 //   <!-- each items as item (item.id) -->                // explicit key
-//   <!-- each items as item (item.id), index -->         // key + index
-// Capture groups: arrayPath, itemAlias, keyExpr (optional), indexAlias (optional).
+//   <!-- each items as item (item.id), index -->         // key, then index
+//   <!-- each items as item, index (item.id) -->         // index, then key
+// Capture groups: arrayPath, itemAlias, keyBeforeIndex (optional), indexAlias
+// (optional), keyAfterIndex (optional). The key lands in group 3 when written
+// before the index and in group 5 when written after; parseIterationHeader
+// coalesces the two — prefer that helper over destructuring the raw match.
 // The array expression can be any JS: a state path, a window global, a method
 // call, or an inline literal. The optional key expression is evaluated per
 // item against scoped state to produce a stable identity for diffing — this
 // keeps survivors stable when earlier items are removed (otherwise the
 // fallback hash key embeds the index and triggers bulk re-render).
-export const ITERATION_REGEX = /^each\s+(.+)\s+as\s+(\w+)(?:\s*\(\s*([^)]+?)\s*\))?(?:\s*,\s*(\w+))?\s*$/;
+export const ITERATION_REGEX = /^each\s+(.+)\s+as\s+(\w+)(?:\s*\(\s*([^)]+?)\s*\))?(?:\s*,\s*(\w+))?(?:\s*\(\s*([^)]+?)\s*\))?\s*$/;
 
 // Regex for detecting start of iteration comment
 export const ITERATION_START_REGEX = /^each\s+/;

package/runtime/iteration-utils.js

@@ -1,5 +1,24 @@
 // Utility functions for array iteration
-import { ITERATION_START_REGEX, CONDITIONAL_START_REGEX } from './constants.js';
+import { ITERATION_REGEX, ITERATION_START_REGEX, CONDITIONAL_START_REGEX } from './constants.js';
+
+// 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;
+  const [, arrayPath, itemAlias, keyBeforeIndex, indexAlias, keyAfterIndex] = match;
+  const keyExpr = keyBeforeIndex ?? keyAfterIndex;
+  return {
+    arrayPath,
+    itemAlias,
+    keyExpr: keyExpr != null ? keyExpr.trim() : null,
+    indexAlias: indexAlias ?? null,
+  };
+};
 
 // Resolve nested paths in state (e.g., "user.items" -> state.user.items)
 // Supports bracket notation: "teams[0].combatants" -> state.teams[0].combatants

package/runtime/parse.js

@@ -1,8 +1,7 @@
-import { findEndComment, findConditionalEnd } from './iteration-utils.js';
+import { findEndComment, findConditionalEnd, parseIterationHeader } from './iteration-utils.js';
 import {
   NON_REACTIVE_ELEMENTS,
   BINDING_REGEX,
-  ITERATION_REGEX,
   CONDITIONAL_REGEX,
   DOM_ELEMENT_PROPERTIES,
   DEHYDRATE_CLASS_OR_ATTR,
@@ -150,10 +149,10 @@ const recursive = (children, rootKey = undefined, skipIndices = new Set(), stats
 
     // Handle iteration comments
     if (nodeName === '#comment') {
-      const iterationMatch = textContent.trim().match(ITERATION_REGEX);
+      const iterationMatch = parseIterationHeader(textContent.trim());
 
       if (iterationMatch) {
-        const [_, arrayPath, itemAlias, keyExpr, indexAlias] = iterationMatch;
+        const { arrayPath, itemAlias, keyExpr, indexAlias } = iterationMatch;
 
         try {
           // Find matching end comment