@constela/server 3.0.0 → 4.0.0

package/README.md

@@ -0,0 +1,184 @@
+# @constela/server
+
+Server-side rendering (SSR) for Constela JSON programs.
+
+## Installation
+
+```bash
+npm install @constela/server
+```
+
+**Peer Dependencies:**
+- `@constela/compiler` ^0.7.0
+
+## 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" } }
+    ]
+  }
+}
+```
+
+↓ SSR
+
+```html
+<h1>Hello, World</h1>
+```
+
+## Features
+
+### Markdown Rendering
+
+```json
+{
+  "kind": "markdown",
+  "content": { "expr": "data", "name": "article", "path": "content" }
+}
+```
+
+Rendered with async parsing and Shiki syntax highlighting.
+
+### Code Highlighting
+
+```json
+{
+  "kind": "code",
+  "code": { "expr": "lit", "value": "const x = 1;" },
+  "language": { "expr": "lit", "value": "typescript" }
+}
+```
+
+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
+
+### Route Context
+
+Pass route parameters for dynamic pages:
+
+```json
+{
+  "route": { "path": "/users/:id" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "route", "name": "id", "source": "param" }
+  }
+}
+```
+
+### Import Data
+
+Pass external data at render time:
+
+```json
+{
+  "imports": { "config": "./data/config.json" },
+  "view": {
+    "kind": "text",
+    "value": { "expr": "import", "name": "config", "path": "siteName" }
+  }
+}
+```
+
+## Output Structure
+
+### Code Block HTML
+
+```html
+<div class="constela-code" data-code-content="...">
+  <div class="group relative">
+    <div class="language-badge">typescript</div>
+    <button class="constela-copy-btn"><!-- Copy icon --></button>
+    <pre><code class="shiki">...</code></pre>
+  </div>
+</div>
+```
+
+### CSS Variables
+
+```css
+/* Light mode */
+.shiki { background-color: var(--shiki-light-bg); }
+.shiki span { color: var(--shiki-light); }
+
+/* Dark mode */
+.dark .shiki { background-color: var(--shiki-dark-bg); }
+.dark .shiki span { color: var(--shiki-dark); }
+```
+
+## Security
+
+- **HTML Escaping** - All text output is escaped
+- **DOMPurify** - Markdown content is sanitized
+- **Prototype Pollution Prevention** - Same as runtime
+
+## Internal API
+
+> For framework developers only. End users should use the CLI.
+
+### renderToString
+
+```typescript
+import { renderToString } from '@constela/server';
+
+const html = await renderToString(compiledProgram, {
+  route: {
+    params: { id: '123' },
+    query: { tab: 'overview' },
+    path: '/users/123',
+  },
+  imports: {
+    config: { siteName: 'My Site' },
+  },
+});
+```
+
+**RenderOptions:**
+
+```typescript
+interface RenderOptions {
+  route?: {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    path?: string;
+  };
+  imports?: Record<string, unknown>;
+}
+```
+
+## Integration with @constela/runtime
+
+Server-rendered HTML can be hydrated on the client:
+
+```json
+{
+  "version": "1.0",
+  "lifecycle": { "onMount": "initializeClient" },
+  "state": { ... },
+  "actions": [
+    {
+      "name": "initializeClient",
+      "steps": [
+        { "do": "storage", "operation": "get", "key": { "expr": "lit", "value": "preferences" }, ... }
+      ]
+    }
+  ],
+  "view": { ... }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -6,12 +6,24 @@ import { CompiledProgram } from '@constela/compiler';
  * Renders CompiledProgram to HTML string for Server-Side Rendering.
  */
 
+/**
+ * Options for renderToString
+ */
+interface RenderOptions {
+    route?: {
+        params?: Record<string, string>;
+        query?: Record<string, string>;
+        path?: string;
+    };
+    imports?: Record<string, unknown>;
+}
 /**
  * Renders a CompiledProgram to an HTML string.
  *
  * @param program - The compiled program to render
+ * @param options - Optional render options including route context
  * @returns Promise that resolves to HTML string representation
  */
-declare function renderToString(program: CompiledProgram): Promise<string>;
+declare function renderToString(program: CompiledProgram, options?: RenderOptions): Promise<string>;
 
-export { renderToString };
+export { type RenderOptions, renderToString };

package/dist/index.js

@@ -1,15 +1,7 @@
 // src/markdown.ts
 import { marked } from "marked";
+import markedShiki from "marked-shiki";
 import DOMPurify from "isomorphic-dompurify";
-marked.setOptions({ gfm: true, breaks: false });
-function parseMarkdownSSR(content) {
-  const rawHtml = marked.parse(content, { async: false });
-  return DOMPurify.sanitize(rawHtml, {
-    USE_PROFILES: { html: true },
-    FORBID_TAGS: ["script", "style", "iframe"],
-    FORBID_ATTR: ["onerror", "onload", "onclick"]
-  });
-}
 
 // src/code.ts
 import { createHighlighter } from "shiki";
@@ -45,7 +37,7 @@ var PRELOAD_LANGS = [
 async function getHighlighter() {
   if (!highlighter) {
     highlighter = await createHighlighter({
-      themes: ["github-dark"],
+      themes: ["github-light", "github-dark"],
       langs: PRELOAD_LANGS
     });
   }
@@ -59,7 +51,15 @@ async function renderCodeSSR(code, language) {
       await hl.loadLanguage(language);
     }
     const langToUse = language || "text";
-    return hl.codeToHtml(code, { lang: langToUse, theme: "github-dark" });
+    const html = hl.codeToHtml(code, {
+      lang: langToUse,
+      themes: {
+        light: "github-light",
+        dark: "github-dark"
+      },
+      defaultColor: false
+    });
+    return html.replace(/background-color:[^;]+;?/g, "");
   } catch {
     const escapedCode = escapeHtml(code);
     const langClass = language ? ` class="language-${language}"` : "";
@@ -67,6 +67,44 @@ async function renderCodeSSR(code, language) {
   }
 }
 
+// src/markdown.ts
+var markedConfigured = false;
+async function configureMarked() {
+  if (markedConfigured) return;
+  const highlighter2 = await getHighlighter();
+  marked.use(
+    markedShiki({
+      highlight: async (code, lang) => {
+        const loadedLangs = highlighter2.getLoadedLanguages();
+        let langToUse = lang || "text";
+        if (lang && !loadedLangs.includes(lang) && lang !== "text") {
+          try {
+            await highlighter2.loadLanguage(lang);
+          } catch {
+            langToUse = "text";
+          }
+        }
+        const html = highlighter2.codeToHtml(code, {
+          lang: langToUse,
+          theme: "github-dark"
+        });
+        return html.replace(/background-color:[^;]+;?/g, "");
+      }
+    })
+  );
+  marked.setOptions({ gfm: true, breaks: false });
+  markedConfigured = true;
+}
+async function parseMarkdownSSRAsync(content) {
+  await configureMarked();
+  const rawHtml = await marked.parse(content, { async: true });
+  return DOMPurify.sanitize(rawHtml, {
+    USE_PROFILES: { html: true },
+    FORBID_TAGS: ["script", "style", "iframe"],
+    FORBID_ATTR: ["onerror", "onload", "onclick"]
+  });
+}
+
 // src/renderer.ts
 var VOID_ELEMENTS = /* @__PURE__ */ new Set([
   "area",
@@ -157,8 +195,30 @@ function evaluate(expr, ctx) {
       }
       return importData;
     }
+    case "data": {
+      const dataValue = ctx.imports?.[expr.name];
+      if (dataValue === void 0) return void 0;
+      if (expr.path) {
+        return getNestedValue(dataValue, expr.path);
+      }
+      return dataValue;
+    }
     case "ref":
       return null;
+    case "index": {
+      const forbiddenKeys = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+      const base = evaluate(expr.base, ctx);
+      const key = evaluate(expr.key, ctx);
+      if (base == null || key == null) return void 0;
+      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)}`);
@@ -270,9 +330,11 @@ async function renderNode(node, ctx) {
     case "each":
       return await renderEach(node, ctx);
     case "markdown":
-      return renderMarkdown(node, ctx);
+      return await renderMarkdown(node, ctx);
     case "code":
       return await renderCode(node, ctx);
+    case "slot":
+      return "";
     default: {
       const _exhaustiveCheck = node;
       throw new Error(`Unknown node kind: ${JSON.stringify(_exhaustiveCheck)}`);
@@ -350,25 +412,33 @@ async function renderEach(node, ctx) {
   }
   return result;
 }
-function renderMarkdown(node, ctx) {
+async function renderMarkdown(node, ctx) {
   const content = evaluate(node.content, ctx);
-  const html = parseMarkdownSSR(formatValue(content));
+  const html = await parseMarkdownSSRAsync(formatValue(content));
   return `<div class="constela-markdown">${html}</div>`;
 }
 async function renderCode(node, ctx) {
   const language = formatValue(evaluate(node.language, ctx));
   const content = formatValue(evaluate(node.content, ctx));
-  const html = await renderCodeSSR(content, language);
-  return `<div class="constela-code">${html}</div>`;
+  const highlightedCode = await renderCodeSSR(content, language);
+  const languageBadge = language ? `<div class="absolute right-12 top-3 z-10 rounded bg-muted-foreground/20 px-2 py-0.5 text-xs font-medium text-muted-foreground">${escapeHtml(language)}</div>` : "";
+  const copyButton = `<button class="constela-copy-btn absolute right-3 top-3 z-10 flex h-8 w-8 items-center justify-center rounded-md border border-border bg-background/80 opacity-0 transition-opacity hover:bg-muted group-hover:opacity-100" data-copy-target="code" aria-label="Copy code"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="h-4 w-4"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg></button>`;
+  return `<div class="constela-code" data-code-content="${escapeHtml(content)}"><div class="group relative">${languageBadge}${copyButton}${highlightedCode}</div></div>`;
 }
-async function renderToString(program) {
+async function renderToString(program, options) {
   const state = /* @__PURE__ */ new Map();
   for (const [name, field] of Object.entries(program.state)) {
     state.set(name, field.initial);
   }
   const ctx = {
     state,
-    locals: {}
+    locals: {},
+    route: options?.route ? {
+      params: options.route.params ?? {},
+      query: options.route.query ?? {},
+      path: options.route.path ?? ""
+    } : void 0,
+    imports: options?.imports ?? program.importData
   };
   return await renderNode(program.view, ctx);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constela/server",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Server-side rendering for Constela UI framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,11 +15,12 @@
     "dist"
   ],
   "peerDependencies": {
-    "@constela/compiler": "^0.7.0"
+    "@constela/compiler": "^0.8.0"
   },
   "dependencies": {
     "isomorphic-dompurify": "^2.35.0",
     "marked": "^17.0.1",
+    "marked-shiki": "^1.2.0",
     "shiki": "^1.0.0"
   },
   "devDependencies": {
@@ -27,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"