From 736f784511d9de91f7e95dc63bc52879f7833bc1 Mon Sep 17 00:00:00 2001 From: Ole-Morten Duesund Date: Mon, 18 Aug 2025 20:04:53 +0200 Subject: [PATCH] Reformat and enhance CLAUDE.md documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- CLAUDE.md | 231 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 155 insertions(+), 76 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0e5bbf0..29eed55 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,111 +4,190 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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 ``` zalgo/ -├── app/ # Main application directory (served as document root) +├── app/ # Main application (served as document root in production) │ ├── index.html # Main HTML page -│ ├── zalgo.js # Zalgo text generation logic -│ ├── app.js # Main application logic and PWA registration -│ ├── styles.css # Application styles -│ ├── sw.js # Service worker for offline functionality -│ ├── manifest.json # PWA manifest -│ ├── icons/ # PWA icons (SVG placeholders) -│ ├── create-icons.js # Node.js script to generate PNG icons -│ └── generate-icons.html # Browser-based icon generator -├── server.py # Development server (serves app/ as root) -├── package.json # Node dependencies and scripts -├── bun.lockb # Bun lockfile +│ ├── 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 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 -### Running the Application +### Server & Testing ```bash -# Start development server (serves on http://localhost:8000/ and [::]:8000) -python3 server.py - -# Or using the npm script -bun run serve +python3 server.py # Start dev server with dual-stack support +bun run serve # Alternative: start server via npm script ``` -### Code Quality and Linting +### Code Quality ```bash -# Lint JavaScript files -bun run lint:js +# 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 -# Lint and auto-fix JavaScript -bun run lint:js:fix - -# Format all code with Prettier -bun run format - -# Check formatting without changes -bun run check - -# Lint Python code -black server.py -pylint server.py +# Python +black server.py # Format Python code +pylint server.py # Lint Python code ``` -### Generating Icons +### Icon Generation ```bash -# Install canvas package first (optional, for PNG generation) -bun add canvas +# Method 1: Node.js script (requires canvas package) +bun add canvas # Install canvas dependency +node app/create-icons.js # Generate PNG icons -# Generate PNG icons programmatically -node app/create-icons.js - -# Or open app/generate-icons.html in browser and manually save icons +# Method 2: Browser-based +# Open app/generate-icons.html in browser +# Right-click and save each icon manually ``` -## Architecture and Key Components +## Architecture -### Zalgo Text Generation (zalgo.js) -- **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 +### Core Components -### Application Logic (app.js) -- Real-time text corruption as user types -- Click-to-copy functionality with visual feedback -- Keyboard shortcuts (Ctrl+K to clear) -- PWA installation handling +#### `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 -### PWA Implementation -- **Service Worker (sw.js)**: Enables offline functionality with cache-first strategy -- **Manifest (manifest.json)**: PWA configuration for installability -- Caches all essential files for offline use +#### `sw.js` - Service Worker +- Cache-first strategy for offline support +- Caches all essential files on install - Automatic cache cleanup on update +- Handles offline fallback -### Styling (styles.css) -- Dark theme with glitch-inspired aesthetics -- Responsive design for mobile and desktop -- CSS animations for glitch effects -- Print-friendly styles +#### `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) -## 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 -- 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 +## Deployment Guidelines -## 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: -1. Text corruption works with various Unicode characters -2. Copy functionality works on both desktop and mobile -3. PWA installs correctly -4. Offline mode functions properly -5. Responsive design works on all screen sizes -6. All linting passes (JavaScript, Python, HTML validation) \ No newline at end of file +### 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, 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 \ No newline at end of file