glitchcraft/CLAUDE.md

# CLAUDE.md

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

## Project Overview

**GlitchCraft** is a Progressive Web App (PWA) that generates zalgo text - corrupted/glitched text using Unicode combining characters. 

**Tagline:** "Artisanal text corruption, served fresh!"

### Key Features
- Real-time text corruption with adjustable intensity (1-10 scale)
- Click-to-copy functionality with visual feedback
- Progressive Web App with offline support
- Responsive design for all devices
- Dark theme with glitch aesthetics

## Project Structure

```
zalgo/
├── app/                    # Main application (served as document root in production)
│   ├── index.html         # Main HTML page
│   ├── zalgo.js           # Zalgo text generation engine
│   ├── app.js             # Application logic and PWA registration
│   ├── styles.css         # Application styles (dark theme)
│   ├── sw.js              # Service worker for offline support
│   ├── manifest.json      # PWA manifest configuration
│   └── icons/             # PWA icons (currently SVG placeholders)
├── server.py              # Development server (dual-stack IPv4/IPv6)
├── package.json           # Node.js dependencies and scripts
├── bun.lockb             # Bun package manager lockfile
├── .eslintrc.json        # ESLint configuration
├── .prettierrc           # Prettier code formatting config
└── .gitignore            # Git ignore patterns
```

## Quick Start

```bash
# Clone and enter directory
cd zalgo

# Install dependencies (using Bun)
bun install

# Start development server
python3 server.py
# Server runs on http://localhost:8000/ (IPv4) and http://[::1]:8000/ (IPv6)
```

## Development Commands

### Server & Testing
```bash
python3 server.py          # Start dev server with dual-stack support
bun run serve             # Alternative: start server via npm script
```

### Code Quality
```bash
# JavaScript
bun run lint:js           # Check JavaScript with ESLint
bun run lint:js:fix       # Auto-fix JavaScript issues
bun run format            # Format all files with Prettier
bun run check             # Check formatting without modifying

# Python
black server.py           # Format Python code
pylint server.py          # Lint Python code

# File References
just validate-references  # Check HTML/manifest file references exist
```

### Icon Generation
```bash
# Method 1: Node.js script (requires canvas package)
bun add canvas            # Install canvas dependency
node app/create-icons.js  # Generate PNG icons

# Method 2: Browser-based
# Open app/generate-icons.html in browser
# Right-click and save each icon manually
```

## Architecture

### Core Components

#### `zalgo.js` - Text Corruption Engine
- **Class:** `ZalgoGenerator`
- **Methods:**
  - `generate(text, intensity)` - Corrupts text with Unicode combining marks
  - `clean(text)` - Removes corruption from text
- **Character Sets:**
  - Above: Diacritical marks that appear above letters
  - Middle: Marks that overlay characters
  - Below: Marks that appear below letters

#### `app.js` - Application Controller
- Manages user interactions
- Real-time corruption on input
- Clipboard operations with visual feedback
- Keyboard shortcuts (Ctrl/Cmd+K to clear)
- PWA installation prompt handling
- Service worker registration

#### `sw.js` - Service Worker
- Cache-first strategy for offline support
- Caches all essential files on install
- Automatic cache cleanup on update
- Handles offline fallback

#### `server.py` - Development Server
- Dual-stack server (IPv4 and IPv6)
- Serves `app/` directory as document root
- Adds required PWA headers
- No external dependencies (uses Python stdlib)

### Styling & Design
- Dark theme (#0f0f14 background)
- Glitch-inspired animations
- Accent color: #00ff88 (bright green)
- Responsive breakpoint: 600px
- Monospace font for text areas

## Deployment Guidelines

### Production Setup
1. Serve `app/` directory as document root
2. Enable HTTPS (required for PWA features)
3. Configure proper MIME types for manifest.json
4. Set appropriate cache headers

### Pre-deployment Checklist
- [ ] Generate PNG icons (replace SVG placeholders)
- [ ] Test PWA installation on mobile devices
- [ ] Verify offline functionality
- [ ] Check HTTPS certificate
- [ ] Test on multiple browsers (Chrome, Firefox, Safari, Edge)

## Testing Requirements

### Functional Tests
1. **Text Corruption**
   - Various Unicode characters (emoji, special chars)
   - Empty input handling
   - Very long text performance

2. **User Interface**
   - Intensity slider (1-10 range)
   - Copy notification visibility
   - Clear button functionality
   - Keyboard shortcuts

3. **PWA Features**
   - Installation prompt
   - Offline mode
   - Icon display
   - App name in launcher

4. **Cross-platform**
   - Mobile responsiveness
   - Touch interactions
   - Desktop browsers
   - Print styles

### Code Quality
- ESLint: No errors, no warnings
- Prettier: All files formatted
- Black: Python code formatted
- Pylint: Score 10/10
- File References: All HTML/manifest references exist

## Common Tasks

### Adding New Features
1. Update `app.js` for UI logic
2. Modify `zalgo.js` for corruption algorithms
3. Update `styles.css` for visual changes
4. Increment cache version in `sw.js`
5. Run linting and formatting
6. Test offline functionality

### Updating Dependencies
```bash
bun update               # Update all dependencies
bun add [package]        # Add new dependency
bun remove [package]     # Remove dependency
```

### Debugging
- Check browser console for errors
- Verify service worker registration
- Use Chrome DevTools Application tab for PWA debugging
- Test with `python3 -m http.server` as fallback server