@constela/runtime 0.11.1 → 0.12.1

package/README.md

@@ -40,6 +40,81 @@ Becomes an interactive app with:
 
 ## Features
 
+### Fine-grained State Updates (setPath)
+
+Update nested values without replacing entire arrays:
+
+```json
+{
+  "do": "setPath",
+  "target": "posts",
+  "path": [5, "liked"],
+  "value": { "expr": "lit", "value": true }
+}
+```
+
+Dynamic path with variables:
+
+```json
+{
+  "do": "setPath",
+  "target": "posts",
+  "path": { "expr": "var", "name": "payload", "path": "index" },
+  "field": "liked",
+  "value": { "expr": "lit", "value": true }
+}
+```
+
+### Key-based List Diffing
+
+Efficient list updates - only changed items re-render:
+
+```json
+{
+  "kind": "each",
+  "items": { "expr": "state", "name": "posts" },
+  "as": "post",
+  "key": { "expr": "var", "name": "post", "path": "id" },
+  "body": { ... }
+}
+```
+
+Benefits:
+- Add/remove items: Only affected DOM nodes change
+- Reorder: DOM nodes move without recreation
+- Update item: Only that item re-renders
+- Input state preserved during updates
+
+### WebSocket Connections
+
+Real-time data with declarative WebSocket:
+
+```json
+{
+  "connections": {
+    "chat": {
+      "type": "websocket",
+      "url": "wss://api.example.com/ws",
+      "onMessage": { "action": "handleMessage" },
+      "onOpen": { "action": "connectionOpened" },
+      "onClose": { "action": "connectionClosed" }
+    }
+  }
+}
+```
+
+Send messages:
+
+```json
+{ "do": "send", "connection": "chat", "data": { "expr": "state", "name": "inputText" } }
+```
+
+Close connection:
+
+```json
+{ "do": "close", "connection": "chat" }
+```
+
 ### Markdown Rendering
 
 ```json
@@ -148,17 +223,43 @@ interface AppInstance {
 ### Reactive Primitives
 
 ```typescript
-import { createSignal, createEffect } from '@constela/runtime';
+import { createSignal, createEffect, createComputed } from '@constela/runtime';
 
 const count = createSignal(0);
 count.get();  // Read
 count.set(1); // Write
 
+// Computed values with automatic dependency tracking
+const doubled = createComputed(() => count.get() * 2);
+doubled.get(); // Returns memoized value
+
 const cleanup = createEffect(() => {
   console.log(`Count: ${count.get()}`);
 });
 ```
 
+### TypedStateStore (TypeScript)
+
+Type-safe state access for TypeScript developers:
+
+```typescript
+import { createTypedStateStore } from '@constela/runtime';
+
+interface AppState {
+  posts: { id: number; liked: boolean }[];
+  filter: string;
+}
+
+const state = createTypedStateStore<AppState>({
+  posts: { type: 'list', initial: [] },
+  filter: { type: 'string', initial: '' },
+});
+
+state.get('posts');  // Type: { id: number; liked: boolean }[]
+state.set('filter', 'recent'); // OK
+state.set('filter', 123);      // TypeScript error
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -17,6 +17,26 @@ type CleanupFn = () => void;
 type EffectFn = () => void | CleanupFn;
 declare function createEffect(fn: EffectFn): () => void;
 
+/**
+ * Computed - Derived reactive value
+ *
+ * A Computed holds a derived value that is automatically recalculated
+ * when its dependencies change. It tracks Signal dependencies and
+ * memoizes results for efficiency.
+ */
+interface Computed<T> {
+    get(): T;
+    subscribe?(fn: (value: T) => void): () => void;
+}
+/**
+ * Creates a computed value that automatically tracks dependencies
+ * and memoizes results.
+ *
+ * @param getter - Function that computes the derived value
+ * @returns Computed object with get() and subscribe() methods
+ */
+declare function createComputed<T>(getter: () => T): Computed<T>;
+
 /**
  * StateStore - Centralized state management
  *
@@ -27,13 +47,62 @@ interface StateStore {
     get(name: string): unknown;
     set(name: string, value: unknown): void;
     subscribe(name: string, fn: (value: unknown) => void): () => void;
+    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;
 }
 interface StateDefinition {
     type: string;
     initial: unknown;
 }
+/**
+ * TypedStateStore - Generic interface for type-safe state access
+ *
+ * Usage:
+ * interface AppState {
+ *   items: { id: number; liked: boolean }[];
+ *   filter: string;
+ * }
+ * const state = createStateStore(definitions) as TypedStateStore<AppState>;
+ * state.get('items'); // returns { id: number; liked: boolean }[]
+ */
+interface TypedStateStore<T extends Record<string, unknown>> extends StateStore {
+    get<K extends keyof T>(name: K): T[K];
+    set<K extends keyof T>(name: K, value: T[K]): void;
+    subscribe<K extends keyof T>(name: K, fn: (value: T[K]) => void): () => void;
+    getPath<K extends keyof T>(name: K, path: string | (string | number)[]): unknown;
+    setPath<K extends keyof T>(name: K, path: string | (string | number)[], value: unknown): void;
+    subscribeToPath<K extends keyof T>(name: K, path: string | (string | number)[], fn: (value: unknown) => void): () => void;
+}
 declare function createStateStore(definitions: Record<string, StateDefinition>): StateStore;
 
+/**
+ * Typed State Store - Helper for creating type-safe state stores
+ */
+
+/**
+ * Creates a type-safe state store with inferred types
+ *
+ * @example
+ * interface AppState {
+ *   items: { id: number; liked: boolean }[];
+ *   filter: string;
+ *   count: number;
+ * }
+ *
+ * const state = createTypedStateStore<AppState>({
+ *   items: { type: 'list', initial: [] },
+ *   filter: { type: 'string', initial: '' },
+ *   count: { type: 'number', initial: 0 },
+ * });
+ *
+ * state.get('items'); // correctly typed as { id: number; liked: boolean }[]
+ * state.set('count', 10); // type-checked
+ */
+declare function createTypedStateStore<T extends Record<string, unknown>>(definitions: {
+    [K in keyof T]: StateDefinition;
+}): TypedStateStore<T>;
+
 /**
  * Expression Evaluator - Evaluates compiled expressions
  *
@@ -88,6 +157,91 @@ interface StyleExprInput {
  */
 declare function evaluateStyle(expr: StyleExprInput, ctx: EvaluationContext): string | undefined;
 
+/**
+ * WebSocket Connection Module - Interface Stubs for TDD
+ *
+ * This file provides the interface definitions and stub implementations
+ * for WebSocket connection management in Constela runtime.
+ *
+ * TDD Red Phase: These stubs will fail tests until properly implemented.
+ */
+/**
+ * WebSocket connection interface for sending/receiving data
+ */
+interface WebSocketConnection {
+    /**
+     * Send data through the WebSocket connection
+     * Objects and arrays are JSON stringified
+     * @param data - The data to send
+     */
+    send(data: unknown): void;
+    /**
+     * Close the WebSocket connection
+     */
+    close(): void;
+    /**
+     * Get the current connection state
+     * @returns The connection state
+     */
+    getState(): 'connecting' | 'open' | 'closing' | 'closed';
+}
+/**
+ * Event handlers for WebSocket connection events
+ */
+interface WebSocketHandlers {
+    /** Called when connection is established */
+    onOpen?: () => Promise<void> | void;
+    /** Called when connection is closed */
+    onClose?: (code: number, reason: string) => Promise<void> | void;
+    /** Called when an error occurs */
+    onError?: (error: Event) => Promise<void> | void;
+    /** Called when a message is received (JSON parsed if possible) */
+    onMessage?: (data: unknown) => Promise<void> | void;
+}
+/**
+ * Connection manager for named WebSocket connections
+ */
+interface ConnectionManager {
+    /**
+     * Create a new named WebSocket connection
+     * If a connection with the same name exists, it will be closed first
+     */
+    create(name: string, url: string, handlers: WebSocketHandlers): void;
+    /**
+     * Get a connection by name
+     * @returns The connection or undefined if not found
+     */
+    get(name: string): WebSocketConnection | undefined;
+    /**
+     * Send data to a named connection
+     * @throws Error if connection not found
+     */
+    send(name: string, data: unknown): void;
+    /**
+     * Close a named connection
+     * No-op if connection not found
+     */
+    close(name: string): void;
+    /**
+     * Close all connections
+     */
+    closeAll(): void;
+}
+/**
+ * Create a WebSocket connection with event handlers
+ *
+ * @param url - The WebSocket URL (e.g., "wss://api.example.com/ws")
+ * @param handlers - Event handlers for connection lifecycle
+ * @returns A WebSocketConnection interface for sending/closing
+ */
+declare function createWebSocketConnection(url: string, handlers: WebSocketHandlers): WebSocketConnection;
+/**
+ * Create a connection manager for managing multiple named connections
+ *
+ * @returns A ConnectionManager interface
+ */
+declare function createConnectionManager(): ConnectionManager;
+
 /**
  * Action Executor - Executes compiled action steps
  *
@@ -113,6 +267,7 @@ interface ActionContext {
         path: string;
     };
     imports?: Record<string, unknown>;
+    connections?: ConnectionManager;
 }
 declare function executeAction(action: CompiledAction, ctx: ActionContext): Promise<void>;
 
@@ -203,4 +358,4 @@ interface HydrateOptions {
  */
 declare function hydrateApp(options: HydrateOptions): AppInstance;
 
-export { type ActionContext, type AppInstance, type EvaluationContext, type HydrateOptions, type RenderContext, type Signal, type StateStore, type StylePreset, createApp, createEffect, createSignal, createStateStore, evaluate, evaluateStyle, executeAction, hydrateApp, render };
+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 };

package/dist/index.js

@@ -9,6 +9,9 @@ var effectDependencies = /* @__PURE__ */ new Map();
 function setCurrentEffect(effect) {
   currentEffect = effect;
 }
+function getCurrentEffect() {
+  return currentEffect;
+}
 function registerEffectCleanup(effect) {
   if (!effectDependencies.has(effect)) {
     effectDependencies.set(effect, /* @__PURE__ */ new Set());
@@ -95,7 +98,121 @@ function createEffect(fn) {
   };
 }
 
+// src/reactive/computed.ts
+function createComputed(getter) {
+  let cachedValue;
+  let isDirty = true;
+  let isComputing = false;
+  let hasValue = false;
+  const subscribers = /* @__PURE__ */ new Set();
+  const effectSubscribers = /* @__PURE__ */ new Set();
+  const markDirty = () => {
+    if (!isDirty) {
+      isDirty = true;
+      const effects = [...effectSubscribers];
+      effects.forEach((effect) => effect());
+      if (subscribers.size > 0 && hasValue) {
+        const oldValue = cachedValue;
+        try {
+          compute();
+          if (!Object.is(cachedValue, oldValue)) {
+            notifySubscribers();
+          }
+        } catch {
+        }
+      }
+    }
+  };
+  const compute = () => {
+    if (isComputing) {
+      throw new Error("Circular dependency detected in computed");
+    }
+    cleanupEffect(markDirty);
+    isComputing = true;
+    const previousEffect = getCurrentEffect();
+    registerEffectCleanup(markDirty);
+    setCurrentEffect(markDirty);
+    try {
+      cachedValue = getter();
+      isDirty = false;
+      hasValue = true;
+    } finally {
+      isComputing = false;
+      setCurrentEffect(previousEffect);
+    }
+  };
+  const notifySubscribers = () => {
+    subscribers.forEach((fn) => {
+      try {
+        fn(cachedValue);
+      } catch (e) {
+        console.error("Error in computed subscriber:", e);
+      }
+    });
+  };
+  return {
+    get() {
+      if (isDirty) {
+        compute();
+      }
+      const currentEff = getCurrentEffect();
+      if (currentEff && currentEff !== markDirty) {
+        effectSubscribers.add(currentEff);
+      }
+      return cachedValue;
+    },
+    subscribe(fn) {
+      if (isDirty) {
+        try {
+          compute();
+        } catch {
+        }
+      }
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    }
+  };
+}
+
 // src/state/store.ts
+function normalizePath(path) {
+  if (typeof path === "string") {
+    return path.split(".").map((segment) => {
+      const num = parseInt(segment, 10);
+      return isNaN(num) ? segment : num;
+    });
+  }
+  return path;
+}
+function getValueAtPath(obj, path) {
+  let current = obj;
+  for (const key2 of path) {
+    if (current == null) return void 0;
+    current = current[key2];
+  }
+  return current;
+}
+function setValueAtPath(obj, path, value) {
+  if (path.length === 0) return value;
+  const head2 = path[0];
+  const rest = path.slice(1);
+  const isArrayIndex = typeof head2 === "number";
+  let clone3;
+  if (isArrayIndex) {
+    clone3 = Array.isArray(obj) ? [...obj] : [];
+  } else {
+    clone3 = obj != null && typeof obj === "object" ? { ...obj } : {};
+  }
+  const objRecord = obj;
+  clone3[head2] = setValueAtPath(
+    objRecord?.[head2],
+    rest,
+    value
+  );
+  return clone3;
+}
 function createStateStore(definitions) {
   const signals = /* @__PURE__ */ new Map();
   for (const [name, def] of Object.entries(definitions)) {
@@ -136,10 +253,48 @@ function createStateStore(definitions) {
         throw new Error(`State field "${name}" does not exist`);
       }
       return signal.subscribe(fn);
+    },
+    getPath(name, path) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      const normalizedPath = normalizePath(path);
+      return getValueAtPath(signal.get(), normalizedPath);
+    },
+    setPath(name, path, value) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      const normalizedPath = normalizePath(path);
+      const currentState = signal.get();
+      const newState = setValueAtPath(currentState, normalizedPath, value);
+      signal.set(newState);
+    },
+    subscribeToPath(name, path, fn) {
+      const signal = signals.get(name);
+      if (!signal) {
+        throw new Error(`State field "${name}" does not exist`);
+      }
+      const normalizedPath = normalizePath(path);
+      let previousValue = getValueAtPath(signal.get(), normalizedPath);
+      return signal.subscribe((newFieldValue) => {
+        const newValue = getValueAtPath(newFieldValue, normalizedPath);
+        if (newValue !== previousValue) {
+          previousValue = newValue;
+          fn(newValue);
+        }
+      });
     }
   };
 }
 
+// src/state/typed.ts
+function createTypedStateStore(definitions) {
+  return createStateStore(definitions);
+}
+
 // src/expression/evaluator.ts
 function evaluate(expr, ctx) {
   switch (expr.expr) {
@@ -267,12 +422,40 @@ function evaluate(expr, ctx) {
     }
     case "style":
       return evaluateStyle(expr, ctx);
+    case "concat": {
+      return expr.items.map((item) => {
+        const val = evaluate(item, ctx);
+        return val == null ? "" : String(val);
+      }).join("");
+    }
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);
     }
   }
 }
+function isExpression(value) {
+  return typeof value === "object" && value !== null && Object.prototype.hasOwnProperty.call(value, "expr") && typeof value.expr === "string";
+}
+function evaluatePayload(payload, ctx) {
+  if (isExpression(payload)) {
+    return evaluate(payload, ctx);
+  }
+  if (typeof payload === "object" && payload !== null) {
+    const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+    const result = {};
+    for (const [key2, value] of Object.entries(payload)) {
+      if (forbiddenKeys.has(key2)) continue;
+      if (isExpression(value)) {
+        result[key2] = evaluate(value, ctx);
+      } else {
+        result[key2] = value;
+      }
+    }
+    return result;
+  }
+  return payload;
+}
 function getNestedValue(obj, path) {
   const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
   const parts = path.split(".");
@@ -408,7 +591,7 @@ function createEvalContext(ctx) {
 }
 async function executeAction(action, ctx) {
   for (const step of action.steps) {
-    if (step.do === "set" || step.do === "update") {
+    if (step.do === "set" || step.do === "update" || step.do === "setPath") {
       executeStepSync(step, ctx);
     } else if (step.do === "if") {
       await executeIfStep(step, ctx);
@@ -425,6 +608,9 @@ function executeStepSync(step, ctx) {
     case "update":
       executeUpdateStepSync(step, ctx);
       break;
+    case "setPath":
+      executeSetPathStepSync(step, ctx);
+      break;
   }
 }
 async function executeIfStep(step, ctx) {
@@ -432,7 +618,7 @@ async function executeIfStep(step, ctx) {
   const condition = evaluate(step.condition, evalCtx);
   const stepsToExecute = condition ? step.then : step.else || [];
   for (const nestedStep of stepsToExecute) {
-    if (nestedStep.do === "set" || nestedStep.do === "update") {
+    if (nestedStep.do === "set" || nestedStep.do === "update" || nestedStep.do === "setPath") {
       executeStepSync(nestedStep, ctx);
     } else if (nestedStep.do === "if") {
       await executeIfStep(nestedStep, ctx);
@@ -532,6 +718,31 @@ function executeUpdateStepSync(step, ctx) {
     }
   }
 }
+function executeSetPathStepSync(step, ctx) {
+  const evalCtx = createEvalContext(ctx);
+  const pathValue = evaluate(step.path, evalCtx);
+  let path;
+  if (typeof pathValue === "string") {
+    path = pathValue.split(".").map((segment) => {
+      const num = parseInt(segment, 10);
+      return isNaN(num) ? segment : num;
+    });
+  } else if (Array.isArray(pathValue)) {
+    path = pathValue.map((item) => {
+      if (typeof item === "object" && item !== null && "expr" in item) {
+        return evaluate(item, evalCtx);
+      }
+      return item;
+    });
+  } else {
+    path = [pathValue];
+  }
+  const newValue = evaluate(step.value, evalCtx);
+  ctx.state.setPath(step.target, path, newValue);
+}
+async function executeSetPathStep(step, ctx) {
+  executeSetPathStepSync(step, ctx);
+}
 async function executeStep(step, ctx) {
   switch (step.do) {
     case "set":
@@ -540,6 +751,9 @@ async function executeStep(step, ctx) {
     case "update":
       await executeUpdateStep(step, ctx);
       break;
+    case "setPath":
+      await executeSetPathStep(step, ctx);
+      break;
     case "fetch":
       await executeFetchStep(step, ctx);
       break;
@@ -570,6 +784,12 @@ async function executeStep(step, ctx) {
     case "if":
       await executeIfStep(step, ctx);
       break;
+    case "send":
+      await executeSendStep(step, ctx);
+      break;
+    case "close":
+      await executeCloseStep(step, ctx);
+      break;
   }
 }
 async function executeSetStep(target, value, ctx) {
@@ -924,6 +1144,18 @@ async function executeDomStep(step, ctx) {
       break;
   }
 }
+async function executeSendStep(step, ctx) {
+  if (!ctx.connections) {
+    throw new Error(`Connection "${step.connection}" not found`);
+  }
+  const evalCtx = createEvalContext(ctx);
+  const data = evaluate(step.data, evalCtx);
+  ctx.connections.send(step.connection, data);
+}
+async function executeCloseStep(step, ctx) {
+  if (!ctx.connections) return;
+  ctx.connections.close(step.connection);
+}
 
 // ../../node_modules/.pnpm/marked@17.0.1/node_modules/marked/lib/marked.esm.js
 function L() {
@@ -12961,7 +13193,7 @@ function renderElement(node, ctx) {
             }
             let payload = void 0;
             if (handler.payload) {
-              payload = evaluate(handler.payload, {
+              payload = evaluatePayload(handler.payload, {
                 state: ctx.state,
                 locals: { ...ctx.locals, ...eventLocals },
                 ...ctx.imports && { imports: ctx.imports }
@@ -13095,52 +13327,162 @@ function renderIf(node, ctx) {
   }
   return fragment;
 }
+function createReactiveLocals(baseLocals, itemKey, itemSignal, indexKey, indexSignal) {
+  return new Proxy(baseLocals, {
+    get(target, prop) {
+      if (prop === itemKey) {
+        return itemSignal.get();
+      }
+      if (indexKey && prop === indexKey) {
+        return indexSignal.get();
+      }
+      return target[prop];
+    },
+    has(target, prop) {
+      if (prop === itemKey) return true;
+      if (indexKey && prop === indexKey) return true;
+      return prop in target;
+    }
+  });
+}
 function renderEach(node, ctx) {
   const anchor = document.createComment("each");
+  const hasKey = !!node.key;
+  let itemStateMap = /* @__PURE__ */ new Map();
   let currentNodes = [];
   let itemCleanups = [];
   const effectCleanup = createEffect(() => {
     const items = evaluate(node.items, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
-    for (const cleanup of itemCleanups) {
-      cleanup();
-    }
-    itemCleanups = [];
-    for (const oldNode of currentNodes) {
-      if (oldNode.parentNode) {
-        oldNode.parentNode.removeChild(oldNode);
+    if (!hasKey || !node.key) {
+      for (const cleanup of itemCleanups) {
+        cleanup();
+      }
+      itemCleanups = [];
+      for (const oldNode of currentNodes) {
+        if (oldNode.parentNode) {
+          oldNode.parentNode.removeChild(oldNode);
+        }
       }
+      currentNodes = [];
+      if (Array.isArray(items)) {
+        items.forEach((item, index) => {
+          const itemLocals = {
+            ...ctx.locals,
+            [node.as]: item
+          };
+          if (node.index) {
+            itemLocals[node.index] = index;
+          }
+          const localCleanups = [];
+          const itemCtx = {
+            ...ctx,
+            locals: itemLocals,
+            cleanups: localCleanups
+          };
+          const itemNode = render(node.body, itemCtx);
+          currentNodes.push(itemNode);
+          itemCleanups.push(...localCleanups);
+          if (anchor.parentNode) {
+            let refNode = anchor.nextSibling;
+            if (currentNodes.length > 1) {
+              const lastExisting = currentNodes[currentNodes.length - 2];
+              if (lastExisting) {
+                refNode = lastExisting.nextSibling;
+              }
+            }
+            anchor.parentNode.insertBefore(itemNode, refNode);
+          }
+        });
+      }
+      return;
     }
-    currentNodes = [];
+    const newItemStateMap = /* @__PURE__ */ new Map();
+    const newNodes = [];
+    const seenKeys = /* @__PURE__ */ new Set();
     if (Array.isArray(items)) {
       items.forEach((item, index) => {
-        const itemLocals = {
+        const tempLocals = {
           ...ctx.locals,
-          [node.as]: item
-        };
-        if (node.index) {
-          itemLocals[node.index] = index;
-        }
-        const localCleanups = [];
-        const itemCtx = {
-          ...ctx,
-          locals: itemLocals,
-          cleanups: localCleanups
+          [node.as]: item,
+          ...node.index ? { [node.index]: index } : {}
         };
-        const itemNode = render(node.body, itemCtx);
-        currentNodes.push(itemNode);
-        itemCleanups.push(...localCleanups);
-        if (anchor.parentNode) {
-          let refNode = anchor.nextSibling;
-          if (currentNodes.length > 1) {
-            const lastExisting = currentNodes[currentNodes.length - 2];
-            if (lastExisting) {
-              refNode = lastExisting.nextSibling;
-            }
+        const keyValue = evaluate(node.key, {
+          state: ctx.state,
+          locals: tempLocals,
+          ...ctx.imports && { imports: ctx.imports }
+        });
+        if (seenKeys.has(keyValue)) {
+          if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+            console.warn(`Duplicate key "${keyValue}" in each loop. Keys should be unique.`);
           }
-          anchor.parentNode.insertBefore(itemNode, refNode);
+        }
+        seenKeys.add(keyValue);
+        const existingState = itemStateMap.get(keyValue);
+        if (existingState) {
+          existingState.itemSignal.set(item);
+          existingState.indexSignal.set(index);
+          newItemStateMap.set(keyValue, existingState);
+          newNodes.push(existingState.node);
+        } else {
+          const itemSignal = createSignal(item);
+          const indexSignal = createSignal(index);
+          const reactiveLocals = createReactiveLocals(
+            ctx.locals,
+            node.as,
+            itemSignal,
+            node.index,
+            indexSignal
+          );
+          const localCleanups = [];
+          const itemCtx = {
+            ...ctx,
+            locals: reactiveLocals,
+            cleanups: localCleanups
+          };
+          const itemNode = render(node.body, itemCtx);
+          const newState = {
+            key: keyValue,
+            node: itemNode,
+            cleanups: localCleanups,
+            itemSignal,
+            indexSignal
+          };
+          newItemStateMap.set(keyValue, newState);
+          newNodes.push(itemNode);
         }
       });
     }
+    for (const [key2, state] of itemStateMap) {
+      if (!newItemStateMap.has(key2)) {
+        for (const cleanup of state.cleanups) {
+          cleanup();
+        }
+        if (state.node.parentNode) {
+          state.node.parentNode.removeChild(state.node);
+        }
+      }
+    }
+    const activeElement = document.activeElement;
+    const shouldRestoreFocus = activeElement && activeElement !== document.body;
+    if (anchor.parentNode) {
+      let refNode = anchor;
+      for (const itemNode of newNodes) {
+        const nextSibling = refNode.nextSibling;
+        if (nextSibling !== itemNode) {
+          anchor.parentNode.insertBefore(itemNode, refNode.nextSibling);
+        }
+        refNode = itemNode;
+      }
+    }
+    if (shouldRestoreFocus && activeElement instanceof HTMLElement && document.activeElement !== activeElement) {
+      activeElement.focus();
+    }
+    itemStateMap = newItemStateMap;
+    currentNodes = newNodes;
+    itemCleanups = [];
+    for (const state of itemStateMap.values()) {
+      itemCleanups.push(...state.cleanups);
+    }
   });
   ctx.cleanups?.push(effectCleanup);
   ctx.cleanups?.push(() => {
@@ -13263,6 +13605,20 @@ function createApp(program, mount) {
 }
 
 // src/hydrate.ts
+function createReactiveLocals2(baseLocals, itemSignal, indexSignal, itemName, indexName) {
+  return new Proxy(baseLocals, {
+    get(target, prop) {
+      if (prop === itemName) return itemSignal.get();
+      if (indexName && prop === indexName) return indexSignal.get();
+      return target[prop];
+    },
+    has(target, prop) {
+      if (prop === itemName) return true;
+      if (indexName && prop === indexName) return true;
+      return prop in target;
+    }
+  });
+}
 function isEventHandler2(value) {
   return typeof value === "object" && value !== null && "event" in value && "action" in value;
 }
@@ -13383,7 +13739,7 @@ function hydrateElement(node, el, ctx) {
             }
             let payload = void 0;
             if (handler.payload) {
-              payload = evaluate(handler.payload, {
+              payload = evaluatePayload(handler.payload, {
                 state: ctx.state,
                 locals: { ...ctx.locals, ...eventLocals },
                 ...ctx.imports && { imports: ctx.imports },
@@ -13693,6 +14049,8 @@ function hydrateEach(node, firstItemDomNode, ctx) {
   if (!parent) return;
   const anchor = document.createComment("each");
   parent.insertBefore(anchor, firstItemDomNode);
+  const hasKey = !!node.key;
+  let itemStateMap = /* @__PURE__ */ new Map();
   let currentNodes = [];
   let itemCleanups = [];
   const initialItems = evaluate(node.items, {
@@ -13704,29 +14062,85 @@ function hydrateEach(node, firstItemDomNode, ctx) {
   let isFirstRun = true;
   if (Array.isArray(initialItems) && initialItems.length > 0) {
     let domNode = firstItemDomNode;
-    initialItems.forEach((item, index) => {
-      if (!domNode) return;
-      currentNodes.push(domNode);
-      const itemLocals = {
-        ...ctx.locals,
-        [node.as]: item
-      };
-      if (node.index) {
-        itemLocals[node.index] = index;
-      }
-      const localCleanups = [];
-      const itemCtx = {
-        ...ctx,
-        locals: itemLocals,
-        cleanups: localCleanups
-      };
-      hydrate(node.body, domNode, itemCtx);
-      itemCleanups.push(...localCleanups);
-      domNode = domNode.nextSibling;
-      while (domNode && domNode.nodeType === Node.COMMENT_NODE) {
+    if (hasKey && node.key) {
+      const seenKeys = /* @__PURE__ */ new Set();
+      initialItems.forEach((item, index) => {
+        if (!domNode) return;
+        const tempLocals = {
+          ...ctx.locals,
+          [node.as]: item,
+          ...node.index ? { [node.index]: index } : {}
+        };
+        const keyValue = evaluate(node.key, {
+          state: ctx.state,
+          locals: tempLocals,
+          ...ctx.imports && { imports: ctx.imports },
+          ...ctx.route && { route: ctx.route }
+        });
+        if (seenKeys.has(keyValue)) {
+          if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+            console.warn(`Duplicate key "${keyValue}" in each loop. Keys should be unique.`);
+          }
+        }
+        seenKeys.add(keyValue);
+        const itemSignal = createSignal(item);
+        const indexSignal = createSignal(index);
+        const reactiveLocals = createReactiveLocals2(
+          ctx.locals,
+          itemSignal,
+          indexSignal,
+          node.as,
+          node.index
+        );
+        const localCleanups = [];
+        const itemCtx = {
+          ...ctx,
+          locals: reactiveLocals,
+          cleanups: localCleanups
+        };
+        hydrate(node.body, domNode, itemCtx);
+        const itemState = {
+          key: keyValue,
+          node: domNode,
+          cleanups: localCleanups,
+          itemSignal,
+          indexSignal
+        };
+        itemStateMap.set(keyValue, itemState);
+        currentNodes.push(domNode);
         domNode = domNode.nextSibling;
+        while (domNode && domNode.nodeType === Node.COMMENT_NODE) {
+          domNode = domNode.nextSibling;
+        }
+      });
+      for (const state of itemStateMap.values()) {
+        itemCleanups.push(...state.cleanups);
       }
-    });
+    } else {
+      initialItems.forEach((item, index) => {
+        if (!domNode) return;
+        currentNodes.push(domNode);
+        const itemLocals = {
+          ...ctx.locals,
+          [node.as]: item
+        };
+        if (node.index) {
+          itemLocals[node.index] = index;
+        }
+        const localCleanups = [];
+        const itemCtx = {
+          ...ctx,
+          locals: itemLocals,
+          cleanups: localCleanups
+        };
+        hydrate(node.body, domNode, itemCtx);
+        itemCleanups.push(...localCleanups);
+        domNode = domNode.nextSibling;
+        while (domNode && domNode.nodeType === Node.COMMENT_NODE) {
+          domNode = domNode.nextSibling;
+        }
+      });
+    }
   }
   const effectCleanup = createEffect(() => {
     const items = evaluate(node.items, {
@@ -13739,48 +14153,141 @@ function hydrateEach(node, firstItemDomNode, ctx) {
       isFirstRun = false;
       return;
     }
-    for (const cleanup of itemCleanups) {
-      cleanup();
-    }
-    itemCleanups = [];
-    for (const oldNode of currentNodes) {
-      if (oldNode.parentNode) {
-        oldNode.parentNode.removeChild(oldNode);
+    if (!hasKey || !node.key) {
+      for (const cleanup of itemCleanups) {
+        cleanup();
       }
+      itemCleanups = [];
+      for (const oldNode of currentNodes) {
+        if (oldNode.parentNode) {
+          oldNode.parentNode.removeChild(oldNode);
+        }
+      }
+      currentNodes = [];
+      if (Array.isArray(items)) {
+        items.forEach((item, index) => {
+          const itemLocals = {
+            ...ctx.locals,
+            [node.as]: item
+          };
+          if (node.index) {
+            itemLocals[node.index] = index;
+          }
+          const localCleanups = [];
+          const itemCtx = {
+            state: ctx.state,
+            actions: ctx.actions,
+            locals: itemLocals,
+            cleanups: localCleanups,
+            ...ctx.imports && { imports: ctx.imports }
+          };
+          const itemNode = render(node.body, itemCtx);
+          currentNodes.push(itemNode);
+          itemCleanups.push(...localCleanups);
+          if (anchor.parentNode) {
+            let refNode = anchor.nextSibling;
+            if (currentNodes.length > 1) {
+              const lastExisting = currentNodes[currentNodes.length - 2];
+              if (lastExisting) {
+                refNode = lastExisting.nextSibling;
+              }
+            }
+            anchor.parentNode.insertBefore(itemNode, refNode);
+          }
+        });
+      }
+      return;
     }
-    currentNodes = [];
+    const newItemStateMap = /* @__PURE__ */ new Map();
+    const newNodes = [];
+    const seenKeys = /* @__PURE__ */ new Set();
     if (Array.isArray(items)) {
       items.forEach((item, index) => {
-        const itemLocals = {
+        const tempLocals = {
           ...ctx.locals,
-          [node.as]: item
+          [node.as]: item,
+          ...node.index ? { [node.index]: index } : {}
         };
-        if (node.index) {
-          itemLocals[node.index] = index;
-        }
-        const localCleanups = [];
-        const itemCtx = {
+        const keyValue = evaluate(node.key, {
           state: ctx.state,
-          actions: ctx.actions,
-          locals: itemLocals,
-          cleanups: localCleanups,
-          ...ctx.imports && { imports: ctx.imports }
-        };
-        const itemNode = render(node.body, itemCtx);
-        currentNodes.push(itemNode);
-        itemCleanups.push(...localCleanups);
-        if (anchor.parentNode) {
-          let refNode = anchor.nextSibling;
-          if (currentNodes.length > 1) {
-            const lastExisting = currentNodes[currentNodes.length - 2];
-            if (lastExisting) {
-              refNode = lastExisting.nextSibling;
-            }
+          locals: tempLocals,
+          ...ctx.imports && { imports: ctx.imports },
+          ...ctx.route && { route: ctx.route }
+        });
+        if (seenKeys.has(keyValue)) {
+          if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production") {
+            console.warn(`Duplicate key "${keyValue}" in each loop. Keys should be unique.`);
           }
-          anchor.parentNode.insertBefore(itemNode, refNode);
+        }
+        seenKeys.add(keyValue);
+        const existingState = itemStateMap.get(keyValue);
+        if (existingState) {
+          existingState.itemSignal.set(item);
+          existingState.indexSignal.set(index);
+          newItemStateMap.set(keyValue, existingState);
+          newNodes.push(existingState.node);
+        } else {
+          const itemSignal = createSignal(item);
+          const indexSignal = createSignal(index);
+          const reactiveLocals = createReactiveLocals2(
+            ctx.locals,
+            itemSignal,
+            indexSignal,
+            node.as,
+            node.index
+          );
+          const localCleanups = [];
+          const itemCtx = {
+            state: ctx.state,
+            actions: ctx.actions,
+            locals: reactiveLocals,
+            cleanups: localCleanups,
+            ...ctx.imports && { imports: ctx.imports }
+          };
+          const itemNode = render(node.body, itemCtx);
+          const newState = {
+            key: keyValue,
+            node: itemNode,
+            cleanups: localCleanups,
+            itemSignal,
+            indexSignal
+          };
+          newItemStateMap.set(keyValue, newState);
+          newNodes.push(itemNode);
         }
       });
     }
+    for (const [key2, state] of itemStateMap) {
+      if (!newItemStateMap.has(key2)) {
+        for (const cleanup of state.cleanups) {
+          cleanup();
+        }
+        if (state.node.parentNode) {
+          state.node.parentNode.removeChild(state.node);
+        }
+      }
+    }
+    const activeElement = document.activeElement;
+    const shouldRestoreFocus = activeElement && activeElement !== document.body;
+    if (anchor.parentNode) {
+      let refNode = anchor;
+      for (const itemNode of newNodes) {
+        const nextSibling = refNode.nextSibling;
+        if (nextSibling !== itemNode) {
+          anchor.parentNode.insertBefore(itemNode, refNode.nextSibling);
+        }
+        refNode = itemNode;
+      }
+    }
+    if (shouldRestoreFocus && activeElement instanceof HTMLElement && document.activeElement !== activeElement) {
+      activeElement.focus();
+    }
+    itemStateMap = newItemStateMap;
+    currentNodes = newNodes;
+    itemCleanups = [];
+    for (const state of itemStateMap.values()) {
+      itemCleanups.push(...state.cleanups);
+    }
   });
   ctx.cleanups.push(effectCleanup);
   ctx.cleanups.push(() => {
@@ -13809,11 +14316,105 @@ function initCopyButtons(container) {
     });
   });
 }
+
+// src/connection/websocket.ts
+function createWebSocketConnection(url, handlers) {
+  const ws = new WebSocket(url);
+  ws.onopen = () => {
+    handlers.onOpen?.();
+  };
+  ws.onclose = (event) => {
+    handlers.onClose?.(event.code, event.reason);
+  };
+  ws.onerror = (event) => {
+    handlers.onError?.(event);
+  };
+  ws.onmessage = (event) => {
+    let data = event.data;
+    if (typeof data === "string") {
+      try {
+        data = JSON.parse(data);
+      } catch {
+      }
+    }
+    handlers.onMessage?.(data);
+  };
+  return {
+    send(data) {
+      if (ws.readyState === WebSocket.OPEN) {
+        let message;
+        if (typeof data === "string") {
+          message = data;
+        } else {
+          message = JSON.stringify(data);
+        }
+        ws.send(message);
+      }
+    },
+    close() {
+      ws.close();
+    },
+    getState() {
+      switch (ws.readyState) {
+        case WebSocket.CONNECTING:
+          return "connecting";
+        case WebSocket.OPEN:
+          return "open";
+        case WebSocket.CLOSING:
+          return "closing";
+        case WebSocket.CLOSED:
+          return "closed";
+        default:
+          return "closed";
+      }
+    }
+  };
+}
+function createConnectionManager() {
+  const connections = /* @__PURE__ */ new Map();
+  return {
+    create(name, url, handlers) {
+      const existing = connections.get(name);
+      if (existing) {
+        existing.close();
+      }
+      const conn = createWebSocketConnection(url, handlers);
+      connections.set(name, conn);
+    },
+    get(name) {
+      return connections.get(name);
+    },
+    send(name, data) {
+      const conn = connections.get(name);
+      if (!conn) {
+        throw new Error(`Connection "${name}" not found`);
+      }
+      conn.send(data);
+    },
+    close(name) {
+      const conn = connections.get(name);
+      if (conn) {
+        conn.close();
+        connections.delete(name);
+      }
+    },
+    closeAll() {
+      for (const conn of connections.values()) {
+        conn.close();
+      }
+      connections.clear();
+    }
+  };
+}
 export {
   createApp,
+  createComputed,
+  createConnectionManager,
   createEffect,
   createSignal,
   createStateStore,
+  createTypedStateStore,
+  createWebSocketConnection,
   evaluate,
   evaluateStyle,
   executeAction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.11.1",
+  "version": "0.12.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/core": "0.8.0",
-    "@constela/compiler": "0.8.0"
+    "@constela/compiler": "0.9.1",
+    "@constela/core": "0.9.1"
   },
   "devDependencies": {
     "@types/dompurify": "^3.2.0",
@@ -29,7 +29,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0",
-    "@constela/server": "4.1.0"
+    "@constela/server": "5.0.1"
   },
   "engines": {
     "node": ">=20.0.0"