@hypen-space/core 0.4.46 → 0.4.81

package/src/hypen.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")
  *     }
@@ -29,12 +29,13 @@
  * Creates a proxy that captures property access as a binding path string.
  *
  * When used in a template literal, the proxy's toString() returns the
- * full binding expression (e.g., "${state.user.name}").
+ * full binding expression (e.g., "@{state.user.name}"). This lets you
+ * interpolate JS variables into hypen templates without losing type safety.
  *
  * @example
  * ```typescript
  * const state = createBindingProxy('state');
- * `${state.user.name}` // Returns: "${state.user.name}"
+ * String(state.user.name) // Returns: "@{state.user.name}"
  * ```
  */
 function createBindingProxy(root: string): any {
@@ -46,7 +47,7 @@ function createBindingProxy(root: string): any {
         prop === "toString" ||
         prop === "valueOf"
       ) {
-        return () => `\${${root}}`;
+        return () => `@{${root}}`;
       }
 
       // Handle other Symbol properties (e.g., Symbol.toStringTag)
@@ -56,7 +57,7 @@ function createBindingProxy(root: string): any {
 
       // Handle JSON.stringify
       if (prop === "toJSON") {
-        return () => `\${${root}}`;
+        return () => `@{${root}}`;
       }
 
       // Chain to nested property: state.user -> state.user.name
@@ -87,12 +88,18 @@ function createBindingProxy(root: string): any {
 /**
  * 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 const state: any = createBindingProxy("state");
@@ -106,7 +113,7 @@ export const state: any = createBindingProxy("state");
  * ```typescript
  * hypen`
  *   List(@state.items) {
- *     Text("${item.name}: ${item.price}")
+ *     Text("@{item.name}: @{item.price}")
  *   }
  * `
  * ```
@@ -122,51 +129,50 @@ export const item: any = createBindingProxy("item");
  * ```typescript
  * hypen`
  *   List(@state.items) {
- *     Text("Item #${index}: ${item.name}")
+ *     Text("Item #@{index}: @{item.name}")
  *   }
  * `
  * ```
  */
 export const index: any = {
-  [Symbol.toPrimitive]: () => "${index}",
-  toString: () => "${index}",
-  valueOf: () => "${index}",
-  toJSON: () => "${index}",
+  [Symbol.toPrimitive]: () => "@{index}",
+  toString: () => "@{index}",
+  valueOf: () => "@{index}",
+  toJSON: () => "@{index}",
 };
 
 /**
  * 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 function hypen(
@@ -179,7 +185,7 @@ export function hypen(
     const expr = expressions[i];
 
     // Convert expression to string
-    // Binding proxies will return "${state.x}" via their toString()
+    // Binding proxies will return "@{state.x}" via their toString()
     result += String(expr);
     result += strings[i + 1]!;
   }

package/src/index.ts

@@ -16,7 +16,7 @@
  *   })
  *   .ui(hypen`
  *     Column {
- *       Text("Count: ${state.count}")
+ *       Text("Count: @{state.count}")
  *       Button { Text("+") }
  *         .onClick("@actions.increment")
  *     }
@@ -37,7 +37,7 @@
  *   .build();
  *
  * // component.hypen (separate file)
- * // Column { Text("Count: ${state.count}") ... }
+ * // Column { Text("Count: @{state.count}") ... }
  * ```
  */
 
@@ -95,6 +95,12 @@ export type {
   DataSourceAccessor,
 } from "./app.js";
 
+// ============================================================================
+// STATE PERSISTENCE
+// ============================================================================
+
+export type { StateStore } from "./persistence.js";
+
 // ============================================================================
 // DATA SOURCE PLUGIN SYSTEM
 // ============================================================================

package/src/persistence.ts

@@ -0,0 +1,25 @@
+/**
+ * State Persistence Layer
+ *
+ * Pluggable persistence interface for Hypen modules.
+ * Modules opt in with `.persist(adapter)` on the builder.
+ * The runtime handles save/restore lifecycle transparently.
+ */
+
+export interface StateStore<T = unknown> {
+  /**
+   * Resolve the storage key for this module instance.
+   * Called on init and whenever state changes (for withKey).
+   * Returns null = no persistence active.
+   */
+  resolveKey(state: T, moduleName: string, sessionId: string): string | null;
+
+  /** Load persisted state. Called when key first resolves to non-null. */
+  load(key: string): Promise<T | null>;
+
+  /** Save state. Called on mutation (debounced by runtime). */
+  save(key: string, state: T): Promise<void>;
+
+  /** Delete persisted state. Called on session expire. */
+  delete(key: string): Promise<void>;
+}

package/src/remote/client.ts

@@ -71,6 +71,8 @@ export interface SessionOptions {
   id?: string;
   /** Client metadata (platform, version, userId, etc.) */
   props?: Record<string, unknown>;
+  /** Optional persist/routing key for Durable Object routing (withKey) */
+  persistKey?: string;
 }
 
 /**
@@ -270,6 +272,7 @@ export class RemoteEngine implements Disposable {
       type: "hello",
       sessionId: this.currentSessionId ?? this.sessionOptions?.id,
       props: this.sessionOptions?.props,
+      persistKey: this.sessionOptions?.persistKey,
     };
 
     this.ws.send(JSON.stringify(hello));

package/src/remote/types.ts

@@ -73,6 +73,8 @@ export interface HelloMessage {
   sessionId?: string;
   /** Client metadata (platform, version, userId, etc.) */
   props?: Record<string, any>;
+  /** Optional persist/routing key for Durable Object routing (withKey) */
+  persistKey?: string;
 }
 
 /**

package/src/router.ts

@@ -184,12 +184,19 @@ export class HypenRouter {
           window.history.pushState(null, "", url);
         }
 
-        // Manually trigger hashchange event
-        const hashChangeEvent = new HashChangeEvent("hashchange", {
-          oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
-          newURL: window.location.href,
-        });
-        window.dispatchEvent(hashChangeEvent);
+        // Manually trigger hashchange event.  Wrap in try-catch because
+        // in test environments the global HashChangeEvent class may come
+        // from a different realm than the window, causing dispatchEvent to
+        // reject it with "parameter 1 is not of type 'Event'".
+        try {
+          const hashChangeEvent = new HashChangeEvent("hashchange", {
+            oldURL: window.location.href.replace(window.location.hash, "#" + oldPath),
+            newURL: window.location.href,
+          });
+          window.dispatchEvent(hashChangeEvent);
+        } catch {
+          // Ignore cross-realm Event dispatch errors
+        }
       }
     } finally {
       this.isUpdating = false;

package/src/types.ts

@@ -36,3 +36,4 @@ export type ComponentResolver = (
   componentName: string,
   contextPath: string | null
 ) => ResolvedComponent | null;
+