npm - @ape-egg/vibe - Versions diffs - 1.0.0 - Mend

@ape-egg/vibe 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.md +42 -0
package/README.md +108 -0
package/_vibe-compiled-iteration-batch.js +161 -0
package/affected.js +149 -0
package/conditionals.js +182 -0
package/constants.js +76 -0
package/hydrate.js +100 -0
package/index.js +250 -0
package/iterate.js +451 -0
package/iteration-utils.js +261 -0
package/link.js +13 -0
package/llms.txt +279 -0
package/package.json +26 -0
package/parse.js +225 -0
package/state.js +26 -0
package/utils.js +45 -0
package/vibe.css +11 -0

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,42 @@
+# Changelog
+## [1.0.0] - 2026-01-19
+### Added
+- Initial public release
+- Proxy-based reactive state (`window.$`)
+- MutationObserver for automatic DOM tracking
+- Fine-grained updates (no virtual DOM)
+### Core Features
+- **Reactive bindings**: `@[property]` syntax in HTML and CSS
+- **Iteration**: `<!-- each items as item, i -->` with efficient diffing
+- **Nested iteration**: `<!-- each category.items as item -->`
+- **Conditionals**: `<!-- if condition -->...<!-- else -->...<!-- /if -->`
+- **Dehydrate**: `<div dehydrate>` to skip reactive processing
+- **Expression evaluation**: `@[count * 2]`, `@[firstName + ' ' + lastName]`
+### Performance
+- Surgical DOM updates - only affected elements re-render
+---
+## [0.0.5] - 2026-01-15
+- Heavy optimizations for iteration rendering
+- Added benchmark tooling
+- Improved diffing algorithm for array changes
+## [0.0.4] - 2026-01-10
+- Renamed from "Soulbound" to "Vibe"
+- Published to npm as `@ape-egg/vibe`
+## [0.0.1-0.0.3] - 2026-01-06 to 2026-01-09
+- Initial development and prototyping
+- Core architecture: parse, link, hydrate, affected, state
+- Basic iteration and conditional support

package/README.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Vibe
+A runtime-first reactive library.
+No virtual DOM. No build step. Just modern JavaScript.
+## Install
+```bash
+npm install @ape-egg/vibe
+```
+## Quick Start
+```html
+<script type="module">
+  import state from "@ape-egg/vibe";
+  window.$ = state({ name: "World", count: 0 });
+</script>
+<h1>Hello, @[name]!</h1>
+<button onclick="$.count++">Clicked @[count] times</button>
+```
+## Features
+### Reactive Bindings
+Use `@[property]` anywhere in HTML or CSS:
+```html
+<div>@[firstName] @[lastName]</div>
+<div>@[firstName + ' ' + lastName]</div>
+<style>
+  .box { background: @[themeColor]; }
+</style>
+```
+### Iteration
+```html
+<!-- each items as item, index -->
+  <li>@[index]: @[item]</li>
+<!-- /each -->
+```
+Nested iteration with dot paths:
+```html
+<!-- each categories as category -->
+  <!-- each category.items as item -->
+    <span>@[item.name]</span>
+  <!-- /each -->
+<!-- /each -->
+```
+### Conditionals
+```html
+<!-- if user.isAdmin -->
+  <admin-badge>Admin</admin-badge>
+<!-- else -->
+  <span>User</span>
+<!-- /if -->
+```
+### Dehydrate
+Skip reactive processing for an element:
+```html
+<code dehydrate>@[this] displays literally</code>
+```
+### Dynamic Elements
+Elements added via JavaScript are automatically hydrated through MutationObserver.
+## How It Works
+1. **Proxy-based state** — `window.$` intercepts property changes
+2. **DOM parsing** — Finds all `@[...]` bindings on load
+3. **Surgical updates** — Only affected elements re-render
+4. **MutationObserver** — Tracks dynamically added elements
+## Prevent FOUC
+Hide content until hydration completes:
+```html
+<body style="visibility: hidden;">
+```
+Or use the included CSS:
+```html
+<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
+<body vibe>
+```
+## Browser Support
+Modern browsers with Proxy and MutationObserver support.
+## License
+ISC

package/_vibe-compiled-iteration-batch.js ADDED Viewed

@@ -0,0 +1,161 @@
+/**
+ * _vibe-compiled-iteration-batch.js
+ *
+ * EXPERIMENTAL: Fast path for iteration rendering using compiled batch functions.
+ *
+ * This is a preview/prototype of what Vibe Compiled (Phase 2) will do automatically.
+ * Currently opt-in via: window.__VIBE_FAST_ITERATION__ = true
+ *
+ * HOW IT WORKS:
+ * Instead of cloning DOM nodes and hydrating each item individually (slow),
+ * this compiles the template to a JavaScript function that builds HTML strings
+ * in a loop, then parses once with innerHTML (fast).
+ *
+ * Template: <item-card><item-text>@[item.name]</item-text></item-card>
+ * Compiles to: (arr) => { let html=''; for(...) html += `<item-card>...${item.name}...`; return html; }
+ *
+ * LIMITATIONS:
+ * - Cannot handle nested <!-- each --> or <!-- if --> (those need DOM-based rendering)
+ * - Cannot do incremental updates for small changes (rebuilds entire list)
+ * - Template structure is "frozen" at compile time
+ *
+ * WHEN VIBE COMPILED EXISTS:
+ * This logic will move to build-time compilation, producing optimized JavaScript
+ * that gets shipped to the browser. The runtime will just execute the compiled code.
+ *
+ * See: .claude/phase-2-compiler.md for full compiler plans
+ */
+import { BINDING_REGEX } from './constants.js';
+// Reusable template element for HTML parsing
+const parseTemplate = document.createElement('template');
+/**
+ * Check if a template can use the fast path (no nested iterations/conditionals)
+ */
+export const canUseFastPath = (template) => {
+  return !hasNestedStructures(template);
+};
+/**
+ * Recursively check if tree has nested iterations or conditionals
+ */
+const hasNestedStructures = (tree) => {
+  if (!tree || !tree.children) return false;
+  for (const key in tree.children) {
+    const child = tree.children[key];
+    if (!child) continue;
+    if (child.type === 'iteration' || child.type === 'conditional') return true;
+    if (hasNestedStructures(child)) return true;
+  }
+  return false;
+};
+/**
+ * Compile a batch function for an iteration template.
+ * Returns a function: (array, ...stateValues) => htmlString
+ */
+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 + '}');
+  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;
+  `);
+};
+/**
+ * Fast render: compile template to batch function and render via innerHTML
+ */
+export const renderFast = (iterationNode, array, state, parent, endComment) => {
+  const { itemAlias, indexAlias, template } = iterationNode.meta;
+  // Compile batch function if not cached
+  if (!iterationNode.runtime.batchFn) {
+    const stateKeys = Object.keys(state);
+    iterationNode.runtime.batchFn = compileBatchFn(template, itemAlias, indexAlias, stateKeys);
+    iterationNode.runtime.stateKeys = stateKeys;
+  }
+  const batchFn = iterationNode.runtime.batchFn;
+  const stateKeys = iterationNode.runtime.stateKeys;
+  // Build HTML string using batch function
+  const stateValues = stateKeys.map(k => state[k]);
+  const html = batchFn(array, ...stateValues);
+  // Parse with reusable template element
+  parseTemplate.innerHTML = html;
+  const frag = parseTemplate.content;
+  const kids = frag.children;
+  // Track instances
+  const arrayLen = array.length;
+  const instances = new Array(arrayLen);
+  for (let i = 0; i < arrayLen; i++) {
+    instances[i] = { element: kids[i], item: array[i], index: i };
+  }
+  parent.insertBefore(frag, endComment);
+  iterationNode.runtime.instances = instances;
+};
+/**
+ * Fast update: clear and rebuild for bulk operations
+ */
+export const updateFast = (iterationNode, newArray, state, startComment, endComment) => {
+  const { itemAlias, indexAlias, template } = iterationNode.meta;
+  const parent = startComment.parentNode;
+  // Fast clear using Range
+  if (iterationNode.runtime.instances.length > 0) {
+    const range = document.createRange();
+    range.setStartAfter(startComment);
+    range.setEndBefore(endComment);
+    range.deleteContents();
+  }
+  if (newArray.length === 0) {
+    iterationNode.runtime.instances = [];
+    return;
+  }
+  // Compile batch function if not cached (e.g., initial array was empty)
+  if (!iterationNode.runtime.batchFn) {
+    const stateKeys = Object.keys(state);
+    iterationNode.runtime.batchFn = compileBatchFn(template, itemAlias, indexAlias, stateKeys);
+    iterationNode.runtime.stateKeys = stateKeys;
+  }
+  // Build HTML string using cached batch function
+  const batchFn = iterationNode.runtime.batchFn;
+  const stateKeys = iterationNode.runtime.stateKeys;
+  const stateValues = stateKeys.map(k => state[k]);
+  const html = batchFn(newArray, ...stateValues);
+  // Parse and insert
+  parseTemplate.innerHTML = html;
+  const frag = parseTemplate.content;
+  const kids = frag.children;
+  // Build instance tracking
+  const arrayLen = newArray.length;
+  const instances = new Array(arrayLen);
+  for (let i = 0; i < arrayLen; i++) {
+    instances[i] = { element: kids[i], item: newArray[i], index: i };
+  }
+  parent.insertBefore(frag, endComment);
+  iterationNode.runtime.instances = instances;
+};

package/affected.js ADDED Viewed

@@ -0,0 +1,149 @@
+import { resolvePath, deepEqual } from './iteration-utils.js'
+import { extractDependencies } from './conditionals.js'
+import { BINDING_REGEX } from './constants.js'
+// Evaluate conditional expression
+const evaluateCondition = (expression, state) => {
+  try {
+    const keys = Object.keys(state);
+    const values = Object.values(state);
+    const result = new Function(...keys, `'use strict'; return !!(${expression})`)(...values);
+    return !!result;
+  } catch (e) {
+    return false;
+  }
+};
+// Helper function to check if a match references a specific key
+const matchesKey = (matchStr, key) => matchStr === key || matchStr.startsWith(key + '.');
+const recursive = (tree, state, newState, affected) => {
+  // Handle iteration nodes specially
+  if (tree.type === 'iteration') {
+    const oldArray = resolvePath(state, tree.meta.arrayPath);
+    const newArray = resolvePath(newState, tree.meta.arrayPath);
+    // Fast path: reference comparison (arrays are typically replaced, not mutated)
+    // This avoids expensive O(n) deepEqual for large arrays
+    if (oldArray !== newArray) {
+      affected.push({
+        type: 'iteration',
+        node: tree,
+        changeType: 'array'
+      });
+    }
+    return affected;
+  }
+  // Handle conditional nodes specially
+  if (tree.type === 'conditional') {
+    const oldValue = evaluateCondition(tree.meta.expression, state);
+    const newValue = evaluateCondition(tree.meta.expression, newState);
+    // Check if condition result changed
+    if (oldValue !== newValue) {
+      affected.push({
+        type: 'conditional',
+        node: tree,
+        changeType: 'expression'
+      });
+      return affected;
+    }
+    // Condition didn't change, check for affected elements inside active branch
+    if (tree.runtime.activeInstance && tree.runtime.activeInstance.parsedTree) {
+      return recursive(tree.runtime.activeInstance.parsedTree, state, newState, affected);
+    }
+    return affected;
+  }
+  // Reset regex state for reuse
+  BINDING_REGEX.lastIndex = 0;
+  const matches = [];
+  let match;
+  while ((match = BINDING_REGEX.exec(tree.parsed))) {
+    matches.push({ outer: match[0], inner: match[1], input: match.input });
+  }
+  if (matches.length) {
+    const shallowState = Object.keys(state);
+    const shallowNewState = Object.keys(newState);
+    let hasAffected = false;
+    const checkedMatches = [];
+    for (const m of matches) {
+      const noMatch = !shallowState.some(key => matchesKey(m.inner, key));
+      const newMatches = shallowNewState.filter(key => matchesKey(m.inner, key));
+      if (noMatch || newMatches.length) {
+        hasAffected = true;
+      }
+      checkedMatches.push({
+        ...m,
+        matches: newMatches.length ? newMatches : shallowState.filter(key => matchesKey(m.inner, key))
+      });
+    }
+    if (hasAffected) {
+      for (const m of checkedMatches) {
+        affected.push({
+          matchOuter: m.outer,
+          matchInner: m.inner,
+          input: m.input,
+          matches: m.matches,
+          element: tree.element
+        });
+      }
+    }
+  }
+  // Check attribute bindings
+  if (tree.attributes) {
+    const shallowState = Object.keys(state);
+    const shallowNewState = Object.keys(newState);
+    for (const [attrName, attrValue] of Object.entries(tree.attributes)) {
+      BINDING_REGEX.lastIndex = 0;
+      const attrMatches = [];
+      let attrMatch;
+      while ((attrMatch = BINDING_REGEX.exec(attrValue))) {
+        attrMatches.push({ outer: attrMatch[0], inner: attrMatch[1] });
+      }
+      for (const m of attrMatches) {
+        const noMatch = !shallowState.some(key => matchesKey(m.inner, key));
+        const newMatches = shallowNewState.filter(key => matchesKey(m.inner, key));
+        if (noMatch || newMatches.length) {
+          affected.push({
+            type: 'attribute',
+            attrName,
+            attrValue,
+            matchOuter: m.outer,
+            matchInner: m.inner,
+            element: tree.element
+          });
+        }
+      }
+    }
+  }
+  // Process children
+  const children = tree.children;
+  if (children) {
+    for (const key in children) {
+      const child = children[key];
+      if (child && typeof child === 'object') {
+        recursive(child, state, newState, affected);
+      }
+    }
+  }
+  return affected;
+};
+export default (tree, state, newState) => recursive(tree, state, newState, [])

package/conditionals.js ADDED Viewed

@@ -0,0 +1,182 @@
+import parse from './parse.js';
+import affected from './affected.js';
+import hydrate from './hydrate.js';
+import { createScopedState, renderAllIterations, initializeBlock } from './iterate.js';
+// Evaluate conditional expression in state context
+const evaluateCondition = (expression, state) => {
+  try {
+    const keys = Object.keys(state);
+    const values = Object.values(state);
+    // Create a function with state keys as parameters and evaluate the expression
+    const result = new Function(...keys, `'use strict'; return !!(${expression})`)(...values);
+    return !!result; // Coerce to boolean
+  } catch (e) {
+    console.warn(`Error evaluating condition "${expression}":`, e);
+    return false; // Default to false on error
+  }
+};
+// Extract state dependencies from an expression
+// e.g., "count > 5" → ["count"]
+// e.g., "isLoggedIn && isAdmin" → ["isLoggedIn", "isAdmin"]
+export const extractDependencies = (expression) => {
+  const regex = /\b([a-zA-Z_$][a-zA-Z0-9_$]*)\b/g;
+  const matches = [];
+  let match;
+  while ((match = regex.exec(expression))) {
+    const identifier = match[1];
+    // Filter out JavaScript keywords and common literals
+    if (!['true', 'false', 'null', 'undefined', 'this', 'return'].includes(identifier)) {
+      matches.push(identifier);
+    }
+  }
+  return [...new Set(matches)]; // Unique values
+};
+// Render all conditionals in the parsed tree
+export const renderAllConditionals = (tree, state, linkList, parentScope = {}) => {
+  // If this is a conditional node, render it
+  if (tree.type === 'conditional') {
+    renderConditional(tree, state, linkList, parentScope);
+    return;
+  }
+  // Recursively render conditionals in child nodes
+  if (tree.children) {
+    Object.keys(tree.children).forEach(key => {
+      const child = tree.children[key];
+      if (typeof child === 'object' && child !== null) {
+        renderAllConditionals(child, state, linkList, parentScope);
+      }
+    });
+  }
+};
+// Initial render of a conditional block
+export const renderConditional = (node, state, linkList, parentScope = {}) => {
+  const { expression, startComment, endComment, branches } = node.meta;
+  // Remove original template nodes from DOM (between start and end comments)
+  // Only do this on first render (when activeBranch is undefined)
+  if (node.runtime.activeBranch === undefined) {
+    let currentNode = startComment.nextSibling;
+    while (currentNode && currentNode !== endComment) {
+      const nextNode = currentNode.nextSibling;
+      if (currentNode.parentNode) {
+        currentNode.parentNode.removeChild(currentNode);
+      }
+      currentNode = nextNode;
+    }
+    // Mark that template has been removed
+    node.runtime.templateRemoved = true;
+  }
+  // Evaluate condition with current state
+  const conditionResult = evaluateCondition(expression, state);
+  // Determine which branch to mount
+  const branchToMount = conditionResult ? branches.if : branches.else;
+  // Mount the appropriate branch
+  mountBranch(node, branchToMount, state, linkList, parentScope);
+  // Store active branch reference
+  node.runtime.activeBranch = branchToMount;
+};
+// Mount a specific branch
+const mountBranch = (node, branchData, state, linkList, parentScope) => {
+  const { startComment, endComment } = node.meta;
+  // If branch doesn't exist (no else clause), just unmount current
+  if (!branchData) {
+    unmountBranch(node);
+    return;
+  }
+  // Unmount current branch first (if any)
+  unmountBranch(node);
+  // Clone the template element
+  const templateContent = branchData.element.childNodes;
+  const parent = startComment.parentNode;
+  // Create scoped state (with parent scope if inside iteration)
+  const scopedState = Object.keys(parentScope).length > 0
+    ? createScopedState(state, parentScope)
+    : state;
+  // Initialize block (clone, parse, hydrate)
+  const { element: firstElement, tree: branchTree, clonedNodes } = initializeBlock(templateContent, scopedState);
+  // Insert cloned nodes into DOM
+  clonedNodes.forEach(clonedNode => parent.insertBefore(clonedNode, endComment));
+  // Recursively render any nested iterations and conditionals
+  if (branchTree) {
+    renderAllIterations(branchTree, scopedState, linkList);
+    renderAllConditionals(branchTree, scopedState, linkList, parentScope);
+  }
+  // Store active instance
+  node.runtime.activeInstance = {
+    branch: branchData,
+    nodes: clonedNodes,
+    parsedTree: branchTree
+  };
+};
+// Unmount currently active branch
+const unmountBranch = (node) => {
+  const { activeInstance } = node.runtime;
+  if (!activeInstance) return;
+  // Remove all nodes from DOM
+  activeInstance.nodes.forEach(domNode => {
+    if (domNode.parentNode) {
+      domNode.parentNode.removeChild(domNode);
+    }
+  });
+  // Clear active instance
+  node.runtime.activeInstance = null;
+};
+// Update conditional when dependencies change
+export const updateConditional = (node, newState, oldState, linkList, parentScope = {}) => {
+  const { expression, branches } = node.meta;
+  // If not yet rendered, skip (renderConditional handles initial render)
+  if (!node.runtime.templateRemoved) {
+    return;
+  }
+  // Evaluate expression with new state
+  const newConditionResult = evaluateCondition(expression, newState);
+  const newBranchData = newConditionResult ? branches.if : branches.else;
+  // Check if branch changed (compare references)
+  const branchChanged = node.runtime.activeBranch !== newBranchData;
+  if (branchChanged) {
+    // Switch branches
+    mountBranch(node, newBranchData, newState, linkList, parentScope);
+    node.runtime.activeBranch = newBranchData;
+  } else {
+    // Same branch, but state might have changed - rehydrate
+    const { activeInstance } = node.runtime;
+    if (activeInstance && activeInstance.parsedTree) {
+      const scopedState = Object.keys(parentScope).length > 0
+        ? createScopedState(newState, parentScope)
+        : newState;
+      const affectedElements = affected(activeInstance.parsedTree, oldState, scopedState);
+      hydrate(affectedElements, scopedState);
+    }
+  }
+};