@hypen-space/core 0.4.46 → 0.4.81

package/dist/hypen.d.ts

@@ -3,7 +3,7 @@
  *
  * Enables single-file components with inline UI templates.
  *
- * The `hypen` tagged template preserves ${state.x} and ${item.x} bindings
+ * The `hypen` tagged template preserves @{state.x} and @{item.x} bindings
  * instead of interpolating them, allowing you to write:
  *
  * @example
@@ -17,7 +17,7 @@
  *   })
  *   .ui(hypen`
  *     Column {
- *       Text("Count: ${state.count}")
+ *       Text("Count: @{state.count}")
  *       Button { Text("+") }
  *         .onClick("@actions.increment")
  *     }
@@ -27,12 +27,18 @@
 /**
  * Proxy for state bindings.
  *
- * Use in hypen templates to create reactive state bindings:
+ * In hypen templates, prefer the direct `@{state.x}` syntax. This proxy
+ * exists for cases where you want to interpolate JS values into templates
+ * — e.g., `hypen\`Text("${state.user.name}")\`` produces the same string
+ * as `hypen\`Text("@{state.user.name}")\``.
  *
  * @example
  * ```typescript
+ * // Preferred: direct syntax
+ * hypen`Text("Hello, @{state.user.name}")`
+ *
+ * // Also works: proxy interpolation
  * hypen`Text("Hello, ${state.user.name}")`
- * // Produces: Text("Hello, ${state.user.name}")
  * ```
  */
 export declare const state: any;
@@ -45,7 +51,7 @@ export declare const state: any;
  * ```typescript
  * hypen`
  *   List(@state.items) {
- *     Text("${item.name}: ${item.price}")
+ *     Text("@{item.name}: @{item.price}")
  *   }
  * `
  * ```
@@ -60,7 +66,7 @@ export declare const item: any;
  * ```typescript
  * hypen`
  *   List(@state.items) {
- *     Text("Item #${index}: ${item.name}")
+ *     Text("Item #@{index}: @{item.name}")
  *   }
  * `
  * ```
@@ -69,36 +75,35 @@ export declare const index: any;
 /**
  * Tagged template literal for Hypen DSL templates.
  *
- * Works with the `state`, `item`, and `index` binding proxies to preserve
- * binding syntax in the output string.
+ * Prefer the direct `@{state.x}` / `@{item.x}` syntax. The `state`, `item`,
+ * and `index` proxies are available for interpolating JS variables or
+ * mixing dynamic content with bindings.
  *
  * @example
  * ```typescript
  * import { hypen, state, item } from "@hypen-space/core";
  *
- * // Simple state binding
- * const t1 = hypen`Text("Count: ${state.count}")`;
- * // Result: 'Text("Count: ${state.count}")'
+ * // Preferred: direct binding syntax
+ * const t1 = hypen`Text("Count: @{state.count}")`;
  *
- * // Nested state binding
- * const t2 = hypen`Text("Hello, ${state.user.profile.name}")`;
- * // Result: 'Text("Hello, ${state.user.profile.name}")'
+ * // Nested paths work the same way
+ * const t2 = hypen`Text("Hello, @{state.user.profile.name}")`;
  *
  * // List with item binding
  * const t3 = hypen`
  *   List(@state.products) {
- *     Text("${item.name} - $${item.price}")
+ *     Text("@{item.name} - $@{item.price}")
  *   }
  * `;
  *
- * // Complex expressions (use regular JS interpolation for static values)
+ * // Interpolate JS variables alongside bindings
  * const title = "My App";
- * const t4 = hypen`Text("${title}: ${state.count}")`;
- * // Result: 'Text("My App: ${state.count}")'
+ * const t4 = hypen`Text("${title}: @{state.count}")`;
+ * // Result: 'Text("My App: @{state.count}")'
  * ```
  *
  * @param strings - Template literal string parts
- * @param expressions - Interpolated expressions (proxies return binding strings)
+ * @param expressions - Interpolated JS values or binding proxies
  * @returns The template string with bindings preserved
  */
 export declare function hypen(strings: TemplateStringsArray, ...expressions: unknown[]): string;

package/dist/hypen.js

@@ -26,13 +26,13 @@ function createBindingProxy(root) {
   const handler = {
     get(_, prop) {
       if (prop === Symbol.toPrimitive || prop === "toString" || prop === "valueOf") {
-        return () => `\${${root}}`;
+        return () => `@{${root}}`;
       }
       if (typeof prop === "symbol") {
         return;
       }
       if (prop === "toJSON") {
-        return () => `\${${root}}`;
+        return () => `@{${root}}`;
       }
       return createBindingProxy(`${root}.${prop}`);
     },
@@ -54,10 +54,10 @@ function createBindingProxy(root) {
 var state = createBindingProxy("state");
 var item = createBindingProxy("item");
 var index = {
-  [Symbol.toPrimitive]: () => "${index}",
-  toString: () => "${index}",
-  valueOf: () => "${index}",
-  toJSON: () => "${index}"
+  [Symbol.toPrimitive]: () => "@{index}",
+  toString: () => "@{index}",
+  valueOf: () => "@{index}",
+  toJSON: () => "@{index}"
 };
 function hypen(strings, ...expressions) {
   let result = strings[0];
@@ -75,4 +75,4 @@ export {
   hypen
 };
 
-//# debugId=00831BA93E2ED31164756E2164756E21
+//# debugId=E5F0C092159197CD64756E2164756E21

package/dist/hypen.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/hypen.ts"],
   "sourcesContent": [
-    "/**\n * Hypen Tagged Template Literal\n *\n * Enables single-file components with inline UI templates.\n *\n * The `hypen` tagged template preserves ${state.x} and ${item.x} bindings\n * instead of interpolating them, allowing you to write:\n *\n * @example\n * ```typescript\n * import { app, hypen, state } from \"@hypen-space/core\";\n *\n * export default app\n *   .defineState({ count: 0 })\n *   .onAction(\"increment\", ({ state }) => {\n *     state.count += 1;\n *   })\n *   .ui(hypen`\n *     Column {\n *       Text(\"Count: ${state.count}\")\n *       Button { Text(\"+\") }\n *         .onClick(\"@actions.increment\")\n *     }\n *   `);\n * ```\n */\n\n/**\n * Creates a proxy that captures property access as a binding path string.\n *\n * When used in a template literal, the proxy's toString() returns the\n * full binding expression (e.g., \"${state.user.name}\").\n *\n * @example\n * ```typescript\n * const state = createBindingProxy('state');\n * `${state.user.name}` // Returns: \"${state.user.name}\"\n * ```\n */\nfunction createBindingProxy(root: string): any {\n  const handler: ProxyHandler<object> = {\n    get(_, prop: string | symbol): any {\n      // Handle Symbol.toPrimitive, toString, and valueOf for string conversion\n      if (\n        prop === Symbol.toPrimitive ||\n        prop === \"toString\" ||\n        prop === \"valueOf\"\n      ) {\n        return () => `\\${${root}}`;\n      }\n\n      // Handle other Symbol properties (e.g., Symbol.toStringTag)\n      if (typeof prop === \"symbol\") {\n        return undefined;\n      }\n\n      // Handle JSON.stringify\n      if (prop === \"toJSON\") {\n        return () => `\\${${root}}`;\n      }\n\n      // Chain to nested property: state.user -> state.user.name\n      return createBindingProxy(`${root}.${prop}`);\n    },\n\n    // Support for `in` operator\n    has() {\n      return true;\n    },\n\n    // Support for Object.keys() - return empty to avoid enumeration issues\n    ownKeys() {\n      return [];\n    },\n\n    getOwnPropertyDescriptor() {\n      return {\n        configurable: true,\n        enumerable: true,\n      };\n    },\n  };\n\n  return new Proxy({} as any, handler);\n}\n\n/**\n * Proxy for state bindings.\n *\n * Use in hypen templates to create reactive state bindings:\n *\n * @example\n * ```typescript\n * hypen`Text(\"Hello, ${state.user.name}\")`\n * // Produces: Text(\"Hello, ${state.user.name}\")\n * ```\n */\nexport const state: any = createBindingProxy(\"state\");\n\n/**\n * Proxy for item bindings in list iteration.\n *\n * Use inside List components to reference the current item:\n *\n * @example\n * ```typescript\n * hypen`\n *   List(@state.items) {\n *     Text(\"${item.name}: ${item.price}\")\n *   }\n * `\n * ```\n */\nexport const item: any = createBindingProxy(\"item\");\n\n/**\n * Proxy for index in list iteration.\n *\n * Use inside List components to reference the current index:\n *\n * @example\n * ```typescript\n * hypen`\n *   List(@state.items) {\n *     Text(\"Item #${index}: ${item.name}\")\n *   }\n * `\n * ```\n */\nexport const index: any = {\n  [Symbol.toPrimitive]: () => \"${index}\",\n  toString: () => \"${index}\",\n  valueOf: () => \"${index}\",\n  toJSON: () => \"${index}\",\n};\n\n/**\n * Tagged template literal for Hypen DSL templates.\n *\n * Works with the `state`, `item`, and `index` binding proxies to preserve\n * binding syntax in the output string.\n *\n * @example\n * ```typescript\n * import { hypen, state, item } from \"@hypen-space/core\";\n *\n * // Simple state binding\n * const t1 = hypen`Text(\"Count: ${state.count}\")`;\n * // Result: 'Text(\"Count: ${state.count}\")'\n *\n * // Nested state binding\n * const t2 = hypen`Text(\"Hello, ${state.user.profile.name}\")`;\n * // Result: 'Text(\"Hello, ${state.user.profile.name}\")'\n *\n * // List with item binding\n * const t3 = hypen`\n *   List(@state.products) {\n *     Text(\"${item.name} - $${item.price}\")\n *   }\n * `;\n *\n * // Complex expressions (use regular JS interpolation for static values)\n * const title = \"My App\";\n * const t4 = hypen`Text(\"${title}: ${state.count}\")`;\n * // Result: 'Text(\"My App: ${state.count}\")'\n * ```\n *\n * @param strings - Template literal string parts\n * @param expressions - Interpolated expressions (proxies return binding strings)\n * @returns The template string with bindings preserved\n */\nexport function hypen(\n  strings: TemplateStringsArray,\n  ...expressions: unknown[]\n): string {\n  let result = strings[0];\n\n  for (let i = 0; i < expressions.length; i++) {\n    const expr = expressions[i];\n\n    // Convert expression to string\n    // Binding proxies will return \"${state.x}\" via their toString()\n    result += String(expr);\n    result += strings[i + 1]!;\n  }\n\n  return result!.trim();\n}\n\n/**\n * Type helper for defining state shape.\n * Use with state proxy for better IDE support in complex scenarios.\n *\n * @example\n * ```typescript\n * type MyState = { user: { name: string; age: number } };\n * const typedState = state as StateProxy<MyState>;\n * ```\n */\nexport type StateProxy<T> = {\n  [K in keyof T]: T[K] extends object\n    ? StateProxy<T[K]> & { toString(): string }\n    : { toString(): string };\n} & { toString(): string };\n\n/**\n * Type helper for item proxy in lists.\n */\nexport type ItemProxy<T> = StateProxy<T>;\n"
+    "/**\n * Hypen Tagged Template Literal\n *\n * Enables single-file components with inline UI templates.\n *\n * The `hypen` tagged template preserves @{state.x} and @{item.x} bindings\n * instead of interpolating them, allowing you to write:\n *\n * @example\n * ```typescript\n * import { app, hypen, state } from \"@hypen-space/core\";\n *\n * export default app\n *   .defineState({ count: 0 })\n *   .onAction(\"increment\", ({ state }) => {\n *     state.count += 1;\n *   })\n *   .ui(hypen`\n *     Column {\n *       Text(\"Count: @{state.count}\")\n *       Button { Text(\"+\") }\n *         .onClick(\"@actions.increment\")\n *     }\n *   `);\n * ```\n */\n\n/**\n * Creates a proxy that captures property access as a binding path string.\n *\n * When used in a template literal, the proxy's toString() returns the\n * full binding expression (e.g., \"@{state.user.name}\"). This lets you\n * interpolate JS variables into hypen templates without losing type safety.\n *\n * @example\n * ```typescript\n * const state = createBindingProxy('state');\n * String(state.user.name) // Returns: \"@{state.user.name}\"\n * ```\n */\nfunction createBindingProxy(root: string): any {\n  const handler: ProxyHandler<object> = {\n    get(_, prop: string | symbol): any {\n      // Handle Symbol.toPrimitive, toString, and valueOf for string conversion\n      if (\n        prop === Symbol.toPrimitive ||\n        prop === \"toString\" ||\n        prop === \"valueOf\"\n      ) {\n        return () => `@{${root}}`;\n      }\n\n      // Handle other Symbol properties (e.g., Symbol.toStringTag)\n      if (typeof prop === \"symbol\") {\n        return undefined;\n      }\n\n      // Handle JSON.stringify\n      if (prop === \"toJSON\") {\n        return () => `@{${root}}`;\n      }\n\n      // Chain to nested property: state.user -> state.user.name\n      return createBindingProxy(`${root}.${prop}`);\n    },\n\n    // Support for `in` operator\n    has() {\n      return true;\n    },\n\n    // Support for Object.keys() - return empty to avoid enumeration issues\n    ownKeys() {\n      return [];\n    },\n\n    getOwnPropertyDescriptor() {\n      return {\n        configurable: true,\n        enumerable: true,\n      };\n    },\n  };\n\n  return new Proxy({} as any, handler);\n}\n\n/**\n * Proxy for state bindings.\n *\n * In hypen templates, prefer the direct `@{state.x}` syntax. This proxy\n * exists for cases where you want to interpolate JS values into templates\n * — e.g., `hypen\\`Text(\"${state.user.name}\")\\`` produces the same string\n * as `hypen\\`Text(\"@{state.user.name}\")\\``.\n *\n * @example\n * ```typescript\n * // Preferred: direct syntax\n * hypen`Text(\"Hello, @{state.user.name}\")`\n *\n * // Also works: proxy interpolation\n * hypen`Text(\"Hello, ${state.user.name}\")`\n * ```\n */\nexport const state: any = createBindingProxy(\"state\");\n\n/**\n * Proxy for item bindings in list iteration.\n *\n * Use inside List components to reference the current item:\n *\n * @example\n * ```typescript\n * hypen`\n *   List(@state.items) {\n *     Text(\"@{item.name}: @{item.price}\")\n *   }\n * `\n * ```\n */\nexport const item: any = createBindingProxy(\"item\");\n\n/**\n * Proxy for index in list iteration.\n *\n * Use inside List components to reference the current index:\n *\n * @example\n * ```typescript\n * hypen`\n *   List(@state.items) {\n *     Text(\"Item #@{index}: @{item.name}\")\n *   }\n * `\n * ```\n */\nexport const index: any = {\n  [Symbol.toPrimitive]: () => \"@{index}\",\n  toString: () => \"@{index}\",\n  valueOf: () => \"@{index}\",\n  toJSON: () => \"@{index}\",\n};\n\n/**\n * Tagged template literal for Hypen DSL templates.\n *\n * Prefer the direct `@{state.x}` / `@{item.x}` syntax. The `state`, `item`,\n * and `index` proxies are available for interpolating JS variables or\n * mixing dynamic content with bindings.\n *\n * @example\n * ```typescript\n * import { hypen, state, item } from \"@hypen-space/core\";\n *\n * // Preferred: direct binding syntax\n * const t1 = hypen`Text(\"Count: @{state.count}\")`;\n *\n * // Nested paths work the same way\n * const t2 = hypen`Text(\"Hello, @{state.user.profile.name}\")`;\n *\n * // List with item binding\n * const t3 = hypen`\n *   List(@state.products) {\n *     Text(\"@{item.name} - $@{item.price}\")\n *   }\n * `;\n *\n * // Interpolate JS variables alongside bindings\n * const title = \"My App\";\n * const t4 = hypen`Text(\"${title}: @{state.count}\")`;\n * // Result: 'Text(\"My App: @{state.count}\")'\n * ```\n *\n * @param strings - Template literal string parts\n * @param expressions - Interpolated JS values or binding proxies\n * @returns The template string with bindings preserved\n */\nexport function hypen(\n  strings: TemplateStringsArray,\n  ...expressions: unknown[]\n): string {\n  let result = strings[0];\n\n  for (let i = 0; i < expressions.length; i++) {\n    const expr = expressions[i];\n\n    // Convert expression to string\n    // Binding proxies will return \"@{state.x}\" via their toString()\n    result += String(expr);\n    result += strings[i + 1]!;\n  }\n\n  return result!.trim();\n}\n\n/**\n * Type helper for defining state shape.\n * Use with state proxy for better IDE support in complex scenarios.\n *\n * @example\n * ```typescript\n * type MyState = { user: { name: string; age: number } };\n * const typedState = state as StateProxy<MyState>;\n * ```\n */\nexport type StateProxy<T> = {\n  [K in keyof T]: T[K] extends object\n    ? StateProxy<T[K]> & { toString(): string }\n    : { toString(): string };\n} & { toString(): string };\n\n/**\n * Type helper for item proxy in lists.\n */\nexport type ItemProxy<T> = StateProxy<T>;\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;AAuCA,SAAS,kBAAkB,CAAC,MAAmB;AAAA,EAC7C,MAAM,UAAgC;AAAA,IACpC,GAAG,CAAC,GAAG,MAA4B;AAAA,MAEjC,IACE,SAAS,OAAO,eAChB,SAAS,cACT,SAAS,WACT;AAAA,QACA,OAAO,MAAM,MAAM;AAAA,MACrB;AAAA,MAGA,IAAI,OAAO,SAAS,UAAU;AAAA,QAC5B;AAAA,MACF;AAAA,MAGA,IAAI,SAAS,UAAU;AAAA,QACrB,OAAO,MAAM,MAAM;AAAA,MACrB;AAAA,MAGA,OAAO,mBAAmB,GAAG,QAAQ,MAAM;AAAA;AAAA,IAI7C,GAAG,GAAG;AAAA,MACJ,OAAO;AAAA;AAAA,IAIT,OAAO,GAAG;AAAA,MACR,OAAO,CAAC;AAAA;AAAA,IAGV,wBAAwB,GAAG;AAAA,MACzB,OAAO;AAAA,QACL,cAAc;AAAA,QACd,YAAY;AAAA,MACd;AAAA;AAAA,EAEJ;AAAA,EAEA,OAAO,IAAI,MAAM,CAAC,GAAU,OAAO;AAAA;AAc9B,IAAM,QAAa,mBAAmB,OAAO;AAgB7C,IAAM,OAAY,mBAAmB,MAAM;AAgB3C,IAAM,QAAa;AAAA,GACvB,OAAO,cAAc,MAAM;AAAA,EAC5B,UAAU,MAAM;AAAA,EAChB,SAAS,MAAM;AAAA,EACf,QAAQ,MAAM;AAChB;AAqCO,SAAS,KAAK,CACnB,YACG,aACK;AAAA,EACR,IAAI,SAAS,QAAQ;AAAA,EAErB,SAAS,IAAI,EAAG,IAAI,YAAY,QAAQ,KAAK;AAAA,IAC3C,MAAM,OAAO,YAAY;AAAA,IAIzB,UAAU,OAAO,IAAI;AAAA,IACrB,UAAU,QAAQ,IAAI;AAAA,EACxB;AAAA,EAEA,OAAO,OAAQ,KAAK;AAAA;",
-  "debugId": "00831BA93E2ED31164756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,kBAAkB,CAAC,MAAmB;AAAA,EAC7C,MAAM,UAAgC;AAAA,IACpC,GAAG,CAAC,GAAG,MAA4B;AAAA,MAEjC,IACE,SAAS,OAAO,eAChB,SAAS,cACT,SAAS,WACT;AAAA,QACA,OAAO,MAAM,KAAK;AAAA,MACpB;AAAA,MAGA,IAAI,OAAO,SAAS,UAAU;AAAA,QAC5B;AAAA,MACF;AAAA,MAGA,IAAI,SAAS,UAAU;AAAA,QACrB,OAAO,MAAM,KAAK;AAAA,MACpB;AAAA,MAGA,OAAO,mBAAmB,GAAG,QAAQ,MAAM;AAAA;AAAA,IAI7C,GAAG,GAAG;AAAA,MACJ,OAAO;AAAA;AAAA,IAIT,OAAO,GAAG;AAAA,MACR,OAAO,CAAC;AAAA;AAAA,IAGV,wBAAwB,GAAG;AAAA,MACzB,OAAO;AAAA,QACL,cAAc;AAAA,QACd,YAAY;AAAA,MACd;AAAA;AAAA,EAEJ;AAAA,EAEA,OAAO,IAAI,MAAM,CAAC,GAAU,OAAO;AAAA;AAoB9B,IAAM,QAAa,mBAAmB,OAAO;AAgB7C,IAAM,OAAY,mBAAmB,MAAM;AAgB3C,IAAM,QAAa;AAAA,GACvB,OAAO,cAAc,MAAM;AAAA,EAC5B,UAAU,MAAM;AAAA,EAChB,SAAS,MAAM;AAAA,EACf,QAAQ,MAAM;AAChB;AAoCO,SAAS,KAAK,CACnB,YACG,aACK;AAAA,EACR,IAAI,SAAS,QAAQ;AAAA,EAErB,SAAS,IAAI,EAAG,IAAI,YAAY,QAAQ,KAAK;AAAA,IAC3C,MAAM,OAAO,YAAY;AAAA,IAIzB,UAAU,OAAO,IAAI;AAAA,IACrB,UAAU,QAAQ,IAAI;AAAA,EACxB;AAAA,EAEA,OAAO,OAAQ,KAAK;AAAA;",
+  "debugId": "E5F0C092159197CD64756E2164756E21",
   "names": []
 }

package/dist/index.browser.js

@@ -723,6 +723,7 @@ class HypenAppBuilder {
   template;
   _registry;
   dataSourceEntries = [];
+  _stateStore;
   constructor(initialState, options, registry) {
     this.initialState = initialState;
     this.options = options || {};
@@ -756,6 +757,10 @@ class HypenAppBuilder {
     this.errorHandler = fn;
     return this;
   }
+  persist(store) {
+    this._stateStore = store;
+    return this;
+  }
   useDataSource(plugin, config2) {
     this.dataSourceEntries.push({ plugin, config: config2 });
     return this;
@@ -780,6 +785,7 @@ class HypenAppBuilder {
       initialState: this.initialState,
       template: this.template,
       dataSources: this.dataSourceEntries.length > 0 ? this.dataSourceEntries : undefined,
+      stateStore: this._stateStore,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
@@ -844,22 +850,33 @@ class HypenModuleInstance {
   stateChangeCallbacks = [];
   dataSourceManager;
   dataSourceAccessor = {};
-  constructor(engine, definition, router, globalContext) {
+  stateStore;
+  currentPersistKey = null;
+  persistDebounceTimer;
+  sessionId;
+  moduleKey = "";
+  constructor(engine, definition, router, globalContext, sessionId) {
     this.engine = engine;
     this.definition = definition;
     this.router = router ?? null;
     this.globalContext = globalContext;
-    const statePrefix = (definition.name || "").toLowerCase();
+    this.sessionId = sessionId ?? crypto.randomUUID();
+    this.stateStore = definition.stateStore;
+    const moduleKey = (definition.name || "").toLowerCase();
+    this.moduleKey = moduleKey;
     this.state = createObservableState(definition.initialState, {
       onChange: (change) => {
-        this.engine.notifyStateChange(change.paths, change.newValues);
+        this.engine.updateStateSparse(moduleKey || null, change.paths, change.newValues);
         this.stateChangeCallbacks.forEach((cb) => cb());
-      },
-      pathPrefix: statePrefix || undefined
+        this.persistIfNeeded();
+      }
     });
     const snapshot = getStateSnapshot(this.state);
-    const prefixedState = statePrefix ? { [statePrefix]: snapshot } : snapshot;
-    this.engine.setModule(definition.name || "AnonymousModule", definition.actions, definition.stateKeys, prefixedState);
+    if (moduleKey) {
+      this.engine.registerModule(moduleKey, definition.actions, definition.stateKeys, snapshot);
+    } else {
+      this.engine.setModule("AnonymousModule", definition.actions, definition.stateKeys, snapshot);
+    }
     for (const [actionName, handler] of definition.handlers.onAction) {
       log2.debug(`Registering action handler: ${actionName} for module ${definition.name}`);
       this.engine.onAction(actionName, async (action) => {
@@ -969,7 +986,54 @@ class HypenModuleInstance {
     log2.error(`${context.actionName ? `Action "${context.actionName}"` : `Lifecycle "${context.lifecycle}"`} error:`, error);
     return false;
   }
+  persistIfNeeded() {
+    if (!this.stateStore)
+      return;
+    const store = this.stateStore;
+    const newKey = store.resolveKey(this.state, this.definition.name || "AnonymousModule", this.sessionId);
+    if (newKey && !this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+    if (!newKey && this.currentPersistKey) {
+      this.currentPersistKey = null;
+      return;
+    }
+    if (newKey && newKey !== this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+    if (!this.currentPersistKey)
+      return;
+    clearTimeout(this.persistDebounceTimer);
+    this.persistDebounceTimer = setTimeout(() => {
+      const snapshot = getStateSnapshot(this.state);
+      store.save(this.currentPersistKey, snapshot);
+    }, 50);
+  }
+  async activatePersistence(key) {
+    this.currentPersistKey = key;
+    const stored = await this.stateStore.load(key);
+    if (stored) {
+      const merged = { ...this.definition.initialState, ...stored };
+      Object.assign(this.state, merged);
+    } else {
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore.save(key, snapshot);
+    }
+  }
   async callCreatedHandler() {
+    if (this.stateStore) {
+      const key = this.stateStore.resolveKey(this.state, this.definition.name || "AnonymousModule", this.sessionId);
+      if (key) {
+        this.currentPersistKey = key;
+        const stored = await this.stateStore.load(key);
+        if (stored) {
+          const merged = { ...this.definition.initialState, ...stored };
+          Object.assign(this.state, merged);
+        }
+      }
+    }
     if (this.definition.dataSources?.length) {
       const dsEngine = this.engine;
       this.dataSourceManager = new DataSourceManager(dsEngine);
@@ -1008,6 +1072,11 @@ class HypenModuleInstance {
   async destroy() {
     if (this.isDestroyed)
       return;
+    if (this.currentPersistKey && this.stateStore) {
+      clearTimeout(this.persistDebounceTimer);
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore.save(this.currentPersistKey, snapshot);
+    }
     if (this.dataSourceManager) {
       try {
         await this.dataSourceManager.disconnectAll();
@@ -1336,11 +1405,13 @@ class HypenRouter {
         } else {
           window.history.pushState(null, "", url);
         }
-        const hashChangeEvent = new HashChangeEvent("hashchange", {
-          oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
-          newURL: window.location.href
-        });
-        window.dispatchEvent(hashChangeEvent);
+        try {
+          const hashChangeEvent = new HashChangeEvent("hashchange", {
+            oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
+            newURL: window.location.href
+          });
+          window.dispatchEvent(hashChangeEvent);
+        } catch {}
       }
     } finally {
       this.isUpdating = false;
@@ -1812,7 +1883,8 @@ class RemoteEngine {
     const hello = {
       type: "hello",
       sessionId: this.currentSessionId ?? this.sessionOptions?.id,
-      props: this.sessionOptions?.props
+      props: this.sessionOptions?.props,
+      persistKey: this.sessionOptions?.persistKey
     };
     this.ws.send(JSON.stringify(hello));
   }
@@ -2082,4 +2154,4 @@ export {
   BaseRenderer
 };
 
-//# debugId=1B989D60F3E5B0FC64756E2164756E21
+//# debugId=DD07DC2DABBCE3FD64756E2164756E21