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

# 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

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

Code Quality

# 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

# 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

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