# Elementor JSON Generator

Convert website design images into valid **Elementor Pro JSON** for WordPress.

Upload (or paste) a screenshot of any web page design → choose your Elementor Pro version → download a ready-to-import `.json` template.

---

## Stack

| Layer | Technology |
|---|---|
| Frontend | React 18 + Vite + TypeScript + Tailwind CSS |
| Backend | Node.js + Express + TypeScript |
| AI Vision | Anthropic Claude API (`claude-sonnet-4-6`) |
| Database | MongoDB + Mongoose (optional) |

---

## Prerequisites

- Node.js 18+
- An **Anthropic API key** (get one at console.anthropic.com)
- MongoDB (optional — history feature requires it)

---

## Quick Start

### 1. Clone / download the project

```bash
cd ElProJson
```

### 2. Install dependencies

```bash
# Root workspace + both packages
npm install
cd client && npm install
cd ../server && npm install
cd ..
```

### 3. Configure environment

```bash
# Edit server/.env
ANTHROPIC_API_KEY=sk-ant-your-key-here
MONGODB_URI=                     # leave empty to skip MongoDB
PORT=3001
```

### 4. Run development servers

```bash
# From the root — starts both client (5173) and server (3001)
npm run dev
```

Open **http://localhost:5173**

---

## How It Works

### Image → JSON Pipeline

```
User uploads image
      │
      ▼
POST /api/generate (Express + multer)
      │
      ▼
Claude claude-sonnet-4-6 Vision API
  → Structural analysis prompt
  → Returns JSON: sections, elements, colors, fonts
      │
      ▼
elementorBuilder.ts
  → Maps analyzed elements to Elementor widget types
  → Builds internal ElementorElement tree
  → Applies page settings
      │
      ▼
versionAdapter.ts
  → Adapts structure to target version
  → v3.6+: Flexbox Container layout
  → pre-3.6: legacy Section → Column layout
  → Removes unsupported widgets with warnings
      │
      ▼
validator.ts
  → Checks structure validity
  → Checks widget type names
  → Reports errors + warnings
      │
      ▼
Response: { template, warnings, confidence, metadata }
      │
      ▼
Client: preview + download .json
```

### Version Refresh Flow

```
User clicks "Update Versions"
      │
      ▼
POST /api/versions/refresh
      │
      ▼
Fetch https://api.wordpress.org/plugins/info/... (Elementor free, as proxy signal)
      │
      ├── New version found → add to registry, inherit features from previous
      │   └── Persist to MongoDB (if connected)
      └── No change → report "already up to date"
      │
      ▼
UI shows changes list
Version selector updates
```

> **Note:** Elementor Pro is commercial and not on WordPress.org. The refresh uses the free Elementor plugin version as a version signal. When a new version is detected, it inherits the feature set of the previous latest version. You should review the official changelog at https://elementor.com/changelog/ to update the feature flags manually.

---

## Elementor JSON Format

Based on official Elementor export format `v0.4`:

```json
{
  "version": "0.4",
  "title": "Page Title",
  "type": "page",
  "page_settings": {
    "background_color": "#ffffff",
    "hide_title": "yes"
  },
  "content": [
    {
      "id": "abc12345",
      "elType": "container",
      "settings": {
        "flex_direction": "column",
        "content_width": "boxed",
        "padding": { "top": "60", "right": "0", "bottom": "60", "left": "0", "unit": "px", "isLinked": false }
      },
      "elements": [
        {
          "id": "def67890",
          "elType": "widget",
          "widgetType": "heading",
          "settings": {
            "title": "Welcome",
            "header_size": "h1",
            "align": "center"
          },
          "elements": []
        }
      ]
    }
  ]
}
```

### Version Differences

| Version | Layout Structure | Key Feature |
|---|---|---|
| < 3.6 | `section → column → widget` | Legacy layout |
| 3.6+ | `container → widget` | Flexbox Container |
| 3.7+ | containers + Loop Grid | Loop Grid widget |
| 3.10+ | containers + Off Canvas | Off Canvas widget |
| 3.14+ | all above + AI tools | AI Copilot |
| 3.21+ | latest | All features |

---

## Architecture

```
ElProJson/
├── client/                    # React + Vite frontend
│   └── src/
│       ├── components/        # UI components
│       ├── hooks/             # useVersions, useImageUpload, useGeneration
│       ├── services/api.ts    # Axios API calls
│       └── types/             # TypeScript interfaces
│
├── server/                    # Express backend
│   └── src/
│       ├── config/database.ts # MongoDB connection
│       ├── types/             # Elementor + Analysis types
│       ├── services/
│       │   ├── imageAnalysis.ts     # Claude Vision API
│       │   ├── elementorBuilder.ts  # JSON builder
│       │   ├── versionRegistry.ts   # Version data + refresh
│       │   ├── versionAdapter.ts    # Version-specific adapters
│       │   └── validator.ts         # JSON structure validation
│       ├── models/            # Mongoose models
│       └── routes/            # Express routes
│
└── package.json               # npm workspace root
```

---

## Known Limitations

- **Best-effort conversion.** AI vision cannot perfectly reconstruct designs. Always review in Elementor before publishing.
- **Fonts are guessed.** The AI identifies fonts visually; exact font names require manual verification.
- **No dynamic content.** WooCommerce, dynamic tags, and custom post type loops cannot be auto-generated.
- **Forms need manual setup.** The generator marks form placeholders; you must configure them in Elementor Pro.
- **Responsive breakpoints.** Mobile/tablet settings are not generated — add them manually.
- **Elementor Pro is commercial.** Version refresh uses the free Elementor plugin as a proxy; feature flags for new Pro-only features must be updated manually in `versionRegistry.ts`.
- **Animations and interactions** are not captured from images.

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `ANTHROPIC_API_KEY` | ✅ Yes | — | Your Anthropic API key |
| `MONGODB_URI` | No | — | MongoDB connection string. If empty, history is disabled |
| `PORT` | No | `3001` | Server port |
| `MAX_IMAGE_SIZE_MB` | No | `10` | Max upload size in MB |
| `CLIENT_ORIGIN` | No | `http://localhost:5173` | Allowed CORS origin |