@hypen-space/core 0.4.46 → 0.4.81

package/dist/engine-base.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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 type { Action, RenderCallback, ActionHandler, ComponentResolver } from "./types.js";
+/**
+ * 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 declare abstract class BaseEngine {
+    protected wasmEngine: any;
+    protected initialized: boolean;
+    /**
+     * 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;
+    /**
+     * Set the render callback that receives patches.
+     */
+    setRenderCallback(callback: RenderCallback): void;
+    /**
+     * Set the component resolver for dynamic component composition.
+     */
+    setComponentResolver(resolver: ComponentResolver): void;
+    /**
+     * Parse and render Hypen DSL source code.
+     * @throws {ParseError} if the source fails to parse
+     * @throws {RenderError} if rendering fails
+     */
+    renderSource(source: string): void;
+    /**
+     * Render a lazy component (for lazy route loading).
+     */
+    renderLazyComponent(source: string): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Dispatch an action.
+     * @throws {HypenError} if the action dispatch fails
+     */
+    dispatchAction(name: string, payload?: any): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Initialize the primary module.
+     */
+    setModule(name: string, actions: string[], stateKeys: string[], initialState: Record<string, any>): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Clear the engine tree.
+     */
+    clearTree(): void;
+    /**
+     * Full reset: clears tree, module, component registry, dependencies,
+     * and revision. Render callback and component resolver are preserved.
+     */
+    reset(): void;
+    /**
+     * Debug method to inspect parsed components.
+     */
+    debugParseComponent(source: string): string;
+    /**
+     * 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;
+    /**
+     * Remove a data source context entirely.
+     * Drops the provider's state and re-renders bound nodes (they resolve to null).
+     */
+    removeContext(name: string): void;
+    /**
+     * 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;
+}