@hypen-space/core 0.3.11 → 0.4.0

package/src/engine.ts

@@ -6,6 +6,10 @@
 // WASM module types
 import { WasmEngine } from "../wasm-node/hypen_engine.js";
 import { frameworkLoggers } from "./logger.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;
 
@@ -34,38 +38,6 @@ function unwrapForWasm<T>(value: T): T {
   }
 }
 
-export type Patch = {
-  type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
-  id?: string;
-  elementType?: string;
-  props?: Record<string, any>;
-  name?: string;
-  value?: any;
-  text?: string;
-  parentId?: string;
-  beforeId?: string;
-  eventName?: string;
-};
-
-export type Action = {
-  name: string;
-  payload?: any;
-  sender?: string;
-};
-
-export type RenderCallback = (patches: Patch[]) => void;
-export type ActionHandler = (action: Action) => void | Promise<void>;
-
-export type ResolvedComponent = {
-  source: string;
-  path: string;
-};
-
-export type ComponentResolver = (
-  componentName: string,
-  contextPath: string | null
-) => ResolvedComponent | null;
-
 /**
  * Engine wraps the WASM engine and provides a TypeScript-friendly API
  */

package/src/index.browser.ts

@@ -5,10 +5,9 @@
  */
 
 // ============================================================================
-// ENGINE API (Browser version)
+// CORE TYPES (WASM-free)
 // ============================================================================
 
-export { Engine } from "./engine.browser.js";
 export type {
   Patch,
   Action,
@@ -16,8 +15,11 @@ export type {
   ActionHandler as EngineActionHandler,
   ResolvedComponent,
   ComponentResolver,
-  EngineInitOptions,
-} from "./engine.browser.js";
+} from "./types.js";
+
+// NOTE: Engine (BrowserEngine) is NOT exported from the barrel.
+// Import it explicitly from its subpath to avoid pulling in WASM:
+//   import { Engine } from "@hypen-space/core/engine/browser"
 
 // ============================================================================
 // APP / MODULE SYSTEM

package/src/index.ts

@@ -42,10 +42,9 @@
  */
 
 // ============================================================================
-// ENGINE API
+// CORE TYPES (WASM-free)
 // ============================================================================
 
-export { Engine } from "./engine.js";
 export type {
   Patch,
   Action,
@@ -53,11 +52,12 @@ export type {
   ActionHandler as EngineActionHandler,
   ResolvedComponent,
   ComponentResolver as EngineComponentResolver,
-} from "./engine.js";
+} from "./types.js";
 
-// Browser engine (explicit WASM init)
-export { Engine as BrowserEngine } from "./engine.browser.js";
-export type { EngineInitOptions } from "./engine.browser.js";
+// NOTE: Engine and BrowserEngine are NOT exported from the barrel.
+// Import them explicitly from their subpaths to avoid pulling in WASM:
+//   import { Engine } from "@hypen-space/core/engine"
+//   import { Engine } from "@hypen-space/core/engine/browser"
 
 // ============================================================================
 // APP / MODULE SYSTEM

package/src/managed-router.ts

@@ -0,0 +1,195 @@
+/**
+ * Managed Router — orchestrates module mount/unmount on route changes.
+ *
+ * When the router navigates to a route:
+ * 1. Unmounts the previous module (destroy instance, unregister from GlobalContext)
+ * 2. Mounts the new module (create instance with namespaced state, register)
+ *
+ * Module names are used as state prefixes (lowercased) for isolation.
+ */
+
+import type { IEngine, HypenModuleDefinition } from "./app.js";
+import { HypenModuleInstance } 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");
+
+export interface RouteDefinition {
+  /** Route path pattern (e.g., "/", "/profile/:id") */
+  path: string;
+  /** Component name — used to look up in ModuleRegistry */
+  component: string;
+  /** Inline module definition (alternative to registry lookup) */
+  module?: HypenModuleDefinition;
+}
+
+export class ManagedRouter {
+  private router: HypenRouter;
+  private engine: IEngine;
+  private registry: ModuleRegistry;
+  private globalContext: HypenGlobalContext;
+  private routes: RouteDefinition[] = [];
+  private activeModule: HypenModuleInstance | null = null;
+  private activeRoute: RouteDefinition | null = null;
+  private unsubscribe: (() => void) | null = null;
+  /** Cached instances for modules with persist=true */
+  private persistedModules = new Map<string, HypenModuleInstance>();
+
+  constructor(
+    router: HypenRouter,
+    engine: IEngine,
+    registry: ModuleRegistry,
+    globalContext: HypenGlobalContext
+  ) {
+    this.router = router;
+    this.engine = engine;
+    this.registry = registry;
+    this.globalContext = globalContext;
+  }
+
+  /**
+   * Add a route definition.
+   */
+  addRoute(route: RouteDefinition): this {
+    this.routes.push(route);
+    return this;
+  }
+
+  /**
+   * Start listening for route changes and mount the initial route.
+   */
+  start(): void {
+    this.unsubscribe = this.router.onNavigate((routeState: RouteState) => {
+      this.handleRouteChange(routeState);
+    });
+  }
+
+  /**
+   * Stop listening and unmount the active module.
+   * Also destroys all persisted modules.
+   */
+  stop(): void {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    this.unmountActive();
+
+    // Destroy all persisted modules on full stop
+    for (const [moduleId, instance] of this.persistedModules) {
+      log.debug(`Destroying persisted module on stop: ${moduleId}`);
+      instance.destroy();
+      this.globalContext.unregisterModule(moduleId);
+    }
+    this.persistedModules.clear();
+  }
+
+  /**
+   * Get the currently active module instance.
+   */
+  getActiveModule(): HypenModuleInstance | null {
+    return this.activeModule;
+  }
+
+  /**
+   * Get the currently active route.
+   */
+  getActiveRoute(): RouteDefinition | null {
+    return this.activeRoute;
+  }
+
+  private handleRouteChange(routeState: RouteState): void {
+    const path = routeState.currentPath;
+    const matched = this.matchRoute(path);
+
+    if (!matched) {
+      log.debug(`No route matched for path: ${path}`);
+      this.unmountActive();
+      return;
+    }
+
+    // If same route, no need to remount
+    if (this.activeRoute && this.activeRoute.path === matched.path) {
+      return;
+    }
+
+    // Unmount old, mount new
+    this.unmountActive();
+    this.mount(matched);
+  }
+
+  private matchRoute(path: string): RouteDefinition | null {
+    for (const route of this.routes) {
+      if (this.router.matchPath(route.path, path) !== null) {
+        return route;
+      }
+    }
+    return null;
+  }
+
+  private mount(route: RouteDefinition): void {
+    // Look up module definition: inline first, then registry
+    const definition = route.module || this.registry.get(route.component);
+    if (!definition) {
+      log.debug(`No module definition found for component: ${route.component}`);
+      this.activeRoute = route;
+      return;
+    }
+
+    // Ensure the definition has a name for state namespacing
+    const namedDef = {
+      ...definition,
+      name: definition.name || route.component.toLowerCase(),
+    };
+
+    const moduleId = namedDef.name!.toLowerCase();
+
+    // Check for a persisted instance first
+    const persisted = this.persistedModules.get(moduleId);
+    if (persisted) {
+      log.debug(`Restoring persisted module: ${moduleId} for route: ${route.path}`);
+      this.activeModule = persisted;
+      this.activeRoute = route;
+      return;
+    }
+
+    log.debug(`Mounting module: ${namedDef.name} for route: ${route.path}`);
+
+    const instance = new HypenModuleInstance(
+      this.engine,
+      namedDef as HypenModuleDefinition<object>,
+      { root: this.router },
+      this.globalContext
+    );
+
+    // Register in global context under the module name (lowercase)
+    this.globalContext.registerModule(moduleId, instance);
+
+    this.activeModule = instance;
+    this.activeRoute = route;
+  }
+
+  private unmountActive(): void {
+    if (this.activeModule && this.activeRoute) {
+      const definition = this.activeRoute.module || this.registry.get(this.activeRoute.component);
+      const moduleId = (definition?.name || this.activeRoute.component).toLowerCase();
+      const persist = definition?.persist === true;
+
+      if (persist) {
+        log.debug(`Persisting module: ${moduleId} (persist=true)`);
+        this.persistedModules.set(moduleId, this.activeModule);
+        // Keep registered in GlobalContext so other modules can still access its state
+      } else {
+        log.debug(`Unmounting module: ${moduleId}`);
+        this.activeModule.destroy();
+        this.globalContext.unregisterModule(moduleId);
+      }
+    }
+
+    this.activeModule = null;
+    this.activeRoute = null;
+  }
+}

package/src/module-registry.ts

@@ -0,0 +1,76 @@
+/**
+ * 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();
+  }
+}

package/src/remote/client.ts

@@ -36,7 +36,7 @@ import type {
   SessionAckMessage,
   SessionExpiredMessage,
 } from "./types.js";
-import type { Patch } from "../engine.js";
+import type { Patch } from "../types.js";
 import {
   type Result,
   Ok,

package/src/remote/index.ts

@@ -37,5 +37,5 @@ export type {
   RemoteServerConfig,
 } from "./types.js";
 
-// Re-export Patch type from engine
-export type { Patch } from "../engine.js";
+// Re-export Patch type
+export type { Patch } from "../types.js";

package/src/remote/server.ts

@@ -44,7 +44,7 @@ import type {
   Session,
   SessionConfig,
 } from "./types.js";
-import type { Patch } from "../engine.js";
+import type { Patch } from "../types.js";
 import type { ServerWebSocket } from "bun";
 import { SessionManager } from "./session.js";
 import { frameworkLoggers } from "../logger.js";

package/src/remote/types.ts

@@ -2,7 +2,7 @@
  * Remote UI Protocol Types
  */
 
-import type { Patch } from "../engine.js";
+import type { Patch } from "../types.js";
 
 export type RemoteMessage =
   | InitialTreeMessage

package/src/renderer.ts

@@ -5,7 +5,7 @@
  * (DOM, Canvas, Native, etc.)
  */
 
-import type { Patch } from "./engine.js";
+import type { Patch } from "./types.js";
 import { frameworkLoggers } from "./logger.js";
 
 const log = frameworkLoggers.renderer;

package/src/resolver.ts

@@ -39,6 +39,12 @@ export interface ResolverOptions {
    * Useful for adding authentication, custom headers, etc.
    */
   customFetch?: (url: string) => Promise<string>;
+
+  /**
+   * Module registry for looking up pre-registered module definitions.
+   * When set, the resolver will check the registry before doing file I/O.
+   */
+  moduleRegistry?: { has: (name: string) => boolean; get: (name: string) => any };
 }
 
 /**
@@ -47,22 +53,48 @@ export interface ResolverOptions {
  */
 export class ComponentResolver {
   private cache = new Map<string, ComponentDefinition>();
-  private options: Required<ResolverOptions>;
+  private options: Required<Pick<ResolverOptions, 'baseDir' | 'cache' | 'customFetch'>> & Pick<ResolverOptions, 'moduleRegistry'>;
+
+  private moduleRegistry?: { has: (name: string) => boolean; get: (name: string) => any };
 
   constructor(options: ResolverOptions = {}) {
     this.options = {
       baseDir: options.baseDir || process.cwd(),
       cache: options.cache ?? true,
       customFetch: options.customFetch || this.defaultFetch.bind(this),
+      moduleRegistry: options.moduleRegistry,
     };
+    this.moduleRegistry = options.moduleRegistry;
   }
 
   /**
-   * Resolve a component from an import statement
+   * Resolve a component from an import statement.
+   * Checks the module registry first (if available), then falls back to file I/O.
    */
   async resolve(
     importStmt: ImportStatement
   ): Promise<Record<string, ComponentDefinition>> {
+    // Check module registry first — if a component is pre-registered,
+    // use its template directly (it will be mounted as a full module)
+    if (this.moduleRegistry) {
+      const names = importStmt.clause.type === "named"
+        ? importStmt.clause.names
+        : [importStmt.clause.name];
+
+      const allFound = names.every(name => this.moduleRegistry!.has(name));
+      if (allFound) {
+        const result: Record<string, ComponentDefinition> = {};
+        for (const name of names) {
+          const def = this.moduleRegistry!.get(name);
+          result[name] = {
+            module: def,
+            template: def?.template || "",
+          };
+        }
+        return result;
+      }
+    }
+
     const sourcePath = this.getSourcePath(importStmt.source);
 
     // Check cache first
@@ -91,13 +123,28 @@ export class ComponentResolver {
    * Resolve a component from a local file path
    */
   private async resolveLocal(path: string): Promise<ComponentDefinition> {
-    // For local paths, we expect the build system to have already
-    // processed them into the generated components file
-    // This is a fallback for dynamic resolution
-    throw new Error(
-      `Dynamic local component resolution not yet implemented: ${path}\n` +
-        `Please use the build-components.ts script to generate component imports.`
-    );
+    const { resolve, join } = await import("path");
+    const { readFile } = await import("fs/promises");
+
+    const basePath = resolve(this.options.baseDir, path);
+
+    // Try .hypen extension
+    const hypenPath = basePath.endsWith(".hypen")
+      ? basePath
+      : `${basePath}.hypen`;
+
+    const template = await readFile(hypenPath, "utf-8");
+
+    // Try loading sibling .ts module (stateless components have no module)
+    const modulePath = hypenPath.replace(/\.hypen$/, ".ts");
+    let module = {};
+    try {
+      module = await import(modulePath);
+    } catch {
+      // Stateless component — no module file
+    }
+
+    return { module, template };
   }
 
   /**

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Core types shared across the engine and runtime.
+ *
+ * These types are intentionally decoupled from the WASM engine so that
+ * packages can import them without pulling in any WASM code.
+ */
+
+export type Patch = {
+  type: "create" | "setProp" | "setText" | "insert" | "move" | "remove" | "attachEvent" | "detachEvent";
+  id?: string;
+  elementType?: string;
+  props?: Record<string, any>;
+  name?: string;
+  value?: any;
+  text?: string;
+  parentId?: string;
+  beforeId?: string;
+  eventName?: string;
+};
+
+export type Action = {
+  name: string;
+  payload?: any;
+  sender?: string;
+};
+
+export type RenderCallback = (patches: Patch[]) => void;
+export type ActionHandler = (action: Action) => void | Promise<void>;
+
+export type ResolvedComponent = {
+  source: string;
+  path: string;
+};
+
+export type ComponentResolver = (
+  componentName: string,
+  contextPath: string | null
+) => ResolvedComponent | null;

package/wasm-browser/README.md

@@ -583,6 +583,12 @@ pub use state::StateChange;
 
 ## Related Documentation
 
+- [Documentation Index](./docs/README.md) - Full documentation index
+- [Control Flow Components](./docs/control-flow.md) - ForEach, When/If, Map usage guide
+- [Router](./docs/router.md) - Declarative routing and navigation
+- [Architecture Internals](./docs/architecture.md) - Reactive system, reconciliation, IR
+- [Advanced SDK Usage](./docs/advanced-sdk-usage.md) - Custom renderers, component resolvers, Remote UI
+- [Glossary](./docs/glossary.md) - Key terms and binding syntax reference
+- [Browser Compatibility](./docs/browser-compatibility.md) - Browser, platform, and WASM target support
 - [BUILD_WASM.md](./BUILD_WASM.md) - Detailed WASM build instructions
 - [../parser/README.md](../parser/README.md) - Hypen parser documentation
-- [../hypen-render-bun/README.md](../hypen-render-bun/README.md) - Bun renderer implementation

package/wasm-browser/hypen_engine.d.ts

@@ -22,6 +22,7 @@ export class WasmEngine {
   constructor();
   /**
    * Parse and render Hypen DSL source code
+   * Supports documents with import statements - imports are resolved via the component resolver
    */
   renderSource(source: string): void;
   /**

package/wasm-browser/hypen_engine.js

@@ -282,6 +282,7 @@ export class WasmEngine {
     }
     /**
      * Parse and render Hypen DSL source code
+     * Supports documents with import statements - imports are resolved via the component resolver
      * @param {string} source
      */
     renderSource(source) {

package/wasm-browser/package.json

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

package/wasm-node/README.md

@@ -583,6 +583,12 @@ pub use state::StateChange;
 
 ## Related Documentation
 
+- [Documentation Index](./docs/README.md) - Full documentation index
+- [Control Flow Components](./docs/control-flow.md) - ForEach, When/If, Map usage guide
+- [Router](./docs/router.md) - Declarative routing and navigation
+- [Architecture Internals](./docs/architecture.md) - Reactive system, reconciliation, IR
+- [Advanced SDK Usage](./docs/advanced-sdk-usage.md) - Custom renderers, component resolvers, Remote UI
+- [Glossary](./docs/glossary.md) - Key terms and binding syntax reference
+- [Browser Compatibility](./docs/browser-compatibility.md) - Browser, platform, and WASM target support
 - [BUILD_WASM.md](./BUILD_WASM.md) - Detailed WASM build instructions
 - [../parser/README.md](../parser/README.md) - Hypen parser documentation
-- [../hypen-render-bun/README.md](../hypen-render-bun/README.md) - Bun renderer implementation

package/wasm-node/hypen_engine.d.ts

@@ -22,6 +22,7 @@ export class WasmEngine {
   constructor();
   /**
    * Parse and render Hypen DSL source code
+   * Supports documents with import statements - imports are resolved via the component resolver
    */
   renderSource(source: string): void;
   /**

package/wasm-node/hypen_engine.js

@@ -276,6 +276,7 @@ class WasmEngine {
     }
     /**
      * Parse and render Hypen DSL source code
+     * Supports documents with import statements - imports are resolved via the component resolver
      * @param {string} source
      */
     renderSource(source) {

package/wasm-node/package.json

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