@constela/runtime 0.10.3 → 0.11.1

package/README.md

@@ -1,6 +1,6 @@
 # @constela/runtime
 
-Runtime DOM renderer for the Constela UI framework with fine-grained reactivity.
+Executes Constela JSON programs in the browser with fine-grained reactivity.
 
 ## Installation
 
@@ -8,299 +8,157 @@ Runtime DOM renderer for the Constela UI framework with fine-grained reactivity.
 npm install @constela/runtime
 ```
 
-## Overview
+## How It Works
 
-This package provides the client-side rendering engine for Constela applications. Key features:
+Your JSON program:
 
-- **Fine-grained Reactivity** - Signal-based updates without virtual DOM
-- **Hydration** - Rehydrate server-rendered HTML
-- **Markdown & Code** - Built-in Markdown and syntax highlighting support
-
-## API Reference
-
-### createApp
-
-Creates and mounts a Constela application.
-
-```typescript
-import { createApp } from '@constela/runtime';
-
-const app = createApp(compiledProgram, document.getElementById('app'));
-
-// Later: cleanup
-app.destroy();
-```
-
-**Parameters:**
-- `program: CompiledProgram` - Compiled program from `@constela/compiler`
-- `mount: HTMLElement` - DOM element to mount to
-
-**Returns:** `AppInstance`
-
-### hydrateApp
-
-Hydrates server-rendered HTML without DOM reconstruction.
-
-```typescript
-import { hydrateApp } from '@constela/runtime';
-
-const app = hydrateApp({
-  program: compiledProgram,
-  mount: document.getElementById('app'),
-  route: {
-    params: { id: '123' },
-    query: { tab: 'details' },
-    path: '/users/123'
+```json
+{
+  "version": "1.0",
+  "state": {
+    "count": { "type": "number", "initial": 0 }
   },
-  imports: {
-    config: { apiUrl: 'https://api.example.com' }
+  "actions": [
+    {
+      "name": "increment",
+      "steps": [{ "do": "update", "target": "count", "operation": "increment" }]
+    }
+  ],
+  "view": {
+    "kind": "element",
+    "tag": "button",
+    "props": { "onClick": { "event": "click", "action": "increment" } },
+    "children": [{ "kind": "text", "value": { "expr": "state", "name": "count" } }]
   }
-});
-```
-
-**HydrateOptions:**
-- `program: CompiledProgram` - Compiled program
-- `mount: HTMLElement` - Container element
-- `route?: RouteContext` - Route parameters
-- `imports?: Record<string, unknown>` - Import data
-
-### AppInstance
-
-```typescript
-interface AppInstance {
-  destroy(): void;
-  setState(name: string, value: unknown): void;
-  getState(name: string): unknown;
-  subscribe(name: string, fn: (value: unknown) => void): () => void;
 }
 ```
 
-#### destroy()
-
-Cleans up the application, removes event listeners, and clears state.
+Becomes an interactive app with:
+- **Reactive state management** - Signal-based updates without virtual DOM
+- **Efficient DOM updates** - Fine-grained reactivity
+- **Event handling** - Declarative action binding
 
-#### setState(name, value)
+## Features
 
-Updates a state field programmatically.
+### Markdown Rendering
 
-```typescript
-app.setState('count', 10);
-app.setState('user', { name: 'John', email: 'john@example.com' });
+```json
+{
+  "kind": "markdown",
+  "content": { "expr": "state", "name": "markdownContent" }
+}
 ```
 
-#### getState(name)
+Rendered with [marked](https://marked.js.org/) and sanitized with [DOMPurify](https://github.com/cure53/DOMPurify).
 
-Reads current state value.
+### Code Blocks
 
-```typescript
-const count = app.getState('count');
+```json
+{
+  "kind": "code",
+  "code": { "expr": "lit", "value": "const x: number = 42;" },
+  "language": { "expr": "lit", "value": "typescript" }
+}
 ```
 
-#### subscribe(name, fn)
+Features:
+- Syntax highlighting with [Shiki](https://shiki.style/)
+- Dual theme support (light/dark)
+- Built-in copy button
 
-Subscribes to state changes. Returns an unsubscribe function.
+### Hydration
 
-```typescript
-const unsubscribe = app.subscribe('count', (value) => {
-  console.log('count changed:', value);
-});
+Server-rendered HTML is hydrated on the client without DOM reconstruction:
 
-// Later: stop listening
-unsubscribe();
+```json
+{
+  "version": "1.0",
+  "state": { "theme": { "type": "string", "initial": "light" } },
+  "lifecycle": {
+    "onMount": "loadTheme"
+  },
+  "actions": [
+    {
+      "name": "loadTheme",
+      "steps": [
+        {
+          "do": "storage",
+          "operation": "get",
+          "key": { "expr": "lit", "value": "theme" },
+          "storage": "local",
+          "result": "savedTheme",
+          "onSuccess": [
+            { "do": "set", "target": "theme", "value": { "expr": "var", "name": "savedTheme" } }
+          ]
+        }
+      ]
+    }
+  ],
+  "view": { ... }
+}
 ```
 
-## Reactive Primitives
-
-Low-level reactive APIs for advanced usage.
-
-### createSignal
-
-Creates a reactive signal with fine-grained dependency tracking.
-
-```typescript
-import { createSignal } from '@constela/runtime';
-
-const count = createSignal(0);
+## Security
 
-// Read value (auto-tracks in effects)
-console.log(count.get()); // 0
+The runtime includes security measures:
 
-// Update value
-count.set(1);
+- **Prototype Pollution Prevention** - Blocks `__proto__`, `constructor`, `prototype`
+- **Safe Globals** - Only exposes `JSON`, `Math`, `Date`, `Object`, `Array`, `String`, `Number`, `Boolean`, `console`
+- **HTML Sanitization** - DOMPurify for Markdown content
 
-// Subscribe to changes
-const unsubscribe = count.subscribe((value) => {
-  console.log('Value:', value);
-});
-```
+## Internal API
 
-### createEffect
+> For framework developers only. End users should use the CLI.
 
-Creates a reactive side effect that auto-tracks dependencies.
+### createApp
 
 ```typescript
-import { createSignal, createEffect } from '@constela/runtime';
-
-const name = createSignal('World');
-
-const cleanup = createEffect(() => {
-  console.log(`Hello, ${name.get()}!`);
-
-  // Optional cleanup function
-  return () => {
-    console.log('Effect cleaned up');
-  };
-});
+import { createApp } from '@constela/runtime';
 
-name.set('Constela'); // Logs: "Hello, Constela!"
+const app = createApp(compiledProgram, document.getElementById('app'));
 
-cleanup(); // Stops the effect
+// Cleanup
+app.destroy();
 ```
 
-### createStateStore
-
-Centralized state management with signal-based reactivity.
+### hydrateApp
 
 ```typescript
-import { createStateStore } from '@constela/runtime';
+import { hydrateApp } from '@constela/runtime';
 
-const store = createStateStore({
-  count: { type: 'number', initial: 0 },
-  name: { type: 'string', initial: '' }
+const app = hydrateApp({
+  program: compiledProgram,
+  mount: document.getElementById('app'),
+  route: { params: { id: '123' }, query: new URLSearchParams(), path: '/users/123' },
+  imports: { config: { apiUrl: 'https://api.example.com' } }
 });
-
-store.get('count'); // 0
-store.set('count', 5);
-store.subscribe('count', (value) => console.log(value));
 ```
 
-## Expression Evaluation
-
-### evaluate
-
-Evaluates compiled expressions.
+### AppInstance
 
 ```typescript
-import { evaluate } from '@constela/runtime';
-
-const result = evaluate(expression, {
-  state: stateStore,
-  locals: { item: { id: 1, name: 'Test' } },
-  route: { params: { id: '123' }, query: new URLSearchParams(), path: '/items/123' },
-  imports: { config: { apiUrl: '...' } },
-  data: { posts: [...] },
-  refs: { inputEl: document.querySelector('#input') }
-});
+interface AppInstance {
+  destroy(): void;
+  setState(name: string, value: unknown): void;
+  getState(name: string): unknown;
+  subscribe(name: string, fn: (value: unknown) => void): () => void;
+}
 ```
 
-**Supported Expressions:**
-- Literals, state reads, variables
-- Binary operations, logical not, conditionals
-- Property access, array indexing
-- Route parameters/query/path
-- Imports and loaded data
-- DOM refs
-
-## Action Execution
-
-### executeAction
-
-Executes compiled actions.
+### Reactive Primitives
 
 ```typescript
-import { executeAction } from '@constela/runtime';
-
-await executeAction(action, {
-  state: stateStore,
-  locals: {},
-  route: { ... },
-  imports: { ... },
-  refs: { ... },
-  subscriptions: []
-});
-```
-
-**Supported Steps:**
-- `set`, `update` - State mutations
-- `fetch` - HTTP requests
-- `storage` - localStorage/sessionStorage
-- `clipboard` - Clipboard operations
-- `navigate` - Page navigation
-- `import`, `call` - Dynamic imports and function calls
-- `subscribe`, `dispose` - Event subscriptions
-- `dom` - DOM manipulation
-- `if` - Conditional execution
-
-## Rendering
-
-### render
+import { createSignal, createEffect } from '@constela/runtime';
 
-Renders compiled nodes to DOM.
+const count = createSignal(0);
+count.get();  // Read
+count.set(1); // Write
 
-```typescript
-import { render } from '@constela/runtime';
-
-const domNode = render(compiledNode, {
-  state: stateStore,
-  actions: compiledProgram.actions,
-  components: {},
-  locals: {},
-  route: { ... },
-  imports: { ... },
-  refs: {},
-  subscriptions: [],
-  cleanups: []
+const cleanup = createEffect(() => {
+  console.log(`Count: ${count.get()}`);
 });
 ```
 
-**Supported Nodes:**
-- Element nodes with props and event handlers
-- Text nodes with reactive updates
-- Conditional rendering (`if/else`)
-- List rendering (`each`)
-- Markdown with sanitization
-- Code blocks with Shiki highlighting
-
-## Markdown & Code Blocks
-
-The runtime includes built-in support for rendering Markdown and syntax-highlighted code.
-
-### Markdown
-
-Rendered using [marked](https://marked.js.org/) with [DOMPurify](https://github.com/cure53/DOMPurify) sanitization.
-
-```json
-{
-  "kind": "markdown",
-  "content": { "expr": "state", "name": "markdownContent" }
-}
-```
-
-### Code Blocks
-
-Rendered with [Shiki](https://shiki.style/) syntax highlighting.
-
-```json
-{
-  "kind": "code",
-  "code": { "expr": "lit", "value": "const x = 1;" },
-  "language": { "expr": "lit", "value": "typescript" }
-}
-```
-
-**Features:**
-- Dual theme support (light/dark)
-- Copy button with feedback
-- Dynamic language loading
-
-## Security
-
-The runtime includes security measures:
-
-- **Prototype Pollution Prevention** - Blocks `__proto__`, `constructor`, `prototype`
-- **Safe Globals** - Only exposes `JSON`, `Math`, `Date`, `Object`, `Array`, `String`, `Number`, `Boolean`, `console`
-- **HTML Sanitization** - DOMPurify for Markdown content
-
 ## License
 
 MIT

package/dist/index.d.ts

@@ -47,6 +47,17 @@ declare function createStateStore(definitions: Record<string, StateDefinition>):
  * - Property access (get)
  */
 
+/**
+ * Style preset definition - matches @constela/core StylePreset
+ */
+interface StylePreset {
+    base: string;
+    variants?: Record<string, Record<string, string>>;
+    defaultVariants?: Record<string, string>;
+    compoundVariants?: Array<Record<string, string> & {
+        class: string;
+    }>;
+}
 interface EvaluationContext {
     state: StateStore;
     locals: Record<string, unknown>;
@@ -57,8 +68,25 @@ interface EvaluationContext {
     };
     imports?: Record<string, unknown>;
     refs?: Record<string, Element>;
+    styles?: Record<string, StylePreset>;
 }
 declare function evaluate(expr: CompiledExpression, ctx: EvaluationContext): unknown;
+/**
+ * Style expression type for evaluateStyle
+ */
+interface StyleExprInput {
+    expr: 'style';
+    name: string;
+    variants?: Record<string, CompiledExpression>;
+}
+/**
+ * Evaluates a style expression to produce CSS class names
+ *
+ * @param expr - The style expression to evaluate
+ * @param ctx - The evaluation context containing styles presets
+ * @returns The computed CSS class string, or undefined if preset not found
+ */
+declare function evaluateStyle(expr: StyleExprInput, ctx: EvaluationContext): string | undefined;
 
 /**
  * Action Executor - Executes compiled action steps
@@ -175,4 +203,4 @@ interface HydrateOptions {
  */
 declare function hydrateApp(options: HydrateOptions): AppInstance;
 
-export { type ActionContext, type AppInstance, type EvaluationContext, type HydrateOptions, type RenderContext, type Signal, type StateStore, createApp, createEffect, createSignal, createStateStore, evaluate, executeAction, hydrateApp, render };
+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 };

package/dist/index.js

@@ -99,7 +99,21 @@ function createEffect(fn) {
 function createStateStore(definitions) {
   const signals = /* @__PURE__ */ new Map();
   for (const [name, def] of Object.entries(definitions)) {
-    signals.set(name, createSignal(def.initial));
+    let initialValue = def.initial;
+    if (name === "theme" && typeof window !== "undefined") {
+      try {
+        const stored = localStorage.getItem("theme");
+        if (stored !== null) {
+          try {
+            initialValue = JSON.parse(stored);
+          } catch {
+            initialValue = stored;
+          }
+        }
+      } catch {
+      }
+    }
+    signals.set(name, createSignal(initialValue));
   }
   return {
     get(name) {
@@ -251,6 +265,8 @@ function evaluate(expr, ctx) {
     case "param": {
       return void 0;
     }
+    case "style":
+      return evaluateStyle(expr, ctx);
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);
@@ -349,6 +365,36 @@ function evaluateBinary(op, left, right, ctx) {
       throw new Error("Unknown binary operator: " + op);
   }
 }
+function evaluateStyle(expr, ctx) {
+  const preset = ctx.styles?.[expr.name];
+  if (!preset) return void 0;
+  let classes = preset.base;
+  if (preset.variants) {
+    for (const variantKey of Object.keys(preset.variants)) {
+      let variantValueStr = null;
+      if (expr.variants?.[variantKey]) {
+        let variantValue;
+        try {
+          variantValue = evaluate(expr.variants[variantKey], ctx);
+        } catch {
+          continue;
+        }
+        if (variantValue != null) {
+          variantValueStr = String(variantValue);
+        }
+      } else if (preset.defaultVariants?.[variantKey] !== void 0) {
+        variantValueStr = preset.defaultVariants[variantKey];
+      }
+      if (variantValueStr !== null) {
+        const variantClasses = preset.variants[variantKey]?.[variantValueStr];
+        if (variantClasses) {
+          classes += " " + variantClasses;
+        }
+      }
+    }
+  }
+  return classes.trim();
+}
 
 // src/action/executor.ts
 function createEvalContext(ctx) {
@@ -13769,6 +13815,7 @@ export {
   createSignal,
   createStateStore,
   evaluate,
+  evaluateStyle,
   executeAction,
   hydrateApp,
   render

package/package.json

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