@causyne/agent 1.10.19 → 1.10.21

package/src/tui/banner.js

@@ -237,7 +237,9 @@ function shortPath(p, maxw) {
 }
 function statusLine(info, maxw, unicode) {
     const sep = unicode ? '  ·  ' : '  |  ';
-    const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', [info.provider, info.model].filter(Boolean).join('/'), info.mode ?? '', info.cwd ?? ''].filter(Boolean);
+    const providerModel = [info.provider, info.model].filter(Boolean).join('/');
+    const providerPart = providerModel || 'select provider';
+    const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', providerPart, info.mode ?? '', info.cwd ?? ''].filter(Boolean);
     const fits = () => parts.join(sep).length <= maxw;
     if (!fits() && info.cwd) {
         const others = parts.slice(0, -1).join(sep).length + (parts.length > 1 ? sep.length : 0);

package/src/tui/banner.ts

@@ -240,7 +240,9 @@ function shortPath(p: string, maxw: number): string {
 }
 function statusLine(info: BannerInfo, maxw: number, unicode: boolean): string {
   const sep = unicode ? '  ·  ' : '  |  ';
-  const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', [info.provider, info.model].filter(Boolean).join('/'), info.mode ?? '', info.cwd ?? ''].filter(Boolean);
+  const providerModel = [info.provider, info.model].filter(Boolean).join('/');
+  const providerPart = providerModel || 'select provider';
+  const parts = [info.version ? 'v' + String(info.version).replace(/^v/, '') : '', providerPart, info.mode ?? '', info.cwd ?? ''].filter(Boolean);
   const fits = (): boolean => parts.join(sep).length <= maxw;
   if (!fits() && info.cwd) {
     const others = parts.slice(0, -1).join(sep).length + (parts.length > 1 ? sep.length : 0);

package/src/tui/dialogs.js

@@ -38,9 +38,17 @@ export class SelectLayer extends Layer {
       emptyText: options.emptyText
     });
     this.onPick = options.onPick || null;
+    this.settled = false;
     this.footer = options.footer || dialogHint();
   }
 
+  /** Dismissal must resolve pending picker flows, just like text inputs. */
+  answer() {
+    if (this.settled) return;
+    this.settled = true;
+    if (this.onPick) this.onPick(null);
+  }
+
   preferredHeight() {
     // filter row + rule + one row per item (+ its category header) + frame.
     const categories = new Set(this.list.filtered.map((entry) => entry.item.category).filter(Boolean));
@@ -66,7 +74,9 @@ export class SelectLayer extends Layer {
 
     if (action === 'select') {
       const item = this.list.current;
+      this.settled = true;
       const result = this.onPick ? this.onPick(item) : null;
+      if (result === 'keep') this.settled = false;
       return result === 'keep' ? 'handled' : 'close';
     }
     if (action === 'cancel') return 'close';

package/src/tui/home.js

@@ -2,15 +2,21 @@
 
 import { SelectLayer, InputLayer } from './dialogs.js';
 import { paint, dim, bold, badge, GLYPHS } from './theme.js';
+import { runSetup } from './setup.js';
 import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
 
 /** Local runtime and provider summary. */
 export function homeStatusLine({ config = {} } = {}) {
-  const model = config.model ? `${config.provider || 'default'}/${config.model}` : (config.provider || 'no provider');
-  const configured = config.apiKey || config.provider === 'ollama';
+  const hasProvider = Boolean(config.provider && config.provider !== 'unconfigured');
+  const model = hasProvider
+    ? (config.model ? `${config.provider}/${config.model}` : config.provider)
+    : 'no provider configured';
+  const configured = Boolean((hasProvider && config.apiKey) || config.provider === 'ollama');
   return '  ' + [
     paint('success', `${GLYPHS.bullet} local desktop`),
-    configured ? dim(model) : paint('warn', `${model} — no key`)
+    configured
+      ? dim(model)
+      : (hasProvider ? paint('warn', `${model} — no key`) : paint('warn', 'no provider configured — run /setup'))
   ].join(dim(`  ${GLYPHS.dot}  `));
 }
 
@@ -41,7 +47,7 @@ export const PRIMARY_ACTIONS = [
     kind: 'stay',
     run: async () => (await import('../reporting.js')).buildUsageText()
   },
-  { id: 'config', label: 'config', hint: 'provider, model, API key', kind: 'config' },
+  { id: 'config', label: 'setup', hint: 'provider · endpoint · model · permissions', kind: 'config' },
   { id: 'more', label: 'more…', hint: 'sessions · model · approvals · tools', kind: 'more' }
 ];
 
@@ -70,6 +76,13 @@ export const MORE_ACTIONS = [
     // be the one path around the gate.
     command: '/undo'
   },
+  {
+    id: 'creative', label: 'creative apps', category: 'tools', hint: 'check installed apps and adapter readiness', kind: 'stay',
+    run: async () => {
+      const { creativeAppStatus } = await import('../creative/apps.js');
+      return (await creativeAppStatus()).map(app => `${app.label}: ${app.available ? 'available' : 'not connected'}\n  ${app.detail}`).join('\n');
+    }
+  },
   { id: 'mcp', label: 'mcp', category: 'tools', hint: 'manage MCP servers', kind: 'mcp' },
   { id: 'help', label: 'commands', category: 'tools', hint: 'show every slash command', kind: 'command', command: '/help' },
   {
@@ -111,16 +124,8 @@ export function homeHint() {
 export { badge };
 
 // ---------------------------------------------------------------------------
-// The two flows that need a keyboard
+// Provider setup and MCP navigation
 //
-// Both of these used inquirer, which takes stdin while ChatPrompt is already
-// holding it in raw mode — the two contend and the question lands on a
-// half-drawn prompt. Inside home there IS a live region and a modal stack, so
-// they can be asked properly. `causyne config` invoked on its own still uses the
-// inquirer wizard, because standalone there is no live region to draw into and
-// building a second one is how the deleted alt-screen shell started.
-// ---------------------------------------------------------------------------
-
 /** Provider choices for local CLI configuration. */
 // Suggested models come from src/modelCatalogue.js rather than being repeated
 // here. This list had drifted to `gpt-4o` and `gemini-2.5-pro` — two
@@ -140,65 +145,17 @@ export const PROVIDERS = [
   { id: 'ollama', label: 'Ollama', hint: 'local / offline' }
 ].map((entry) => ({ ...entry, model: DEFAULT_MODEL_BY_PROVIDER[entry.id] ?? '' }));
 
-/**
- * Ask for provider, then model, then key — each in the prompt's own panel.
- *
- * Resolves when the last answer is in, or when any step is dismissed. Dismissing
- * cancels the whole flow rather than saving a half-configuration, because a
- * provider saved without its key leaves the agent in a state that fails on the
- * next turn with an error about credentials rather than about the cancel.
- */
-export function configureInPrompt(prompt, { loadConfig, saveConfig }) {
-  return new Promise((resolve) => {
-    const config = loadConfig();
-
-    prompt.openLayer(new SelectLayer({
-      title: 'provider',
-      items: PROVIDERS.map((p) => ({ id: p.id, label: p.label, description: p.hint, value: p })),
-      onPick: (item) => {
-        if (!item) { resolve(null); return; }
-        const provider = item.value;
-        askModel(provider);
-      }
-    }));
-
-    function askModel(provider) {
-      const suggested = (config.provider === provider.id && config.model) ? config.model : provider.model;
-      prompt.openLayer(new InputLayer({
-        title: `model for ${provider.label}`,
-        lines: [
-          'Model ids change often. Type the one you want, or accept the suggestion.'
-        ],
-        value: suggested,
-        placeholder: 'model id',
-        onSubmit: (model) => askKey(provider, (model || '').trim() || suggested),
-        onCancel: () => resolve(null)
-      }));
-    }
-
-    function askKey(provider, model) {
-      prompt.openLayer(new InputLayer({
-        title: 'API key',
-        lines: [
-          `${provider.label} ${GLYPHS.arrow} ${model}`,
-          '',
-          'Stored encrypted in ~/.causyne/config.json. It never leaves this machine.'
-        ],
-        mask: true,
-        value: '',
-        placeholder: 'paste your key (blank keeps the current one)',
-        onSubmit: (apiKey) => {
-          const next = loadConfig();
-          next.provider = provider.id;
-          next.model = model;
-          if (apiKey) next.apiKey = apiKey;
-          saveConfig(next);
-          resolve({ provider: provider.id, model });
-        },
-        onCancel: () => resolve(null)
-      }));
-    }
-  });
+/** Run the shared setup transaction inside the existing prompt. */
+export function configureInPrompt(prompt, store) {
+  return runSetup({
+    select: (options) => new Promise((resolve) => {
+      const layer = new SelectLayer({ ...options, onPick: resolve });
+      prompt.openLayer(layer);
+    }),
+    text: (options) => new Promise((resolve) => {
+      prompt.openLayer(new InputLayer({ ...options, onSubmit: resolve, onCancel: () => resolve(null) }));
+    })
+  }, PROVIDERS, store);
 }
 
 /** The MCP server list, as something you can act on rather than read. */

package/src/tui/setup.js

@@ -0,0 +1,104 @@
+const string = (value) => typeof value === 'string' ? value : '';
+const customProviders = new Set(['openai-compatible', 'dashscope-byok', 'ollama']);
+const defaults = {
+    ollama: 'http://localhost:11434/api/chat',
+    'dashscope-byok': 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions'
+};
+export function validateEndpoint(value) {
+    try {
+        const url = new URL(value);
+        if (url.username || url.password || url.search || url.hash)
+            return 'Use an endpoint without credentials, query parameters, or a fragment.';
+        const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+            return 'Use HTTPS, or HTTP on localhost for a local model.';
+        return null;
+    }
+    catch {
+        return 'Enter a complete endpoint URL.';
+    }
+}
+export async function runSetup(ui, providers, store, workspace = process.cwd()) {
+    const original = store.loadConfig();
+    let draft = { ...original };
+    async function text(title, lines, value = '', mask = false, validate = () => null) {
+        let error = null;
+        for (;;) {
+            const answer = await ui.text({ title, lines: error ? [...lines, error] : lines, value,
+                placeholder: mask ? 'paste key' : '', mask });
+            if (answer === null)
+                return null;
+            const cleaned = answer.trim();
+            error = /[\x00-\x1f\x7f]/.test(cleaned) ? 'Use a single line without control characters.' : validate(cleaned);
+            if (!error)
+                return cleaned;
+            value = mask ? '' : cleaned;
+        }
+    }
+    for (;;) {
+        const selected = await ui.select({ title: 'Setup 1/5 · provider', items: providers.map(p => ({ id: p.id, label: p.label, description: p.hint })) });
+        if (!selected)
+            return null;
+        const provider = providers.find(p => p.id === selected.id);
+        if (!provider)
+            return null;
+        const sameProvider = draft.provider === provider.id;
+        let baseUrl = '';
+        if (customProviders.has(provider.id)) {
+            const answer = await text('Setup 2/5 · endpoint', ['Full chat endpoint URL, including /v1/chat/completions or /api/chat.',
+                'Credentials are sent to this endpoint when you use the model.'], (sameProvider ? string(draft.baseUrl) : '') || defaults[provider.id] || '', false, validateEndpoint);
+            // No network request is made by setup.
+            if (answer === null)
+                return null;
+            baseUrl = answer;
+        }
+        const model = await text('Setup 3/5 · model', ['Enter the model ID supported by your provider.'], (sameProvider ? string(draft.model) : '') || provider.model, false, value => value ? null : 'A model ID is required.');
+        if (model === null)
+            return null;
+        const unchangedEndpoint = sameProvider && (string(draft.baseUrl) || defaults[provider.id] || '') === baseUrl;
+        // Fixed endpoints have no editable URL. A changed endpoint never inherits a key.
+        const keepKey = sameProvider && (!customProviders.has(provider.id) || unchangedEndpoint);
+        let apiKey = '';
+        if (provider.id !== 'ollama') {
+            const oldKey = keepKey ? string(draft.apiKey) : '';
+            const answer = await text('Setup 3/5 · credentials', ['Stored encrypted locally; used to authenticate with your selected provider.',
+                oldKey ? 'Blank keeps the key for this same provider and endpoint.' : 'Enter a key for this provider.',
+                provider.id === 'openai-compatible' ? 'Blank is allowed for an endpoint that needs no authentication.' : ''], '', true, value => value || oldKey || provider.id === 'openai-compatible' ? null : 'An API key is required.');
+            if (answer === null)
+                return null;
+            apiKey = answer || oldKey;
+        }
+        const mode = await ui.select({ title: 'Setup 4/5 · autonomy', items: [
+                { id: 'B', label: 'B · Supervised (Standard)', description: 'Recommended. Approval for dangerous actions; routine work continues.' },
+                { id: 'A', label: 'A · Ask first (Strict)', description: 'Explicit confirmation before every tool call.' },
+                { id: 'C', label: 'C · Autonomous (High Velocity)', description: 'Fewer interruptions; mandatory safety and decision gates remain.' }
+            ] });
+        if (!mode || !['A', 'B', 'C'].includes(mode.id))
+            return null;
+        draft = { ...draft, provider: provider.id, model, apiKey, autonomyMode: mode.id };
+        if (baseUrl)
+            draft.baseUrl = baseUrl;
+        else
+            delete draft.baseUrl;
+        const review = await ui.select({ title: 'Setup 5/5 · review', items: [
+                { id: 'save', label: 'Save configuration', description: `${provider.label} · ${model} · Mode ${mode.id}` },
+                { id: 'edit', label: 'Edit choices', description: baseUrl || 'Provider default endpoint' },
+                { id: 'cancel', label: 'Cancel without saving', description: `Workspace: ${workspace}` }
+            ] });
+        if (!review || review.id === 'cancel')
+            return null;
+        if (review.id === 'edit')
+            continue;
+        if (review.id !== 'save')
+            return null;
+        // Preserve unrelated settings changed while the dialog was open.
+        const next = { ...store.loadConfig(), provider: draft.provider, model, apiKey, autonomyMode: mode.id };
+        const saved = next;
+        if (baseUrl)
+            saved.baseUrl = baseUrl;
+        else
+            delete saved.baseUrl;
+        store.saveConfig(saved);
+        return { provider: provider.id, model };
+    }
+}

package/src/tui/setup.ts

@@ -0,0 +1,98 @@
+/** Shared setup transaction for the home panel and standalone CLI. */
+export interface SetupChoice { id: string; label: string; description?: string }
+export interface SetupProvider { id: string; label: string; hint: string; model: string }
+export interface SetupUI {
+  select(options: { title: string; items: SetupChoice[] }): Promise<SetupChoice | null>;
+  text(options: { title: string; lines: string[]; value: string; placeholder: string; mask: boolean }): Promise<string | null>;
+}
+type Config = Record<string, unknown>;
+const string = (value: unknown): string => typeof value === 'string' ? value : '';
+const customProviders = new Set(['openai-compatible', 'dashscope-byok', 'ollama']);
+const defaults: Record<string, string> = {
+  ollama: 'http://localhost:11434/api/chat',
+  'dashscope-byok': 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions'
+};
+
+export function validateEndpoint(value: string): string | null {
+  try {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash) return 'Use an endpoint without credentials, query parameters, or a fragment.';
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) return 'Use HTTPS, or HTTP on localhost for a local model.';
+    return null;
+  } catch { return 'Enter a complete endpoint URL.'; }
+}
+
+export async function runSetup(ui: SetupUI, providers: SetupProvider[], store: {
+  loadConfig(): Config; saveConfig(config: Config): void;
+}, workspace = process.cwd()): Promise<{ provider: string; model: string } | null> {
+  const original = store.loadConfig();
+  let draft: Config = { ...original };
+  async function text(title: string, lines: string[], value = '', mask = false,
+    validate: (answer: string) => string | null = () => null): Promise<string | null> {
+    let error: string | null = null;
+    for (;;) {
+      const answer = await ui.text({ title, lines: error ? [...lines, error] : lines, value,
+        placeholder: mask ? 'paste key' : '', mask });
+      if (answer === null) return null;
+      const cleaned = answer.trim();
+      error = /[\x00-\x1f\x7f]/.test(cleaned) ? 'Use a single line without control characters.' : validate(cleaned);
+      if (!error) return cleaned;
+      value = mask ? '' : cleaned;
+    }
+  }
+  for (;;) {
+    const selected = await ui.select({ title: 'Setup 1/5 · provider', items: providers.map(p => ({ id: p.id, label: p.label, description: p.hint })) });
+    if (!selected) return null;
+    const provider = providers.find(p => p.id === selected.id);
+    if (!provider) return null;
+    const sameProvider = draft.provider === provider.id;
+    let baseUrl = '';
+    if (customProviders.has(provider.id)) {
+      const answer = await text('Setup 2/5 · endpoint', ['Full chat endpoint URL, including /v1/chat/completions or /api/chat.',
+        'Credentials are sent to this endpoint when you use the model.'],
+      (sameProvider ? string(draft.baseUrl) : '') || defaults[provider.id] || '', false, validateEndpoint);
+      // No network request is made by setup.
+      if (answer === null) return null;
+      baseUrl = answer;
+    }
+    const model = await text('Setup 3/5 · model', ['Enter the model ID supported by your provider.'],
+      (sameProvider ? string(draft.model) : '') || provider.model, false, value => value ? null : 'A model ID is required.');
+    if (model === null) return null;
+    const unchangedEndpoint = sameProvider && (string(draft.baseUrl) || defaults[provider.id] || '') === baseUrl;
+    // Fixed endpoints have no editable URL. A changed endpoint never inherits a key.
+    const keepKey = sameProvider && (!customProviders.has(provider.id) || unchangedEndpoint);
+    let apiKey = '';
+    if (provider.id !== 'ollama') {
+      const oldKey = keepKey ? string(draft.apiKey) : '';
+      const answer = await text('Setup 3/5 · credentials', ['Stored encrypted locally; used to authenticate with your selected provider.',
+        oldKey ? 'Blank keeps the key for this same provider and endpoint.' : 'Enter a key for this provider.',
+        provider.id === 'openai-compatible' ? 'Blank is allowed for an endpoint that needs no authentication.' : ''], '', true,
+      value => value || oldKey || provider.id === 'openai-compatible' ? null : 'An API key is required.');
+      if (answer === null) return null;
+      apiKey = answer || oldKey;
+    }
+    const mode = await ui.select({ title: 'Setup 4/5 · autonomy', items: [
+      { id: 'B', label: 'B · Supervised (Standard)', description: 'Recommended. Approval for dangerous actions; routine work continues.' },
+      { id: 'A', label: 'A · Ask first (Strict)', description: 'Explicit confirmation before every tool call.' },
+      { id: 'C', label: 'C · Autonomous (High Velocity)', description: 'Fewer interruptions; mandatory safety and decision gates remain.' }
+    ] });
+    if (!mode || !['A', 'B', 'C'].includes(mode.id)) return null;
+    draft = { ...draft, provider: provider.id, model, apiKey, autonomyMode: mode.id };
+    if (baseUrl) draft.baseUrl = baseUrl; else delete draft.baseUrl;
+    const review = await ui.select({ title: 'Setup 5/5 · review', items: [
+      { id: 'save', label: 'Save configuration', description: `${provider.label} · ${model} · Mode ${mode.id}` },
+      { id: 'edit', label: 'Edit choices', description: baseUrl || 'Provider default endpoint' },
+      { id: 'cancel', label: 'Cancel without saving', description: `Workspace: ${workspace}` }
+    ] });
+    if (!review || review.id === 'cancel') return null;
+    if (review.id === 'edit') continue;
+    if (review.id !== 'save') return null;
+    // Preserve unrelated settings changed while the dialog was open.
+    const next = { ...store.loadConfig(), provider: draft.provider, model, apiKey, autonomyMode: mode.id };
+    const saved: Config = next;
+    if (baseUrl) saved.baseUrl = baseUrl; else delete saved.baseUrl;
+    store.saveConfig(saved);
+    return { provider: provider.id, model };
+  }
+}

package/src/uiEngine/uiForge.js

@@ -0,0 +1,211 @@
+/*
+ * Copyright (c) 2011-2024 Thesys Inc.
+ * SPDX-License-Identifier: MIT
+ *
+ * Adapted for Causyne UI Forge — Generative Component & Design Engine.
+ */
+/**
+ * Generate semantic, modern HTML + CSS component code under Causyne UI Forge.
+ */
+export function generateHtmlComponent(spec) {
+    const isDark = spec.theme !== 'light';
+    const cardBg = isDark ? 'rgba(30, 41, 59, 0.75)' : 'rgba(255, 255, 255, 0.95)';
+    const border = isDark ? 'rgba(255, 255, 255, 0.12)' : 'rgba(0, 0, 0, 0.1)';
+    const text = isDark ? '#f8fafc' : '#0f172a';
+    const textMuted = isDark ? '#94a3b8' : '#64748b';
+    const accent = '#6366f1';
+    const accentHover = '#4f46e5';
+    const css = `
+/* Causyne UI Forge Generated Styles - Responsive, Accessible & Performant */
+.causyne-ui-root {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  color: ${text};
+  line-height: 1.5;
+  box-sizing: border-box;
+}
+.causyne-ui-root * { box-sizing: border-box; margin: 0; padding: 0; }
+.causyne-ui-card {
+  background: ${cardBg};
+  backdrop-filter: blur(12px);
+  border: 1px solid ${border};
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.2), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+.causyne-ui-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 20px 30px -10px rgba(0, 0, 0, 0.3);
+}
+.causyne-ui-header { margin-bottom: 16px; }
+.causyne-ui-title { font-size: 1.25rem; font-weight: 600; letter-spacing: -0.02em; }
+.causyne-ui-desc { font-size: 0.875rem; color: ${textMuted}; margin-top: 4px; }
+.causyne-ui-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin: 16px 0; }
+.causyne-ui-stat-box {
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid ${border};
+  border-radius: 8px;
+  padding: 16px;
+}
+.causyne-ui-stat-label { font-size: 0.75rem; text-transform: uppercase; letter-spacing: 0.05em; color: ${textMuted}; }
+.causyne-ui-stat-value { font-size: 1.75rem; font-weight: 700; color: ${accent}; margin-top: 4px; }
+.causyne-ui-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 16px;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  font-weight: 500;
+  cursor: pointer;
+  border: 1px solid transparent;
+  transition: all 0.15s ease;
+}
+.causyne-ui-btn-primary { background: ${accent}; color: #ffffff; }
+.causyne-ui-btn-primary:hover { background: ${accentHover}; }
+.causyne-ui-btn-secondary { background: transparent; border-color: ${border}; color: ${text}; }
+.causyne-ui-btn-secondary:hover { background: rgba(255, 255, 255, 0.05); }
+.causyne-ui-actions { display: flex; gap: 8px; margin-top: 20px; justify-content: flex-end; }
+`.trim();
+    let html = '';
+    const title = spec.title || 'Component';
+    const desc = spec.description || '';
+    if (spec.type === 'dashboard-stats' || (spec.items && spec.items.length > 0)) {
+        const itemsHtml = (spec.items || [])
+            .map((item) => `
+    <div class="causyne-ui-stat-box">
+      <div class="causyne-ui-stat-label">${escapeHtml(item.label)}</div>
+      <div class="causyne-ui-stat-value">${escapeHtml(String(item.value ?? '—'))}</div>
+      ${item.description ? `<div class="causyne-ui-desc">${escapeHtml(item.description)}</div>` : ''}
+    </div>`)
+            .join('\n');
+        html = `
+<div class="causyne-ui-root">
+  <div class="causyne-ui-card">
+    <div class="causyne-ui-header">
+      <h3 class="causyne-ui-title">${escapeHtml(title)}</h3>
+      ${desc ? `<p class="causyne-ui-desc">${escapeHtml(desc)}</p>` : ''}
+    </div>
+    <div class="causyne-ui-grid">
+${itemsHtml}
+    </div>
+    ${renderActions(spec.actions)}
+  </div>
+</div>`.trim();
+    }
+    else {
+        html = `
+<div class="causyne-ui-root">
+  <div class="causyne-ui-card">
+    <div class="causyne-ui-header">
+      <h3 class="causyne-ui-title">${escapeHtml(title)}</h3>
+      ${desc ? `<p class="causyne-ui-desc">${escapeHtml(desc)}</p>` : ''}
+    </div>
+    ${renderActions(spec.actions)}
+  </div>
+</div>`.trim();
+    }
+    return { html, css };
+}
+function renderActions(actions) {
+    if (!actions || actions.length === 0)
+        return '';
+    const btns = actions
+        .map((a) => `<button class="causyne-ui-btn ${a.primary ? 'causyne-ui-btn-primary' : 'causyne-ui-btn-secondary'}" data-action="${escapeHtml(a.action)}">${escapeHtml(a.label)}</button>`)
+        .join('\n      ');
+    return `
+    <div class="causyne-ui-actions">
+      ${btns}
+    </div>`;
+}
+function escapeHtml(str) {
+    return String(str || '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * Generate full self-contained preview document.
+ */
+export function generatePreviewHtml(html, css, theme = 'dark') {
+    const bg = theme === 'dark' ? '#0b0f19' : '#f1f5f9';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Causyne UI Forge Preview</title>
+  <style>
+    body {
+      margin: 0;
+      padding: 40px 20px;
+      min-height: 100vh;
+      background: ${bg};
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      box-sizing: border-box;
+    }
+    ${css}
+  </style>
+</head>
+<body>
+  ${html}
+</body>
+</html>`;
+}
+/**
+ * Generate React + Tailwind component code under Causyne UI Forge.
+ */
+export function generateReactComponent(spec) {
+    const compName = (spec.name || 'CausyneCard').replace(/[^a-zA-Z0-9]/g, '');
+    const title = spec.title || 'Component';
+    const desc = spec.description || '';
+    return `import React from 'react';
+
+export interface ${compName}Props {
+  title?: string;
+  description?: string;
+}
+
+export const ${compName}: React.FC<${compName}Props> = ({
+  title = "${title}",
+  description = "${desc}"
+}) => {
+  return (
+    <div className="rounded-xl border border-slate-700/60 bg-slate-900/80 p-6 backdrop-blur-md shadow-xl transition-all hover:shadow-2xl">
+      <div className="mb-4">
+        <h3 className="text-xl font-semibold tracking-tight text-white">{title}</h3>
+        {description && <p className="mt-1 text-sm text-slate-400">{description}</p>}
+      </div>
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3 my-4">
+        ${(spec.items || [])
+        .map((item) => `
+        <div key="${item.id || item.label}" className="rounded-lg border border-slate-800 bg-slate-800/40 p-4">
+          <div className="text-xs font-medium uppercase tracking-wider text-slate-400">${item.label}</div>
+          <div className="mt-1 text-2xl font-bold text-indigo-400">${item.value ?? '—'}</div>
+          ${item.description ? `<p className="mt-1 text-xs text-slate-500">${item.description}</p>` : ''}
+        </div>`)
+        .join('')}
+      </div>
+      ${(spec.actions && spec.actions.length > 0)
+        ? `
+      <div className="mt-6 flex justify-end gap-3">
+        ${spec.actions
+            .map((a) => `
+        <button className="px-4 py-2 text-sm font-medium rounded-lg transition-colors ${a.primary
+            ? 'bg-indigo-600 text-white hover:bg-indigo-500'
+            : 'border border-slate-700 text-slate-300 hover:bg-slate-800'}">
+          ${a.label}
+        </button>`)
+            .join('')}
+      </div>`
+        : ''}
+    </div>
+  );
+};
+
+export default ${compName};
+`;
+}