# CLAUDE.md

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

## Project Overview

This is a WordPress plugin called "Cursor Style & Animation" that adds customizable cursor animations and styles to websites. It features 4 animation types (trail, particles, ripple, magnetic), 10+ cursor styles, custom cursor image support, and mobile optimization.

## Architecture

### Data Flow
1. **PHP Settings** (`cursor-animator.php`): Registers WordPress options, sanitizes input, and passes settings to frontend via `wp_localize_script()` as `csanimSettings` object
2. **Frontend JS** (`assets/js/cursor-animator.js`): Reads `csanimSettings`, initializes animation classes, applies cursor styles
3. **Admin JS** (`admin/js/admin-script.js`): Handles settings UI, WordPress Media Uploader integration, live preview

### Animation System (cursor-animator.js)
- `BaseAnimation`: Abstract base class with canvas creation, mouse/touch event binding, lifecycle management
- `TrailEffect`: Extends BaseAnimation - draws trailing line segments following cursor
- `ParticleEffect`: Extends BaseAnimation - spawns particles with velocity/decay physics
- `RippleEffect`: Extends BaseAnimation - creates expanding circular ripples
- `MagneticEffect`: Extends BaseAnimation - applies transform translations to nearby elements

All animations use HTML5 Canvas with `requestAnimationFrame` for rendering.

### Cursor Style System
- `initCursorStyles()`: Entry point, adds `csanim-custom-cursor` class to body when custom cursor active
- `applyCursorStyle()`: Sets CSS `cursor` property on elements with proper `url()` syntax
- `applyElementSpecificCursors()`: Applies appropriate cursors to interactive elements (links, buttons, inputs)

### WordPress Integration
- Settings stored as individual options with `csanim_` prefix
- Admin page registered under Settings menu at `csanim-settings`
- Uses WordPress Settings API with sanitization callbacks
- Media Uploader integration via `wp_enqueue_media()`

## Key Files

| File | Purpose |
|------|---------|
| `cursor-animator.php` | Main plugin file, WordPress hooks, settings registration |
| `assets/js/cursor-animator.js` | Frontend animation engine (vanilla JS) |
| `assets/css/cursor-animator.css` | Frontend styles, cursor classes, accessibility rules |
| `admin/admin-page.php` | Settings page HTML template |
| `admin/js/admin-script.js` | Admin UI logic, media uploader (jQuery) |
| `admin/css/admin-style.css` | Admin page styling |

## WordPress Options

All options use `csanim_` prefix:
- `csanim_enabled` - Plugin on/off ('1'/'0')
- `csanim_type` - Animation type ('trail', 'particles', 'ripple', 'magnetic')
- `csanim_cursor_style` - Cursor style ('default', 'pointer', 'custom', 'hidden', etc.)
- `csanim_custom_cursor` - Custom cursor image URL
- `csanim_cursor_size` - Custom cursor size (16-64px)
- `csanim_trail_*` - Trail-specific settings (length, size, color)
- `csanim_speed` - Animation speed multiplier (0.1-2.0)
- `csanim_mobile` - Enable on mobile ('1'/'0')

## Testing

Open `demo.html`, `test-animations.html`, or `test-effects.html` in a browser for standalone testing without WordPress.

For WordPress testing, install in `/wp-content/plugins/` and access Settings > Cursor Style & Animation.

## Known Issues

### Custom Cursor URL Syntax
The CSS cursor property requires specific syntax: `url("image.png") x y, fallback`. Hotspot coordinates (x, y) must be integers. The current implementation at `cursor-animator.js:443` uses `size / 2` which may produce decimals - should use `Math.floor(size / 2)`.

### CSS Specificity
Element-specific cursor rules in `cursor-animator.css` (lines 207-241) use `body:not(.csanim-custom-cursor)` selector to avoid overriding custom cursors. When custom cursor is active, the body gets `csanim-custom-cursor` class to bypass these rules.

### Settings Passed as Strings
WordPress `wp_localize_script()` passes all values as strings. The JS code must parse numeric values (e.g., `parseInt(settings.trailLength)`).