Wordle clones are a popular first project, and a lot of them work fine until you test an edge case. The daily format hides many problems, because you only ever see one word per day.

Unlimited mode exposes them. I’ve been studying how Canuckle Unlimited approaches this: it’s a Canadian-themed word game where a new five-letter word loads the moment you finish a round, while streaks and stats carry across rounds. Features like that raise real engineering questions, and this post works through them.

By the end you’ll have:

1. A correct guess-evaluation function that handles repeated letters
2. A “shuffle bag” word picker that avoids repeats in endless play
3. A resilient stats and streak tracker
4. An accessible feedback system that doesn’t rely on colour alone

All code is framework-free, so you can drop it into any stack.

1. Scoring guesses correctly (the duplicate-letter trap)

The most common bug is scoring each letter independently. It breaks when a guess contains more copies of a letter than the answer does.

Consider the answer MAPLE and the guess LLAMA. The guess has two L’s and two A’s, but the answer has one of each. If you mark every matching letter yellow, you’ll show clues that don’t exist.

The fix is a two-pass algorithm:

• Pass 1: mark exact matches (correct), and count the unmatched answer letters.
• Pass 2: for each remaining guess letter, mark it “present” only if the counter still has that letter, then decrement.

const STATE = { CORRECT: "correct", PRESENT: "present", ABSENT: "absent" };

export function evaluateGuess(guess, answer) {
  const len = answer.length;
  const result = Array(len).fill(STATE.ABSENT);
  const remaining = {};

  // Pass 1: exact matches, and tally the answer letters left over
  for (let i = 0; i < len; i++) {
    if (guess[i] === answer[i]) {
      result[i] = STATE.CORRECT;
    } else {
      remaining[answer[i]] = (remaining[answer[i]] || 0) + 1;
    }
  }

  // Pass 2: misplaced letters, limited by what's left in the tally
  for (let i = 0; i < len; i++) {
    if (result[i] === STATE.CORRECT) continue;
    const ch = guess[i];
    if (remaining[ch] > 0) {
      result[i] = STATE.PRESENT;
      remaining[ch]--;
    }
  }
  return result;
}

Test it with known cases:

import assert from "node:assert/strict";

// Duplicate letters in the guess, single copies in the answer
assert.deepEqual(
  evaluateGuess("LLAMA", "MAPLE"),
  ["present", "absent", "present", "present", "absent"]
);

// Classic case: only one E can be yellow
assert.deepEqual(
  evaluateGuess("SPEED", "ABIDE"),
  ["absent", "absent", "present", "absent", "present"]
);

// Exact matches take priority over misplaced ones
assert.deepEqual(
  evaluateGuess("LOOSE", "MOOSE"),
  ["absent", "correct", "correct", "correct", "correct"]
);

Write these tests before you build any UI. Scoring logic is the one part of the game that must never be wrong.

2. A shuffle bag for unlimited mode

In unlimited mode, the naive approach is words[Math.floor(Math.random() * words.length)]. With a modest word list, you’ll see the same word twice in a row far sooner than players expect, and it feels like a bug.

A shuffle bag fixes this: shuffle the whole list once, deal words from it until it’s empty, then reshuffle. Every word appears once per cycle.

function shuffle(arr) {
  // Fisher–Yates
  for (let i = arr.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr;
}

export function createWordBag(words) {
  let bag = [];
  let last = null;

  return function nextWord() {
    if (bag.length === 0) {
      bag = shuffle([...words]);
      // Avoid a repeat across the reshuffle boundary
      if (bag.length > 1 && bag[bag.length - 1] === last) {
        [bag[0], bag[bag.length - 1]] = [bag[bag.length - 1], bag[0]];
      }
    }
    last = bag.pop();
    return last;
  };
}

Usage :

const nextWord = createWordBag(["MOOSE", "TOQUE", "LOONIE", "HOSER"].filter(w => w.length === 5));
let answer = nextWord();

Two details matter here. The array is copied before shuffling so your source list isn’t mutated, and the boundary check prevents the same word appearing at the end of one cycle and the start of the next.

If your game has a themed list (Canadian geography, slang, wildlife, food), this approach also guarantees players see the full range of categories before any repeats.

3. Tracking streaks and stats safely

Unlimited mode needs a reason to keep playing, and streaks provide it. The state you need is small:

const DEFAULT_STATS = {
  played: 0,
  wins: 0,
  streak: 0,
  maxStreak: 0,
  distribution: [0, 0, 0, 0, 0, 0], // wins by number of guesses
};

const KEY = "wordgame:stats:v1";

export function loadStats() {
  try {
    const raw = localStorage.getItem(KEY);
    return raw ? { ...DEFAULT_STATS, ...JSON.parse(raw) } : { ...DEFAULT_STATS };
  } catch {
    return { ...DEFAULT_STATS }; // storage blocked or data corrupted
  }
}

export function recordResult(stats, won, guessCount) {
  const next = { ...stats, distribution: [...stats.distribution] };
  next.played += 1;

  if (won) {
    next.wins += 1;
    next.streak += 1;
    next.maxStreak = Math.max(next.maxStreak, next.streak);
    next.distribution[guessCount - 1] += 1;
  } else {
    next.streak = 0;
  }

  try {
    localStorage.setItem(KEY, JSON.stringify(next));
  } catch {
    /* private mode or quota exceeded: keep playing without persistence */
  }
  return next;
}

Design notes worth copying:

• Version your storage key (:v1). When you change the stats shape later, you can migrate instead of crashing on old data.
• Wrap storage in try/catch. Private browsing and blocked storage throw errors, and a game that crashes on load because of that is a bad first impression.
• Merge with defaults when loading, so new fields don’t break existing players.
• Never mutate state in place. Returning a new object makes UI updates predictable.

4. Feedback that doesn’t depend on colour alone

Tile colours are the core of the game, and also an accessibility problem. Red/green or red/yellow palettes are hard for many colourblind players, and colour alone fails screen reader users entirely.

Do two things.

First, drive colours from CSS variables so a high-contrast mode is a one-line toggle:

:root {
  --tile-correct: #c8102e;
  --tile-present: #e0a800;
  --tile-absent:  #5a5a5a;
}

:root[data-contrast="high"] {
  --tile-correct: #f5792a; /* orange */
  --tile-present: #1f6feb; /* blue */
  --tile-absent:  #3a3a3a;
}

.tile[data-state="correct"] { background: var(--tile-correct); }
.tile[data-state="present"] { background: var(--tile-present); }
.tile[data-state="absent"]  { background: var(--tile-absent); }

Orange and blue remain distinguishable for most colour-vision types, which is why many word games use that pair for high-contrast mode.

Second, expose state as text. Every tile needs a label, and results should be announced:

function renderTile(el, letter, state, position) {
  el.textContent = letter;
  el.dataset.state = state;
  el.setAttribute(
    "aria-label",
    `${letter}, position ${position + 1}, ${state === "present" ? "in word, wrong spot" : state === "correct" ? "correct" : "not in word"}`
  );
}

<div id="status" role="status" aria-live="polite" class="sr-only"></div>

Update #status after each guess with something like “Guess 3 of 6: two letters correct, one in the wrong spot.” Players using assistive tech get the same information sighted players get from colour.

You can also add a non-colour cue to the tiles themselves, such as a small icon or pattern for “present” versus “correct,” which helps in bright sunlight and on low-quality screens, too.

5. Putting it together

A minimal game loop that combines all four pieces:

const nextWord = createWordBag(WORDS);
let stats = loadStats();
let answer = nextWord();
let guesses = [];

function submitGuess(guess) {
  if (!VALID_WORDS.has(guess)) return announce("Not in word list");

  const result = evaluateGuess(guess, answer);
  guesses.push({ guess, result });
  renderRow(guesses.length - 1, guess, result);

  const won = result.every(s => s === "correct");
  const lost = !won && guesses.length === 6;

  if (won || lost) {
    stats = recordResult(stats, won, guesses.length);
    showEndScreen({ won, answer, stats });
  }
}

function playAgain() {
  answer = nextWord();
  guesses = [];
  resetBoard();
}

Note that playAgain() doesn’t touch stats. That’s what makes streaks continue across rounds in unlimited mode.

Common mistakes to avoid

That last row is worth highlighting. Your answer list can be small and carefully curated, such as a themed list of Canadian words, while your accepted guess list should be much larger, so players aren’t punished for trying a legitimate word.

Why a themed word list is worth the effort

Engineering aside, the biggest differentiator for a word game is content. A generic dictionary makes every clone interchangeable. A curated, themed list changes how people play, because common pattern-matching shortcuts stop working and players have to reason about the theme. If you pair that with a short fact after each round, even a lost game leaves the player with something.

Wrapping up

None of these pieces is complicated, but each one is easy to get wrong, and together they separate a polished game from a tutorial project:

1. Score with two passes, and test duplicates first.
2. Use a shuffle bag for unlimited play.
3. Version and guard your persisted stats.
4. Make feedback readable without colour.

If you want to see these ideas in a live product, play a few back-to-back rounds and watch what happens between puzzles: how fast the next word loads, how the streak carries over, and what the post-round content adds. Then try building your own version with a theme you care about.

What edge cases have you hit building word games? Drop them in the comments and I’ll cover the best ones in a follow-up.

I built the grid version of Canuckle, Canuckle Waffle, as a separate mode next to the single-word game. The word-guessing logic didn’t carry over at all. This post covers the parts that had to be written from scratch: the data model, the generator, the scramble, and the scoring. I covered per-mode storage in an earlier post, so I’m skipping that here.

All code below is plain JavaScript with no dependencies.

The grid has 21 cells, not 25

Three words run across (rows 0, 2, 4) and three run down (columns 0, 2, 4). The four cells where an odd row meets an odd column don’t exist. Six five-letter words would be 30 letters, but the 9 crossings are shared, which leaves 30 − 9 = 21 unique tiles.

I store the board as a flat array of 21 letters and precompute which cell indices belong to each word:

const SIZE = 5;
const CELL = {};
let count = 0;

for (let r = 0; r < SIZE; r++) {
  for (let c = 0; c < SIZE; c++) {
    if (!(r % 2 === 1 && c % 2 === 1)) CELL[r + ',' + c] = count++;
  }
}
// count === 21

const WORDS = [
  ...[0, 2, 4].map(r => [0, 1, 2, 3, 4].map(c => CELL[r + ',' + c])), // across
  ...[0, 2, 4].map(c => [0, 1, 2, 3, 4].map(r => CELL[r + ',' + c])), // down
];

WORDS[0..2] are the across words and WORDS[3..5] are the down words. Every other function in this post works from that table, so rendering, swapping, scoring and win detection never deal with rows and columns directly.

Six words that agree at nine crossings

Choosing six random words is easy. Choosing six whose letters match at every crossing is the hard part.

Across word i (row 2i) crosses down word j (column 2j) at one cell. That gives the constraint across[i][2j] === down[j][2i], nine times over. The useful observation is that once you fix the three across words, each down word is almost fully determined. Down word j must have these letters at positions 0, 2 and 4:

down[j][0] = across[0][2j]
down[j][2] = across[1][2j]
down[j][4] = across[2][2j]

So I index the word pool by the letters at positions 0, 2 and 4, and each down word becomes a lookup:

function buildIndex(words) {
  const byKey = new Map();
  for (const w of words) {
    const key = w[0] + w[2] + w[4];
    if (!byKey.has(key)) byKey.set(key, []);
    byKey.get(key).push(w);
  }
  return byKey;
}

const pick = (arr, rand) => arr[Math.floor(rand() * arr.length)];

function generateSolution(pool, themed, rand, attempts = 20000) {
  const byKey = buildIndex(pool);
  let best = null;
  let bestScore = -1;

  for (let n = 0; n < attempts; n++) {
    const across = [pick(pool, rand), pick(pool, rand), pick(pool, rand)];

    const downs = [0, 1, 2].map(j => {
      const key = across[0][2 * j] + across[1][2 * j] + across[2][2 * j];
      const options = byKey.get(key);
      return options ? pick(options, rand) : null;
    });

    if (downs.includes(null)) continue;
    const all = [...across, ...downs];
    if (new Set(all).size !== 6) continue; // no repeated words

    const score = all.filter(w => themed.has(w)).length;
    if (score > bestScore) {
      best = { across, downs };
      bestScore = score;
      if (score === 6) break;
    }
  }
  return best && { ...best, score: bestScore };
}

The crossings can never disagree, because the lookup key is built from exactly the cells the down word shares with the across words. That removes the need to validate nine constraints after the fact.

Why a themed word list needs a filler pool

The search above works well with a large general dictionary. A themed list is a different situation. A Canadian word bank (provinces, slang, wildlife, food) is small, and the chance that a random triple of themed words produces three matching keys in that same small list is low. In practice, a purely themed pool rarely produces a full grid.

The pool / themed split in the function above is how I handle it. The pool contains themed words plus plain English filler, and themed is the subset I actually want. The search keeps the candidate with the most themed words and stops early if it finds a grid made entirely of them. On most days that means five themed words and one filler word, which is why the puzzle page tells players that one word may look less Canadian than the rest.

If you’re building a themed variant of any word game, expect this and plan for it. Hiding it tends to confuse players more than explaining it does.

Scrambling backwards so a solution always exists

The obvious scramble is to shuffle all 21 tiles. The trouble is that you then know nothing about how many swaps the puzzle needs, so you can’t set a fair move limit.

I start from the solved grid and apply a fixed number of random swaps. The puzzle is solvable in at most that many swaps by construction, because you can simply reverse them.

function acceptable(grid, solution) {
  const misplaced = grid.filter((ch, i) => ch !== solution[i]).length;
  const solvedWords = WORDS.filter(w =>
    w.every(c => grid[c] === solution[c])
  ).length;
  return misplaced >= 12 && solvedWords === 0;
}

function scramble(solution, rand, swaps = 10) {
  let grid;
  do {
    grid = solution.slice();
    for (let i = 0; i < swaps; i++) {
      const a = Math.floor(rand() * 21);
      const b = Math.floor(rand() * 21);
      if (a === b || grid[a] === grid[b]) { i--; continue; }
      [grid[a], grid[b]] = [grid[b], grid[a]];
    }
  } while (!acceptable(grid, solution));
  return grid;
}

Two details matter here. Swapping two identical letters is a wasted move that changes nothing visible, so the loop retries instead of counting it. And random swaps can undo each other, so the result sometimes comes out too easy. The acceptable check rejects any scramble that leaves a word already solved or fewer than 12 tiles out of place.

A 10-swap scramble gives an honest “solvable in 10” guarantee, and the move limit can be set a few moves above that.

One thing I deliberately don’t compute is the true minimum number of swaps. For a permutation of distinct letters it’s the number of misplaced tiles minus the number of cycles among them. With repeated letters, you’d have to pick the assignment of duplicates that maximises cycles, which is a harder problem than it looks. The construction-based guarantee avoids that entirely, at the cost of the true minimum sometimes being lower than 10.

Same puzzle for everyone, no backend

For a daily puzzle I wanted every player to get the same grid without a server deciding it. A seeded random number generator does that. The seed is the day number, and the generator above produces the same output for the same seed.

function mulberry32(seed) {
  return function () {
    seed |= 0; seed = (seed + 0x6D2B79F5) | 0;
    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

const dayNumber = (d = new Date()) =>
  Math.floor(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()) / 86400000);

const rand = mulberry32(dayNumber());
const solution = toGrid(generateSolution(pool, themed, rand));
const board = scramble(solution, rand);

I build the day number from the local date parts, not from Date.now(), so the puzzle changes at the player’s local midnight. The tradeoff is that two players in different time zones can see different puzzles on the same UTC day.

The other tradeoff is that shipping the generator to the browser means anyone reading the source can work out tomorrow’s answer. For a casual daily game, I accepted that. If it matters for yours, generate the puzzles at build time and ship a static schedule instead.

toGrid just writes each word’s letters into the cells from the WORDS table:

function toGrid({ across, downs }) {
  const grid = new Array(21);
  across.forEach((w, i) => WORDS[i].forEach((cell, k) => (grid[cell] = w[k])));
  downs.forEach((w, j) => WORDS[3 + j].forEach((cell, k) => (grid[cell] = w[k])));
  return grid;
}

Feedback when one tile belongs to two words

Single-word games colour each letter by comparing it to the answer. A waffle tile at a crossing belongs to two words, and repeated letters make the naive comparison wrong, so I score per word with the usual two-pass approach and then merge.

const RANK = { absent: 0, present: 1, correct: 2 };

function scoreWord(cells, grid, solution) {
  const out = cells.map(() => 'absent');
  const remaining = {};

  cells.forEach((cell, i) => {
    if (grid[cell] === solution[cell]) out[i] = 'correct';
    else remaining[solution[cell]] = (remaining[solution[cell]] || 0) + 1;
  });

  cells.forEach((cell, i) => {
    if (out[i] === 'correct') return;
    const ch = grid[cell];
    if (remaining[ch] > 0) { out[i] = 'present'; remaining[ch]--; }
  });
  return out;
}

function scoreGrid(grid, solution) {
  const status = new Array(grid.length).fill('absent');
  for (const word of WORDS) {
    const s = scoreWord(word, grid, solution);
    word.forEach((cell, i) => {
      if (RANK[s[i]] > RANK[status[cell]]) status[cell] = s[i];
    });
  }
  return status;
}

The first pass marks exact matches and counts the solution letters that are still unaccounted for in that word. The second pass hands out “present” only while there are unaccounted letters of that type left. A tile at a crossing takes the better of its two results.

Detecting a win without punishing alternate solutions

My first win check compared the grid to the stored solution cell by cell. That’s correct for the intended answer but strict about everything else, and with repeated letters there can be other arrangements where all six words are valid.

Checking the words instead handles that:

const isSolved = (grid, validWords) =>
  WORDS.every(cells => validWords.has(cells.map(c => grid[c]).join('')));

If all six words read as valid entries in the acceptable-word set, the player is done. The intended solution always passes, and so does any other arrangement that happens to work.

What I still haven’t settled is the exact minimum-swap count when letters repeat. If you’ve solved that cleanly for a 21-tile board, I’d like to see the approach.

When I took over the architecture and development for Canuckle (a Canadian-themed word puzzle ecosystem originally conceptualized by Mark Rogers in 2022), the immediate challenge was clear: How do you evolve a single-format script into a resilient, performant, and search-optimized multi-mode web application?

Here is a breakdown of the technical hurdles, architectural decisions, and schema workflows behind turning a lightweight word game into a scalable platform.

1. Game State Isolation Across Multiple Modes

One major flaw with basic word game implementations is state leakage. When you expand a single game into multiple modes (e.g., standard 5-letter, 6-letter expansion, unlimited practice, and grid variants), sharing a single storage namespace creates state collisions.

To prevent daily puzzle progress from overwriting unlimited sessions, we decoupled the state persistence layer using strict key-scoping:

// Utility: Namespaced state management for game modes
const createGameStore = (modeKey) => {
  const STORAGE_PREFIX = `canuckle_state_${modeKey}`;

  return {
    get: () => {
      try {
        const raw = localStorage.getItem(STORAGE_PREFIX);
        return raw ? JSON.parse(raw) : null;
      } catch (e) {
        console.error("Failed to parse local game state", e);
        return null;
      }
    },
    save: (state) => {
      try {
        localStorage.setItem(STORAGE_PREFIX, JSON.stringify({
          ...state,
          lastUpdated: new Date().toISOString()
        }));
      } catch (e) {
        console.error("Quota exceeded or storage disabled", e);
      }
    }
  };
};

export const dailyStore = createGameStore("daily_5");
export const unlimitedStore = createGameStore("unlimited");

This decoupled pattern ensures that mode toggling operates predictably without requiring complex global state reducers.

1. URL Architecture: Dedicated Routing vs. Dynamic Toggles A common anti-pattern in casual game clones is burying different play modes behind modal toggles or UI tabs on the root route. While it simplifies state management, it creates severe discoverability and caching penalties:

Intent Isolation: Users searching for a daily puzzle vs. an "unlimited practice" session have fundamentally different query intents.

Granular Caching: Dynamic single-page toggles make static caching and edge delivery harder to configure per route.

We decoupled each format into dedicated static endpoints (/unlimited, /plus-6-letter, /waffle-grid). Each route serves pre-rendered HTML shells with dedicated OpenGraph tags and isolated canonical references.

1. Structured Data: JSON-LD for Rich Web Entities Web utility apps frequently struggle with search visibility because search engines cannot execute complex gameplay loops during initial crawling. To communicate page intent programmatically, we integrated structured JSON-LD schemas covering WebApplication, FAQPage, and HowTo definitions.

Here is the modular schema structure implemented on the primary gameplay route:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebApplication",
      "@id": "https://canucklegame.ca/#webapp",
      "name": "Canuckle",
      "applicationCategory": "GameApplication",
      "operatingSystem": "All",
      "browserRequirements": "Requires JavaScript. Requires HTML5.",
      "offers": {
        "@type": "Offer",
        "price": "0",
        "priceCurrency": "USD"
      }
    },
    {
      "@type": "FAQPage",
      "@id": "https://canucklegame.ca/#faq",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "How does the daily puzzle reset work?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "The daily puzzle refreshes automatically at midnight local time based on the user's localized timezone offset."
          }
        }
      ]
    }
  ]
}
</script>

Implementing validated schemas eliminates crawler ambiguity and provides clear entity associations directly within search indices.

4. Handling Regional Character Sets and Dictionaries

Building a regional-themed game requires strict data validation. In our case, supporting Canadian English meant curating custom dictionary arrays where spelling variants (e.g., colour vs. color, favour vs. favor) are handled gracefully without breaking letter-count validation loops.

Instead of bundling massive dictionary JSON files into the client entry bundle, we split word validation into:

1. Target Word List: Loaded synchronously with the bundle for fast client-side win/loss evaluation.

2. Acceptable Guesses List: Lazy-loaded asynchronously upon first user input or checked against an optimized in-memory Set lookup.

3. // O(1) word validation lookup using Set
   const validWordSet = new Set(acceptableWordsArray);
   
   export const validateGuess = (guess) => {
     if (guess.length !== 5) return false;
     return validWordSet.has(guess.toLowerCase());
   };
   

Key Takeaway

Building web apps in popular genres isn't just about recreating the basic loop—it comes down to the operational discipline around the codebase:

• Modular state persistence.

• High-intent URL routing.

• Comprehensive JSON-LD structured data.

• Performance-conscious bundle loading.

When you bridge the gap between simple script forks and production-ready web engineering, even familiar formats can be scaled into reliable, high-performance platforms.

Project Reference: Canuckle Game