Crossword Puzzle Maker

On December 21, 1913, the Sunday fun page of the New York World carried a diamond-shaped puzzle with a hollow centre. Arthur Wynne called it a word-cross. An illustrator later swapped the halves of the name, and the crossword had its word. The idea Wynne fixed in place is still the whole idea: words run across and down, and wherever two of them meet they must share a letter.

That one rule is what makes a crossword feel fair. A stuck solver gets help from every word that crosses the clue. Break the promise once and the puzzle stops being a puzzle.

Placing words is a search, not a drawing

A teacher who wants a puzzle on the solar system, or a family that wants one for a birthday, starts with a list of answers and clues. The grid has to be found. Crossword software has worked this way since at least 1976, when the earliest programs took a list of fill words and mapped them onto a grid. Wikipedia’s crossword article describes this as a search problem: there are many possible arrangements, each has to be checked against the rules of construction, and a given set of answers might have no legal arrangement, one, or many.

Computer scientists file it under constraint satisfaction. A constraint satisfaction problem has variables, a set of allowed values for each, and constraints that rule out bad combinations; crosswords appear in the standard list of examples beside Sudoku and the eight queens. Here the variables are the positions of the words, and the constraints are the rules every printed crossword follows.

The usual way to search such a space is backtracking. You build a candidate one piece at a time and abandon it the moment it can no longer become a valid answer. In a crossword maker that means placing the longest word first, then trying every spot where the next word could cross a letter already on the board, and stepping back to try an earlier word somewhere else when a later word has nowhere to go.

Exhaustive backtracking over a long list is slow, so practical makers mix it with restarts. The hill climbing literature describes the trick plainly: a local search can get stuck on a layout that cannot be improved by small changes, and running it again from different starting points is a simple way out. This tool runs a fixed number of seeded attempts, 80 at the Normal setting, keeps a small backtracking budget inside each, and keeps the best grid: most words placed, then most crossings, then the smallest box.

The randomness is seeded, using Marsaglia’s xorshift generator, which produces each new number from the last with three shifts and exclusive-or steps. The point is repeatability. The same list and the same seed give the same grid on any device, so a teacher can rebuild last year’s puzzle exactly.

The rule against accidental words

Crossing letters must agree. That part is obvious. The less obvious rule is the one that separates a real crossword from a heap of words that happen to touch: every run of two or more letters, across or down, must be one of your words.

Picture two answers laid side by side in neighbouring rows. Each is fine on its own, but every column where they sit together now reads a two-letter scrap from top to bottom, and none of those scraps has a clue. The solver sees a run of white squares with no number and no hint. A word that ends right where another begins does the same damage in a straight line, fusing two answers into one long nonsense entry.

So the maker checks four things before it accepts any placement. The letters agree at every crossing. The squares just before the first letter and just after the last are empty. A crossing square is not already used by a word running the same way. And each new letter has empty neighbours on both sides across the word. Break the last rule and the stray runs appear at once: in testing, a copy of the generator with that check removed produced a stray word in 99 of 100 random puzzles.

Rules in the generator are not enough on their own, because the generator is the thing being checked. A separate checker reads only the finished grid. It confirms the letters form one connected group, using a breadth-first search that spreads from one square to every square that shares a side. It lists every maximal run and insists each is exactly one listed word, used once. Over 500 random lists of 5 to 60 words, every grid passed, and an independent checker written in another language agreed.

Why some lists will not connect

A word joins the grid only where it shares a letter with something already there. RHYTHM and QUIZ share none, and no amount of searching can join them. The honest answer is to say so.

That is why the maker reports every word as placed or not placed, with a reason. Some words share no letter with any other word at all. Some share letters only with other words that were also left out, forming a little island the main grid never reaches. Some could cross in principle but found no legal spot in the best layout, which usually means the grid is too small or the list is crowded with long words that block each other. The fixes are different: add a bridging word, raise the largest side, or try another seed.

It also matters what the tool will not do. It has no dictionary. It never fills a blocked grid with words of its own choosing, the way newspaper constructors pack every square of a symmetric 15 by 15 design. What it builds is closer to the free-form criss-cross style that classroom puzzles use, with your words and nothing else. Clues are yours too, shown exactly as you wrote them.

Numbers, lengths and letters

Numbering looks like decoration but follows a firm convention. Among the schemes tried early on, the one that became standard numbers only the squares that start a word, reading left to right and top to bottom. A square gets the next number if it starts an across word, a down word, or both, so 1 Across and 1 Down can share a square.

Answers that are phrases need a length hint. Cryptic crosswords print the letter count after the clue, with a series of numbers for a phrase: “cryptic crossword” is shown as (7,9). This tool does the same from what you typed. MILKY WAY becomes (5,3), and STAR-GAZER keeps its hyphen as (4-5). Spaces and hyphens are left out of the grid itself, since each square holds one letter.

Letters are harder than they look once a list leaves plain English. The same accented letter can be stored as one character or as a base letter plus a combining mark, and Unicode treats the two as canonically equivalent. Normalizing to the composed form, which JavaScript does with String.prototype.normalize, makes them compare as equal, and grapheme segmentation keeps a letter and its marks together in one square.

Whether an accented letter may cross a plain one is a matter of language. Portuguese, Romanian and Latin crosswords ignore most accents; Irish crosswords keep them as different letters. The maker keeps them distinct by default and folds them on request. It also uses a collator at base sensitivity to point out answers that differ only by accents or case, since those are usually typing slips.

A worked example you can rebuild

Open the tool and leave the example list alone: fifteen night sky answers, from TELESCOPE and ASTRONAUT down to COMET and ORBIT, with the seed at 2026, Normal effort and a largest side of 17. The search tries 80 layouts and keeps a grid 16 squares wide and 12 tall.

All 15 words are placed, on 84 letter squares. Those squares sit in a box of 192, so the density shows as 44 percent. The grid has 16 crossings, two more than the 14 that the minimum needed to join 15 words into one piece. Change the seed and you get a different grid; set it back to 2026 and the same one returns.

Printing a puzzle people can solve on paper

A crossword that will be solved with a pencil needs room for the pencil. The PDF here uses squares of 8.5 millimetres, or 10.6 in large print, and makes them smaller only when the grid would not fit the page. The clues sit under the grid in two columns, Across on the left and Down on the right, and carry on to a new page instead of shrinking. The answer key always starts a page of its own, so a teacher can hand out the puzzle without the solution on the back.

Fair clues are the other half of fairness. Match the answer’s tense and number, so “Traveled on horseback” leads to RODE and not RIDE. For a class, clue from what was taught. For a family, a shared joke works better than a dictionary definition.

Lists arrive in odd shapes. A CSV file from a spreadsheet follows RFC 4180, where a field holding a comma or a line break is wrapped in double quotes and a quote inside it is doubled. The maker reads such files on the device, a slice at a time. It treats every cell as plain text, so a clue that starts with an equals sign is printed, never run as a formula; OWASP warns that spreadsheets will run such cells when they are opened. Finished puzzles can be saved in ipuz, an open format that other crossword software reads.