What I learned writing a crossword generator that runs in the browser

Casey Jefferson — Tue, 08 Sep 2026 14:06:04 +0000

Most of my side-project time goes into a small site that holds the full King James Bible text with a few word games sitting on top of it. The games started as a weekend joke. They are now the part I actually maintain.

The crossword ate the most evenings, and not for the reason I expected. Drawing the grid is nothing — CSS grid, a couple of input handlers, done in an afternoon. Filling the grid is where I got humbled.

The greedy version, which I shipped anyway

First attempt was about as naive as it gets:

Sort the words longest first.
For each word, scan the board for a cell whose letter matches one of its letters.
Drop it into the first slot that doesn't break a neighbour.
If nothing fits, shrug and skip the word.

That worked for maybe six words out of ten. The rest got skipped, so the puzzle came out sparse and half the clues pointed at nothing. My fix at the time was to run the whole thing 200 times with a shuffled word order and keep the densest result. It was dumb and it shipped and nobody complained for two months.

What actually fixed it

Backtracking, but with the cheap heuristics doing the real work:

keep a Map of every placed letter keyed by row,col, so checking a candidate slot is a lookup and not a scan
score each possible placement by how many existing letters it crosses, prefer more crossings
place, recurse, undo on failure, with a step budget so a bad seed can't hang the tab
if the budget blows, drop the longest unplaced word and restart the branch

The search itself is textbook. The ordering is what moved the numbers. Sorting candidates by crossing count rather then by length cut the average placement attempts by something like 8x on my test set of 40 puzzles.

The boring part that mattered most

The word list. Biblical vocabulary is genuinely hostile to crosswords — it is full of proper nouns nobody can spell and long names that cross with nothing. NEBUCHADNEZZAR is fourteen letters of dead weight. Anything over nine letters now goes into a "bonus" bucket that the generator drops first when it gets stuck, and the core list is hand-checked, 4 to 9 letters, weighted toward words with common vowels.

I spent two weeks tuning the algorithm and then got a bigger improvement in one evening of editing a text file. That keeps happening to me.

Seed everything, do it early

The one thing I would do differently: make it deterministic from day one. I now use a small mulberry32 PRNG and pass a seed through the whole generator, so the daily puzzle is identical for every visitor and a bug report is just a seed number. Before that I burned an entire evening chasing a broken grid I could not reproduce, because every reload built a different board.

Mobile input

Short version — don't put a real <input> in every cell. One hidden input, a caret you draw yourself, and arrow/tab handling that skips black squares. iOS Safari will fight you about the keyboard staying open; a readonly toggle on blur is what finally settled it for me.

The live version is here if you want to poke at the grid behaviour: the Bible crossword. The generator runs entirely client-side, so view-source is basically the whole story.