@ape-egg/vibe 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.3.2] - 2025-02-06
+
+### Fixed
+
+- **Package completeness**: Added missing `boot.js` to npm package
+  - File was missing from the "files" allowlist in package.json
+
+### Changed
+
+- **Package strategy**: Switched from allowlist to denylist approach
+  - Removed "files" field from package.json
+  - Added `.npmignore` to exclude build artifacts (`target/`) and dev files
+  - Ensures all source files are included without manual maintenance
+
+---
+
+## [1.3.1] - 2025-02-06
+
+### Fixed
+
+- **Package exports**: Added missing `./component` export to package.json
+  - Enables proper import: `import component from '@ape-egg/vibe/component'`
+  - Previously `component.js` was included in package files but not exposed via exports field
+
+---
+
 ## [1.3.0] - 2025-02-06
 
 ### Added

package/ROADMAP.md

@@ -0,0 +1,289 @@
+# Vibe Roadmap
+
+Feature proposals and improvements for Vibe's runtime-first reactive framework.
+
+---
+
+## Proposed: Manual Hydration API
+
+**Status**: Proposal
+**Priority**: Medium
+**Category**: Core Runtime
+
+### Problem
+
+Vibe's MutationObserver automatically hydrates `@[bindings]` on initial page load and incremental DOM changes, but fails when developers perform wholesale DOM replacement via `innerHTML`:
+
+```js
+// This doesn't trigger Vibe's hydration:
+element.innerHTML = '<h1>Welcome, @[race]!</h1>';
+// Result: Literal text "@[race]" instead of evaluated "human"
+```
+
+This happens because:
+1. `innerHTML` replacement destroys all old DOM nodes and creates new ones
+2. Vibe's MutationObserver is designed for incremental mutations, not complete replacement
+3. No mechanism exists to manually trigger re-hydration
+
+### Current Workaround
+
+Users must manually evaluate bindings before setting innerHTML:
+
+```js
+const evaluateBindings = (html) => {
+  return html.replace(/@\[([^\]]+)\]/g, (match, expression) => {
+    const keys = Object.keys(window.$);
+    const values = Object.values(window.$);
+    const result = new Function(...keys, `return ${expression}`)(...values);
+    return result ?? '';
+  });
+};
+
+element.innerHTML = evaluateBindings(html); // Manually evaluated
+```
+
+**Issues with this approach:**
+- Not DRY - duplicates Vibe's internal evaluation logic
+- Fragile - user's regex might not match Vibe's parser exactly
+- Knowledge burden - users need to know when manual evaluation is needed
+- Inconsistent - some bindings auto-hydrate, others need manual work
+
+### Use Cases
+
+This affects multiple real-world scenarios:
+
+1. **Dynamic content replacement** (tutorials, articles, modals)
+2. **Client-side routing** (replacing page sections with new HTML)
+3. **Lazy-loaded sections** (loading HTML from server with bindings)
+4. **Template cloning** (using `<template>` elements with `@[bindings]`)
+5. **Server-sent HTML** (SSR-like patterns where server sends HTML with bindings)
+
+### Proposed Solution
+
+Add a manual hydration API that allows users to trigger Vibe's binding evaluation:
+
+#### Option 1: Element Hydration
+```js
+vibe.hydrate(element);
+```
+
+**Usage:**
+```js
+tutorial.innerHTML = '<h1>Welcome, @[race]!</h1>';
+vibe.hydrate(tutorial); // Scan tutorial and children for @[bindings]
+```
+
+**Pros:**
+- Most flexible - works with any element
+- Matches web component patterns (`connectedCallback()`)
+- Clear intent - "scan this element"
+
+**Cons:**
+- Requires import/reference to vibe library
+- Two-step process (set innerHTML, then hydrate)
+
+#### Option 2: HTML String Evaluation
+```js
+const evaluated = vibe.evaluate(html, state);
+```
+
+**Usage:**
+```js
+const html = '<h1>Welcome, @[race]!</h1>';
+const evaluated = vibe.evaluate(html, window.$);
+tutorial.innerHTML = evaluated;
+```
+
+**Pros:**
+- Pure function - easier to test
+- Works without DOM access
+- Can be used server-side or in workers
+
+**Cons:**
+- Users must manage state passing
+- Doesn't handle nested/dynamic state updates
+
+#### Option 3: Safe innerHTML Setter
+```js
+vibe.setHTML(element, html);
+```
+
+**Usage:**
+```js
+vibe.setHTML(tutorial, '<h1>Welcome, @[race]!</h1>');
+```
+
+**Pros:**
+- Single operation - set and hydrate in one call
+- Matches platform APIs (`element.setHTML()`)
+- Simplest API surface
+
+**Cons:**
+- Yet another setter abstraction
+- Might conflict with future platform APIs
+
+### Recommendation
+
+**Implement Option 1** (`vibe.hydrate(element)`):
+- Aligns with Vibe's runtime-first philosophy
+- Gives users explicit control over hydration timing
+- Most flexible for different scenarios
+- Clear and predictable behavior
+
+### Implementation Notes
+
+```js
+// Expose on the state proxy:
+window.$ = state({ race: 'human' });
+window.$.vibe.hydrate(element); // Scan element for @[bindings]
+
+// Or as a module export:
+import state, { hydrate } from '@ape-egg/vibe';
+hydrate(element);
+```
+
+Should support:
+- Single element: `hydrate(tutorial)`
+- Multiple elements: `hydrate([el1, el2])`
+- Selector: `hydrate('tutorial')` (convenience)
+
+### Related
+
+Compare to other frameworks:
+- **Alpine.js**: `Alpine.initTree(el)` - manual initialization
+- **Vue**: `app.mount(el)` - mount to element
+- **Svelte**: Compiler handles this at build time
+- **HTMX**: `htmx.process(el)` - process element for attributes
+
+---
+
+## Known Issues
+
+### innerHTML Replacement Corrupts Conditional Branches in Iterations
+
+**Status**: Bug
+**Priority**: Low (edge case)
+**Category**: Core Runtime
+**Discovered**: 2026-01-25
+
+#### Problem
+
+When a parent element containing iterations with nested conditionals has its `innerHTML` replaced multiple times with identical HTML, the conditional's `else` branches become `null` after 2-3 replacements. This causes conditionals to fail rendering.
+
+**Root cause:**
+1. Iteration template's `branches` object is shared across all iteration instances (iterate.js:65: `branches, // Branch templates are reused`)
+2. When `innerHTML` replacement happens, something mutates the shared `branches.else` to `null`
+3. All instances reference the same corrupted branches object
+4. Subsequent renders have no `else` branch template to mount
+
+#### Reproduction
+
+Programmatic test case:
+
+```js
+// HTML structure
+const html = `
+  <item-list>
+    <!-- each items as item, i -->
+    <item-card>
+      <span>@[item]</span>
+      <!-- if i % 2 === 0 -->
+      <badge>Even</badge>
+      <!-- else -->
+      <badge secondary>Odd</badge>
+      <!-- /if -->
+    </item-card>
+    <!-- /each -->
+  </item-list>
+`;
+
+// State
+window.$ = state({ items: ['Apple', 'Banana', 'Cherry'] });
+
+// Trigger the bug
+const container = document.querySelector('[vibe]');
+
+// First replacement: works
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Second replacement: works
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Third replacement: branches.else becomes NULL
+container.innerHTML = html;
+await new Promise(r => setTimeout(r, 100));
+
+// Result: Even/Odd badges fail to render in the third iteration
+```
+
+#### Observations
+
+1. Cloning `branches` object during iteration (shallow copy) doesn't prevent the bug
+2. The mutation happens BEFORE cloning, meaning the original template is corrupted
+3. Setting a property trap on `branches.else` doesn't catch the mutation (already null when accessed)
+4. Only affects conditionals inside iterations - standalone conditionals work fine
+5. Only triggers with multiple innerHTML replacements - single replacement works
+
+#### Affected Patterns
+
+This bug only affects:
+- Replacing innerHTML multiple times with identical HTML containing iterations + conditionals
+- Demo infrastructure like tutorial.js that re-renders on state changes
+- Not representative of typical usage patterns
+
+Does NOT affect:
+- Normal reactivity (state changes)
+- Single innerHTML replacement
+- Iterations without conditionals
+- Conditionals outside iterations
+- Incremental DOM mutations (appendChild, insertBefore, etc.)
+
+#### Workaround
+
+Avoid multiple innerHTML replacements on parents containing iteration+conditional templates. Instead:
+1. Use incremental DOM APIs (appendChild, createElement)
+2. Replace innerHTML once at initialization only
+3. Use Vibe's normal reactivity for updates
+4. Don't wrap demo content in `<tutorial>` that re-renders via innerHTML
+
+#### Investigation Log
+
+Debugging attempts (2026-01-25):
+- ✓ Confirmed `branches.else` becomes `null` after 3rd innerHTML replacement
+- ✓ Added deep cloning of branches object - didn't help (already null before clone)
+- ✓ Added Object.defineProperty trap - didn't fire (already null)
+- ✓ Checked parsing logic - correctly finds else comments
+- ✗ Unable to identify where mutation occurs
+- ✗ Unable to reproduce with simpler test case (needs tutorial.js pattern)
+
+Likely related to:
+- MutationObserver's removedNodes callback cleaning up references
+- Template caching/reuse strategy in iterate.js
+- Interaction between parse → clone → hydrate → render cycle
+
+#### Resolution Path
+
+**Phase 1 (Current)**: Document and work around
+- Remove `<tutorial>` wrapper from demos
+- Add note in CLAUDE.md about limitation
+- Tests validate core reactivity works correctly
+
+**Phase 2+**: Consider fixing if real-world need emerges
+- Deep investigation into branch reference lifecycle
+- Possibly: deep clone branches instead of sharing reference
+- Possibly: rebuild conditional metadata on each innerHTML replacement
+- Possibly: manual hydration API (see "Manual Hydration API" proposal above)
+
+This is acceptable technical debt since:
+1. Edge case not representative of normal usage
+2. Core reactivity (the 99% case) works correctly
+3. Can be addressed when/if users report needing this pattern
+4. Phase 1 goals (iteration + conditionals) are met
+
+---
+
+## Future Proposals
+
+*This section reserved for additional feature proposals*

package/boot.js

@@ -0,0 +1,46 @@
+// Shared boot mechanism for vibe
+// Used by both index.js (global state) and component.js (component state)
+
+import main from './runtime/index.js';
+
+let bootQueued = false;
+let booted = false;
+
+export const ensureBoot = () => {
+  if (booted || bootQueued) return;
+  bootQueued = true;
+
+  // Auto-boot in next microtask if no explicit boot
+  queueMicrotask(() => {
+    if (!booted) {
+      boot();
+    }
+  });
+};
+
+export const boot = () => {
+  if (booted) {
+    return window.$;
+  }
+  booted = true;
+
+  // Merge all state: global + components
+  const globalState = window.__vibeGlobalState || {};
+  const componentStates = window.__vibeComponents || {};
+
+  const mergedState = {
+    ...globalState,
+    ...componentStates,
+  };
+
+  // Get config and targetSelector (first caller wins)
+  const config = window.__vibeConfig || {};
+  const targetSelector = window.__vibeTargetSelector || '';
+
+  // Boot with merged state
+  window.$ = main(mergedState, config, targetSelector);
+
+  return window.$;
+};
+
+export const isBooted = () => booted;

package/component.js

@@ -0,0 +1,59 @@
+// Component state entry point
+// Usage:
+//   <component>
+//     <script type="module">
+//       import component from 'vibe/component.js';
+//       component({ count: 0 }, { debug: false }, 'body');
+//     </script>
+//     <div>@[this.count]</div>
+//   </component>
+//
+// Or with class:
+//   <div class="component">...</div>
+
+import { generateComponentId } from './runtime/component-state.js';
+import { ensureBoot } from './boot.js';
+
+const component = (state = {}, config, targetSelector) => {
+  // Find the first unprocessed INLINE component wrapper
+  // Skip <component src=""> (fetched components) - they don't need state tagging
+  // Scripts execute in DOM order, so we claim wrappers in DOM order too
+  // Supports: <component> or <div class="component">
+  const allWrappers = Array.from(document.querySelectorAll('component:not([src]), div.component:not([src])'));
+  const wrapper = allWrappers.find(el => !el.hasAttribute('data-vibe-component-id'));
+
+  if (!wrapper) {
+    console.warn('[vibe] component() must be called inside <component> or <div class="component">');
+    return;
+  }
+
+  // Generate unique component ID
+  const componentId = generateComponentId();
+
+  // Tag only the wrapper element
+  // All descendants will find it via element.closest('[data-vibe-component-id]')
+  wrapper.setAttribute('data-vibe-component-id', componentId);
+
+  // Register component state in shared registry
+  if (!window.__vibeComponents) {
+    window.__vibeComponents = {};
+  }
+  window.__vibeComponents[componentId] = state;
+
+  // Store config (first caller wins)
+  if (config && !window.__vibeConfig) {
+    window.__vibeConfig = config;
+  }
+
+  // Store targetSelector (first caller wins)
+  if (targetSelector && !window.__vibeTargetSelector) {
+    window.__vibeTargetSelector = targetSelector;
+  }
+
+  // Ensure boot happens
+  ensureBoot();
+
+  return componentId;
+};
+
+export default component;

package/llms.txt

@@ -0,0 +1,304 @@
+# Vibe - Complete Documentation
+
+> Runtime-first reactivity. No virtual DOM. No build step.
+
+## Overview
+
+Vibe is a lightweight reactive library that uses Proxy-based state and MutationObserver for fine-grained DOM updates. It works directly in the browser with zero compilation required.
+
+**Key characteristics:**
+- Proxy-based reactive state (`window.$`)
+- Deep reactivity (nested mutations automatically trigger updates)
+- Surgical DOM updates (only affected elements re-render)
+- MutationObserver for dynamic element tracking
+- Works with vanilla HTML - no special file format
+
+## Installation
+
+```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>
+```
+
+## Core Syntax
+
+### Reactive Bindings
+
+Use `@[property]` syntax anywhere in HTML or CSS:
+
+```html
+<!-- Text content -->
+<div>@[firstName]</div>
+
+<!-- Expressions -->
+<div>@[firstName + ' ' + lastName]</div>
+<div>@[count * 2]</div>
+
+<!-- Attributes -->
+<input value="@[inputValue]">
+<button disabled="@[isLoading]">Submit</button>
+
+<!-- CSS -->
+<style>
+  .box { background: @[themeColor]; }
+</style>
+```
+
+⚠️ **Important**: Bindings are evaluated using `new Function()`. Do not bind untrusted user input.
+
+### State Access
+
+State is accessed globally via `window.$`:
+
+```javascript
+// Read
+console.log($.firstName);
+
+// Write (triggers re-render)
+$.firstName = "John";
+
+// Increment
+$.count++;
+
+// Deep mutations (also trigger re-render)
+$.user.profile.name = "Alice";
+$.todos[2].completed = true;
+$.config.theme.colors.primary = "#007bff";
+```
+
+Vibe uses recursive proxies to detect changes at any nesting level automatically.
+
+## Control Flow
+
+### Iteration
+
+```html
+<!-- each items as item -->
+  <li>@[item]</li>
+<!-- /each -->
+```
+
+With index:
+
+```html
+<!-- each items as item, index -->
+  <li>@[index]: @[item]</li>
+<!-- /each -->
+```
+
+### Nested Iteration
+
+Use dot paths for nested arrays:
+
+```html
+<!-- each categories as category -->
+  <h2>@[category.name]</h2>
+  <!-- each category.items as item -->
+    <span>@[item.name]</span>
+  <!-- /each -->
+<!-- /each -->
+```
+
+### Conditionals
+
+```html
+<!-- if isLoggedIn -->
+  <span>Welcome, @[username]!</span>
+<!-- else -->
+  <span>Please log in</span>
+<!-- /if -->
+```
+
+Conditionals can be nested inside iterations and vice versa.
+
+## Special Attributes
+
+### Dehydrate
+
+Skip reactive processing for an element and its children:
+
+```html
+<code dehydrate>@[this] displays literally, not parsed</code>
+```
+
+Use cases:
+- Displaying `@[...]` syntax in documentation
+- Static content that shouldn't be reactive
+- Performance optimization for large static sections
+
+### Boolean Attributes
+
+Attributes not in the value whitelist are removed when falsy:
+
+```html
+<button disabled="@[isLoading]">Submit</button>
+<!-- When isLoading is false, disabled attribute is removed entirely -->
+```
+
+## Events
+
+Use standard inline event handlers:
+
+```html
+<button onclick="$.count++">Increment</button>
+<input oninput="$.text = this.value">
+<form onsubmit="event.preventDefault(); handleSubmit()">
+```
+
+## Styling
+
+### CSS Bindings
+
+Reactive values work inside `<style>` tags:
+
+```html
+<style>
+  .box {
+    background: @[backgroundColor];
+    color: @[textColor];
+    width: @[width]px;
+  }
+</style>
+```
+
+### Preventing 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-fouc>
+```
+
+## Dynamic Elements
+
+Elements added via JavaScript are automatically hydrated through MutationObserver:
+
+```javascript
+const div = document.createElement('div');
+div.innerHTML = '<span>Hello, @[name]!</span>';
+document.body.appendChild(div);
+// Automatically becomes reactive
+```
+
+## API Reference
+
+### `state(initialState, afterUpdate?)`
+
+Creates reactive state and initializes the framework.
+
+```javascript
+import state from "@ape-egg/vibe";
+
+window.$ = state(
+  { count: 0, user: { name: "Alice" } },
+  (newState, oldState) => {
+    console.log("State updated:", newState);
+  }
+);
+```
+
+**Parameters:**
+- `initialState` - Object containing initial state values
+- `afterUpdate` - Optional callback after each state change (receives read-only snapshots)
+
+**Returns:** Proxy object for reactive state access
+
+## Scoped Variables
+
+Inside `<!-- each -->` blocks, these variables are available:
+- `item` (or custom name) - current array element
+- `index` (or custom name) - current index
+- Parent state remains accessible via `$`
+
+```html
+<!-- each users as user, i -->
+  <div>@[i]: @[user.name] (total: @[users.length])</div>
+<!-- /each -->
+```
+
+### Scoped State (Internal)
+
+Each iteration instance stores a `scopedState` - a Proxy wrapper that provides access to both local variables (`item`, `index`) and global state. This enables reactive updates inside iterations:
+
+```html
+<!-- each menuItems as item -->
+  <a completed="@[tutorialProgress[item.id]]">
+    @[item.label]
+  </a>
+<!-- /each -->
+```
+
+When `tutorialProgress` changes, Vibe:
+1. Finds affected elements inside iteration instances
+2. Uses that instance's `scopedState` for evaluation
+3. Can access both `item` (local) and `tutorialProgress` (global)
+4. Updates only the affected elements without re-rendering the entire iteration
+
+## Architecture
+
+Vibe consists of these core modules:
+
+- **state.js** - Proxy-based reactive state container with recursive proxies for deep reactivity
+- **parse.js** - DOM parser that finds `@[...]` bindings
+- **link.js** - Maps elements to parsed tree nodes
+- **hydrate.js** - Updates DOM with current state values (supports scoped state for iterations)
+- **affected.js** - Determines which elements need updating (walks iteration instances with scoped state)
+- **iterate.js** - Array rendering with efficient diffing (stores scoped state per instance)
+- **conditionals.js** - Conditional block rendering
+
+## How It Works
+
+```
+1. state() initializes the Proxy and framework
+2. parse.js scans DOM for @[...], <!-- each -->, <!-- if -->
+3. link.js maps elements to the parsed tree
+4. hydrate.js replaces bindings with values
+5. iterate.js renders <!-- each --> loops
+6. conditionals.js renders <!-- if --> blocks
+7. MutationObserver watches for new elements
+8. On state change: affected.js finds changed elements → hydrate.js updates them
+```
+
+## Current Limitations
+
+- **No computed values**: Derived state must be calculated manually
+- **No two-way binding sugar**: Must wire input events manually
+- **Expression security**: `new Function()` evaluation - don't bind untrusted input
+
+## Best Practices
+
+1. **Initialize state before DOM**: Place `<script>` in `<head>` or before reactive elements
+2. **Use dehydrate for docs**: When showing `@[...]` syntax examples
+3. **Prevent FOUC**: Use `visibility: hidden` on body until hydration
+4. **Keep expressions simple**: Complex logic belongs in JavaScript, not templates
+5. **Mutate freely**: Deep reactivity means `$.user.name = "New"` just works - no spread operators needed
+
+## Browser Support
+
+Modern browsers with:
+- Proxy (ES6)
+- MutationObserver
+- ES Modules
+
+## Resources
+
+- **Homepage**: https://vibe.korte.kim
+- **npm**: https://www.npmjs.com/package/@ape-egg/vibe

package/package.json

@@ -1,33 +1,19 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",
   "homepage": "https://vibe.korte.kim",
   "exports": {
     ".": "./index.js",
+    "./component": "./component.js",
     "./runtime": "./runtime/index.js",
     "./compiler": "./compiler/bin/vibe-compile.js"
   },
   "bin": {
     "vibe": "./compiler/bin/vibe-compile.js"
   },
-  "files": [
-    "index.js",
-    "vibe.css",
-    "runtime/",
-    "compiler/bin/",
-    "compiler/native/",
-    "compiler/src/Cargo.lock",
-    "compiler/src/Cargo.toml",
-    "compiler/src/compiler/",
-    "compiler/src/config.rs",
-    "compiler/src/main.rs",
-    "compiler/src/parser/",
-    "README.md",
-    "CHANGELOG.md"
-  ],
   "keywords": [
     "reactive",
     "framework",