@constela/runtime 0.10.2 → 0.11.0

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
@@ -105,6 +133,7 @@ interface RenderContext {
     imports?: Record<string, unknown>;
     cleanups?: (() => void)[];
     refs?: Record<string, Element>;
+    inSvg?: boolean;
 }
 declare function render(node: CompiledNode, ctx: RenderContext): Node;
 
@@ -174,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

@@ -251,6 +251,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 +351,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) {
@@ -2421,12 +2453,12 @@ function createDOMPurify() {
   let URI_SAFE_ATTRIBUTES = null;
   const DEFAULT_URI_SAFE_ATTRIBUTES = addToSet({}, ["alt", "class", "for", "id", "label", "name", "pattern", "placeholder", "role", "summary", "title", "value", "style", "xmlns"]);
   const MATHML_NAMESPACE = "http://www.w3.org/1998/Math/MathML";
-  const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+  const SVG_NAMESPACE2 = "http://www.w3.org/2000/svg";
   const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
   let NAMESPACE = HTML_NAMESPACE;
   let IS_EMPTY_INPUT = false;
   let ALLOWED_NAMESPACES = null;
-  const DEFAULT_ALLOWED_NAMESPACES = addToSet({}, [MATHML_NAMESPACE, SVG_NAMESPACE, HTML_NAMESPACE], stringToString);
+  const DEFAULT_ALLOWED_NAMESPACES = addToSet({}, [MATHML_NAMESPACE, SVG_NAMESPACE2, HTML_NAMESPACE], stringToString);
   let MATHML_TEXT_INTEGRATION_POINTS = addToSet({}, ["mi", "mo", "mn", "ms", "mtext"]);
   let HTML_INTEGRATION_POINTS = addToSet({}, ["annotation-xml"]);
   const COMMON_SVG_AND_HTML_ELEMENTS = addToSet({}, ["title", "style", "font", "a", "script"]);
@@ -2600,7 +2632,7 @@ function createDOMPurify() {
     if (!ALLOWED_NAMESPACES[element2.namespaceURI]) {
       return false;
     }
-    if (element2.namespaceURI === SVG_NAMESPACE) {
+    if (element2.namespaceURI === SVG_NAMESPACE2) {
       if (parent.namespaceURI === HTML_NAMESPACE) {
         return tagName === "svg";
       }
@@ -2613,13 +2645,13 @@ function createDOMPurify() {
       if (parent.namespaceURI === HTML_NAMESPACE) {
         return tagName === "math";
       }
-      if (parent.namespaceURI === SVG_NAMESPACE) {
+      if (parent.namespaceURI === SVG_NAMESPACE2) {
         return tagName === "math" && HTML_INTEGRATION_POINTS[parentTagName];
       }
       return Boolean(ALL_MATHML_TAGS[tagName]);
     }
     if (element2.namespaceURI === HTML_NAMESPACE) {
-      if (parent.namespaceURI === SVG_NAMESPACE && !HTML_INTEGRATION_POINTS[parentTagName]) {
+      if (parent.namespaceURI === SVG_NAMESPACE2 && !HTML_INTEGRATION_POINTS[parentTagName]) {
         return false;
       }
       if (parent.namespaceURI === MATHML_NAMESPACE && !MATHML_TEXT_INTEGRATION_POINTS[parentTagName]) {
@@ -12831,6 +12863,40 @@ async function highlightCode(code, language) {
 }
 
 // src/renderer/index.ts
+var SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+var SVG_TAGS = /* @__PURE__ */ new Set([
+  "svg",
+  "path",
+  "line",
+  "circle",
+  "rect",
+  "ellipse",
+  "polyline",
+  "polygon",
+  "g",
+  "defs",
+  "use",
+  "text",
+  "tspan",
+  "clipPath",
+  "mask",
+  "linearGradient",
+  "radialGradient",
+  "stop",
+  "pattern",
+  "symbol",
+  "marker",
+  "image",
+  "filter",
+  "foreignObject",
+  "animate",
+  "animateTransform",
+  "desc",
+  "title"
+]);
+function isSvgTag(tag) {
+  return SVG_TAGS.has(tag);
+}
 function isEventHandler(value) {
   return typeof value === "object" && value !== null && "event" in value && "action" in value;
 }
@@ -12853,7 +12919,10 @@ function render(node, ctx) {
   }
 }
 function renderElement(node, ctx) {
-  const el = document.createElement(node.tag);
+  const tag = node.tag;
+  const inSvgContext = ctx.inSvg || tag === "svg";
+  const useSvgNamespace = inSvgContext && isSvgTag(tag);
+  const el = useSvgNamespace ? document.createElementNS(SVG_NAMESPACE, tag) : document.createElement(tag);
   if (node.ref && ctx.refs) {
     if (typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production" && ctx.refs[node.ref]) {
       console.warn(`Duplicate ref name "${node.ref}" detected. The later element will overwrite the earlier one.`);
@@ -12896,21 +12965,31 @@ function renderElement(node, ctx) {
       } else {
         const cleanup = createEffect(() => {
           const value = evaluate(propValue, { state: ctx.state, locals: ctx.locals, ...ctx.imports && { imports: ctx.imports } });
-          applyProp(el, propName, value);
+          applyProp(el, propName, value, useSvgNamespace);
         });
         ctx.cleanups?.push(cleanup);
       }
     }
   }
   if (node.children) {
+    const childInSvg = tag === "foreignObject" ? false : inSvgContext;
+    const childCtx = childInSvg !== ctx.inSvg ? { ...ctx, inSvg: childInSvg } : ctx;
     for (const child of node.children) {
-      const childNode = render(child, ctx);
+      const childNode = render(child, childCtx);
       el.appendChild(childNode);
     }
   }
   return el;
 }
-function applyProp(el, propName, value) {
+function applyProp(el, propName, value, isSvg = false) {
+  if (isSvg && propName === "className") {
+    if (value) {
+      el.setAttribute("class", String(value));
+    } else {
+      el.removeAttribute("class");
+    }
+    return;
+  }
   if (propName === "className") {
     el.className = String(value ?? "");
   } else if (propName === "style" && typeof value === "string") {
@@ -13722,6 +13801,7 @@ export {
   createSignal,
   createStateStore,
   evaluate,
+  evaluateStyle,
   executeAction,
   hydrateApp,
   render

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "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.7.0",
-    "@constela/compiler": "0.7.1"
+    "@constela/compiler": "0.8.0",
+    "@constela/core": "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.0.0"
   },
   "engines": {
     "node": ">=20.0.0"