cyrus-studio 1.0.5 → 1.0.7

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/dist/index.cjs

@@ -0,0 +1,121 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// packages/cyrus-sdk/src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CyrusCanvasIframe: () => CyrusCanvasIframe,
+  createCyrusEmbedUrl: () => createCyrusEmbedUrl,
+  getCyrusLLMSystemPrompt: () => getCyrusLLMSystemPrompt,
+  validateAndRepairCyrusIR: () => validateAndRepairCyrusIR
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = __toESM(require("react"), 1);
+
+// packages/cyrus-sdk/src/protocol.ts
+function validateAndRepairCyrusIR(rawInput) {
+  let doc = rawInput;
+  if (typeof rawInput === "string") {
+    try {
+      const cleaned = rawInput.replace(/```json\s*/gi, "").replace(/```\s*$/gi, "").trim();
+      doc = JSON.parse(cleaned);
+    } catch {
+      return { version: "1.0", projectTitle: "AI Application", pages: [{ name: "Page 1", elements: [] }] };
+    }
+  }
+  if (!doc || typeof doc !== "object") {
+    return { version: "1.0", projectTitle: "AI Application", pages: [{ name: "Page 1", elements: [] }] };
+  }
+  const pages = Array.isArray(doc.pages) ? doc.pages : [{ name: "Home", elements: doc.elements || [] }];
+  return {
+    version: "1.0",
+    projectTitle: String(doc.projectTitle || doc.name || "AI Application"),
+    type: doc.type || "webapp",
+    theme: doc.theme || "light",
+    palette: doc.palette || { primary: "#0071e3", secondary: "#7d2ae8", background: "#ffffff", surface: "#f5f5f7", text: "#1d1d1f" },
+    pages: pages.map((p, idx) => ({
+      name: p.name || `Page ${idx + 1}`,
+      slug: p.slug || `page-${idx + 1}`,
+      elements: Array.isArray(p.elements) ? p.elements : []
+    }))
+  };
+}
+function getCyrusLLMSystemPrompt() {
+  return `Output your designs strictly in the Cyrus IR JSON format:
+{
+  "version": "1.0",
+  "projectTitle": "Title",
+  "type": "webapp",
+  "theme": "light",
+  "pages": [
+    { "name": "Home", "elements": [{ "type": "navbar" }, { "type": "heading" }, { "type": "button" }] }
+  ]
+}`;
+}
+
+// packages/cyrus-sdk/src/index.ts
+function createCyrusEmbedUrl(options = {}) {
+  const host = options.hostUrl || "http://localhost:5173";
+  const pid = options.projectId || "demo";
+  const theme = options.theme || "light";
+  return `${host}/#/embed/${pid}?theme=${theme}&readOnly=${Boolean(options.readOnly)}`;
+}
+function CyrusCanvasIframe({
+  projectId = "demo",
+  hostUrl = "http://localhost:5173",
+  theme = "light",
+  onStateChange,
+  style,
+  className,
+  ...rest
+}) {
+  const embedUrl = createCyrusEmbedUrl({ projectId, hostUrl, theme });
+  import_react.default.useEffect(() => {
+    if (!onStateChange || typeof window === "undefined") return;
+    const handleMessage = (event) => {
+      if (event.data && event.data.type === "CYRUS_STATE_CHANGED") {
+        onStateChange(event.data.payload);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, [onStateChange]);
+  return import_react.default.createElement("iframe", {
+    src: embedUrl,
+    className: className || "w-full h-full border-0 rounded-2xl shadow-lg",
+    style: {
+      width: "100%",
+      height: "600px",
+      border: "none",
+      borderRadius: "16px",
+      ...style
+    },
+    title: "Cyrus Visual Canvas Studio",
+    ...rest
+  });
+}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+
+export interface CyrusIRElement {
+  id?: string;
+  type: string;
+  name?: string;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  styles?: Record<string, any>;
+  content?: Record<string, any>;
+  children?: CyrusIRElement[];
+}
+
+export interface CyrusIRPage {
+  id?: string;
+  name?: string;
+  slug?: string;
+  backgroundColor?: string;
+  elements: CyrusIRElement[];
+}
+
+export interface CyrusIRDocument {
+  version: '1.0';
+  projectTitle: string;
+  type?: 'webapp' | 'website' | 'dashboard' | 'landing' | 'mobile';
+  theme?: 'light' | 'dark' | 'system';
+  palette?: {
+    primary?: string;
+    secondary?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+  };
+  pages: CyrusIRPage[];
+}
+
+export declare function validateAndRepairCyrusIR(rawInput: any): CyrusIRDocument;
+export declare function irToProject(ir: CyrusIRDocument): any;
+export declare function projectToCyrusIR(project: any): CyrusIRDocument;
+export declare function getCyrusLLMSystemPrompt(): string;
+export declare function createCyrusEmbedUrl(options: { projectId?: string; hostUrl?: string; theme?: 'light' | 'dark'; readOnly?: boolean; }): string;
+
+export interface CyrusIframeProps extends React.IframeHTMLAttributes<HTMLIFrameElement> {
+  projectId?: string;
+  hostUrl?: string;
+  theme?: 'light' | 'dark';
+  onStateChange?: (state: any) => void;
+}
+
+export declare function CyrusCanvasIframe(props: CyrusIframeProps): React.ReactElement;

package/dist/index.js

@@ -0,0 +1,41 @@
+import React from 'react';
+export * from './protocol.js';
+/**
+ * Generates an embeddable Cyrus studio URL from a project ID or custom host.
+ */
+export function createCyrusEmbedUrl(options = {}) {
+    const host = options.hostUrl || 'http://localhost:5173';
+    const pid = options.projectId || 'demo';
+    const theme = options.theme || 'light';
+    return `${host}/#/embed/${pid}?theme=${theme}&readOnly=${Boolean(options.readOnly)}`;
+}
+/**
+ * React Component to embed the Cyrus Visual Canvas Studio in any web app.
+ */
+export function CyrusCanvasIframe({ projectId = 'demo', hostUrl = 'http://localhost:5173', theme = 'light', onStateChange, style, className, ...rest }) {
+    const embedUrl = createCyrusEmbedUrl({ projectId, hostUrl, theme });
+    React.useEffect(() => {
+        if (!onStateChange || typeof window === 'undefined')
+            return;
+        const handleMessage = (event) => {
+            if (event.data && event.data.type === 'CYRUS_STATE_CHANGED') {
+                onStateChange(event.data.payload);
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        return () => window.removeEventListener('message', handleMessage);
+    }, [onStateChange]);
+    return React.createElement('iframe', {
+        src: embedUrl,
+        className: className || 'w-full h-full border-0 rounded-2xl shadow-lg',
+        style: {
+            width: '100%',
+            height: '600px',
+            border: 'none',
+            borderRadius: '16px',
+            ...style,
+        },
+        title: 'Cyrus Visual Canvas Studio',
+        ...rest,
+    });
+}

package/dist/index.mjs

@@ -0,0 +1,91 @@
+// packages/cyrus-sdk/src/index.ts
+import React from "react";
+
+// packages/cyrus-sdk/src/protocol.ts
+function validateAndRepairCyrusIR(rawInput) {
+  let doc = rawInput;
+  if (typeof rawInput === "string") {
+    try {
+      const cleaned = rawInput.replace(/```json\s*/gi, "").replace(/```\s*$/gi, "").trim();
+      doc = JSON.parse(cleaned);
+    } catch {
+      return { version: "1.0", projectTitle: "AI Application", pages: [{ name: "Page 1", elements: [] }] };
+    }
+  }
+  if (!doc || typeof doc !== "object") {
+    return { version: "1.0", projectTitle: "AI Application", pages: [{ name: "Page 1", elements: [] }] };
+  }
+  const pages = Array.isArray(doc.pages) ? doc.pages : [{ name: "Home", elements: doc.elements || [] }];
+  return {
+    version: "1.0",
+    projectTitle: String(doc.projectTitle || doc.name || "AI Application"),
+    type: doc.type || "webapp",
+    theme: doc.theme || "light",
+    palette: doc.palette || { primary: "#0071e3", secondary: "#7d2ae8", background: "#ffffff", surface: "#f5f5f7", text: "#1d1d1f" },
+    pages: pages.map((p, idx) => ({
+      name: p.name || `Page ${idx + 1}`,
+      slug: p.slug || `page-${idx + 1}`,
+      elements: Array.isArray(p.elements) ? p.elements : []
+    }))
+  };
+}
+function getCyrusLLMSystemPrompt() {
+  return `Output your designs strictly in the Cyrus IR JSON format:
+{
+  "version": "1.0",
+  "projectTitle": "Title",
+  "type": "webapp",
+  "theme": "light",
+  "pages": [
+    { "name": "Home", "elements": [{ "type": "navbar" }, { "type": "heading" }, { "type": "button" }] }
+  ]
+}`;
+}
+
+// packages/cyrus-sdk/src/index.ts
+function createCyrusEmbedUrl(options = {}) {
+  const host = options.hostUrl || "http://localhost:5173";
+  const pid = options.projectId || "demo";
+  const theme = options.theme || "light";
+  return `${host}/#/embed/${pid}?theme=${theme}&readOnly=${Boolean(options.readOnly)}`;
+}
+function CyrusCanvasIframe({
+  projectId = "demo",
+  hostUrl = "http://localhost:5173",
+  theme = "light",
+  onStateChange,
+  style,
+  className,
+  ...rest
+}) {
+  const embedUrl = createCyrusEmbedUrl({ projectId, hostUrl, theme });
+  React.useEffect(() => {
+    if (!onStateChange || typeof window === "undefined") return;
+    const handleMessage = (event) => {
+      if (event.data && event.data.type === "CYRUS_STATE_CHANGED") {
+        onStateChange(event.data.payload);
+      }
+    };
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, [onStateChange]);
+  return React.createElement("iframe", {
+    src: embedUrl,
+    className: className || "w-full h-full border-0 rounded-2xl shadow-lg",
+    style: {
+      width: "100%",
+      height: "600px",
+      border: "none",
+      borderRadius: "16px",
+      ...style
+    },
+    title: "Cyrus Visual Canvas Studio",
+    ...rest
+  });
+}
+export {
+  CyrusCanvasIframe,
+  createCyrusEmbedUrl,
+  getCyrusLLMSystemPrompt,
+  validateAndRepairCyrusIR
+};

package/dist/protocol.d.ts

@@ -0,0 +1,35 @@
+export interface CyrusIRElement {
+    id?: string;
+    type: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    styles?: Record<string, any>;
+    content?: Record<string, any>;
+    children?: CyrusIRElement[];
+}
+export interface CyrusIRPage {
+    id?: string;
+    name?: string;
+    slug?: string;
+    backgroundColor?: string;
+    elements: CyrusIRElement[];
+}
+export interface CyrusIRDocument {
+    version: '1.0';
+    projectTitle: string;
+    type?: 'webapp' | 'website' | 'dashboard' | 'landing' | 'mobile';
+    theme?: 'light' | 'dark' | 'system';
+    palette?: {
+        primary?: string;
+        secondary?: string;
+        background?: string;
+        surface?: string;
+        text?: string;
+    };
+    pages: CyrusIRPage[];
+}
+export declare function validateAndRepairCyrusIR(rawInput: any): CyrusIRDocument;
+export declare function getCyrusLLMSystemPrompt(): string;

package/dist/protocol.js

@@ -0,0 +1,31 @@
+export function validateAndRepairCyrusIR(rawInput) {
+    let doc = rawInput;
+    if (typeof rawInput === 'string') {
+        try {
+            const cleaned = rawInput.replace(/```json\s*/gi, '').replace(/```\s*$/gi, '').trim();
+            doc = JSON.parse(cleaned);
+        }
+        catch {
+            return { version: '1.0', projectTitle: 'AI Application', pages: [{ name: 'Page 1', elements: [] }] };
+        }
+    }
+    if (!doc || typeof doc !== 'object') {
+        return { version: '1.0', projectTitle: 'AI Application', pages: [{ name: 'Page 1', elements: [] }] };
+    }
+    const pages = Array.isArray(doc.pages) ? doc.pages : [{ name: 'Home', elements: doc.elements || [] }];
+    return {
+        version: '1.0',
+        projectTitle: String(doc.projectTitle || doc.name || 'AI Application'),
+        type: doc.type || 'webapp',
+        theme: doc.theme || 'light',
+        palette: doc.palette || { primary: '#0071e3', secondary: '#7d2ae8', background: '#ffffff', surface: '#f5f5f7', text: '#1d1d1f' },
+        pages: pages.map((p, idx) => ({
+            name: p.name || `Page ${idx + 1}`,
+            slug: p.slug || `page-${idx + 1}`,
+            elements: Array.isArray(p.elements) ? p.elements : [],
+        })),
+    };
+}
+export function getCyrusLLMSystemPrompt() {
+    return `Output your designs strictly in the Cyrus IR JSON format:\n{\n  "version": "1.0",\n  "projectTitle": "Title",\n  "type": "webapp",\n  "theme": "light",\n  "pages": [\n    { "name": "Home", "elements": [{ "type": "navbar" }, { "type": "heading" }, { "type": "button" }] }\n  ]\n}`;
+}