@ape-egg/vibe 1.0.5 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## [1.1.1] - 2026-02-01
+
+### Added
+
+- **Compiler CLI**: Modern command structure with subcommand support
+  - New bin command: `vibe`
+  - Subcommand syntax: `bunx vibe compile [options]` or shorthand `bunx vibe c [options]`
+  - Accessible directly via `bunx` without manual npm scripts
+  - Automatic detection of unknown subcommands with helpful error messages
+  - Backward compatibility: works with or without `compile` subcommand
+- **Validation time tracking**: Compiler now reports component validation phase timing separately
+  - Shows time spent fetching external components
+  - Helps explain total compilation time vs individual phase times
+  - Displayed as: `* Validated components in XXms`
+- **Component tree output**: Improved verbose logging for component compilation
+  - Tree structure with nested dependencies (e.g., nav.html → top-of-nav.html, menu.html)
+  - Usage counts for each unique component
+  - Color-coded: internal (green) vs external (magenta)
+  - Summary format: `Compiled components (X internal, Y external)`
+  - Clean hierarchical display with `└─` for children
+- **Compiler documentation**: Updated READMEs with new CLI commands
+  - `/vibe/README.md` and `/vibe/compiler/README.md` now show `bunx vibe compile` syntax
+  - Added npm scripts examples for optional shortcuts
+  - Removed outdated `bun vibe:compile` references
+
+### Changed
+
+- **Compiler output formatting**: Consistent spacing between major sections (Vibe Compiler, Compiler config, Compiled components, etc.)
+- **Verbose logging**: Removed redundant component loading list, streamlined validation output
+
+---
+
+## [1.0.7] - 2026-01-30
+
+### Added
+
+- **`<component>` element**: Runtime implementation of reusable HTML components
+  - Fetch HTML from local or remote sources: `<component src="/components/card.html">`
+  - Props system: Pass reactive bindings `headline="@[title]"` or static values `theme="dark"`
+  - Children via `<slot>`: Content between tags replaces `<slot></slot>` in fetched HTML
+  - Recursive resolution: Fetched HTML can contain more `<component>` elements
+  - Runtime-first with future compiler optimization planned (Phase 5)
+- **Deep reactivity**: Nested property mutations now automatically trigger updates
+  - Recursive proxy implementation wraps all nested objects and arrays
+  - `$.obj.nested.prop = x` now triggers reactivity (previously required `$.obj = { ...$.obj, nested: { ...$.obj.nested, prop: x } }`)
+  - WeakMap cache prevents double-wrapping of proxies
+  - Tracks root property for each mutation to trigger correct affected element checks
+  - Same approach as Vue 3 - tiny performance cost for massive DX improvement
+- **Scoped state for iterations**: Iteration instances now preserve local context for reactive updates
+  - Each `<!-- each items as item -->` instance stores its own `scopedState` (Proxy wrapper with local variables)
+  - When global state changes (e.g., `tutorialProgress`), affected elements inside iterations can access both local (`item`) and global variables
+  - Enables reactive attributes like `completed="@[tutorialProgress[item.id]]"` to update correctly without full re-render
+  - Scoped state flows through `affected.js` → `hydrate.js` pipeline for proper evaluation context
+- **Compiler (first pass)**: Rust-based optional build tool
+  - Asset handling with whitelist approach (fonts, images, media, docs automatically copied)
+  - HTML/CSS/JS processing
+  - Configuration via `package.json` (`vibe-compiler` section)
+  - Node.js wrapper for cross-platform execution
+  - Foundation for future optimizations (component inlining, iteration optimization, two-way binding sugar)
+- **Unit tests**: Comprehensive unit test suite (212 tests) for runtime modules using Bun's test framework - tests pure function layer (utils, state, iteration-utils, conditionals, affected, manifest) with aggressive edge case coverage
+- **NPM scripts**: Added `bun unit` and `bun unit:watch` commands for running unit tests
+- **Name bindings**: Bindings in attribute name position now supported
+  - Syntax: `<icon @[section.icon]></icon>` evaluates expression and sets it as attribute name
+  - HTML lowercases attribute names, so case-insensitive property lookup is used for simple properties
+  - Old attributes are automatically cleaned up when the bound value changes
+  - Useful for dynamic attribute names like icon libraries, custom elements, or conditional attributes
+  - Works in all contexts: root level, iterations, conditionals, and inside `<component>` elements
+
+### Fixed
+
+- **Replace abort**: `<component>` elements now properly abort pending fetches (via `AbortController`) when removed from DOM before fetch completes, preventing "no parent node" errors and saving bandwidth
+- **Nested iterations and conditionals**: Fixed issue where nested `<!-- each -->` and `<!-- if -->` blocks inside `<component>` elements would render then immediately disappear
+  - Root cause: MutationObserver re-parsing created fresh runtime state, causing iterations to think they needed re-rendering
+  - Solution: Added `__vibeRendered` marker on comment nodes that persists across re-parses
+  - Now properly handles complex nested structures like menu systems with dynamic sections and items
+- **Conditionals wrapping iteration content**: Fixed conditionals in attribute name position (e.g., `<!-- if condition -->` wrapping `<nav-section>`) not being detected inside iteration templates
+  - Root cause: `initializeBlock()` only parsed the first element node, missing comment nodes like `<!-- if -->`
+  - Solution: Parse all template nodes in a container to capture comment nodes, ensuring tree element references match actual DOM nodes
+  - Enables patterns like conditional menu items: `<!-- each items as item --><!-- if condition --><item>...</item><!-- /if --><!-- /each -->`
+- **StructuredClone with proxies**: Replaced `structuredClone()` with custom `deepClone()` that properly unwraps proxy objects for state snapshots in hooks
+
+---
+
+## [1.0.6] - 2026-01-29
+
+### Added
+
+- **Debug mode**: New optional third parameter to enable colored console logging of Vibe's lifecycle phases (Attach, Parse, Manifest, Hydrate, Iterate, Condition, Observe, Fetch, Complete, Update, Mutate)
+- **Debug helper**: Centralized `debugLog()` function with phase-specific color coding and tree-style indentation for nested operations
+
+### Fixed
+
+- **Nested brackets**: `BINDING_REGEX` and `PURE_BINDING_REGEX` now correctly parse bindings with one level of nested brackets (e.g., `@[items[0]]`, `@[obj[key]]`)
+
+### Changed
+
+- **Internal naming**: Renamed `link.js` → `manifest.js` and `linkList` → `manifest` throughout codebase to better reflect its purpose as a DOM element registry/manifest
+- **Phase constants**: Added `PHASE_*` constants for all lifecycle phases to ensure consistent naming across debug logs
+
+---
+
 ## [1.0.5] - 2026-01-25
 
 ### Fixed

package/README.md

@@ -4,34 +4,71 @@ A runtime-first reactive library.
 
 No virtual DOM. No build step. Just modern JavaScript.
 
-## Install
-
 ```bash
 npm install @ape-egg/vibe
 ```
 
-## Quick Start
+---
+
+## Vibe Runtime
+
+The core reactive runtime. Works directly in the browser without any build tools.
+
+### Quick Start
 
 ```html
-<script type="module">
-  import state from "@ape-egg/vibe";
-  window.$ = state({ name: "World", count: 0 });
-</script>
+<html>
+<head>
+  <link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
+  <script type="module">
+    import state from "@ape-egg/vibe";
+    // Attaches to element with attribute "vibe" by default
+    window.$ = state({ name: "World", count: 0 });
+  </script>
+</head>
+<body vibe>
 
 <h1>Hello, @[name]!</h1>
 <button onclick="$.count++">Clicked @[count] times</button>
+
+</body>
+</html>
 ```
 
-## Features
+### Prevent FOUC
+
+To prevent a flash of unstyled content while Vibe hydrates:
+
+1. Include `vibe.css` in your HTML
+2. Add the `vibe` attribute to an element (typically `<body>`) to mark the hydration boundary
+
+The CSS targets `[vibe]` and hides it until hydration completes. Once Vibe finishes processing, it removes the attribute, revealing your content.
 
 ### Reactive Bindings
 
-Use `@[property]` anywhere in HTML or CSS:
+Vibe supports bindings in three positions:
 
+**Text content** — Inside element tags:
 ```html
 <div>@[firstName] @[lastName]</div>
-<div>@[firstName + ' ' + lastName]</div>
+<h1>Hello, @[name]!</h1>
+```
+
+**Attribute values** — In attribute value position:
+```html
+<input value="@[username]" />
+<div class="@[theme]" style="color: @[color]"></div>
+<a href="@[url]">Link</a>
+```
 
+**Attribute names** — In attribute name position (useful for dynamic attributes):
+```html
+<icon @[iconName]></icon>
+<button @[state]>Click me</button>
+```
+
+**CSS** — Bindings also work in style tags:
+```html
 <style>
   .box { background: @[themeColor]; }
 </style>
@@ -65,6 +102,16 @@ Nested iteration with dot paths:
 <!-- /if -->
 ```
 
+### Components
+
+Runtime component loading with props and slots:
+
+```html
+<component src="/components/card.html" title="@[pageTitle]" theme="dark">
+  <p>Content passed as slot</p>
+</component>
+```
+
 ### Dehydrate
 
 Skip reactive processing for an element:
@@ -73,32 +120,190 @@ Skip reactive processing for an element:
 <code dehydrate>@[this] displays literally</code>
 ```
 
-### Dynamic Elements
+### Deep Reactivity
 
-Elements added via JavaScript are automatically hydrated through MutationObserver.
+Vibe uses recursive proxies to detect changes at any nesting level:
 
-## How It Works
+```javascript
+// All of these trigger reactive updates:
+$.user.name = "Alice";
+$.todos[2].completed = true;
+$.config.theme.colors.primary = "#007bff";
+```
+
+No need for immutable update patterns or spread operators. Just mutate and Vibe handles the rest.
+
+### 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
+2. **Deep reactivity** — Nested mutations trigger updates automatically (`$.obj.nested.prop = x`)
+3. **DOM parsing** — Finds all `@[...]` bindings on load
+4. **Surgical updates** — Only affected elements re-render
+5. **MutationObserver** — Tracks dynamically added elements
 
-## Prevent FOUC
+---
 
-Hide content until hydration completes:
+## Vibe Compiler
 
-```html
-<body style="visibility: hidden;">
+Optional build step for production optimization. The compiler processes HTML files, inlines components, and handles assets while preserving directory structure.
+
+### Installation
+
+The compiler requires Rust for non-macOS ARM64 platforms:
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+**Note:** A prebuilt binary for macOS ARM64 is included. Other platforms will compile from source automatically.
+
+### Usage
+
+```bash
+# Initialize config in package.json
+bunx vibe compile --init
+
+# Compile
+bunx vibe compile
+
+# 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 --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)
 ```
 
-Or use the included CSS:
+Or via npm scripts:
+
+```json
+{
+  "scripts": {
+    "vibe:compile": "vibe compile",
+    "vibe:compile:init": "vibe compile --init"
+  }
+}
+```
+
+Then run with `bun vibe:compile` or `npm run vibe:compile`.
+
+### Configuration
+
+Add to your `package.json`:
+
+```json
+{
+  "vibe-compiler": {
+    "source": "./",
+    "output": "./compiled",
+    "components": "components",
+    "pages": "pages",
+    "assets": "assets",
+    "minify": false,
+    "accessibility": false,
+    "excludeTags": [],
+    "nodeModulesAsIs": false
+  }
+}
+```
+
+**Defaults** (when no config):
+- `source`: `./`
+- `output`: `./compiled`
+- `components`: `<source>/components`
+- `pages`: `<source>/pages`
+- `assets`: `<source>/assets`
+
+### Asset Handling
+
+The compiler uses a whitelist approach. These file types are automatically copied:
+
+**Fonts:** `.ttf`, `.otf`, `.woff`, `.woff2`, `.eot`
+**Images:** `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico`
+**Media:** `.mp4`, `.webm`, `.ogg`, `.mp3`, `.wav`, `.flac`, `.aac`
+**Documents:** `.pdf`
+**Data:** `.json`, `.xml`, `.csv`
+
+HTML, CSS, and JavaScript files are processed by the compiler.
+
+### Node Modules (Self-Contained Output)
+
+By default, the compiler creates deployable output by installing production dependencies directly into the output directory:
+
+1. Copies `package.json` and lockfile to output
+2. Runs `<package-manager> install --production` in output directory
+3. Removes `package.json` and lockfile from output (cleanup)
+
+This ensures:
+- Compiled output only includes runtime dependencies (from `dependencies`, not `devDependencies`)
+- Local `node_modules` is never modified
+- Faster than copying (no intermediate copy step)
+
+**Package Manager Detection:**
+Auto-detects based on lockfiles: `bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`
+
+**Opt-out:**
+Set `nodeModulesAsIs: true` in config or use `--node-modules-as-is` flag to copy node_modules as-is.
+
+### Output Structure
+
+Mirrors source structure:
+
+```
+src/                     compiled/
+├── pages/              ├── pages/
+│   └── index.html      │   └── index.html
+├── components/         │   (components inlined)
+│   └── counter.html
+├── assets/             ├── assets/
+│   └── image.png       │   └── image.png
+└── node_modules/       └── node_modules/
+    └── @ape-egg/           └── @ape-egg/
+        └── vibe/               └── vibe/
+```
+
+### Accessibility Mode
+
+`--accessibility` transforms custom HTML elements to divs with classes:
 
 ```html
-<link rel="stylesheet" href="@ape-egg/vibe/vibe.css">
-<body vibe>
+<!-- input -->
+<counter-header>Count</counter-header>
+
+<!-- output -->
+<div class="counter-header">Count</div>
 ```
 
+Exclude specific tags (e.g., web components) via `excludeTags` config.
+
+### Building Native Binaries
+
+For distribution without Rust:
+
+```bash
+cd node_modules/@ape-egg/vibe/compiler/src
+
+# Build for current platform
+cargo build --release
+
+# Copy binary to native directory
+cp target/release/vibe-compiler ../native/vibe-compiler-darwin-arm64
+```
+
+Supported platforms:
+- `vibe-compiler-darwin-arm64` (macOS Apple Silicon) ✅ Included
+- `vibe-compiler-darwin-x64` (macOS Intel)
+- `vibe-compiler-linux-x64`
+- `vibe-compiler-linux-arm64`
+- `vibe-compiler-win32-x64.exe`
+
+The CLI wrapper automatically falls back to `cargo run` when native binaries aren't present.
+
+---
+
 ## Browser Support
 
 Modern browsers with Proxy and MutationObserver support.

package/compiler/bin/vibe-compile.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { platform, arch } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const nativeDir = join(__dirname, '..', 'native');
+const originalCwd = process.cwd();
+
+// Map Node.js platform/arch to binary names
+const getPlatformBinary = () => {
+  const os = platform();
+  const cpu = arch();
+
+  const platformMap = {
+    'darwin-arm64': 'vibe-compiler-darwin-arm64',
+    'darwin-x64': 'vibe-compiler-darwin-x64',
+    'linux-x64': 'vibe-compiler-linux-x64',
+    'linux-arm64': 'vibe-compiler-linux-arm64',
+    'win32-x64': 'vibe-compiler-win32-x64.exe',
+  };
+
+  const key = `${os}-${cpu}`;
+  const binary = platformMap[key];
+
+  if (!binary) {
+    console.error(`Unsupported platform: ${os}-${cpu}`);
+    console.error('Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64');
+    process.exit(1);
+  }
+
+  return binary;
+};
+
+const run = () => {
+  const binary = getPlatformBinary();
+  const binaryPath = join(nativeDir, binary);
+  let userArgs = process.argv.slice(2);
+
+  // Handle subcommand: vibe compile [args]
+  // If first arg is "compile" or "c", remove it (the binary doesn't need it)
+  if (userArgs[0] === 'compile' || userArgs[0] === 'c') {
+    userArgs = userArgs.slice(1);
+  } else if (userArgs[0] && !userArgs[0].startsWith('-')) {
+    // Unknown subcommand
+    console.error(`Unknown subcommand: ${userArgs[0]}`);
+    console.error('Available subcommands: compile (or c)');
+    console.error('Usage: vibe compile [options]');
+    process.exit(1);
+  }
+  // If no subcommand provided, default to compile behavior (pass args as-is)
+
+  // Check if native binary exists
+  if (!existsSync(binaryPath)) {
+    // Fall back to cargo run for development
+    console.info('[vibe-compile] Native binary not found, building with cargo...');
+
+    const srcDir = join(__dirname, '..', 'src');
+
+    if (!existsSync(join(srcDir, 'Cargo.toml'))) {
+      console.error('Neither native binary nor Rust source found.');
+      console.error(`Expected binary at: ${binaryPath}`);
+      console.error(`Or Cargo.toml at: ${srcDir}`);
+      process.exit(1);
+    }
+
+    // Pass --cwd to tell the Rust binary the original working directory
+    const cargoArgs = ['run', '--release', '--', '--cwd', originalCwd, ...userArgs];
+
+    const cargo = spawn('cargo', cargoArgs, {
+      cwd: srcDir,
+      stdio: 'inherit',
+    });
+
+    cargo.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        console.error('Cargo not found. Please install Rust: https://rustup.rs');
+      } else {
+        console.error('Failed to run cargo:', err.message);
+      }
+      process.exit(1);
+    });
+
+    cargo.on('close', (code) => {
+      process.exit(code ?? 0);
+    });
+
+    return;
+  }
+
+  // Run the native binary (it runs in the user's cwd, so no --cwd needed)
+  const child = spawn(binaryPath, userArgs, {
+    stdio: 'inherit',
+  });
+
+  child.on('error', (err) => {
+    console.error('Failed to run vibe-compiler:', err.message);
+    process.exit(1);
+  });
+
+  child.on('close', (code) => {
+    process.exit(code ?? 0);
+  });
+};
+
+run();