@hypen-space/core 0.2.0

package/src/engine.browser.ts

@@ -0,0 +1,245 @@
+/**
+ * Browser-compatible wrapper around the WASM engine
+ * Uses web target for browser environments
+ */
+
+// Dynamic import path - will be configured at build time
+// For browser, the WASM needs to be served and initialized explicitly
+let wasmInit: ((path?: string) => Promise<void>) | null = null;
+let WasmEngineClass: any = null;
+
+export type Patch = {
+  type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
+  id?: string;
+  element_type?: string;
+  props?: Record<string, any> | Map<string, any>;
+  name?: string;
+  value?: any;
+  text?: string;
+  parent_id?: string;
+  before_id?: string;
+  event_name?: string;
+};
+
+export type Action = {
+  name: string;
+  payload?: any;
+  sender?: string;
+};
+
+export type RenderCallback = (patches: Patch[]) => void;
+export type ActionHandler = (action: Action) => void | Promise<void>;
+
+export type ResolvedComponent = {
+  source: string;
+  path: string;
+};
+
+export type ComponentResolver = (
+  componentName: string,
+  contextPath: string | null
+) => ResolvedComponent | null;
+
+export interface EngineInitOptions {
+  /** Path to the WASM file (default: "/hypen_engine_bg.wasm") */
+  wasmPath?: string;
+}
+
+/**
+ * Recursively convert Maps and nested structures to plain objects
+ */
+function mapToObject(value: any): any {
+  if (value instanceof Map) {
+    const obj: Record<string, any> = {};
+    for (const [key, val] of value.entries()) {
+      obj[key] = mapToObject(val);
+    }
+    return obj;
+  } else if (Array.isArray(value)) {
+    return value.map(mapToObject);
+  } else if (value && typeof value === 'object' && value.constructor === Object) {
+    const obj: Record<string, any> = {};
+    for (const [key, val] of Object.entries(value)) {
+      obj[key] = mapToObject(val);
+    }
+    return obj;
+  }
+  return value;
+}
+
+/**
+ * Engine wraps the WASM engine and provides a TypeScript-friendly API
+ * Browser version with explicit WASM initialization
+ */
+export class Engine {
+  private wasmEngine: any = null;
+  private initialized = false;
+
+  /**
+   * Initialize the WASM module
+   * @param options - Initialization options including wasmPath
+   */
+  async init(options: EngineInitOptions = {}): Promise<void> {
+    if (this.initialized) return;
+
+    const wasmPath = options.wasmPath ?? "/hypen_engine_bg.wasm";
+
+    // Dynamically import the WASM module
+    // This allows the path to be configured at runtime
+    try {
+      // @ts-expect-error WASM module is generated at build time
+      const wasmModule = await import("../wasm/hypen_engine.js");
+      wasmInit = wasmModule.default;
+      WasmEngineClass = wasmModule.WasmEngine;
+
+      // Initialize WASM with explicit path
+      await wasmInit!(wasmPath);
+
+      this.wasmEngine = new WasmEngineClass();
+      this.initialized = true;
+    } catch (error) {
+      console.error("[Hypen] Failed to initialize WASM engine:", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Ensure the engine is initialized before operations
+   */
+  private ensureInitialized(): any {
+    if (!this.wasmEngine) {
+      throw new Error("Engine not initialized. Call init() first.");
+    }
+    return this.wasmEngine;
+  }
+
+  /**
+   * Set the render callback that receives patches
+   */
+  setRenderCallback(callback: RenderCallback): void {
+    const engine = this.ensureInitialized();
+    engine.setRenderCallback((patches: Patch[]) => {
+      callback(patches);
+    });
+  }
+
+  /**
+   * Set the component resolver for dynamic component composition
+   */
+  setComponentResolver(resolver: ComponentResolver): void {
+    const engine = this.ensureInitialized();
+    engine.setComponentResolver((componentName: string, contextPath: string | null) => {
+      const result = resolver(componentName, contextPath);
+      return result;
+    });
+  }
+
+  /**
+   * Parse and render Hypen DSL source code
+   */
+  renderSource(source: string): void {
+    const engine = this.ensureInitialized();
+    engine.renderSource(source);
+  }
+
+  /**
+   * Render a lazy component (for lazy route loading)
+   */
+  renderLazyComponent(source: string): void {
+    const engine = this.ensureInitialized();
+    engine.renderLazyComponent(source);
+  }
+
+  /**
+   * Render a component into a specific parent node (subtree rendering)
+   */
+  renderInto(source: string, parentNodeId: string, state: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+    const safeState = JSON.parse(JSON.stringify(state));
+    engine.renderInto(source, parentNodeId, safeState);
+  }
+
+  /**
+   * Notify the engine of state changes
+   */
+  notifyStateChange(paths: string[], currentState: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+
+    const plainObject = JSON.parse(JSON.stringify(currentState));
+    engine.updateState(plainObject);
+
+    if (paths.length > 0) {
+      console.debug("[Hypen] State changed:", paths);
+    }
+  }
+
+  /**
+   * Update state (triggers re-render of affected nodes)
+   * @deprecated Use notifyStateChange instead
+   */
+  updateState(statePatch: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+    const plainObject = JSON.parse(JSON.stringify(statePatch));
+    engine.updateState(plainObject);
+  }
+
+  /**
+   * Dispatch an action
+   */
+  dispatchAction(name: string, payload?: any): void {
+    const engine = this.ensureInitialized();
+    console.log(`[Engine] Action dispatched: ${name}`);
+    engine.dispatchAction(name, payload ?? null);
+  }
+
+  /**
+   * Register an action handler
+   */
+  onAction(actionName: string, handler: ActionHandler): void {
+    const engine = this.ensureInitialized();
+    engine.onAction(actionName, (action: Action) => {
+      const normalizedAction: Action = {
+        ...action,
+        payload: action.payload ? mapToObject(action.payload) : action.payload,
+      };
+      Promise.resolve(handler(normalizedAction)).catch(console.error);
+    });
+  }
+
+  /**
+   * Initialize a module
+   */
+  setModule(
+    name: string,
+    actions: string[],
+    stateKeys: string[],
+    initialState: Record<string, any>
+  ): void {
+    const engine = this.ensureInitialized();
+    engine.setModule(name, actions, stateKeys, initialState);
+  }
+
+  /**
+   * Get the current revision number
+   */
+  getRevision(): bigint {
+    const engine = this.ensureInitialized();
+    return engine.getRevision();
+  }
+
+  /**
+   * Clear the engine tree
+   */
+  clearTree(): void {
+    const engine = this.ensureInitialized();
+    engine.clearTree();
+  }
+
+  /**
+   * Debug method to inspect parsed components
+   */
+  debugParseComponent(source: string): string {
+    const engine = this.ensureInitialized();
+    return engine.debugParseComponent(source);
+  }
+}

package/src/engine.ts

@@ -0,0 +1,208 @@
+/**
+ * Low-level wrapper around the WASM engine
+ * Node.js / Bundler target
+ */
+
+// @ts-expect-error WASM module is generated at build time
+import { WasmEngine } from "../wasm/hypen_engine.js";
+
+export type Patch = {
+  type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
+  id?: string;
+  elementType?: string;
+  props?: Record<string, any>;
+  name?: string;
+  value?: any;
+  text?: string;
+  parentId?: string;
+  beforeId?: string;
+  eventName?: string;
+};
+
+export type Action = {
+  name: string;
+  payload?: any;
+  sender?: string;
+};
+
+export type RenderCallback = (patches: Patch[]) => void;
+export type ActionHandler = (action: Action) => void | Promise<void>;
+
+export type ResolvedComponent = {
+  source: string;
+  path: string;
+};
+
+export type ComponentResolver = (
+  componentName: string,
+  contextPath: string | null
+) => ResolvedComponent | null;
+
+/**
+ * Engine wraps the WASM engine and provides a TypeScript-friendly API
+ */
+export class Engine {
+  private wasmEngine: WasmEngine | null = null;
+  private initialized = false;
+
+  /**
+   * Initialize the WASM module
+   */
+  async init(): Promise<void> {
+    if (this.initialized) return;
+
+    // For bundler target, WASM is auto-initialized
+    this.wasmEngine = new WasmEngine();
+    this.initialized = true;
+  }
+
+  /**
+   * Ensure the engine is initialized before operations
+   */
+  private ensureInitialized(): WasmEngine {
+    if (!this.wasmEngine) {
+      throw new Error("Engine not initialized. Call init() first.");
+    }
+    return this.wasmEngine;
+  }
+
+  /**
+   * Set the render callback that receives patches
+   */
+  setRenderCallback(callback: RenderCallback): void {
+    const engine = this.ensureInitialized();
+    engine.setRenderCallback((patches: Patch[]) => {
+      callback(patches);
+    });
+  }
+
+  /**
+   * Set the component resolver for dynamic component composition
+   */
+  setComponentResolver(resolver: ComponentResolver): void {
+    const engine = this.ensureInitialized();
+    engine.setComponentResolver((componentName: string, contextPath: string | null) => {
+      const result = resolver(componentName, contextPath);
+      return result;
+    });
+  }
+
+  /**
+   * Parse and render Hypen DSL source code
+   */
+  renderSource(source: string): void {
+    const engine = this.ensureInitialized();
+    engine.renderSource(source);
+  }
+
+  /**
+   * Render a lazy component (for lazy route loading)
+   */
+  renderLazyComponent(source: string): void {
+    const engine = this.ensureInitialized();
+    engine.renderLazyComponent(source);
+  }
+
+  /**
+   * Render a component into a specific parent node (subtree rendering)
+   */
+  renderInto(source: string, parentNodeId: string, state: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+    const safeState = JSON.parse(JSON.stringify(state));
+    engine.renderInto(source, parentNodeId, safeState);
+  }
+
+  /**
+   * Notify the engine of state changes using sparse updates
+   */
+  notifyStateChange(paths: string[], values: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+
+    if (paths.length === 0) {
+      return;
+    }
+
+    engine.updateStateSparse(paths, values);
+    console.debug("[Hypen] State changed (sparse):", paths);
+  }
+
+  /**
+   * Notify the engine of state changes using full state replacement
+   * @deprecated Use notifyStateChange with sparse values instead
+   */
+  notifyStateChangeFull(paths: string[], currentState: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+
+    const plainObject = JSON.parse(JSON.stringify(currentState));
+    engine.updateState(plainObject);
+
+    if (paths.length > 0) {
+      console.debug("[Hypen] State changed (full):", paths);
+    }
+  }
+
+  /**
+   * Update state (triggers re-render of affected nodes)
+   * @deprecated Use notifyStateChange instead
+   */
+  updateState(statePatch: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+    const plainObject = JSON.parse(JSON.stringify(statePatch));
+    engine.updateState(plainObject);
+  }
+
+  /**
+   * Dispatch an action
+   */
+  dispatchAction(name: string, payload?: any): void {
+    const engine = this.ensureInitialized();
+    engine.dispatchAction(name, payload ?? null);
+  }
+
+  /**
+   * Register an action handler
+   */
+  onAction(actionName: string, handler: ActionHandler): void {
+    const engine = this.ensureInitialized();
+    engine.onAction(actionName, (action: Action) => {
+      Promise.resolve(handler(action)).catch(console.error);
+    });
+  }
+
+  /**
+   * Initialize a module
+   */
+  setModule(
+    name: string,
+    actions: string[],
+    stateKeys: string[],
+    initialState: Record<string, any>
+  ): void {
+    const engine = this.ensureInitialized();
+    engine.setModule(name, actions, stateKeys, initialState);
+  }
+
+  /**
+   * Get the current revision number
+   */
+  getRevision(): number {
+    const engine = this.ensureInitialized();
+    return engine.getRevision();
+  }
+
+  /**
+   * Clear the engine tree
+   */
+  clearTree(): void {
+    const engine = this.ensureInitialized();
+    engine.clearTree();
+  }
+
+  /**
+   * Debug method to inspect parsed components
+   */
+  debugParseComponent(source: string): string {
+    const engine = this.ensureInitialized();
+    return engine.debugParseComponent(source);
+  }
+}

package/src/events.ts

@@ -0,0 +1,126 @@
+/**
+ * Type-safe Event System
+ *
+ * Provides strongly-typed event emission and subscription with autocomplete support.
+ */
+
+export type EventHandler<T = unknown> = (payload: T) => void;
+
+/**
+ * Type-safe event emitter with generics
+ */
+export class TypedEventEmitter<TEvents extends Record<string, unknown> = Record<string, unknown>> {
+  private eventBus = new Map<keyof TEvents, Set<EventHandler<any>>>();
+
+  /**
+   * Emit an event with type-safe payload
+   */
+  emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void {
+    const handlers = this.eventBus.get(event);
+    if (!handlers || handlers.size === 0) {
+      return;
+    }
+
+    handlers.forEach((handler) => {
+      try {
+        handler(payload);
+      } catch (error) {
+        console.error(`Error in event handler for "${String(event)}":`, error);
+      }
+    });
+  }
+
+  /**
+   * Subscribe to an event with type-safe payload
+   * Returns an unsubscribe function
+   */
+  on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
+    if (!this.eventBus.has(event)) {
+      this.eventBus.set(event, new Set());
+    }
+
+    const handlers = this.eventBus.get(event)!;
+    handlers.add(handler);
+
+    // Return unsubscribe function
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.eventBus.delete(event);
+      }
+    };
+  }
+
+  /**
+   * Subscribe to an event once (auto-unsubscribe after first emit)
+   */
+  once<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
+    const wrappedHandler = (payload: TEvents[K]) => {
+      handler(payload);
+      unsubscribe();
+    };
+
+    const unsubscribe = this.on(event, wrappedHandler);
+    return unsubscribe;
+  }
+
+  /**
+   * Unsubscribe a specific handler from an event
+   */
+  off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void {
+    const handlers = this.eventBus.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.eventBus.delete(event);
+      }
+    }
+  }
+
+  /**
+   * Remove all listeners for a specific event
+   */
+  removeAllListeners<K extends keyof TEvents>(event: K): void {
+    this.eventBus.delete(event);
+  }
+
+  /**
+   * Remove all listeners for all events
+   */
+  clearAll(): void {
+    this.eventBus.clear();
+  }
+
+  /**
+   * Get the number of listeners for an event
+   */
+  listenerCount<K extends keyof TEvents>(event: K): number {
+    return this.eventBus.get(event)?.size ?? 0;
+  }
+
+  /**
+   * Get all registered event names
+   */
+  eventNames(): Array<keyof TEvents> {
+    return Array.from(this.eventBus.keys());
+  }
+}
+
+/**
+ * Default events for Hypen framework (can be extended by users)
+ */
+export type HypenFrameworkEvents = {
+  'module:created': { moduleId: string };
+  'module:destroyed': { moduleId: string };
+  'route:changed': { from: string | null; to: string };
+  'state:updated': { moduleId: string; paths: string[] };
+  'action:dispatched': { moduleId: string; actionName: string; payload?: unknown };
+  'error': { message: string; error?: Error; context?: string };
+};
+
+/**
+ * Create a typed event emitter with custom event map
+ */
+export function createEventEmitter<TEvents extends Record<string, unknown> = HypenFrameworkEvents>(): TypedEventEmitter<TEvents> {
+  return new TypedEventEmitter<TEvents>();
+}

package/src/index.browser.ts

@@ -0,0 +1,104 @@
+/**
+ * @hypen/core - Browser Entry Point
+ *
+ * This entry point uses the browser-compatible engine with explicit WASM initialization.
+ */
+
+// ============================================================================
+// ENGINE API (Browser version)
+// ============================================================================
+
+export { Engine } from "./engine.browser.js";
+export type {
+  Patch,
+  Action,
+  RenderCallback,
+  ActionHandler as EngineActionHandler,
+  ResolvedComponent,
+  ComponentResolver,
+  EngineInitOptions,
+} from "./engine.browser.js";
+
+// ============================================================================
+// APP / MODULE SYSTEM
+// ============================================================================
+
+export { app, HypenApp, HypenAppBuilder, HypenModuleInstance } from "./app.js";
+export type {
+  IEngine,
+  RouterContext,
+  ActionContext,
+  ActionNext,
+  GlobalContext,
+  LifecycleHandler,
+  ActionHandlerContext,
+  ActionHandler,
+  HypenModuleDefinition,
+  HypenModule,
+} from "./app.js";
+
+// ============================================================================
+// STATE MANAGEMENT
+// ============================================================================
+
+export {
+  createObservableState,
+  batchStateUpdates,
+  getStateSnapshot,
+} from "./state.js";
+export type {
+  StatePath,
+  StateChange,
+  StateObserverOptions,
+} from "./state.js";
+
+// ============================================================================
+// RENDERER ABSTRACTION
+// ============================================================================
+
+export { BaseRenderer, ConsoleRenderer } from "./renderer.js";
+export type { Renderer } from "./renderer.js";
+
+// ============================================================================
+// ROUTING
+// ============================================================================
+
+export { HypenRouter } from "./router.js";
+export type {
+  RouteMatch,
+  RouteState,
+  RouteChangeCallback,
+} from "./router.js";
+
+// ============================================================================
+// EVENTS
+// ============================================================================
+
+export { TypedEventEmitter, createEventEmitter } from "./events.js";
+export type { EventHandler, HypenFrameworkEvents } from "./events.js";
+
+// ============================================================================
+// GLOBAL CONTEXT
+// ============================================================================
+
+export { HypenGlobalContext } from "./context.js";
+export type { ModuleReference } from "./context.js";
+
+// ============================================================================
+// REMOTE UI
+// ============================================================================
+
+export { RemoteEngine } from "./remote/client.js";
+export type {
+  RemoteMessage,
+  InitialTreeMessage,
+  PatchMessage,
+  DispatchActionMessage,
+  StateUpdateMessage,
+  RemoteClient,
+  RemoteServerConfig,
+} from "./remote/types.js";
+export type {
+  RemoteConnectionState,
+  RemoteEngineOptions,
+} from "./remote/client.js";