@constela/runtime 0.10.1 → 0.10.3

package/README.md

@@ -0,0 +1,306 @@
+# @constela/runtime
+
+Runtime DOM renderer for the Constela UI framework with fine-grained reactivity.
+
+## Installation
+
+```bash
+npm install @constela/runtime
+```
+
+## Overview
+
+This package provides the client-side rendering engine for Constela applications. Key features:
+
+- **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'
+  },
+  imports: {
+    config: { apiUrl: 'https://api.example.com' }
+  }
+});
+```
+
+**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.
+
+#### setState(name, value)
+
+Updates a state field programmatically.
+
+```typescript
+app.setState('count', 10);
+app.setState('user', { name: 'John', email: 'john@example.com' });
+```
+
+#### getState(name)
+
+Reads current state value.
+
+```typescript
+const count = app.getState('count');
+```
+
+#### subscribe(name, fn)
+
+Subscribes to state changes. Returns an unsubscribe function.
+
+```typescript
+const unsubscribe = app.subscribe('count', (value) => {
+  console.log('count changed:', value);
+});
+
+// Later: stop listening
+unsubscribe();
+```
+
+## 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);
+
+// Read value (auto-tracks in effects)
+console.log(count.get()); // 0
+
+// Update value
+count.set(1);
+
+// Subscribe to changes
+const unsubscribe = count.subscribe((value) => {
+  console.log('Value:', value);
+});
+```
+
+### createEffect
+
+Creates a reactive side effect that auto-tracks dependencies.
+
+```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');
+  };
+});
+
+name.set('Constela'); // Logs: "Hello, Constela!"
+
+cleanup(); // Stops the effect
+```
+
+### createStateStore
+
+Centralized state management with signal-based reactivity.
+
+```typescript
+import { createStateStore } from '@constela/runtime';
+
+const store = createStateStore({
+  count: { type: 'number', initial: 0 },
+  name: { type: 'string', initial: '' }
+});
+
+store.get('count'); // 0
+store.set('count', 5);
+store.subscribe('count', (value) => console.log(value));
+```
+
+## Expression Evaluation
+
+### evaluate
+
+Evaluates compiled expressions.
+
+```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') }
+});
+```
+
+**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.
+
+```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
+
+Renders compiled nodes to DOM.
+
+```typescript
+import { render } from '@constela/runtime';
+
+const domNode = render(compiledNode, {
+  state: stateStore,
+  actions: compiledProgram.actions,
+  components: {},
+  locals: {},
+  route: { ... },
+  imports: { ... },
+  refs: {},
+  subscriptions: [],
+  cleanups: []
+});
+```
+
+**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

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

package/dist/index.js

@@ -248,6 +248,9 @@ function evaluate(expr, ctx) {
       }
       return dataValue;
     }
+    case "param": {
+      return void 0;
+    }
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);
@@ -2418,12 +2421,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"]);
@@ -2597,7 +2600,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";
       }
@@ -2610,13 +2613,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]) {
@@ -12828,6 +12831,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;
 }
@@ -12850,7 +12887,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.`);
@@ -12893,21 +12933,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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/runtime",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Runtime DOM renderer for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
     "dompurify": "^3.3.1",
     "marked": "^17.0.1",
     "shiki": "^3.20.0",
-    "@constela/compiler": "0.7.0",
+    "@constela/compiler": "0.7.1",
     "@constela/core": "0.7.0"
   },
   "devDependencies": {
@@ -29,7 +29,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0",
-    "@constela/server": "3.0.0"
+    "@constela/server": "3.0.1"
   },
   "engines": {
     "node": ">=20.0.0"