@hypen-space/core 0.4.37 → 0.4.38

package/src/engine.browser.ts

@@ -1,302 +0,0 @@
-/**
- * Browser-compatible wrapper around the WASM engine
- * Uses web target for browser environments
- */
-
-import { frameworkLoggers } from "./logger.js";
-import { classifyEngineError } from "./result.js";
-import type { Patch, Action, RenderCallback, ActionHandler, ResolvedComponent, ComponentResolver } from "./types.js";
-
-// Re-export types so existing consumers of "./engine.browser.js" still work
-export type { Patch, Action, RenderCallback, ActionHandler, ResolvedComponent, ComponentResolver } from "./types.js";
-
-const log = frameworkLoggers.engine;
-
-// 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 interface EngineInitOptions {
-  /**
-   * URL to the WASM binary file.
-   * Default: loads from unpkg CDN
-   * For production, consider serving from your own domain for better performance.
-   */
-  wasmUrl?: string;
-
-  /**
-   * URL to the WASM JS glue code.
-   * Default: loads from unpkg CDN
-   * For self-hosting, point to your own copy of hypen_engine.js
-   */
-  jsUrl?: 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 wasmUrl and jsUrl
-   */
-  async init(options: EngineInitOptions = {}): Promise<void> {
-    if (this.initialized) return;
-
-    // Default to CDN for zero-config experience
-    const cdnBase = "https://unpkg.com/@hypen-space/core@latest/wasm-browser";
-    const jsUrl = options.jsUrl ?? `${cdnBase}/hypen_engine.js`;
-    const wasmUrl = options.wasmUrl ?? `${cdnBase}/hypen_engine_bg.wasm`;
-
-    // Dynamically import the WASM JS glue code from CDN (or custom URL)
-    // Using dynamic import with variable URL to avoid bundler resolution
-    try {
-      const wasmModule: any = await import(/* @vite-ignore */ jsUrl);
-      wasmInit = wasmModule.default;
-      WasmEngineClass = wasmModule.WasmEngine;
-
-      // Initialize WASM with explicit path
-      await wasmInit!(wasmUrl);
-
-      this.wasmEngine = new WasmEngineClass();
-      this.initialized = true;
-    } catch (error) {
-      log.error("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
-   * @throws {ParseError} if the source fails to parse
-   * @throws {RenderError} if rendering fails
-   */
-  renderSource(source: string): void {
-    const engine = this.ensureInitialized();
-    try {
-      engine.renderSource(source);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * 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)
-   * @throws {ParseError} if the source fails to parse
-   * @throws {RenderError} if the parent node is not found or rendering fails
-   */
-  renderInto(source: string, parentNodeId: string, state: Record<string, any>): void {
-    const engine = this.ensureInitialized();
-    const safeState = JSON.parse(JSON.stringify(state));
-    try {
-      engine.renderInto(source, parentNodeId, safeState);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * Notify the engine of state changes using sparse updates
-   * @throws {StateError} if the state patch is invalid
-   */
-  notifyStateChange(paths: string[], values: Record<string, any>): void {
-    const engine = this.ensureInitialized();
-
-    if (paths.length === 0) {
-      return;
-    }
-
-    const plainValues = JSON.parse(JSON.stringify(values));
-    try {
-      engine.updateStateSparse(paths, plainValues);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-    log.debug("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) {
-      log.debug("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
-   * @throws {HypenError} if the action dispatch fails
-   */
-  dispatchAction(name: string, payload?: any): void {
-    const engine = this.ensureInitialized();
-    log.debug(`Action dispatched: ${name}`);
-    try {
-      engine.dispatchAction(name, payload ?? null);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * 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((err) => log.error("Action handler error:", err));
-    });
-  }
-
-  /**
-   * 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);
-  }
-
-  // ── Data Source Context ────────────────────────────────────────
-
-  /**
-   * Set (or replace) a named data source context.
-   *
-   * Registers the provider in the dependency graph, stores the data,
-   * and re-renders every node bound to `$name.*`.
-   *
-   * @param name - Provider name (e.g., "spacetime", "firebase")
-   * @param data - Full state object for this provider
-   */
-  setContext(name: string, data: Record<string, unknown>): void {
-    const engine = this.ensureInitialized();
-    const plainData = JSON.parse(JSON.stringify(data));
-    try {
-      engine.setContext(name, plainData);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * Remove a data source context entirely.
-   * Drops the provider's state and re-renders bound nodes (they resolve to null).
-   */
-  removeContext(name: string): void {
-    const engine = this.ensureInitialized();
-    engine.removeContext(name);
-  }
-}

package/src/engine.ts

@@ -1,282 +0,0 @@
-/**
- * Low-level wrapper around the WASM engine
- * Node.js / Bundler target
- */
-
-// WASM module types
-import { WasmEngine } from "../wasm-node/hypen_engine.js";
-import { frameworkLoggers } from "./logger.js";
-import { classifyEngineError } from "./result.js";
-import type { Patch, Action, RenderCallback, ActionHandler, ResolvedComponent, ComponentResolver } from "./types.js";
-
-// Re-export types so existing consumers of "./engine.js" still work
-export type { Patch, Action, RenderCallback, ActionHandler, ResolvedComponent, ComponentResolver } from "./types.js";
-
-const log = frameworkLoggers.engine;
-
-/**
- * Unwrap proxy objects to plain values for WASM serialization.
- * Uses structuredClone when available (Node 17+, Bun, modern browsers),
- * falls back to JSON round-trip for proxy objects or older environments.
- */
-function unwrapForWasm<T>(value: T): T {
-  // Fast path: primitives don't need cloning
-  if (value === null || typeof value !== 'object') {
-    return value;
-  }
-
-  // Check if the object has a snapshot method (our proxy convention)
-  if (typeof (value as any).__getSnapshot === 'function') {
-    return (value as any).__getSnapshot() as T;
-  }
-
-  // Try structuredClone first (fastest for plain objects)
-  try {
-    return structuredClone(value);
-  } catch {
-    // Fallback for proxy objects or unsupported types
-    return JSON.parse(JSON.stringify(value));
-  }
-}
-
-/**
- * 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
-   * @throws {ParseError} if the source fails to parse
-   * @throws {RenderError} if rendering fails
-   */
-  renderSource(source: string): void {
-    const engine = this.ensureInitialized();
-    try {
-      engine.renderSource(source);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * 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)
-   * @throws {ParseError} if the source fails to parse
-   * @throws {RenderError} if the parent node is not found or rendering fails
-   */
-  renderInto(source: string, parentNodeId: string, state: Record<string, any>): void {
-    const engine = this.ensureInitialized();
-    try {
-      engine.renderInto(source, parentNodeId, unwrapForWasm(state));
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * Notify the engine of state changes using sparse updates
-   * @throws {StateError} if the state patch is invalid
-   */
-  notifyStateChange(paths: string[], values: Record<string, any>): void {
-    const engine = this.ensureInitialized();
-
-    if (paths.length === 0) {
-      return;
-    }
-
-    try {
-      engine.updateStateSparse(paths, unwrapForWasm(values));
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-    log.debug("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();
-    engine.updateState(unwrapForWasm(currentState));
-
-    if (paths.length > 0) {
-      log.debug("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();
-    engine.updateState(unwrapForWasm(statePatch));
-  }
-
-  /**
-   * Dispatch an action
-   * @throws {HypenError} if the action dispatch fails
-   */
-  dispatchAction(name: string, payload?: any): void {
-    const engine = this.ensureInitialized();
-    try {
-      engine.dispatchAction(name, payload ?? null);
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-  }
-
-  /**
-   * Register an action handler
-   */
-  private _onErrorHandler?: (error: Error) => void;
-
-  /**
-   * Set error handler for action errors
-   */
-  setOnError(handler: (error: Error) => void): void {
-    this._onErrorHandler = handler;
-  }
-
-  onAction(actionName: string, handler: ActionHandler): void {
-    const engine = this.ensureInitialized();
-    const handleError = (err: unknown) => {
-      log.error("Action handler error:", err);
-      if (this._onErrorHandler) {
-        this._onErrorHandler(err instanceof Error ? err : new Error(String(err)));
-      }
-    };
-    engine.onAction(actionName, (action: Action) => {
-      try {
-        const result = handler(action);
-        // If handler returns a promise, catch async errors too
-        if (result && typeof (result as any).catch === "function") {
-          (result as any).catch(handleError);
-        }
-      } catch (err) {
-        handleError(err);
-      }
-    });
-  }
-
-  /**
-   * 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 Number(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);
-  }
-
-  // ── Data Source Context ────────────────────────────────────────
-
-  /**
-   * Set (or replace) a named data source context.
-   *
-   * Registers the provider in the dependency graph, stores the data,
-   * and re-renders every node bound to `$name.*`.
-   * Sparse merging (if needed) should happen at the SDK layer before
-   * calling this method with the merged object.
-   *
-   * @param name - Provider name (e.g., "spacetime", "firebase")
-   * @param data - Full state object for this provider
-   */
-  setContext(name: string, data: Record<string, unknown>): void {
-    const engine = this.ensureInitialized();
-    try {
-      engine.setContext(name, unwrapForWasm(data));
-    } catch (err) {
-      throw classifyEngineError(err);
-    }
-    log.debug(`Data source "${name}" context set`);
-  }
-
-  /**
-   * Remove a data source context entirely.
-   * Drops the provider's state and re-renders bound nodes (they resolve to null).
-   */
-  removeContext(name: string): void {
-    const engine = this.ensureInitialized();
-    engine.removeContext(name);
-  }
-}

package/src/loader.ts

@@ -1,136 +0,0 @@
-/**
- * Component Loader
- *
- * Loads and registers Hypen components from file system.
- * Works in both Node.js and Bun environments.
- */
-
-import { existsSync, readdirSync, readFileSync } from "fs";
-import { join } from "path";
-import type { HypenModuleDefinition } from "./app.js";
-import { frameworkLoggers } from "./logger.js";
-
-const log = frameworkLoggers.loader;
-
-export interface ComponentDefinition {
-  name: string;
-  module: HypenModuleDefinition<any>;
-  template: string; // The .hypen file content
-  path: string;
-}
-
-export class ComponentLoader {
-  private components = new Map<string, ComponentDefinition>();
-
-  /**
-   * Register a component with its module and template
-   */
-  register(
-    name: string,
-    module: HypenModuleDefinition<any>,
-    template: string,
-    path?: string
-  ): void {
-    this.components.set(name, {
-      name,
-      module,
-      template,
-      path: path || name,
-    });
-  }
-
-  /**
-   * Get a registered component by name
-   */
-  get(name: string): ComponentDefinition | undefined {
-    return this.components.get(name);
-  }
-
-  /**
-   * Check if a component is registered
-   */
-  has(name: string): boolean {
-    return this.components.has(name);
-  }
-
-  /**
-   * Get all registered component names
-   */
-  getNames(): string[] {
-    return Array.from(this.components.keys());
-  }
-
-  /**
-   * Get all registered components
-   */
-  getAll(): ComponentDefinition[] {
-    return Array.from(this.components.values());
-  }
-
-  /**
-   * Clear all registered components
-   */
-  clear(): void {
-    this.components.clear();
-  }
-
-  /**
-   * Load a component from a directory
-   * Expects: component.ts and component.hypen in the same directory
-   */
-  async loadFromDirectory(name: string, dirPath: string): Promise<void> {
-    try {
-      // Dynamic import of the module
-      const modulePath = join(dirPath, "component.ts");
-      const moduleExport = await import(modulePath);
-      const module = moduleExport.default as HypenModuleDefinition<any>;
-
-      // Read the .hypen template file
-      const templatePath = join(dirPath, "component.hypen");
-      const template = readFileSync(templatePath, "utf-8");
-
-      // Register the component
-      this.register(name, module, template, dirPath);
-
-      log.debug(`Loaded component: ${name} from ${dirPath}`);
-    } catch (error) {
-      log.error(`Failed to load component ${name} from ${dirPath}:`, error);
-      throw error;
-    }
-  }
-
-  /**
-   * Auto-load all components from a directory
-   * Scans for subdirectories containing component.ts and component.hypen
-   */
-  async loadFromComponentsDir(baseDir: string): Promise<void> {
-    try {
-      if (!existsSync(baseDir)) {
-        log.warn(`Components directory not found: ${baseDir}`);
-        return;
-      }
-
-      const entries = readdirSync(baseDir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-
-        const componentDir = join(baseDir, entry.name);
-        const hypenPath = join(componentDir, "component.hypen");
-
-        // Only load if component.hypen exists
-        if (existsSync(hypenPath)) {
-          await this.loadFromDirectory(entry.name, componentDir);
-        }
-      }
-
-      log.debug(`Loaded ${this.components.size} components from ${baseDir}`);
-    } catch (error) {
-      log.error(`Failed to load components from ${baseDir}:`, error);
-      throw error;
-    }
-  }
-}
-
-// Global component loader instance
-export const componentLoader = new ComponentLoader();