@hypen-space/core 0.3.12 → 0.4.0

package/dist/resolver.js

@@ -31,14 +31,32 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 class ComponentResolver {
   cache = new Map;
   options;
+  moduleRegistry;
   constructor(options = {}) {
     this.options = {
       baseDir: options.baseDir || process.cwd(),
       cache: options.cache ?? true,
-      customFetch: options.customFetch || this.defaultFetch.bind(this)
+      customFetch: options.customFetch || this.defaultFetch.bind(this),
+      moduleRegistry: options.moduleRegistry
     };
+    this.moduleRegistry = options.moduleRegistry;
   }
   async resolve(importStmt) {
+    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 = {};
+        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);
     if (this.options.cache && this.cache.has(sourcePath)) {
       const cached = this.cache.get(sourcePath);
@@ -56,8 +74,17 @@ class ComponentResolver {
     return this.extractComponents(importStmt.clause, component);
   }
   async resolveLocal(path) {
-    throw new Error(`Dynamic local component resolution not yet implemented: ${path}
-` + `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);
+    const hypenPath = basePath.endsWith(".hypen") ? basePath : `${basePath}.hypen`;
+    const template = await readFile(hypenPath, "utf-8");
+    const modulePath = hypenPath.replace(/\.hypen$/, ".ts");
+    let module = {};
+    try {
+      module = await import(modulePath);
+    } catch {}
+    return { module, template };
   }
   async resolveUrl(url) {
     try {
@@ -124,4 +151,4 @@ export {
   ComponentResolver
 };
 
-//# debugId=708BFB387356D58864756E2164756E21
+//# debugId=20EC11627252563C64756E2164756E21

package/dist/resolver.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/resolver.ts"],
   "sourcesContent": [
-    "/**\n * Component Resolver\n * Resolves component imports from local paths or web URLs\n */\n\nexport interface ImportStatement {\n  clause: ImportClause;\n  source: ImportSource;\n}\n\nexport type ImportClause =\n  | { type: \"named\"; names: string[] }\n  | { type: \"default\"; name: string };\n\nexport type ImportSource =\n  | { type: \"local\"; path: string }\n  | { type: \"url\"; url: string };\n\nexport interface ComponentDefinition {\n  module: any;\n  template: string;\n}\n\nexport interface ResolverOptions {\n  /**\n   * Base directory for resolving relative local paths\n   * Defaults to current working directory\n   */\n  baseDir?: string;\n\n  /**\n   * Cache resolved components to avoid re-fetching\n   * Defaults to true\n   */\n  cache?: boolean;\n\n  /**\n   * Custom fetch function for URL imports\n   * Useful for adding authentication, custom headers, etc.\n   */\n  customFetch?: (url: string) => Promise<string>;\n}\n\n/**\n * Component Resolver\n * Resolves and loads components from local files or remote URLs\n */\nexport class ComponentResolver {\n  private cache = new Map<string, ComponentDefinition>();\n  private options: Required<ResolverOptions>;\n\n  constructor(options: ResolverOptions = {}) {\n    this.options = {\n      baseDir: options.baseDir || process.cwd(),\n      cache: options.cache ?? true,\n      customFetch: options.customFetch || this.defaultFetch.bind(this),\n    };\n  }\n\n  /**\n   * Resolve a component from an import statement\n   */\n  async resolve(\n    importStmt: ImportStatement\n  ): Promise<Record<string, ComponentDefinition>> {\n    const sourcePath = this.getSourcePath(importStmt.source);\n\n    // Check cache first\n    if (this.options.cache && this.cache.has(sourcePath)) {\n      const cached = this.cache.get(sourcePath)!;\n      return this.extractComponents(importStmt.clause, cached);\n    }\n\n    // Load the component\n    let component: ComponentDefinition;\n    if (importStmt.source.type === \"local\") {\n      component = await this.resolveLocal(importStmt.source.path);\n    } else {\n      component = await this.resolveUrl(importStmt.source.url);\n    }\n\n    // Cache it\n    if (this.options.cache) {\n      this.cache.set(sourcePath, component);\n    }\n\n    return this.extractComponents(importStmt.clause, component);\n  }\n\n  /**\n   * Resolve a component from a local file path\n   */\n  private async resolveLocal(path: string): Promise<ComponentDefinition> {\n    // For local paths, we expect the build system to have already\n    // processed them into the generated components file\n    // This is a fallback for dynamic resolution\n    throw new Error(\n      `Dynamic local component resolution not yet implemented: ${path}\\n` +\n        `Please use the build-components.ts script to generate component imports.`\n    );\n  }\n\n  /**\n   * Resolve a component from a URL\n   */\n  private async resolveUrl(url: string): Promise<ComponentDefinition> {\n    try {\n      const response = await this.options.customFetch(url);\n      const data = JSON.parse(response);\n\n      // Expected format: { module: {...}, template: \"...\" }\n      if (!data.module || !data.template) {\n        throw new Error(\n          `Invalid component format from ${url}. Expected { module, template }`\n        );\n      }\n\n      return data;\n    } catch (error) {\n      throw new Error(\n        `Failed to resolve component from ${url}: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n  }\n\n  /**\n   * Default fetch implementation\n   */\n  private async defaultFetch(url: string): Promise<string> {\n    const response = await fetch(url);\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n    return response.text();\n  }\n\n  /**\n   * Extract the requested components based on the import clause\n   */\n  private extractComponents(\n    clause: ImportClause,\n    component: ComponentDefinition\n  ): Record<string, ComponentDefinition> {\n    if (clause.type === \"default\") {\n      return {\n        [clause.name]: component,\n      };\n    } else {\n      // Named imports - for now, we only support single exports\n      // In the future, we could support exporting multiple components\n      // from a single file\n      const result: Record<string, ComponentDefinition> = {};\n      for (const name of clause.names) {\n        result[name] = component;\n      }\n      return result;\n    }\n  }\n\n  /**\n   * Get the source path as a string (for caching)\n   */\n  private getSourcePath(source: ImportSource): string {\n    return source.type === \"local\" ? source.path : source.url;\n  }\n\n  /**\n   * Clear the component cache\n   */\n  clearCache(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Parse import statements from Hypen DSL text\n   * This is a simple parser that extracts import statements\n   */\n  static parseImports(text: string): ImportStatement[] {\n    const imports: ImportStatement[] = [];\n    const importRegex =\n      /import\\s+(?:(\\{[^}]*\\})|(\\w+))\\s+from\\s+[\"']([^\"']+)[\"']/g;\n\n    let match;\n    while ((match = importRegex.exec(text)) !== null) {\n      const [, namedImports, defaultImport, source] = match;\n\n      if (!source) continue;\n\n      let clause: ImportClause;\n      if (namedImports) {\n        // Named imports: { Button, Card }\n        const names = namedImports\n          .slice(1, -1) // Remove { and }\n          .split(\",\")\n          .map((n) => n.trim())\n          .filter((n) => n.length > 0);\n        clause = { type: \"named\", names };\n      } else if (defaultImport) {\n        // Default import: HomePage\n        clause = { type: \"default\", name: defaultImport };\n      } else {\n        continue;\n      }\n\n      // Determine if source is URL or local path\n      const sourceObj: ImportSource = source.startsWith(\"http://\") ||\n        source.startsWith(\"https://\")\n        ? { type: \"url\", url: source }\n        : { type: \"local\", path: source };\n\n      imports.push({ clause, source: sourceObj });\n    }\n\n    return imports;\n  }\n}\n"
+    "/**\n * Component Resolver\n * Resolves component imports from local paths or web URLs\n */\n\nexport interface ImportStatement {\n  clause: ImportClause;\n  source: ImportSource;\n}\n\nexport type ImportClause =\n  | { type: \"named\"; names: string[] }\n  | { type: \"default\"; name: string };\n\nexport type ImportSource =\n  | { type: \"local\"; path: string }\n  | { type: \"url\"; url: string };\n\nexport interface ComponentDefinition {\n  module: any;\n  template: string;\n}\n\nexport interface ResolverOptions {\n  /**\n   * Base directory for resolving relative local paths\n   * Defaults to current working directory\n   */\n  baseDir?: string;\n\n  /**\n   * Cache resolved components to avoid re-fetching\n   * Defaults to true\n   */\n  cache?: boolean;\n\n  /**\n   * Custom fetch function for URL imports\n   * Useful for adding authentication, custom headers, etc.\n   */\n  customFetch?: (url: string) => Promise<string>;\n\n  /**\n   * Module registry for looking up pre-registered module definitions.\n   * When set, the resolver will check the registry before doing file I/O.\n   */\n  moduleRegistry?: { has: (name: string) => boolean; get: (name: string) => any };\n}\n\n/**\n * Component Resolver\n * Resolves and loads components from local files or remote URLs\n */\nexport class ComponentResolver {\n  private cache = new Map<string, ComponentDefinition>();\n  private options: Required<Pick<ResolverOptions, 'baseDir' | 'cache' | 'customFetch'>> & Pick<ResolverOptions, 'moduleRegistry'>;\n\n  private moduleRegistry?: { has: (name: string) => boolean; get: (name: string) => any };\n\n  constructor(options: ResolverOptions = {}) {\n    this.options = {\n      baseDir: options.baseDir || process.cwd(),\n      cache: options.cache ?? true,\n      customFetch: options.customFetch || this.defaultFetch.bind(this),\n      moduleRegistry: options.moduleRegistry,\n    };\n    this.moduleRegistry = options.moduleRegistry;\n  }\n\n  /**\n   * Resolve a component from an import statement.\n   * Checks the module registry first (if available), then falls back to file I/O.\n   */\n  async resolve(\n    importStmt: ImportStatement\n  ): Promise<Record<string, ComponentDefinition>> {\n    // Check module registry first — if a component is pre-registered,\n    // use its template directly (it will be mounted as a full module)\n    if (this.moduleRegistry) {\n      const names = importStmt.clause.type === \"named\"\n        ? importStmt.clause.names\n        : [importStmt.clause.name];\n\n      const allFound = names.every(name => this.moduleRegistry!.has(name));\n      if (allFound) {\n        const result: Record<string, ComponentDefinition> = {};\n        for (const name of names) {\n          const def = this.moduleRegistry!.get(name);\n          result[name] = {\n            module: def,\n            template: def?.template || \"\",\n          };\n        }\n        return result;\n      }\n    }\n\n    const sourcePath = this.getSourcePath(importStmt.source);\n\n    // Check cache first\n    if (this.options.cache && this.cache.has(sourcePath)) {\n      const cached = this.cache.get(sourcePath)!;\n      return this.extractComponents(importStmt.clause, cached);\n    }\n\n    // Load the component\n    let component: ComponentDefinition;\n    if (importStmt.source.type === \"local\") {\n      component = await this.resolveLocal(importStmt.source.path);\n    } else {\n      component = await this.resolveUrl(importStmt.source.url);\n    }\n\n    // Cache it\n    if (this.options.cache) {\n      this.cache.set(sourcePath, component);\n    }\n\n    return this.extractComponents(importStmt.clause, component);\n  }\n\n  /**\n   * Resolve a component from a local file path\n   */\n  private async resolveLocal(path: string): Promise<ComponentDefinition> {\n    const { resolve, join } = await import(\"path\");\n    const { readFile } = await import(\"fs/promises\");\n\n    const basePath = resolve(this.options.baseDir, path);\n\n    // Try .hypen extension\n    const hypenPath = basePath.endsWith(\".hypen\")\n      ? basePath\n      : `${basePath}.hypen`;\n\n    const template = await readFile(hypenPath, \"utf-8\");\n\n    // Try loading sibling .ts module (stateless components have no module)\n    const modulePath = hypenPath.replace(/\\.hypen$/, \".ts\");\n    let module = {};\n    try {\n      module = await import(modulePath);\n    } catch {\n      // Stateless component — no module file\n    }\n\n    return { module, template };\n  }\n\n  /**\n   * Resolve a component from a URL\n   */\n  private async resolveUrl(url: string): Promise<ComponentDefinition> {\n    try {\n      const response = await this.options.customFetch(url);\n      const data = JSON.parse(response);\n\n      // Expected format: { module: {...}, template: \"...\" }\n      if (!data.module || !data.template) {\n        throw new Error(\n          `Invalid component format from ${url}. Expected { module, template }`\n        );\n      }\n\n      return data;\n    } catch (error) {\n      throw new Error(\n        `Failed to resolve component from ${url}: ${error instanceof Error ? error.message : String(error)}`\n      );\n    }\n  }\n\n  /**\n   * Default fetch implementation\n   */\n  private async defaultFetch(url: string): Promise<string> {\n    const response = await fetch(url);\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n    return response.text();\n  }\n\n  /**\n   * Extract the requested components based on the import clause\n   */\n  private extractComponents(\n    clause: ImportClause,\n    component: ComponentDefinition\n  ): Record<string, ComponentDefinition> {\n    if (clause.type === \"default\") {\n      return {\n        [clause.name]: component,\n      };\n    } else {\n      // Named imports - for now, we only support single exports\n      // In the future, we could support exporting multiple components\n      // from a single file\n      const result: Record<string, ComponentDefinition> = {};\n      for (const name of clause.names) {\n        result[name] = component;\n      }\n      return result;\n    }\n  }\n\n  /**\n   * Get the source path as a string (for caching)\n   */\n  private getSourcePath(source: ImportSource): string {\n    return source.type === \"local\" ? source.path : source.url;\n  }\n\n  /**\n   * Clear the component cache\n   */\n  clearCache(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Parse import statements from Hypen DSL text\n   * This is a simple parser that extracts import statements\n   */\n  static parseImports(text: string): ImportStatement[] {\n    const imports: ImportStatement[] = [];\n    const importRegex =\n      /import\\s+(?:(\\{[^}]*\\})|(\\w+))\\s+from\\s+[\"']([^\"']+)[\"']/g;\n\n    let match;\n    while ((match = importRegex.exec(text)) !== null) {\n      const [, namedImports, defaultImport, source] = match;\n\n      if (!source) continue;\n\n      let clause: ImportClause;\n      if (namedImports) {\n        // Named imports: { Button, Card }\n        const names = namedImports\n          .slice(1, -1) // Remove { and }\n          .split(\",\")\n          .map((n) => n.trim())\n          .filter((n) => n.length > 0);\n        clause = { type: \"named\", names };\n      } else if (defaultImport) {\n        // Default import: HomePage\n        clause = { type: \"default\", name: defaultImport };\n      } else {\n        continue;\n      }\n\n      // Determine if source is URL or local path\n      const sourceObj: ImportSource = source.startsWith(\"http://\") ||\n        source.startsWith(\"https://\")\n        ? { type: \"url\", url: source }\n        : { type: \"local\", path: source };\n\n      imports.push({ clause, source: sourceObj });\n    }\n\n    return imports;\n  }\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "708BFB387356D58864756E2164756E21",
+  "mappings": "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",
+  "debugId": "20EC11627252563C64756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypen-space/core",
-  "version": "0.3.12",
+  "version": "0.4.0",
   "description": "Hypen core engine - Platform-agnostic reactive UI runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -129,6 +129,12 @@
       "bun": "./src/disposable.ts",
       "import": "./dist/disposable.js",
       "default": "./dist/disposable.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "bun": "./src/types.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
     }
   },
   "files": [

package/src/app.ts

@@ -3,7 +3,7 @@
  * Implements the stateful module system from RFC-0001
  */
 
-import type { Action } from "./engine.js";
+import type { Action } from "./types.js";
 import type { Session } from "./remote/types.js";
 import { type Result, Ok, Err, fromPromise, ActionError, HypenError } from "./result.js";
 
@@ -383,7 +383,11 @@ export class HypenModuleInstance<T extends object = any> {
     this.routerContext = routerContext;
     this.globalContext = globalContext;
 
+    // Named state prefix — all lowercase per convention
+    const statePrefix = (definition.name || "").toLowerCase();
+
     // Create observable state that sends only changed paths and values to engine
+    // When a prefix is set, all paths are namespaced (e.g., "homepage.count")
     this.state = createObservableState<T>(definition.initialState as T & object, {
       onChange: (change: StateChange) => {
         // Send only the changed paths and their new values (not the whole state)
@@ -391,14 +395,22 @@ export class HypenModuleInstance<T extends object = any> {
         // Notify all registered callbacks
         this.stateChangeCallbacks.forEach(cb => cb());
       },
+      pathPrefix: statePrefix || undefined,
     });
 
     // Register with engine (initial state registration)
+    // When prefixed, nest the state under the module name so the engine sees
+    // e.g., { homepage: { count: 0 } } instead of { count: 0 }
+    const snapshot = getStateSnapshot(this.state);
+    const prefixedState = statePrefix
+      ? { [statePrefix]: snapshot }
+      : snapshot;
+
     this.engine.setModule(
       definition.name || "AnonymousModule",
       definition.actions,
       definition.stateKeys,
-      getStateSnapshot(this.state)
+      prefixedState
     );
 
     // Register action handlers with flexible parameter support

package/src/discovery.ts

@@ -123,7 +123,9 @@ export async function discoverComponents(
 
     seen.add(name);
     const templateRaw = readFileSync(hypenPath, "utf-8");
-    const template = removeImports(templateRaw).trim();
+    // Preserve import statements in templates — the engine now processes them
+    // via parse_document() and resolves imports through the component resolver
+    const template = templateRaw.trim();
 
     components.push({
       name,

package/src/engine.browser.ts

@@ -4,6 +4,10 @@
  */
 
 import { frameworkLoggers } from "./logger.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;
 
@@ -12,38 +16,6 @@ const log = frameworkLoggers.engine;
 let wasmInit: ((path?: string) => Promise<void>) | null = null;
 let WasmEngineClass: any = null;
 
-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;
-
 export interface EngineInitOptions {
   /**
    * URL to the WASM binary file.

package/src/engine.ts

@@ -3,12 +3,13 @@
  * Node.js / Bundler target
  */
 
-// WASM module loaded lazily to avoid pulling readFileSync into browser bundles
-import type { WasmEngine as WasmEngineType } from "../wasm-node/hypen_engine.js";
-type WasmEngine = WasmEngineType;
-let WasmEngineClass: (new () => WasmEngine) | null = null;
-
+// 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;
 
@@ -37,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
  */
@@ -82,13 +51,8 @@ export class Engine {
   async init(): Promise<void> {
     if (this.initialized) return;
 
-    // Lazy-load WASM to avoid pulling readFileSync into browser bundles
-    if (!WasmEngineClass) {
-      const wasm = await import("../wasm-node/hypen_engine.js");
-      WasmEngineClass = wasm.WasmEngine;
-    }
-
-    this.wasmEngine = new WasmEngineClass();
+    // For bundler target, WASM is auto-initialized
+    this.wasmEngine = new WasmEngine();
     this.initialized = true;
   }
 

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