cyrus-studio 1.0.6 → 1.0.8

package/README.md

@@ -1,113 +1,155 @@
-# Cyrus Studio — AI Visual Product Builder & Multi-Framework Code Generator
+# cyrus-studio
 
 <p align="center">
   <a href="https://cyrustudio.vercel.app"><img src="https://img.shields.io/badge/Live_App-cyrustudio.vercel.app-6366f1?style=for-the-badge&logo=vercel&logoColor=white" alt="Live Demo" /></a>
   <a href="https://www.npmjs.com/package/cyrus-studio"><img src="https://img.shields.io/npm/v/cyrus-studio?style=for-the-badge&color=blue" alt="NPM Version" /></a>
   <a href="https://www.npmjs.com/package/cyrus-studio"><img src="https://img.shields.io/npm/dm/cyrus-studio?style=for-the-badge&color=green" alt="NPM Downloads" /></a>
-  <a href="https://github.com/cyrus-studio/cyrus"><img src="https://img.shields.io/badge/License-MIT-amber?style=for-the-badge" alt="License" /></a>
+  <img src="https://img.shields.io/badge/License-MIT-amber?style=for-the-badge" alt="License" />
 </p>
 
+> **AI Visual Canvas Studio** — Embed Cyrus in any React app, generate full UIs from prompts, and export clean code for React, Flutter, SwiftUI & HTML.
+
+🚀 **Try the Live App**: **[https://cyrustudio.vercel.app](https://cyrustudio.vercel.app)**
+
 ---
 
-**Cyrus Studio** is a modern visual product builder that lets designers and developers create production-ready user interfaces on a visual canvas, preview them in real time, and export clean, maintainable source code for **React / Next.js**, **Flutter**, **SwiftUI**, and **HTML / Tailwind CSS**.
+## Install
 
-🚀 **Try the Live Cloud App**: **[https://cyrustudio.vercel.app](https://cyrustudio.vercel.app)**
+```bash
+npm install cyrus-studio
+```
+
+> **Peer dependencies required**: `react >= 18` and `react-dom >= 18`
 
 ---
 
-## ✨ Features
+## Usage
 
-- 🎨 **Visual Canvas & Drag-and-Drop Editor**: Build complex UIs with intuitive positioning, flex layouts, smart alignment guides, multi-selection, and layered hierarchy.
-- ⚡ **Multi-Framework Code Generation**:
-  - ⚛️ **React / Next.js** (Tailwind CSS, TypeScript)
-  - 📱 **Flutter / Dart** (Widget tree with theme binding)
-  - 🍎 **SwiftUI** (Native declarative iOS/macOS views)
-  - 🌐 **Clean HTML5 / CSS** (Semantic layout with Tailwind)
-- 🤖 **AI Design & Code Copilot**: Integrate OpenAI, Google Gemini, Anthropic Claude, or local Ollama models to generate layouts, copy, and components via natural language.
-- 👥 **Real-Time Multiplayer Collaboration**: Multiplayer room with live cursor tracking, conflict resolution, and commenting.
-- 📐 **Responsive Viewport Controls**: Instant switching between Desktop (1440px), Tablet (768px), and Mobile (390px) viewports with auto-scaling.
-- 🌗 **Design Systems & Theme Engine**: Global color palettes, typography tokens, component instances, and dynamic light/dark mode preview.
-- 📦 **One-Click Export**: Download structured ZIP bundles, export individual page source files, or save high-resolution PNG/PDF artboards.
+### 1. Embed the Cyrus Canvas in your React App
 
----
+```tsx
+import { CyrusCanvasIframe } from 'cyrus-studio';
 
-## 🚀 Quick Start
+export default function App() {
+  return (
+    <CyrusCanvasIframe
+      hostUrl="https://cyrustudio.vercel.app"
+      projectId="my-project"
+      theme="dark"
+      style={{ height: '800px' }}
+      onStateChange={(state) => console.log('Canvas state:', state)}
+    />
+  );
+}
+```
 
-### Option 1: Use the Live Web App (No Setup Required)
-Open **[https://cyrustudio.vercel.app](https://cyrustudio.vercel.app)** in your browser and start designing immediately.
+### 2. Generate an Embed URL Programmatically
 
-### Option 2: Run Locally via Git / NPM
+```ts
+import { createCyrusEmbedUrl } from 'cyrus-studio';
 
-```bash
-# 1. Clone the repository
-git clone https://github.com/cyrus-studio/cyrus.git
-cd cyrus
+const url = createCyrusEmbedUrl({
+  hostUrl: 'https://cyrustudio.vercel.app',
+  projectId: 'landing-v2',
+  theme: 'light',
+  readOnly: true,
+});
+
+console.log(url);
+// https://cyrustudio.vercel.app/#/embed/landing-v2?theme=light&readOnly=true
+```
+
+### 3. Use the Cyrus IR (Intermediate Representation) Protocol
+
+The Cyrus IR is a universal JSON schema for AI-generated UIs. Use it to pass designs between your AI pipeline and the Cyrus canvas.
+
+```ts
+import {
+  validateAndRepairCyrusIR,
+  getCyrusLLMSystemPrompt,
+  type CyrusIRDocument,
+} from 'cyrus-studio';
 
-# 2. Install dependencies
-npm install
+// Get the system prompt to paste into your LLM
+const systemPrompt = getCyrusLLMSystemPrompt();
 
-# 3. Start development server
-npm run dev
+// Validate and repair raw LLM output
+const rawAiOutput = `{ "version": "1.0", "projectTitle": "My App", "pages": [...] }`;
+const doc: CyrusIRDocument = validateAndRepairCyrusIR(rawAiOutput);
+
+console.log(doc.pages[0].elements);
 ```
 
-Once started, open **`http://localhost:5173`** in your browser.
+---
+
+## API Reference
+
+### `CyrusCanvasIframe`
 
-- **Vite Web App**: Port `5173`
-- **Backend API Gateway**: Port `8787` (`/api` proxy)
+React component that embeds the Cyrus Visual Canvas as an iframe.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `hostUrl` | `string` | `http://localhost:5173` | URL of the Cyrus app |
+| `projectId` | `string` | `"demo"` | Project ID to load in canvas |
+| `theme` | `"light" \| "dark"` | `"light"` | Canvas color theme |
+| `onStateChange` | `(state: any) => void` | — | Callback fired when canvas state changes |
+| `style` | `CSSProperties` | — | Inline styles for the iframe |
+| `className` | `string` | — | CSS class for the iframe |
+
+All standard `<iframe>` HTML attributes are also supported.
 
 ---
 
-## ⚙️ Configuration & Environment Variables
+### `createCyrusEmbedUrl(options)`
 
-Copy `.env.example` to `.env` to configure optional integrations:
+Returns an embeddable URL string.
 
-```bash
-cp .env.example .env
+```ts
+createCyrusEmbedUrl({
+  projectId?: string;   // Project to load
+  hostUrl?: string;     // Cyrus host (default: localhost:5173)
+  theme?: 'light' | 'dark';
+  readOnly?: boolean;
+})
 ```
 
-| Variable | Description |
-| :--- | :--- |
-| `VITE_STRIPE_PUBLISHABLE_KEY` | Stripe Publishable Key for billing checkout. |
-| `STRIPE_SECRET_KEY` | Stripe Secret Key for serverless subscription sessions. |
-| `GEMINI_API_KEY` | Google Gemini API key for AI generation. |
-| `OPENAI_API_KEY` | OpenAI API key for GPT-4o design assistant. |
-| `ANTHROPIC_API_KEY` | Anthropic Claude API key. |
-| `JWT_SECRET` | Secret string for production session token signing. |
+---
 
-> **Note**: Cyrus Studio runs fully locally even without external API keys. Features requiring a specific provider will prompt for the key when used.
+### `validateAndRepairCyrusIR(rawInput)`
 
----
+Parses, validates, and repairs raw AI output (string or object) into a valid `CyrusIRDocument`. Safe to call with any LLM response — never throws.
 
-## 🛠️ Development & Testing Scripts
+---
 
-```bash
-# Start local development server (Client + Server concurrently)
-npm run dev
+### `getCyrusLLMSystemPrompt()`
 
-# Run TypeScript type checking
-npm run typecheck
+Returns the recommended system prompt string to paste into Claude, GPT-4, Gemini, or any other LLM so it outputs valid Cyrus IR JSON.
 
-# Run test suite with Vitest (90+ unit and integration tests)
-npm run test
+---
 
-# Build production bundle
-npm run build
+## TypeScript Types
 
-# Preview production build locally
-npm run preview
+```ts
+import type {
+  CyrusIRDocument,
+  CyrusIRPage,
+  CyrusIRElement,
+  CyrusIframeProps,
+} from 'cyrus-studio';
 ```
 
 ---
 
-## 📦 Tech Stack
+## CommonJS Support
 
-- **Frontend**: React 19, TypeScript, Tailwind CSS v4, Zustand, Lucide Icons, JSZip
-- **Build System**: Vite, PostCSS, Oxlint
-- **Backend & APIs**: Node.js, Vercel Serverless Functions, Firebase Auth / Cloud Firestore
-- **Testing**: Vitest, React Testing Library
+```js
+// Works with require() too
+const { CyrusCanvasIframe, createCyrusEmbedUrl } = require('cyrus-studio');
+```
 
 ---
 
-## 📄 License
+## License
 
-This project is licensed under the **[MIT License](LICENSE)**.
+MIT © [Cyrus Studio Team](https://cyrustudio.vercel.app)

package/bin/mcp-server.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+
+/**
+ * Cyrus Studio Model Context Protocol (MCP) CLI Entrypoint v1.0.8
+ * 
+ * Standalone JSON-RPC 2.0 / MCP Server for:
+ * - Claude Desktop
+ * - Cursor
+ * - Antigravity / Gemini CLI
+ * - Autonomous AI Agents
+ */
+
+import readline from 'node:readline';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+function generateId(prefix = 'el') {
+  return `${prefix}_${randomBytes(5).toString('hex')}`;
+}
+
+// ─── LOCAL ATOMIC PERSISTENCE ───────────────────────────────────────
+const DB_DIR = path.join(os.homedir(), '.cyrus-studio');
+const DB_FILE = path.join(DB_DIR, 'db.json');
+
+function loadMemoryDb() {
+  try {
+    if (!fs.existsSync(DB_DIR)) fs.mkdirSync(DB_DIR, { recursive: true });
+    if (fs.existsSync(DB_FILE)) {
+      return JSON.parse(fs.readFileSync(DB_FILE, 'utf8'));
+    }
+  } catch {}
+  return { version: 1, projects: [] };
+}
+
+function saveMemoryDb(db) {
+  try {
+    if (!fs.existsSync(DB_DIR)) fs.mkdirSync(DB_DIR, { recursive: true });
+    fs.writeFileSync(DB_FILE, JSON.stringify(db, null, 2), 'utf8');
+  } catch {}
+}
+
+// ─── MCP TOOL SCHEMAS ───────────────────────────────────────────────
+export const MCP_TOOLS = [
+  {
+    name: 'cyrus_generate_ui',
+    description: 'Generates a complete, structured visual UI page layout on the Cyrus Canvas from a text prompt. Creates the project, saves it, and returns the interactive canvas URLs and clean React code.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'Description of the UI to generate' },
+        type: { type: 'string', enum: ['webapp', 'website', 'dashboard', 'landing', 'mobile'], default: 'webapp' },
+        theme: { type: 'string', enum: ['light', 'dark'], default: 'dark' },
+        preset: { type: 'string', enum: ['apple-hig', 'shadcn-zinc', 'shadcn-slate', 'shadcn-violet', 'shadcn-rose', 'tailwind-cyberpunk'], default: 'shadcn-zinc' }
+      },
+      required: ['prompt']
+    }
+  },
+  {
+    name: 'cyrus_create_element',
+    description: 'Creates and places a new high-fidelity UI widget/component onto the Cyrus Canvas (navbar, hero, button, pricingCard, metricCard, lineChart, searchBar, container, footer).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string', description: 'Target project ID' },
+        type: { type: 'string', description: 'Component type' },
+        name: { type: 'string', description: 'Human-readable element label' },
+        x: { type: 'number' },
+        y: { type: 'number' },
+        width: { type: 'number' },
+        height: { type: 'number' },
+        styles: { type: 'object' },
+        content: { type: 'object' }
+      },
+      required: ['type']
+    }
+  },
+  {
+    name: 'cyrus_modify_element',
+    description: 'Updates specific visual styles, text content, or dimensions of an existing canvas element by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        elementId: { type: 'string' },
+        updates: { type: 'object' }
+      },
+      required: ['projectId', 'elementId', 'updates']
+    }
+  },
+  {
+    name: 'cyrus_delete_element',
+    description: 'Deletes an element from the Cyrus canvas by its element ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        elementId: { type: 'string' }
+      },
+      required: ['projectId', 'elementId']
+    }
+  },
+  {
+    name: 'cyrus_apply_design_system',
+    description: 'Applies global design system tokens (colors, typography, radii, theme presets) across the canvas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        preset: { type: 'string', enum: ['apple-hig', 'shadcn-zinc', 'shadcn-slate', 'shadcn-violet', 'shadcn-rose', 'tailwind-cyberpunk'] },
+        colors: { type: 'object' },
+        radii: { type: 'object' }
+      },
+      required: ['projectId']
+    }
+  },
+  {
+    name: 'cyrus_get_canvas_document',
+    description: 'Retrieves the complete structured Cyrus IR JSON document of a canvas project.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' }
+      }
+    }
+  },
+  {
+    name: 'cyrus_list_projects',
+    description: 'Lists all Cyrus Studio projects available with IDs, names, and preview URLs.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
+  },
+  {
+    name: 'cyrus_export_code',
+    description: 'Exports production-ready code (React + Tailwind CSS, Flutter, SwiftUI, or HTML + CSS) for the current visual canvas.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        projectId: { type: 'string' },
+        framework: { type: 'string', enum: ['react-tailwind', 'flutter', 'swiftui', 'html-css'], default: 'react-tailwind' }
+      },
+      required: ['projectId']
+    }
+  }
+];
+
+// ─── PURE ESM CODE GENERATOR ─────────────────────────────────────────
+function generateReactTailwindCode(page) {
+  const elements = page?.elements || [];
+  const componentName = (page?.name || 'Page').replace(/[^a-zA-Z0-9]/g, '') || 'CyrusApp';
+
+  const rendered = elements.map(el => {
+    const c = el.content || {};
+    return `      {/* ${el.name || el.type} */}
+      <div className="p-6 rounded-2xl border border-white/10 bg-neutral-900/60 shadow-xl">
+        <h3 className="text-xl font-bold text-white">${c.title || c.headline || c.text || el.name || 'Component'}</h3>
+      </div>`;
+  });
+
+  return `import React from 'react';
+
+export default function ${componentName}() {
+  return (
+    <div className="min-h-screen bg-[#09090b] text-neutral-100 p-8 space-y-6">
+${rendered.join('\n\n')}
+    </div>
+  );
+}`;
+}
+
+export async function handleToolCall(name, args = {}) {
+  const db = loadMemoryDb();
+
+  switch (name) {
+    case 'cyrus_generate_ui': {
+      const prompt = String(args.prompt || 'Modern Web Application').trim();
+      const theme = args.theme || 'dark';
+      const type = args.type || 'webapp';
+      const preset = args.preset || 'shadcn-zinc';
+      const projectId = `proj_${generateId()}`;
+
+      const elements = [
+        {
+          id: `el_${generateId()}`,
+          type: 'navbar',
+          name: 'Main Navigation Bar',
+          x: 40,
+          y: 30,
+          width: 1200,
+          height: 64,
+          styles: { backgroundColor: '#18181b', borderRadius: 12 },
+          content: { brandName: 'Cyrus Studio AI', buttonText: 'Launch App' }
+        },
+        {
+          id: `el_${generateId()}`,
+          type: 'hero',
+          name: 'Hero Section',
+          x: 40,
+          y: 110,
+          width: 1200,
+          height: 320,
+          styles: { backgroundColor: '#09090b', borderRadius: 16 },
+          content: {
+            badge: 'AI Generated Layout',
+            headline: prompt.slice(0, 60),
+            subtitle: `Generated for ${type.toUpperCase()} layout using ${preset} design tokens.`,
+            buttonText: 'Get Started'
+          }
+        },
+        {
+          id: `el_${generateId()}`,
+          type: 'pricingCard',
+          name: 'Subscription Plan',
+          x: 40,
+          y: 450,
+          width: 380,
+          height: 360,
+          styles: { backgroundColor: '#18181b', borderRadius: 16 },
+          content: {
+            badge: 'PRO TIER',
+            planName: 'Enterprise Engine',
+            price: '$49/mo',
+            features: ['Unlimited Canvas Projects', 'Real-time MCP Sync', 'React & Flutter Export']
+          }
+        }
+      ];
+
+      const page = { id: `page_${generateId()}`, name: 'Home', elements };
+      const projectDoc = {
+        id: projectId,
+        name: prompt.slice(0, 40),
+        version: '1.0.8',
+        theme,
+        type,
+        preset,
+        pages: [page],
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+      };
+
+      db.projects.push({ document: projectDoc });
+      saveMemoryDb(db);
+
+      return {
+        success: true,
+        projectId,
+        title: projectDoc.name,
+        elementCount: elements.length,
+        editorUrl: `https://cyrustudio.vercel.app/#/editor/${projectId}`,
+        previewUrl: `https://cyrustudio.vercel.app/#/embed/${projectId}?theme=${theme}`,
+        document: projectDoc,
+        code: generateReactTailwindCode(page)
+      };
+    }
+
+    case 'cyrus_create_element': {
+      let targetProj = db.projects[db.projects.length - 1]?.document;
+      if (args.projectId) {
+        const found = db.projects.find(p => p.document?.id === args.projectId);
+        if (found) targetProj = found.document;
+      }
+      if (!targetProj) {
+        targetProj = {
+          id: `proj_${generateId()}`,
+          name: 'Cyrus Project',
+          pages: [{ id: `page_${generateId()}`, name: 'Home', elements: [] }]
+        };
+        db.projects.push({ document: targetProj });
+      }
+
+      const activePage = targetProj.pages[0];
+      const newEl = {
+        id: `el_${generateId()}`,
+        type: args.type || 'button',
+        name: args.name || args.type || 'New Element',
+        x: args.x || 100,
+        y: args.y || 120,
+        width: args.width || 320,
+        height: args.height || 120,
+        styles: args.styles || { backgroundColor: '#18181b', borderRadius: 12 },
+        content: args.content || { title: args.name || 'New Widget' }
+      };
+
+      activePage.elements.push(newEl);
+      saveMemoryDb(db);
+
+      return { success: true, projectId: targetProj.id, createdElement: newEl, totalElements: activePage.elements.length };
+    }
+
+    case 'cyrus_modify_element': {
+      const { projectId, elementId, updates = {} } = args;
+      const proj = db.projects.find(p => p.document?.id === projectId);
+      if (!proj) throw new Error(`Project "${projectId}" not found.`);
+
+      let targetEl = null;
+      for (const page of (proj.document.pages || [])) {
+        targetEl = (page.elements || []).find(e => e.id === elementId);
+        if (targetEl) break;
+      }
+      if (!targetEl) throw new Error(`Element "${elementId}" not found.`);
+
+      if (updates.styles) targetEl.styles = { ...targetEl.styles, ...updates.styles };
+      if (updates.content) targetEl.content = { ...targetEl.content, ...updates.content };
+      saveMemoryDb(db);
+
+      return { success: true, projectId, elementId, updatedElement: targetEl };
+    }
+
+    case 'cyrus_list_projects': {
+      const list = (db.projects || []).map(p => ({
+        id: p.document?.id,
+        name: p.document?.name || 'Untitled',
+        previewUrl: `https://cyrustudio.vercel.app/#/embed/${p.document?.id}`
+      }));
+      return { success: true, count: list.length, projects: list };
+    }
+
+    case 'cyrus_export_code': {
+      const { projectId, framework = 'react-tailwind' } = args;
+      const proj = db.projects.find(p => p.document?.id === projectId);
+      if (!proj) throw new Error(`Project "${projectId}" not found.`);
+      const page = proj.document.pages?.[0] || { name: 'Home', elements: [] };
+      return { success: true, projectId, framework, code: generateReactTailwindCode(page) };
+    }
+
+    default:
+      throw new Error(`Unknown Cyrus MCP tool: "${name}"`);
+  }
+}
+
+// ─── JSON-RPC 2.0 PROTOCOL HANDLER ───────────────────────────────────
+export async function handleMcpJsonRpc(request) {
+  if (!request || typeof request !== 'object') {
+    return { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } };
+  }
+
+  const { id, method, params } = request;
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: 'cyrus-studio', version: '1.0.8' }
+      }
+    };
+  }
+
+  if (method === 'notifications/initialized' || method === 'initialized') return null;
+  if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
+  if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools: MCP_TOOLS } };
+
+  if (method === 'tools/call') {
+    try {
+      const data = await handleToolCall(params?.name, params?.arguments);
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], isError: false }
+      };
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true }
+      };
+    }
+  }
+
+  return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method "${method}" not found.` } };
+}
+
+// ─── STDIO STREAM ───────────────────────────────────────────────────
+if (process.argv.includes('--stdio') || !process.stdin.isTTY || process.argv.includes('mcp-server')) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    try {
+      const res = await handleMcpJsonRpc(JSON.parse(trimmed));
+      if (res) process.stdout.write(JSON.stringify(res) + '\n');
+    } catch (err) {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { message: err.message } }) + '\n');
+    }
+  });
+} else {
+  console.log('🤖 Cyrus Studio MCP Server v1.0.8');
+  console.log('Use with Claude Desktop or Cursor: npx cyrus-studio mcp-server');
+}