@ape-egg/vibe 1.3.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # Changelog
 
+## [1.6.0] - 2026-02-12
+
+### Added
+
+- **Watch mode** - Compiler now supports file watching with incremental compilation
+  - New `--watch` flag monitors source files for changes and automatically recompiles
+  - Intelligent change detection tracks affected files and their dependencies
+  - Transitive dependency tracking: changes to components trigger recompilation of pages using them
+  - Blacklist support: watch mode respects SKIP_FILES patterns (tests/, node_modules/, etc.)
+  - Debounced file events (300ms) prevent excessive compilation during rapid changes
+  - Outputs only changed files for fast incremental builds
+  - First compile shows full output, subsequent compiles show only deltas
+- **Reserved element validation** - Compiler now prevents component naming conflicts
+  - New `reservedElements` config option (replaces `excludeTags`)
+  - Defaults to all HTML5 elements plus "component" keyword
+  - User-provided values append to defaults (not replace)
+  - Case-sensitive validation: `nav.html` → Error, `Nav.html` → OK
+  - Compile-time error with clear message showing conflicting filename
+  - Prevents runtime confusion between HTML elements and custom components
+- **Component path case-sensitivity** - Component paths are now treated as case-sensitive
+  - `<component src="path/to/MyComponent.html">` and `<component src="path/to/mycomponent.html">` are different
+  - Both runtime and compiler preserve exact case in paths
+  - Cache keys include full case-sensitive path
+  - Enables PascalCase naming convention for components while supporting any casing
+
+### Changed
+
+- **Component inlining architecture** - Complete rewrite from iterative to recursive fetching
+  - Removed MAX_ITERATIONS constant and loop-based approach
+  - `fetch_component_recursive()` now returns fully resolved content with all nested components inlined
+  - Components are cached only after being fully resolved (prevents incomplete content in cache)
+  - `inline_component_elements()` now does single pass (no loops)
+  - Significant performance improvement: sub-100ms compilation for complex nested components
+- **Framework element handling** - `<component>` is now recognized as a framework element
+  - Never transformed to `<div>` regardless of `--elements-as-is` flag
+  - Custom elements (e.g., `<card>`, `<text>`) are transformed when `elements_as_is: false`
+  - Framework elements vs custom elements properly distinguished in compiler
+  - Wrapper `<component>` tags remain after inlining (expected by runtime)
+- **Component inlining behavior** - Custom elements are always inlined
+  - `<card>` → transformed to `<component>` → inlined even with `--components-as-is`
+  - `--components-as-is` only affects explicit `<component src="...">` tags
+  - Consistent behavior: custom elements compile away, framework elements remain
+- **Path normalization** - Component paths now consistently normalized
+  - All paths start with `/` (unless external URL)
+  - Cache uses normalized paths to prevent duplicates (`/components/nav.html` vs `./components/nav.html`)
+  - Fixes cache pollution from different path formats for same component
+- **Config naming** - `excludeTags` renamed to `reservedElements` throughout codebase
+  - Better describes purpose (reserved from use as component names)
+  - Updated in Rust compiler, config files, and documentation
+  - Backward compatible: old config key still works but deprecated
+
+### Fixed
+
+- Watch mode was compiling blacklisted files (tests/, node_modules/)
+- Component inlining created infinite nested wrappers (100+ levels)
+- Empty headlines in tests due to broken external component fetching
+- Path case normalization could cause duplicates in component cache
+- Accessibility transformation incorrectly converting `<component>` to divs
+- Test expectations mismatched actual framework element behavior
+
+### Performance
+
+- Watch mode incremental compilation: ~100ms for typical changes
+- First full compilation: ~300-500ms
+- Component fetching: recursive approach 10x faster than iterative (no MAX_ITERATIONS overhead)
+- Path normalization prevents redundant fetches of same component
+
+---
+
+## [1.5.0] - 2026-02-09
+
+### Added
+
+- **Nested iteration compilation** - Compiler now handles infinitely nested `<!-- each -->` blocks
+  - Recursive processing in `iteration_optimizer.rs` with depth counting for comment pair matching
+  - Nested loops compile to IIFEs (Immediately Invoked Function Expressions) with template literals
+  - Inner iterations inlined directly into outer batch functions for optimal performance
+  - Example: `<!-- each categories as cat --><!-- each cat.items as item -->` compiles to single optimized function
+- **QuickJS JavaScript runtime** - Full expression evaluation at compile time
+  - Embedded QuickJS engine (`rquickjs = "0.6"`) for JavaScript evaluation in Rust
+  - No external dependencies - increases binary size by ~1-2MB
+  - Evaluates any JavaScript expression: `@[categories.length]`, `@[items[0]]`, `@[user.name.toUpperCase()]`
+  - State set in global scope: `Object.assign(globalThis, $)` matches Vibe runtime behavior
+  - Fast evaluation: ~160ms overhead for 35 files (~5ms per file)
+- **Complete pre-rendering** - Zero FOUC with all bindings pre-rendered for SEO
+  - All `@[expression]` bindings evaluated and stamped into HTML at compile time
+  - Handles property access (`@[user.name]`), array methods (`@[categories.length]`), and complex expressions
+  - Nested iterations fully pre-rendered with merged state for each iteration context
+  - Falls back gracefully: undefined expressions left as `@[...]` for runtime hydration
+  - New test: `stamp_array_length` validates `.length` property evaluation
+
+### Changed
+
+- **Value stamper rewrite** (`value_stamper.rs`) - Complete overhaul to use QuickJS
+  - Replaced JSON path resolution with JavaScript expression evaluation
+  - `eval_expression()` handles any valid JavaScript with state in scope
+  - `eval_array_path()` evaluates array paths for iteration rendering
+  - Iteration rendering creates merged state (parent + item + index) for nested context
+  - Removed manual property traversal code - JavaScript engine handles it all
+- **Compiled iteration updates** - Always use compiled path when available (`iterate.js:364`)
+  - Previously only used compiled updates for edge cases (empty↔full, large arrays >100)
+  - Now uses compiled batch functions for ALL updates when manifest has `compiled.iterations.batchFn`
+  - Fixes issue where small array updates (3→4 items) fell through to incompatible runtime path
+  - Ensures consistent performance regardless of array size or transition type
+- **State extraction improvements** (`state_extractor.rs`) - Better error handling
+  - Silently skips unparseable state objects instead of failing compilation
+  - Enables graceful degradation when state contains functions or complex expressions
+
+### Fixed
+
+- Compiled iterations not updating when array size changes (e.g., add/remove items)
+- Pre-rendering skipped for JavaScript expressions like `@[categories.length]`
+- Nested iteration values showing as `@[item]` instead of actual data
+- Runtime path attempting to handle compiled iterations incorrectly
+
+### Performance
+
+- Pre-rendering adds ~160ms to compilation for 35 files (~435ms total, up from ~310ms)
+- QuickJS evaluation: ~1-5ms per binding
+- Compiled nested iterations: Same performance as shallow iterations (no recursion overhead at runtime)
+- Zero runtime cost for pre-rendered bindings - HTML arrives with values already stamped
+
+---
+
+## [1.4.0] - 2026-02-09
+
+### Added
+
+- **Iteration optimization** - Compiler now generates optimized batch functions for `<!-- each -->` loops
+  - New `iteration_optimizer.rs` module generates string-based batch render functions
+  - Provides 2-3x performance improvement for iteration rendering (15-17ms vs 40ms for 1000 rows)
+  - Only applies to shallow iterations (nested iterations still use runtime path)
+  - Compiled batch functions are stored in manifest and executed at runtime
+- **Pre-compiled iterations runtime** (`runtime/pre-compiled-iterations.js`)
+  - Production implementation of compiled iteration rendering
+  - Uses pre-compiled batch functions from manifest generated at build time
+  - Based on the prototype in `_vibe-compiled-iteration-batch.js`
+  - Automatically falls back to runtime rendering for nested iterations or missing batch functions
+- **Compiler configuration** - New `iterationsAsIs` flag
+  - Set to `true` in `vibe-compiler` config to skip iteration optimization
+  - Iterations pass through unchanged and are handled entirely by runtime
+  - Default: `false` (iterations are optimized)
+- **Hyperspeed benchmark** - New benchmark page for measuring pre-compiled performance
+  - Tests iteration optimization with 1000 rows
+  - Compares runtime vs compiled iteration rendering
+  - Available at `e2e-runtime/hyperspeed-benchmark.html`
+- **Compiler test coverage** for iteration compilation
+  - `tests/compiler/iterations/` - Tests iteration optimization is applied
+  - `tests/compiler/iterations-as-is/` - Tests `iterationsAsIs` flag skips optimization
+  - E2E tests verify compiled iterations render correctly
+
+### Changed
+
+- **Renamed `runtime/hyperspeed.js` → `runtime/pre-compiled-manifest.js`**
+  - Better naming to reflect that it handles all pre-compiled features, not just "hyperspeed"
+  - Updated all imports and references throughout codebase
+- **Enhanced manifest merging** - Compiler manifest now preserves compiled iteration data
+  - Iteration nodes retain `compiled.iterations.batchFn` from manifest during runtime merge
+  - Prevents compiled data from being discarded when merging with runtime tree
+- **Debug logging improvements**
+  - Added manifest filename to debug output ("Loaded index.manifest.js, page is pre-compiled")
+  - Shows compiled feature count (e.g., "3 iterations optimized")
+  - Better visibility into which optimizations are active
+- **Runtime iteration handling** - Iterations check for compiled batch functions before falling back
+  - `canUseCompiled()` determines if iteration can use batch function
+  - Falls back to runtime rendering for nested structures or missing compiled data
+  - Seamless integration between compiled and runtime paths
+
+### Fixed
+
+- Runtime cleanup now properly handles compiled iteration nodes
+- Manifest merge no longer discards compiled data from iteration nodes
+- Debug logging visibility flag now correctly propagates through manifest loading
+- Iteration restoration respects compiled batch functions
+
+---
+
+## [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/README.md

@@ -124,6 +124,103 @@ Skip reactive processing for an element:
 <code dehydrate>@[this] displays literally</code>
 ```
 
+### Reserved Words & Gotchas
+
+Vibe uses specific patterns and keywords that have special meaning. Avoid using these for other purposes to prevent unexpected behavior:
+
+#### Classes & Attributes
+
+- **`vibe-fouc`** — Class or attribute for FOUC (Flash of Unstyled Content) prevention. Automatically removed after hydration completes.
+  ```html
+  <body vibe-fouc>  <!-- or class="vibe-fouc" -->
+  ```
+
+- **`vibe-dehydrate`** — Class or attribute to skip reactive processing. Useful for displaying literal `@[...]` syntax in documentation.
+  ```html
+  <code vibe-dehydrate>@[variable]</code>  <!-- or class="vibe-dehydrate" -->
+  ```
+
+#### Element Names & Classes
+
+- **`<component>`** — Element name for component system. Used with `src` attribute for runtime component loading, or as a wrapper for inlined components.
+  ```html
+  <component src="/path/to/component.html"></component>
+  ```
+
+- **`class="component"`** — Alternative syntax for components using standard HTML elements. Useful for HTML validation or accessibility.
+  ```html
+  <div class="component" src="/path/to/component.html"></div>
+  ```
+
+- **`<slot>`** — Element name for component content injection. Gets replaced with content passed between component tags.
+  ```html
+  <!-- In component file -->
+  <slot></slot>
+
+  <!-- Usage -->
+  <component src="...">
+    <p>This replaces the slot</p>
+  </component>
+  ```
+
+#### Comment Syntax
+
+- **`<!-- each -->`** / **`<!-- /each -->`** — Iteration block markers.
+  ```html
+  <!-- each items as item -->
+  <!-- /each -->
+  ```
+
+- **`<!-- if -->`** / **`<!-- else -->`** / **`<!-- /if -->`** — Conditional block markers.
+  ```html
+  <!-- if condition -->
+  <!-- else -->
+  <!-- /if -->
+  ```
+
+#### Binding Syntax
+
+- **`@[...]`** — Reactive binding syntax. Reserved for state references.
+  ```html
+  <div>@[variable]</div>
+  ```
+
+#### Global Properties
+
+- **`window.$`** — Global reactive state object. All reactive data should be accessed through this.
+  ```javascript
+  window.$ = state({ count: 0 });
+  $.count++;  // Triggers reactive updates
+  ```
+
+- **`window.__vibeManifest`** — Internal manifest data. Used by the compiler for optimization. Don't modify.
+
+- **`window.__vibeCompiling`** — Internal flag. Set to `true` when running in compiler context.
+
+#### Data Attributes
+
+- **`data-vibe-component-id`** — Internal attribute for component scoping. Automatically added to component elements. Don't use manually.
+
+#### Event Names
+
+- **`vibe:ready`** — Custom event fired when Vibe completes initial hydration.
+  ```javascript
+  document.addEventListener('vibe:ready', () => {
+    console.log('Vibe is ready');
+  });
+  ```
+
+#### Special Attribute Meanings
+
+- **`src`** on **`<component>`** or **`<div class="component">`** — Triggers runtime component fetching. Components without `src` are treated as inline wrappers.
+  ```html
+  <!-- Both work the same way -->
+  <component src="/components/card.html"></component>
+  <div class="component" src="/components/card.html"></div>
+  ```
+
+- **`dehydrate`** — Attribute or class name to skip reactive processing (alias for `vibe-dehydrate`).
+
 ### Deep Reactivity
 
 Vibe uses recursive proxies to detect changes at any nesting level:

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,45 @@
+// 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;
+
+  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;