# CrossWordGrid Generator - User Guide

A tool for generating crossword-style word grids from your word list.

## Quick Start

1. **Start the application**:
   ```bash
   python3 -m http.server 8000
   ```
   Open http://localhost:8000/ in your browser

2. **Add words** to your list (one at a time)
   - Words are automatically converted to UPPERCASE
   - Empty words are rejected

3. **Reorder words** by dragging them up or down (optional)
   - Words at the end are more likely to be dropped if they don't fit

4. **Set grid size** (3×3 to 20×20, default 10×10)

5. **Click "Generate Grids"**
   - Watch real-time progress: "Generating... (X/5 found)"
   - Algorithm generates 1-5 unique candidate grids

6. **Preview candidates**
   - Click thumbnails to preview different grids
   - Large preview shows full detail

7. **Choose output format**
   - Click **Crossword** — empty cells display as black squares (traditional crossword style)
   - Click **Wordsearch** — empty cells are filled with random letters
   - You can flip between the two formats at any time

8. **Printed output format**
   When sending to print, only the grid is sent, full-width

## Bookmarking and Sharing

**Your word list and settings are saved in the URL!**

- The URL updates automatically as you add/remove words or change settings
- **Bookmark** the page to save your current word list and grid configuration
- **Share** the URL with others to collaborate on word lists
- Example URL: `?words=CAT,DOG,BIRD&width=12&height=10&all_cross=false`

Reloading the page or opening a bookmarked URL restores your complete setup.

## Tips

**Word Selection:**
- Use words that share letters for better crossword-style grids
- Example: DOG, DIG, GOT (share D, G, O)
- Grid generation works best with 3-8 words

**If some words don't fit:**
- The app will show which words were used vs dropped
- Try a larger grid size
- Reorder your word list (priority words first)
- Remove or replace problematic words

**Grid Size:**
- Start with 10×10 for most word lists
- Use smaller (5×5) for 2-3 short words
- Use larger (15×15+) for many long words

## Iterative Workflow

You can edit words and grid settings after viewing results:
1. Generate grids
2. Review candidates
3. Edit word list or grid size
4. Generate again with new settings

Controls are only disabled while the algorithm is running.

## Example Word Lists

**Easy (3 words):**
- CAT, HAT, RAT (3×3 grid)

**Medium (5 words):**
- HEAD, THIS, DOSE, FILM, MICE (10×10 grid)

**Challenge (8 words):**
- APPLE, PLANE, EAGLE, STEEL, LEECH, PEACH, TEACH, REACH (12×12 grid)

## Technical Notes

- **Crossword style**: All words must intersect at least once
- **Generation time**: Usually 1-2 seconds, max 5 seconds timeout
- **Output formats**: Crossword (black squares) or Wordsearch (random letters) — switchable any time
- **Unique solutions**: Each candidate grid has a different layout

## Troubleshooting

**"Failed to generate grids":**
- Your words may not share enough letters to intersect
- Try a larger grid size
- Add words that share letters with existing words

**Words being dropped:**
- Increase grid size
- Move important words to the start of your list
- Ensure words share common letters

**No candidates generated:**
- Check that words can intersect (share letters)
- Increase grid dimensions
- Try a different word combination

## Files

- **index.html** - Main application
- **testRunner.html** - Run tests in browser
- **js/gridgen.js** - Grid generation algorithm (reusable)

For developers: See [claude.md](claude.md) for architecture and [decisions.md](decisions.md) for design rationale.