@hypen-space/core 0.4.81 → 0.4.83

package/src/managed-router.ts

@@ -2,10 +2,53 @@
  * 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)
+ * 1. Deactivates and unmounts the previous module (either persisting it for
+ *    later reuse or destroying it).
+ * 2. Mounts the new module (creating it fresh or restoring from cache) and
+ *    activates it.
  *
  * Module names are used as state prefixes (lowercased) for isolation.
+ *
+ * ## Persistence (default: on for module-backed routes)
+ *
+ * By default, any route whose `component` resolves to a registered module
+ * definition (or provides one inline via `route.module`) has its module
+ * instance **persisted** across navigations. This preserves module state
+ * (e.g. fetched data, form inputs, scroll position in state) so that
+ * navigating away and back doesn't re-trigger the initial "loading" state
+ * that usually lives in `onCreated`.
+ *
+ * Opt out by setting `persist: false` on the module definition. Routes
+ * without a module definition are unchanged — they have nothing to persist.
+ *
+ * ## Persistence cache bound (LRU)
+ *
+ * The persisted-module cache is an insertion-ordered LRU with a default
+ * cap of `DEFAULT_MAX_PERSISTED_MODULES` (= 10). Persisting a module
+ * past the cap evicts the least-recently-persisted entry and tears it
+ * down via `instance.destroy()` + `unregisterModule()` — the same path a
+ * `persist: false` module takes on unmount. Restoring from the cache
+ * counts as a touch (the entry is removed on mount and re-inserted on
+ * next unmount, placing it at the MRU end).
+ *
+ * The cap matches the engine's `DEFAULT_ROUTER_CACHE_SIZE` for the
+ * Router IR subtree cache, so SDK-level module retention and
+ * engine-level DOM-subtree retention stay in lockstep by default.
+ * Override via the `maxPersistedModules` constructor option. Pass
+ * `Infinity` to disable eviction (only advisable for bounded route
+ * sets — otherwise a long session will leak).
+ *
+ * ## Lifecycle on navigation
+ *
+ * First visit to a route:
+ *   `construct → onCreated → onActivated`
+ * Navigate away:
+ *   `onDeactivated` (then either persist in cache OR `onDestroyed`)
+ * Revisit (persisted):
+ *   `onActivated` (only — `onCreated` does not re-run)
+ *
+ * Use `onActivated` for per-navigation side effects like refreshing data;
+ * use `onCreated` for one-time module setup.
  */
 
 import type { IEngine, HypenModuleDefinition } from "./app.js";
@@ -16,6 +59,13 @@ import { createLogger } from "./logger.js";
 
 const log = createLogger("ManagedRouter");
 
+/**
+ * Default upper bound on `persistedModules`. Mirrors
+ * `DEFAULT_ROUTER_CACHE_SIZE` in the engine's Router IR node so the SDK
+ * module cache and the engine subtree cache evict in lockstep.
+ */
+export const DEFAULT_MAX_PERSISTED_MODULES = 10;
+
 export interface RouteDefinition {
   /** Route path pattern (e.g., "/", "/profile/:id") */
   path: string;
@@ -25,6 +75,17 @@ export interface RouteDefinition {
   module?: HypenModuleDefinition;
 }
 
+export interface ManagedRouterOptions {
+  /**
+   * Maximum number of persisted module instances retained across
+   * navigations. When persistence would push the cache past this cap,
+   * the least-recently-persisted entry is destroyed. Defaults to
+   * `DEFAULT_MAX_PERSISTED_MODULES`. Pass `Infinity` to disable
+   * eviction.
+   */
+  maxPersistedModules?: number;
+}
+
 export class ManagedRouter {
   private router: HypenRouter;
   private engine: IEngine;
@@ -34,19 +95,46 @@ export class ManagedRouter {
   private activeModule: HypenModuleInstance | null = null;
   private activeRoute: RouteDefinition | null = null;
   private unsubscribe: (() => void) | null = null;
-  /** Cached instances for modules with persist=true */
+  /**
+   * Cached instances for module-backed routes, keyed by the lowercase
+   * module id. Entries are populated on unmount (when `persist` is truthy)
+   * and consulted on mount to restore state across navigations.
+   *
+   * Persistence is the default for any route whose `component` or `module`
+   * resolves to a module definition; opt out by setting `persist: false`
+   * on the definition.
+   *
+   * Bounded by `maxPersistedModules`. Map insertion order drives LRU
+   * eviction: restoring from the cache removes the entry (so the next
+   * persist re-inserts it at the MRU end), and persisting past the cap
+   * destroys the oldest entry.
+   */
   private persistedModules = new Map<string, HypenModuleInstance>();
+  private readonly maxPersistedModules: number;
+  /**
+   * Serialized chain of in-flight route transitions. Because mount /
+   * unmount are now async (they await `onActivated` / `onDeactivated`),
+   * back-to-back navigations must not interleave. Each `handleRouteChange`
+   * appends to this chain so transitions run strictly in order.
+   */
+  private navPromise: Promise<void> = Promise.resolve();
 
   constructor(
     router: HypenRouter,
     engine: IEngine,
     registry: HypenApp,
-    globalContext: HypenGlobalContext
+    globalContext: HypenGlobalContext,
+    options: ManagedRouterOptions = {}
   ) {
     this.router = router;
     this.engine = engine;
     this.registry = registry;
     this.globalContext = globalContext;
+    const cap = options.maxPersistedModules ?? DEFAULT_MAX_PERSISTED_MODULES;
+    // Guard against obviously-invalid caps — a zero or negative limit would
+    // mean "never persist", which the call site should express via
+    // `persist: false` on definitions instead.
+    this.maxPersistedModules = cap > 0 ? cap : DEFAULT_MAX_PERSISTED_MODULES;
   }
 
   /**
@@ -59,36 +147,109 @@ export class ManagedRouter {
 
   /**
    * Start listening for route changes and mount the initial route.
+   *
+   * Also installs the `@router.*` engine action handlers so DSL authors can
+   * write `.onClick(@router.push, to: "/x")` / `@router.back` /
+   * `@router.replace` / `@router.forward` and have them dispatched against
+   * this session's `HypenRouter` without any per-example wiring. The
+   * reserved namespace is set up by `hypen-engine` in `ir/expand.rs`.
    */
   start(): void {
     this.unsubscribe = this.router.onNavigate((routeState: RouteState) => {
       this.handleRouteChange(routeState);
     });
+    this.installRouterActions();
+  }
+
+  /**
+   * Register handlers for the reserved `router.*` action namespace.
+   *
+   * All navigations go through `queueMicrotask` so the router state mutation
+   * lands after the engine finishes dispatching the action — synchronous
+   * writes would re-enter the engine's WASM state proxy, which the Rust side
+   * rejects ("recursive use of an object").
+   */
+  private installRouterActions(): void {
+    const router = this.router;
+    const defer = (fn: () => void) => queueMicrotask(fn);
+    const readTo = (action: { payload?: unknown } | null | undefined): string | null => {
+      const payload = action?.payload as Record<string, unknown> | null | undefined;
+      const to = payload?.to;
+      return typeof to === "string" && to.length > 0 ? to : null;
+    };
+
+    this.engine.onAction("router.push", (action) => {
+      const to = readTo(action);
+      if (to) defer(() => router.push(to));
+    });
+    this.engine.onAction("router.replace", (action) => {
+      const to = readTo(action);
+      if (to) defer(() => router.replace(to));
+    });
+    this.engine.onAction("router.back", () => {
+      defer(() => router.back());
+    });
+    this.engine.onAction("router.forward", () => {
+      defer(() => router.forward());
+    });
   }
 
   /**
    * Stop listening and unmount the active module.
    * Also destroys all persisted modules.
+   *
+   * Waits for any in-flight navigation to settle before tearing down so
+   * lifecycle hooks always complete in order.
    */
-  stop(): void {
+  async stop(): Promise<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();
+    // Wait for any in-flight navigation before tearing down.
+    const cleanup = this.navPromise
+      .catch(() => {
+        /* previous navigation errors already reported */
+      })
+      .then(async () => {
+        await this.unmountActive();
+
+        // Destroy all persisted modules on full stop. Instances in this
+        // map are inactive (they were deactivated when persisted), so
+        // `destroy()` just fires `onDestroyed`.
+        for (const [moduleId, instance] of this.persistedModules) {
+          log.debug(`Destroying persisted module on stop: ${moduleId}`);
+          try {
+            await instance.destroy();
+          } catch (e) {
+            log.error(`Error destroying persisted module ${moduleId}:`, e);
+          }
+          this.globalContext.unregisterModule(moduleId);
+        }
+        this.persistedModules.clear();
+      });
+
+    this.navPromise = cleanup;
+    await cleanup;
 
     // Clean up router event listeners
     this.router.dispose();
   }
 
+  /**
+   * Returns a promise that resolves once all currently-queued route
+   * transitions have finished. Useful in tests to await lifecycle
+   * ordering without reaching into internals.
+   */
+  async waitForNavigation(): Promise<void> {
+    try {
+      await this.navPromise;
+    } catch {
+      /* navigation errors are logged; callers don't need to rethrow */
+    }
+  }
+
   /**
    * Get the currently active module instance.
    */
@@ -104,23 +265,35 @@ export class ManagedRouter {
   }
 
   private handleRouteChange(routeState: RouteState): void {
+    // Chain onto the in-flight navigation promise so transitions run
+    // strictly in order. Async activate/deactivate hooks otherwise make
+    // it possible for a late `A → B` to finish before an earlier `B → A`.
+    this.navPromise = this.navPromise
+      .catch((e) => {
+        log.error("Previous navigation failed:", e);
+      })
+      .then(() => this.processRouteChange(routeState));
+  }
+
+  private async processRouteChange(routeState: RouteState): Promise<void> {
     const path = routeState.currentPath;
     const matched = this.matchRoute(path);
 
     if (!matched) {
       log.debug(`No route matched for path: ${path}`);
-      this.unmountActive();
+      await this.unmountActive();
       return;
     }
 
-    // If same route, no need to remount
+    // If same route, no need to remount. Still a no-op for same-path
+    // navigations (e.g. reselecting the active tab).
     if (this.activeRoute && this.activeRoute.path === matched.path) {
       return;
     }
 
-    // Unmount old, mount new
-    this.unmountActive();
-    this.mount(matched);
+    // Unmount old, mount new.
+    await this.unmountActive();
+    await this.mount(matched);
   }
 
   private matchRoute(path: string): RouteDefinition | null {
@@ -132,7 +305,7 @@ export class ManagedRouter {
     return null;
   }
 
-  private mount(route: RouteDefinition): void {
+  private async mount(route: RouteDefinition): Promise<void> {
     // Look up module definition: inline first, then registry
     const definition = route.module || this.registry.get(route.component);
     if (!definition) {
@@ -149,12 +322,19 @@ export class ManagedRouter {
 
     const moduleId = namedDef.name!.toLowerCase();
 
-    // Check for a persisted instance first
+    // Check for a persisted instance first. If we hit the cache, we reuse
+    // its state verbatim — `onCreated` has already fired (once) and
+    // activate() below will fire `onActivated` without re-running the
+    // one-time setup.
     const persisted = this.persistedModules.get(moduleId);
     if (persisted) {
       log.debug(`Restoring persisted module: ${moduleId} for route: ${route.path}`);
       this.activeModule = persisted;
       this.activeRoute = route;
+      // Remove from the cache while it's active so that a concurrent
+      // navigation can't double-mount the same instance.
+      this.persistedModules.delete(moduleId);
+      await persisted.activate();
       return;
     }
 
@@ -172,26 +352,96 @@ export class ManagedRouter {
 
     this.activeModule = instance;
     this.activeRoute = route;
+
+    // Fire `onActivated` after `onCreated` resolves. `activate()` awaits
+    // the instance's internal readiness promise, so this is safe even
+    // though the constructor kicks off `onCreated` asynchronously.
+    await instance.activate();
   }
 
-  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);
-      }
+  private async unmountActive(): Promise<void> {
+    if (!this.activeModule || !this.activeRoute) {
+      this.activeModule = null;
+      this.activeRoute = null;
+      return;
     }
 
+    const active = this.activeModule;
+    const route = this.activeRoute;
+    const definition = route.module || this.registry.get(route.component);
+    const moduleId = (definition?.name || route.component).toLowerCase();
+
+    // Persistence default: any route backed by a module definition
+    // persists unless the definition explicitly opts out.
+    //
+    //   definition present & persist !== false  →  cache the instance
+    //   definition present & persist === false  →  destroy the instance
+    //   definition missing                       →  nothing to persist
+    //
+    // This is the new default behavior — prior to this change, persist
+    // was opt-in via `persist: true`. Modules that relied on a fresh
+    // instance on every navigation should set `persist: false` or move
+    // per-navigation work into the new `onActivated` hook.
+    const persist = definition != null && definition.persist !== false;
+
+    // Clear the active slot *before* firing lifecycle hooks so the
+    // module cannot observe itself as "active" from inside onDeactivated.
     this.activeModule = null;
     this.activeRoute = null;
+
+    // Always deactivate first — regardless of whether we persist or
+    // destroy — so `onDeactivated → (onDestroyed)` ordering holds.
+    try {
+      await active.deactivate();
+    } catch (e) {
+      log.error(`Error deactivating module ${moduleId}:`, e);
+    }
+
+    if (persist) {
+      log.debug(`Persisting module: ${moduleId}`);
+      // If this id is already cached (e.g. after being destroyed and
+      // re-activated without passing through mount(), though rare),
+      // delete first so the re-insert places it at the MRU end.
+      this.persistedModules.delete(moduleId);
+      this.persistedModules.set(moduleId, active);
+      await this.evictPersistedOverflow();
+      // Keep registered in GlobalContext so other modules can still
+      // access its state while it's off-screen.
+    } else {
+      log.debug(`Unmounting module: ${moduleId}`);
+      try {
+        await active.destroy();
+      } catch (e) {
+        log.error(`Error destroying module ${moduleId}:`, e);
+      }
+      this.globalContext.unregisterModule(moduleId);
+    }
+  }
+
+  /**
+   * Trim `persistedModules` down to `maxPersistedModules` by destroying
+   * the oldest entries (FIFO in Map insertion order, which tracks LRU
+   * because `mount()` removes on restore and `unmountActive()` re-inserts
+   * at the MRU end on every persist).
+   *
+   * Errors during eviction are logged — one misbehaving `onDestroyed` hook
+   * must not block the router from shrinking the cache on the next
+   * navigation.
+   */
+  private async evictPersistedOverflow(): Promise<void> {
+    while (this.persistedModules.size > this.maxPersistedModules) {
+      const oldest = this.persistedModules.keys().next();
+      if (oldest.done) break;
+      const oldestId = oldest.value;
+      const evicted = this.persistedModules.get(oldestId)!;
+      this.persistedModules.delete(oldestId);
+      log.debug(`Evicting persisted module (LRU): ${oldestId}`);
+      try {
+        await evicted.destroy();
+      } catch (e) {
+        log.error(`Error destroying evicted module ${oldestId}:`, e);
+      }
+      this.globalContext.unregisterModule(oldestId);
+    }
   }
 }

package/src/portable.ts

@@ -0,0 +1,113 @@
+/**
+ * Portable helper DI seam for `@hypen-space/core`.
+ *
+ * `@hypen-space/core` is WASM-free: it ships to contexts (tree-shakers,
+ * browser remote-client bundles) that must not pull in the 2 MB engine
+ * binary. But every Hypen runtime — Node via `@hypen-space/server`,
+ * browser SPA via `@hypen-space/web-engine`, tests via the bun preload
+ * — composes core with a host that HAS loaded the engine. Those
+ * packages call [`setPortableImpl`] at their init time, plugging the
+ * canonical Rust-engine impls (`hypen-engine-rs/src/portable/`) into
+ * core.
+ *
+ * There is no TypeScript fallback. A core instance whose portable
+ * helpers are called before `setPortableImpl` has run throws a clear
+ * error pointing at the fix. Reasons:
+ *
+ * * Any fallback is a second implementation to maintain, exactly the
+ *   drift tax this whole refactor eliminated for the other four SDKs.
+ * * Core's own consumers of the portable helpers (`HypenRouter.matchPath`,
+ *   `createObservableState`'s `notifyChange`) are never reached in
+ *   remote-client-only browser bundles — those bundles drive UI purely
+ *   from server-pushed patches.
+ * * Callers who DO reach the helpers (server, web-engine, tests) always
+ *   have an engine available.
+ */
+
+import type { StateChange, StatePath } from "./state";
+
+export interface PortableImpl {
+  diffState(oldState: any, newState: any, basePath?: string): StateChange;
+  matchPath(
+    pattern: string,
+    path: string,
+  ): { params: Record<string, string> } | null;
+  pathGet(value: any, path: string): unknown;
+  pathHas(value: any, path: string): boolean;
+  pathSet(value: any, path: string, newValue: any): any;
+  pathDelete(value: any, path: string): { value: any; removed: boolean };
+  encodeUriComponent(input: string): string;
+  decodeUriComponent(input: string): string;
+  parseQuery(fullPath: string): { path: string; query: Record<string, string> };
+  buildUrl(path: string, query: Record<string, string>): string;
+}
+
+function notInstalled(name: string): never {
+  throw new Error(
+    `[@hypen-space/core] Portable helper "${name}" called before the engine was installed. ` +
+      `Import @hypen-space/server, @hypen-space/web-engine, or call setPortableImpl() before use.`,
+  );
+}
+
+let current: PortableImpl = {
+  diffState: () => notInstalled("diffState"),
+  matchPath: () => notInstalled("matchPath"),
+  pathGet: () => notInstalled("pathGet"),
+  pathHas: () => notInstalled("pathHas"),
+  pathSet: () => notInstalled("pathSet"),
+  pathDelete: () => notInstalled("pathDelete"),
+  encodeUriComponent: () => notInstalled("encodeUriComponent"),
+  decodeUriComponent: () => notInstalled("decodeUriComponent"),
+  parseQuery: () => notInstalled("parseQuery"),
+  buildUrl: () => notInstalled("buildUrl"),
+};
+
+/**
+ * Install the engine-backed [`PortableImpl`]. Called once by
+ * `@hypen-space/server` at import time (synchronous wasm-node load) or
+ * by `@hypen-space/web-engine` inside `Engine.init()` once the browser
+ * wasm module resolves.
+ *
+ * Passing `null` resets to the "not installed" throwing default — used
+ * by test teardown when you want to verify the no-engine error path.
+ */
+export function setPortableImpl(impl: PortableImpl | null): void {
+  if (impl === null) {
+    current = {
+      diffState: () => notInstalled("diffState"),
+      matchPath: () => notInstalled("matchPath"),
+      pathGet: () => notInstalled("pathGet"),
+      pathHas: () => notInstalled("pathHas"),
+      pathSet: () => notInstalled("pathSet"),
+      pathDelete: () => notInstalled("pathDelete"),
+      encodeUriComponent: () => notInstalled("encodeUriComponent"),
+      decodeUriComponent: () => notInstalled("decodeUriComponent"),
+      parseQuery: () => notInstalled("parseQuery"),
+      buildUrl: () => notInstalled("buildUrl"),
+    };
+    return;
+  }
+  current = impl;
+}
+
+/**
+ * Live portable API. Every call dispatches to whatever
+ * [`setPortableImpl`] most recently installed.
+ */
+export const portable: PortableImpl = {
+  diffState: (o, n, b) => current.diffState(o, n, b),
+  matchPath: (p, path) => current.matchPath(p, path),
+  pathGet: (v, p) => current.pathGet(v, p),
+  pathHas: (v, p) => current.pathHas(v, p),
+  pathSet: (v, p, nv) => current.pathSet(v, p, nv),
+  pathDelete: (v, p) => current.pathDelete(v, p),
+  encodeUriComponent: (s) => current.encodeUriComponent(s),
+  decodeUriComponent: (s) => current.decodeUriComponent(s),
+  parseQuery: (f) => current.parseQuery(f),
+  buildUrl: (p, q) => current.buildUrl(p, q),
+};
+
+// `StatePath` is still part of this module's public surface via
+// re-export; keeping it reachable from `@hypen-space/core/portable`
+// simplifies bindings in server / web-engine adapters.
+export type { StatePath } from "./state";

package/src/router.ts

@@ -6,6 +6,7 @@
 import { createObservableState, getStateSnapshot } from "./state.js";
 import { disposableListener, type Disposable } from "./disposable.js";
 import { frameworkLoggers } from "./logger.js";
+import { portable } from "./portable.js";
 
 const log = frameworkLoggers.router;
 
@@ -232,61 +233,35 @@ export class HypenRouter {
   }
 
   /**
-   * Match a pattern against a path
+   * Match a pattern against a path.
+   *
+   * Thin wrapper over [`portable.matchPath`] — the three-case matcher
+   * (exact / `/prefix/*` wildcard / `:param`) lives in the Rust engine
+   * at `hypen-engine-rs/src/portable/route.rs` and is reached through
+   * the WASM installed by server / web-engine, with a TS fallback for
+   * standalone core use.
    */
   matchPath(pattern: string, path: string): RouteMatch | null {
-    // Handle invalid inputs gracefully
-    if (!pattern || typeof pattern !== 'string') {
-      return null;
-    }
-    if (!path || typeof path !== 'string') {
-      return null;
-    }
-
-    // Exact match
-    if (pattern === path) {
-      return {
-        params: {},
-        query: this.state.query,
-        path,
-      };
-    }
-
-    // Wildcard match: /dashboard/* matches /dashboard/anything
-    if (pattern.endsWith("/*")) {
-      const prefix = pattern.slice(0, -2);
-      if (path === prefix || path.startsWith(prefix + "/")) {
-        return {
-          params: {},
-          query: this.state.query,
-          path,
-        };
-      }
-      return null;
-    }
+    if (!pattern || typeof pattern !== "string") return null;
+    if (!path || typeof path !== "string") return null;
+
+    // Strip any query portion before matching; the engine matcher
+    // operates on the clean path and we track `query` ourselves.
+    // `noUncheckedIndexedAccess` makes `[0]` `string | undefined`; fall
+    // back to the full path when split yields an empty array (which
+    // only happens for empty input — already ruled out above).
+    const cleanPath = path.split("?")[0] ?? path;
+    const result = portable.matchPath(pattern, cleanPath);
+    if (!result) return null;
 
-    // Parameter match: /users/:id matches /users/123
-    const paramNames: string[] = [];
-    const regexPattern = pattern
-      .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, name) => {
-        paramNames.push(name);
-        return "([^/]+)";
-      })
-      .replace(/\*/g, ".*");
-
-    const regex = new RegExp(`^${regexPattern}$`);
-    const match = path.match(regex);
-
-    if (!match) return null;
-
-    // Extract params
     const params: Record<string, string> = {};
-    paramNames.forEach((name, i) => {
-      const value = match[i + 1];
-      if (value !== undefined) {
-        params[name] = decodeURIComponent(value);
+    for (const [name, raw] of Object.entries(result.params)) {
+      try {
+        params[name] = decodeURIComponent(raw);
+      } catch {
+        params[name] = raw;
       }
-    });
+    }
 
     return {
       params,