# jsOM 🎨

[![License: Source Available](https://img.shields.io/badge/License-Source_Available-blue.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/Alemusica/jsom?style=social)](https://github.com/Alemusica/jsom)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/Alemusica?style=social)](https://github.com/sponsors/Alemusica)

> **jsOM - The Definitive Designer Platform, LLM Friendly**

Draw UI visually → Export precise JSON specs → Any LLM generates production code. The bridge between human creativity and AI code generation.

---

## ⚖️ LICENSE CHANGE NOTICE

**IMPORTANT:** As of **January 28, 2026**, jsOM is licensed under a **Source-Available License**.

| Version | License | Status |
|---------|---------|--------|
| **≤ v1.4.0-beta** (tag: `v1.4.0-beta-MIT-LAST`) | MIT | ⚠️ **DEPRECATED** - No updates, no support |
| **≥ v1.5.0** | Source-Available | ✅ **ACTIVE** - All new features here |

### ⚠️ MIT Versions Are DEPRECATED

The MIT version (v1.4.0-beta and earlier) is **officially deprecated**:

- ❌ **No security updates**
- ❌ **No bug fixes**
- ❌ **No new features**
- ❌ **No support**
- ❌ **Architecturally diverging** (incompatible soon)

**Using the MIT fork = Using abandonware.**

### 📋 Read the Ethics Statement

**127 people cloned jsOM under MIT.**

If you're one of them: **[Read MIT-ETHICS.md](MIT-ETHICS.md)**

**TL;DR:** You have legal rights. But parasitizing a solo dev's work for commercial gain is morally bankrupt and the community will know.

### For Users of Pre-v1.5.0 (MIT versions)

If you downloaded jsOM under MIT before Jan 28, 2026:

✅ **Legitimate Use** (learning, internal tools, contributions):
- You're fine, keep learning!

⚠️ **Commercial Use** (competitor products, SaaS, rebrand):
- **Contact:** alessioivoycazzaniga@gmail.com
- Discuss collaboration, licensing, partnership
- **Undeclared commercial forks will be publicly tracked**

❌ **Parasitic Use** (silent competitor, zero attribution):
- See [MIT-ETHICS.md](MIT-ETHICS.md)
- Your fork will be listed publicly
- Community judgment is permanent

**Note:** v1.6.0+ will use AGPL-licensed dependencies, making MIT forks legally incompatible with new code.

### Branches

| Branch | Status | Description |
|--------|--------|-------------|
| `master` | **Main** | Stable release, production-ready |
| `core` | Dev | Development branch |
| `feature/*` | Experimental | Feature development branches |

<p align="center">
  <a href="https://ui-canvas-mcp.vercel.app">
    <img src="docs/assets/jsom-logo.jpg" alt="jsOM Logo" width="400"/>
  </a>
  <br/>
  <strong>👉 <a href="https://ui-canvas-mcp.vercel.app">Try Live Demo</a></strong>
</p>

---

## 💖 Support This Project

If jsOM helps your workflow, consider supporting its development:

<p align="center">
  <a href="https://github.com/sponsors/Alemusica">
    <img src="https://img.shields.io/badge/Sponsor-❤️-ea4aaa?style=for-the-badge&logo=github" alt="GitHub Sponsors"/>
  </a>
  <a href="https://ko-fi.com/alessiocazzaniga9543">
    <img src="https://img.shields.io/badge/Ko--fi-☕-ff5e5b?style=for-the-badge&logo=ko-fi" alt="Ko-fi"/>
  </a>
</p>

### Sponsor Tiers
| Tier | Perks |
|------|-------|
| ☕ **Supporter** (€5/mo) | Name in README, Discord access |
| 🚀 **Builder** (€10/mo) | Early access to features, priority support |
| 💎 **Patron** (€25/mo) | 30min monthly consulting, feature requests |

---

## 🎯 What is this?

**UI Canvas MCP** is a visual design tool that:

1. **Lets you draw UI visually** - Like Figma/Keynote, with rectangles, text, buttons, etc.
2. **AI understands your design** - Multi-agent pipeline analyzes layout, style, hierarchy
3. **Generates precise specs** - Export universal format any LLM can understand
4. **MCP integration** - AI agents can read and manipulate your designs

**The key insight:** Your drawing is the source of truth. AI doesn't guess layouts - it uses YOUR precise design.

---

## 🆕 What's New (v1.4.0-beta - Jan 2026)

### Fan Pivot - Gestural Fan Arrangement
- **Keychain Metaphor** - Arrange elements like keys on a keychain, pinned at a pivot point
- **Click & Drag** - Click to place pivot, drag to control spread and rotation
- **Progressive Rotation** - Each element rotates more than the previous for natural fan effect
- **Physics Settling** - Elements settle with inertia after gesture release
- **Polar Control** - Angle controls rotation, distance controls spread
- Access via 🌀 Fan icon in toolbar (requires 2+ selected elements)

### PDD - Physics Driven Design (World Paradigm)
- **Enter the World** - Instead of "simulate", you step into a physics environment
- **Spring Constraints** - Connect elements with elastic springs (Soft, Medium, Stiff, Bouncy presets)
- **Real-time Physics** - 60fps simulation via Konva direct manipulation
- **Tension Visualization** - See constraint forces in real-time
- **Commit on Exit** - Leave the world to commit final positions
- Access via ⚛️ Atom icon in toolbar

### Rotation Curve System (Beta)
- **Intelligent Rotation Distribution** - Apply easing curves to control rotation across multiple elements
- **Preset Curves** - Linear, Ease In/Out, Logarithmic, Exponential
- **Freehand Mode** - Draw custom curves directly on canvas
- **Real-time Preview** - See rotation changes as you draw
- **Keyboard Controls** - Enter to confirm, ESC to cancel

### TIP Lite Architecture
- **Layered Code Structure** - archetipi (pure math) → molecole (domain rules) → organismi (orchestration)
- **World Paradigm** - Enter/exit instead of start/stop for immersive interactions
- Applied to Fan Pivot and PDD modules

---

## What's New (v1.3.0 - Jan 2026)

### UILayoutSpec v1.1 (LLM-Optimized Export)
- **Direct LLM Instructions** - `llmContext` field with code generation guidance
- **Dual Type System** - Both `type` (raw) and `semanticType` (inferred) for transparency
- **Token Optimization** - Stripped default values based on fig2json research
- **Research-Backed** - Based on Addy Osmani's LLM workflow best practices

### Precise Mode & Snap Grid
- **Shift+Drag** - DAW/synth-style fine movement (1/10 precision)
- **Alt+Drag** - Temporary grid snapping (Apple Keynote-style)
- **Live Overlay** - Coordinates display near cursor during precise mode

### Typography Harmonization System
- **Font Database** - 15+ fonts with classification metadata
- **Brand Archetypes** - clean, classy, friendly, quirky, techie
- **Compatibility Scores** - Algorithmic pairing analysis
- **Type Scales** - Mobile, desktop, editorial presets

### Test Suite & Code Quality
- **Vitest** - 26 unit tests for canvasStore
- **DOMPurify** - XSS prevention for user input
- **Quadtree** - O(log n) marquee selection
- **Scoped Logging** - Environment-aware debug utilities

---

## 📜 Previous Updates (v1.2.0)

### Blender-Style Smooth Zoom
- **Exponential Scaling** - Perceptually linear zoom using `Math.pow(2, -deltaY * ZOOM_SENSITIVITY)`
- **Trackpad Friendly** - No more "shooting off" with two-finger zoom gestures
- **Consistent Feel** - Same zoom behavior regardless of scroll speed
- **Wide Range** - 0.1x to 10x zoom levels

### TOON Export Format
- **40% Fewer Tokens** - Optimized notation for LLM context windows
- **Tabular Format** - Elements, events, voice notes in compact tables
- **Element Markers** - Voice notes reference elements with @id syntax
- **Export Integration** - Available alongside JSON, YAML, Markdown in Export Panel

### Extended Device Support
- **24+ Device Presets** - iPhone 16 Pro/Max, Pixel 9, Samsung S24, iPad Air, Galaxy Tab S9, MacBook Pro 14", iMac 24", and more
- **Device-Aware Blueprints** - Automatically scale UI elements based on device type (mobile/tablet/desktop)
- **Modern Devices** - Latest 2024-2025 device dimensions

### Semantic Layers System
- **HTML Structure Organization** - Organize elements into semantic sections (navigation, header, hero, footer, etc.)
- **Dual View Mode** - Toggle between Classic (z-index) and Semantic (hierarchy) views
- **Quick Assign** - One-click element assignment to sections
- **CSS Hints** - Each section includes layout hints (flexbox, grid, positioning)

### Multi-LLM Support
- **Gemini 2.0 Flash** - Use Google's latest model for faster, smarter generation
- **Ollama Integration** - Local models with qwen2.5:7b and minicpm-v
- **Provider Switching** - Easily switch between cloud (Gemini) and local (Ollama)

### Style Blueprints
- **9 Complete Design Systems** - Bauhaus, Swiss, Glassmorphism, Brutalist, Material, Neomorphism, Retro80s, Japanese, Minimal
- **6 UI Component Blueprints** - Hero, Navbar, Landing Page, Dashboard, Product Card, Profile
- **LLM-Optimized** - Each blueprint includes compositional rules, color palettes, and element specs
- **Device-Aware Scaling** - Blueprints adapt to mobile/tablet/desktop automatically
- **Semantic Integration** - Blueprints map to semantic sections automatically

### Multi-Agent AI Pipeline
- **LangGraph Integration** - Stateful agent orchestration with conditional routing
- **Smart Mode** - One-click AI generation with vision analysis
- **Knowledge Base** - Design intelligence powered by SurrealDB
- **PHI Algorithms** - Golden ratio layouts, spacing, and color harmony

### Enhanced Canvas
- **Marquee Selection** - Drag to select multiple elements
- **Voice Notes** - Record and transcribe design notes (Whisper support)
- **Storyboard Recording** - Track element movements for animations

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                        UI Canvas MCP                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐    ┌─────────────────────────────────────────┐   │
│  │   Canvas     │    │         Multi-Agent Pipeline            │   │
│  │   Editor     │    │  ┌─────────────────────────────────┐   │   │
│  │  (React +    │───▶│  │        SimpleOrchestrator       │   │   │
│  │   Konva)     │    │  │   (Browser-compatible runner)   │   │   │
│  └──────────────┘    │  └─────────────────────────────────┘   │   │
│         │            │              │                          │   │
│         │            │  ┌───────────▼───────────┐             │   │
│         ▼            │  │     RouterAgent       │             │   │
│  ┌──────────────┐    │  │  (Intent detection)   │             │   │
│  │  Properties  │    │  └───────────┬───────────┘             │   │
│  │    Panel     │    │              │                          │   │
│  │  + Notes     │    │      ┌───────┴───────┐                 │   │
│  │  + Voice     │    │      ▼               ▼                 │   │
│  └──────────────┘    │  ┌────────┐    ┌───────────┐          │   │
│                      │  │ Vision │    │  Prompt   │          │   │
│  ┌──────────────┐    │  │ Agent  │    │ Engineer  │          │   │
│  │   Toolbar    │    │  │minicpm │    │  Agent    │          │   │
│  │  + PHI       │    │  └────┬───┘    └─────┬─────┘          │   │
│  │  Algorithms  │    │       │              │                 │   │
│  └──────────────┘    │       └──────┬───────┘                 │   │
│                      │              ▼                          │   │
│                      │  ┌───────────────────┐                 │   │
│                      │  │  ExecutorAgent    │                 │   │
│                      │  │ (Grid + Collision │                 │   │
│                      │  │   + Z-Index)      │                 │   │
│                      │  └───────────────────┘                 │   │
│                      └─────────────────────────────────────────┘   │
│                                     │                              │
│  ┌──────────────┐    ┌──────────────▼──────────────┐              │
│  │  MCP Server  │◀──▶│       Knowledge Base        │              │
│  │  (stdio)     │    │  - Style Systems            │              │
│  └──────────────┘    │  - Layout Patterns          │              │
│                      │  - Component Patterns       │              │
│                      │  - Design Rules             │              │
│                      └─────────────────────────────┘              │
│                                     │                              │
│                      ┌──────────────▼──────────────┐              │
│                      │         SurrealDB           │              │
│                      │   (Projects + Elements)     │              │
│                      └─────────────────────────────┘              │
└─────────────────────────────────────────────────────────────────────┘
```

---

## 🤖 Multi-Agent System

### Agent Pipeline

| Agent | Model | Role |
|-------|-------|------|
| **RouterAgent** | qwen2.5:7b | Classifies intent (create/modify/vision) |
| **VisionAgent** | minicpm-v | Analyzes screenshots, extracts UI elements |
| **PromptEngineerAgent** | qwen2.5:7b | Transforms requests into design specs |
| **ExecutorAgent** | qwen2.5:7b | Generates canvas elements with positioning |

### Smart Mode Features

```typescript
// Enable Smart Mode in LLMPanel
const orchestrator = new SimpleOrchestrator({ model: 'qwen2.5:7b' });

const result = await orchestrator.generate(prompt, device, {
  screenshot: imageData,           // Optional: analyze existing UI
  existingElements: elements,      // Context for modifications
  visionModel: 'minicpm-v',       // Vision model for screenshots
  onProgress: (step, progress) => console.log(step, progress),
});
```

### LangGraph Workflow (Server-side)

```typescript
import { UIGenerationGraph } from './orchestration';

const graph = new UIGenerationGraph();
const result = await graph.invoke({
  userPrompt: "Create a login form with email and password",
  device: { name: 'iPhone 14', width: 390, height: 844 },
  screenshot: base64Image,  // Optional
});
```

---

## 🧠 Knowledge Base

The Knowledge Base provides design intelligence to agents:

### Style Systems
- **Swiss International** - Bold typography, grid-based, minimal color
- **Material Design** - Card-based, shadows, 8dp grid
- **Glassmorphism** - Frosted glass, transparency, soft shadows
- **Brutalist** - Raw, monospace, harsh borders
- **Japanese Minimalism** - Extreme whitespace, earth tones

### Layout Patterns
- **Hero Section** - Full-width header with CTA
- **Dashboard** - Grid-based cards and metrics
- **Form Layout** - Labeled inputs with validation

### Design Rules
- Spacing guidelines (8px base, PHI scale)
- Typography hierarchy
- Color accessibility (WCAG AA)
- Responsive breakpoints

---

## 🌀 PHI (Golden Ratio) Algorithms

Built-in golden ratio utilities for harmonious designs:

```typescript
import {
  phiSpacing,        // PHI-based spacing scale
  phiColorScale,     // Golden angle color harmony
  phiLayerPalette,   // Layer-aware color palette
  phiGridLayout,     // Golden rectangle grid
  sunflowerPattern,  // Vogel spiral arrangement
  ensureContrast,    // WCAG contrast checking
} from './shared/phi';

// Generate PHI spacing: 16, 26, 42, 68, 110...
const spacing = phiSpacingScale(16, 5);

// Generate harmonious colors using golden angle
const colors = phiColorScale(210, 5); // 5 colors from blue

// Layer-aware palette for UI hierarchy
const palette = phiLayerPalette(220, true); // Dark theme
// { background, surface, content, interactive, overlay }
```

### Toolbar Actions
- **PHI Spacing** - Harmonize element spacing
- **PHI Colors** - Apply golden angle color distribution
- **PHI Spiral** - Arrange elements in Fibonacci spiral
- **Sunflower Pattern** - Vogel spiral arrangement
- **PHI Sizes** - Scale elements using golden ratio

---

## 🚀 Quick Start

### 1. Install dependencies

```bash
git clone https://github.com/Alemusica/jsom.git
cd jsom
npm install
```

### 2. Start SurrealDB

```bash
surreal start --user root --pass root file:./data/ui-canvas.db
```

### 3. Configure LLM Provider

**Option A: Ollama (Local)**
```bash
# Text generation model
ollama pull qwen2.5:7b

# Vision model for screenshot analysis
ollama pull minicpm-v
```

**Option B: Gemini 2.0 Flash (Cloud)**
```bash
# Set your Gemini API key
export VITE_GEMINI_API_KEY=your_api_key_here
```

### 4. Run the app

```bash
npm run dev
```

Open http://localhost:5173

---

## ☁️ Vercel Deployment

Deploy the canvas app to Vercel:

### 1. Install Vercel CLI
```bash
npm i -g vercel
```

### 2. Configure Environment
Create `.env.production`:
```env
VITE_GEMINI_API_KEY=your_gemini_api_key
VITE_DEFAULT_PROVIDER=gemini
```

### 3. Deploy
```bash
vercel --prod
```

> **Note:** Vercel deployment runs the canvas app only (client-side). For full MCP server functionality, deploy to a Node.js-compatible platform.

---

## 📦 Project Structure

```
jsom/
├── src/
│   ├── canvas/
│   │   ├── components/
│   │   │   ├── CanvasStage.tsx    # Konva canvas with marquee
│   │   │   ├── Toolbar.tsx        # Tools + PHI buttons
│   │   │   ├── PropertiesPanel.tsx # Element properties
│   │   │   ├── NotesPanel.tsx     # Voice notes + transcription
│   │   │   ├── LLMPanel.tsx       # Smart Mode UI
│   │   │   ├── HelpPanel.tsx      # In-app manual
│   │   │   └── FisicaPanel.tsx    # Physics controls
│   │   ├── fan-pivot/             # Fan Pivot (TIP Lite)
│   │   │   ├── archetipi.ts       # Pure math functions
│   │   │   ├── molecole.ts        # Domain rules
│   │   │   ├── FanPivotWorld.ts   # World orchestration
│   │   │   └── useFanPivot.ts     # React hook
│   │   ├── pdd/                   # Physics Driven Design
│   │   │   ├── world/             # World paradigm
│   │   │   ├── constraints/       # Spring, rope, rigid
│   │   │   └── usePDDWorld.ts     # React hook
│   │   ├── services/
│   │   │   ├── agents/            # Multi-agent system
│   │   │   │   ├── BaseAgent.ts
│   │   │   │   ├── RouterAgent.ts
│   │   │   │   ├── VisionAgent.ts
│   │   │   │   ├── PromptEngineerAgent.ts
│   │   │   │   └── ExecutorAgent.ts
│   │   │   ├── orchestration/     # LangGraph + SimpleOrchestrator
│   │   │   │   ├── UIGenerationGraph.ts
│   │   │   │   └── SimpleOrchestrator.ts
│   │   │   ├── knowledge/         # Design Knowledge Base
│   │   │   │   ├── DesignKnowledgeBase.ts
│   │   │   │   └── types.ts
│   │   │   ├── llm.ts             # Ollama integration
│   │   │   └── toon/              # TOON format encoder
│   │   └── store/
│   │       ├── canvasStore.ts     # Zustand state
│   │       └── storyboardStore.ts # Animation recording
│   ├── mcp-server/
│   │   ├── index.ts               # MCP Server entry
│   │   └── storage.ts             # SurrealDB integration
│   └── shared/
│       ├── types.ts               # Shared types
│       └── phi.ts                 # Golden ratio utilities
├── docs/
│   └── assets/                    # Screenshots and demos
├── LICENSE                        # MIT License
└── README.md
```

---

## 🎮 Keyboard Shortcuts

| Key | Action |
|-----|--------|
| V | Select tool |
| R | Rectangle |
| T | Text |
| C | Circle |
| L | Line |
| P | Path/Bezier |
| I | Image |
| B | Button |
| N | Input |
| Delete/Backspace | Delete selected |
| ⌘D | Duplicate |
| ⌘⇧D | Duplicate x5 with offset |
| ⌘Z | Undo |
| ⌘⇧Z | Redo |
| ⌘⇧H | Distribute horizontal |
| ⌘⇧J | Distribute vertical |
| ⌘⇧G | Distribute grid |
| ⌘⇧R | Progressive rotation |
| Scroll | Zoom (Blender-style smooth) |
| Shift+Scroll | Pan canvas |
| F | Fit to screen |
| Drag on empty | Marquee selection |

---

## 🛠️ MCP Server Tools

| Tool | Description |
|------|-------------|
| `create_project` | Create new canvas project |
| `add_element` | Add element at exact position |
| `get_elements` | Get all elements with positions |
| `update_element` | Modify element properties |
| `delete_element` | Remove element |
| `export_layout_spec` | Export universal UI spec (YAML/JSON/TOON) |
| `export_code` | Generate React/HTML code |

### MCP Configuration

```json
{
  "mcpServers": {
    "ui-canvas": {
      "command": "node",
      "args": ["/path/to/jsom/dist/mcp-server/index.js"]
    }
  }
}
```

---

## 📱 Device Presets

**Mobile iOS:** iPhone 16 Pro, iPhone 16 Pro Max, iPhone 15, iPhone 14, iPhone 14 Pro Max, iPhone SE

**Mobile Android:** Pixel 9, Pixel 7, Samsung S24, Samsung S23

**Tablet iOS:** iPad Mini, iPad Air, iPad Pro 11", iPad Pro 12.9"

**Tablet Android:** Galaxy Tab S9, Pixel Tablet

**Desktop:** HD 1080p, 2K, 4K, MacBook Air 13", MacBook Pro 14", MacBook Pro 16", Surface Laptop, iMac 24"

---

## 🔧 Development

```bash
# Run everything (canvas + MCP server)
npm run dev

# Build for production
npm run build

# Run MCP server only
npm run mcp

# Canvas only
npm run dev:canvas
```

---

## 📚 Documentation

- [Multi-LLM Architecture](docs/MULTI_LLM_ARCHITECTURE.md)
- [Agent System Design](docs/AGENT_SYSTEM.md)

---

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs.

1. Fork the repo
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 🧩 Tech Stack

- **Frontend:** React 18, Konva.js, Zustand, TailwindCSS
- **AI:** LangGraph, LangChain, Ollama (local), Gemini 2.0 Flash (cloud)
- **Vision:** minicpm-v, Gemini 2.0 (UI screenshot analysis)
- **Database:** SurrealDB
- **Protocol:** MCP (Model Context Protocol)
- **Deployment:** Vercel, Docker

---

## 📄 License

**jsom Source Available License v1.0**

This project is **source-available** but NOT open source.

- ✅ **Free** for personal, educational, and non-commercial use
- ✅ **View, modify, contribute** to the source code
- ❌ **NO commercial use** without permission
- ❌ **NO competing products** or rebranding
- ❌ **NO redistribution** under different names

See [LICENSE](LICENSE) for full terms.

### 📜 On MIT Versions

If you downloaded jsOM under MIT (before Jan 27, 2026), you have **legal rights** to that version.
But please read [MIT-ETHICS.md](MIT-ETHICS.md) on the **moral expectations** of open source.

For commercial licensing: alessioivoycazzaniga@gmail.com

---

## 🙏 Acknowledgments

- [Konva.js](https://konvajs.org/) - Canvas rendering
- [LangChain](https://langchain.com/) - AI orchestration
- [Ollama](https://ollama.ai/) - Local LLM inference
- [SurrealDB](https://surrealdb.com/) - Multi-model database
- [Anthropic MCP](https://modelcontextprotocol.io/) - AI agent protocol

---

<p align="center">
  Built with ❤️ by <a href="https://twitter.com/FluturArt">@FluturArt</a> for the agentic future.
</p>

<p align="center">
  <a href="https://github.com/sponsors/Alemusica">
    <img src="https://img.shields.io/badge/Sponsor_this_project-❤️-ea4aaa?style=for-the-badge" alt="Sponsor"/>
  </a>
</p>