@constela/runtime 0.15.2 → 0.16.1

package/dist/index.d.ts

@@ -50,8 +50,11 @@ interface StateStore {
     getPath(name: string, path: string | (string | number)[]): unknown;
     setPath(name: string, path: string | (string | number)[], value: unknown): void;
     subscribeToPath(name: string, path: string | (string | number)[], fn: (value: unknown) => void): () => void;
+    serialize(): Record<string, unknown>;
+    restore(snapshot: Record<string, unknown>, newDefinitions: StateDefinition[]): void;
 }
 interface StateDefinition {
+    name?: string;
     type: string;
     initial: unknown;
 }
@@ -316,6 +319,11 @@ interface RenderContext {
         store: LocalStateStore;
         actions: Record<string, CompiledLocalAction>;
     };
+    route?: {
+        params: Record<string, string>;
+        query: Record<string, string>;
+        path: string;
+    };
 }
 declare function render(node: CompiledNode, ctx: RenderContext): Node;
 
@@ -385,4 +393,194 @@ interface HydrateOptions {
  */
 declare function hydrateApp(options: HydrateOptions): AppInstance;
 
-export { type ActionContext, type AppInstance, type Computed, type ConnectionManager, type EvaluationContext, type HydrateOptions, type RenderContext, type Signal, type StateStore, type StylePreset, type TypedStateStore, type WebSocketConnection, type WebSocketHandlers, createApp, createComputed, createConnectionManager, createEffect, createSignal, createStateStore, createTypedStateStore, createWebSocketConnection, evaluate, evaluateStyle, executeAction, hydrateApp, render };
+/**
+ * HMR Client - WebSocket client for Hot Module Replacement
+ *
+ * This module provides a client-side WebSocket connection for receiving
+ * HMR updates from the development server.
+ *
+ * WebSocket Protocol:
+ * - Server -> Client: 'connected' on connection
+ * - Server -> Client: 'update' when file changes (file: string, program: CompiledProgram)
+ * - Server -> Client: 'error' when compilation fails (file: string, errors: unknown[])
+ */
+
+/**
+ * Options for creating an HMR client
+ */
+interface HMRClientOptions {
+    /** WebSocket server URL (e.g., 'ws://localhost:3001') */
+    url: string;
+    /** Called when a file update is received */
+    onUpdate: (file: string, program: CompiledProgram) => void;
+    /** Called when a compilation error is received */
+    onError: (file: string, errors: unknown[]) => void;
+    /** Called when connection is established */
+    onConnect?: () => void;
+    /** Called when connection is lost */
+    onDisconnect?: () => void;
+    /** Initial reconnect delay in milliseconds (default: 1000) */
+    initialReconnectDelay?: number;
+    /** Maximum reconnect delay in milliseconds (default: 30000) */
+    maxReconnectDelay?: number;
+}
+/**
+ * HMR Client interface
+ */
+interface HMRClient {
+    /** Establish WebSocket connection */
+    connect(): void;
+    /** Close WebSocket connection */
+    disconnect(): void;
+    /** Check if currently connected */
+    isConnected(): boolean;
+}
+/**
+ * Creates an HMR client for receiving hot updates from the development server.
+ *
+ * Features:
+ * - WebSocket connection management
+ * - JSON message parsing
+ * - Auto-reconnect with exponential backoff
+ * - Connection state tracking
+ *
+ * @param options - Client configuration options
+ * @returns HMRClient interface for managing the connection
+ */
+declare function createHMRClient(options: HMRClientOptions): HMRClient;
+
+/**
+ * HMR Handler - Update handler for Hot Module Replacement
+ *
+ * This module handles applying HMR updates to the running application,
+ * preserving state across updates.
+ *
+ * Update Flow:
+ * 1. Serialize current state: state.serialize()
+ * 2. Destroy old app: app.destroy()
+ * 3. Render new app with new program
+ * 4. Restore state: state.restore(snapshot, newDefinitions)
+ */
+
+/**
+ * Route context for the application
+ */
+interface RouteContext {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    path: string;
+}
+/**
+ * Options for creating an HMR handler
+ */
+interface HMRHandlerOptions {
+    /** Container element for the application */
+    container: HTMLElement;
+    /** Initial compiled program */
+    program: CompiledProgram;
+    /** Optional route context */
+    route?: RouteContext;
+}
+/**
+ * HMR Handler interface
+ */
+interface HMRHandler {
+    /** Apply a program update while preserving state */
+    handleUpdate(program: CompiledProgram): void;
+    /** Destroy the handler and cleanup resources */
+    destroy(): void;
+}
+/**
+ * Creates an HMR handler for applying hot updates to the running application.
+ *
+ * Update Flow:
+ * 1. Serialize current state: state.serialize()
+ * 2. Destroy old app: app.destroy()
+ * 3. Create new state store from new program
+ * 4. Restore state: state.restore(snapshot, newDefinitions)
+ * 5. Render new app with restored state
+ *
+ * @param options - Handler configuration options
+ * @returns HMRHandler interface for managing updates
+ */
+declare function createHMRHandler(options: HMRHandlerOptions): HMRHandler;
+
+/**
+ * HMR Error Overlay - Display compilation errors during development
+ *
+ * This module provides an error overlay UI that displays compilation errors
+ * as an overlay on the DOM, helping developers quickly identify and fix issues.
+ *
+ * Features:
+ * - Display file path and error details
+ * - Show error code and suggestions
+ * - Auto-hide when error is fixed
+ * - Styled overlay with dark background and high z-index
+ *
+ * Usage:
+ * ```typescript
+ * const overlay = createErrorOverlay();
+ *
+ * // Show error
+ * overlay.show({
+ *   file: '/src/pages/index.json',
+ *   errors: [{ code: 'PARSE_ERROR', message: 'Unexpected token' }]
+ * });
+ *
+ * // Hide when fixed
+ * overlay.hide();
+ * ```
+ */
+/**
+ * Error information to display in the overlay
+ */
+interface ErrorInfo {
+    /** File path where the error occurred */
+    file: string;
+    /** Array of error details */
+    errors: Array<{
+        /** Error code (e.g., 'PARSE_ERROR', 'UNDEFINED_STATE') */
+        code?: string;
+        /** Human-readable error message */
+        message: string;
+        /** Path to the problematic element in the JSON (e.g., 'view.children[0].value') */
+        path?: string;
+        /** Error severity ('error' | 'warning') */
+        severity?: string;
+        /** Suggestion for fixing the error */
+        suggestion?: string;
+    }>;
+}
+/**
+ * Error overlay interface for displaying and hiding compilation errors
+ */
+interface ErrorOverlay {
+    /**
+     * Show the error overlay with the given error information
+     * @param errorInfo - Error details to display
+     */
+    show(errorInfo: ErrorInfo): void;
+    /**
+     * Hide the error overlay and remove it from the DOM
+     */
+    hide(): void;
+    /**
+     * Check if the overlay is currently visible
+     * @returns true if the overlay is visible, false otherwise
+     */
+    isVisible(): boolean;
+}
+/**
+ * Creates an error overlay instance for displaying compilation errors.
+ *
+ * The overlay is rendered as a full-screen element with:
+ * - Dark semi-transparent background
+ * - White text for readability
+ * - High z-index to appear above all other content
+ * - File path and error details prominently displayed
+ *
+ * @returns ErrorOverlay interface for managing the overlay
+ */
+declare function createErrorOverlay(): ErrorOverlay;
+
+export { type ActionContext, type AppInstance, type Computed, type ConnectionManager, type ErrorInfo, type ErrorOverlay, type EvaluationContext, type HMRClient, type HMRClientOptions, type HMRHandler, type HMRHandlerOptions, type HydrateOptions, type RenderContext, type RouteContext, type Signal, type StateStore, type StylePreset, type TypedStateStore, type WebSocketConnection, type WebSocketHandlers, createApp, createComputed, createConnectionManager, createEffect, createErrorOverlay, createHMRClient, createHMRHandler, createSignal, createStateStore, createTypedStateStore, createWebSocketConnection, evaluate, evaluateStyle, executeAction, hydrateApp, render };

package/dist/index.js

@@ -319,9 +319,54 @@ function createStateStore(definitions) {
           fn(newValue);
         }
       });
+    },
+    serialize() {
+      const result = {};
+      for (const [name, signal] of signals) {
+        const value = signal.get();
+        if (typeof value !== "function") {
+          result[name] = value;
+        }
+      }
+      return result;
+    },
+    restore(snapshot, newDefinitions) {
+      for (const def of newDefinitions) {
+        const name = def.name;
+        if (!name) continue;
+        const signal = signals.get(name);
+        if (!signal) continue;
+        if (!(name in snapshot)) {
+          continue;
+        }
+        const snapshotValue = snapshot[name];
+        const initialValue = def.initial;
+        if (typesMatch(snapshotValue, initialValue)) {
+          signal.set(snapshotValue);
+        } else {
+          console.warn(
+            `State field "${name}" type changed. Using new initial value.`
+          );
+          signal.set(initialValue);
+        }
+      }
     }
   };
 }
+function typesMatch(a, b2) {
+  if (a === null) {
+    return b2 === null || typeof b2 === "object" && !Array.isArray(b2);
+  }
+  if (b2 === null) {
+    return typeof a === "object" && !Array.isArray(a);
+  }
+  const aIsArray = Array.isArray(a);
+  const bIsArray = Array.isArray(b2);
+  if (aIsArray || bIsArray) {
+    return aIsArray && bIsArray;
+  }
+  return typeof a === typeof b2;
+}
 
 // src/state/typed.ts
 function createTypedStateStore(definitions) {
@@ -13674,7 +13719,7 @@ function renderElement(node, ctx) {
         }
       } else {
         const cleanup = createEffect(() => {
-          const value = evaluate(propValue, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
+          const value = evaluate(propValue, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } });
           applyProp(el, propName, value, useSvgNamespace);
         });
         ctx.cleanups?.push(cleanup);
@@ -13729,7 +13774,7 @@ function applyProp(el, propName, value, isSvg = false) {
 function renderText(node, ctx) {
   const textNode = document.createTextNode("");
   const cleanup = createEffect(() => {
-    const value = evaluate(node.value, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
+    const value = evaluate(node.value, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } });
     textNode.textContent = formatValue(value);
   });
   ctx.cleanups?.push(cleanup);
@@ -13750,7 +13795,7 @@ function renderIf(node, ctx) {
   let currentBranch = "none";
   let branchCleanups = [];
   const effectCleanup = createEffect(() => {
-    const condition = evaluate(node.condition, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
+    const condition = evaluate(node.condition, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } });
     const shouldShowThen = Boolean(condition);
     const newBranch = shouldShowThen ? "then" : node.else ? "else" : "none";
     if (newBranch !== currentBranch) {
@@ -13828,7 +13873,7 @@ function renderEach(node, ctx) {
   let currentNodes = [];
   let itemCleanups = [];
   const effectCleanup = createEffect(() => {
-    const items = evaluate(node.items, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
+    const items = evaluate(node.items, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } });
     if (!hasKey || !node.key) {
       for (const cleanup of itemCleanups) {
         cleanup();
@@ -13977,7 +14022,7 @@ function renderMarkdown(node, ctx) {
   const container = document.createElement("div");
   container.className = "constela-markdown";
   const cleanup = createEffect(() => {
-    const content = evaluate(node.content, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
+    const content = evaluate(node.content, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } });
     const html6 = parseMarkdown(String(content ?? ""));
     container.innerHTML = html6;
   });
@@ -13992,8 +14037,8 @@ function renderCode(node, ctx) {
   container.appendChild(pre);
   pre.appendChild(codeEl);
   const cleanup = createEffect(() => {
-    const language = String(evaluate(node.language, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } }) ?? "plaintext");
-    const content = String(evaluate(node.content, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } }) ?? "");
+    const language = String(evaluate(node.language, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } }) ?? "plaintext");
+    const content = String(evaluate(node.content, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports }, ...ctx.route && { route: ctx.route } }) ?? "");
     codeEl.className = `language-${language || "plaintext"}`;
     codeEl.dataset["language"] = language || "plaintext";
     container.dataset["language"] = language || "plaintext";
@@ -14113,6 +14158,12 @@ function createStateWithLocalState(globalState, localStore) {
     },
     subscribeToPath(name, path, fn) {
       return globalState.subscribeToPath(name, path, fn);
+    },
+    serialize() {
+      return globalState.serialize();
+    },
+    restore(snapshot, newDefinitions) {
+      globalState.restore(snapshot, newDefinitions);
     }
   };
 }
@@ -15071,11 +15122,304 @@ function createConnectionManager() {
     }
   };
 }
+
+// src/hmr/client.ts
+var DEFAULT_INITIAL_RECONNECT_DELAY = 1e3;
+var DEFAULT_MAX_RECONNECT_DELAY = 3e4;
+function createHMRClient(options) {
+  const {
+    url,
+    onUpdate,
+    onError,
+    onConnect,
+    onDisconnect,
+    initialReconnectDelay = DEFAULT_INITIAL_RECONNECT_DELAY,
+    maxReconnectDelay = DEFAULT_MAX_RECONNECT_DELAY
+  } = options;
+  let ws = null;
+  let isManualDisconnect = false;
+  let reconnectDelay = initialReconnectDelay;
+  let reconnectTimeoutId = null;
+  function handleMessage(event) {
+    try {
+      const message = JSON.parse(event.data);
+      switch (message.type) {
+        case "connected":
+          break;
+        case "update":
+          if (message.file && message.program) {
+            onUpdate(message.file, message.program);
+          }
+          break;
+        case "error":
+          if (message.file && message.errors) {
+            onError(message.file, message.errors);
+          }
+          break;
+        default:
+          break;
+      }
+    } catch {
+    }
+  }
+  function handleOpen() {
+    reconnectDelay = initialReconnectDelay;
+    onConnect?.();
+  }
+  function handleClose() {
+    onDisconnect?.();
+    if (!isManualDisconnect) {
+      scheduleReconnect();
+    }
+  }
+  function handleError() {
+  }
+  function scheduleReconnect() {
+    if (reconnectTimeoutId !== null) {
+      return;
+    }
+    reconnectTimeoutId = setTimeout(() => {
+      reconnectTimeoutId = null;
+      if (!isManualDisconnect) {
+        ws = null;
+        createConnection();
+        reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
+      }
+    }, reconnectDelay);
+  }
+  function createConnection() {
+    ws = new WebSocket(url);
+    ws.onopen = handleOpen;
+    ws.onclose = handleClose;
+    ws.onerror = handleError;
+    ws.onmessage = handleMessage;
+  }
+  return {
+    connect() {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        return;
+      }
+      isManualDisconnect = false;
+      if (reconnectTimeoutId !== null) {
+        clearTimeout(reconnectTimeoutId);
+        reconnectTimeoutId = null;
+      }
+      createConnection();
+    },
+    disconnect() {
+      isManualDisconnect = true;
+      if (reconnectTimeoutId !== null) {
+        clearTimeout(reconnectTimeoutId);
+        reconnectTimeoutId = null;
+      }
+      if (ws) {
+        ws.close();
+        ws = null;
+      }
+    },
+    isConnected() {
+      return ws !== null && ws.readyState === WebSocket.OPEN;
+    }
+  };
+}
+
+// src/hmr/handler.ts
+function createHMRApp(program, container, route, existingStateStore) {
+  const state = existingStateStore ?? createStateStore(program.state);
+  let actions;
+  if (program.actions instanceof Map) {
+    actions = {};
+    program.actions.forEach((action, name) => {
+      actions[name] = action;
+    });
+  } else {
+    actions = program.actions;
+  }
+  const cleanups = [];
+  const refs = {};
+  const ctx = {
+    state,
+    actions,
+    locals: {},
+    cleanups,
+    refs,
+    ...route && { route },
+    ...program.importData && { imports: program.importData }
+  };
+  const rootNode = render(program.view, ctx);
+  container.appendChild(rootNode);
+  const actionCtx = {
+    state,
+    actions,
+    locals: {},
+    refs,
+    ...route && { route },
+    ...program.importData && { imports: program.importData }
+  };
+  if (program.lifecycle?.onMount) {
+    const onMountAction = actions[program.lifecycle.onMount];
+    if (onMountAction) {
+      void executeAction(onMountAction, actionCtx);
+    }
+  }
+  let destroyed = false;
+  return {
+    stateStore: state,
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      if (program.lifecycle?.onUnmount) {
+        const onUnmountAction = actions[program.lifecycle.onUnmount];
+        if (onUnmountAction) {
+          void executeAction(onUnmountAction, actionCtx);
+        }
+      }
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+      while (container.firstChild) {
+        container.removeChild(container.firstChild);
+      }
+    },
+    setState(name, value) {
+      if (destroyed) return;
+      state.set(name, value);
+    },
+    getState(name) {
+      return state.get(name);
+    },
+    subscribe(name, fn) {
+      if (destroyed) return () => {
+      };
+      return state.subscribe(name, fn);
+    }
+  };
+}
+function createHMRHandler(options) {
+  const { container, program, route } = options;
+  let currentApp = null;
+  let destroyed = false;
+  currentApp = createHMRApp(program, container, route);
+  return {
+    handleUpdate(newProgram) {
+      if (destroyed) {
+        return;
+      }
+      let stateSnapshot = {};
+      if (currentApp) {
+        stateSnapshot = currentApp.stateStore.serialize();
+        currentApp.destroy();
+        currentApp = null;
+      }
+      const newStateStore = createStateStore(newProgram.state);
+      const newDefinitions = Object.entries(newProgram.state).map(
+        ([name, def]) => ({
+          name,
+          ...def
+        })
+      );
+      newStateStore.restore(stateSnapshot, newDefinitions);
+      currentApp = createHMRApp(newProgram, container, route, newStateStore);
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      if (currentApp) {
+        currentApp.destroy();
+        currentApp = null;
+      }
+    }
+  };
+}
+
+// src/utils/escape.ts
+function escapeHtml(text3) {
+  const div = document.createElement("div");
+  div.textContent = text3;
+  return div.innerHTML;
+}
+
+// src/hmr/overlay.ts
+var OVERLAY_ATTRIBUTE = "data-constela-error-overlay";
+function createOverlayElement() {
+  const element2 = document.createElement("div");
+  element2.setAttribute(OVERLAY_ATTRIBUTE, "");
+  Object.assign(element2.style, {
+    position: "fixed",
+    top: "0",
+    left: "0",
+    right: "0",
+    bottom: "0",
+    width: "100%",
+    height: "100%",
+    backgroundColor: "rgba(0, 0, 0, 0.9)",
+    color: "#ffffff",
+    zIndex: "9999",
+    overflow: "auto",
+    padding: "24px",
+    boxSizing: "border-box",
+    fontFamily: "monospace",
+    fontSize: "14px",
+    lineHeight: "1.5"
+  });
+  return element2;
+}
+function renderErrorContent(errorInfo) {
+  const errorItems = errorInfo.errors.map((error) => {
+    const parts = [];
+    if (error.code) {
+      parts.push(`<span style="color: #ff6b6b; font-weight: bold;">${escapeHtml(error.code)}</span>`);
+    }
+    parts.push(`<div style="margin-top: 4px;">${escapeHtml(error.message)}</div>`);
+    if (error.path) {
+      parts.push(`<div style="color: #888; margin-top: 4px;">at ${escapeHtml(error.path)}</div>`);
+    }
+    if (error.suggestion) {
+      parts.push(`<div style="color: #4ecdc4; margin-top: 8px;">${escapeHtml(error.suggestion)}</div>`);
+    }
+    return `<div style="background: rgba(255, 255, 255, 0.05); padding: 16px; border-radius: 4px; margin-bottom: 12px;">${parts.join("")}</div>`;
+  }).join("");
+  return `
+    <div style="margin-bottom: 24px;">
+      <div style="color: #ff6b6b; font-size: 18px; font-weight: bold; margin-bottom: 8px;">Compilation Error</div>
+      <div style="color: #aaa; word-break: break-all;">${escapeHtml(errorInfo.file)}</div>
+    </div>
+    <div>${errorItems}</div>
+  `;
+}
+function createErrorOverlay() {
+  let overlayElement = null;
+  return {
+    show(errorInfo) {
+      if (overlayElement && document.body.contains(overlayElement)) {
+        overlayElement.innerHTML = renderErrorContent(errorInfo);
+        return;
+      }
+      overlayElement = createOverlayElement();
+      overlayElement.innerHTML = renderErrorContent(errorInfo);
+      document.body.appendChild(overlayElement);
+    },
+    hide() {
+      if (overlayElement && document.body.contains(overlayElement)) {
+        document.body.removeChild(overlayElement);
+      }
+      overlayElement = null;
+    },
+    isVisible() {
+      return overlayElement !== null && document.body.contains(overlayElement);
+    }
+  };
+}
 export {
   createApp,
   createComputed,
   createConnectionManager,
   createEffect,
+  createErrorOverlay,
+  createHMRClient,
+  createHMRHandler,
   createSignal,
   createStateStore,
   createTypedStateStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "description": "Runtime DOM renderer for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,8 +18,8 @@
     "dompurify": "^3.3.1",
     "marked": "^17.0.1",
     "shiki": "^3.20.0",
-    "@constela/compiler": "0.11.1",
-    "@constela/core": "0.12.0"
+    "@constela/compiler": "0.11.2",
+    "@constela/core": "0.12.1"
   },
   "devDependencies": {
     "@types/dompurify": "^3.2.0",