From 33d5d55c33fcec743b8574479e1d4f72cd54a9fe Mon Sep 17 00:00:00 2001
From: jay <thejayman77@gmail.com>
Date: Wed, 10 Jun 2026 20:23:13 -0400
Subject: [PATCH] Word Search: extract pure selection/match logic + pin with
 vitest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per Codex's Phase 2 audit notes. Moved the drag-snap (lineFrom) and find-match
(matchWord) logic into $lib/wordsearch.js and added vitest coverage:
- lineFrom always yields a straight, in-bounds path — a non-straight drag snaps,
  never returns bent; single cell and edge-clamping covered.
- matchWord matches forward + reversed selections, is a harmless no-op on an
  already-found word (so completion/best-time can't double-record), and returns
  null for non-words / too-short selections.

Restore behaviour audited: finish() (which records best-time) only runs when the
final word is found mid-play; on refresh, restore() repopulates found cells +
time and the derived status flips to done WITHOUT calling finish(), so best-time
never re-records. First JS test runner for the frontend (npm test → vitest run).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/package-lock.json                    | 339 +++++++++++++++++-
 frontend/package.json                         |   6 +-
 .../src/lib/components/WordSearchGame.svelte  |  28 +-
 frontend/src/lib/wordsearch.js                |  44 +++
 frontend/src/lib/wordsearch.test.js           |  54 +++
 5 files changed, 443 insertions(+), 28 deletions(-)
 create mode 100644 frontend/src/lib/wordsearch.js
 create mode 100644 frontend/src/lib/wordsearch.test.js

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index aa8ab6c..38b974f 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,7 +13,8 @@
         "@sveltejs/vite-plugin-svelte": "^5.0.0",
         "an-array-of-english-words": "^2.0.0",
         "svelte": "^5.1.0",
-        "vite": "^6.0.0"
+        "vite": "^6.0.0",
+        "vitest": "^4.1.8"
       }
     },
     "node_modules/@esbuild/aix-ppc64": {
@@ -911,12 +912,28 @@
         "vite": "^6.0.0"
       }
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
     "node_modules/@types/cookie": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/@types/cookie/-/cookie-0.6.0.tgz",
       "integrity": "sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==",
       "dev": true
     },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true
+    },
     "node_modules/@types/estree": {
       "version": "1.0.9",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
@@ -929,6 +946,112 @@
       "integrity": "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==",
       "dev": true
     },
+    "node_modules/@vitest/expect": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.8.tgz",
+      "integrity": "sha512-h3nDO677RDLEGlBxyQ5CW8RlMThSKSRLUePLOx09gNIWRL40edgA1GCZSZgf1W55MFAG6/Sw14KeaAnqv0NKdQ==",
+      "dev": true,
+      "dependencies": {
+        "@standard-schema/spec": "^1.1.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.1.8",
+        "@vitest/utils": "4.1.8",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.8.tgz",
+      "integrity": "sha512-LEiN/xe4OSIbKe9HQIp5OC24agGD9J5CnmMgsLohVVoOPWL9a2sBoR6VBx43jQZb7Kr1l4RCuyCJzcAa0+dojw==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/spy": "4.1.8",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.8.tgz",
+      "integrity": "sha512-9GasEBxpZ1VYIpqHf/0+YGg121uSNwCKOJqIrTwWP/TB7DmFCiaBpNl3aPZzoLWfWkuqhbH8vJIVobZkvdo2cA==",
+      "dev": true,
+      "dependencies": {
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.8.tgz",
+      "integrity": "sha512-EmVxeBAfMJvycdjd6Hm+RbFBbA9fKvo0Kx37hNpBYoYeavH3RNsBXWDooR1mgD52dCrxIIuP7UotpfiwOikvcg==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/utils": "4.1.8",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.8.tgz",
+      "integrity": "sha512-acfZboRmAIf05DEKcBQy33VXojFJjtUdLyo7oOmV9kebb2xdU01UknNiPuPZoJZQyO7DF0gZdTGTpeAzET9QPQ==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.8",
+        "@vitest/utils": "4.1.8",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.8.tgz",
+      "integrity": "sha512-6EevtBp6OZOPF7bmz36HrGMeP3txgVSrgebWxHOafDXGkhIzfXK14f8KF6MuFfgXXUeHxmpD3BQxkV00/3s5mA==",
+      "dev": true,
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.8.tgz",
+      "integrity": "sha512-uOJamYALNhfJ6iolExyQM40yIQwDqYnkKtQ5VCiSe17E33H0aQ/u+1GlRuz4LZBk6Mm3sg90G9hEbmEt37C1Zg==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.8",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/acorn": {
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
@@ -960,6 +1083,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/axobject-query": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
@@ -969,6 +1101,15 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/clsx": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
@@ -978,6 +1119,12 @@
         "node": ">=6"
       }
     },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true
+    },
     "node_modules/cookie": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.6.0.tgz",
@@ -1019,6 +1166,12 @@
       "integrity": "sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==",
       "dev": true
     },
+    "node_modules/es-module-lexer": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.1.0.tgz",
+      "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==",
+      "dev": true
+    },
     "node_modules/esbuild": {
       "version": "0.25.12",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.12.tgz",
@@ -1083,6 +1236,24 @@
         }
       }
     },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -1180,6 +1351,25 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/obug": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.2.tgz",
+      "integrity": "sha512-AWGB9WFcRXOQs48Z/udjI5ZcZMHXwX8XPByNpOydgcGsDLIzjGizhoMWJyKAWze7AVW/2W1i+/gPX4YtKe5cyg==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -1282,6 +1472,12 @@
       "integrity": "sha512-kjnC1DXBHcxaOaOXBHBeRtltsDG2nUiUni+jP92M9gYdW12rsmx92UsfpH7o5tDRs7I1ZZPSQJQGv3UaRfCiuw==",
       "dev": true
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true
+    },
     "node_modules/sirv": {
       "version": "3.0.2",
       "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
@@ -1305,6 +1501,18 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true
+    },
+    "node_modules/std-env": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.1.0.tgz",
+      "integrity": "sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==",
+      "dev": true
+    },
     "node_modules/svelte": {
       "version": "5.56.0",
       "resolved": "https://registry.npmjs.org/svelte/-/svelte-5.56.0.tgz",
@@ -1332,6 +1540,21 @@
         "node": ">=18"
       }
     },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true
+    },
+    "node_modules/tinyexec": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.4.tgz",
+      "integrity": "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg==",
+      "dev": true,
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.17",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
@@ -1348,6 +1571,15 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tinyrainbow": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.0.tgz",
+      "integrity": "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==",
+      "dev": true,
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
     "node_modules/totalist": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
@@ -1445,6 +1677,111 @@
         }
       }
     },
+    "node_modules/vitest": {
+      "version": "4.1.8",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.8.tgz",
+      "integrity": "sha512-flY6ScbCIt9HThs+C5HS7jvGOB560DJtk/Z15IQROTA6zEy49Nh8T/dofWTQL+n3vswqn87sbJNiuqw1SDp5Ig==",
+      "dev": true,
+      "dependencies": {
+        "@vitest/expect": "4.1.8",
+        "@vitest/mocker": "4.1.8",
+        "@vitest/pretty-format": "4.1.8",
+        "@vitest/runner": "4.1.8",
+        "@vitest/snapshot": "4.1.8",
+        "@vitest/spy": "4.1.8",
+        "@vitest/utils": "4.1.8",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.8",
+        "@vitest/browser-preview": "4.1.8",
+        "@vitest/browser-webdriverio": "4.1.8",
+        "@vitest/coverage-istanbul": "4.1.8",
+        "@vitest/coverage-v8": "4.1.8",
+        "@vitest/ui": "4.1.8",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/zimmerframe": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
diff --git a/frontend/package.json b/frontend/package.json
index c7a213d..8fe8bf3 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,7 +6,8 @@
   "scripts": {
     "dev": "vite dev --host",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run"
   },
   "devDependencies": {
     "@sveltejs/adapter-static": "^3.0.6",
@@ -14,6 +15,7 @@
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
     "an-array-of-english-words": "^2.0.0",
     "svelte": "^5.1.0",
-    "vite": "^6.0.0"
+    "vite": "^6.0.0",
+    "vitest": "^4.1.8"
   }
 }
diff --git a/frontend/src/lib/components/WordSearchGame.svelte b/frontend/src/lib/components/WordSearchGame.svelte
index 762f626..cf92398 100644
--- a/frontend/src/lib/components/WordSearchGame.svelte
+++ b/frontend/src/lib/components/WordSearchGame.svelte
@@ -1,5 +1,6 @@
 <script>
   import { getJSON } from '$lib/api.js';
+  import { lineFrom, matchWord } from '$lib/wordsearch.js';
 
   let { onstatus } = $props();
 
@@ -69,25 +70,6 @@
     return [r, c];
   }
 
-  // Snap a drag to the nearest of the 8 straight directions.
-  function lineFrom(start, end) {
-    const [r0, c0] = start, [r1, c1] = end;
-    let dr = r1 - r0, dc = c1 - c0;
-    if (dr === 0 && dc === 0) return [start];
-    const adr = Math.abs(dr), adc = Math.abs(dc);
-    if (adr > adc * 2) dc = 0;
-    else if (adc > adr * 2) dr = 0;
-    else { const m = Math.max(adr, adc); dr = Math.sign(dr) * m; dc = Math.sign(dc) * m; }
-    const steps = Math.max(Math.abs(dr), Math.abs(dc));
-    const sr = Math.sign(dr), sc = Math.sign(dc), cells = [];
-    for (let i = 0; i <= steps; i++) {
-      const r = r0 + sr * i, c = c0 + sc * i;
-      if (r < 0 || r >= size || c < 0 || c >= size) break;
-      cells.push([r, c]);
-    }
-    return cells.length ? cells : [start];
-  }
-
   function down(e) {
     if (status === 'done') return;
     selecting = true;
@@ -98,7 +80,7 @@
   }
   function move(e) {
     if (!selecting) return;
-    sel = lineFrom(sel[0], cellAt(e));
+    sel = lineFrom(sel[0], cellAt(e), size);
   }
   function up() {
     if (!selecting) return;
@@ -108,11 +90,7 @@
   }
 
   function evaluate(cells) {
-    if (cells.length < 2) return;
-    const word = cells.map(([r, c]) => grid[r][c]).join('');
-    const rev = [...word].reverse().join('');
-    const hit = words.includes(word) && !found.includes(word) ? word
-              : words.includes(rev) && !found.includes(rev) ? rev : null;
+    const hit = matchWord(cells, grid, words, found);
     if (!hit) return;
     found = [...found, hit];
     const fc = new Set(foundCells);
diff --git a/frontend/src/lib/wordsearch.js b/frontend/src/lib/wordsearch.js
new file mode 100644
index 0000000..9a1e6ae
--- /dev/null
+++ b/frontend/src/lib/wordsearch.js
@@ -0,0 +1,44 @@
+// Pure word-search helpers — no DOM, so they're unit-testable. Used by
+// WordSearchGame.svelte for drag selection and find-matching.
+
+/**
+ * Snap a drag from `start` to `end` onto the nearest of the 8 straight
+ * directions and return the colinear cells, clamped to the grid. Guarantees a
+ * straight path — a non-straight drag is snapped, never returned bent.
+ * @param {[number,number]} start
+ * @param {[number,number]} end
+ * @param {number} size
+ * @returns {[number,number][]}
+ */
+export function lineFrom(start, end, size) {
+  const [r0, c0] = start, [r1, c1] = end;
+  let dr = r1 - r0, dc = c1 - c0;
+  if (dr === 0 && dc === 0) return [start];
+  const adr = Math.abs(dr), adc = Math.abs(dc);
+  if (adr > adc * 2) dc = 0;            // mostly vertical → snap orthogonal
+  else if (adc > adr * 2) dr = 0;       // mostly horizontal → snap orthogonal
+  else { const m = Math.max(adr, adc); dr = Math.sign(dr) * m; dc = Math.sign(dc) * m; } // diagonal
+  const steps = Math.max(Math.abs(dr), Math.abs(dc));
+  const sr = Math.sign(dr), sc = Math.sign(dc), cells = [];
+  for (let i = 0; i <= steps; i++) {
+    const r = r0 + sr * i, c = c0 + sc * i;
+    if (r < 0 || r >= size || c < 0 || c >= size) break;
+    cells.push([r, c]);
+  }
+  return cells.length ? cells : [start];
+}
+
+/**
+ * Read the letters along `cells` off `grid` (array of row strings) and return
+ * the matching not-yet-found word (forward or reversed), or null. Re-selecting
+ * an already-found word, or a non-word, returns null — harmless.
+ * @returns {string|null}
+ */
+export function matchWord(cells, grid, words, found) {
+  if (!cells || cells.length < 2) return null;
+  const word = cells.map(([r, c]) => grid[r][c]).join('');
+  const rev = [...word].reverse().join('');
+  if (words.includes(word) && !found.includes(word)) return word;
+  if (words.includes(rev) && !found.includes(rev)) return rev;
+  return null;
+}
diff --git a/frontend/src/lib/wordsearch.test.js b/frontend/src/lib/wordsearch.test.js
new file mode 100644
index 0000000..c4229d0
--- /dev/null
+++ b/frontend/src/lib/wordsearch.test.js
@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { lineFrom, matchWord } from './wordsearch.js';
+
+const colinear = (cells) => {
+  if (cells.length < 2) return true;
+  const [r0, c0] = cells[0], [r1, c1] = cells[1];
+  const sr = Math.sign(r1 - r0), sc = Math.sign(c1 - c0);
+  return cells.every(([r, c], i) => r === r0 + sr * i && c === c0 + sc * i);
+};
+
+describe('lineFrom', () => {
+  it('builds straight horizontal / vertical / diagonal runs', () => {
+    expect(lineFrom([2, 1], [2, 4], 10)).toEqual([[2, 1], [2, 2], [2, 3], [2, 4]]);
+    expect(lineFrom([1, 3], [4, 3], 10)).toEqual([[1, 3], [2, 3], [3, 3], [4, 3]]);
+    expect(lineFrom([0, 0], [3, 3], 10)).toEqual([[0, 0], [1, 1], [2, 2], [3, 3]]);
+  });
+
+  it('snaps a non-straight drag onto a straight line (never bent)', () => {
+    // knight-ish move (dr=1, dc=3) → should snap, and stay colinear
+    const cells = lineFrom([5, 2], [6, 8], 10);
+    expect(colinear(cells)).toBe(true);
+    // a near-diagonal still resolves to a straight path
+    expect(colinear(lineFrom([0, 0], [4, 5], 10))).toBe(true);
+  });
+
+  it('clamps to the grid and handles a single cell', () => {
+    expect(lineFrom([0, 0], [0, 0], 10)).toEqual([[0, 0]]);
+    const cells = lineFrom([8, 8], [20, 8], 10);   // runs off the bottom edge
+    expect(cells.every(([r, c]) => r >= 0 && r < 10 && c >= 0 && c < 10)).toBe(true);
+  });
+});
+
+describe('matchWord', () => {
+  const grid = ['CALM', 'XXXX', 'XXXX', 'XXXX']; // CALM across row 0
+  const words = ['CALM', 'PEACE'];
+
+  it('matches a forward word', () => {
+    expect(matchWord([[0, 0], [0, 1], [0, 2], [0, 3]], grid, words, [])).toBe('CALM');
+  });
+
+  it('matches a reversed selection to the listed word', () => {
+    expect(matchWord([[0, 3], [0, 2], [0, 1], [0, 0]], grid, words, [])).toBe('CALM');
+  });
+
+  it('is harmless on an already-found word (no re-record)', () => {
+    expect(matchWord([[0, 0], [0, 1], [0, 2], [0, 3]], grid, words, ['CALM'])).toBe(null);
+  });
+
+  it('returns null for a non-word or too-short selection', () => {
+    expect(matchWord([[1, 0], [1, 1], [1, 2], [1, 3]], grid, words, [])).toBe(null); // XXXX
+    expect(matchWord([[0, 0]], grid, words, [])).toBe(null);
+    expect(matchWord([], grid, words, [])).toBe(null);
+  });
+});