letter-punk

Letter Punk

Live App: Play Letter Punk

How to Play

Letter Punk is a word-chain puzzle in the spirit of NYT’s Letter Boxed, played on a 12-letter board arranged as 4 sides of 3 letters each.

The basics

• Tap a letter to add it to the word you’re building, or type it on your keyboard — both do exactly the same thing. Consecutive letters must come from different sides of the board — you can’t chain two letters from the same side back to back. Keyboard entry needs a board with no repeated letters to stay unambiguous, which every board the app can produce or accept already guarantees (generated boards, daily puzzles, shared links, and the manual “New Game” form all reject duplicates); it’s included as a genuine alternative input method, not a fallback, for players who find tapping tiles difficult.
• Words need at least 3 letters, and are checked locally against two combined dictionaries as you type — nothing is ever sent to a server. Turn on “Show dictionary provenance bar” in Settings for a bar next to Accepted Words summarizing which dictionary source(s) accepted your words; click it for a per-word breakdown. See Dual Dictionary Validation for how the underlying validation works.
• After your first word, every new word must start with the last letter of the previous word — unless “Free Chain mode” is on in Settings, which drops that requirement so you can use any word in any order.
• Use every letter on the board at least once to solve the puzzle. It can take as many words as you need — there’s no word-count limit and no way to “lose.”

Double letters Tap — or type — the same letter twice in a row to double it (e.g. the “ZZ” in “PUZZLE”). Classic Letter Boxed doesn’t allow this; Letter Punk treats it as first-class play — a real, deliberate part of solving the puzzle, not a workaround.

Undo controls

• Undo Letter removes one letter at a time, and can back up into a previously accepted word if the current one is already empty.
• Undo Word clears the word you’re building; press it again to remove the last accepted word.

Reading the board

• Unused letters appear as silver steel tanks; used letters switch to patina tanks with a checkmark badge, dashed border, and striped tag, so the state is clear without relying on color alone.
• A small xN badge appears on a tile once you’ve used that letter N times so far, across both accepted words and the word you’re building.
• The board header shows a running letter count — the total across every accepted word plus your word in progress, i.e. what your final character count would be if you hit Enter right now.

Solving and scoring Once you’ve used every letter, Letter Punk compares your total character count to a reference solution and awards one of three titles: Efficiency Engineer (you used fewer characters), Dead Reckoner (you matched it exactly), or Vocabulary Wrangler (you used more, weaving in extra letters). All three are equally legitimate ways to play well — see Canonical Solution Rating for the full reasoning.

Stuck? Ask for a hint Whenever a reference solution is known (daily puzzles, an imported Letter Boxed board, or a Random/Simple Puzzle — not Random Letters or a hand-built board, which have none), Hint appears next to Accepted Words as soon as you start, and stays available until you solve it. It opens three tiers you reveal one at a time, each showing strictly more than the last: word count and lengths, then each word’s start/end letters, then the full solution — reveal only as much as you actually want, in any order, and nothing is shown until you explicitly ask for that specific tier. Using a hint never affects scoring, titles, or anything Share/Reveal Solution show — it’s a private aid, not part of the record of how you solved it.

Boards and puzzles

• A new daily puzzle is available each day; use the </> arrows or “Today’s Puzzle” to navigate, and “Yesterday” to see the previous day’s canonical solution.
• Navigating to a daily puzzle you’ve already made progress on — partial or fully solved — picks up exactly where you left off, the same way it would if you’d never left, saved locally on your own device (no account, nothing sent to a server). Reset, next to the puzzle-navigation arrows, clears the puzzle currently on screen and starts it over from scratch; a few presses of Undo Word does the same thing by hand, since both just leave a blank board behind.
• New, next to the puzzle-navigation arrows, opens the “New Game” dialog. Right at the top, “Play today’s NYT Letter Boxed” links straight out to the real nytimes.com puzzle, for anyone who’d rather play the original directly; right below it, Letter (Punk) Boxed fetches that same day’s board and applies it right here in one click, no separate Apply step, closing the dialog itself — handy for playing alongside friends who are still on the original game, using Letter Punk’s own mechanics (double letters, Free Chain, no fail state) on the identical puzzle. When the source provides it, the real answer comes along too, held quietly the same way a generated board’s solution words are — never shown up front, only usable for scoring and Reveal Solution once you actually get there.
• That same “New Game” dialog also offers Random Puzzle and Simple Puzzle — both fully automated boards with a genuine reference solution, picked and paired the same way the daily catalog itself is generated, just held quietly rather than shown up front; Simple Puzzle narrows to a frequency-filtered, more everyday vocabulary than Random Puzzle’s broader tier. One of its two “Advanced” sections covers everything requiring more of your own input: pasting a board from classic Letter Boxed, generating one from your own solution word(s) (type a single word as a seed and Letter Punk finds a companion automatically), typing all 12 letters in by hand, or Random Letters — a raw random arrangement with no known solution at all, not guaranteed easy or even short to solve. Every option besides Letter (Punk) Boxed just fills the board fields for review — an explicit “Apply Board” click commits it. That same dialog’s “Copy Blank Link” / “Copy Progress Link” buttons send a board to a friend as a URL — either a fresh challenge, or exactly where your own play currently stands, replaying pipe-by-pipe when they open it. If your progress was played in Free Chain mode, the recipient’s copy turns it on automatically to match, without changing their own Settings default.

Sharing a result Once you’ve solved the board, Share appears right next to your Accepted Words and copies a Wordle-style summary to your clipboard — word lengths and chaining shown as colored blocks, a bare Bonus +N count (never the specific title names, so it can’t hint which side of the day’s reference solution you landed on), a Free Chain badge when the whole solve happened in that mode, and a word/letter count line at the bottom for convenience — no actual letters anywhere. Turn on “Include link when sharing” in Settings if you’d also like a link to a blank copy of the same puzzle included, so a friend without the game bookmarked can jump straight in and play it themselves; off by default, so a shared result stays a clean, spoiler-free summary.

Once solved, a second button, Reveal Solution, appears next to your Accepted Words — a good fit for the classic “share the score first, then reveal the full board once you both know your friend has played too” routine. It copies the same style of pasteable text as Share, but with your actual words spelled out instead of colored blocks, any earned title named outright with the exact canonical count and delta (e.g. “Efficiency Engineer (2 under the canonical 16)”), and — when known — the puzzle’s own reference solution words on a trailing line, since by the time you’re both revealing full solutions, there’s nothing left to protect. It’s a separate, always-distinct button rather than a Settings toggle on purpose: a toggle could get flipped on once and silently forgotten, unmasking a later Share meant for a different, more public audience. Share always stays masked, no matter what; Reveal Solution always shows everything, no matter what.

Why Letter Punk Exists

• Letter Punk leans into a Steampunk visual identity: steel and brass tones, riveted tanks, pipe-route overlays, pressure-valve motifs, and mechanical feedback cues that make the board feel like a working machine rather than a flat grid.
• The project started with the observation that traditional Letter Boxed has a limitation: excluding words with double letters rules out a rich portion of everyday vocabulary.
• Letter Punk keeps the core chaining puzzle structure, but treats double-letter words as first-class play so puzzle decisions come from word choice and path planning, not from an artificial vocabulary cutoff.
• The goal is to preserve the elegance of the original format while expanding expressive play and making room for a broader, more natural dictionary.
• There’s no word-count cap and no failure state: Delete Word/Delete Char can always back out of a dead end, so completing a well-formed board is generally achievable through persistence, not just cleverness — skill differentiates how well you solved it (see docs/canonical-solution-rating.md), not whether you can. That said, “well-formed” is doing real work in that sentence: a board built from letters with poor vowel coverage can still be a genuinely hard exception, in the extreme leaving only one or two legal words that can even start from certain letters.

Current Feature Set

• Steampunk-themed board and route visualization designed for high readability.
• Letter-first input model: tap the same letter twice in a row to double it. A decorative per-tile xN badge tracks how many times each letter has actually been used so far (accepted words plus the word in progress) — informational only, not a control.
• Physical-keyboard letter entry as a genuine alternative to tapping tiles, not just a convenience: typing a letter calls the exact same engine path a tile click does, so doubling and off-board rejection behave identically either way. Guarded by a board-size check (getBoardSize() === 12) since keyboard entry is only unambiguous when no letter repeats on the board — true of every board the app can currently produce or accept, but checked defensively rather than assumed, since a duplicate would make the same physical key map to two different tiles.
• Word-chain gameplay rules (next word starts with previous word’s final letter).
• Free Chain mode: a Settings toggle that drops the starting-letter requirement between words entirely — no forced first letter, no auto-filled seed, just find words from the board’s letters in any order. A “Free Chain” badge appears on the board header while it’s active. Persisted as your own default only when you flip the toggle yourself; opening a shared puzzle link whose recorded progress wasn’t chainable (proof it was played in Free Chain mode, since normal mode rejects a non-chaining word the moment it’s typed) turns the mode on for that puzzle only, without touching your saved preference.
• Stacked local packed dictionary validation so either the primary dictionary or the compatibility fallback can accept a word.
• A consolidated dictionary-provenance bar next to Accepted Words, showing which of all six dictionaries (Hunspell-based, 3of6game, Common, Common (simplistic), Proper nouns, Proper nouns (simplistic)) each accepted word actually landed in — always tracked, whether or not the bar itself is currently shown. The bar summarizes the whole solve — segments sized to how many words matched each dictionary — and opens a per-word breakdown on click, rather than badging every word pill individually; a word matching several tiers at once (say, both Common and its simplistic subset) shows every square it genuinely earned, not just the narrowest one. The separate live builder indicator next to the word you’re typing stays deliberately brief (general/word-game dictionary, API, or custom), leaving the full detail to the bar’s own breakdown.
• A live running letter-count stat in the board header — the total across accepted words plus the word in progress, i.e. what the character count would be if Enter were pressed right now. Deliberately board-scoped rather than tucked into either side panel, since it’s neither an “accepted words” stat nor a “current word” stat but the running total of both.
• Provenance bar visibility toggle in Settings, defaulting to off for a cleaner play surface.
• Dictionary override support through public/data/dictionary-overrides.txt.
• Dated daily puzzle catalog in public/data/daily-puzzles.json.
• Compact puzzle navigation controls: previous (<), next (>), return-to-home (Today's Puzzle), and New (opens the New Game dialog).
• Play-ahead and archive traversal across catalog entries.
• Local, per-puzzle progress memory: a daily puzzle’s found words and in-progress letters are saved to localStorage as you play, and restored automatically the next time you navigate to that date — at boot, or via the </>/”Today’s Puzzle” arrows. A dedicated Reset control clears the puzzle on screen; manually undoing back to a blank board has the identical effect, since the saved record is just whatever the board currently shows. Deliberately scoped to catalog puzzles only — a shared link’s own encoded state always takes priority and is never affected by this.
• “Yesterday/Previous” modal showing canonical solution words for the prior catalog puzzle.
• Play today’s NYT Letter Boxed / Letter (Punk) Boxed: at the top of the New Game dialog, a plain link sends you straight to the real puzzle on nytimes.com, for anyone who’d rather play the original; right beneath it, Letter (Punk) Boxed fetches that same day’s board and applies it here directly, closing the dialog itself — the only option in that dialog that doesn’t wait for a separate Apply Board click. Two independent third-party sources are tried in order, so one going down or getting bot-blocked doesn’t take the feature with it — see Letter-Boxed-Game-Logic-Copyright.md for why pulling in just the bare letter layout this way stays clear of NYT’s actual IP. When a source provides it, the real solution words come along too and are held exactly like a generated board’s own solution words are — quietly, usable for Reveal Solution/Share/word-count comparisons, never displayed until you explicitly ask.
• Random Puzzle and Simple Puzzle: two fully automated boards in New Game’s basic section — each picks a random seed word and pairs it with a companion the same way the daily catalog itself is generated, so the result comes with a genuine reference solution. Random Puzzle draws from the broader common-words tier (real words, not obscure ones, and not proper nouns like little-known place names); Simple Puzzle narrows further to a frequency-filtered subset of that same tier, biased toward the most everyday, recognizable words — see docs/development.md for how both tiers are built. Either solution is set quietly, exactly like Letter (Punk) Boxed’s: never displayed up front, usable only for Reveal Solution/Share/word-count comparisons once you’ve actually solved it. Both retry with a fresh random seed (rather than surfacing an error) if a given seed happens to have no valid companion; both fill the board fields for review, requiring an explicit Apply Board click to commit.
• Controlled Puzzle (its own disclosure in New Game, not nested under “Advanced” — it’s more configuration than Random/Simple Puzzle’s zero-config buttons, but not fiddly to operate the way the paste/generate/type-in tools below it are): pick any combination of all six dictionaries (Hunspell-based, 3of6game, Common, Common (simplistic), Proper nouns, Proper nouns (simplistic)) — Primary/Fallback as independent checkboxes, and Common/Proper nouns each grouped with its own simplistic subset as a mutually-exclusive radio choice, since checking both a tier and its own simplistic subset is never meaningfully different from the broader tier alone. The seed/companion can come from the union of whichever tiers you pick — for players who want more control than Random/Simple Puzzle’s own fixed tiers, including access to the proper-noun tiers those two deliberately avoid. Same quiet-solution and retry behavior as Random/Simple Puzzle, with a higher retry ceiling to accommodate sparser single-dictionary selections.
• Custom board tools (in New Game’s Advanced section): paste/parse board text, generate a board from two solution words, or Random Letters — a raw random 12-letter arrangement (the same generator used for the placeholder board before the daily catalog loads at boot) with no known reference solution at all, not even a hidden one, and no guarantee it’s short or even easy to solve. A single typed word is treated as a seed for Generate From Words; a companion is picked from the full set of valid dictionary candidates by starting at the 25th percentile of candidate length and walking outward until one actually produces a valid board layout (see docs/canonical-solution-rating.md), rather than a purely random or shortest-possible pick — the literal median runs noticeably longer than what a well-read person would typically reach for, since raw dictionaries are dominated by long, obscure derived words. Non-blocking warnings flag words the dictionary doesn’t recognize or a word pair that isn’t actually chainable in normal play; blocked words are always rejected outright. Solution words that aren’t real dictionary entries (proper nouns, another game’s vocabulary) are still guaranteed solvable once applied, via a per-board session override that never overrides a word already valid on its own.
• Hint: three progressive, opt-in tiers (word count/lengths, then start/end letters per word, then the full solution), each revealed only on explicit request and independently of the others — available whenever a reference solution is known (daily puzzles, an imported Letter Boxed board, Random/Simple Puzzle), hidden entirely otherwise. Resets whenever the board actually changes. Purely a private aid: never affects scoring, titles, or anything Share/Reveal Solution show.
• Canonical character-count rating: solving a board compares the player’s total character count against a reference solution and awards one of three titles — Efficiency Engineer (fewer characters), Dead Reckoner (an exact match), or Vocabulary Wrangler (more characters) — treating all three as equally legitimate ways to be good at the game, not one “correct” direction with silence everywhere else. Works for daily puzzles, custom boards, and shared links alike.
• Solo Plumber: a bonus title, independent of the three above, earned whenever no letter is ever used as both one word’s start and another’s end — recognized purely from how a solve actually happened, never something to preselect or aim for going in, the same way none of the titles above are chosen in advance.
• Union Plumber: Solo Plumber’s opposite number, earned in Free Chain mode when a player voluntarily chains every word into the next anyway — the discipline classic Letter Boxed always required, chosen rather than forced.
• Cataloger: a bonus title for Controlled Puzzle only, earned when every accepted word happens to be found in the puzzle’s own dictionary selection — not necessarily the canonical solution itself, any word that lands in the same theme counts (a word matching any one of several selected dictionaries qualifies, mirroring how the puzzle itself was generated as a union of them). All-or-nothing across the whole solve, and independent of the character-count title and Solo/Union Plumber, so a solve can earn any combination of all three at once.
• Shareable puzzle links: “Copy Blank Link” (a fresh, unplayed board) / “Copy Progress Link” (wherever the sharer’s own play currently stands — none, partial, or complete) in the New Game dialog encode the active board into a compact URL fragment. Words already played are stored as plain text since they’re immediately visible once the link opens; the canonical reference solution, when known, stays obfuscated — each letter stored as its board position, shifted by the word’s own length — so a partially-shared puzzle doesn’t spoil the unplayed remainder, and the reference solution survives so a recipient can freely retry and still be rated against it. Any progress in the link replays pipe-by-pipe as the page loads, in the order it was actually played, rather than appearing all at once — governed by the same “Reduce motion effects” setting as the rest of the pipe animation. The link also carries which of Import Today’s Letter Boxed / Random Puzzle / Simple Puzzle / Controlled Puzzle / Random Letters (if any) produced the board, so the recipient’s own puzzle status reads the same specific label the sender saw — for Controlled Puzzle, that includes which dictionaries were actually selected (e.g. “Controlled Puzzle, proper nouns”), not just the generic kind name.
• Share button: appears next to the Accepted Words list only once the board is fully solved (mirroring Wordle’s own “the share button is what greets you on completion” pattern, without a disruptive takeover modal — continued play after solving still works normally), and copies a masked, Wordle-style result summary to the clipboard — word lengths and chaining shown as colored/link emoji blocks, earned titles surfaced only as a bare Bonus +N count (never by name, so a friend’s masked share can’t be used to triangulate the puzzle’s canonical character count), a Free Chain badge when the whole solve happened in that mode, and a word/letter count line at the bottom for convenience — no actual letters, safe to paste into a text thread that won’t render monospace alignment. An optional, off-by-default Settings toggle appends a link to a blank copy of the same puzzle (whichever day is currently active, not necessarily today’s) — the point is getting a friend without the game bookmarked into their own attempt, not showing them yours, so it deliberately doesn’t carry your progress or a replay. For a dated daily puzzle, the link is a short, plain ?date=20260714-style address rather than a cryptic one — the board and reference solution are already public in the daily-puzzle catalog, so the link only needs to say which date. Opening one is exactly like navigating there normally, so the recipient can use the </> arrows to move on to another day (share yesterday’s puzzle and they can arrow straight into today’s once they’ve solved it). Today’s puzzle specifically drops even the date, since visiting the site fresh already loads it by default; only a custom or randomly generated board still needs the longer, cryptic link, since there’s no public date to reference for those.
• Reveal Solution button: appears next to the Accepted Words list only once the board is solved, and copies the same pasteable text format as Share but with actual words spelled out instead of blocks, earned titles named outright with the exact canonical count and delta rather than masked as a bonus count, and the puzzle’s own reference solution words when known — a deliberate, always-distinct second action (not a Settings toggle) so the primary Share button can never be made to silently produce unmasked text later by a forgotten setting.
• Route history rendering with recency fading so active routes stay emphasized while retaining additive context.
• Reduced-motion setting that preserves readability while limiting animation.
• Keyboard/focus-aware modal behavior with focus trapping and escape-to-close support.
• Accessibility helpers including skip link, ARIA live regions, and non-color letter-state cues.
• A small awareness card near the pipe artwork, on by default, linking to one real, current educational page or game — currently ICRC’s Rules of War, WHO’s page on fighting online misinformation, Poynter’s AI literacy hub, CCDH’s “Spot the Fake” AI-image literacy tool, and two free games that build resistance to manipulation, “Bad Vaxx” (vaccine misinformation) and “Harmony Square” (political disinformation) — not a donation ask, rotating as the list grows, dismissible, no sponsored content or borrowed logos, just a link to real work.

Learn More

• Dual Dictionary Validation for Word-Chain Games — how word validation and dictionary provenance actually work, and a reusable implementation write-up aimed at other game developers.
• Canonical Solution Rating — the design reasoning behind rating a solve against a “canonical” solution, and why that scoring deliberately avoids computing the objectively best possible answer.
• More Than One Way to Win — a short, general-audience essay on the design ideas behind this project’s approach to winning, written for anyone building anything, not just games. Dedicated to the public domain (CC0) — free to use, no permission needed.
• Roadmap & Future Concepts — potential board-configuration and rule variants, a wildcard-letter idea, and a full concept brief for a separate pictograph-based spin-off. Nothing here is a commitment.
• Letter-Boxed-Game-Logic-Copyright.md — concept/copyright notes.
• Acknowledgments — a note from the author on the AI collaboration behind this project.

Development

For local setup, the dictionary/puzzle build pipeline, testing, and deployment, see docs/development.md — most visitors just here to play won’t need it.

License

Letter Punk is licensed under the PolyForm Noncommercial License 1.0.0. In short: you’re free to use, study, modify, and share this code for any noncommercial purpose — personal use, research, education, hobby projects, nonprofits — no permission needed. Commercial use requires a separate agreement with the licensor. There’s no separate license for docs/design-philosophy.md, which is dedicated to the public domain (CC0) on its own terms, independent of the code.

This license covers Letter Punk’s own code and expression only — it doesn’t and can’t extend to the underlying word-chaining game mechanic itself, which was never anyone’s to own in the first place. See Letter-Boxed-Game-Logic-Copyright.md for the reasoning.

This site is open source. Improve this page.