@hypen-space/core 0.2.1 → 0.2.3

package/src/router.ts

@@ -27,6 +27,7 @@ export class HypenRouter {
   private state: RouteState;
   private subscribers = new Set<RouteChangeCallback>();
   private isInitialized = false;
+  private isUpdating = false;
 
   constructor() {
     // Create observable state for reactivity
@@ -68,6 +69,8 @@ export class HypenRouter {
 
     // Listen for hash changes
     window.addEventListener("hashchange", () => {
+      // Don't respond to hashchange events we triggered ourselves
+      if (this.isUpdating) return;
       const newPath = this.getPathFromBrowser();
       this.updatePath(newPath, false);
     });
@@ -150,26 +153,37 @@ export class HypenRouter {
     updateBrowser: boolean,
     replace: boolean = false
   ) {
-    const oldPath = this.state.currentPath;
-    this.state.previousPath = oldPath;
-    this.state.currentPath = path;
-    this.state.query = this.parseQuery();
-
-    // Update browser URL if needed
-    if (updateBrowser && typeof window !== "undefined") {
-      const url = "#" + path;
-      if (replace) {
-        window.history.replaceState(null, "", url);
-      } else {
-        window.history.pushState(null, "", url);
+    // Prevent re-entrant updates
+    if (this.isUpdating) return;
+
+    this.isUpdating = true;
+    try {
+      const oldPath = this.state.currentPath;
+      this.state.previousPath = oldPath;
+      this.state.currentPath = path;
+      this.state.query = this.parseQuery();
+
+      // Notify subscribers synchronously before any browser events
+      this.notifySubscribers();
+
+      // Update browser URL if needed
+      if (updateBrowser && typeof window !== "undefined") {
+        const url = "#" + path;
+        if (replace) {
+          window.history.replaceState(null, "", url);
+        } else {
+          window.history.pushState(null, "", url);
+        }
+
+        // Manually trigger hashchange event
+        const hashChangeEvent = new HashChangeEvent("hashchange", {
+          oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
+          newURL: window.location.href,
+        });
+        window.dispatchEvent(hashChangeEvent);
       }
-
-      // Manually trigger hashchange event
-      const hashChangeEvent = new HashChangeEvent("hashchange", {
-        oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
-        newURL: window.location.href,
-      });
-      window.dispatchEvent(hashChangeEvent);
+    } finally {
+      this.isUpdating = false;
     }
   }
 
@@ -272,7 +286,11 @@ export class HypenRouter {
     this.subscribers.add(callback);
 
     // Call immediately with current state
-    callback(this.getState());
+    try {
+      callback(this.getState());
+    } catch (error) {
+      console.error("[HypenRouter] Error in route subscriber:", error);
+    }
 
     // Return unsubscribe function
     return () => {
@@ -286,7 +304,11 @@ export class HypenRouter {
   private notifySubscribers() {
     const routeState = this.getState();
     this.subscribers.forEach((callback) => {
-      callback(routeState);
+      try {
+        callback(routeState);
+      } catch (error) {
+        console.error("[HypenRouter] Error in route subscriber:", error);
+      }
     });
   }
 

package/src/state.ts

@@ -91,11 +91,20 @@ function deepClone<T>(obj: T): T {
     // Handle plain objects
     const objClone: any = {};
     visited.set(value, objClone);
+
+    // Clone string keys
     for (const key in value) {
       if (value.hasOwnProperty(key)) {
         objClone[key] = cloneInternal(value[key]);
       }
     }
+
+    // Clone Symbol keys (not enumerable by for...in)
+    const symbolKeys = Object.getOwnPropertySymbols(value);
+    for (const sym of symbolKeys) {
+      objClone[sym] = cloneInternal(value[sym]);
+    }
+
     return objClone;
   }
 
@@ -191,7 +200,14 @@ export function createObservableState<T extends object>(
   // Use default options if not provided
   const opts: StateObserverOptions = options || { onChange: () => {} };
 
+  // Handle null/undefined by using an empty object
+  // This allows modules to start with null state
+  if (initialState === null || initialState === undefined) {
+    initialState = {} as T;
+  }
+
   // Detect and reject primitive wrapper objects (Number, String, Boolean)
+  // These cannot be properly proxied due to internal slots
   if (
     initialState instanceof Number ||
     initialState instanceof String ||
@@ -203,6 +219,10 @@ export function createObservableState<T extends object>(
     );
   }
 
+  // Clone the initial state to ensure each observable has its own copy
+  // This prevents multiple modules from sharing the same underlying state object
+  initialState = deepClone(initialState);
+
   // Keep a snapshot of the last known state
   let lastSnapshot = deepClone(initialState);
   const pathPrefix = opts.pathPrefix || "";

package/wasm-browser/README.md

@@ -0,0 +1,425 @@
+# Hypen Engine
+
+The core reactive rendering engine for Hypen, written in Rust. Compiles to WASM for web/desktop or native binaries with UniFFI for mobile platforms.
+
+## Overview
+
+Hypen Engine is a platform-agnostic UI engine that:
+- **Expands** Hypen DSL components into an intermediate representation (IR)
+- **Tracks** reactive dependencies between state and UI nodes
+- **Reconciles** UI trees efficiently using keyed diffing
+- **Generates** minimal platform-agnostic patches for renderers
+- **Routes** actions and events between UI and application logic
+- **Serializes** for Remote UI scenarios (client-server streaming)
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Hypen Engine                          │
+├─────────────────────────────────────────────────────────┤
+│  Parser → IR → Reactive Graph → Reconciler → Patches   │
+│     ↓                                            ↓       │
+│  Component Registry                    Platform Renderer│
+│  Dependency Tracking                   (Web/iOS/Android)│
+│  State Management                                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Core Systems
+
+1. **IR & Component Expansion** (`src/ir/`)
+   - Canonical intermediate representation
+   - Component registry and resolution
+   - Props/slots expansion with defaults
+   - Stable NodeId generation
+
+2. **Reactive System** (`src/reactive/`)
+   - Dependency graph tracking `${state.*}` bindings
+   - Dirty marking on state changes
+   - Scheduling for efficient updates
+
+3. **Reconciliation** (`src/reconcile/`)
+   - Virtual instance tree (no platform objects)
+   - Keyed children diffing algorithm
+   - Minimal patch generation
+
+4. **Patch Types** (Platform-agnostic):
+   - `Create(id, type, props)` - Create new node
+   - `SetProp(id, name, value)` - Update property
+   - `SetText(id, text)` - Update text content
+   - `Insert(parent, id, before?)` - Insert into tree
+   - `Move(parent, id, before?)` - Reorder node
+   - `Remove(id)` - Remove from tree
+   - `AttachEvent(id, event)` / `DetachEvent(id, event)`
+
+5. **Action/Event Routing** (`src/dispatch/`)
+   - Map `@actions.*` to module handlers
+   - Forward UI events (click, input, etc.)
+   - Stable dispatch contract for SDKs
+
+6. **Lifecycle Management** (`src/lifecycle/`)
+   - Module lifecycle (created/destroyed)
+   - Component lifecycle (mount/unmount)
+   - Resource cache (images/fonts) with pluggable fetcher
+
+7. **Remote UI Serialization** (`src/serialize/`)
+   - Initial tree serialization
+   - Incremental patch streaming
+   - Revision tracking and optional integrity hashes
+   - JSON/CBOR format support
+
+## Usage
+
+### Basic Example
+
+```rust
+use hypen_engine::{Engine, ir::{Element, Value, Component}};
+use serde_json::json;
+
+// Create engine
+let mut engine = Engine::new();
+
+// Register a custom component
+engine.register_component(Component::new("Greeting", |props| {
+    Element::new("Text")
+        .with_prop("text", Value::Binding("${state.name}".to_string()))
+}));
+
+// Set render callback
+engine.set_render_callback(|patches| {
+    for patch in patches {
+        println!("Patch: {:?}", patch);
+    }
+});
+
+// Register action handler
+engine.on_action("greet", |action| {
+    println!("Hello from action: {:?}", action);
+});
+
+// Render UI
+let ui = Element::new("Column")
+    .with_child(Element::new("Greeting"));
+
+engine.render(&ui);
+
+// Update state
+engine.update_state(json!({
+    "name": "Alice"
+}));
+```
+
+### With Module Host
+
+```rust
+use hypen_engine::lifecycle::{Module, ModuleInstance};
+
+// Create module definition
+let module = Module::new("ProfilePage")
+    .with_actions(vec!["signIn".to_string(), "signOut".to_string()])
+    .with_state_keys(vec!["user".to_string()])
+    .with_persist(true);
+
+// Create module instance
+let instance = ModuleInstance::new(
+    module,
+    json!({ "user": null })
+);
+
+engine.set_module(instance);
+```
+
+## Compilation Targets
+
+### Native (Development)
+
+```bash
+cargo build
+cargo test
+```
+
+### WASM (Web/Desktop)
+
+```bash
+# Install wasm-pack (one time)
+cargo install wasm-pack
+
+# Build for all WASM targets
+./build-wasm.sh
+
+# Or build manually for specific targets:
+wasm-pack build --target bundler    # For webpack/vite
+wasm-pack build --target nodejs     # For Node.js
+wasm-pack build --target web        # For vanilla JS
+```
+
+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`)
+
+### JavaScript/TypeScript API
+
+```typescript
+import init, { WasmEngine } from './pkg/web/hypen_engine.js';
+
+// Initialize WASM
+await init();
+
+// Create engine
+const engine = new WasmEngine();
+
+// Set render callback
+engine.setRenderCallback((patches) => {
+    console.log('Patches:', patches);
+    // Apply patches to your renderer
+});
+
+// Register action handlers
+engine.onAction('increment', (action) => {
+    console.log('Increment action:', action);
+});
+
+// Initialize module
+engine.setModule(
+    'CounterModule',
+    ['increment', 'decrement'],
+    ['count'],
+    { count: 0 }
+);
+
+// Render Hypen DSL
+const source = `
+    Column {
+        Text("Count: \${state.count}")
+        Button("@actions.increment") { Text("+1") }
+    }
+`;
+engine.renderSource(source);
+
+// Update state
+engine.updateState({ count: 42 });
+
+// Dispatch action
+engine.dispatchAction('increment', { amount: 1 });
+```
+
+### Testing WASM Build
+
+Open `example.html` in a web server:
+
+```bash
+# Using Python
+python3 -m http.server 8000
+
+# Using Node.js
+npx serve .
+
+# Then visit: http://localhost:8000/example.html
+```
+
+### Mobile (UniFFI)
+
+```bash
+# Generate Swift/Kotlin bindings (coming soon)
+cargo install uniffi_bindgen
+uniffi-bindgen generate src/hypen_engine.udl --language swift
+uniffi-bindgen generate src/hypen_engine.udl --language kotlin
+```
+
+## Project Structure
+
+```
+hypen-engine-rs/
+├── src/
+│   ├── lib.rs              # Public API
+│   ├── engine.rs           # Main orchestrator
+│   ├── wasi.rs             # WASI interfaces
+│   ├── ir/                 # IR & component expansion
+│   │   ├── node.rs         # NodeId, Element, Props, Value
+│   │   ├── component.rs    # Component registry
+│   │   └── expand.rs       # AST → IR lowering
+│   ├── reactive/           # Reactive system
+│   │   ├── binding.rs      # ${state.*} parsing
+│   │   ├── graph.rs        # Dependency tracking
+│   │   └── scheduler.rs    # Dirty marking
+│   ├── reconcile/          # Reconciliation
+│   │   ├── tree.rs         # Instance tree
+│   │   ├── diff.rs         # Diffing algorithm
+│   │   └── patch.rs        # Patch types
+│   ├── dispatch/           # Events & actions
+│   │   ├── action.rs       # Action dispatcher
+│   │   └── event.rs        # Event router
+│   ├── lifecycle/          # Lifecycle
+│   │   ├── module.rs       # Module lifecycle
+│   │   ├── component.rs    # Component lifecycle
+│   │   └── resource.rs     # Resource cache
+│   └── serialize/          # Serialization
+│       └── remote.rs       # Remote UI protocol
+├── Cargo.toml
+└── README.md
+```
+
+## Key Data Structures
+
+### Element (IR Node)
+```rust
+pub struct Element {
+    pub element_type: String,           // "Column", "Text", etc.
+    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
+}
+```
+
+### Value (Props)
+```rust
+pub enum Value {
+    Static(serde_json::Value),  // Literal values
+    Binding(String),             // ${state.user.name}
+    Action(String),              // @actions.signIn
+}
+```
+
+### Patch (Output)
+```rust
+pub enum Patch {
+    Create { id, element_type, props },
+    SetProp { id, name, value },
+    SetText { id, text },
+    Insert { parent_id, id, before_id? },
+    Move { parent_id, id, before_id? },
+    Remove { id },
+    AttachEvent { id, event_name },
+    DetachEvent { id, event_name },
+}
+```
+
+## Integration with Parser
+
+The engine integrates with the Hypen parser from `../parser`:
+
+```rust
+use hypen_parser::parse_component;
+use hypen_engine::ast_to_ir;
+
+let source = r#"
+    Column {
+        Text("Hello, ${state.name}")
+        Button("@actions.greet") { Text("Greet") }
+    }
+"#;
+
+let ast = parse_component(source)?;
+let element = ast_to_ir(&ast); // Convert AST → IR
+engine.render(&element);
+```
+
+### Full Example with Parser
+
+```rust
+use hypen_engine::{Engine, ast_to_ir};
+use hypen_parser::parse_component;
+use serde_json::json;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut engine = Engine::new();
+
+    // Set render callback
+    engine.set_render_callback(|patches| {
+        println!("Patches: {:#?}", patches);
+    });
+
+    // Parse Hypen DSL
+    let source = r#"
+        Column {
+            Text("Count: ${state.count}")
+            Button("@actions.increment") { Text("+1") }
+        }
+    "#;
+
+    let ast = parse_component(source)?;
+    let element = ast_to_ir(&ast);
+
+    // Render
+    engine.render(&element);
+
+    // Update state
+    engine.update_state(json!({"count": 42}));
+
+    Ok(())
+}
+```
+
+## Performance Considerations
+
+- **Keyed reconciliation**: Use `key` props for list items to minimize DOM churn
+- **Dependency tracking**: Only re-render nodes affected by state changes
+- **Lazy evaluation**: Bindings are resolved on-demand during reconciliation
+- **Resource caching**: Images/fonts are cached with configurable eviction
+
+## Remote UI Protocol
+
+For client-server streaming:
+
+```json
+// Initial tree (client connects)
+{
+  "type": "initialTree",
+  "module": "ProfilePage",
+  "state": { "user": null },
+  "patches": [...],
+  "revision": 0
+}
+
+// State update (server → client)
+{
+  "type": "stateUpdate",
+  "module": "ProfilePage",
+  "state": { "user": { "name": "Alice" } }
+}
+
+// Incremental patches (server → client)
+{
+  "type": "patch",
+  "module": "ProfilePage",
+  "patches": [{ "type": "setProp", ... }],
+  "revision": 42
+}
+
+// Action dispatch (client → server)
+{
+  "type": "dispatchAction",
+  "module": "ProfilePage",
+  "action": "signIn",
+  "payload": { "provider": "google" }
+}
+```
+
+## Testing
+
+```bash
+# Run all tests
+cargo test
+
+# Run with output
+cargo test -- --nocapture
+
+# Test specific module
+cargo test reactive::
+```
+
+## Contributing
+
+This is part of the Hypen project. See the main repository for contribution guidelines.
+
+## License
+
+See main Hypen project for license information.
+
+---
+
+**Status**: ✅ Core systems implemented, WASM integration in progress
+**Next**: Full keyed reconciliation, UniFFI bindings, platform renderers