@ape-egg/vibe 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## [1.9.0] - 2026-04-18
+
+### Added
+
+- **`$.reconcile()` — subtree reconciliation API** (`runtime/reconcile.js`, new 621-line module) — reconcile a Vibe-managed subtree against new source HTML with a tag-aligned, two-pointer walker. Vibe-owned regions (iterations, conditionals, components, `<slot>` pairs) are treated as opaque; their internals stay state-driven. DOM identity, focus, and selection survive wherever a match is found.
+  - Exposed as `$.reconcile` (non-enumerable so it stays out of state snapshots)
+  - Test: `tests/e2e/reconcile.spec.js`
+
+- **Component state cleanup on unmount** (`runtime/component.js`, `runtime/conditionals.js`, `runtime/index.js`, `runtime/manifest.js`) — when a `<component>` leaves the DOM (conditional branch swap, iteration key removal, etc.), its entry in `window.__vibeComponents[id]` and `window.$[id]` is evicted. `collectComponentIds` walks removed subtrees; `releaseOrphanedComponentState` verifies the DOM is fully gone before deleting state. Prevents state leaks from components that mount and unmount repeatedly.
+  - Test: `tests/e2e/component-state-cleanup.spec.js`
+
+- **Arbitrary JS expressions in `<!-- each -->`** (`runtime/constants.js`) — `ITERATION_REGEX` relaxed from `[\w.\[\]]+` to `.+`. The array expression is now evaluated via `evalInScope`, so you can iterate over method calls, window globals, inline array literals, filters, and `Array.from(...)`:
+  ```html
+  <!-- each items.filter(x => x.active) as item -->
+  <!-- each Array.from({length: 10}, (_, i) => i) as n -->
+  <!-- each window.fights as fight, i -->
+  ```
+  - Test: `tests/e2e/each-expression.spec.js`
+
+- **Missing-identifier safety in expressions** (`runtime/utils.js`) — `evalInScope` now wraps free identifiers that aren't state keys, reserved words, or known globals in `typeof` guards so they resolve to `undefined` instead of throwing `ReferenceError`. `@[!missingProp]` → `true`, `@[optional?.x]` → `undefined`. Uses `typeof` rather than a `var` hoist so real globals (app functions on `window` like `getLevelByExperience`) stay reachable.
+
+- **Arrow function parameters and object-literal keys recognized** (`runtime/utils.js`) — identifier rewriting now skips `(a, b) =>` / `x =>` parameter lists and `{ key: value }` property names. Expressions like `items.map(x => x.name)` and `@[{ a: 1 }[k]]` no longer get turned into invalid JS by the missing-identifier pass.
+
+- **Prop substitution covers directive comments and event handlers** (`runtime/component.js`) — prop identifiers now resolve inside `<!-- if propName -->`, `<!-- else if propName -->`, `<!-- each propName as item -->` and `onclick="$.propName = x"` in addition to `@[...]`. Writing `$.value = x` inside an event handler on a child component whose parent passed `value="@[email]"` updates `$.email` on the parent — natural two-way binding with no extra API.
+  - Tests: `tests/e2e/prop-in-directive.spec.js`, `tests/e2e/prop-in-expression.spec.js`, `tests/e2e/two-way-binding.spec.js`
+
+- **Pre-boot `$.ready` promise** (`index.js`, `boot.js`) — the placeholder returned by `vibe()` before boot now exposes a `.ready` promise that chains to the real post-boot `$.ready`. Consumers that captured `window.$` early (tests, auto-initializers) can `await $.ready` without polling. New `chainInstanceReady` export links the two.
+
+- **Async component scripts** (`runtime/component.js`) — `<script type="module">` blocks in components with `import` statements are rewritten to `await import()` and executed via `AsyncFunction`. Sync execution preserved when there are no imports (keeps boot timing unchanged). Component finalization waits for all async scripts before inlining.
+  - Tests: `tests/e2e/async-component-state.spec.js`, `tests/e2e/parallel-components.spec.js`
+
+- **Promises never proxied as reactive state** (`runtime/state.js`) — proxy `get` trap now bails on `value instanceof Promise`. Wrapping a Promise violates the Proxy invariant when exposed as a non-writable property (e.g. `$.ready`) and makes no sense as reactive state.
+
+### Fixed
+
+- **HTML-entity decoding in compiled iteration templates** (`runtime/_vibe-compiled-iteration-batch.js`) — when a template's attributes get serialized via `innerHTML`, the browser encodes `<`, `>`, `"`, `&`, `'`. The batch-function compiler was wrapping those encoded expressions directly in a template literal, producing invalid JS for bindings like `@[x > 0 ? 'a' : 'b']` when used inside an attribute. Entities are now decoded before interpolation.
+
+- **`<!-- each -->` over `Array.from(...)` and other inline expressions** — previously failed silently because `ITERATION_REGEX` only accepted simple paths. See `ITERATION_REGEX` change above.
+
+- **Attribute bindings on fetched `<component src>` wrappers were coerced to strings** (`runtime/parse.js`) — `captureAttributeBindings` now returns nulls for elements that are still `<component src>` / `<div class="component" src>` (pre-fetch), so raw prop values survive untouched for `processComponent` to substitute. Post-fetch wrappers (no `src`) capture attributes normally.
+
+### Changed
+
+- **Iteration engine rework** (`runtime/iterate.js`, +378 lines over 1.8.1) — unified update path around tagged instance keys, bulk-replacement fast path when old/new arrays share no common keys (uses `Range.deleteContents` + single `innerHTML`), and DocumentFragment batching inside `renderIteration` so N inserts become one.
+
+- **Debug scaffolding removed** (`runtime/index.js`) — an ad-hoc `[vibe-debug] rerender` `console.info` and the associated `window.__lastHits` / `window.__parsedTree` probes (leftover from an investigation) have been deleted.
+
+### Documentation
+
+- **README — "Future improvements to refactor"** — documents the string-based dependency-tracking approach used by `affected()` and its always-affected fallback semantics, and the HTML-lowercased attribute-name handling.
+
+### Packaging
+
+- **`@ape-egg/vite-plugin-vibe` published** — new sibling package providing a Vite plugin with HMR for Vibe pages and components. See its own `README.md` and `CHANGELOG.md`.
+
+---
+
+## [1.8.1] - 2026-04-12
+
+### Added
+
+- **`<slot>` boundary preserved in processed DOM** — component slot content is now wrapped in a `<slot>` element instead of being spliced in directly. Dev tools, HMR, and anything that needs to locate slot boundaries can query for `<slot>` instead of tracking comment pairs.
+  - `runtime/component.js` — `<slot></slot>` replaced with `<slot>${children}</slot>`
+  - `compiler/src/parser/html.rs` — compiler emits the same wrapping
+  - `vibe.css` — `slot, div.slot { display: contents }` so the wrapper is layout-transparent
+
+### Fixed
+
+- **Conditionals inside doubly-nested component slots lost their templates** — when a `<component src>` appeared inside another component's slot content, Vibe's parser ran `renderConditional` (which strips template nodes) before `processComponent` captured the slot content, so branch templates were gone by the time the nested component tried to use them.
+  - `runtime/index.js` — `processMutations` now captures `_vibeSlotContent` for all nested `<component src>` elements before parse/hydrate runs
+  - Test: `tests/e2e/conditional-in-nested-slot.spec.js`
+
+- **Bindings with complex expressions re-hydrated on every state change** — `matchesKey` did prefix-only matching, so expressions like `@[Math.floor(coins / 100)]` couldn't be matched to any state key and hit the "always affected" fallback. A 250ms client clock would re-hydrate every such binding 4× per second.
+  - `runtime/affected.js` — `matchesKey` now also does word-boundary search so it finds `coins` as an identifier inside the expression
+  - Test: `tests/e2e/expression-dependency.spec.js`
+
+- **Iteration instance comparisons used live Proxy as "old state"** — `scopedState` is a Proxy that reflects current global state, so comparing `state[k]` vs `newState[k]` showed both as the new value. Global state changes inside iterations weren't detected as changes.
+  - `runtime/affected.js` — iteration recursion now builds plain-object snapshots from previousState/currentState merged with scopedState's local vars
+
+- **Name bindings re-hydrated on every state change** — HTML lowercases attribute names, so `<page @[pageName]>` becomes `@[pagename]` in the DOM. `matchesKey('pagename', 'pageName')` failed (case-sensitive), triggering the always-affected fallback and causing constant attribute flashing.
+  - `runtime/affected.js` — name binding dependency check now matches state keys case-insensitively, mirroring `hydrate.js`'s existing case-insensitive evaluation fallback
+
+### Documentation
+
+- `README.md` — "Future improvements to refactor" section documenting string-based dependency tracking limitations and HTML lowercase attribute handling
+
+---
+
 ## [1.8.0] - 2026-04-10
 
 ### Added

package/README.md

@@ -525,3 +525,31 @@ Modern browsers with Proxy and MutationObserver support.
 ## License
 
 ISC
+
+---
+
+## Future improvements to refactor
+
+### Dependency tracking uses string matching, not AST
+
+`affected()` determines which bindings to re-hydrate by string-matching expression text against state key names. When matching fails, a safety fallback marks the binding as affected on every state change.
+
+- `runtime/affected.js:15` — `matchesKey` does exact/prefix match, then word-boundary search
+- `runtime/affected.js:~122` — `shouldAffect = noMatch || ...` fallback for unmatched expressions
+- `runtime/affected.js:~248` — same fallback for name bindings
+
+Every time `matchesKey` can't prove an expression is unrelated to a state change, that binding re-hydrates. A proper AST-based dependency extraction at parse time would eliminate the fallback entirely: each binding stores its exact dependency set, and runtime just checks if any dep key changed.
+
+### HTML lowercases attribute names — breaks name binding matching
+
+The browser lowercases all attribute names during HTML parsing. `<page @[pageName]>` becomes `@[pagename]` in the DOM. Every value hydrated into an attribute NAME position loses its case. `@[myCoolPage]` → DOM stores `@[mycoolpage]`, causing comparison mismatches against camelCase state keys.
+
+Handled today by case-insensitive fallbacks in two places:
+- `runtime/hydrate.js:~32` — case-insensitive state key lookup when evaluating name bindings
+- `runtime/affected.js:~235` — case-insensitive `matchesKey` wrapper for name bindings
+
+Both are workarounds for HTML's behavior. A cleaner architecture would centralize the case-insensitive state key resolution into one helper, or normalize the name binding expression to canonical state-key case at first evaluation and cache it on the tree node.
+
+### Related: value hydration into attribute values is case-preserving
+
+Only attribute NAMES are lowercased by HTML, not values. So `title="@[pageName]"` and `@[pageName]` in text content preserve case and work without fallbacks — the issue is specific to name bindings.

package/boot.js

@@ -2,7 +2,7 @@
 // Used by both index.js (global state) and component.js (component state)
 
 import main from './runtime/index.js';
-import { getPendingListeners } from './index.js';
+import { getPendingListeners, chainInstanceReady } from './index.js';
 
 let bootQueued = false;
 let booted = false;
@@ -40,6 +40,10 @@ export const boot = () => {
   // Boot with merged state
   window.$ = main(mergedState, config, targetSelector);
 
+  // Forward real $.ready to the pre-boot placeholder's ready promise so
+  // any consumer that captured the placeholder can still await readiness.
+  chainInstanceReady(window.$.ready);
+
   // Apply pending listeners from vibe instance
   const pendingListeners = getPendingListeners();
   if (pendingListeners) {

package/compiler/src/parser/html.rs

@@ -231,15 +231,15 @@ impl HtmlParser {
                         replacement = replacement.replace(&prop_binding, &prop_value);
                     }
 
-                    // Replace <slot> tags with content, or remove if empty/missing
-                    let slot_replacement = if slot_content.trim().is_empty() {
-                        ""
+                    // Replace <slot> tags — wrap children in <slot> boundary, or remove if empty
+                    let slot_wrapped = if slot_content.trim().is_empty() {
+                        String::new()
                     } else {
-                        &slot_content
+                        format!("<slot>{}</slot>", slot_content)
                     };
-                    replacement = replacement.replace("<slot></slot>", slot_replacement);
-                    replacement = replacement.replace("<slot/>", slot_replacement);
-                    replacement = replacement.replace("<slot />", slot_replacement);
+                    replacement = replacement.replace("<slot></slot>", &slot_wrapped);
+                    replacement = replacement.replace("<slot/>", &slot_wrapped);
+                    replacement = replacement.replace("<slot />", &slot_wrapped);
 
                     // Keep the wrapper for consistency with runtime (using generic <component> wrapper)
                     // No src attribute = wrapper won't be re-processed
@@ -371,10 +371,10 @@ impl HtmlParser {
                 replacement = replacement.replace(&prop_binding, prop_value);
             }
 
-            let slot_replacement = if slot_content.trim().is_empty() { "" } else { slot_content.as_str() };
-            replacement = replacement.replace("<slot></slot>", slot_replacement);
-            replacement = replacement.replace("<slot/>", slot_replacement);
-            replacement = replacement.replace("<slot />", slot_replacement);
+            let slot_wrapped = if slot_content.trim().is_empty() { String::new() } else { format!("<slot>{}</slot>", slot_content) };
+            replacement = replacement.replace("<slot></slot>", &slot_wrapped);
+            replacement = replacement.replace("<slot/>", &slot_wrapped);
+            replacement = replacement.replace("<slot />", &slot_wrapped);
 
             let wrapper = format!("<component>{}</component>", replacement);
             result.replace_range(*start..*end, &wrapper);
@@ -447,10 +447,10 @@ impl HtmlParser {
                         replacement = replacement.replace(&prop_binding, prop_value);
                     }
 
-                    let slot_replacement = if slot_content.trim().is_empty() { "" } else { slot_content.as_str() };
-                    replacement = replacement.replace("<slot></slot>", slot_replacement);
-                    replacement = replacement.replace("<slot/>", slot_replacement);
-                    replacement = replacement.replace("<slot />", slot_replacement);
+                    let slot_wrapped = if slot_content.trim().is_empty() { String::new() } else { format!("<slot>{}</slot>", slot_content) };
+                    replacement = replacement.replace("<slot></slot>", &slot_wrapped);
+                    replacement = replacement.replace("<slot/>", &slot_wrapped);
+                    replacement = replacement.replace("<slot />", &slot_wrapped);
 
                     let wrapper = format!("<component>{}</component>", replacement);
                     result.replace_range(start..end, &wrapper);

package/index.js

@@ -5,9 +5,16 @@ import { boot, isBooted, ensureBoot } from './boot.js';
 
 // Shared instance for queueing listeners before boot
 let vibeInstance = null;
+let resolveInstanceReady = null;
 
 const createVibeInstance = () => ({
   _pendingListeners: { afterUpdate: [], afterDomMutation: [], ready: [] },
+  // Promise that resolves when the real $.ready resolves post-boot. Lets
+  // consumers holding the pre-boot placeholder (e.g. tests awaiting
+  // `window.$.ready` before boot has replaced $ with the reactive proxy)
+  // wait for readiness without polling. Non-enumerable so it stays out of
+  // state snapshots.
+  ready: new Promise((resolve) => { resolveInstanceReady = resolve; }),
   on(event, callback) {
     // If booted, delegate to window.$
     if (isBooted() && window.$) {
@@ -66,4 +73,12 @@ const vibe = (state = {}, config, targetSelector) => {
 // Export function to get pending listeners (used by boot.js)
 export const getPendingListeners = () => vibeInstance?._pendingListeners || null;
 
+// Forward post-boot $.ready to the pre-boot placeholder's ready promise.
+// Called by boot.js after main() creates the real reactive proxy.
+export const chainInstanceReady = (realReadyPromise) => {
+  if (resolveInstanceReady && realReadyPromise) {
+    realReadyPromise.then(() => resolveInstanceReady());
+  }
+};
+
 export default vibe;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
@@ -27,7 +27,7 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "author": "Kim Korte",
+  "author": "kkortes",
   "license": "ISC",
   "publishConfig": {
     "access": "public"

package/runtime/_vibe-compiled-iteration-batch.js

@@ -28,6 +28,15 @@
 
 import { BINDING_REGEX } from './constants.js';
 
+// innerHTML serialization encodes <, >, &, ", ' inside attribute values.
+// Decode them back before wrapping @[expr] in ${...} for the template literal.
+const decodeEntities = (s) => s
+  .replace(/&lt;/g, '<')
+  .replace(/&gt;/g, '>')
+  .replace(/&quot;/g, '"')
+  .replace(/&#39;/g, "'")
+  .replace(/&amp;/g, '&');
+
 // Reusable template element for HTML parsing
 const parseTemplate = document.createElement('template');
 
@@ -59,20 +68,20 @@ const hasNestedStructures = (tree) => {
 export const compileBatchFn = (template, itemAlias, indexAlias, stateKeys) => {
   const templateHtml = template.element.innerHTML.trim();
   const escaped = templateHtml.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
-  const code = escaped.replace(BINDING_REGEX, (_, expr) => '${' + expr + '}');
+  const code = escaped.replace(BINDING_REGEX, (_, expr) => '${' + decodeEntities(expr) + '}');
 
   return new Function(
     'arr',
     ...stateKeys,
     `
-    let html = '';
-    const len = arr.length;
-    for (let ${indexAlias} = 0; ${indexAlias} < len; ${indexAlias}++) {
-      const ${itemAlias} = arr[${indexAlias}];
-      html += \`${code}\`;
-    }
-    return html;
-  `,
+      let html = '';
+      const len = arr.length;
+      for (let ${indexAlias} = 0; ${indexAlias} < len; ${indexAlias}++) {
+        const ${itemAlias} = arr[${indexAlias}];
+        html += \`${code}\`;
+      }
+      return html;
+    `,
   );
 };
 

package/runtime/affected.js

@@ -6,20 +6,33 @@ import { evalInScope, resolveThisPath } from './utils.js';
 // Evaluate conditional expression
 const evaluateCondition = (expression, state, element = null) => !!evalInScope(expression, state, element);
 
-// Helper function to check if a match references a specific key
-const matchesKey = (matchStr, key) =>
-  matchStr === key ||
-  matchStr.startsWith(key + '.') ||
-  matchStr.startsWith(key + '[');
+// Helper function to check if a match references a specific key.
+// Fast path: exact match or property access (`user.name` matches `user`).
+// Slow path: word-boundary search for complex expressions like `Math.floor(coins / 100)`
+// where the key appears as an identifier anywhere in the expression.
+const isIdentChar = (c) => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c === '_' || c === '$';
+
+const matchesKey = (matchStr, key) => {
+  if (matchStr === key || matchStr.startsWith(key + '.') || matchStr.startsWith(key + '[')) return true;
+
+  // Search for key as a standalone identifier (word boundaries on both sides)
+  let i = 0;
+  while ((i = matchStr.indexOf(key, i)) !== -1) {
+    const before = i === 0 ? '' : matchStr[i - 1];
+    const after = i + key.length >= matchStr.length ? '' : matchStr[i + key.length];
+    if (!isIdentChar(before) && !isIdentChar(after)) return true;
+    i += key.length;
+  }
+  return false;
+};
 
 const recursive = (tree, state, newState, affected, scopedStateForHydration = null, depth = 0) => {
   // Handle iteration nodes specially
   if (tree.type === 'iteration') {
-    // Handle this.property for component-scoped arrays
-    const arrayPath = resolveThisPath(tree.meta.arrayPath, tree.meta.startComment?.parentElement);
+    const resolvedExpr = resolveThisPath(tree.meta.arrayPath, tree.meta.startComment?.parentElement);
 
-    const oldArray = resolvePath(state, arrayPath);
-    const newArray = resolvePath(newState, arrayPath);
+    const oldArray = evalInScope(resolvedExpr, state, tree.meta.startComment?.parentElement) ?? resolvePath(state, resolvedExpr);
+    const newArray = evalInScope(resolvedExpr, newState, tree.meta.startComment?.parentElement) ?? resolvePath(newState, resolvedExpr);
 
     // Fast path: reference comparison (arrays are typically replaced, not mutated)
     // This avoids expensive O(n) deepEqual for large arrays
@@ -55,11 +68,15 @@ const recursive = (tree, state, newState, affected, scopedStateForHydration = nu
 
       for (const instance of tree.runtime.instances) {
         if (instance.tree && instance.scopedState) {
-          // Use the instance's scoped state (includes item, index, etc.)
-          // Merge newState into scopedState to get updated global values
+          // Build plain-object snapshots for comparison. scopedState is a live Proxy
+          // that reflects current global state — spreading it gives us the local vars
+          // (cat, index) plus current global values. We then override globals with the
+          // actual old (state) / new (newState) values so binding comparisons can detect
+          // which state keys changed.
+          const mergedOldState = { ...instance.scopedState, ...state };
           const mergedNewState = { ...instance.scopedState, ...newState };
-          // Pass the Proxy as scopedState so evalInScope can access iteration variables
-          recursive(instance.tree, instance.scopedState, mergedNewState, affected, instance.scopedState, depth + 1);
+          // Pass scopedState as scopedStateForHydration so evalInScope can access iteration variables
+          recursive(instance.tree, mergedOldState, mergedNewState, affected, instance.scopedState, depth + 1);
         }
       }
     }
@@ -220,17 +237,20 @@ const recursive = (tree, state, newState, affected, scopedStateForHydration = nu
       for (const m of nameMatches) {
         // Resolve this.property to componentId.property
         const resolvedInner = resolveThisPath(m.inner, tree.element);
+        // HTML lowercases attribute names, so expression may be lowercase while state
+        // keys are camelCase. Match case-insensitively by trying both direct and lowercased.
+        const matchKey = (key) => matchesKey(resolvedInner, key) || matchesKey(resolvedInner, key.toLowerCase());
 
-        const noMatch = !shallowState.some((key) => matchesKey(resolvedInner, key));
+        const noMatch = !shallowState.some(matchKey);
 
         let shouldAffect = false;
 
         if (isInitialHydration) {
-          const newMatches = shallowNewState.filter((key) => matchesKey(resolvedInner, key));
+          const newMatches = shallowNewState.filter(matchKey);
           shouldAffect = noMatch || newMatches.length > 0;
         } else {
           const changedKeys = shallowNewState.filter((key) =>
-            matchesKey(resolvedInner, key) && state[key] !== newState[key]
+            matchKey(key) && state[key] !== newState[key]
           );
           shouldAffect = noMatch || changedKeys.length > 0;
         }