@hypen-space/core 0.2.1 → 0.2.2

package/README.md

@@ -1,6 +1,28 @@
 # @hypen-space/core
 
-Platform-agnostic reactive UI runtime for the Hypen declarative UI language.
+The reactive runtime for Hypen - a declarative UI language that separates what your UI looks like from how it behaves.
+
+## What is Hypen?
+
+Hypen lets you write UI templates in a clean, declarative syntax:
+
+```hypen
+Column {
+  Text("Hello, ${state.user.name}!")
+  Button(onClick: @actions.logout) {
+    Text("Sign Out")
+  }
+}
+```
+
+The `@hypen-space/core` package provides the engine that:
+
+1. **Parses** your Hypen templates
+2. **Tracks** reactive state bindings (like `${state.user.name}`)
+3. **Generates patches** when state changes (instead of re-rendering everything)
+4. **Dispatches actions** triggered from the UI (like `@actions.logout`)
+
+You provide a renderer that applies those patches to your platform (DOM, Canvas, Native, etc).
 
 ## Installation
 
@@ -10,12 +32,54 @@ npm install @hypen-space/core
 bun add @hypen-space/core
 ```
 
+## Core Concepts
+
+### Templates
+
+Hypen templates describe your UI structure. Components can have:
+
+- **Arguments**: `Text("Hello")` or `Button(disabled: true)`
+- **Children**: Nested inside `{ }` braces
+- **Applicators**: Chained styling like `.padding(16).color(blue)`
+
+### State Bindings
+
+Use `${state.path}` to bind template values to your module's state:
+
+```hypen
+Text("Count: ${state.count}")
+Text("User: ${state.user.name}")
+```
+
+When state changes, only the affected parts of the UI update.
+
+### Actions
+
+Use `@actions.name` to dispatch events from the UI to your module:
+
+```hypen
+Button(onClick: @actions.increment) { Text("+") }
+Button(onClick: @actions.submitForm) { Text("Submit") }
+```
+
+### Patches
+
+The engine doesn't manipulate the UI directly. Instead, it emits **patches** - minimal instructions describing what changed:
+
+```typescript
+{ type: "Create", id: "1", elementType: "Text", props: { text: "Hello" } }
+{ type: "SetProp", id: "1", name: "text", value: "Hello, World" }
+{ type: "Remove", id: "1" }
+```
+
+Your renderer applies these patches to the actual platform.
+
 ## Quick Start
 
 ```typescript
 import { Engine, app } from "@hypen-space/core";
 
-// 1. Define a stateful module
+// 1. Define your module's state and actions
 const counter = app
   .defineState({ count: 0 })
   .onAction("increment", ({ state }) => state.count++)
@@ -26,14 +90,14 @@ const counter = app
 const engine = new Engine();
 await engine.init();
 
-// 3. Set up render callback (you provide the renderer)
+// 3. Connect your renderer
 engine.setRenderCallback((patches) => {
-  // Apply patches to your platform (DOM, Canvas, Native, etc.)
   myRenderer.applyPatches(patches);
 });
 
-// 4. Register module and render
+// 4. Register the module and render
 engine.setModule("counter", counter.actions, counter.stateKeys, counter.initialState);
+
 engine.renderSource(`
   Column {
     Text("Count: \${state.count}")
@@ -45,75 +109,9 @@ engine.renderSource(`
 `);
 ```
 
-## Component Discovery
-
-Auto-discover `.hypen` components from the filesystem:
-
-```typescript
-import { discoverComponents, loadDiscoveredComponents, watchComponents } from "@hypen-space/core";
-
-// Discover components in a directory
-const components = await discoverComponents("./src/components", {
-  patterns: ["folder", "sibling", "index"], // Naming conventions
-  recursive: false,
-  debug: true,
-});
-
-// Load discovered components with their modules
-const loaded = await loadDiscoveredComponents(components);
-
-// Watch for changes (hot reload)
-const watcher = watchComponents("./src/components", {
-  onAdd: (c) => console.log("Added:", c.name),
-  onUpdate: (c) => console.log("Updated:", c.name),
-  onRemove: (name) => console.log("Removed:", name),
-  onChange: (all) => console.log("All components:", all.length),
-});
-
-// Stop watching
-watcher.stop();
-```
-
-### Supported Patterns
-
-```
-# Folder-based (recommended)
-Counter/
-├── component.hypen
-└── component.ts
+## Modules
 
-# Sibling files
-Counter.hypen
-Counter.ts
-
-# Index-based
-Counter/
-├── index.hypen
-└── index.ts
-```
-
-## Component Loader
-
-Register and manage components:
-
-```typescript
-import { componentLoader, ComponentLoader } from "@hypen-space/core";
-
-// Use the global loader
-componentLoader.register("Counter", counterModule, counterTemplate);
-componentLoader.get("Counter");        // Get component
-componentLoader.has("Counter");        // Check if exists
-componentLoader.getNames();            // List all names
-
-// Or create your own
-const loader = new ComponentLoader();
-await loader.loadFromDirectory("Counter", "./src/components/Counter");
-await loader.loadFromComponentsDir("./src/components"); // Auto-load all
-```
-
-## Module System
-
-Create stateful modules with the fluent `app` builder:
+Modules manage state and handle actions. Use the `app` builder to define them:
 
 ```typescript
 import { app } from "@hypen-space/core";
@@ -126,13 +124,13 @@ interface UserState {
 const userModule = app
   .defineState<UserState>({ user: null, loading: false })
 
-  // Lifecycle hooks
+  // Called when module is created
   .onCreated(async ({ state, next }) => {
     state.loading = true;
-    next(); // Sync state to engine
+    next(); // Sync state changes to engine
   })
 
-  // Action handlers
+  // Handle actions dispatched from UI
   .onAction("loadUser", async ({ state, action, next }) => {
     const userId = action.payload?.id;
     state.user = await fetchUser(userId);
@@ -145,16 +143,19 @@ const userModule = app
     next();
   })
 
+  // Called when module is destroyed
   .onDestroyed(({ state }) => {
-    console.log("Module cleanup");
+    console.log("Cleanup");
   })
 
   .build();
 ```
 
-## State Management
+The `next()` callback synchronizes state changes with the engine after async operations.
+
+## State
 
-Observable state with automatic change tracking:
+State is automatically tracked via Proxy. Mutations trigger UI updates:
 
 ```typescript
 import { createObservableState, batchStateUpdates, getStateSnapshot } from "@hypen-space/core";
@@ -169,19 +170,50 @@ const state = createObservableState({ count: 0, items: [] }, {
 state.count = 5;
 state.items.push("item");
 
-// Batch multiple updates
+// Batch multiple updates into one render cycle
 batchStateUpdates(state, () => {
   state.count = 10;
   state.items = ["a", "b", "c"];
 });
 
-// Get immutable snapshot
+// Get an immutable snapshot
 const snapshot = getStateSnapshot(state);
 ```
 
+## Custom Renderers
+
+Extend `BaseRenderer` to render to any platform:
+
+```typescript
+import { BaseRenderer } from "@hypen-space/core";
+
+class MyRenderer extends BaseRenderer {
+  protected onCreate(id: string, type: string, props: Record<string, any>) {
+    // Create an element
+  }
+  protected onSetProp(id: string, name: string, value: any) {
+    // Update a property
+  }
+  protected onSetText(id: string, text: string) {
+    // Set text content
+  }
+  protected onInsert(parentId: string, id: string, beforeId?: string) {
+    // Insert into parent
+  }
+  protected onMove(parentId: string, id: string, beforeId?: string) {
+    // Reorder element
+  }
+  protected onRemove(id: string) {
+    // Remove element
+  }
+}
+```
+
+See `@hypen-space/web` for a DOM renderer implementation.
+
 ## Routing
 
-Built-in hash-based or pathname-based routing:
+Built-in hash or pathname routing:
 
 ```typescript
 import { HypenRouter } from "@hypen-space/core";
@@ -191,46 +223,90 @@ const router = new HypenRouter();
 router.navigate("/products/123");
 
 router.subscribe((state) => {
-  console.log("Route:", state.currentPath);
-  console.log("Params:", state.params);
+  console.log("Path:", state.currentPath);
+  console.log("Params:", state.params);   // { id: "123" }
   console.log("Query:", state.query);
 });
 ```
 
-## Built-in Components
+Use built-in components in templates:
 
-Framework-provided components for routing:
+```hypen
+Router {
+  Route(path: "/") { HomePage }
+  Route(path: "/products/:id") { ProductPage }
+}
+Link(to: "/products/42") { Text("View Product") }
+```
+
+## Component Discovery
+
+For larger apps, organize components as files and auto-discover them:
 
 ```typescript
-import { Router, Route, Link } from "@hypen-space/core";
-
-// Use in templates:
-// Router {
-//   Route(path: "/") { HomePage }
-//   Route(path: "/products") { ProductList }
-// }
-// Link(to: "/products") { Text("View Products") }
+import { discoverComponents, loadDiscoveredComponents } from "@hypen-space/core";
+
+const components = await discoverComponents("./src/components");
+const loaded = await loadDiscoveredComponents(components);
 ```
 
-## Remote UI (WebSocket)
+Supported file patterns:
+
+```
+Counter/
+├── component.hypen    # Template
+└── component.ts       # Module
 
-Connect to a remote Hypen server:
+Counter.hypen          # Or sibling files
+Counter.ts
+
+Counter/
+├── index.hypen        # Or index-based
+└── index.ts
+```
+
+Watch for changes (hot reload):
+
+```typescript
+import { watchComponents } from "@hypen-space/core";
+
+const watcher = watchComponents("./src/components", {
+  onUpdate: (c) => console.log("Updated:", c.name),
+});
+```
+
+## Component Loader
+
+Register components programmatically:
+
+```typescript
+import { componentLoader, ComponentLoader } from "@hypen-space/core";
+
+// Global loader
+componentLoader.register("Counter", counterModule, counterTemplate);
+componentLoader.get("Counter");
+componentLoader.has("Counter");
+
+// Or create your own
+const loader = new ComponentLoader();
+await loader.loadFromComponentsDir("./src/components");
+```
+
+## Remote UI
+
+Connect to a Hypen server for server-driven UI:
 
 ```typescript
 import { RemoteEngine } from "@hypen-space/core";
 
 const remote = new RemoteEngine("ws://localhost:3000", {
   autoReconnect: true,
-  reconnectInterval: 3000,
-  maxReconnectAttempts: 10,
 });
 
 remote
   .onPatches((patches) => renderer.applyPatches(patches))
   .onStateUpdate((state) => console.log("Server state:", state))
-  .onConnect(() => console.log("Connected"))
-  .onDisconnect(() => console.log("Disconnected"))
-  .onError((error) => console.error("Error:", error));
+  .onConnect(() => console.log("Connected"));
 
 await remote.connect();
 remote.dispatchAction("loadData", { page: 1 });
@@ -238,86 +314,55 @@ remote.dispatchAction("loadData", { page: 1 });
 
 ## Global Context
 
-Cross-module communication:
+Share state and events across modules:
 
 ```typescript
 import { HypenGlobalContext } from "@hypen-space/core";
 
 const context = new HypenGlobalContext();
 
-context.registerModule("auth", authModuleInstance);
-context.registerModule("cart", cartModuleInstance);
+context.registerModule("auth", authModule);
+context.registerModule("cart", cartModule);
 
-const auth = context.getModule("auth");
-const cartState = context.getModule("cart").getState();
+// Cross-module access
+const user = context.getModule("auth").getState().user;
 
-// Event system
-context.on("userLoggedIn", (user) => console.log("Logged in:", user));
+// Event bus
+context.on("userLoggedIn", (user) => { /* ... */ });
 context.emit("userLoggedIn", { id: "1", name: "Ian" });
 ```
 
-## Custom Renderer
-
-Implement the `Renderer` interface for any platform:
+## Browser vs Node.js
 
 ```typescript
-import { BaseRenderer, type Patch } from "@hypen-space/core";
+// Node.js / Bundler - WASM loads automatically
+import { Engine } from "@hypen-space/core";
+const engine = new Engine();
+await engine.init();
 
-class MyRenderer extends BaseRenderer {
-  protected onCreate(id: string, type: string, props: Record<string, any>) {
-    // Create element
-  }
-  protected onSetProp(id: string, name: string, value: any) {
-    // Set property
-  }
-  protected onSetText(id: string, text: string) {
-    // Set text
-  }
-  protected onInsert(parentId: string, id: string, beforeId?: string) {
-    // Insert into parent
-  }
-  protected onMove(parentId: string, id: string, beforeId?: string) {
-    // Move element
-  }
-  protected onRemove(id: string) {
-    // Remove element
-  }
-}
+// Browser - specify WASM path
+import { BrowserEngine } from "@hypen-space/core";
+const engine = new BrowserEngine();
+await engine.init({ wasmPath: "/hypen_engine_bg.wasm" });
 ```
 
-## Exports
+## Package Exports
 
 | Export | Description |
 |--------|-------------|
-| `@hypen-space/core` | Main entry - Engine, app, state, router, discovery, loader |
-| `@hypen-space/core/engine` | Low-level WASM engine API |
-| `@hypen-space/core/engine/browser` | Browser-optimized engine (explicit WASM init) |
-| `@hypen-space/core/app` | Module builder and HypenModuleInstance |
+| `@hypen-space/core` | Main entry point |
+| `@hypen-space/core/engine` | Low-level WASM engine |
+| `@hypen-space/core/engine/browser` | Browser-optimized engine |
+| `@hypen-space/core/app` | Module builder |
 | `@hypen-space/core/state` | Observable state utilities |
-| `@hypen-space/core/renderer` | Abstract renderer interface |
+| `@hypen-space/core/renderer` | Abstract renderer |
 | `@hypen-space/core/router` | Routing system |
-| `@hypen-space/core/events` | Typed event emitter |
 | `@hypen-space/core/context` | Global context |
 | `@hypen-space/core/remote` | Remote UI protocol |
-| `@hypen-space/core/remote/client` | WebSocket client |
 | `@hypen-space/core/loader` | Component loader |
 | `@hypen-space/core/discovery` | Component discovery |
 | `@hypen-space/core/components` | Built-in Router, Route, Link |
 
-## Browser vs Node.js
-
-```typescript
-// Node.js / Bundler (auto WASM init)
-import { Engine } from "@hypen-space/core";
-const engine = new Engine();
-await engine.init();
-
-// Browser (explicit WASM path)
-import { BrowserEngine } from "@hypen-space/core";
-const engine = new BrowserEngine();
-await engine.init({ wasmPath: "/hypen_engine_bg.wasm" });
-```
-
 ## Requirements
 
 - Node.js >= 18.0.0

package/package.json

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