@hypen-space/core 0.4.81 → 0.4.83

package/src/app.ts

@@ -140,7 +140,7 @@ export interface ErrorContext<T> {
   /** The action name if error occurred in an action handler */
   actionName?: string;
   /** The lifecycle phase if error occurred in a lifecycle handler */
-  lifecycle?: "created" | "destroyed" | "disconnect" | "reconnect" | "expire";
+  lifecycle?: "created" | "activated" | "deactivated" | "destroyed" | "disconnect" | "reconnect" | "expire";
 }
 
 /**
@@ -181,6 +181,20 @@ export interface HypenModuleDefinition<T = unknown> {
   stateStore?: StateStore<T>;
   handlers: {
     onCreated?: LifecycleHandler<T>;
+    /**
+     * Called every time the module becomes the active route target.
+     * Runs after `onCreated` on first mount, and again on each re-mount
+     * from the ManagedRouter's persistence cache. Use for data refresh,
+     * subscription (re)connects, or any "screen became visible" work.
+     */
+    onActivated?: LifecycleHandler<T>;
+    /**
+     * Called every time the module stops being the active route target.
+     * Runs before the module is cached for persistence OR before
+     * `onDestroyed` if the module is being torn down. Use for pausing
+     * timers, tearing down ephemeral subscriptions, etc.
+     */
+    onDeactivated?: LifecycleHandler<T>;
     onAction: Map<string, ActionHandler<T, any>>;
     onDestroyed?: LifecycleHandler<T>;
     /** Called when client disconnects (session persists for TTL) */
@@ -206,6 +220,8 @@ export class HypenAppBuilder<T> {
   private initialState: T;
   private options: { persist?: boolean; version?: number; name?: string };
   private createdHandler?: LifecycleHandler<T>;
+  private activatedHandler?: LifecycleHandler<T>;
+  private deactivatedHandler?: LifecycleHandler<T>;
   private actionHandlers: Map<string, ActionHandler<T, any>> = new Map();
   private destroyedHandler?: LifecycleHandler<T>;
   private disconnectHandler?: DisconnectHandler<T>;
@@ -257,6 +273,47 @@ export class HypenAppBuilder<T> {
     return this;
   }
 
+  /**
+   * Register a handler that runs every time the module becomes the active
+   * route target.
+   *
+   * Unlike `onCreated`, which only runs once per module instance, `onActivated`
+   * runs on **every** mount — the first one (right after `onCreated`) and
+   * every subsequent re-entry when a cached module is restored by
+   * `ManagedRouter`. Use this hook for data refresh, (re)connecting
+   * subscriptions, starting timers, and any "screen became visible" work
+   * that should happen on every navigation to this route.
+   *
+   * @example
+   * ```typescript
+   * app
+   *   .defineState({ items: [], loading: false })
+   *   .onActivated(async (state) => {
+   *     state.loading = true;
+   *     state.items = await fetchItems();
+   *     state.loading = false;
+   *   });
+   * ```
+   */
+  onActivated(fn: LifecycleHandler<T>): this {
+    this.activatedHandler = fn;
+    return this;
+  }
+
+  /**
+   * Register a handler that runs every time the module stops being the
+   * active route target.
+   *
+   * Runs before the module is cached for persistence (when the user
+   * navigates to another route) OR before `onDestroyed` if the module is
+   * being torn down. Use this for pausing timers, unsubscribing from
+   * ephemeral streams, and any "screen became hidden" cleanup.
+   */
+  onDeactivated(fn: LifecycleHandler<T>): this {
+    this.deactivatedHandler = fn;
+    return this;
+  }
+
   /**
    * Register a handler for module destruction
    */
@@ -453,6 +510,8 @@ export class HypenAppBuilder<T> {
       stateStore: this._stateStore,
       handlers: {
         onCreated: this.createdHandler,
+        onActivated: this.activatedHandler,
+        onDeactivated: this.deactivatedHandler,
         onAction: this.actionHandlers,
         onDestroyed: this.destroyedHandler,
         onDisconnect: this.disconnectHandler,
@@ -582,6 +641,13 @@ export class HypenModuleInstance<T extends object = any> {
   private definition: HypenModuleDefinition<T>;
   private state: T;
   private isDestroyed = false;
+  /**
+   * True when the module is currently the active route target (i.e.
+   * `onActivated` has fired more recently than `onDeactivated`).
+   * Used to make `activate()` / `deactivate()` idempotent so the
+   * `ManagedRouter` can call them safely regardless of state.
+   */
+  private isActive = false;
   private router: HypenRouter | null;
   private globalContext?: HypenGlobalContext;
   private stateChangeCallbacks: Array<() => void> = [];
@@ -718,6 +784,63 @@ export class HypenModuleInstance<T extends object = any> {
     await this._readyPromise;
   }
 
+  /**
+   * Mark the module as the active route target and fire `onActivated`.
+   *
+   * Idempotent: calling `activate()` on an already-active module is a
+   * no-op. Internally awaits `waitForReady()` so that `onCreated` always
+   * runs to completion before `onActivated` fires, regardless of who
+   * calls this method and when.
+   *
+   * Called by `ManagedRouter` on every route mount — both fresh
+   * constructions and re-mounts from the persistence cache.
+   */
+  async activate(): Promise<void> {
+    if (this.isDestroyed || this.isActive) return;
+    // Ensure onCreated finishes before onActivated — critical on fresh
+    // mounts where the constructor kicks off onCreated asynchronously.
+    await this._readyPromise;
+    if (this.isDestroyed || this.isActive) return;
+    this.isActive = true;
+    if (this.definition.handlers.onActivated) {
+      const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
+      try {
+        await this.definition.handlers.onActivated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onActivated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "activated" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
+    }
+  }
+
+  /**
+   * Mark the module as no longer the active route target and fire
+   * `onDeactivated`.
+   *
+   * Idempotent: calling `deactivate()` on an inactive module is a no-op.
+   * Called by `ManagedRouter` before persisting a module for later reuse
+   * OR before destroying it.
+   */
+  async deactivate(): Promise<void> {
+    if (this.isDestroyed || !this.isActive) return;
+    this.isActive = false;
+    if (this.definition.handlers.onDeactivated) {
+      const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
+      try {
+        await this.definition.handlers.onDeactivated(this.state, context);
+      } catch (e) {
+        const error = e instanceof HypenError ? e : new ActionError("onDeactivated", e);
+        const shouldRethrow = await this.handleError(error, { lifecycle: "deactivated" });
+        if (shouldRethrow) {
+          throw error;
+        }
+      }
+    }
+  }
+
   /**
    * Create the global context API for this module
    */
@@ -963,6 +1086,13 @@ export class HypenModuleInstance<T extends object = any> {
   async destroy(): Promise<void> {
     if (this.isDestroyed) return;
 
+    // If this module is still marked as active (e.g. destroy() was called
+    // without a preceding deactivate()), fire onDeactivated first so the
+    // lifecycle order is always: ...onActivated → onDeactivated → onDestroyed.
+    if (this.isActive) {
+      await this.deactivate();
+    }
+
     // Flush any pending persistence writes before shutdown
     if (this.currentPersistKey && this.stateStore) {
       clearTimeout(this.persistDebounceTimer);

package/src/engine-base.ts

@@ -227,6 +227,61 @@ export abstract class BaseEngine {
     return action;
   }
 
+  /**
+   * Parse a Hypen DSL source and return every `Router { Route ... }`
+   * block found in it. The SDK uses this to auto-wire a ManagedRouter
+   * against the template without the user having to repeat the route
+   * table in code.
+   *
+   * `moduleScope` is the enclosing `module X { ... }` scope (lowercased)
+   * — `null` for the document root. `elementNames` is BFS-ordered so
+   * the SDK can pick the first name that matches a registered
+   * `HypenApp` module (wrappers like Column / Row come before the
+   * real route component).
+   */
+  discoverRouters(source: string): Array<{
+    moduleScope: string | null;
+    routes: Array<{ path: string; elementNames: string[] }>;
+  }> {
+    const engine = this.ensureInitialized();
+    const raw = (engine as any).discoverRouters?.(source);
+    if (!raw) return [];
+    // wasm-bindgen returns Maps; normalize to plain objects for
+    // ergonomic downstream consumption. The nested structures were
+    // encoded with serde_wasm_bindgen so plain objects is the right
+    // post-decode shape for most consumers.
+    const mapToObj = (v: unknown): any => {
+      if (v instanceof Map) {
+        const obj: Record<string, unknown> = {};
+        for (const [k, val] of v.entries()) obj[String(k)] = mapToObj(val);
+        return obj;
+      }
+      if (Array.isArray(v)) return v.map(mapToObj);
+      if (v && typeof v === "object") {
+        const obj: Record<string, unknown> = {};
+        for (const [k, val] of Object.entries(v)) obj[k] = mapToObj(val);
+        return obj;
+      }
+      return v;
+    };
+    const normalized = mapToObj(raw) as Array<{
+      module_scope: string | null;
+      moduleScope?: string | null;
+      routes: Array<{
+        path: string;
+        element_names?: string[];
+        elementNames?: string[];
+      }>;
+    }>;
+    return normalized.map((r) => ({
+      moduleScope: r.moduleScope ?? r.module_scope ?? null,
+      routes: r.routes.map((route) => ({
+        path: route.path,
+        elementNames: route.elementNames ?? route.element_names ?? [],
+      })),
+    }));
+  }
+
   /**
    * Initialize the primary module.
    */

package/src/index.ts

@@ -132,6 +132,13 @@ export type {
   StateObserverOptions,
 } from "./state.js";
 
+// Portable DI seam: `@hypen-space/server` and `@hypen-space/web-engine`
+// call `setPortableImpl` at their module-init time to route core's
+// diff / matchPath / path-ops / URL helpers through the Rust engine's
+// canonical implementations. Standalone core use gets TS fallbacks.
+export { setPortableImpl, portable } from "./portable.js";
+export type { PortableImpl } from "./portable.js";
+
 // ============================================================================
 // RENDERER ABSTRACTION
 // ============================================================================
@@ -150,6 +157,12 @@ export type {
   RouteChangeCallback,
 } from "./router.js";
 
+// Route-based module lifecycle orchestrator. Wraps HypenRouter and
+// mounts/unmounts modules as the route changes, with optional per-module
+// persistence to avoid tearing down state on every navigation.
+export { ManagedRouter } from "./managed-router.js";
+export type { RouteDefinition } from "./managed-router.js";
+
 // ============================================================================
 // EVENTS
 // ============================================================================