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.

Quick Start

Rust

use hypen_engine::{Engine, ast_to_ir_node};
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_ir_node(&ast_to_ir_node(&ast));
engine.update_state(json!({ "count": 42 }));

JavaScript/TypeScript (WASM)

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}") }`);

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, 9 total):

   • Create(id, type, props) - Create new node
   • SetProp(id, name, value) - Update property
   • RemoveProp(id, name) - Remove a property
   • SetText(id, text) - Update text content (reserved; reconciler emits SetProp for the positional text slot)
   • Insert(parent, id, before?) - Insert into tree
   • Move(parent, id, before?) - Reorder node
   • Remove(id) - Remove from tree
   • Detach(id) - Unlink subtree but keep native element alive (Router cache)
   • Attach(parent, id, before?) - Reattach a previously-detached subtree
   • Event handling is managed at the renderer level

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 format support

Usage

Basic Example

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
// Note: In practice, you'd typically parse Hypen DSL with ast_to_ir_node
engine.register_component(Component::new("Greeting", |props: IndexMap<String, serde_json::Value>| {
    Element::new("Text")
        .with_prop("text", Value::Binding(
            parse_binding("@{state.name}").expect("valid binding")
        ))
}));

// 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

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)

cargo build
cargo test

WASM (Web/Desktop)

The WASM build is fully functional and tested. Run ./build-wasm.sh to build all targets (bundler, nodejs, web).

Quick Start:

# 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/rollup
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)

Build to custom directory:

# Build directly to your renderer project
wasm-pack build --target bundler --out-dir ../hypen-web/packages/web-engine/wasm-browser

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:

import init, { WasmEngine } from './pkg/web/hypen_engine.js';

// Initialize WASM (required before creating engine)
await init();

// Create engine instance
const engine = new WasmEngine();

// Set render callback to receive patches
engine.setRenderCallback((patches) => {
    console.log('Patches:', patches);
    // Apply patches to your platform renderer
    applyPatchesToDOM(patches);
});

// Register action handlers
engine.onAction('increment', (action) => {
    console.log('Action received:', action.name, action.payload);
    // Handle action (e.g., update state)
    engine.updateState({ count: action.payload.count + 1 });
});

// Initialize module with state and actions
engine.setModule(
    'CounterModule',           // Module name
    ['increment', 'decrement'], // Available actions
    ['count'],                  // State keys
    { count: 0 }                // Initial state
);

// Render Hypen DSL source code
const source = `
    Column {
        Text("Count: @{state.count}")
        Button("@actions.increment") { Text("+1") }
    }
`;
engine.renderSource(source);

// Update state (triggers reactive re-render)
engine.updateState({ count: 42 });

// 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

Testing WASM Build

Open example.html in a web server:

# Using Python
python3 -m http.server 8000

# Using Node.js
npx serve .

# Then visit: http://localhost:8000/example.html

Mobile (UniFFI)

UniFFI bindings for native mobile platforms ship behind the uniffi feature flag (see src/uniffi/). They power the Kotlin (hypen-kotlin) and Swift (hypen-server-swift) SDKs today.

# Build the engine with UniFFI support
cargo build --features uniffi --release

# Generate Swift/Kotlin bindings via the generated uniffi-bindgen binary
cargo run --features uniffi --bin uniffi-bindgen -- generate --library target/release/libhypen_engine.dylib --language kotlin --out-dir out/kotlin
cargo run --features uniffi --bin uniffi-bindgen -- generate --library target/release/libhypen_engine.dylib --language swift  --out-dir out/swift

Non-UniFFI mobile targets can still consume the WASM build via WebView or native WASM runtimes.

Project Structure

hypen-engine-rs/
├── src/
│   ├── lib.rs              # Public API exports
│   ├── engine.rs           # Main Engine orchestrator
│   ├── engine_core.rs      # Shared core engine logic
│   ├── state.rs            # State change tracking
│   ├── render.rs           # Dirty node rendering
│   ├── error.rs            # EngineError type
│   ├── logger.rs           # Logging utilities
│   ├── wasm/               # WASM bindings (multi-binding)
│   │   ├── mod.rs          # Binding selection (js vs wasi)
│   │   ├── shared.rs       # Binding-agnostic helpers
│   │   ├── ffi.rs          # Shared FFI data types
│   │   ├── js.rs           # wasm-bindgen JS bindings (js feature)
│   │   └── wasi.rs         # WASI C FFI (wasi feature)
│   ├── uniffi/             # UniFFI bindings (uniffi feature)
│   ├── ir/                 # IR & component expansion
│   │   ├── mod.rs          # Module exports
│   │   ├── node.rs         # NodeId, Element, Props, Value, IRNode
│   │   ├── component.rs    # Component registry & resolution
│   │   ├── icon.rs         # SVG icon parsing + ResourceRegistry
│   │   ├── walk.rs         # IR tree walkers
│   │   └── expand.rs       # AST → IR lowering
│   ├── reactive/           # Reactive system
│   │   ├── mod.rs          # Module exports
│   │   ├── binding.rs      # @{state.*} parsing
│   │   ├── expression.rs   # Expression evaluation (exprimo)
│   │   ├── graph.rs        # Dependency tracking
│   │   └── scheduler.rs    # Dirty marking & scheduling
│   ├── reconcile/          # Reconciliation
│   │   ├── mod.rs          # Module exports
│   │   ├── tree.rs         # Instance tree (virtual DOM) + Router subtree cache
│   │   ├── diff.rs         # Keyed diffing algorithm
│   │   ├── keyed.rs        # Keyed list reconciliation
│   │   ├── conditionals.rs # When/If + Router route matching
│   │   ├── item_bindings.rs# ForEach iteration context
│   │   ├── resolve.rs      # Value resolution
│   │   └── patch.rs        # 9 Patch variants
│   ├── dispatch/           # Events & actions
│   ├── lifecycle/          # Lifecycle management (module/component/resource)
│   ├── portable/           # Canonical helpers shared with every SDK (route match, session, path, url, diff)
│   └── serialize/          # Remote UI protocol (initial tree + incremental patches)
├── tests/                  # Integration tests
├── benches/                # Criterion benchmarks
├── wit/                    # WIT interfaces (component-model feature)
├── Cargo.toml              # Rust dependencies
├── build-wasm.sh           # WASM build script
├── example.html            # WASM demo page
└── README.md               # This file

Key Data Structures

Element (IR Node)

pub struct Element {
    pub element_type: String,               // "Column", "Text", etc.
    pub props: Props,                       // Arc<IndexMap<String, Value>>
    pub children: im::Vector<Arc<Element>>, // Child elements (O(1) clone)
    pub ir_children: Vec<IRNode>,           // Control-flow nodes (ForEach, When)
    pub key: Option<String>,                // For reconciliation
    // Note: Event handling is done at the renderer level, not in IR
}

Value (Props)

pub enum Value {
    Static(serde_json::Value),  // Literal values
    Binding(Binding),            // Parsed @{state.user.name} binding
    TemplateString {             // Template with embedded bindings
        template: String,
        bindings: Vec<Binding>,
    },
    Action(String),              // @actions.signIn
}

Patch (Output)

pub enum Patch {
    Create { id, element_type, props },
    SetProp { id, name, value },
    RemoveProp { id, name },
    SetText { id, text },                             // reserved; reconciler emits SetProp for text
    Insert { parent_id, id, before_id? },
    Move { parent_id, id, before_id? },
    Remove { id },
    Detach { id },                                    // unlink but keep alive (Router cache)
    Attach { parent_id, id, before_id? },             // reinsert a previously-detached subtree
    // Note: Event handling is done at the renderer level, not via patches.
}

Integration with Parser

The engine integrates with the Hypen parser from ../parser:

use hypen_parser::parse_component;
use hypen_engine::ast_to_ir_node;

let source = r#"
    Column {
        Text("Hello, @{state.name}")
        Button("@actions.greet") { Text("Greet") }
    }
"#;

let ast = parse_component(source)?;
let ir_node = ast_to_ir_node(&ast); // Convert AST → IR
engine.render_ir_node(&ir_node);

Full Example with Parser

use hypen_engine::{Engine, ast_to_ir_node};
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 ir_node = ast_to_ir_node(&ast);

    // Render
    engine.render_ir_node(&ir_node);

    // 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:

// 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

# Run all tests
cargo test

# 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.

License

See main Hypen project for license information.

API Reference

Engine (Rust)

The main Engine struct provides the core functionality:

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<(), EngineError>;
    pub fn revision(&self) -> u64;
    pub fn component_registry(&self) -> &ComponentRegistry;
    pub fn resources(&self) -> &ResourceCache;
}

Key Exports

pub use engine::Engine;
pub use ir::{ast_to_ir_node, Element, IRNode, Value};
pub use lifecycle::{Module, ModuleInstance};
pub use reconcile::Patch;
pub use state::StateChange;

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

• Documentation Index - Full documentation index
• Control Flow Components - ForEach, When/If, Map usage guide
• Router - Declarative routing and navigation
• Architecture Internals - Reactive system, reconciliation, IR
• Advanced SDK Usage - Custom renderers, component resolvers, Remote UI
• Glossary - Key terms and binding syntax reference
• Browser Compatibility - Browser, platform, and WASM target support
• ../parser/README.md - Hypen parser documentation