@hypen-space/core 0.2.2 → 0.2.4

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

package/wasm-browser/hypen_engine.d.ts

@@ -0,0 +1,151 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Export patches as JSON string (for debugging)
+ */
+export function patchesToJson(patches: any): string;
+/**
+ * Parse Hypen DSL and return AST as JSON
+ */
+export function parseToJson(source: string): string;
+export function main(): void;
+/**
+ * WASM-exported engine instance
+ * Uses Rc<RefCell<>> instead of Send+Sync for WASM single-threaded environment
+ */
+export class WasmEngine {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Create a new engine instance
+   */
+  constructor();
+  /**
+   * Parse and render Hypen DSL source code
+   */
+  renderSource(source: string): void;
+  /**
+   * Set the render callback that receives patches
+   */
+  setRenderCallback(callback: Function): void;
+  /**
+   * Set the component resolver callback
+   * The resolver receives (componentName, contextPath) and should return
+   * { source: string, path: string } or null
+   *
+   * contextPath is the path of the component that's referencing this component
+   * The returned path should be the resolved absolute path to the component file
+   */
+  setComponentResolver(resolver: Function): void;
+  /**
+   * Register a primitive element (like Text, Button, etc.) to skip component resolution
+   * This prevents unnecessary resolver calls for built-in DOM elements
+   */
+  registerPrimitive(name: string): void;
+  /**
+   * Render a component source (for lazy loading routes)
+   * This allows rendering a component on-demand
+   */
+  renderLazyComponent(source: string): void;
+  /**
+   * Render a component into a specific parent node (subtree rendering)
+   * This is used for lazy routing where components are rendered on-demand into route containers
+   *
+   * # Arguments
+   * * `source` - The Hypen DSL source to parse and render
+   * * `parent_node_id_str` - The serialized node ID string of the parent element
+   * * `state_js` - The state to use for rendering (as JsValue)
+   */
+  renderInto(source: string, parent_node_id_str: string, state_js: any): void;
+  /**
+   * Update state from JavaScript
+   */
+  updateState(state_patch: any): void;
+  /**
+   * Update state using sparse path-value pairs
+   * More efficient than updateState for large state objects when only a few paths changed
+   *
+   * # Arguments
+   * * `paths_js` - Array of changed paths (e.g., ["user.name", "count"])
+   * * `values_js` - Object mapping paths to their new values (e.g., { "user.name": "Bob", "count": 42 })
+   */
+  updateStateSparse(paths_js: any, values_js: any): void;
+  /**
+   * Dispatch an action
+   */
+  dispatchAction(name: string, payload: any): void;
+  /**
+   * Register an action handler
+   */
+  onAction(action_name: string, handler: Function): void;
+  /**
+   * Clear the engine tree (useful when switching samples)
+   */
+  clearTree(): void;
+  /**
+   * Debug method to inspect parsed components
+   */
+  debugParseComponent(source: string): string;
+  /**
+   * Initialize a module
+   */
+  setModule(name: string, actions: string[], state_keys: string[], initial_state: any): void;
+  /**
+   * Get the current revision number
+   */
+  getRevision(): bigint;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly __wbg_wasmengine_free: (a: number, b: number) => void;
+  readonly wasmengine_new: () => number;
+  readonly wasmengine_setRenderCallback: (a: number, b: any) => void;
+  readonly wasmengine_setComponentResolver: (a: number, b: any) => void;
+  readonly wasmengine_registerPrimitive: (a: number, b: number, c: number) => void;
+  readonly wasmengine_renderLazyComponent: (a: number, b: number, c: number) => [number, number];
+  readonly wasmengine_renderInto: (a: number, b: number, c: number, d: number, e: number, f: any) => [number, number];
+  readonly wasmengine_updateState: (a: number, b: any) => [number, number];
+  readonly wasmengine_updateStateSparse: (a: number, b: any, c: any) => [number, number];
+  readonly wasmengine_dispatchAction: (a: number, b: number, c: number, d: any) => [number, number];
+  readonly wasmengine_onAction: (a: number, b: number, c: number, d: any) => void;
+  readonly wasmengine_clearTree: (a: number) => void;
+  readonly wasmengine_debugParseComponent: (a: number, b: number, c: number) => [number, number, number, number];
+  readonly wasmengine_setModule: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: any) => [number, number];
+  readonly wasmengine_getRevision: (a: number) => bigint;
+  readonly patchesToJson: (a: any) => [number, number, number, number];
+  readonly parseToJson: (a: number, b: number) => [number, number, number, number];
+  readonly main: () => void;
+  readonly wasmengine_renderSource: (a: number, b: number, c: number) => [number, number];
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_export_2: WebAssembly.Table;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __externref_table_dealloc: (a: number) => void;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;