@hypen-space/core 0.4.2 → 0.4.5

package/src/components/builtin.ts

@@ -4,7 +4,6 @@
  */
 
 import { app } from "../app.js";
-import type { HypenRouter } from "../router.js";
 import { frameworkLoggers } from "../logger.js";
 
 const log = frameworkLoggers.router;
@@ -36,7 +35,7 @@ export const Router = app
     }
 
     // Subscribe to router changes
-    const router = (context as any).__router as HypenRouter;
+    const router = context.router;
     if (!router) {
       log.error("Router not found in context");
       return;
@@ -149,7 +148,7 @@ export const Link = app
     { name: "__Link" }
   )
   .onAction("navigate", ({ state, context }) => {
-    const router = (context as any)?.__router as HypenRouter;
+    const router = context?.router;
     if (!router) {
       log.error("Link requires router context");
       return;
@@ -162,7 +161,7 @@ export const Link = app
     if (!context) return;
 
     // Check if current path matches this link's target
-    const router = (context as any).__router as HypenRouter;
+    const router = context.router;
     if (router) {
       router.onNavigate((routeState) => {
         state.isActive = routeState.currentPath === state.to;

package/src/discovery.ts

@@ -43,7 +43,7 @@ export interface DiscoveryOptions {
 
   /**
    * Recursively scan subdirectories
-   * Default: false
+   * Default: true
    */
   recursive?: boolean;
 
@@ -95,7 +95,7 @@ export async function discoverComponents(
 ): Promise<DiscoveredComponent[]> {
   const {
     patterns = ["single-file", "folder", "sibling", "index"],
-    recursive = false,
+    recursive = true,
     debug = false,
   } = options;
 

package/src/engine.browser.ts

@@ -4,6 +4,7 @@
  */
 
 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
@@ -125,10 +126,16 @@ export class Engine {
 
   /**
    * 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();
-    engine.renderSource(source);
+    try {
+      engine.renderSource(source);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
   }
 
   /**
@@ -141,15 +148,22 @@ export class Engine {
 
   /**
    * 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));
-    engine.renderInto(source, parentNodeId, safeState);
+    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();
@@ -159,7 +173,11 @@ export class Engine {
     }
 
     const plainValues = JSON.parse(JSON.stringify(values));
-    engine.updateStateSparse(paths, plainValues);
+    try {
+      engine.updateStateSparse(paths, plainValues);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
     log.debug("State changed (sparse):", paths);
   }
 
@@ -189,11 +207,16 @@ export class Engine {
 
   /**
    * 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}`);
-    engine.dispatchAction(name, payload ?? null);
+    try {
+      engine.dispatchAction(name, payload ?? null);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
   }
 
   /**

package/src/engine.ts

@@ -6,6 +6,7 @@
 // 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
@@ -89,10 +90,16 @@ export class Engine {
 
   /**
    * 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();
-    engine.renderSource(source);
+    try {
+      engine.renderSource(source);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
   }
 
   /**
@@ -105,14 +112,21 @@ export class Engine {
 
   /**
    * 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();
-    engine.renderInto(source, parentNodeId, unwrapForWasm(state));
+    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();
@@ -121,7 +135,11 @@ export class Engine {
       return;
     }
 
-    engine.updateStateSparse(paths, unwrapForWasm(values));
+    try {
+      engine.updateStateSparse(paths, unwrapForWasm(values));
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
     log.debug("State changed (sparse):", paths);
   }
 
@@ -149,10 +167,15 @@ export class Engine {
 
   /**
    * Dispatch an action
+   * @throws {HypenError} if the action dispatch fails
    */
   dispatchAction(name: string, payload?: any): void {
     const engine = this.ensureInitialized();
-    engine.dispatchAction(name, payload ?? null);
+    try {
+      engine.dispatchAction(name, payload ?? null);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
   }
 
   /**

package/src/index.browser.ts

@@ -28,9 +28,7 @@ export type {
 export { app, HypenApp, HypenAppBuilder, HypenModuleInstance } from "./app.js";
 export type {
   IEngine,
-  RouterContext,
   ActionContext,
-  ActionNext,
   GlobalContext,
   LifecycleHandler,
   ActionHandlerContext,

package/src/index.ts

@@ -74,9 +74,7 @@ export type { StateProxy, ItemProxy } from "./hypen.js";
 
 export type {
   IEngine,
-  RouterContext,
   ActionContext,
-  ActionNext,
   GlobalContext,
   LifecycleHandler,
   ActionHandlerContext,
@@ -245,6 +243,9 @@ export {
   ActionError,
   ConnectionError,
   StateError,
+  ParseError,
+  RenderError,
+  classifyEngineError,
 } from "./result.js";
 export type { Result } from "./result.js";
 

package/src/managed-router.ts

@@ -9,10 +9,9 @@
  */
 
 import type { IEngine, HypenModuleDefinition } from "./app.js";
-import { HypenModuleInstance } from "./app.js";
+import { HypenModuleInstance, HypenApp } from "./app.js";
 import type { HypenRouter, RouteState } from "./router.js";
 import type { HypenGlobalContext } from "./context.js";
-import { ModuleRegistry } from "./module-registry.js";
 import { createLogger } from "./logger.js";
 
 const log = createLogger("ManagedRouter");
@@ -20,7 +19,7 @@ const log = createLogger("ManagedRouter");
 export interface RouteDefinition {
   /** Route path pattern (e.g., "/", "/profile/:id") */
   path: string;
-  /** Component name — used to look up in ModuleRegistry */
+  /** Component name — used to look up in app registry */
   component: string;
   /** Inline module definition (alternative to registry lookup) */
   module?: HypenModuleDefinition;
@@ -29,7 +28,7 @@ export interface RouteDefinition {
 export class ManagedRouter {
   private router: HypenRouter;
   private engine: IEngine;
-  private registry: ModuleRegistry;
+  private registry: HypenApp;
   private globalContext: HypenGlobalContext;
   private routes: RouteDefinition[] = [];
   private activeModule: HypenModuleInstance | null = null;
@@ -41,7 +40,7 @@ export class ManagedRouter {
   constructor(
     router: HypenRouter,
     engine: IEngine,
-    registry: ModuleRegistry,
+    registry: HypenApp,
     globalContext: HypenGlobalContext
   ) {
     this.router = router;
@@ -161,7 +160,7 @@ export class ManagedRouter {
     const instance = new HypenModuleInstance(
       this.engine,
       namedDef as HypenModuleDefinition<object>,
-      { root: this.router },
+      this.router,
       this.globalContext
     );
 

package/src/remote/server.ts

@@ -1,36 +1,36 @@
 /**
  * RemoteServer - Stream Hypen apps over WebSocket with Session Management
  *
- * Usage:
+ * Usage with inline UI:
  * ```typescript
  * import { RemoteServer, app } from "@hypen-space/core";
  *
  * const counter = app
  *   .defineState({ count: 0 })
  *   .onAction("increment", ({ state }) => state.count++)
- *   .onDisconnect(async ({ state, session }) => {
- *     await redis.set(`session:${session.id}`, JSON.stringify(state));
- *   })
- *   .onReconnect(async ({ session, restore }) => {
- *     const saved = await redis.get(`session:${session.id}`);
- *     if (saved) restore(JSON.parse(saved));
- *   })
- *   .onExpire(async ({ session }) => {
- *     await redis.del(`session:${session.id}`);
- *   })
  *   .build();
  *
  * new RemoteServer()
  *   .module("Counter", counter)
  *   .ui(`Column { Text("Count: \${state.count}") }`)
- *   .session({ ttl: 3600, concurrent: "kick-old" })
  *   .listen(3000);
  * ```
+ *
+ * Usage with directory-based discovery (auto-resolves imports):
+ * ```typescript
+ * import { RemoteServer } from "@hypen-space/core";
+ * import chatModule from "./apps/chat/Chat/component.js";
+ *
+ * await new RemoteServer()
+ *   .source("./apps/chat")
+ *   .module("Chat", chatModule)
+ *   .listen(3001);
+ * ```
  */
 
 import { Engine } from "../engine.js";
 import { HypenModuleInstance } from "../app.js";
-import type { HypenModule } from "../app.js";
+import type { HypenModule, HypenModuleDefinition } from "../app.js";
 import type {
   RemoteMessage,
   RemoteClient,
@@ -44,10 +44,15 @@ import type {
   Session,
   SessionConfig,
 } from "./types.js";
-import type { Patch } from "../types.js";
+import type { Patch, ResolvedComponent } from "../types.js";
 import type { ServerWebSocket } from "bun";
 import { SessionManager } from "./session.js";
 import { frameworkLoggers } from "../logger.js";
+import {
+  discoverComponents,
+  loadDiscoveredComponents,
+  type DiscoveredComponent,
+} from "../discovery.js";
 
 const log = frameworkLoggers.remote;
 
@@ -72,6 +77,8 @@ export class RemoteServer {
   private _module: HypenModule<any> | null = null;
   private _moduleName: string = "App";
   private _ui: string = "";
+  private _sourceDir: string | null = null;
+  private _discoveredComponents: Map<string, { template: string; module?: HypenModuleDefinition<any> }> = new Map();
   private _config: RemoteServerConfig = {};
   private _sessionConfig: SessionConfig = {};
   private _onConnectionCallbacks: Array<(client: RemoteClient) => void> = [];
@@ -98,6 +105,26 @@ export class RemoteServer {
     return this;
   }
 
+  /**
+   * Set a source directory for automatic component discovery.
+   *
+   * All .hypen and .ts components in the directory (and subdirectories) are
+   * discovered automatically. The entry component's template is used as the
+   * UI, so calling .ui() is optional when .source() is set.
+   *
+   * @example
+   * ```typescript
+   * new RemoteServer()
+   *   .source("./apps/chat")
+   *   .module("Chat", chatModule)
+   *   .listen(3001);
+   * ```
+   */
+  source(dir: string): this {
+    this._sourceDir = dir;
+    return this;
+  }
+
   /**
    * Set server configuration
    */
@@ -133,13 +160,20 @@ export class RemoteServer {
   /**
    * Start the WebSocket server
    */
-  listen(port?: number): this {
+  async listen(port?: number): Promise<this> {
     if (!this._module) {
       throw new Error("Module not set. Call .module() before .listen()");
     }
 
+    // Run component discovery if source directory is set
+    if (this._sourceDir) {
+      await this.discoverFromSource();
+    }
+
     if (!this._ui) {
-      throw new Error("UI not set. Call .ui() before .listen()");
+      throw new Error(
+        "UI not set. Call .ui() or .source() before .listen()"
+      );
     }
 
     // Initialize session manager
@@ -214,6 +248,56 @@ export class RemoteServer {
     return `ws://${hostname}:${port}`;
   }
 
+  /**
+   * Discover components from the source directory.
+   * Populates _discoveredComponents and sets _ui from the entry component
+   * if not already set via .ui().
+   */
+  private async discoverFromSource(): Promise<void> {
+    const dir = this._sourceDir!;
+    log.info(`Discovering components from ${dir}...`);
+
+    const discovered = await discoverComponents(dir);
+    const loaded = await loadDiscoveredComponents(discovered);
+
+    for (const [name, { module, template }] of loaded) {
+      this._discoveredComponents.set(name, { template, module });
+    }
+
+    log.info(
+      `Discovered ${this._discoveredComponents.size} components: ${Array.from(this._discoveredComponents.keys()).join(", ")}`
+    );
+
+    // If .ui() was not called, use the entry component's template
+    if (!this._ui) {
+      const entry = this._discoveredComponents.get(this._moduleName);
+      if (entry) {
+        this._ui = entry.template;
+      }
+    }
+  }
+
+  /**
+   * Set up a component resolver on a client engine so that imports
+   * and component references in templates are resolved from discovered
+   * components.
+   */
+  private setupComponentResolver(engine: Engine): void {
+    if (this._discoveredComponents.size === 0) return;
+
+    engine.setComponentResolver(
+      (componentName: string, _contextPath: string | null) => {
+        const comp = this._discoveredComponents.get(componentName);
+        if (!comp) return null;
+
+        return {
+          source: comp.template,
+          path: componentName,
+        };
+      }
+    );
+  }
+
   /**
    * Handle new WebSocket connection
    * Waits for hello message before fully initializing
@@ -227,6 +311,9 @@ export class RemoteServer {
       const engine = new Engine();
       await engine.init();
 
+      // Wire up component resolver if we have discovered components
+      this.setupComponentResolver(engine);
+
       // Create module instance
       const moduleInstance = new HypenModuleInstance(engine, this._module!);
 
@@ -618,19 +705,27 @@ export class RemoteServer {
 /**
  * Convenience function to create and start a RemoteServer
  */
-export function serve(options: {
+export async function serve(options: {
   module: HypenModule<any>;
   moduleName?: string;
-  ui: string;
+  ui?: string;
+  source?: string;
   port?: number;
   hostname?: string;
   session?: SessionConfig;
   onConnection?: (client: RemoteClient) => void;
   onDisconnection?: (client: RemoteClient) => void;
-}): RemoteServer {
+}): Promise<RemoteServer> {
   const server = new RemoteServer()
-    .module(options.moduleName ?? "App", options.module)
-    .ui(options.ui);
+    .module(options.moduleName ?? "App", options.module);
+
+  if (options.source) {
+    server.source(options.source);
+  }
+
+  if (options.ui) {
+    server.ui(options.ui);
+  }
 
   if (options.port || options.hostname) {
     server.config({

package/src/result.ts

@@ -258,3 +258,51 @@ export class StateError extends HypenError {
     this.path = path;
   }
 }
+
+/**
+ * Error thrown when parsing Hypen DSL source fails
+ */
+export class ParseError extends HypenError {
+  readonly source?: string;
+
+  constructor(message: string, source?: string, cause?: unknown) {
+    super('PARSE_ERROR', message, {
+      context: { source },
+      cause: cause instanceof Error ? cause : undefined,
+    });
+    this.name = 'ParseError';
+    this.source = source;
+  }
+}
+
+/**
+ * Error thrown when rendering fails
+ */
+export class RenderError extends HypenError {
+  constructor(message: string, cause?: unknown) {
+    super('RENDER_ERROR', message, {
+      cause: cause instanceof Error ? cause : undefined,
+    });
+    this.name = 'RenderError';
+  }
+}
+
+/**
+ * Classify a WASM engine error string into the appropriate HypenError subclass.
+ * The engine returns JsValue error strings with known prefixes.
+ */
+export function classifyEngineError(err: unknown): HypenError {
+  const message = err instanceof Error ? err.message : String(err);
+
+  if (message.startsWith('Parse error:')) {
+    return new ParseError(message);
+  }
+  if (message.startsWith('Invalid state:') || message.startsWith('Invalid state patch:')) {
+    return new StateError(message);
+  }
+  if (message.startsWith('Parent node not found:')) {
+    return new RenderError(message);
+  }
+
+  return new RenderError(message);
+}

package/wasm-browser/package.json

@@ -5,7 +5,7 @@
     "Hypen Contributors"
   ],
   "description": "A Rust implementation of the Hypen engine",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "license": "MIT",
   "repository": {
     "type": "git",

package/wasm-node/package.json

@@ -4,7 +4,7 @@
     "Hypen Contributors"
   ],
   "description": "A Rust implementation of the Hypen engine",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,5 +16,7 @@
     "hypen_engine.d.ts"
   ],
   "main": "hypen_engine.js",
-  "types": "hypen_engine.d.ts"
-}
+  "types": "hypen_engine.d.ts",
+  "type": "commonjs",
+  "sideEffects": false
+}

package/src/module-registry.ts

@@ -1,76 +0,0 @@
-/**
- * Module Registry — maps component names to module definitions.
- *
- * Used by the import resolution pipeline and ManagedRouter to look up
- * module definitions by their component name (e.g., "HomePage", "ProfilePage").
- */
-
-import type { HypenModuleDefinition } from "./app.js";
-import { createLogger } from "./logger.js";
-
-const log = createLogger("ModuleRegistry");
-
-export class ModuleRegistry {
-  private definitions = new Map<string, HypenModuleDefinition>();
-
-  /**
-   * Register a module definition under a component name.
-   */
-  register(name: string, definition: HypenModuleDefinition): void {
-    if (this.definitions.has(name)) {
-      log.warn(`Module "${name}" is already registered. Overwriting.`);
-    }
-    this.definitions.set(name, definition);
-    log.debug(`Registered module definition: ${name}`);
-  }
-
-  /**
-   * Get a module definition by component name.
-   */
-  get(name: string): HypenModuleDefinition | undefined {
-    return this.definitions.get(name);
-  }
-
-  /**
-   * Check if a module definition exists.
-   */
-  has(name: string): boolean {
-    return this.definitions.has(name);
-  }
-
-  /**
-   * Get all registered definitions.
-   */
-  getAll(): Map<string, HypenModuleDefinition> {
-    return new Map(this.definitions);
-  }
-
-  /**
-   * Get all registered component names.
-   */
-  getNames(): string[] {
-    return Array.from(this.definitions.keys());
-  }
-
-  /**
-   * Unregister a module definition.
-   */
-  unregister(name: string): void {
-    this.definitions.delete(name);
-    log.debug(`Unregistered module definition: ${name}`);
-  }
-
-  /**
-   * Number of registered definitions.
-   */
-  get size(): number {
-    return this.definitions.size;
-  }
-
-  /**
-   * Clear all registered definitions.
-   */
-  clear(): void {
-    this.definitions.clear();
-  }
-}