@hypen-space/core 0.2.0

package/src/index.ts

@@ -0,0 +1,126 @@
+/**
+ * @hypen/core - Hypen Core Engine
+ *
+ * Platform-agnostic reactive UI runtime.
+ * Use with @hypen/web for browser rendering, or build your own renderer.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Engine, app } from "@hypen/core";
+ *
+ * // Create a stateful module
+ * const counter = app
+ *   .defineState({ count: 0 })
+ *   .onAction("increment", ({ state }) => {
+ *     state.count++;
+ *   })
+ *   .build();
+ *
+ * // Initialize the engine
+ * const engine = new Engine();
+ * await engine.init();
+ * ```
+ */
+
+// ============================================================================
+// ENGINE API
+// ============================================================================
+
+export { Engine } from "./engine.js";
+export type {
+  Patch,
+  Action,
+  RenderCallback,
+  ActionHandler as EngineActionHandler,
+  ResolvedComponent,
+  ComponentResolver,
+} from "./engine.js";
+
+// Browser engine (explicit WASM init)
+export { Engine as BrowserEngine } from "./engine.browser.js";
+export type { 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";

package/src/remote/client.ts

@@ -0,0 +1,274 @@
+/**
+ * RemoteEngine - Connect to a remote Hypen app over WebSocket
+ * Platform-agnostic client (uses standard WebSocket API)
+ */
+
+import type {
+  RemoteMessage,
+  InitialTreeMessage,
+  PatchMessage,
+  DispatchActionMessage,
+} from "./types.js";
+import type { Patch } from "../engine.js";
+
+export type RemoteConnectionState = "disconnected" | "connecting" | "connected" | "error";
+
+export interface RemoteEngineOptions {
+  autoReconnect?: boolean;
+  reconnectInterval?: number;
+  maxReconnectAttempts?: number;
+}
+
+/**
+ * Client-side engine that connects to a remote Hypen app
+ */
+export class RemoteEngine {
+  private ws: WebSocket | null = null;
+  private url: string;
+  private state: RemoteConnectionState = "disconnected";
+  private options: Required<RemoteEngineOptions>;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Callbacks
+  private patchCallbacks: Array<(patches: Patch[]) => void> = [];
+  private stateCallbacks: Array<(state: any) => void> = [];
+  private connectionCallbacks: Array<() => void> = [];
+  private disconnectionCallbacks: Array<() => void> = [];
+  private errorCallbacks: Array<(error: Error) => void> = [];
+
+  // State
+  private currentState: any = null;
+  private currentRevision = 0;
+  private moduleName: string = "";
+
+  constructor(url: string, options: RemoteEngineOptions = {}) {
+    this.url = url;
+    this.options = {
+      autoReconnect: options.autoReconnect ?? true,
+      reconnectInterval: options.reconnectInterval ?? 3000,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+    };
+  }
+
+  /**
+   * Connect to the remote server
+   */
+  async connect(): Promise<void> {
+    if (this.state === "connected" || this.state === "connecting") {
+      return;
+    }
+
+    this.state = "connecting";
+
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.url);
+
+        this.ws.onopen = () => {
+          this.state = "connected";
+          this.reconnectAttempts = 0;
+          this.connectionCallbacks.forEach((cb) => cb());
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          this.handleMessage(event.data);
+        };
+
+        this.ws.onerror = () => {
+          this.state = "error";
+          const error = new Error("WebSocket error");
+          this.errorCallbacks.forEach((cb) => cb(error));
+          reject(error);
+        };
+
+        this.ws.onclose = () => {
+          this.state = "disconnected";
+          this.disconnectionCallbacks.forEach((cb) => cb());
+          this.attemptReconnect();
+        };
+      } catch (error) {
+        this.state = "error";
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Disconnect from the remote server
+   */
+  disconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+
+    this.state = "disconnected";
+  }
+
+  /**
+   * Dispatch an action to the remote server
+   */
+  dispatchAction(action: string, payload?: any): void {
+    if (this.state !== "connected" || !this.ws) {
+      console.warn("Cannot dispatch action: not connected");
+      return;
+    }
+
+    const message: DispatchActionMessage = {
+      type: "dispatchAction",
+      module: this.moduleName,
+      action,
+      payload,
+    };
+
+    this.ws.send(JSON.stringify(message));
+  }
+
+  /**
+   * Register callback for patches
+   */
+  onPatches(callback: (patches: Patch[]) => void): this {
+    this.patchCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Register callback for state updates
+   */
+  onStateUpdate(callback: (state: any) => void): this {
+    this.stateCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Register callback for connection
+   */
+  onConnect(callback: () => void): this {
+    this.connectionCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Register callback for disconnection
+   */
+  onDisconnect(callback: () => void): this {
+    this.disconnectionCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Register callback for errors
+   */
+  onError(callback: (error: Error) => void): this {
+    this.errorCallbacks.push(callback);
+    return this;
+  }
+
+  /**
+   * Get current connection state
+   */
+  getConnectionState(): RemoteConnectionState {
+    return this.state;
+  }
+
+  /**
+   * Get current app state
+   */
+  getCurrentState(): any {
+    return this.currentState;
+  }
+
+  /**
+   * Get current revision
+   */
+  getRevision(): number {
+    return this.currentRevision;
+  }
+
+  private handleMessage(data: string): void {
+    try {
+      const message = JSON.parse(data) as RemoteMessage;
+
+      switch (message.type) {
+        case "initialTree":
+          this.handleInitialTree(message as InitialTreeMessage);
+          break;
+
+        case "patch":
+          this.handlePatch(message as PatchMessage);
+          break;
+
+        case "stateUpdate":
+          this.currentState = message.state;
+          this.stateCallbacks.forEach((cb) => cb(message.state));
+          break;
+      }
+    } catch (error) {
+      console.error("Error handling remote message:", error);
+      this.errorCallbacks.forEach((cb) =>
+        cb(error instanceof Error ? error : new Error(String(error)))
+      );
+    }
+  }
+
+  private handleInitialTree(message: InitialTreeMessage): void {
+    this.moduleName = message.module;
+    this.currentState = message.state;
+    this.currentRevision = message.revision;
+
+    // Apply initial patches
+    if (message.patches.length > 0) {
+      this.patchCallbacks.forEach((cb) => cb(message.patches));
+    }
+
+    // Notify state callbacks
+    this.stateCallbacks.forEach((cb) => cb(message.state));
+  }
+
+  private handlePatch(message: PatchMessage): void {
+    // Check revision ordering
+    if (message.revision <= this.currentRevision) {
+      console.warn(
+        `Out of order patch: expected > ${this.currentRevision}, got ${message.revision}`
+      );
+      return;
+    }
+
+    this.currentRevision = message.revision;
+
+    // Apply patches
+    if (message.patches.length > 0) {
+      this.patchCallbacks.forEach((cb) => cb(message.patches));
+    }
+  }
+
+  private attemptReconnect(): void {
+    if (!this.options.autoReconnect) {
+      return;
+    }
+
+    if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+      console.error("Max reconnection attempts reached");
+      return;
+    }
+
+    this.reconnectAttempts++;
+
+    console.log(
+      `Attempting to reconnect (${this.reconnectAttempts}/${this.options.maxReconnectAttempts})...`
+    );
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch((error) => {
+        console.error("Reconnection failed:", error);
+      });
+    }, this.options.reconnectInterval);
+  }
+}

package/src/remote/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Remote UI streaming for Hypen
+ *
+ * Client-side: Connect to remote Hypen apps
+ */
+
+export { RemoteEngine } from "./client.js";
+export type {
+  RemoteMessage,
+  InitialTreeMessage,
+  PatchMessage,
+  DispatchActionMessage,
+  StateUpdateMessage,
+  RemoteClient,
+  RemoteServerConfig,
+} from "./types.js";
+export type { RemoteConnectionState, RemoteEngineOptions } from "./client.js";

package/src/remote/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Remote UI Protocol Types
+ */
+
+import type { Patch } from "../engine.js";
+
+export type RemoteMessage =
+  | InitialTreeMessage
+  | PatchMessage
+  | StateUpdateMessage
+  | DispatchActionMessage;
+
+export interface InitialTreeMessage {
+  type: "initialTree";
+  module: string;
+  state: any;
+  patches: Patch[];
+  revision: number;
+}
+
+export interface PatchMessage {
+  type: "patch";
+  module: string;
+  patches: Patch[];
+  revision: number;
+}
+
+export interface StateUpdateMessage {
+  type: "stateUpdate";
+  module: string;
+  state: any;
+  revision: number;
+}
+
+export interface DispatchActionMessage {
+  type: "dispatchAction";
+  module: string;
+  action: string;
+  payload?: any;
+}
+
+export interface RemoteClient {
+  id: string;
+  socket: any;
+  connectedAt: Date;
+}
+
+export interface RemoteServerConfig {
+  port?: number;
+  hostname?: string;
+}

package/src/renderer.ts

@@ -0,0 +1,102 @@
+/**
+ * Renderer abstraction interface
+ *
+ * Renderers are pluggable and can be implemented for different platforms
+ * (DOM, Canvas, Native, etc.)
+ */
+
+import type { Patch } from "./engine.js";
+
+/**
+ * Renderer interface that all platform renderers must implement
+ */
+export interface Renderer {
+  /**
+   * Apply a batch of patches to the render tree
+   */
+  applyPatches(patches: Patch[]): void;
+
+  /**
+   * Get a node by its ID (optional, for debugging)
+   */
+  getNode?(id: string): any;
+
+  /**
+   * Clear the entire render tree
+   */
+  clear?(): void;
+}
+
+/**
+ * Base renderer class with common utilities
+ */
+export abstract class BaseRenderer implements Renderer {
+  protected nodes: Map<string, any> = new Map();
+
+  abstract applyPatches(patches: Patch[]): void;
+
+  getNode(id: string): any {
+    return this.nodes.get(id);
+  }
+
+  clear(): void {
+    this.nodes.clear();
+  }
+
+  /**
+   * Apply a single patch
+   */
+  protected applyPatch(patch: Patch): void {
+    switch (patch.type) {
+      case "create":
+        this.onCreate(patch.id!, patch.elementType!, patch.props || {});
+        break;
+      case "setProp":
+        this.onSetProp(patch.id!, patch.name!, patch.value);
+        break;
+      case "setText":
+        this.onSetText(patch.id!, patch.text!);
+        break;
+      case "insert":
+        this.onInsert(patch.parentId!, patch.id!, patch.beforeId);
+        break;
+      case "move":
+        this.onMove(patch.parentId!, patch.id!, patch.beforeId);
+        break;
+      case "remove":
+        this.onRemove(patch.id!);
+        break;
+      case "attachEvent":
+        this.onAttachEvent(patch.id!, patch.eventName!);
+        break;
+      case "detachEvent":
+        this.onDetachEvent(patch.id!, patch.eventName!);
+        break;
+    }
+  }
+
+  /**
+   * Platform-specific patch handlers
+   */
+  protected abstract onCreate(id: string, elementType: string, props: Record<string, any>): void;
+  protected abstract onSetProp(id: string, name: string, value: any): void;
+  protected abstract onSetText(id: string, text: string): void;
+  protected abstract onInsert(parentId: string, id: string, beforeId?: string): void;
+  protected abstract onMove(parentId: string, id: string, beforeId?: string): void;
+  protected abstract onRemove(id: string): void;
+  protected abstract onAttachEvent(id: string, eventName: string): void;
+  protected abstract onDetachEvent(id: string, eventName: string): void;
+}
+
+/**
+ * Console/Debug renderer that logs patches
+ */
+export class ConsoleRenderer implements Renderer {
+  applyPatches(patches: Patch[]): void {
+    console.group("Patches:");
+    for (const patch of patches) {
+      console.log(patch);
+    }
+    console.groupEnd();
+  }
+}