@constela/server 3.0.1 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @constela/server
 
-Server-side rendering (SSR) for the Constela UI framework.
+Server-side rendering (SSR) for Constela JSON programs.
 
 ## Installation
 
@@ -11,76 +11,85 @@ npm install @constela/server
 **Peer Dependencies:**
 - `@constela/compiler` ^0.7.0
 
-## Overview
-
-This package provides SSR capabilities for Constela applications. Features:
-
-- **HTML Generation** - Render programs to HTML strings
-- **Route Context** - Pass route params and query strings
-- **Markdown & Code** - Server-side Markdown and syntax highlighting
-- **Dual Theme** - Light and dark theme code blocks
+## How It Works
+
+JSON program → HTML string
+
+```json
+{
+  "version": "1.0",
+  "state": { "name": { "type": "string", "initial": "World" } },
+  "view": {
+    "kind": "element",
+    "tag": "h1",
+    "children": [
+      { "kind": "text", "value": { "expr": "lit", "value": "Hello, " } },
+      { "kind": "text", "value": { "expr": "state", "name": "name" } }
+    ]
+  }
+}
+```
 
-## API Reference
+↓ SSR
 
-### renderToString
+```html
+<h1>Hello, World</h1>
+```
 
-Main SSR function that renders a compiled program to HTML.
+## Features
 
-```typescript
-import { renderToString } from '@constela/server';
+### Markdown Rendering
 
-const html = await renderToString(compiledProgram, {
-  route: {
-    params: { id: '123' },
-    query: { tab: 'overview' },
-    path: '/users/123',
-  },
-  imports: {
-    config: { siteName: 'My Site' },
-  },
-});
+```json
+{
+  "kind": "markdown",
+  "content": { "expr": "data", "name": "article", "path": "content" }
+}
 ```
 
-**Parameters:**
-- `program: CompiledProgram` - Compiled program from `@constela/compiler`
-- `options?: RenderOptions` - Optional render configuration
+Rendered with async parsing and Shiki syntax highlighting.
 
-**RenderOptions:**
-```typescript
-interface RenderOptions {
-  route?: {
-    params?: Record<string, string>;
-    query?: Record<string, string>;
-    path?: string;
-  };
-  imports?: Record<string, unknown>;
+### Code Highlighting
+
+```json
+{
+  "kind": "code",
+  "code": { "expr": "lit", "value": "const x = 1;" },
+  "language": { "expr": "lit", "value": "typescript" }
 }
 ```
 
-**Returns:** `Promise<string>` - Complete HTML string
+Features:
+- Dual theme support (github-light, github-dark)
+- CSS custom properties for theme switching
+- Preloaded languages: javascript, typescript, json, html, css, python, rust, go, java, bash, markdown
 
-## Internal Features
+### Route Context
 
-The package internally handles:
+Pass route parameters for dynamic pages:
 
-**Markdown Rendering:**
-- Async parsing with Shiki syntax highlighting
-- Sanitization via DOMPurify
+```json
+{
+  "route": { "path": "/users/:id" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "route", "name": "id", "source": "param" }
+  }
+}
+```
 
-**Code Highlighting:**
-- Dual theme support (github-light, github-dark)
-- CSS custom properties for theme switching
-- Preloaded languages: javascript, typescript, json, html, css, python, rust, go, java, bash, markdown
+### Import Data
 
-**CSS Variables:** Code blocks use CSS custom properties:
-```css
-/* Light mode */
-.shiki { background-color: var(--shiki-light-bg); }
-.shiki span { color: var(--shiki-light); }
+Pass external data at render time:
 
-/* Dark mode */
-.dark .shiki { background-color: var(--shiki-dark-bg); }
-.dark .shiki span { color: var(--shiki-dark); }
+```json
+{
+  "imports": { "config": "./data/config.json" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "import", "name": "config", "path": "siteName" }
+  }
+}
 ```
 
 ## Output Structure
@@ -91,23 +100,23 @@ The package internally handles:
 <div class="constela-code" data-code-content="...">
   <div class="group relative">
     <div class="language-badge">typescript</div>
-    <button class="constela-copy-btn">
-      <!-- Copy icon SVG -->
-    </button>
+    <button class="constela-copy-btn"><!-- Copy icon --></button>
     <pre><code class="shiki">...</code></pre>
   </div>
 </div>
 ```
 
-The `data-code-content` attribute contains the raw code for copy functionality.
+### CSS Variables
 
-## Expression Evaluation
-
-SSR evaluates expressions server-side with some limitations:
+```css
+/* Light mode */
+.shiki { background-color: var(--shiki-light-bg); }
+.shiki span { color: var(--shiki-light); }
 
-- **No DOM refs** - `ref` expressions return `null`
-- **No safe globals** - Limited to basic operations
-- **Static only** - No reactive updates
+/* Dark mode */
+.dark .shiki { background-color: var(--shiki-dark-bg); }
+.dark .shiki span { color: var(--shiki-dark); }
+```
 
 ## Security
 
@@ -115,29 +124,37 @@ SSR evaluates expressions server-side with some limitations:
 - **DOMPurify** - Markdown content is sanitized
 - **Prototype Pollution Prevention** - Same as runtime
 
-## Example
+## Internal API
+
+> For framework developers only. End users should use the CLI.
+
+### renderToString
 
 ```typescript
-import { compile } from '@constela/compiler';
 import { renderToString } from '@constela/server';
 
-const program = compile({
-  version: '1.0',
-  state: { name: { type: 'string', initial: 'World' } },
-  actions: [],
-  view: {
-    kind: 'element',
-    tag: 'h1',
-    children: [
-      { kind: 'text', value: { expr: 'lit', value: 'Hello, ' } },
-      { kind: 'text', value: { expr: 'state', name: 'name' } },
-    ],
+const html = await renderToString(compiledProgram, {
+  route: {
+    params: { id: '123' },
+    query: { tab: 'overview' },
+    path: '/users/123',
+  },
+  imports: {
+    config: { siteName: 'My Site' },
   },
 });
+```
+
+**RenderOptions:**
 
-if (program.ok) {
-  const html = await renderToString(program.program);
-  console.log(html); // '<h1>Hello, World</h1>'
+```typescript
+interface RenderOptions {
+  route?: {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    path?: string;
+  };
+  imports?: Record<string, unknown>;
 }
 ```
 
@@ -145,14 +162,21 @@ if (program.ok) {
 
 Server-rendered HTML can be hydrated on the client:
 
-```typescript
-// Server
-import { renderToString } from '@constela/server';
-const html = await renderToString(program, { route, imports });
-
-// Client
-import { hydrateApp } from '@constela/runtime';
-hydrateApp({ program, mount, route, imports });
+```json
+{
+  "version": "1.0",
+  "lifecycle": { "onMount": "initializeClient" },
+  "state": { ... },
+  "actions": [
+    {
+      "name": "initializeClient",
+      "steps": [
+        { "do": "storage", "operation": "get", "key": { "expr": "lit", "value": "preferences" }, ... }
+      ]
+    }
+  ],
+  "view": { ... }
+}
 ```
 
 ## License

package/dist/index.js

@@ -213,6 +213,12 @@ function evaluate(expr, ctx) {
       if (typeof key === "string" && forbiddenKeys.has(key)) return void 0;
       return base[key];
     }
+    case "param": {
+      return void 0;
+    }
+    case "style": {
+      return "";
+    }
     default: {
       const _exhaustiveCheck = expr;
       throw new Error(`Unknown expression type: ${JSON.stringify(_exhaustiveCheck)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/server",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Server-side rendering for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "peerDependencies": {
-    "@constela/compiler": "^0.7.0"
+    "@constela/compiler": "^0.8.0"
   },
   "dependencies": {
     "isomorphic-dompurify": "^2.35.0",
@@ -28,7 +28,7 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^2.0.0",
-    "@constela/compiler": "0.7.0"
+    "@constela/compiler": "0.8.0"
   },
   "engines": {
     "node": ">=20.0.0"