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
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)
### 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