@hypen-space/core 0.4.82 → 0.4.83

package/dist/managed-router.d.ts

@@ -2,15 +2,64 @@
  * 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";
 import { HypenModuleInstance, HypenApp } from "./app.js";
 import type { HypenRouter } from "./router.js";
 import type { HypenGlobalContext } from "./context.js";
+/**
+ * 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 declare const DEFAULT_MAX_PERSISTED_MODULES = 10;
 export interface RouteDefinition {
     /** Route path pattern (e.g., "/", "/profile/:id") */
     path: string;
@@ -19,6 +68,16 @@ export interface RouteDefinition {
     /** Inline module definition (alternative to registry lookup) */
     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 declare class ManagedRouter {
     private router;
     private engine;
@@ -28,22 +87,67 @@ export declare class ManagedRouter {
     private activeModule;
     private activeRoute;
     private unsubscribe;
-    /** 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;
-    constructor(router: HypenRouter, engine: IEngine, registry: HypenApp, globalContext: HypenGlobalContext);
+    private readonly maxPersistedModules;
+    /**
+     * 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;
+    constructor(router: HypenRouter, engine: IEngine, registry: HypenApp, globalContext: HypenGlobalContext, options?: ManagedRouterOptions);
     /**
      * Add a route definition.
      */
     addRoute(route: RouteDefinition): this;
     /**
      * 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;
+    /**
+     * 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;
     /**
      * 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(): Promise<void>;
+    /**
+     * Returns a promise that resolves once all currently-queued route
+     * transitions have finished. Useful in tests to await lifecycle
+     * ordering without reaching into internals.
      */
-    stop(): void;
+    waitForNavigation(): Promise<void>;
     /**
      * Get the currently active module instance.
      */
@@ -53,7 +157,19 @@ export declare class ManagedRouter {
      */
     getActiveRoute(): RouteDefinition | null;
     private handleRouteChange;
+    private processRouteChange;
     private matchRoute;
     private mount;
     private unmountActive;
+    /**
+     * 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 evictPersistedOverflow;
 }

package/dist/portable.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 } 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;
+}
+/**
+ * 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 declare function setPortableImpl(impl: PortableImpl | null): void;
+/**
+ * Live portable API. Every call dispatches to whatever
+ * [`setPortableImpl`] most recently installed.
+ */
+export declare const portable: PortableImpl;
+export type { StatePath } from "./state";

package/dist/router.d.ts

@@ -73,7 +73,13 @@ export declare class HypenRouter {
      */
     getState(): RouteState;
     /**
-     * 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;
     /**

package/dist/router.js

@@ -21,6 +21,53 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/portable.ts
+function notInstalled(name) {
+  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.`);
+}
+var 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")
+};
+function setPortableImpl(impl) {
+  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;
+}
+var portable = {
+  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)
+};
+
 // src/state.ts
 var IS_PROXY = Symbol.for("hypen.isProxy");
 var RAW_TARGET = Symbol.for("hypen.rawTarget");
@@ -80,51 +127,7 @@ function deepClone(obj) {
   return cloneInternal(obj);
 }
 function diffState(oldState, newState, basePath = "") {
-  const paths = [];
-  const newValues = {};
-  function diff(oldVal, newVal, path) {
-    if (oldVal === newVal)
-      return;
-    if (typeof oldVal !== "object" || typeof newVal !== "object" || oldVal === null || newVal === null) {
-      if (oldVal !== newVal) {
-        paths.push(path);
-        newValues[path] = newVal;
-      }
-      return;
-    }
-    if (Array.isArray(oldVal) || Array.isArray(newVal)) {
-      if (!Array.isArray(oldVal) || !Array.isArray(newVal) || oldVal.length !== newVal.length) {
-        paths.push(path);
-        newValues[path] = newVal;
-        return;
-      }
-      for (let i = 0;i < newVal.length; i++) {
-        const itemPath = path ? `${path}.${i}` : `${i}`;
-        diff(oldVal[i], newVal[i], itemPath);
-      }
-      return;
-    }
-    const oldKeys = new Set(Object.keys(oldVal));
-    const newKeys = new Set(Object.keys(newVal));
-    for (const key of newKeys) {
-      const propPath = path ? `${path}.${key}` : key;
-      if (!oldKeys.has(key)) {
-        paths.push(propPath);
-        newValues[propPath] = newVal[key];
-      } else {
-        diff(oldVal[key], newVal[key], propPath);
-      }
-    }
-    for (const key of oldKeys) {
-      if (!newKeys.has(key)) {
-        const propPath = path ? `${path}.${key}` : key;
-        paths.push(propPath);
-        newValues[propPath] = undefined;
-      }
-    }
-  }
-  diff(oldState, newState, basePath);
-  return { paths, newValues };
+  return portable.diffState(oldState, newState, basePath);
 }
 function createObservableState(initialState, options) {
   const opts = options || { onChange: () => {} };
@@ -735,46 +738,22 @@ class HypenRouter {
     return getStateSnapshot(this.state);
   }
   matchPath(pattern, path) {
-    if (!pattern || typeof pattern !== "string") {
+    if (!pattern || typeof pattern !== "string")
       return null;
-    }
-    if (!path || typeof path !== "string") {
+    if (!path || typeof path !== "string")
       return null;
-    }
-    if (pattern === path) {
-      return {
-        params: {},
-        query: this.state.query,
-        path
-      };
-    }
-    if (pattern.endsWith("/*")) {
-      const prefix = pattern.slice(0, -2);
-      if (path === prefix || path.startsWith(prefix + "/")) {
-        return {
-          params: {},
-          query: this.state.query,
-          path
-        };
-      }
-      return null;
-    }
-    const paramNames = [];
-    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)
+    const cleanPath = path.split("?")[0] ?? path;
+    const result = portable.matchPath(pattern, cleanPath);
+    if (!result)
       return null;
     const params = {};
-    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,
       query: this.state.query,
@@ -829,4 +808,4 @@ export {
   HypenRouter
 };
 
-//# debugId=7C245540775DFDF064756E2164756E21
+//# debugId=8162B923E6ED164564756E2164756E21