# CLAUDE.md
This file provides guidance to Claude Code when working with the Hypen engine crate.
## Project Overview
`hypen-engine` is the core reactive rendering engine for Hypen. It takes parsed AST, expands it into IR, tracks reactive dependencies, reconciles changes via keyed diffing, and emits minimal patches for platform renderers to apply.
## Module Structure
```
hypen-engine-rs/src/
├── lib.rs # Public API exports
├── engine.rs # Engine struct — main orchestrator
├── error.rs # EngineError type
├── state.rs # StateChange notifications
├── render.rs # Dirty node rendering logic
├── logger.rs # Debug logging
│
├── ir/ # Intermediate Representation
│ ├── node.rs # Element, Value, Props, NodeId
│ ├── component.rs # ComponentRegistry, resolution
│ └── expand.rs # AST → IR lowering
│
├── reactive/ # Dependency Tracking
│ ├── binding.rs # ${state.x} syntax parsing
│ ├── expression.rs # Expression evaluation (exprimo)
│ ├── graph.rs # Dependency graph
│ └── scheduler.rs # Dirty marking and scheduling
│
├── reconcile/ # Virtual DOM Diffing
│ ├── tree.rs # Virtual instance tree
│ ├── diff.rs # Keyed children diffing
│ ├── patch.rs # Patch enum (Create, SetProp, SetText, Insert, Move, Remove)
│ ├── resolve.rs # Value resolution during reconciliation
│ ├── conditionals.rs # When/If control flow
│ ├── keyed.rs # Keyed list reconciliation
│ └── item_bindings.rs # ForEach iteration context
│
├── dispatch/ # Events & Actions
│ ├── action.rs # Action dispatcher for @actions.xxx
│ └── event.rs # Event routing
│
├── lifecycle/ # Lifecycle Management
│ ├── module.rs # Module lifecycle (created/destroyed)
│ ├── component.rs # Component lifecycle (mount/unmount)
│ └── resource.rs # Resource cache
│
├── serialize/ # Remote UI Protocol
│ └── remote.rs # Initial tree & incremental patch serialization
│
├── wasm/ # Language Bindings
│ ├── ffi.rs # Shared FFI types
│ ├── js.rs # wasm-bindgen JS bindings (js feature)
│ └── wasi.rs # WASI C FFI (wasi feature)
│
└── uniffi/ # Mobile Bindings
└── mod.rs # UniFFI scaffolding (uniffi feature)
```
## Development Commands
```bash
cargo test # Run all tests
RUST_BACKTRACE=1 cargo test -- --nocapture # Tests with backtrace
cargo clippy # Lint
cargo bench # Benchmarks (criterion)
./build-wasm.sh # Build all WASM targets
```
## Public API
```rust
pub use engine::Engine;
pub use error::EngineError;
pub use ir::{ast_to_ir_node, Element, IRNode, Value};
pub use lifecycle::{Module, ModuleInstance};
pub use reconcile::Patch;
pub use state::StateChange;
```
## Architecture
```
Hypen DSL Source
↓ (hypen-parser)
AST (ComponentSpecification)
↓ (ir/expand.rs)
IR (Element/IRNode tree)
↓ (reactive/graph.rs)
Dependency Graph
↓ (reconcile/diff.rs)
Virtual Instance Tree → Patches
↓
Platform Renderer (DOM, Canvas, iOS, Android)
```
### Key Design Decisions
- **Path-Based Reactivity**: Dependencies tracked by string paths (`"user.name"`, `"items.0.title"`), not values. The host signals which paths changed.
- **Arc-Based Cloning**: `Arc<IndexMap>` for O(1) cloning. Extensive cloning per render cycle is intentional.
- **First-Class Control Flow**: ForEach/When/If are IR-level types with exhaustive pattern matching.
- **Keyed Reconciliation**: List diffing uses keys to produce minimal Create/Move/Remove patches.
## Feature Flags
| (none) | `.rlib` | Rust embedding |
| `js` | WASM (wasm-bindgen) | Web (bundler, Node.js, browser) |
| `wasi` | C FFI | Go, Python, native |
| `component-model` | WIT bindings | Type-safe cross-language |
| `uniffi` | Kotlin/Swift bindings | Android, iOS |
## Key Dependencies
- `hypen-parser` — upstream AST
- `hypen-tailwind-parse` — Tailwind CSS support
- `indexmap` — ordered property maps
- `im` — persistent/immutable data structures
- `slotmap` — slot allocation for node IDs
- `exprimo` — expression evaluation for `${...}` bindings