@hypen-space/core 0.4.31 → 0.4.35

package/src/app.ts

@@ -6,6 +6,7 @@
 import type { Action } from "./types.js";
 import type { Session } from "./remote/types.js";
 import { type Result, Ok, Err, fromPromise, ActionError, HypenError } from "./result.js";
+import { DataSourceManager, type DataSourcePlugin, type IDataSourceEngine } from "./datasource.js";
 
 // Interface for engine compatibility (works with both engine.js and engine.browser.js)
 export interface IEngine {
@@ -49,6 +50,20 @@ export interface ActionHandlerContext<T, P = unknown> {
   action: ActionContext<P>;
   state: T;
   context: GlobalContext;
+  /** Access to registered data source plugins for mutations */
+  dataSources: DataSourceAccessor;
+}
+
+/**
+ * Provides typed access to registered data source plugins.
+ * Unknown method calls are forwarded to `plugin.call()`:
+ *   `dataSources.spacetime.sendMessage(text)` → `plugin.call("sendMessage", text)`
+ *
+ * You can also call `.call()` directly if you prefer:
+ *   `dataSources.spacetime.call("sendMessage", text)`
+ */
+export interface DataSourceAccessor {
+  [providerName: string]: DataSourcePlugin & Record<string, (...args: unknown[]) => Promise<unknown>>;
 }
 
 /**
@@ -139,6 +154,11 @@ export interface HypenModuleDefinition<T = unknown> {
    * Set via the `.ui(hypen`...`)` method.
    */
   template?: string;
+  /**
+   * Data source plugins registered via `.useDataSource()`.
+   * Each entry contains the plugin and its configuration.
+   */
+  dataSources?: Array<{ plugin: DataSourcePlugin; config: unknown }>;
   handlers: {
     onCreated?: LifecycleHandler<T>;
     onAction: Map<string, ActionHandler<T, any>>;
@@ -174,6 +194,7 @@ export class HypenAppBuilder<T> {
   private errorHandler?: ErrorHandler<T>;
   private template?: string;
   private _registry?: Map<string, HypenModuleDefinition>;
+  private dataSourceEntries: Array<{ plugin: DataSourcePlugin; config: unknown }> = [];
 
   constructor(
     initialState: T,
@@ -285,6 +306,39 @@ export class HypenAppBuilder<T> {
     return this;
   }
 
+  /**
+   * Register a data source plugin for live database subscriptions.
+   *
+   * @example
+   * ```typescript
+   * import { SpacetimeDBPlugin } from "@hypen-space/plugin-spacetimedb";
+   *
+   * export default app
+   *   .defineState({ messageText: "" })
+   *   .useDataSource(new SpacetimeDBPlugin(), {
+   *     uri: "ws://localhost:3000",
+   *     moduleName: "chat",
+   *     tables: ["user", "message"],
+   *   })
+   *   .onAction("sendMessage", async ({ state, dataSources }) => {
+   *     await dataSources.spacetime.sendMessage(state.messageText);
+   *     state.messageText = "";
+   *   })
+   *   .build();
+   * ```
+   *
+   * In Hypen DSL, bind to data source tables with `$provider.table`:
+   * ```hypen
+   * ForEach(items: $spacetime.message, key: "id") {
+   *   Text("${item.text}")
+   * }
+   * ```
+   */
+  useDataSource<C>(plugin: DataSourcePlugin<C>, config: C): this {
+    this.dataSourceEntries.push({ plugin: plugin as DataSourcePlugin, config });
+    return this;
+  }
+
   /**
    * Define the component's UI template inline (single-file component).
    *
@@ -316,6 +370,28 @@ export class HypenAppBuilder<T> {
     return this.build();
   }
 
+  /**
+   * Load a UI template from a .hypen file on disk.
+   *
+   * @example
+   * ```typescript
+   * import { app } from "@hypen-space/core";
+   *
+   * export default app
+   *   .defineState({ count: 0 })
+   *   .onAction("increment", ({ state }) => { state.count += 1; })
+   *   .uiFile("./counter.hypen");
+   * ```
+   *
+   * @param path - Path to a .hypen template file
+   * @returns The built module definition (calls build() internally)
+   */
+  uiFile(path: string): HypenModuleDefinition<T> {
+    const fs = require("fs");
+    this.template = fs.readFileSync(path, "utf-8").trim();
+    return this.build();
+  }
+
   /**
    * Build the module definition
    */
@@ -333,6 +409,7 @@ export class HypenAppBuilder<T> {
       version: this.options.version,
       initialState: this.initialState,
       template: this.template,
+      dataSources: this.dataSourceEntries.length > 0 ? this.dataSourceEntries : undefined,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
@@ -467,6 +544,8 @@ export class HypenModuleInstance<T extends object = any> {
   private router: HypenRouter | null;
   private globalContext?: HypenGlobalContext;
   private stateChangeCallbacks: Array<() => void> = [];
+  private dataSourceManager?: DataSourceManager;
+  private dataSourceAccessor: DataSourceAccessor = {};
 
   constructor(
     engine: IEngine,
@@ -530,6 +609,7 @@ export class HypenModuleInstance<T extends object = any> {
           action: actionCtx,
           state: this.state,
           context: context!,
+          dataSources: this.dataSourceAccessor,
         });
 
         if (!result.ok) {
@@ -584,8 +664,9 @@ export class HypenModuleInstance<T extends object = any> {
     };
 
     // Expose hypen engine for built-in components (if available)
-    if ((ctx as any).__hypenEngine) {
-      (api as any).__hypenEngine = (ctx as any).__hypenEngine;
+    const ctxRecord = ctx as unknown as Record<string, unknown>;
+    if (ctxRecord.__hypenEngine) {
+      (api as Record<string, unknown>).__hypenEngine = ctxRecord.__hypenEngine;
     }
 
     return api;
@@ -675,9 +756,34 @@ export class HypenModuleInstance<T extends object = any> {
   }
 
   /**
-   * Call the onCreated handler
+   * Call the onCreated handler and connect data source plugins
    */
   private async callCreatedHandler(): Promise<void> {
+    // Initialize data source plugins if any are registered
+    if (this.definition.dataSources?.length) {
+      // The engine must implement IDataSourceEngine methods
+      const dsEngine = this.engine as unknown as IDataSourceEngine;
+      this.dataSourceManager = new DataSourceManager(dsEngine);
+
+      for (const { plugin, config } of this.definition.dataSources) {
+        try {
+          await this.dataSourceManager.use(plugin, config);
+          // Wrap plugin in a Proxy so unknown method calls forward to plugin.call():
+          //   dataSources.spacetime.sendMessage(text) → plugin.call("sendMessage", text)
+          this.dataSourceAccessor[plugin.name] = new Proxy(plugin, {
+            get(target, prop) {
+              if (typeof prop === 'string' && !(prop in target)) {
+                return (...args: unknown[]) => target.call(prop, ...args);
+              }
+              return (target as unknown as Record<string | symbol, unknown>)[prop];
+            },
+          }) as typeof plugin & Record<string, (...args: unknown[]) => Promise<unknown>>;
+        } catch (e) {
+          log.error(`Failed to connect data source "${plugin.name}":`, e);
+        }
+      }
+    }
+
     if (this.definition.handlers.onCreated) {
       const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
       try {
@@ -700,11 +806,22 @@ export class HypenModuleInstance<T extends object = any> {
   }
 
   /**
-   * Destroy the module instance
+   * Destroy the module instance and disconnect all data source plugins
    */
   async destroy(): Promise<void> {
     if (this.isDestroyed) return;
 
+    // Disconnect all data source plugins
+    if (this.dataSourceManager) {
+      try {
+        await this.dataSourceManager.disconnectAll();
+      } catch (e) {
+        log.error("Error disconnecting data sources:", e);
+      }
+      this.dataSourceManager = undefined;
+      this.dataSourceAccessor = {};
+    }
+
     if (this.definition.handlers.onDestroyed) {
       try {
         await this.definition.handlers.onDestroyed(this.state);

package/src/context.ts

@@ -10,9 +10,17 @@ import { frameworkLoggers } from "./logger.js";
 const log = frameworkLoggers.context;
 
 export type ModuleReference<T = unknown> = {
-  state: T; // Live proxy state
+  /**
+   * Live proxy state - mutations are tracked and trigger re-renders.
+   * Use `getState()` for a snapshot if you only need to read values.
+   */
+  state: T;
   setState: (patch: Partial<T>) => void;
-  getState: () => T; // Snapshot
+  /**
+   * Returns a deep-cloned snapshot of the current state.
+   * Unlike `state`, mutations to the returned object are NOT tracked.
+   */
+  getState: () => T;
 };
 
 /**

package/src/datasource.ts

@@ -0,0 +1,252 @@
+/**
+ * Data Source Plugin System for Hypen
+ *
+ * Enables live subscription databases (SpacetimeDB, Firebase, Convex, Electric SQL)
+ * to push data into the Hypen reactive engine via a unified plugin interface.
+ *
+ * UI bindings use the `$provider.path` syntax:
+ *   - `$spacetime.messages` → SpacetimeDB messages table
+ *   - `$firebase.user.profile` → Firebase user profile
+ *   - `$convex.tasks` → Convex tasks table
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Core Types
+// ---------------------------------------------------------------------------
+
+/** Connection status for a data source provider */
+export type DataSourceStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "error";
+
+/** Describes a subscription to a table or query */
+export interface DataSourceQuery {
+  /** Table or collection name (e.g., "messages", "users") */
+  table: string;
+  /** Optional filter criteria */
+  filter?: Record<string, unknown>;
+  /** Optional raw query string (e.g., SQL for SpacetimeDB) */
+  sql?: string;
+}
+
+/** Handle returned by subscribe() — call unsubscribe() to stop receiving updates */
+export interface DataSourceSubscription {
+  /** Stop receiving updates for this subscription */
+  unsubscribe(): void;
+  /** Current subscription status */
+  status: "pending" | "applied" | "error";
+  /** Error details if status is "error" */
+  error?: Error;
+}
+
+/** Describes a batch of changes pushed by a plugin */
+export interface DataSourceChange {
+  /** Changed paths relative to the provider root (e.g., ["messages", "users"]) */
+  paths: string[];
+  /** New values at those paths */
+  values: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Interface that all data source plugins must implement.
+ *
+ * A plugin manages the connection lifecycle and translates database-specific
+ * events (row inserts, updates, deletes) into `DataSourceChange` objects that
+ * the Hypen engine can consume.
+ *
+ * @typeParam TConfig - Plugin-specific configuration type
+ *
+ * @example
+ * ```typescript
+ * class SpacetimeDBPlugin implements DataSourcePlugin<SpacetimeDBConfig> {
+ *   readonly name = "spacetime";
+ *   status: DataSourceStatus = "disconnected";
+ *
+ *   async connect(config: SpacetimeDBConfig, onChange: (change: DataSourceChange) => void) {
+ *     // Connect to SpacetimeDB, subscribe to tables, push changes via onChange
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface DataSourcePlugin<TConfig = unknown> {
+  /** Unique provider name (e.g., "spacetime", "firebase", "convex") */
+  readonly name: string;
+
+  /** Current connection status */
+  status: DataSourceStatus;
+
+  /**
+   * Connect to the data source and begin pushing changes.
+   *
+   * @param config - Plugin-specific configuration
+   * @param onChange - Callback to push data changes into the engine.
+   *   The plugin MUST call this whenever subscribed data changes.
+   */
+  connect(config: TConfig, onChange: (change: DataSourceChange) => void): Promise<void>;
+
+  /**
+   * Subscribe to a specific table or query.
+   * Returns a handle to unsubscribe later.
+   */
+  subscribe(query: DataSourceQuery): DataSourceSubscription;
+
+  /**
+   * Call a remote procedure / reducer / mutation.
+   *
+   * @param method - Method name (e.g., "sendMessage" for SpacetimeDB reducer)
+   * @param args - Arguments to pass
+   * @returns The result from the remote call
+   */
+  call(method: string, ...args: unknown[]): Promise<unknown>;
+
+  /**
+   * Disconnect from the data source and clean up all subscriptions.
+   */
+  disconnect(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Data Source Manager
+// ---------------------------------------------------------------------------
+
+/** Interface for the engine's data source operations (maps to WASM setContext/removeContext) */
+export interface IDataSourceEngine {
+  /**
+   * Set (or replace) a named data source context.
+   * Registers the provider, stores the data, and re-renders bound nodes.
+   * Sparse merging should happen at the SDK layer before calling this.
+   */
+  setContext(name: string, data: Record<string, unknown>): void;
+  /**
+   * Remove a data source context entirely.
+   * Drops the provider's state and re-renders bound nodes (they resolve to null).
+   */
+  removeContext(name: string): void;
+}
+
+/**
+ * Manages data source plugin lifecycles and bridges them to the Hypen engine.
+ *
+ * The manager:
+ * 1. Registers plugins with the engine (creates state slots)
+ * 2. Connects plugins and wires their onChange callbacks to engine updates
+ * 3. Manages subscription lifecycles
+ * 4. Handles cleanup on disconnect
+ *
+ * @example
+ * ```typescript
+ * const manager = new DataSourceManager(engine);
+ *
+ * // Register and connect a SpacetimeDB plugin
+ * await manager.use(new SpacetimeDBPlugin(), {
+ *   uri: "ws://localhost:3000",
+ *   moduleName: "chat",
+ *   tables: ["user", "message"],
+ * });
+ *
+ * // Access plugin for mutations
+ * await manager.get("spacetime").call("sendMessage", "Hello!");
+ *
+ * // Clean up
+ * await manager.disconnectAll();
+ * ```
+ */
+export class DataSourceManager {
+  private plugins = new Map<string, DataSourcePlugin>();
+  private configs = new Map<string, unknown>();
+  /** Accumulated state per provider — sparse merging happens here before setContext */
+  private state = new Map<string, Record<string, unknown>>();
+  private engine: IDataSourceEngine;
+
+  constructor(engine: IDataSourceEngine) {
+    this.engine = engine;
+  }
+
+  /**
+   * Register, connect, and start a data source plugin.
+   *
+   * @param plugin - The plugin instance
+   * @param config - Plugin-specific configuration
+   */
+  async use<C>(plugin: DataSourcePlugin<C>, config: C): Promise<void> {
+    const { name } = plugin;
+
+    // Initialize state slot
+    this.state.set(name, {});
+
+    // Store references
+    this.plugins.set(name, plugin as DataSourcePlugin);
+    this.configs.set(name, config);
+
+    // Connect the plugin with an onChange callback that merges sparse data
+    // and pushes the full state via setContext
+    await plugin.connect(config, (change: DataSourceChange) => {
+      // Merge changed paths into the accumulated state
+      const current = this.state.get(name) ?? {};
+      for (const path of change.paths) {
+        if (path in change.values) {
+          current[path] = change.values[path];
+        }
+      }
+      this.state.set(name, current);
+
+      // Push the full merged state to the engine
+      this.engine.setContext(name, current);
+    });
+  }
+
+  /**
+   * Get a registered plugin by name.
+   * Useful for calling mutations: `manager.get("spacetime").call("sendMessage", text)`
+   */
+  get<T extends DataSourcePlugin = DataSourcePlugin>(name: string): T | undefined {
+    return this.plugins.get(name) as T | undefined;
+  }
+
+  /** Check if a plugin is registered */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+
+  /** Get all registered provider names */
+  getNames(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /** Get the status of a specific plugin */
+  getStatus(name: string): DataSourceStatus | undefined {
+    return this.plugins.get(name)?.status;
+  }
+
+  /**
+   * Disconnect and remove a specific plugin.
+   */
+  async remove(name: string): Promise<void> {
+    const plugin = this.plugins.get(name);
+    if (plugin) {
+      await plugin.disconnect();
+      this.plugins.delete(name);
+      this.configs.delete(name);
+      this.state.delete(name);
+      this.engine.removeContext(name);
+    }
+  }
+
+  /**
+   * Disconnect all plugins and clean up.
+   */
+  async disconnectAll(): Promise<void> {
+    const names = Array.from(this.plugins.keys());
+    await Promise.all(names.map((name) => this.remove(name)));
+  }
+}

package/src/discovery.ts

@@ -282,6 +282,8 @@ export async function discoverComponents(
 
           if (module && typeof module === "object" && module.template) {
             addSingleFileComponent(baseName, modulePath, module.template);
+          } else if (module && typeof module === "object") {
+            frameworkLoggers.discovery.warn(`Skipping "${entry.name}": has .ui() pattern but module has no .template property. Did you forget to call .ui(hypen\`...\`)?`);
           }
         } catch (e) {
           // Failed to import, skip this file

package/src/engine.browser.ts

@@ -269,4 +269,34 @@ export class Engine {
     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

@@ -181,10 +181,33 @@ export class Engine {
   /**
    * 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) => {
-      Promise.resolve(handler(action)).catch((err) => log.error("Action handler error:", err));
+      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);
+      }
     });
   }
 
@@ -224,4 +247,36 @@ export class Engine {
     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/index.ts

@@ -92,8 +92,24 @@ export type {
   ErrorContext,
   ErrorHandler,
   ErrorHandlerResult,
+  // Data source access in action handlers
+  DataSourceAccessor,
 } from "./app.js";
 
+// ============================================================================
+// DATA SOURCE PLUGIN SYSTEM
+// ============================================================================
+
+export { DataSourceManager } from "./datasource.js";
+export type {
+  DataSourcePlugin,
+  DataSourceStatus,
+  DataSourceQuery,
+  DataSourceSubscription,
+  DataSourceChange,
+  IDataSourceEngine,
+} from "./datasource.js";
+
 // ============================================================================
 // STATE MANAGEMENT
 // ============================================================================

package/src/managed-router.ts

@@ -84,6 +84,9 @@ export class ManagedRouter {
       this.globalContext.unregisterModule(moduleId);
     }
     this.persistedModules.clear();
+
+    // Clean up router event listeners
+    this.router.dispose();
   }
 
   /**

package/src/remote/server.ts

@@ -303,7 +303,12 @@ export class RemoteServer {
     engine.setComponentResolver(
       (componentName: string, _contextPath: string | null) => {
         const comp = this._discoveredComponents.get(componentName);
-        if (!comp) return null;
+        if (!comp) {
+          log.warn(
+            `Component "${componentName}" not found. Available: ${Array.from(this._discoveredComponents.keys()).join(", ") || "(none)"}`
+          );
+          return null;
+        }
 
         return {
           source: comp.template,
@@ -618,8 +623,12 @@ export class RemoteServer {
 
     let restored = false;
     const restore = (state: unknown) => {
+      if (state === null || typeof state !== 'object') {
+        log.warn("restore() called with non-object state, ignoring:", typeof state);
+        return;
+      }
       restored = true;
-      clientData.moduleInstance.updateState(state as any);
+      clientData.moduleInstance.updateState(state as Record<string, unknown>);
     };
 
     await handler({ session, restore });