olemd/glitchcraft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Reformat and enhance CLAUDE.md documentation

Browse source 
Improvements:
- Added project tagline and branding
- Reorganized sections for better flow
- Added Quick Start section
- Enhanced architecture documentation with component details
- Added deployment guidelines and checklist
- Included testing requirements
- Added common tasks section
- Improved formatting and readability
- Added debugging tips

The documentation now provides clearer guidance for future development
and maintenance of the GlitchCraft PWA.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Ole-Morten Duesund 2025-08-18 20:04:53 +02:00
commit 736f784511
1 changed files with 161 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

231
CLAUDE.md
View file

@ -4,111 +4,190 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
GlitchCraft is a Progressive Web App (PWA) that generates zalgo text (corrupted/glitched text using Unicode combining characters). The app features real-time text corruption with adjustable intensity and click-to-copy functionality. **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 ## Project Structure
``` ```
zalgo/ zalgo/
├── app/ # Main application directory (served as document root) ├── app/ # Main application (served as document root in production)
│ ├── index.html # Main HTML page │ ├── index.html # Main HTML page
│ ├── zalgo.js # Zalgo text generation logic │ ├── zalgo.js # Zalgo text generation engine
│ ├── app.js # Main application logic and PWA registration │ ├── app.js # Application logic and PWA registration
│ ├── styles.css # Application styles │ ├── styles.css # Application styles (dark theme)
│ ├── sw.js # Service worker for offline functionality │ ├── sw.js # Service worker for offline support
│ ├── manifest.json # PWA manifest │ ├── manifest.json # PWA manifest configuration
│ ├── icons/ # PWA icons (SVG placeholders) │ └── icons/ # PWA icons (currently SVG placeholders)
│ ├── create-icons.js # Node.js script to generate PNG icons ├── server.py # Development server (dual-stack IPv4/IPv6)
│ └── generate-icons.html # Browser-based icon generator ├── package.json # Node.js dependencies and scripts
├── server.py # Development server (serves app/ as root) ├── bun.lockb # Bun package manager lockfile
├── package.json # Node dependencies and scripts
├── bun.lockb # Bun lockfile
├── .eslintrc.json # ESLint configuration ├── .eslintrc.json # ESLint configuration
└── .prettierrc # Prettier 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 ## Development Commands
### Running the Application ### Server & Testing
```bash ```bash
# Start development server (serves on http://localhost:8000/ and [::]:8000) python3 server.py # Start dev server with dual-stack support
python3 server.py bun run serve # Alternative: start server via npm script
# Or using the npm script
bun run serve
``` ```
### Code Quality and Linting ### Code Quality
```bash ```bash
# Lint JavaScript files # JavaScript
bun run lint:js 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
# Lint and auto-fix JavaScript # Python
bun run lint:js:fix black server.py # Format Python code
pylint server.py # Lint Python code
# Format all code with Prettier
bun run format
# Check formatting without changes
bun run check
# Lint Python code
black server.py
pylint server.py
``` ```
### Generating Icons ### Icon Generation
```bash ```bash
# Install canvas package first (optional, for PNG generation) # Method 1: Node.js script (requires canvas package)
bun add canvas bun add canvas # Install canvas dependency
node app/create-icons.js # Generate PNG icons
# Generate PNG icons programmatically # Method 2: Browser-based
node app/create-icons.js # Open app/generate-icons.html in browser
# Right-click and save each icon manually
# Or open app/generate-icons.html in browser and manually save icons
``` ```
## Architecture and Key Components ## Architecture
### Zalgo Text Generation (zalgo.js) ### Core Components
- **ZalgoGenerator class**: Core text corruption engine
- Uses Unicode combining diacritical marks (above, middle, below)
- Intensity scale 1-10 controls corruption amount
- `generate()`: Creates zalgo text from input
- `clean()`: Removes corruption from text
### Application Logic (app.js) #### `zalgo.js` - Text Corruption Engine
- Real-time text corruption as user types - **Class:** `ZalgoGenerator`
- Click-to-copy functionality with visual feedback - **Methods:**
- Keyboard shortcuts (Ctrl+K to clear) - `generate(text, intensity)` - Corrupts text with Unicode combining marks
- PWA installation handling - `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 - Service worker registration
### PWA Implementation #### `sw.js` - Service Worker
- **Service Worker (sw.js)**: Enables offline functionality with cache-first strategy - Cache-first strategy for offline support
- **Manifest (manifest.json)**: PWA configuration for installability - Caches all essential files on install
- Caches all essential files for offline use
- Automatic cache cleanup on update - Automatic cache cleanup on update
- Handles offline fallback
### Styling (styles.css) #### `server.py` - Development Server
- Dark theme with glitch-inspired aesthetics - Dual-stack server (IPv4 and IPv6)
- Responsive design for mobile and desktop - Serves `app/` directory as document root
- CSS animations for glitch effects - Adds required PWA headers
- Print-friendly styles - No external dependencies (uses Python stdlib)
## Deployment Notes ### Styling & Design
- Dark theme (#0f0f14 background)
- Glitch-inspired animations
- Accent color: #00ff88 (bright green)
- Responsive breakpoint: 600px
- Monospace font for text areas
- The `app/` directory should be served as the document root ## Deployment Guidelines
- All paths in the app are relative to assume `app/` is the root
- Service worker requires HTTPS in production (except localhost)
- Icons are currently SVG placeholders; generate PNGs for production
## Testing Checklist ### 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
When making changes, ensure: ### Pre-deployment Checklist
1. Text corruption works with various Unicode characters - [ ] Generate PNG icons (replace SVG placeholders)
2. Copy functionality works on both desktop and mobile - [ ] Test PWA installation on mobile devices
3. PWA installs correctly - [ ] Verify offline functionality
4. Offline mode functions properly - [ ] Check HTTPS certificate
5. Responsive design works on all screen sizes - [ ] Test on multiple browsers (Chrome, Firefox, Safari, Edge)
6. All linting passes (JavaScript, Python, HTML validation)
## 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, minimal warnings
- Prettier: All files formatted
- Black: Python code formatted
- Pylint: Score 10/10
## 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