@hypen-space/core 0.2.7 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/core",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Hypen core engine - Platform-agnostic reactive UI runtime",
   "type": "module",
   "main": "./dist/src/index.js",

package/wasm-browser/README.md

@@ -2,6 +2,39 @@
 
 The core reactive rendering engine for Hypen, written in Rust. Compiles to WASM for web/desktop or native binaries with UniFFI for mobile platforms.
 
+## Quick Start
+
+### Rust
+
+```rust
+use hypen_engine::{Engine, ast_to_ir};
+use hypen_parser::parse_component;
+use serde_json::json;
+
+let mut engine = Engine::new();
+engine.set_render_callback(|patches| {
+    // Apply patches to your renderer
+});
+
+let ast = parse_component(r#"Column { Text("Hello") }"#)?;
+engine.render(&ast_to_ir(&ast));
+engine.update_state(json!({ "count": 42 }));
+```
+
+### JavaScript/TypeScript (WASM)
+
+```typescript
+import init, { WasmEngine } from './wasm/hypen_engine.js';
+await init();
+
+const engine = new WasmEngine();
+engine.setRenderCallback((patches) => applyPatches(patches));
+engine.setModule('App', ['increment'], ['count'], { count: 0 });
+engine.renderSource(`Column { Text("\${state.count}") }`);
+```
+
+See [BUILD_WASM.md](./BUILD_WASM.md) for detailed WASM build instructions.
+
 ## Overview
 
 Hypen Engine is a platform-agnostic UI engine that:
@@ -51,7 +84,7 @@ Hypen Engine is a platform-agnostic UI engine that:
    - `Insert(parent, id, before?)` - Insert into tree
    - `Move(parent, id, before?)` - Reorder node
    - `Remove(id)` - Remove from tree
-   - `AttachEvent(id, event)` / `DetachEvent(id, event)`
+   - Event handling is managed at the renderer level
 
 5. **Action/Event Routing** (`src/dispatch/`)
    - Map `@actions.*` to module handlers
@@ -67,7 +100,7 @@ Hypen Engine is a platform-agnostic UI engine that:
    - Initial tree serialization
    - Incremental patch streaming
    - Revision tracking and optional integrity hashes
-   - JSON/CBOR format support
+   - JSON format support
 
 ## Usage
 
@@ -75,15 +108,20 @@ Hypen Engine is a platform-agnostic UI engine that:
 
 ```rust
 use hypen_engine::{Engine, ir::{Element, Value, Component}};
+use hypen_engine::reactive::parse_binding;
+use indexmap::IndexMap;
 use serde_json::json;
 
 // Create engine
 let mut engine = Engine::new();
 
 // Register a custom component
-engine.register_component(Component::new("Greeting", |props| {
+// Note: In practice, you'd typically parse Hypen DSL with ast_to_ir
+engine.register_component(Component::new("Greeting", |props: IndexMap<String, serde_json::Value>| {
     Element::new("Text")
-        .with_prop("text", Value::Binding("${state.name}".to_string()))
+        .with_prop("text", Value::Binding(
+            parse_binding("${state.name}").expect("valid binding")
+        ))
 }));
 
 // Set render callback
@@ -141,6 +179,10 @@ cargo test
 
 ### WASM (Web/Desktop)
 
+The WASM build is fully functional and tested. See [BUILD_WASM.md](./BUILD_WASM.md) for detailed build instructions.
+
+**Quick Start:**
+
 ```bash
 # Install wasm-pack (one time)
 cargo install wasm-pack
@@ -149,47 +191,60 @@ cargo install wasm-pack
 ./build-wasm.sh
 
 # Or build manually for specific targets:
-wasm-pack build --target bundler    # For webpack/vite
+wasm-pack build --target bundler    # For webpack/vite/rollup
 wasm-pack build --target nodejs     # For Node.js
 wasm-pack build --target web        # For vanilla JS
 ```
 
-Output directories:
+**Output directories:**
 - `pkg/bundler/` - For use with bundlers (webpack, vite, rollup)
 - `pkg/nodejs/` - For Node.js
 - `pkg/web/` - For vanilla HTML/JS (see `example.html`)
 
+**Build to custom directory:**
+```bash
+# Build directly to your renderer project
+wasm-pack build --target bundler --out-dir ../hypen-render-bun/wasm
+```
+
+The WASM binary is optimized for size (~300KB) with LTO and size optimizations enabled.
+
 ### JavaScript/TypeScript API
 
+The WASM build provides a `WasmEngine` class with a complete API:
+
 ```typescript
 import init, { WasmEngine } from './pkg/web/hypen_engine.js';
 
-// Initialize WASM
+// Initialize WASM (required before creating engine)
 await init();
 
-// Create engine
+// Create engine instance
 const engine = new WasmEngine();
 
-// Set render callback
+// Set render callback to receive patches
 engine.setRenderCallback((patches) => {
     console.log('Patches:', patches);
-    // Apply patches to your renderer
+    // Apply patches to your platform renderer
+    applyPatchesToDOM(patches);
 });
 
 // Register action handlers
 engine.onAction('increment', (action) => {
-    console.log('Increment action:', action);
+    console.log('Action received:', action.name, action.payload);
+    // Handle action (e.g., update state)
+    engine.updateState({ count: action.payload.count + 1 });
 });
 
-// Initialize module
+// Initialize module with state and actions
 engine.setModule(
-    'CounterModule',
-    ['increment', 'decrement'],
-    ['count'],
-    { count: 0 }
+    'CounterModule',           // Module name
+    ['increment', 'decrement'], // Available actions
+    ['count'],                  // State keys
+    { count: 0 }                // Initial state
 );
 
-// Render Hypen DSL
+// Render Hypen DSL source code
 const source = `
     Column {
         Text("Count: \${state.count}")
@@ -198,13 +253,30 @@ const source = `
 `;
 engine.renderSource(source);
 
-// Update state
+// Update state (triggers reactive re-render)
 engine.updateState({ count: 42 });
 
-// Dispatch action
+// Dispatch action programmatically
 engine.dispatchAction('increment', { amount: 1 });
+
+// Get current revision number (for remote UI)
+const revision = engine.getRevision();
 ```
 
+**WasmEngine API Reference:**
+
+- `constructor()` - Create a new engine instance
+- `renderSource(source: string)` - Render Hypen DSL source code
+- `setRenderCallback(callback: (patches: Patch[]) => void)` - Set patch callback
+- `setModule(name, actions, stateKeys, initialState)` - Initialize module
+- `updateState(patch: object)` - Update state and trigger re-render
+- `dispatchAction(name: string, payload?: any)` - Dispatch an action
+- `onAction(name: string, handler: (action: Action) => void)` - Register action handler
+- `getRevision(): number` - Get current revision number
+- `setComponentResolver(resolver: (name: string, context?: string) => ResolvedComponent | null)` - Set dynamic component resolver
+
+See [BUILD_WASM.md](./BUILD_WASM.md) for more details and examples.
+
 ### Testing WASM Build
 
 Open `example.html` in a web server:
@@ -221,44 +293,62 @@ npx serve .
 
 ### Mobile (UniFFI)
 
+UniFFI bindings for native mobile platforms are planned but not yet implemented.
+
 ```bash
-# Generate Swift/Kotlin bindings (coming soon)
+# Future: Generate Swift/Kotlin bindings
 cargo install uniffi_bindgen
 uniffi-bindgen generate src/hypen_engine.udl --language swift
 uniffi-bindgen generate src/hypen_engine.udl --language kotlin
 ```
 
+For now, mobile platforms can use the WASM build via WebView or native WASM runtimes.
+
 ## Project Structure
 
 ```
 hypen-engine-rs/
 ├── src/
-│   ├── lib.rs              # Public API
-│   ├── engine.rs           # Main orchestrator
-│   ├── wasi.rs             # WASI interfaces
+│   ├── lib.rs              # Public API exports
+│   ├── engine.rs           # Main Engine orchestrator
+│   ├── wasm.rs             # WASM bindings (wasm-bindgen)
+│   ├── state.rs            # State change tracking
+│   ├── render.rs           # Dirty node rendering
+│   ├── logger.rs           # Logging utilities
 │   ├── ir/                 # IR & component expansion
+│   │   ├── mod.rs          # Module exports
 │   │   ├── node.rs         # NodeId, Element, Props, Value
-│   │   ├── component.rs    # Component registry
-│   │   └── expand.rs       # AST → IR lowering
+│   │   ├── component.rs    # Component registry & resolution
+│   │   ├── expand.rs       # AST → IR lowering
+│   │   └── children_slots_test.rs
 │   ├── reactive/           # Reactive system
+│   │   ├── mod.rs          # Module exports
 │   │   ├── binding.rs      # ${state.*} parsing
 │   │   ├── graph.rs        # Dependency tracking
-│   │   └── scheduler.rs    # Dirty marking
+│   │   └── scheduler.rs    # Dirty marking & scheduling
 │   ├── reconcile/          # Reconciliation
-│   │   ├── tree.rs         # Instance tree
-│   │   ├── diff.rs         # Diffing algorithm
+│   │   ├── mod.rs          # Module exports
+│   │   ├── tree.rs         # Instance tree (virtual DOM)
+│   │   ├── diff.rs         # Keyed diffing algorithm
 │   │   └── patch.rs        # Patch types
 │   ├── dispatch/           # Events & actions
+│   │   ├── mod.rs          # Module exports
 │   │   ├── action.rs       # Action dispatcher
 │   │   └── event.rs        # Event router
-│   ├── lifecycle/          # Lifecycle
+│   ├── lifecycle/          # Lifecycle management
+│   │   ├── mod.rs          # Module exports
 │   │   ├── module.rs       # Module lifecycle
 │   │   ├── component.rs    # Component lifecycle
 │   │   └── resource.rs     # Resource cache
 │   └── serialize/          # Serialization
+│       ├── mod.rs          # Module exports
 │       └── remote.rs       # Remote UI protocol
-├── Cargo.toml
-└── README.md
+├── tests/                  # Integration tests
+├── Cargo.toml              # Rust dependencies
+├── build-wasm.sh           # WASM build script
+├── BUILD_WASM.md           # Detailed WASM build docs
+├── example.html            # WASM demo page
+└── README.md               # This file
 ```
 
 ## Key Data Structures
@@ -270,7 +360,7 @@ pub struct Element {
     pub props: IndexMap<String, Value>, // Properties
     pub children: Vec<Element>,         // Child elements
     pub key: Option<String>,            // For reconciliation
-    pub events: IndexMap<String, String>, // event → action
+    // Note: Event handling is done at the renderer level, not in IR
 }
 ```
 
@@ -278,7 +368,11 @@ pub struct Element {
 ```rust
 pub enum Value {
     Static(serde_json::Value),  // Literal values
-    Binding(String),             // ${state.user.name}
+    Binding(Binding),            // Parsed ${state.user.name} binding
+    TemplateString {             // Template with embedded bindings
+        template: String,
+        bindings: Vec<Binding>,
+    },
     Action(String),              // @actions.signIn
 }
 ```
@@ -292,8 +386,7 @@ pub enum Patch {
     Insert { parent_id, id, before_id? },
     Move { parent_id, id, before_id? },
     Remove { id },
-    AttachEvent { id, event_name },
-    DetachEvent { id, event_name },
+    // Note: Event handling is done at the renderer level
 }
 ```
 
@@ -404,13 +497,26 @@ For client-server streaming:
 # Run all tests
 cargo test
 
-# Run with output
+# Run with output (useful for debugging)
 cargo test -- --nocapture
 
 # Test specific module
 cargo test reactive::
+
+# Test specific file
+cargo test --test test_reactive_graph
+
+# Run tests in parallel (default)
+cargo test --jobs 4
 ```
 
+The test suite includes:
+- Unit tests for each module
+- Integration tests for engine workflows
+- WASM integration tests
+- Reactive dependency tracking tests
+- Reconciliation algorithm tests
+
 ## Contributing
 
 This is part of the Hypen project. See the main repository for contribution guidelines.
@@ -419,7 +525,60 @@ This is part of the Hypen project. See the main repository for contribution guid
 
 See main Hypen project for license information.
 
+## API Reference
+
+### Engine (Rust)
+
+The main `Engine` struct provides the core functionality:
+
+```rust
+impl Engine {
+    pub fn new() -> Self;
+    pub fn register_component(&mut self, component: Component);
+    pub fn set_component_resolver<F>(&mut self, resolver: F);
+    pub fn set_module(&mut self, module: ModuleInstance);
+    pub fn set_render_callback<F>(&mut self, callback: F);
+    pub fn on_action<F>(&mut self, action_name: impl Into<String>, handler: F);
+    pub fn render(&mut self, element: &Element);
+    pub fn update_state(&mut self, state_patch: serde_json::Value);
+    pub fn notify_state_change(&mut self, change: &StateChange);
+    pub fn dispatch_action(&mut self, action: Action) -> Result<(), String>;
+    pub fn revision(&self) -> u64;
+    pub fn component_registry(&self) -> &ComponentRegistry;
+    pub fn resources(&self) -> &ResourceCache;
+}
+```
+
+### Key Exports
+
+```rust
+pub use engine::Engine;
+pub use ir::{ast_to_ir, Element, Value};
+pub use lifecycle::{Module, ModuleInstance};
+pub use reconcile::Patch;
+pub use state::StateChange;
+```
+
 ---
 
-**Status**: ✅ Core systems implemented, WASM integration in progress
-**Next**: Full keyed reconciliation, UniFFI bindings, platform renderers
+## Status
+
+**✅ Implemented:**
+- Core reactive rendering engine
+- Component expansion and registry
+- Dependency tracking and dirty marking
+- Keyed reconciliation algorithm
+- Patch generation
+- Action/event dispatch system
+- Module lifecycle management
+- Resource caching
+- WASM bindings (fully functional)
+- Remote UI serialization
+
+---
+
+## Related Documentation
+
+- [BUILD_WASM.md](./BUILD_WASM.md) - Detailed WASM build instructions
+- [../parser/README.md](../parser/README.md) - Hypen parser documentation
+- [../hypen-render-bun/README.md](../hypen-render-bun/README.md) - Bun renderer implementation

package/wasm-browser/hypen_engine.d.ts

@@ -10,7 +10,7 @@ export function patchesToJson(patches: any): string;
 export function parseToJson(source: string): string;
 export function main(): void;
 /**
- * WASM-exported engine instance
+ * WASM-exported engine instance for JavaScript runtimes
  * Uses Rc<RefCell<>> instead of Send+Sync for WASM single-threaded environment
  */
 export class WasmEngine {

package/wasm-browser/hypen_engine.js

@@ -255,7 +255,7 @@ const WasmEngineFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmengine_free(ptr >>> 0, 1));
 /**
- * WASM-exported engine instance
+ * WASM-exported engine instance for JavaScript runtimes
  * Uses Rc<RefCell<>> instead of Send+Sync for WASM single-threaded environment
  */
 export class WasmEngine {

package/wasm-browser/package.json

@@ -1,7 +1,16 @@
 {
   "name": "hypen-engine",
   "type": "module",
-  "version": "0.1.0",
+  "collaborators": [
+    "Hypen Contributors"
+  ],
+  "description": "A Rust implementation of the Hypen engine",
+  "version": "0.1.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypen-lang/hypen-engine-rs"
+  },
   "files": [
     "hypen_engine_bg.wasm",
     "hypen_engine.js",

package/wasm-node/README.md

@@ -2,6 +2,39 @@
 
 The core reactive rendering engine for Hypen, written in Rust. Compiles to WASM for web/desktop or native binaries with UniFFI for mobile platforms.
 
+## Quick Start
+
+### Rust
+
+```rust
+use hypen_engine::{Engine, ast_to_ir};
+use hypen_parser::parse_component;
+use serde_json::json;
+
+let mut engine = Engine::new();
+engine.set_render_callback(|patches| {
+    // Apply patches to your renderer
+});
+
+let ast = parse_component(r#"Column { Text("Hello") }"#)?;
+engine.render(&ast_to_ir(&ast));
+engine.update_state(json!({ "count": 42 }));
+```
+
+### JavaScript/TypeScript (WASM)
+
+```typescript
+import init, { WasmEngine } from './wasm/hypen_engine.js';
+await init();
+
+const engine = new WasmEngine();
+engine.setRenderCallback((patches) => applyPatches(patches));
+engine.setModule('App', ['increment'], ['count'], { count: 0 });
+engine.renderSource(`Column { Text("\${state.count}") }`);
+```
+
+See [BUILD_WASM.md](./BUILD_WASM.md) for detailed WASM build instructions.
+
 ## Overview
 
 Hypen Engine is a platform-agnostic UI engine that:
@@ -51,7 +84,7 @@ Hypen Engine is a platform-agnostic UI engine that:
    - `Insert(parent, id, before?)` - Insert into tree
    - `Move(parent, id, before?)` - Reorder node
    - `Remove(id)` - Remove from tree
-   - `AttachEvent(id, event)` / `DetachEvent(id, event)`
+   - Event handling is managed at the renderer level
 
 5. **Action/Event Routing** (`src/dispatch/`)
    - Map `@actions.*` to module handlers
@@ -67,7 +100,7 @@ Hypen Engine is a platform-agnostic UI engine that:
    - Initial tree serialization
    - Incremental patch streaming
    - Revision tracking and optional integrity hashes
-   - JSON/CBOR format support
+   - JSON format support
 
 ## Usage
 
@@ -75,15 +108,20 @@ Hypen Engine is a platform-agnostic UI engine that:
 
 ```rust
 use hypen_engine::{Engine, ir::{Element, Value, Component}};
+use hypen_engine::reactive::parse_binding;
+use indexmap::IndexMap;
 use serde_json::json;
 
 // Create engine
 let mut engine = Engine::new();
 
 // Register a custom component
-engine.register_component(Component::new("Greeting", |props| {
+// Note: In practice, you'd typically parse Hypen DSL with ast_to_ir
+engine.register_component(Component::new("Greeting", |props: IndexMap<String, serde_json::Value>| {
     Element::new("Text")
-        .with_prop("text", Value::Binding("${state.name}".to_string()))
+        .with_prop("text", Value::Binding(
+            parse_binding("${state.name}").expect("valid binding")
+        ))
 }));
 
 // Set render callback
@@ -141,6 +179,10 @@ cargo test
 
 ### WASM (Web/Desktop)
 
+The WASM build is fully functional and tested. See [BUILD_WASM.md](./BUILD_WASM.md) for detailed build instructions.
+
+**Quick Start:**
+
 ```bash
 # Install wasm-pack (one time)
 cargo install wasm-pack
@@ -149,47 +191,60 @@ cargo install wasm-pack
 ./build-wasm.sh
 
 # Or build manually for specific targets:
-wasm-pack build --target bundler    # For webpack/vite
+wasm-pack build --target bundler    # For webpack/vite/rollup
 wasm-pack build --target nodejs     # For Node.js
 wasm-pack build --target web        # For vanilla JS
 ```
 
-Output directories:
+**Output directories:**
 - `pkg/bundler/` - For use with bundlers (webpack, vite, rollup)
 - `pkg/nodejs/` - For Node.js
 - `pkg/web/` - For vanilla HTML/JS (see `example.html`)
 
+**Build to custom directory:**
+```bash
+# Build directly to your renderer project
+wasm-pack build --target bundler --out-dir ../hypen-render-bun/wasm
+```
+
+The WASM binary is optimized for size (~300KB) with LTO and size optimizations enabled.
+
 ### JavaScript/TypeScript API
 
+The WASM build provides a `WasmEngine` class with a complete API:
+
 ```typescript
 import init, { WasmEngine } from './pkg/web/hypen_engine.js';
 
-// Initialize WASM
+// Initialize WASM (required before creating engine)
 await init();
 
-// Create engine
+// Create engine instance
 const engine = new WasmEngine();
 
-// Set render callback
+// Set render callback to receive patches
 engine.setRenderCallback((patches) => {
     console.log('Patches:', patches);
-    // Apply patches to your renderer
+    // Apply patches to your platform renderer
+    applyPatchesToDOM(patches);
 });
 
 // Register action handlers
 engine.onAction('increment', (action) => {
-    console.log('Increment action:', action);
+    console.log('Action received:', action.name, action.payload);
+    // Handle action (e.g., update state)
+    engine.updateState({ count: action.payload.count + 1 });
 });
 
-// Initialize module
+// Initialize module with state and actions
 engine.setModule(
-    'CounterModule',
-    ['increment', 'decrement'],
-    ['count'],
-    { count: 0 }
+    'CounterModule',           // Module name
+    ['increment', 'decrement'], // Available actions
+    ['count'],                  // State keys
+    { count: 0 }                // Initial state
 );
 
-// Render Hypen DSL
+// Render Hypen DSL source code
 const source = `
     Column {
         Text("Count: \${state.count}")
@@ -198,13 +253,30 @@ const source = `
 `;
 engine.renderSource(source);
 
-// Update state
+// Update state (triggers reactive re-render)
 engine.updateState({ count: 42 });
 
-// Dispatch action
+// Dispatch action programmatically
 engine.dispatchAction('increment', { amount: 1 });
+
+// Get current revision number (for remote UI)
+const revision = engine.getRevision();
 ```
 
+**WasmEngine API Reference:**
+
+- `constructor()` - Create a new engine instance
+- `renderSource(source: string)` - Render Hypen DSL source code
+- `setRenderCallback(callback: (patches: Patch[]) => void)` - Set patch callback
+- `setModule(name, actions, stateKeys, initialState)` - Initialize module
+- `updateState(patch: object)` - Update state and trigger re-render
+- `dispatchAction(name: string, payload?: any)` - Dispatch an action
+- `onAction(name: string, handler: (action: Action) => void)` - Register action handler
+- `getRevision(): number` - Get current revision number
+- `setComponentResolver(resolver: (name: string, context?: string) => ResolvedComponent | null)` - Set dynamic component resolver
+
+See [BUILD_WASM.md](./BUILD_WASM.md) for more details and examples.
+
 ### Testing WASM Build
 
 Open `example.html` in a web server:
@@ -221,44 +293,62 @@ npx serve .
 
 ### Mobile (UniFFI)
 
+UniFFI bindings for native mobile platforms are planned but not yet implemented.
+
 ```bash
-# Generate Swift/Kotlin bindings (coming soon)
+# Future: Generate Swift/Kotlin bindings
 cargo install uniffi_bindgen
 uniffi-bindgen generate src/hypen_engine.udl --language swift
 uniffi-bindgen generate src/hypen_engine.udl --language kotlin
 ```
 
+For now, mobile platforms can use the WASM build via WebView or native WASM runtimes.
+
 ## Project Structure
 
 ```
 hypen-engine-rs/
 ├── src/
-│   ├── lib.rs              # Public API
-│   ├── engine.rs           # Main orchestrator
-│   ├── wasi.rs             # WASI interfaces
+│   ├── lib.rs              # Public API exports
+│   ├── engine.rs           # Main Engine orchestrator
+│   ├── wasm.rs             # WASM bindings (wasm-bindgen)
+│   ├── state.rs            # State change tracking
+│   ├── render.rs           # Dirty node rendering
+│   ├── logger.rs           # Logging utilities
 │   ├── ir/                 # IR & component expansion
+│   │   ├── mod.rs          # Module exports
 │   │   ├── node.rs         # NodeId, Element, Props, Value
-│   │   ├── component.rs    # Component registry
-│   │   └── expand.rs       # AST → IR lowering
+│   │   ├── component.rs    # Component registry & resolution
+│   │   ├── expand.rs       # AST → IR lowering
+│   │   └── children_slots_test.rs
 │   ├── reactive/           # Reactive system
+│   │   ├── mod.rs          # Module exports
 │   │   ├── binding.rs      # ${state.*} parsing
 │   │   ├── graph.rs        # Dependency tracking
-│   │   └── scheduler.rs    # Dirty marking
+│   │   └── scheduler.rs    # Dirty marking & scheduling
 │   ├── reconcile/          # Reconciliation
-│   │   ├── tree.rs         # Instance tree
-│   │   ├── diff.rs         # Diffing algorithm
+│   │   ├── mod.rs          # Module exports
+│   │   ├── tree.rs         # Instance tree (virtual DOM)
+│   │   ├── diff.rs         # Keyed diffing algorithm
 │   │   └── patch.rs        # Patch types
 │   ├── dispatch/           # Events & actions
+│   │   ├── mod.rs          # Module exports
 │   │   ├── action.rs       # Action dispatcher
 │   │   └── event.rs        # Event router
-│   ├── lifecycle/          # Lifecycle
+│   ├── lifecycle/          # Lifecycle management
+│   │   ├── mod.rs          # Module exports
 │   │   ├── module.rs       # Module lifecycle
 │   │   ├── component.rs    # Component lifecycle
 │   │   └── resource.rs     # Resource cache
 │   └── serialize/          # Serialization
+│       ├── mod.rs          # Module exports
 │       └── remote.rs       # Remote UI protocol
-├── Cargo.toml
-└── README.md
+├── tests/                  # Integration tests
+├── Cargo.toml              # Rust dependencies
+├── build-wasm.sh           # WASM build script
+├── BUILD_WASM.md           # Detailed WASM build docs
+├── example.html            # WASM demo page
+└── README.md               # This file
 ```
 
 ## Key Data Structures
@@ -270,7 +360,7 @@ pub struct Element {
     pub props: IndexMap<String, Value>, // Properties
     pub children: Vec<Element>,         // Child elements
     pub key: Option<String>,            // For reconciliation
-    pub events: IndexMap<String, String>, // event → action
+    // Note: Event handling is done at the renderer level, not in IR
 }
 ```
 
@@ -278,7 +368,11 @@ pub struct Element {
 ```rust
 pub enum Value {
     Static(serde_json::Value),  // Literal values
-    Binding(String),             // ${state.user.name}
+    Binding(Binding),            // Parsed ${state.user.name} binding
+    TemplateString {             // Template with embedded bindings
+        template: String,
+        bindings: Vec<Binding>,
+    },
     Action(String),              // @actions.signIn
 }
 ```
@@ -292,8 +386,7 @@ pub enum Patch {
     Insert { parent_id, id, before_id? },
     Move { parent_id, id, before_id? },
     Remove { id },
-    AttachEvent { id, event_name },
-    DetachEvent { id, event_name },
+    // Note: Event handling is done at the renderer level
 }
 ```
 
@@ -404,13 +497,26 @@ For client-server streaming:
 # Run all tests
 cargo test
 
-# Run with output
+# Run with output (useful for debugging)
 cargo test -- --nocapture
 
 # Test specific module
 cargo test reactive::
+
+# Test specific file
+cargo test --test test_reactive_graph
+
+# Run tests in parallel (default)
+cargo test --jobs 4
 ```
 
+The test suite includes:
+- Unit tests for each module
+- Integration tests for engine workflows
+- WASM integration tests
+- Reactive dependency tracking tests
+- Reconciliation algorithm tests
+
 ## Contributing
 
 This is part of the Hypen project. See the main repository for contribution guidelines.
@@ -419,7 +525,60 @@ This is part of the Hypen project. See the main repository for contribution guid
 
 See main Hypen project for license information.
 
+## API Reference
+
+### Engine (Rust)
+
+The main `Engine` struct provides the core functionality:
+
+```rust
+impl Engine {
+    pub fn new() -> Self;
+    pub fn register_component(&mut self, component: Component);
+    pub fn set_component_resolver<F>(&mut self, resolver: F);
+    pub fn set_module(&mut self, module: ModuleInstance);
+    pub fn set_render_callback<F>(&mut self, callback: F);
+    pub fn on_action<F>(&mut self, action_name: impl Into<String>, handler: F);
+    pub fn render(&mut self, element: &Element);
+    pub fn update_state(&mut self, state_patch: serde_json::Value);
+    pub fn notify_state_change(&mut self, change: &StateChange);
+    pub fn dispatch_action(&mut self, action: Action) -> Result<(), String>;
+    pub fn revision(&self) -> u64;
+    pub fn component_registry(&self) -> &ComponentRegistry;
+    pub fn resources(&self) -> &ResourceCache;
+}
+```
+
+### Key Exports
+
+```rust
+pub use engine::Engine;
+pub use ir::{ast_to_ir, Element, Value};
+pub use lifecycle::{Module, ModuleInstance};
+pub use reconcile::Patch;
+pub use state::StateChange;
+```
+
 ---
 
-**Status**: ✅ Core systems implemented, WASM integration in progress
-**Next**: Full keyed reconciliation, UniFFI bindings, platform renderers
+## Status
+
+**✅ Implemented:**
+- Core reactive rendering engine
+- Component expansion and registry
+- Dependency tracking and dirty marking
+- Keyed reconciliation algorithm
+- Patch generation
+- Action/event dispatch system
+- Module lifecycle management
+- Resource caching
+- WASM bindings (fully functional)
+- Remote UI serialization
+
+---
+
+## Related Documentation
+
+- [BUILD_WASM.md](./BUILD_WASM.md) - Detailed WASM build instructions
+- [../parser/README.md](../parser/README.md) - Hypen parser documentation
+- [../hypen-render-bun/README.md](../hypen-render-bun/README.md) - Bun renderer implementation

package/wasm-node/hypen_engine.d.ts

@@ -10,7 +10,7 @@ export function patchesToJson(patches: any): string;
 export function parseToJson(source: string): string;
 export function main(): void;
 /**
- * WASM-exported engine instance
+ * WASM-exported engine instance for JavaScript runtimes
  * Uses Rc<RefCell<>> instead of Send+Sync for WASM single-threaded environment
  */
 export class WasmEngine {

package/wasm-node/hypen_engine.js

@@ -249,7 +249,7 @@ const WasmEngineFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmengine_free(ptr >>> 0, 1));
 /**
- * WASM-exported engine instance
+ * WASM-exported engine instance for JavaScript runtimes
  * Uses Rc<RefCell<>> instead of Send+Sync for WASM single-threaded environment
  */
 class WasmEngine {

package/wasm-node/package.json

@@ -1,6 +1,15 @@
 {
   "name": "hypen-engine",
-  "version": "0.1.0",
+  "collaborators": [
+    "Hypen Contributors"
+  ],
+  "description": "A Rust implementation of the Hypen engine",
+  "version": "0.1.2",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypen-lang/hypen-engine-rs"
+  },
   "files": [
     "hypen_engine_bg.wasm",
     "hypen_engine.js",