@ape-egg/vibe 1.3.2 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,200 @@
 # Changelog
 
+## [1.6.1] - 2026-02-12
+
+### Fixed
+
+- **Compiler output directory handling** - Fixed duplicate file generation in output
+  - Compiler now properly handles source and output paths without preserving source directory structure
+  - Files from `./src` are now correctly written to root of output directory (e.g., `compiled/index.html`) instead of `compiled/src/index.html`
+  - Canonicalized source path for reliable comparison and path stripping
+  - Updated all processing functions to use canonical source path for relative path calculation
+
+- **Manifest detection improvements** - Better handling of directory URLs and extensionless paths
+  - Directory URLs now normalized: `/compiled/` → `/compiled/index.html`
+  - Extensionless URLs now normalized: `/compiled/mypage` → `/compiled/mypage.html`
+  - Fixes manifest detection when visiting pages without explicit `.html` extension
+  - Enables proper hyperspeed loading for directory index pages
+
+---
+
+## [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

@@ -1,13 +1,15 @@
 # Vibe
 
-A runtime-first reactive library.
+**Version 1.6.0 (Alpha)** — A runtime-first reactive framework with optional compilation.
 
-No virtual DOM. No build step. Just modern JavaScript.
+No virtual DOM. No build step required. Just modern JavaScript. When you need production optimizations, add the optional Rust-based compiler.
 
 ```bash
 npm install @ape-egg/vibe
 ```
 
+**Status:** Functional and ready to use, but expect bugs and breaking changes daily until stable. Use in production at your own risk.
+
 ---
 
 ## Vibe Runtime
@@ -124,6 +126,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:
@@ -149,7 +248,7 @@ No need for immutable update patterns or spread operators. Just mutate and Vibe
 
 ## Vibe Compiler
 
-Optional build step for production optimization. The compiler processes HTML files, inlines components, and handles assets while preserving directory structure.
+Optional build step for production optimization. The compiler provides component inlining, iteration optimization, watch mode, and hydration manifests while preserving directory structure.
 
 ### Installation
 
@@ -167,18 +266,27 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 # Initialize config in package.json
 bunx vibe compile --init
 
-# Compile
+# Basic compilation
 bunx vibe compile
+# or shorthand
+bunx vibe c
+
+# Watch mode (incremental compilation)
+bunx vibe compile --watch
+
+# Production build
+bunx vibe compile --minify --source-maps
 
 # With options
 bunx vibe compile --verbose             # Step-by-step logging
 bunx vibe compile --minify              # Minify output
-bunx vibe compile --accessibility       # Transform custom tags to divs
+bunx vibe compile --elements-as-is      # Keep custom elements as-is
 bunx vibe compile --validate            # Validate HTML syntax
-bunx vibe compile --create-manifest     # Generate hydration manifest
 bunx vibe compile --source-maps         # Generate source maps
 bunx vibe compile --node-modules-as-is  # Copy node_modules as-is
-bunx vibe compile --watch               # Watch mode (future)
+bunx vibe compile --components-as-is    # Skip component inlining
+bunx vibe compile --runtime-as-is       # Skip manifest generation
+bunx vibe compile --iterations-as-is    # Skip iteration optimization
 ```
 
 Or via npm scripts:
@@ -186,13 +294,14 @@ Or via npm scripts:
 ```json
 {
   "scripts": {
-    "vibe:compile": "vibe compile",
-    "vibe:compile:init": "vibe compile --init"
+    "compile": "vibe compile",
+    "compile:watch": "vibe compile --watch",
+    "compile:prod": "vibe compile --minify --source-maps"
   }
 }
 ```
 
-Then run with `bun vibe:compile` or `npm run vibe:compile`.
+Then run with `npm run compile` or `bun compile`.
 
 ### Configuration
 
@@ -207,13 +316,26 @@ Add to your `package.json`:
     "pages": "pages",
     "assets": "assets",
     "minify": false,
-    "accessibility": false,
-    "excludeTags": [],
-    "nodeModulesAsIs": false
+    "elementsAsIs": false,
+    "reservedElements": [],
+    "sourceMaps": false,
+    "validate": false,
+    "nodeModulesAsIs": false,
+    "componentsAsIs": false,
+    "runtimeAsIs": false,
+    "iterationsAsIs": false
   }
 }
 ```
 
+**Key Options:**
+
+- `elementsAsIs: false` — Transform custom elements to divs (default)
+- `reservedElements: []` — Additional element names to reserve (appends to built-in HTML5 elements + "component")
+- `componentsAsIs: false` — Inline components (default) or keep separate for runtime
+- `iterationsAsIs: false` — Optimize iterations (default) or use runtime rendering
+- `runtimeAsIs: false` — Generate manifest (default) or skip for runtime-only
+
 **Defaults** (when no config):
 
 - `source`: `./`
@@ -254,6 +376,66 @@ Auto-detects based on lockfiles: `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `pa
 **Opt-out:**
 Set `nodeModulesAsIs: true` in config or use `--node-modules-as-is` flag to copy node_modules as-is.
 
+### Watch Mode
+
+Watch mode enables incremental compilation with intelligent dependency tracking:
+
+```bash
+bunx vibe compile --watch
+```
+
+Features:
+- **Incremental builds** — Only recompiles changed files (~100ms)
+- **Dependency tracking** — Changes to components trigger recompilation of pages using them
+- **Debounced** — 300ms debounce prevents excessive compilation during rapid changes
+- **Delta output** — First compile shows full output, subsequent compiles show only changes
+
+### Component System
+
+Components are automatically inlined during compilation with full support for props and slots:
+
+```html
+<!-- Source: components/card.html -->
+<div class="card">
+  <h2>@[title]</h2>
+  <p>@[description]</p>
+  <slot></slot>
+</div>
+
+<!-- Usage in page -->
+<component src="/components/card.html" title="My Card" description="Card description">
+  <p>Slot content</p>
+</component>
+
+<!-- Compiled output -->
+<component>
+  <div class="card">
+    <h2>My Card</h2>
+    <p>Card description</p>
+    <p>Slot content</p>
+  </div>
+</component>
+```
+
+**Custom element syntax:** Components can also use custom element syntax (e.g., `<card>` → auto-converts to `<component src="/components/card.html">`).
+
+**Opt-out:** Set `componentsAsIs: true` to keep components as separate files for runtime loading.
+
+### Iteration Optimization
+
+The compiler generates optimized batch functions for `<!-- each -->` loops, providing 2-3x faster rendering:
+
+```html
+<!-- Source -->
+<!-- each items as item, index -->
+<li>@[index]: @[item]</li>
+<!-- /each -->
+
+<!-- Compiled to optimized batch function -->
+```
+
+**Opt-out:** Set `iterationsAsIs: true` to use runtime rendering for all iterations.
+
 ### Output Structure
 
 Mirrors source structure:
@@ -271,9 +453,9 @@ src/                     compiled/
         └── vibe/               └── vibe/
 ```
 
-### Accessibility Mode
+### Element Transformation
 
-`--accessibility` transforms custom HTML elements to divs with classes:
+By default (`elementsAsIs: false`), custom HTML elements are transformed to divs with classes for better HTML validity:
 
 ```html
 <!-- input -->
@@ -283,7 +465,23 @@ src/                     compiled/
 <div class="counter-header">Count</div>
 ```
 
-Exclude specific tags (e.g., web components) via `excludeTags` config.
+Set `elementsAsIs: true` or use `--elements-as-is` flag to keep custom elements unchanged.
+
+**Note:** The `<component>` element is a framework element and is never transformed.
+
+### Reserved Element Names
+
+The compiler validates component filenames against reserved element names (all HTML5 elements + "component" + your custom list). This prevents confusing bugs where components share names with HTML elements.
+
+```json
+{
+  "vibe-compiler": {
+    "reservedElements": ["my-custom-element", "another-reserved-name"]
+  }
+}
+```
+
+**Case-sensitive validation:** `nav.html` conflicts with `<nav>` and will error, but `Nav.html` is allowed.
 
 ### Building Native Binaries
 

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();