CrosswordMaker.app is a browser-based crossword generator for teachers. You give it a topic, or paste your own word list, and get a printable puzzle with a separate answer key. Early on we made one rule that shaped everything else: the language model never sees, draws, or edits the grid. It proposes words and clues. A program does the rest.
This post is about that split: why we made it, what each side does, and the search and validation code that does the grid work. All the numbers come from our engine and its benchmark data, not from estimates.
TL;DR
- A crossword grid is a constraint problem: every shared square has to be right for two words at once, and every answer needs exactly as many boxes as letters. Chatbots write text one token at a time and don't check their work, which is the wrong shape for that job.
- The model returns
{ answer, clue }pairs through a JSON schema. The schema has no fields for coordinates, numbering, or validation. We treat its output like any other untrusted input. - Layout is a seeded depth-first search in plain TypeScript. It runs on the browser's main thread with a 25,000-node budget. A memo of layouts already explored means a list with no full layout can be proven impossible cheaply.
- An independent validator rescans the finished grid. It doesn't trust the search.
- On 90 classroom word lists (4,500 builds), 98.9% of first builds placed every word. Median build time was 1 ms; p95 was 6 ms.
The problem with asking a chatbot for a grid
The grid above holds 8 answers, from VAPOR to TRANSPIRATION: 75 letters with 7 shared squares. To be solvable, all of this has to hold at once:
- Each answer gets exactly as many boxes as it has letters.
- Each shared square has the right letter for both its across and its down word.
- No two answers run side by side. If they did, the touching letters would spell "words" with no clue.
- Everything connects.
- Clue 4 Down starts in the square numbered 4.
Ask a chatbot to draw this and you're asking an autoregressive model to commit to row 1 before it has written the down words that must pass through it. You're also asking it to reason about the 7th letter of CONDENSATION when it sees that word as a couple of tokens, not twelve letters. And nothing checks the result unless the model runs code. Even a correct text grid can drift a column in a chat window.
To be clear, we didn't benchmark chatbot grids, and this isn't a "models are bad" post. A model that writes and runs a layout program can do fine. That's the same idea we use: let a program own the grid.
The split
| Language model | Program | |
|---|---|---|
| Picks words for a topic | ✅ | |
| Writes classroom clues | ✅ | |
| Cleans answers (A–Z, length, duplicates) | ✅ | |
| Flags clues that contain their answer | ✅ | |
| Lays out the grid | ✅ | |
| Numbers it | ✅ | |
| Validates it | ✅ | |
| Quotas, billing, IDs | ✅ |
The model's side
The server calls a small hosted model with Structured Outputs. The schema (zod) is deliberately boring:
export const TopicModelOutputSchema = z.object({ title: z.string().min(1).max(120), theme_blurb: z.string().min(1).max(280), entries: z .array(z.object({ answer: z.string().min(1).max(64), clue: z.string().min(1).max(280), })) .min(5) .max(30), }); There's nowhere to put a coordinate. The system prompt says it outright: "You propose crossword answers and clues only. The host application owns grid layout, numbering, validation, billing, and IDs." The user prompt adds rules such as "clues must not contain the answer verbatim" and "never include grid coordinates, numbering, validation flags, prices, or ownership fields."
Then we treat the response as untrusted:
- Normalization. Answers become A–Z: spaces, hyphens, and apostrophes are removed, and "ice cream" becomes ICECREAM. Digits and symbols are rejected. Accented letters are not silently transliterated (in a language class, the accent might be the point); the teacher sees a suggestion instead. Answers must be 3–24 letters, and duplicates are flagged.
- Clue-leak check. A cheap program check catches the most common bad clue:
export function clueLeaksAnswer(clue: string, answer: string): boolean { if (answer.length < 3) return false; const words = clue.toUpperCase().replace(/[^A-Z\s]/g, " ").split(/\s+/).filter(Boolean); return words.includes(answer) || words.join("") === answer; } - Review state. Every AI entry arrives as
needs_review. Nothing the model writes is ever marked fact-checked, and every clue is editable.
If you paste your own list, the model isn't involved unless you ask it to write clues for your answers. In that mode it gets the answer list and must return one clue per answer, without adding, dropping, or renaming any.
The program's side
The pipeline is normalize → build → number → validate. The rest of this post is about build and validate.
Placement rules
Everything starts with one function that says whether a word may go at (row, col, direction). The rules are the five constraints above, turned into local checks:
// (trimmed) canPlace(cells, size, word, row, col, direction) // 1. In bounds. // 2. The cells just before and after the word must be empty, or the run would // extend into another word (a "ghost word"). // 3. For each letter: // - Existing letter: it must match, and the cell must not continue a word in // the same direction (that would overlay VERB inside ADVERB). Count a crossing. // - Empty cell: its perpendicular neighbours must be empty, or the new letter // would touch another word side by side. // 4. After the first word, at least one crossing is required (connectivity). Finding slots without scanning the whole grid
On a 25×25 grid, testing every cell in both directions for every word at every search node gets slow. But a crossing slot is pinned by which existing letter it reuses. So we keep an index of letter → cell positions, and for each letter of the word, enumerate only the slots that put that letter on a matching cell:
for (let i = 0; i < word.length; i++) { for (const pos of index.get(word[i]) ?? []) { const r = Math.floor(pos / cols), c = pos % cols; for (const dir of ["across", "down"]) { const sr = dir === "down" ? r - i : r; const sc = dir === "across" ? c - i : c; // dedupe, then canPlace(...); score = crossings * 10 + rand() } } } That gives the same set of slots, far cheaper. Slots with more crossings sort first, and a seeded random tiebreak adds variety.
The opening word is a special case. On an empty grid, off-centre starts are mostly translated copies of the same search, and corner starts waste space. So we offer only the two slots per direction nearest the centre, with a little seeded jitter.
The search
It's a depth-first search over (word, slot) choices:
function dfs(remaining: WordEntry[]): boolean { if (nodes >= budget) return false; const key = layoutKey(); // sorted "id@row,col,dir" of placed words if (visited.has(key)) return false; // reached this layout by another order visited.add(key); nodes++; recordIfBest(); // keep the best partial layout seen if (remaining.length === 0) return true; // Every remaining word that fits *now*, most-constrained (fewest slots) first. const options = remaining .map((w) => ({ w, slots: findSlots(w) })) .filter((o) => o.slots.length > 0) .sort((a, b) => a.slots.length - b.slots.length); for (const { w, slots } of options) { for (const slot of slots.slice(0, 24)) { // cap branching place(w, slot); if (dfs(remaining.without(w))) return true; undo(w, slot); // clear only the cells it filled } } return false; } Two bugs from earlier versions explain most of the design.
1. Committing to one word made the search incomplete. An older version picked the single most-constrained word and tried only its slots. But in the target layout, the first word you'd naturally place may cross a word that isn't on the board yet: FOG might cross a STORM that comes later. With no slot for FOG yet, the search gave up on lists that did have a connected layout. Now a word with no slot right now is skipped, not dropped, and the loop tries the next word.
2. Returning true at a dead end. Another version returned true from a dead end, which ended the whole search there. Now a dead end returns false and backtracks. The best partial layout is already recorded, so nothing is lost.
The visited memo is what makes "no" cheap. Placing A then B gives the same grid as B then A. Without the memo, the search explores both orders. With it, a list that truly has no full layout finishes in a few hundred nodes instead of burning the whole budget. This matters because "this list can't fully interlock" is a real answer we have to give teachers. In our benchmark, the 8-word weather list RAIN, WIND, SNOW, STORM, CLOUD, SUNNY, FOG, HAIL never fully fit. An exhaustive check confirmed that no layout holds all eight. Drop any one of CLOUD, FOG, or HAIL and it fits.
When the budget runs out or the tree is exhausted, we return the best layout found. Words that didn't fit are listed for the teacher, never silently dropped.
Picking a grid size
"Auto" tries 11×11, 13×13, 15×15, 17×17, 21×21, and 25×25 (skipping any size smaller than the longest word). Since the search is complete, a size that's too small is only ruled out by exhausting its share of the budget, and splitting 25,000 nodes six ways up front would starve the size that works. So there are two passes:
- Scouting: each size gets 40 nodes. Most lists fit right here, in the smallest grid that holds them.
- Deep pass: the rest of the budget is shared among the sizes whose trees the scouting pass didn't finish.
The first fully placed layout wins. Otherwise, results are scored on words placed first, then crossings, density, and squareness:
score = placed * 1000 + crossings * 20 + density * 10 + aspect; Determinism
Randomness comes from a seeded Mulberry32 PRNG, and each grid size gets seed + i * 997. The same list and seed always give the same grid. That buys us three things:
- Reproducible bugs. A bug report with a list and seed reproduces exactly.
- Editable examples. Published example puzzles carry a
seed:budgethint, so "Edit this crossword" rebuilds the exact grid you were looking at. - "Try another layout". This steps the seed forward until the layout actually changes, because nearby seeds sometimes produce the same arrangement.
The validator doesn't trust the search
After numbering, a separate module checks the grid as if a stranger had made it:
- It rescans every row and column for runs of 2 or more letters, independently of the placements the search reported.
- Each declared placement must match a scanned run letter for letter (
letter_mismatch,placement_not_on_grid). - Any scanned run with no placement is a
ghost_word. Any letter covered by no placement is anorphan_letter. - Two same-direction placements sharing cells is a
same_direction_overlap. More than one connected component isdisconnected. Two different numbers on one start square is anumber_conflict.
To check that the validator earns its keep, we took the correct water cycle grid and broke three copies on purpose (our own mistakes, not chatbot output):
| One mistake | Errors reported |
|---|---|
| A shared square holds a letter that fits only one of its two words | 6: letter_mismatch, placement_not_on_grid, ghost_word |
| An answer is one box short | 3: letter_mismatch, placement_not_on_grid, ghost_word |
| A stray letter beside an answer | 3: ghost_word, orphan_letter |
One wrong letter becomes six errors because it breaks two words at once. That's why a single mistake makes a crossword unsolvable for a student.
Numbers
We ran the maker's settings (25,000-node budget, auto size) on 90 real classroom word lists, 50 seeds each: 4,500 builds on Node 22.
| First build placed every word | 98.9% |
| Lists that always fit | 89 of 90 (the 90th is the weather list, proven impossible) |
| Mean share of words placed | 99.9% |
| Build time p50 / p95 | 1 ms / 6 ms |
| Mean crossings per word | 0.9 |
We also resampled random lists by size (200 samples each):
| Words | First build fits | p50 | p95 | Median grid |
|---|---|---|---|---|
| 6 | 98% | 0 ms | 3 ms | 11×11 |
| 10 | 100% | 2 ms | 6 ms | 15×15 |
| 15 | 99.5% | 8 ms | 13 ms | 17×17 |
| 20 | 100% | 14 ms | 23 ms | 21×21 |
| 30 | 100% | 36 ms | 146 ms | 25×25 |
That's fast enough to run on the main thread in the browser, with no Web Worker and no server round trip. Only the AI calls go over the network.
Honest limits
- These are free-form "classroom" crosswords, not dense, symmetric newspaper grids. About 0.9 crossings per word is typical for this style. A full American-style fill is a much harder constraint problem, and this engine doesn't try to solve it.
- English A–Z only. Accented answers are flagged, not converted.
- AI clues still need a human read. The clue-leak check catches one failure mode; wrong facts and clues pitched at the wrong level are on the teacher, and the UI says so.
- Free AI is limited. Anonymous visitors get about 3 AI operations a day. Building a grid from your own words and clues doesn't use AI, so that limit doesn't apply.
Try it
crosswordmaker.app: type a topic, or paste WORD | clue lines into the word-list maker. No sign-up is needed to build and preview a grid.
We'd love to hear from anyone who has worked on crossword construction or other constraint-search problems, especially about the size-selection heuristic. Scout-then-deep was the simplest thing that stopped small grids from starving, and we suspect there's a better answer.
