@hypen-space/core 0.4.46 → 0.4.82

package/src/app.ts

@@ -7,12 +7,27 @@ import type { Action } from "./types.js";
 import type { Session } from "./remote/types.js";
 import { type Result, Ok, Err, fromPromise, ActionError, HypenError } from "./result.js";
 import { DataSourceManager, type DataSourcePlugin, type IDataSourceEngine } from "./datasource.js";
+import type { StateStore } from "./persistence.js";
 
 // Interface for engine compatibility (works with both engine.js and engine.browser.js)
 export interface IEngine {
   setModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
+  registerModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
   onAction(actionName: string, handler: (action: Action) => void | Promise<void>): void;
-  notifyStateChange(paths: string[], changedValues: Record<string, unknown>): void;
+  /**
+   * Apply a sparse state update.
+   *
+   * @param scope  Lowercase module name to target a named module registered
+   *               via `registerModule`. Pass `null` (or empty string) to
+   *               target the primary module set via `setModule`.
+   * @param paths  Changed state paths (relative to the targeted module).
+   * @param values Map of `path -> new value`.
+   */
+  updateStateSparse(
+    scope: string | null,
+    paths: string[],
+    values: Record<string, unknown>
+  ): void;
 }
 
 import { createObservableState, type StateChange, getStateSnapshot } from "./state.js";
@@ -159,6 +174,11 @@ export interface HypenModuleDefinition<T = unknown> {
    * Each entry contains the plugin and its configuration.
    */
   dataSources?: Array<{ plugin: DataSourcePlugin; config: unknown }>;
+  /**
+   * Pluggable state store for persistence across sessions.
+   * Set via the `.persist(store)` builder method.
+   */
+  stateStore?: StateStore<T>;
   handlers: {
     onCreated?: LifecycleHandler<T>;
     onAction: Map<string, ActionHandler<T, any>>;
@@ -195,6 +215,7 @@ export class HypenAppBuilder<T> {
   private template?: string;
   private _registry?: Map<string, HypenModuleDefinition>;
   private dataSourceEntries: Array<{ plugin: DataSourcePlugin; config: unknown }> = [];
+  private _stateStore?: StateStore<T>;
 
   constructor(
     initialState: T,
@@ -306,6 +327,25 @@ export class HypenAppBuilder<T> {
     return this;
   }
 
+  /**
+   * Attach a persistent state store.
+   * The store handles save/restore lifecycle automatically.
+   *
+   * @example
+   * ```typescript
+   * import { durableObjectStore, withKey } from "@hypen-space/cf";
+   *
+   * app
+   *   .defineState({ user: null, todos: [] }, { name: "TodoList" })
+   *   .persist(durableObjectStore(withKey(state => state.user?.id)))
+   *   .build();
+   * ```
+   */
+  persist(store: StateStore<T>): this {
+    this._stateStore = store;
+    return this;
+  }
+
   /**
    * Register a data source plugin for live database subscriptions.
    *
@@ -327,10 +367,10 @@ export class HypenAppBuilder<T> {
    *   .build();
    * ```
    *
-   * In Hypen DSL, bind to data source tables with `$provider.table`:
+   * In Hypen DSL, bind to data source tables with `@provider.table`:
    * ```hypen
-   * ForEach(items: $spacetime.message, key: "id") {
-   *   Text("${item.text}")
+   * ForEach(items: @spacetime.message, key: "id") {
+   *   Text("@{item.text}")
    * }
    * ```
    */
@@ -355,7 +395,7 @@ export class HypenAppBuilder<T> {
    *   })
    *   .ui(hypen`
    *     Column {
-   *       Text("Count: ${state.count}")
+   *       Text("Count: @{state.count}")
    *       Button { Text("+") }
    *         .onClick("@actions.increment")
    *     }
@@ -410,6 +450,7 @@ export class HypenAppBuilder<T> {
       initialState: this.initialState,
       template: this.template,
       dataSources: this.dataSourceEntries.length > 0 ? this.dataSourceEntries : undefined,
+      stateStore: this._stateStore,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
@@ -546,47 +587,70 @@ export class HypenModuleInstance<T extends object = any> {
   private stateChangeCallbacks: Array<() => void> = [];
   private dataSourceManager?: DataSourceManager;
   private dataSourceAccessor: DataSourceAccessor = {};
+  private stateStore?: StateStore<T>;
+  private currentPersistKey: string | null = null;
+  private persistDebounceTimer: any;
+  private sessionId: string;
+  /**
+   * Lowercase name used to address this module in the engine. Empty string
+   * for anonymous modules (which back the engine's primary module slot).
+   */
+  private moduleKey: string = "";
 
   constructor(
     engine: IEngine,
     definition: HypenModuleDefinition<T>,
     router?: HypenRouter | null,
-    globalContext?: HypenGlobalContext
+    globalContext?: HypenGlobalContext,
+    sessionId?: string
   ) {
     this.engine = engine;
     this.definition = definition;
     this.router = router ?? null;
     this.globalContext = globalContext;
-
-    // Named state prefix — all lowercase per convention
-    const statePrefix = (definition.name || "").toLowerCase();
-
-    // Create observable state that sends only changed paths and values to engine
-    // When a prefix is set, all paths are namespaced (e.g., "homepage.count")
+    this.sessionId = sessionId ?? crypto.randomUUID();
+    this.stateStore = definition.stateStore;
+
+    // Lowercase module name — used as the engine-side scope key. Empty for
+    // anonymous modules (which become the engine's primary module).
+    const moduleKey = (definition.name || "").toLowerCase();
+    this.moduleKey = moduleKey;
+
+    // Create observable state that forwards changed paths to the engine.
+    // Paths are passed through raw — the engine handles module scoping via
+    // the IR's `module_scope` field derived from `module <Name> { ... }` in
+    // the DSL.
     this.state = createObservableState<T>(definition.initialState as T & object, {
       onChange: (change: StateChange) => {
-        // Send only the changed paths and their new values (not the whole state)
-        this.engine.notifyStateChange(change.paths, change.newValues);
-        // Notify all registered callbacks
+        this.engine.updateStateSparse(
+          moduleKey || null,
+          change.paths,
+          change.newValues
+        );
         this.stateChangeCallbacks.forEach(cb => cb());
+        this.persistIfNeeded();
       },
-      pathPrefix: statePrefix || undefined,
     });
 
-    // Register with engine (initial state registration)
-    // When prefixed, nest the state under the module name so the engine sees
-    // e.g., { homepage: { count: 0 } } instead of { count: 0 }
+    // Register the module with the engine. Named modules go into the
+    // secondary `engine.modules` slot under their lowercase name; anonymous
+    // modules become the engine's primary module.
     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
+      );
+    }
 
     // Register action handlers with flexible parameter support
     for (const [actionName, handler] of definition.handlers.onAction) {
@@ -766,10 +830,87 @@ export class HypenModuleInstance<T extends object = any> {
     return false;
   }
 
+  /**
+   * Re-evaluate the persistence key and debounce saves on state mutation.
+   * Handles key transitions (null->value, value->null, value->different value).
+   */
+  private persistIfNeeded(): void {
+    if (!this.stateStore) return;
+
+    const store = this.stateStore;
+    const newKey = store.resolveKey(
+      this.state,
+      this.definition.name || "AnonymousModule",
+      this.sessionId
+    );
+
+    // Key transition: null -> value (e.g. login)
+    if (newKey && !this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+
+    // Key transition: value -> null (e.g. logout)
+    if (!newKey && this.currentPersistKey) {
+      this.currentPersistKey = null;
+      return; // stop persisting, but don't delete stored data
+    }
+
+    // Key transition: value -> different value (e.g. account switch)
+    if (newKey && newKey !== this.currentPersistKey) {
+      this.activatePersistence(newKey);
+      return;
+    }
+
+    // No key = no persistence
+    if (!this.currentPersistKey) return;
+
+    // Same key — debounced save
+    clearTimeout(this.persistDebounceTimer);
+    this.persistDebounceTimer = setTimeout(() => {
+      const snapshot = getStateSnapshot(this.state);
+      store.save(this.currentPersistKey!, snapshot);
+    }, 50);
+  }
+
+  /**
+   * Activate persistence for the given key: load stored state and merge.
+   */
+  private async activatePersistence(key: string): Promise<void> {
+    this.currentPersistKey = key;
+    const stored = await this.stateStore!.load(key);
+    if (stored) {
+      // Merge stored over initialState, then apply to live state
+      const merged = { ...this.definition.initialState, ...stored };
+      Object.assign(this.state, merged); // triggers re-render via proxy
+    } else {
+      // First time with this key — save current state
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore!.save(key, snapshot);
+    }
+  }
+
   /**
    * Call the onCreated handler and connect data source plugins
    */
   private async callCreatedHandler(): Promise<void> {
+    // Load persisted state before anything else
+    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);
+        }
+      }
+    }
+
     // Initialize data source plugins if any are registered
     if (this.definition.dataSources?.length) {
       // The engine must implement IDataSourceEngine methods
@@ -822,6 +963,13 @@ export class HypenModuleInstance<T extends object = any> {
   async destroy(): Promise<void> {
     if (this.isDestroyed) return;
 
+    // Flush any pending persistence writes before shutdown
+    if (this.currentPersistKey && this.stateStore) {
+      clearTimeout(this.persistDebounceTimer);
+      const snapshot = getStateSnapshot(this.state);
+      await this.stateStore.save(this.currentPersistKey, snapshot);
+    }
+
     // Disconnect all data source plugins
     if (this.dataSourceManager) {
       try {

package/src/datasource.ts

@@ -4,10 +4,10 @@
  * Enables live subscription databases (SpacetimeDB, Firebase, Convex, Electric SQL)
  * to push data into the Hypen reactive engine via a unified plugin interface.
  *
- * UI bindings use the `$provider.path` syntax:
- *   - `$spacetime.messages` → SpacetimeDB messages table
- *   - `$firebase.user.profile` → Firebase user profile
- *   - `$convex.tasks` → Convex tasks table
+ * UI bindings use the `@provider.path` syntax:
+ *   - `@spacetime.messages` → SpacetimeDB messages table
+ *   - `@firebase.user.profile` → Firebase user profile
+ *   - `@convex.tasks` → Convex tasks table
  *
  * @module
  */

package/src/engine-base.ts

@@ -0,0 +1,358 @@
+/**
+ * Abstract base class for Hypen WASM engine wrappers.
+ *
+ * The Hypen engine is distributed as a wasm-bindgen module — two builds:
+ *
+ *   - `wasm-node`  (bundler target) — used by `@hypen-space/server` on Node/Bun
+ *   - `wasm-browser` (web target)   — used by `@hypen-space/web-engine` in browsers
+ *
+ * Both builds expose an identical `WasmEngine` class; the only genuine
+ * platform differences are:
+ *
+ *   1. How the WASM module is *instantiated*. Node can synchronously `new
+ *      WasmEngine()` (the bundler target auto-initializes); the browser
+ *      target needs an async dynamic import of the JS glue code and an
+ *      explicit `wasm_init(url)` call before any `new WasmEngine()`.
+ *
+ *   2. How host state is *unwrapped* before it crosses the WASM boundary.
+ *      Node can use `structuredClone` (with a `__getSnapshot` fast path for
+ *      Hypen's proxy-backed state); the browser path does a
+ *      `JSON.parse(JSON.stringify())` round-trip plus a Map-to-Object
+ *      conversion for the native Map values that the wasm-bindgen browser
+ *      target returns in action payloads.
+ *
+ * Everything else — method wrappers, error classification, callback wiring,
+ * revision plumbing — is identical between the two. That shared surface
+ * lives here.
+ *
+ * Subclasses implement two abstract hooks:
+ *
+ *   - `init(options?): Promise<void>` — platform-specific WASM setup. Must
+ *     assign `this.wasmEngine` and set `this.initialized = true` on success.
+ *
+ *   - `unwrapForWasm<T>(value: T): T` — platform-specific proxy-to-plain
+ *     conversion. Called before any value crosses into WASM.
+ */
+
+import { frameworkLoggers } from "./logger.js";
+import { classifyEngineError } from "./result.js";
+import type {
+  Patch,
+  Action,
+  RenderCallback,
+  ActionHandler,
+  ComponentResolver,
+} from "./types.js";
+
+const log = frameworkLoggers.engine;
+
+/**
+ * Shared base wrapping a wasm-bindgen `WasmEngine`. `any` here is load-
+ * bearing: the concrete type is `WasmEngine` from either the `wasm-node`
+ * or `wasm-browser` build, and those are separate generated `.d.ts`
+ * files that core cannot (and should not) depend on. Subclasses keep
+ * their own typed reference if they want stricter checking locally.
+ */
+export abstract class BaseEngine {
+  protected wasmEngine: any = null;
+  protected initialized = false;
+
+  /**
+   * Initialize the WASM module. Platform-specific.
+   *
+   * Must assign `this.wasmEngine` and set `this.initialized = true`.
+   * Idempotent: must early-return if already initialized.
+   */
+  abstract init(options?: unknown): Promise<void>;
+
+  /**
+   * Convert a host value (possibly a Proxy, possibly containing Maps,
+   * possibly wrapped in Hypen's observable state) into a plain-object
+   * form safe to pass across the WASM boundary.
+   *
+   * Called on every `updateState` / `updateStateSparse` / `renderInto`
+   * / `setContext` / `registerModule` entry point.
+   */
+  protected abstract unwrapForWasm<T>(value: T): T;
+
+  /**
+   * Guard that throws if the engine hasn't been initialized.
+   * Returns the underlying WASM engine for chained access.
+   */
+  protected ensureInitialized(): any {
+    if (!this.wasmEngine) {
+      throw new Error("Engine not initialized. Call init() first.");
+    }
+    return this.wasmEngine;
+  }
+
+  /**
+   * Set the render callback that receives patches.
+   */
+  setRenderCallback(callback: RenderCallback): void {
+    const engine = this.ensureInitialized();
+    engine.setRenderCallback((patches: Patch[]) => {
+      callback(patches);
+    });
+  }
+
+  /**
+   * Set the component resolver for dynamic component composition.
+   */
+  setComponentResolver(resolver: ComponentResolver): void {
+    const engine = this.ensureInitialized();
+    engine.setComponentResolver(
+      (componentName: string, contextPath: string | null) => {
+        return resolver(componentName, contextPath);
+      },
+    );
+  }
+
+  /**
+   * Parse and render Hypen DSL source code.
+   * @throws {ParseError} if the source fails to parse
+   * @throws {RenderError} if rendering fails
+   */
+  renderSource(source: string): void {
+    const engine = this.ensureInitialized();
+    try {
+      engine.renderSource(source);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
+  }
+
+  /**
+   * Render a lazy component (for lazy route loading).
+   */
+  renderLazyComponent(source: string): void {
+    const engine = this.ensureInitialized();
+    engine.renderLazyComponent(source);
+  }
+
+  /**
+   * Render a component into a specific parent node (subtree rendering).
+   * @throws {ParseError} if the source fails to parse
+   * @throws {RenderError} if the parent node is not found or rendering fails
+   */
+  renderInto(
+    source: string,
+    parentNodeId: string,
+    state: Record<string, any>,
+  ): void {
+    const engine = this.ensureInitialized();
+    try {
+      engine.renderInto(source, parentNodeId, this.unwrapForWasm(state));
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
+  }
+
+  /**
+   * Apply a sparse state update.
+   *
+   * @param scope  Lowercase module name to target a named module registered
+   *               via `registerModule`. Pass `null` (or empty string) to
+   *               target the primary module set via `setModule`.
+   * @param paths  Changed state paths (relative to the targeted module).
+   * @param values Map of `path -> new value`.
+   * @throws {StateError} if the state patch is invalid
+   */
+  updateStateSparse(
+    scope: string | null,
+    paths: string[],
+    values: Record<string, any>,
+  ): void {
+    const engine = this.ensureInitialized();
+
+    if (paths.length === 0) {
+      return;
+    }
+
+    try {
+      engine.updateStateSparse(scope ?? "", paths, this.unwrapForWasm(values));
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
+    log.debug("State changed (sparse):", { scope, paths });
+  }
+
+  /**
+   * Apply a full-state patch. See [updateStateSparse] for `scope` semantics.
+   * Prefer the sparse form when only a few paths changed.
+   */
+  updateState(scope: string | null, statePatch: Record<string, any>): void {
+    const engine = this.ensureInitialized();
+    engine.updateState(scope ?? "", this.unwrapForWasm(statePatch));
+  }
+
+  /**
+   * Dispatch an action.
+   * @throws {HypenError} if the action dispatch fails
+   */
+  dispatchAction(name: string, payload?: any): void {
+    const engine = this.ensureInitialized();
+    try {
+      engine.dispatchAction(name, payload ?? null);
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
+  }
+
+  /**
+   * Register an action handler. Errors thrown synchronously or via rejected
+   * promises are caught and logged at the framework level; caller-side error
+   * recovery should happen inside `handler`.
+   *
+   * Action payloads may contain platform-specific native values (e.g. Maps
+   * in the browser target). Subclasses can override `normalizeAction` to
+   * pre-process the action before calling the user handler.
+   */
+  onAction(actionName: string, handler: ActionHandler): void {
+    const engine = this.ensureInitialized();
+    engine.onAction(actionName, (action: Action) => {
+      const normalized = this.normalizeAction(action);
+      Promise.resolve(handler(normalized)).catch((err) => {
+        log.error("Action handler error:", err);
+      });
+    });
+  }
+
+  /**
+   * Platform hook: normalize an incoming action before the user handler
+   * sees it. Default identity; subclasses can override to unwrap native
+   * values (e.g. browser Maps in action payloads).
+   */
+  protected normalizeAction(action: Action): Action {
+    return action;
+  }
+
+  /**
+   * Initialize the primary module.
+   */
+  setModule(
+    name: string,
+    actions: string[],
+    stateKeys: string[],
+    initialState: Record<string, any>,
+  ): void {
+    const engine = this.ensureInitialized();
+    engine.setModule(name, actions, stateKeys, initialState);
+  }
+
+  /**
+   * Register a named module for multi-module apps.
+   *
+   * Unlike setModule which sets the primary module, this registers an
+   * additional module whose state is scoped to `module <name> { ... }`
+   * blocks in the DSL.
+   */
+  registerModule(
+    name: string,
+    actions: string[],
+    stateKeys: string[],
+    initialState: Record<string, any>,
+  ): void {
+    const engine = this.ensureInitialized();
+    engine.registerModule(
+      name,
+      actions,
+      stateKeys,
+      this.unwrapForWasm(initialState),
+    );
+  }
+
+  /**
+   * Get the current revision number.
+   *
+   * Note: the underlying WASM builder returns `bigint` in some targets
+   * and `number` in others; this normalizes to `number` for consumer
+   * ergonomics (revision counts don't exceed 2^53).
+   */
+  getRevision(): number {
+    const engine = this.ensureInitialized();
+    return Number(engine.getRevision());
+  }
+
+  /**
+   * Clear resolved components and caches, preserving primitives and resolver.
+   * Call before renderSource() during hot-reload so components are re-resolved
+   * from fresh source files.
+   */
+  clearResolvedComponents(): void {
+    const engine = this.ensureInitialized();
+    engine.clearResolvedComponents();
+  }
+
+  /**
+   * Clear the engine tree.
+   */
+  clearTree(): void {
+    const engine = this.ensureInitialized();
+    engine.clearTree();
+  }
+
+  /**
+   * Full reset: clears tree, module, component registry, dependencies,
+   * and revision. Render callback and component resolver are preserved.
+   */
+  reset(): void {
+    const engine = this.ensureInitialized();
+    engine.reset();
+  }
+
+  /**
+   * Debug method to inspect parsed components.
+   */
+  debugParseComponent(source: string): string {
+    const engine = this.ensureInitialized();
+    return engine.debugParseComponent(source);
+  }
+
+  // ── Data Source Context ────────────────────────────────────────
+
+  /**
+   * Set (or replace) a named data source context.
+   *
+   * Registers the provider in the dependency graph, stores the data,
+   * and re-renders every node bound to `$name.*`.
+   *
+   * @param name - Provider name (e.g., "spacetime", "firebase")
+   * @param data - Full state object for this provider
+   */
+  setContext(name: string, data: Record<string, unknown>): void {
+    const engine = this.ensureInitialized();
+    try {
+      engine.setContext(name, this.unwrapForWasm(data));
+    } catch (err) {
+      throw classifyEngineError(err);
+    }
+    log.debug(`Data source "${name}" context set`);
+  }
+
+  /**
+   * Remove a data source context entirely.
+   * Drops the provider's state and re-renders bound nodes (they resolve to null).
+   */
+  removeContext(name: string): void {
+    const engine = this.ensureInitialized();
+    engine.removeContext(name);
+  }
+
+  // ── Resource System ─────────────────────────────────────────────────
+
+  /**
+   * Register resources (name → raw SVG string) with the engine.
+   *
+   * Each SVG is parsed by the WASM engine. When the engine encounters
+   * `Icon(@resources.heart)` in the DSL, it resolves the name from registered
+   * resources and injects SVG path data into the Create patch props.
+   *
+   * @param map - Flat map of resource name to raw SVG string
+   */
+  registerResources(map: Record<string, string>): void {
+    const engine = this.ensureInitialized();
+    engine.registerResources(map);
+    log.debug(`Resources registered (${Object.keys(map).length} entries)`);
+  }
+}