# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Bold Builder is a WordPress page builder plugin (version 5.4.8) that provides visual editing capabilities with a drag-and-drop interface. The plugin uses both front-end (live preview) and back-end editing modes.

## Build Commands

### Build JavaScript assets
```bash
npm run build
```
This runs webpack to compile the React/JSX code from `build/main.js` and `build/main_fe.js` into bundled JavaScript files. Webpack is configured to watch for changes by default.

### Install dependencies
```bash
npm install
```

### Python file watcher (development)
```bash
python pynline.py
```
This watches for changes in source files and inlines content into target files based on `pynline.json` configuration. Used during development to inject code snippets into larger files.

## Architecture

### Core Classes

- **BT_BB_Root**: Base class in `bold-builder.php` that manages the plugin initialization and element registration
- **BT_BB_Element**: Base class for all content elements (sections, rows, columns, buttons, etc.)
- **BT_BB_FE**: Front-end editor class in `bold-builder-fe.php` that handles live editing functionality

### Content Elements System

Content elements are located in `content_elements/*/bt_bb_*.php`. Each element:
- Extends `BT_BB_Element`
- Defines shortcode name (e.g., `bt_bb_section`, `bt_bb_button`)
- Implements `handle_shortcode()` method for rendering
- Defines parameters via `params` array in the element definition
- Has associated JavaScript handlers in `bold-builder-fe.php` for front-end editing

Common elements include:
- **bt_bb_section**: Top-level container with background, parallax, video backgrounds
- **bt_bb_row**: Row container with column layout
- **bt_bb_column**: Column container for content
- **bt_bb_button**, **bt_bb_headline**, **bt_bb_icon**, **bt_bb_image**: Content elements
- **bt_bb_accordion**, **bt_bb_tabs**, **bt_bb_slider**: Interactive components

### Front-End Editor

The front-end editor (`BT_BB_FE`) enables live editing:
- Element configurations in `BT_BB_FE::$elements` define JavaScript handlers for each parameter
- Handler types include: `js_handler`, `ajax_filter`, `js_callback`, `ajax_callback`
- Drag-and-drop functionality with SortableJS
- AJAX operations for saving and rendering content
- Uses TinyMCE for rich text editing

### Webpack Build System

Two entry points:
- `bundle.js`: Back-end/admin editor functionality
- `bundle_fe.js`: Front-end live editor functionality

Babel transpiles JSX/React code with `@babel/preset-react`. Source files are in `build/` directory.

### CSS Architecture

CSS is organized in `css/` directory:
- `front_end/*.css`: Front-end styles for content elements
- Uses CSS Crush for preprocessing (in development mode when server name contains '-dev')
- Separate stylesheets for each major component (sections, buttons, icons, etc.)

### Parameter System

Elements use a consistent parameter definition structure:
- `param_name`: Internal identifier
- `type`: Input type (textfield, dropdown, colorpicker, checkbox, textarea_object, etc.)
- `heading`: Label shown in UI
- `preview`: Whether to show in element preview
- JavaScript handlers in FE define how changes are applied (class changes, style updates, AJAX refresh)

### AJAX Handlers

Key AJAX actions in `bold-builder-fe.php`:
- `bt_bb_fe_save`: Save post content
- `bt_bb_fe_get_html`: Render shortcode to HTML
- `bt_bb_fe_get_template_html`: Load template layouts

### Color Schemes

Color schemes provide consistent styling across elements. Elements can reference color schemes by ID or name, which applies predefined color combinations and styles.

### Integration Points

- **WPML support**: Multi-language content editing with language-specific post updates
- **Contact Form 7**: Integration for form elements
- **Google Maps & Leaflet Maps**: Map rendering capabilities
- **AI assistance**: Located in `ai/ai.php` for content generation features

## Production Build Process

The `production.bat` script automates release preparation:
1. Creates version tags based on plugin header
2. Copies files excluding development artifacts
3. Removes source files, config files, and non-minified JS
4. Generates translation POT file using xgettext
5. Copies to production directory structure

Files excluded from production builds are listed in `exclude.txt`.

## Development Workflow

1. Make changes to PHP element files or JavaScript source files in `build/`
2. Run webpack (`npm run build`) to compile JavaScript changes
3. For development with pynline, run `python pynline.py` to watch file changes
4. Test in WordPress with front-end editor enabled
5. CSS changes in `css/front_end/` are loaded directly (or via CSS Crush in dev mode)

## Important Conventions

- All element shortcodes are prefixed with `bt_bb_`
- CSS classes follow BEM-like naming: `bt_bb_element_modifier`
- Front-end editing requires `current_user_can('edit_pages')`
- Nonce verification is used for all AJAX operations
- Content is sanitized with `wp_kses_post()` before saving
- Special character encoding: backticks and brackets are encoded for WordPress shortcode compatibility