@hypen-space/core 0.4.3 → 0.4.5

package/src/app.ts

@@ -21,22 +21,12 @@ import { createLogger } from "./logger.js";
 
 const log = createLogger("ModuleInstance");
 
-export type RouterContext = {
-  root: HypenRouter;
-  current?: HypenRouter;
-  parent?: HypenRouter;
-};
-
-export type ActionContext = {
+export type ActionContext<P = unknown> = {
   name: string;
-  payload?: unknown;
+  payload?: P;
   sender?: string;
 };
 
-export type ActionNext = {
-  router: HypenRouter; // Direct access to router instance (from nearest parent)
-};
-
 export type GlobalContext = {
   getModule: <T = unknown>(id: string) => ModuleReference<T>;
   hasModule: (id: string) => boolean;
@@ -44,7 +34,7 @@ export type GlobalContext = {
   getGlobalState: () => Record<string, unknown>;
   emit: (event: string, payload?: unknown) => void;
   on: (event: string, handler: (payload?: unknown) => void) => () => void;
-  __router?: unknown; // Internal: router instance for built-in Router component
+  router: HypenRouter | null;
 };
 
 export type LifecycleHandler<T> = (
@@ -55,17 +45,16 @@ export type LifecycleHandler<T> = (
 /**
  * Action handler context - all parameters available explicitly
  */
-export interface ActionHandlerContext<T> {
-  action: ActionContext;
+export interface ActionHandlerContext<T, P = unknown> {
+  action: ActionContext<P>;
   state: T;
-  next: ActionNext;
   context: GlobalContext;
 }
 
 /**
  * Action handler - receives all context in a single object
  */
-export type ActionHandler<T> = (ctx: ActionHandlerContext<T>) => void | Promise<void>;
+export type ActionHandler<T, P = unknown> = (ctx: ActionHandlerContext<T, P>) => void | Promise<void>;
 
 /**
  * Context passed to onDisconnect handler
@@ -152,7 +141,7 @@ export interface HypenModuleDefinition<T = unknown> {
   template?: string;
   handlers: {
     onCreated?: LifecycleHandler<T>;
-    onAction: Map<string, ActionHandler<T>>;
+    onAction: Map<string, ActionHandler<T, any>>;
     onDestroyed?: LifecycleHandler<T>;
     /** Called when client disconnects (session persists for TTL) */
     onDisconnect?: DisconnectHandler<T>;
@@ -177,20 +166,23 @@ export class HypenAppBuilder<T> {
   private initialState: T;
   private options: { persist?: boolean; version?: number; name?: string };
   private createdHandler?: LifecycleHandler<T>;
-  private actionHandlers: Map<string, ActionHandler<T>> = new Map();
+  private actionHandlers: Map<string, ActionHandler<T, any>> = new Map();
   private destroyedHandler?: LifecycleHandler<T>;
   private disconnectHandler?: DisconnectHandler<T>;
   private reconnectHandler?: ReconnectHandler<T>;
   private expireHandler?: ExpireHandler;
   private errorHandler?: ErrorHandler<T>;
   private template?: string;
+  private _registry?: Map<string, HypenModuleDefinition>;
 
   constructor(
     initialState: T,
-    options?: { persist?: boolean; version?: number; name?: string }
+    options?: { persist?: boolean; version?: number; name?: string },
+    registry?: Map<string, HypenModuleDefinition>
   ) {
     this.initialState = initialState;
     this.options = options || {};
+    this._registry = registry;
   }
 
   /**
@@ -202,10 +194,24 @@ export class HypenAppBuilder<T> {
   }
 
   /**
-   * Register a handler for a specific action
+   * Register a handler for a specific action.
+   * Optionally provide a payload type parameter for typed action payloads.
+   *
+   * @example
+   * ```typescript
+   * // Typed payload:
+   * .onAction<{ amount: number }>("add", ({ action, state }) => {
+   *   action.payload.amount; // fully typed
+   * })
+   *
+   * // Untyped (payload is unknown):
+   * .onAction("add", ({ action, state }) => {
+   *   action.payload; // unknown
+   * })
+   * ```
    */
-  onAction(name: string, fn: ActionHandler<T>): this {
-    this.actionHandlers.set(name, fn);
+  onAction<P = unknown>(name: string, fn: ActionHandler<T, P>): this {
+    this.actionHandlers.set(name, fn as ActionHandler<T, any>);
     return this;
   }
 
@@ -319,7 +325,7 @@ export class HypenAppBuilder<T> {
       ? Object.keys(this.initialState)
       : [];
 
-    return {
+    const definition: HypenModuleDefinition<T> = {
       name: this.options.name,
       actions: Array.from(this.actionHandlers.keys()),
       stateKeys,
@@ -337,13 +343,27 @@ export class HypenAppBuilder<T> {
         onError: this.errorHandler,
       },
     };
+
+    // Auto-register in the app registry when the module has a name
+    if (this.options.name && this._registry) {
+      this._registry.set(this.options.name, definition as HypenModuleDefinition);
+    }
+
+    return definition;
   }
 }
 
 /**
- * Hypen App API
+ * Hypen App API — singleton factory and component registry.
+ *
+ * Modules built with a `name` are automatically registered here.
+ * Consumers (ManagedRouter, RemoteServer, ComponentResolver) read from this
+ * registry instead of requiring a separate ModuleRegistry instance.
  */
 export class HypenApp {
+  /** @internal */
+  readonly _registry = new Map<string, HypenModuleDefinition>();
+
   /**
    * Define the initial state for a module
    */
@@ -351,7 +371,83 @@ export class HypenApp {
     initial: T,
     options?: { persist?: boolean; version?: number; name?: string }
   ): HypenAppBuilder<T> {
-    return new HypenAppBuilder(initial, options);
+    return new HypenAppBuilder(initial, options, this._registry);
+  }
+
+  /**
+   * Convenience: start a module builder with a name pre-set.
+   *
+   * @example
+   * ```typescript
+   * export default app
+   *   .module("Settings")
+   *   .defineState({ theme: "dark" })
+   *   .ui(hypen`...`);
+   * ```
+   */
+  module(name: string) {
+    const registry = this._registry;
+    return {
+      defineState: <T>(
+        initial: T,
+        options?: { persist?: boolean; version?: number }
+      ): HypenAppBuilder<T> => {
+        return new HypenAppBuilder(initial, { ...options, name }, registry);
+      },
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Registry API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get a registered module definition by component name.
+   */
+  get(name: string): HypenModuleDefinition | undefined {
+    return this._registry.get(name);
+  }
+
+  /**
+   * Check if a module definition is registered.
+   */
+  has(name: string): boolean {
+    return this._registry.has(name);
+  }
+
+  /**
+   * Read-only view of all registered component definitions.
+   */
+  get components(): ReadonlyMap<string, HypenModuleDefinition> {
+    return this._registry;
+  }
+
+  /**
+   * Get all registered component names.
+   */
+  getNames(): string[] {
+    return Array.from(this._registry.keys());
+  }
+
+  /**
+   * Number of registered definitions.
+   */
+  get size(): number {
+    return this._registry.size;
+  }
+
+  /**
+   * Unregister a module definition.
+   */
+  unregister(name: string): void {
+    this._registry.delete(name);
+  }
+
+  /**
+   * Clear all registered definitions.
+   */
+  clear(): void {
+    this._registry.clear();
   }
 }
 
@@ -368,19 +464,19 @@ export class HypenModuleInstance<T extends object = any> {
   private definition: HypenModuleDefinition<T>;
   private state: T;
   private isDestroyed = false;
-  private routerContext?: RouterContext;
+  private router: HypenRouter | null;
   private globalContext?: HypenGlobalContext;
   private stateChangeCallbacks: Array<() => void> = [];
 
   constructor(
     engine: IEngine,
     definition: HypenModuleDefinition<T>,
-    routerContext?: RouterContext,
+    router?: HypenRouter | null,
     globalContext?: HypenGlobalContext
   ) {
     this.engine = engine;
     this.definition = definition;
-    this.routerContext = routerContext;
+    this.router = router ?? null;
     this.globalContext = globalContext;
 
     // Named state prefix — all lowercase per convention
@@ -425,10 +521,6 @@ export class HypenModuleInstance<T extends object = any> {
           sender: action.sender,
         };
 
-        const next: ActionNext = {
-          router: this.routerContext?.root || (null as any),
-        };
-
         const context: GlobalContext | undefined = this.globalContext
           ? this.createGlobalContextAPI()
           : undefined;
@@ -437,7 +529,6 @@ export class HypenModuleInstance<T extends object = any> {
         const result = await this.executeAction(actionName, handler, {
           action: actionCtx,
           state: this.state,
-          next,
           context: context!,
         });
 
@@ -452,6 +543,22 @@ export class HypenModuleInstance<T extends object = any> {
       });
     }
 
+    // Auto-register __hypen_bind for .bind() two-way binding support
+    this.engine.onAction("__hypen_bind", (action: Action) => {
+      const payload = action.payload as { path?: string; value?: unknown } | null;
+      if (!payload?.path) return;
+
+      const segments = payload.path.split(".");
+      let target: any = this.state;
+      for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i]!;
+        target = target?.[seg];
+        if (target == null) return;
+      }
+      const lastSeg = segments[segments.length - 1]!;
+      target[lastSeg] = payload.value;
+    });
+
     // Call onCreated
     this.callCreatedHandler();
   }
@@ -473,12 +580,10 @@ export class HypenModuleInstance<T extends object = any> {
       emit: (event: string, payload?: any) => ctx.emit(event, payload),
       on: (event: string, handler: (payload?: any) => void) =>
         ctx.on(event, handler),
+      router: this.router,
     };
 
-    // Expose router and hypen engine for built-in components (if available)
-    if ((ctx as any).__router) {
-      api.__router = (ctx as any).__router;
-    }
+    // Expose hypen engine for built-in components (if available)
     if ((ctx as any).__hypenEngine) {
       (api as any).__hypenEngine = (ctx as any).__hypenEngine;
     }
@@ -492,7 +597,7 @@ export class HypenModuleInstance<T extends object = any> {
    */
   private async executeAction(
     actionName: string,
-    handler: ActionHandler<T>,
+    handler: ActionHandler<T, any>,
     ctx: ActionHandlerContext<T>
   ): Promise<Result<void, ActionError>> {
     try {
@@ -575,7 +680,15 @@ export class HypenModuleInstance<T extends object = any> {
   private async callCreatedHandler(): Promise<void> {
     if (this.definition.handlers.onCreated) {
       const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
-      await this.definition.handlers.onCreated(this.state, context);
+      try {
+        await this.definition.handlers.onCreated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onCreated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "created" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
     }
   }
 
@@ -593,7 +706,15 @@ export class HypenModuleInstance<T extends object = any> {
     if (this.isDestroyed) return;
 
     if (this.definition.handlers.onDestroyed) {
-      await this.definition.handlers.onDestroyed(this.state);
+      try {
+        await this.definition.handlers.onDestroyed(this.state);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onDestroyed", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "destroyed" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
     }
 
     this.isDestroyed = true;

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
     );