@ape-egg/vibe 1.3.2 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # 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/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/boot.js

@@ -10,7 +10,6 @@ export const ensureBoot = () => {
   if (booted || bootQueued) return;
   bootQueued = true;
 
-  // Auto-boot in next microtask if no explicit boot
   queueMicrotask(() => {
     if (!booted) {
       boot();