site-builder/CLAUDE.md

# Site Builder - Project Documentation

## Overview

A visual drag-and-drop website builder using GrapesJS. Users can create multi-page websites without writing code, with server-side file storage for assets and localStorage persistence for editor state.

## File Structure

```
site-builder/
├── router.php             # PHP built-in server router (dev server)
├── .htaccess              # Apache rewrite rules for /api/* routing
├── .user.ini              # PHP upload/memory limits for Apache
├── index.html             # Main editor page
├── preview.html           # Preview page (renders saved content with page navigation)
├── CLAUDE.md              # This documentation file
├── api/
│   ├── index.php          # API handler (assets, projects, health endpoints)
│   └── image-resize.php   # Image resize/crop endpoint
├── css/
│   └── editor.css         # Custom editor styles (dark theme, ~1300 lines)
├── js/
│   ├── editor.js          # Editor initialization and all functionality (~1900 lines)
│   ├── assets.js          # Asset management (upload, browse, deploy)
│   └── whp-integration.js # WHP control panel integration
├── storage/
│   ├── assets/            # Uploaded asset files (images, videos, etc.)
│   ├── projects/          # Saved project data (JSON files)
│   └── tmp/               # Temporary files
└── docs/
    └── plans/
        └── 2026-01-26-site-builder-design.md  # Design document
```

## Dependencies (CDN)

All dependencies are loaded from CDN in index.html:
- **GrapesJS Core** (`unpkg.com/grapesjs`) - Main editor engine
- **grapesjs-blocks-basic** - Basic building blocks
- **grapesjs-preset-webpage** - Webpage blocks (hero, features, etc.)
- **grapesjs-plugin-forms** - Form elements
- **grapesjs-style-gradient** - Gradient background support
- **Font Awesome 5** - Block icons
- **Google Fonts** - Inter, Roboto, Open Sans, Poppins, Montserrat, Playfair Display, Merriweather, Source Code Pro

## Running the Project

The project uses PHP for its API backend. Assets are stored as files on disk (not base64 in localStorage), which avoids browser storage quota issues.

### Production (Apache)
The `.htaccess` file routes `/api/*` requests to `api/index.php`. The `.user.ini` sets PHP upload limits. Just deploy to any Apache + PHP host.

### Local Development (PHP built-in server)
```bash
php -d upload_max_filesize=500M -d post_max_size=512M -S localhost:8081 router.php
```

Then open `http://localhost:8081`

### Server API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/health` | Server health check |
| POST | `/api/assets/upload` | Upload file (multipart/form-data) |
| GET | `/api/assets` | List all stored assets |
| DELETE | `/api/assets/<filename>` | Delete an asset |
| POST | `/api/projects/save` | Save project data (JSON body) |
| GET | `/api/projects/list` | List all saved projects |
| GET | `/api/projects/<id>` | Load a specific project |
| DELETE | `/api/projects/<id>` | Delete a project |

## Editor Interface

### Top Navigation Bar
- Logo/branding
- Device switcher (Desktop/Tablet/Mobile)
- Undo/Redo buttons
- Clear canvas button
- Export button (download site as ZIP with options)
- Preview button (opens preview.html in new tab)

### Left Panel (3 tabs)
1. **Blocks** - Draggable components organized by category
2. **Pages** - Multi-page management (add/edit/delete pages)
3. **Layers** - Component hierarchy tree view

### Center Canvas
- Live preview of the website
- Click to select, drag to reposition
- Right-click for context menu
- Resize handles on selected components

### Right Panel (2 tabs)
1. **Styles** - Two modes:
   - **Guided Mode**: Context-aware presets based on selected element type
   - **Advanced Mode**: Full GrapesJS style manager with all CSS properties
2. **Settings** - Component-specific traits/attributes (like Video URL)

## Block Categories

### Layout
| Block | Description |
|-------|-------------|
| Section | Basic content section with centered container |
| Section (Background) | Section with image background and overlay |
| Section (Video BG) | Section with video background (YouTube/Vimeo/MP4) and overlay |
| Logo | Styled logo with icon and text |
| Navigation | Dynamic nav bar with page sync |
| Footer | Footer with links and copyright |
| 1-4 Columns | Flexible column layouts |
| 2 Columns 3/7 | Asymmetric column layout |

### Basic
| Block | Description |
|-------|-------------|
| Text | Paragraph text |
| Heading | H2 heading |
| Button | Styled link button |
| Divider | Horizontal rule (color/thickness editable) |
| Spacer | Vertical spacing element |
| Text Box | Styled container for overlaying on backgrounds |

### Media
| Block | Description |
|-------|-------------|
| Image | Responsive image |
| Video | Universal video (YouTube, Vimeo, or direct file) |

### Sections
| Block | Description |
|-------|-------------|
| Hero (Image) | Hero with image background and overlay |
| Hero (Video) | Hero with video background and overlay |
| Hero (Simple) | Hero with gradient background |
| Features Grid | 3-column feature cards |
| Testimonials | Customer testimonials with star ratings |
| Pricing Table | 3-tier pricing comparison with featured tier |
| Contact Section | Contact info with form |
| Call to Action | CTA banner with gradient background |

### Forms
Form, Input, Textarea, Select, Button, Label, Checkbox, Radio

## Context-Aware Styling (Guided Mode)

The guided panel shows different controls based on selected element:

### Text Elements (p, h1-h6, span, label)
- Text Color (8 presets)
- Font Family (8 Google Fonts)
- Text Size (XS, S, M, L, XL, 2XL)
- Font Weight (Light, Normal, Medium, Semi, Bold)

### Links/Buttons (a)
- Link URL input with "Open in new tab" option
- Button Color (8 presets, auto-adjusts text for contrast)
- Text styling options
- Border Radius and Padding

### Containers (div, section, etc.)
- Background Color (8 presets)
- Background Gradient (12 presets)
- Background Image (URL with size/position controls)
- Padding and Border Radius

### Overlays (.bg-overlay)
- Overlay Color (6 presets)
- Opacity Slider (0-100%)

### Navigation (nav)
- "Sync with Pages" button (auto-generates links from page list)
- "Add Link" button
- Link list with delete buttons

### Dividers (hr)
- Divider Color (8 presets)
- Line Thickness (1-6px)

## Video System

### Supported Formats
The Video block and Section Video BG support:
- **YouTube**: `youtube.com/watch?v=ID`, `youtu.be/ID`
- **Vimeo**: `vimeo.com/ID`
- **Direct files**: `.mp4`, `.webm`, `.ogg`, `.mov`

### How Videos Work
1. URLs are auto-detected and converted to proper embed format
2. YouTube/Vimeo use iframe embeds
3. Direct files use HTML5 video element
4. Background videos auto-play muted and loop

### Editing Video URL
1. Select the video container (use Layers panel if needed)
2. Go to **Settings** tab
3. Paste URL in "Video URL" field
4. Video loads automatically

## Multi-Page System

### Storage
- Pages stored in localStorage key: `sitebuilder-pages`
- Each page has: id, name, slug, html, css

### Page Management
- **Add Page**: Click "Add Page" in Pages tab
- **Edit Page**: Click edit icon on page item
- **Delete Page**: Click delete icon (cannot delete last page)
- **Switch Pages**: Click on page item (auto-saves current page)

### Navigation Sync
1. Add Navigation block to page
2. Select the nav element
3. In Settings, click "Sync with Pages"
4. Links auto-generate from page list
5. CTA button (with `.nav-cta` class) is preserved

## Context Menu (Right-Click)

| Action | Shortcut | Description |
|--------|----------|-------------|
| Edit Content | - | Enable inline text editing |
| Duplicate | Ctrl+D | Copy element in place |
| Copy | Ctrl+C | Copy to clipboard |
| Paste | Ctrl+V | Paste from clipboard |
| Move Up | - | Move element up in parent |
| Move Down | - | Move element down in parent |
| Select Parent | - | Select parent container |
| Wrap in Container | - | Wrap in new div |
| Delete | Del | Remove element |

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| Ctrl/Cmd + Z | Undo |
| Ctrl/Cmd + Shift + Z | Redo |
| Ctrl/Cmd + Y | Redo (alternative) |
| Ctrl/Cmd + C | Copy |
| Ctrl/Cmd + V | Paste |
| Ctrl/Cmd + D | Duplicate |
| Delete / Backspace | Remove selected |
| Escape | Deselect / Close modals |

## Storage Architecture

### Server-Side Storage (primary, when server.py is running)
| Location | Purpose |
|----------|---------|
| `storage/assets/` | Uploaded files (images, videos, etc.) stored on disk |
| `storage/projects/` | Project data as JSON files |
| `storage/tmp/` | Temporary files |

Assets are uploaded via `POST /api/assets/upload` and stored as actual files on disk. They are referenced in the editor by URL (e.g., `/storage/assets/1234567_abc123_photo.jpg`), avoiding localStorage quota limits.

### localStorage Keys (lightweight metadata and editor state)
| Key | Purpose |
|-----|---------|
| `sitebuilder-project` | GrapesJS auto-save (components, styles) |
| `sitebuilder-pages` | Multi-page data (array of page objects) |
| `sitebuilder-assets` | Asset metadata index (URLs and names only, no file contents) |
| `sitebuilder-project-preview` | Preview data (all pages for preview.html) |

**Important:** Asset file contents (images, videos) are NOT stored in localStorage. Only metadata (filename, URL, type) is cached there. This prevents the `QuotaExceededError` that occurred with base64-encoded large files.

## Export Feature

### How to Export
1. Click the **Export** button in the top navigation bar
2. Choose export options:
   - **Minify CSS**: Reduces file size by removing whitespace/comments
   - **Include Google Fonts**: Adds font preload links (recommended)
3. Click **Download ZIP**
4. All pages are exported as standalone HTML files

### Exported File Structure
```
site-export.zip
├── index.html      # Home page
├── about.html      # About page (based on page slug)
├── contact.html    # etc.
```

### Technical Details
- Uses JSZip library (loaded dynamically on first export)
- Each HTML file includes embedded CSS styles
- Responsive CSS reset included in each file
- Mobile column stacking rules included

## Preview System

`preview.html` loads saved content from localStorage and renders it:
- Supports multi-page with page selector buttons
- Backwards compatible with legacy single-page format
- Includes Google Fonts and responsive styles
- "Back to Editor" button

## CSS Architecture (editor.css)

### Main Sections
1. **Base Layout** (~lines 1-100) - Editor container, panels
2. **Top Navigation** (~lines 100-200) - Nav bar, device buttons
3. **Left Panel** (~lines 200-400) - Blocks, pages, layers
4. **Right Panel** (~lines 400-600) - Styles, traits
5. **Guided Styles** (~lines 600-800) - Color presets, font presets
6. **Context Menu** (~lines 800-900) - Right-click menu
7. **Pages Panel** (~lines 900-1000) - Page list, page items
8. **Modals** (~lines 1000-1100) - Page settings modal
9. **New Controls** (~lines 1100-1300) - Background, overlay, nav controls

### Theme
- Dark theme with `#16161a` base
- Accent color: `#3b82f6` (blue)
- Text: `#e4e4e7` (light gray)
- Borders: `#3f3f46` (dark gray)

## JavaScript Architecture (editor.js)

### Structure (approximate line numbers)
1. **GrapesJS Init** (1-200) - Editor configuration, plugins
2. **Custom Blocks** (200-820) - All block definitions including new sections
3. **Component Types** (900-1040) - Video wrapper types with traits
4. **Device Switching** (1040-1080)
5. **Undo/Redo/Clear** (1080-1120)
6. **Preview** (1120-1140)
7. **Panel Tabs** (1140-1200)
8. **Style Mode Toggle** (1200-1220)
9. **Context-Aware UI** (1220-1400) - Element type detection, section visibility
10. **Color/Style Presets** (1400-1600) - Click handlers for all presets
11. **Background/Overlay Controls** (1600-1700)
12. **Navigation Controls** (1700-1800) - Sync with pages, add/remove links
13. **Link Editing** (1800-1850)
14. **Save Status** (1850-1900)
15. **Keyboard Shortcuts** (1900-1950)
16. **Selection Handling** (1950-2050) - Update UI on selection change
17. **Context Menu** (2050-2200) - Right-click functionality
18. **Page Management** (2200-2600) - Pages CRUD, switching, modals
19. **Export Functionality** (2630-2810) - ZIP export with JSZip

### Key Functions
- `convertToEmbedUrl(url)` - Converts YouTube/Vimeo URLs to embed format
- `applyVideoUrl(component, url)` - Applies video to wrapper component
- `getElementType(tagName)` - Returns element category for context-aware UI
- `showSectionsForElement(component)` - Shows relevant guided panel sections
- `loadPages()` / `savePages()` - Page persistence
- `switchToPage(pageId)` - Page switching with auto-save
- `loadNavLinks(component)` - Populate nav links list in guided panel
- `generatePageHtml(page, includeFonts, minifyCss)` - Generate standalone HTML for export
- `createAndDownloadZip(includeFonts, minifyCss)` - Create ZIP and trigger download

## Development Notes

### Adding New Blocks
1. Add to `blockManager.add()` section
2. Choose appropriate category
3. Use inline styles for immediate visibility
4. Add `data-*` attributes for custom component types if needed

### Adding New Guided Controls
1. Add HTML section in `index.html` inside `#guided-styles`
2. Add section reference in `sections` object
3. Update `showSectionsForElement()` to show for relevant element types
4. Add click handlers for presets
5. Add CSS in `editor.css`

### Custom Component Types
Use `editor.DomComponents.addType()` for:
- Custom traits in Settings panel
- Special behavior on attribute changes
- Detection via `isComponent` function

### Testing Video Embeds
YouTube/Vimeo embeds may not work in GrapesJS canvas (nested iframe issue) but work correctly in Preview mode and published sites.

## Future Enhancements (from design doc)

### Phase 2: Backend Integration
- PHP backend for user authentication
- Database storage for projects
- Multiple project support

### Phase 3: Publishing
- Save/publish sites to server
- Subdomain or custom domain support
- Template library

### Phase 4: Enhancements
- More block types
- Custom CSS injection
- Asset manager for images
- SEO settings per page