scrabble-solver 2.15.24 → 2.16.0-alpha.0

package/.nx/workspace-data/source-maps.json

@@ -680,6 +680,10 @@
       "packages/scrabble-solver/package.json",
       "nx/core/package-json"
     ],
+    "metadata.targetGroups.NPM Scripts.6": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
     "metadata.description": [
       "packages/scrabble-solver/package.json",
       "nx/core/package-json"
@@ -852,6 +856,34 @@
       "packages/scrabble-solver/package.json",
       "nx/core/package-json"
     ],
+    "targets.test": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.executor": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options.script": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.scriptContent": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.runCommand": [
+      "packages/scrabble-solver/package.json",
+      "nx/core/package-json"
+    ],
     "targets.type-check": [
       "packages/scrabble-solver/package.json",
       "nx/core/package-json"
@@ -926,6 +958,10 @@
       "packages/solver/package.json",
       "nx/core/package-json"
     ],
+    "metadata.targetGroups.NPM Scripts.2": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
     "metadata.description": [
       "packages/solver/package.json",
       "nx/core/package-json"
@@ -1014,6 +1050,34 @@
       "packages/solver/package.json",
       "nx/core/package-json"
     ],
+    "targets.test": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.executor": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options.script": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.scriptContent": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.runCommand": [
+      "packages/solver/package.json",
+      "nx/core/package-json"
+    ],
     "targets.build.dependsOn": [
       "nx.json",
       "nx/target-defaults"
@@ -1194,6 +1258,10 @@
       "packages/word-definitions/package.json",
       "nx/core/package-json"
     ],
+    "metadata.targetGroups.NPM Scripts.2": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
     "metadata.description": [
       "packages/word-definitions/package.json",
       "nx/core/package-json"
@@ -1282,6 +1350,34 @@
       "packages/word-definitions/package.json",
       "nx/core/package-json"
     ],
+    "targets.test": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.executor": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.options.script": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.scriptContent": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
+    "targets.test.metadata.runCommand": [
+      "packages/word-definitions/package.json",
+      "nx/core/package-json"
+    ],
     "targets.build.dependsOn": [
       "nx.json",
       "nx/target-defaults"

package/.oxlintrc.json

@@ -0,0 +1,314 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "react", "import", "unicorn", "oxc", "jest"],
+  "jsPlugins": [
+    { "name": "import-js", "specifier": "eslint-plugin-import" },
+    { "name": "mocha", "specifier": "eslint-plugin-mocha" },
+    { "name": "react-js", "specifier": "eslint-plugin-react" }
+  ],
+  "env": {
+    "browser": true,
+    "node": true,
+    "jest": true,
+    "mocha": true,
+    "jquery": true,
+    "serviceworker": true
+  },
+  "globals": {
+    "RequestInfo": "readonly",
+    "RequestInit": "readonly",
+    "ServiceWorkerGlobalScope": "readonly",
+    "beforeAll": "readonly",
+    "cy": "readonly",
+    "Cypress": "readonly",
+    "define": "readonly",
+    "describe": "readonly",
+    "expect": "readonly",
+    "globalThis": "readonly",
+    "it": "readonly",
+    "jest": "readonly"
+  },
+  "options": {
+    "typeAware": true
+  },
+  "settings": {
+    "react": {
+      "version": "19"
+    },
+    "import-js/extensions": [".js", ".jsx", ".ts", ".tsx"],
+    "import-js/external-module-folders": ["node_modules"],
+    "import-js/parsers": {
+      "@typescript-eslint/parser": [".ts", ".tsx"]
+    },
+    "import-js/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true,
+        "project": ["tsconfig.json", "packages/*/tsconfig.json", "cypress/tsconfig.json"]
+      },
+      "node": true
+    }
+  },
+  "ignorePatterns": [
+    "**/bin/*.js",
+    "**/build/**/*",
+    "**/coverage/**/*",
+    "**/dist/**/*",
+    "**/node_modules/**/*",
+    "**/*.d.ts",
+    "**/.eslintrc.js",
+    "**/babel.config.js",
+    "**/bump-version.js",
+    "packages/scrabble-solver/next.config.js",
+    "packages/logger/scripts/stats.js",
+    "packages/scrabble-solver/public/service-worker.js",
+    "**/.next/**/*"
+  ],
+  "rules": {
+    "import/default": "error",
+    "import/no-absolute-path": "error",
+    "import/no-cycle": "error",
+    "import/no-dynamic-require": "error",
+
+    "import-js/newline-after-import": "error",
+    "import-js/order": [
+      "error",
+      {
+        "alphabetize": { "order": "asc", "caseInsensitive": true },
+        "groups": [["builtin", "external"], "internal", "parent", "sibling", "index"],
+        "newlines-between": "always",
+        "pathGroups": [{ "pattern": "@/**", "group": "internal" }],
+        "pathGroupsExcludedImportTypes": ["builtin"]
+      }
+    ],
+
+    "mocha/no-exclusive-tests": "error",
+    "jest/no-focused-tests": "error",
+
+    "react-js/no-deprecated": "error",
+    "react-js/no-unused-prop-types": "error",
+    "react-js/sort-comp": [
+      "error",
+      {
+        "order": [
+          "static-methods",
+          "instance-variables",
+          "lifecycle",
+          "/^on.+$/",
+          "everything-else",
+          "render",
+          "/^render.+/"
+        ]
+      }
+    ],
+    "react-js/sort-prop-types": ["error", { "ignoreCase": true, "callbacksLast": true }],
+
+    "no-cond-assign": "error",
+    "no-console": "warn",
+    "no-constant-condition": "error",
+    "no-control-regex": "error",
+    "no-debugger": "warn",
+    "no-dupe-keys": "error",
+    "no-duplicate-case": "error",
+    "no-empty": "error",
+    "no-empty-character-class": "error",
+    "no-ex-assign": "error",
+    "no-extra-boolean-cast": "error",
+    "no-func-assign": "error",
+    "no-invalid-regexp": "error",
+    "no-irregular-whitespace": "error",
+    "no-unsafe-negation": "error",
+    "no-obj-calls": "error",
+    "no-regex-spaces": "error",
+    "no-sparse-arrays": "error",
+    "no-unexpected-multiline": "error",
+    "no-unreachable": "error",
+    "no-unsafe-finally": "error",
+    "use-isnan": "error",
+    "valid-typeof": "error",
+    "accessor-pairs": "error",
+    "array-callback-return": "error",
+    "block-scoped-var": "error",
+    "curly": ["error", "all"],
+    "default-case": "error",
+    "dot-notation": "error",
+    "eqeqeq": "error",
+    "guard-for-in": "error",
+    "no-alert": "error",
+    "no-caller": "error",
+    "no-case-declarations": "error",
+    "no-div-regex": "error",
+    "no-else-return": "error",
+    "no-empty-function": "error",
+    "no-empty-pattern": "error",
+    "no-eq-null": "error",
+    "no-eval": "error",
+    "no-extend-native": "error",
+    "no-extra-bind": "error",
+    "no-extra-label": "error",
+    "no-fallthrough": "error",
+    "no-implicit-coercion": "error",
+    "no-iterator": "error",
+    "no-labels": "error",
+    "no-lone-blocks": "error",
+    "no-loop-func": "error",
+    "no-multi-str": "error",
+    "no-global-assign": "error",
+    "no-new": "error",
+    "no-new-func": "error",
+    "no-new-wrappers": "error",
+    "no-param-reassign": "error",
+    "no-proto": "error",
+    "no-redeclare": ["error", { "builtinGlobals": false }],
+    "no-return-assign": "error",
+    "no-script-url": "error",
+    "no-self-assign": "error",
+    "no-self-compare": "error",
+    "no-sequences": "error",
+    "no-unmodified-loop-condition": "error",
+    "no-unused-expressions": "error",
+    "no-unused-labels": "error",
+    "no-useless-call": "error",
+    "no-useless-concat": "error",
+    "no-useless-escape": "error",
+    "no-void": "error",
+    "no-warning-comments": "warn",
+    "no-with": "error",
+    "radix": "error",
+    "vars-on-top": "error",
+    "yoda": ["error", "never"],
+    "no-delete-var": "error",
+    "no-label-var": "error",
+    "no-restricted-globals": "error",
+    "no-shadow": "error",
+    "no-shadow-restricted-names": "error",
+    "no-undef": "error",
+    "no-unused-vars": "error",
+    "unicorn/no-process-exit": "error",
+
+    "max-depth": ["error", 4],
+    "max-lines": ["warn", 200],
+    "max-nested-callbacks": ["error", 4],
+    "max-params": ["error", 4],
+    "max-statements": ["warn", 20],
+    "new-cap": ["error", { "newIsCap": true, "capIsNew": false, "properties": true }],
+    "no-array-constructor": "error",
+    "no-bitwise": "error",
+    "no-lonely-if": "error",
+    "no-negated-condition": "error",
+    "no-nested-ternary": "error",
+    "no-object-constructor": "error",
+    "no-restricted-exports": [
+      "error",
+      {
+        "restrictDefaultExports": {
+          "direct": true,
+          "named": true,
+          "defaultFrom": true,
+          "namedFrom": true,
+          "namespaceFrom": true
+        }
+      }
+    ],
+    "no-unneeded-ternary": "error",
+    "operator-assignment": ["error", "always"],
+    "sort-vars": "error",
+    "unicode-bom": ["error", "never"],
+
+    "constructor-super": "error",
+    "no-class-assign": "error",
+    "no-const-assign": "error",
+    "no-dupe-class-members": "error",
+    "no-duplicate-imports": "error",
+    "no-this-before-super": "error",
+    "no-useless-computed-key": "error",
+    "no-useless-constructor": "error",
+    "no-useless-rename": "error",
+    "no-var": "error",
+    "object-shorthand": ["error", "always", { "avoidQuotes": true }],
+    "prefer-const": "error",
+    "prefer-rest-params": "error",
+    "prefer-spread": "error",
+    "prefer-template": "error",
+    "require-yield": "error",
+
+    "react/display-name": "off",
+    "react/jsx-no-comment-textnodes": "error",
+    "react/no-danger": "error",
+    "react/no-did-mount-set-state": "error",
+    "react/no-direct-mutation-state": "error",
+    "react/no-is-mounted": "error",
+    "react/no-multi-comp": ["error", { "ignoreStateless": true }],
+    "react/no-render-return-value": "error",
+    "react/no-string-refs": "error",
+    "react/no-unknown-property": "error",
+    "react/prefer-es6-class": "error",
+    "react/react-in-jsx-scope": "off",
+    "react/require-render-return": "error",
+    "react/self-closing-comp": "error",
+    "react/jsx-boolean-value": ["error", "never"],
+    "react/jsx-filename-extension": ["error", { "extensions": [".js", ".jsx", ".ts", ".tsx"] }],
+    "react/jsx-handler-names": [
+      "error",
+      { "eventHandlerPrefix": "on", "eventHandlerPropPrefix": "on" }
+    ],
+    "react/jsx-key": "error",
+    "react/jsx-no-duplicate-props": "error",
+    "react/jsx-no-target-blank": "error",
+    "react/jsx-no-undef": "error",
+    "react/jsx-pascal-case": "error",
+
+    "react/rules-of-hooks": "error",
+    "react/exhaustive-deps": "error"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.ts", "**/*.tsx"],
+      "rules": {
+        "no-unused-vars": "off",
+        "no-shadow": "off",
+        "typescript/consistent-type-imports": ["error", { "fixStyle": "inline-type-imports" }],
+        "typescript/no-deprecated": "error",
+        "typescript/no-shadow": "error",
+        "typescript/no-floating-promises": "error",
+        "typescript/no-misused-promises": "error",
+        "typescript/no-unsafe-argument": "error",
+        "typescript/no-unsafe-call": "error",
+        "typescript/no-unsafe-member-access": "error",
+        "typescript/await-thenable": "error",
+        "typescript/restrict-plus-operands": "error",
+        "typescript/restrict-template-expressions": "error",
+        "typescript/unbound-method": "error",
+        "typescript/no-implied-eval": "error",
+        "typescript/no-unused-vars": [
+          "error",
+          {
+            "argsIgnorePattern": "^_",
+            "caughtErrorsIgnorePattern": "^_",
+            "destructuredArrayIgnorePattern": "^_",
+            "varsIgnorePattern": "^_"
+          }
+        ]
+      }
+    },
+    {
+      "files": ["**/*.test.ts", "**/*.test.tsx"],
+      "rules": {
+        "typescript/no-non-null-assertion": "off"
+      }
+    },
+    {
+      "files": ["**/*.spec.cy.ts", "cypress/**"],
+      "rules": {
+        "max-statements": "off",
+        "jest/valid-expect": "off",
+        "jest/no-focused-tests": "off"
+      }
+    },
+    {
+      "files": ["packages/scrabble-solver/src/pages/**"],
+      "rules": {
+        "no-restricted-exports": "off"
+      }
+    }
+  ]
+}

package/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository layout
+
+This is a Bun-workspaces monorepo (managed with Lerna for versioning/publishing and Nx purely for build caching/ordering). `engines` requires **Bun >=1.3** and **Node.js >=24**. The lockfile is `bun.lock` (text JSON, lockfileVersion 1) — `package-lock.json` was removed when the project migrated off npm/Jest in `#421` (Apr 2026). Workspace scripts use `bun run --filter <pattern> <script>` — the `'./packages/*'` glob runs in dependency order (built-in Nx cache), and `'*'` skips workspaces without that script (relevant for `test`).
+
+The nine packages live under `packages/` and have a strict dependency order. When something breaks "downstream" of where you edited, rebuild the upstream package first:
+
+```
+constants → types → configs ──┐
+                              ├──→ dictionaries → solver → scrabble-solver (Next.js app)
+word-lists ───────────────────┤
+word-definitions ─────────────┘
+logger (independent, used by app + dictionaries)
+```
+
+- `solver` — pure word-finding engine. Given a `Trie`, `Config`, `Board`, and `Tile[]`, returns scored `Result`s. Has no I/O. Pipeline is `generatePatterns → fillPattern (per pattern) → areDigraphsValid (only when `config.twoCharacterTiles` is non-empty) → getUniquePatterns → getPatternScore`. New solving rules belong in this pipeline; `solve.ts` itself is just orchestration.
+- `dictionaries` — downloads/caches per-locale word lists to `$HOME/.scrabble-solver/dictionaries` and exposes them as `Trie`s. The `Dictionaries` class layers a `MemoryCache` over a `DiskCache` (`LayeredCache`) and uses a per-locale `createAsyncProxy` to coalesce concurrent downloads. Cache entries older than `CACHE_STALE_THRESHOLD` (1 day) are refreshed on access. Only this package and `logger` perform filesystem I/O — keep other packages pure so they can run in Edge / browser contexts.
+- `word-lists` — pulls raw word lists from upstream sources (one fetcher per locale in `src/languages/`). Used by `dictionaries` during downloads.
+- `word-definitions` — per-locale `crawl(word) → string` and a parser for each source (Merriam-Webster, CNRTL, DWDS, SJP, dexonline, vajehyab, etc.). Add a new locale by adding a `crawl` and a `parse` function in `src/languages/` and wiring them into `crawl.ts` / `parse.ts`. `parse.test.ts` is where you add fixture-based parser tests.
+- `types` — domain model classes (`Board`, `Cell`, `Tile`, `Pattern`, `Result`, `Config`, `Locale`, …) plus `*Json` shapes. Most of these have a `fromJson` / `toJson` round-trip — use them at the wire boundary instead of hand-rolled serialization.
+- `configs` — split into **games** (`scrabble`, `superScrabble`, `scrabbleDuel`, `letterLeague`, `crossplay`, `literaki`, `kelimelik` — each defines board size, bonuses, rack size, blanks count, bingo bonus) and **languages** (`english`, `french`, …, each spreads a base game config and overrides `locale` + `tiles`). A locale config is one game × one language; e.g. `polishScrabble` = `scrabble` ⊕ Polish tiles + digraphs. Adding a language means a new config here **and** the 15-step checklist under "Add a new language" in `README.md`.
+- `logger` — Winston logger writing JSON to `$HOME/.scrabble-solver/logs/{all,error}.log`. Only `error` goes to console. Used server-side by the app + dictionaries; do **not** import from browser code.
+- `constants` — shared primitives (`BLANK`, `BONUS_CHARACTER`, `BONUS_WORD`, …). No runtime dependencies.
+
+### App package (`@scrabble-solver/scrabble-solver`)
+
+- **Routing**: Next.js Pages Router (`src/pages/`). API routes: `solve`, `verify`, `visit`, `dictionary/[locale]/[word]`. The path alias `@/*` resolves to `src/*` (set in `tsconfig.json`).
+- **State**: Redux Toolkit + Redux-Saga. Slices in `src/state/{board,cellFilters,dictionary,rack,results,settings,solve,verify}`, each exporting `<name>Slice` (reducer + actions) and selectors. The root saga in `state/sagas.ts` reacts to slice actions: `submit` → call SDK → write results back. `solve`, `verify`, and `dictionary` use `takeLatest` (only the latest in-flight request resolves); cell/rack edits use `takeEvery`. State is intentionally **not** serializable-checked (`serializableCheck: false`) because slices hold class instances (`Board`, `Tile`).
+- **SDK layer (`src/sdk/`)**: thin browser/server clients for the four API routes. `findWordDefinitions` is memoized at the saga level via `lib/memoize`. Always go through SDK — never `fetch` directly from a saga or component.
+- **Persistence**: settings, board, and rack auto-persist to `localStorage` via `store2` under the `scrabble-solver` namespace. The `useLocalStorage` hook (mounted in `pages/index.tsx`) subscribes to the three slices and writes them out on every change — **adding a new field to `SettingsState` is enough; you don't need to touch any save code** (PR #321, Apr 2026). On boot, `settingsInitialState` spreads `localStorage.getSettings()` last so persisted values win over the defaults computed at module-load time. When changing settings shape, add a migration block (see `migrateLegacySettings` for the pattern — dated comment with introduction date and life expectancy).
+- **Service worker**: built by `WorkboxPlugin.InjectManifest` from `src/service-worker/index.ts` to `public/service-worker.js`. It precaches the app shell and intercepts `/api/solve` and `/api/verify` requests so the app can still solve offline once a dictionary is cached. Only generated in production builds (`!isServer && !dev`).
+- **i18n**: `src/i18n/languages/<lang>.json` (8 languages, mapped to `Locale` in `i18n.ts`). The `LOCALE_FEATURES` registry in `src/i18n/constants.ts` carries per-locale UI metadata: `direction` ('ltr' | 'rtl'), `comma`/`separator` glyphs (Latin vs Arabic), flag `Icon`, language `label`/`name`, and `consonants`/`vowels` flags that drive the auto-group-tiles UI. The `useDirection` hook applies `direction` to `<html dir>`. Add a new locale by extending this map plus the i18n JSON dictionary plus a `Flag<XX>.svg` icon. `useTranslate()` is the lookup hook.
+- **Layout**: `AppLayoutProvider` (`src/app-layout/`) is a React context exposing `useAppLayoutValue`. It was extracted from a custom hook for memoization reasons — consume layout via `useAppLayout()`, not by re-deriving it. The active modal in `pages/index.tsx` is tracked as a `Record<Modal, boolean>` patched through a single `patchModals` callback.
+- **Styling**: SCSS modules with a shared design-token system. SCSS tokens live in `src/styles/_tokens.scss`; the same values are re-exported to TS via `:export` in `variables.module.scss` (imported in JS as a module, typed by `src/@types/scss.d.ts`). Concrete JS constants live in `src/parameters/index.ts` (e.g. `BREAKPOINTS`, `COLOR_BLUE`, `TRANSITION_DURATION`) — that file is the only place that should read from `variables.module.scss`. Update `_tokens.scss` first → expose via `variables.module.scss` `:export` block → consume via `parameters/`. This was added in PR #228 (Apr 2026); before it, JS-side colors and breakpoints were hard-coded duplicates. Responsive helpers come from `include-media`.
+- **SVGs**: imported as React components via `@svgr/webpack` (configured in `next.config.js`), typed by `src/@types/svg.d.ts`.
+- **Service worker registration**: production-only. Registered by `serviceWorkerManager.ts` from the index page; Cypress tests must call `unregisterServiceWorkers()` (in `cypress/support/lib`) in `beforeEach` and `cy.clearLocalStorage()` in `afterEach` to avoid bleed-through between tests.
+
+## Common commands
+
+All commands run from the repo root unless noted.
+
+| Task | Command |
+| --- | --- |
+| Install + build everything | `bun install && bun run build` |
+| Build all packages | `bun run build` (Nx-cached, respects dep order) |
+| Build one package | `bun run --filter @scrabble-solver/<name> build` |
+| Dev server (port 3000) | `bun run dev` |
+| Production server (port 3333) | `bun start` |
+| Lint | `bun run lint` (oxlint) / `bun run lint:fix` |
+| Format check / fix | `bun run format` / `bun run format:fix` (oxfmt) |
+| Type-check the app | `bun run --filter @scrabble-solver/scrabble-solver type-check` (uses `tsgo`, the TypeScript native preview) |
+| Unit tests (all workspaces) | `bun run test-unit` |
+| Unit tests (one package) | `bun run --filter @scrabble-solver/solver test` |
+| One unit test file | `cd packages/solver && bun test src/solve.test.ts` |
+| One unit test by name | `cd packages/solver && bun test -t "pattern"` |
+| Cypress (interactive) | `bun run test-cypress` (expects dev server on :3000) |
+| Cypress (headless) | `bun run test-cypress:run` (expects server on :3333) |
+| Full test pipeline | `bun run test` (build → unit → `start-server-and-test` boots the app on :3333 → cypress run) — note: `bun test` invokes Bun's built-in test runner, not this script |
+
+Hot reload only works for the `scrabble-solver` package. Edits to any other package require rebuilding that package before the app picks them up.
+
+## Testing notes
+
+- Unit tests run on **Bun's test runner**, not Jest. The API is Jest-compatible (`describe`/`it`/`expect`), which is why the oxlint config still loads the `jest` plugin for rules like `no-focused-tests`.
+- Only `solver`, `word-definitions`, and `scrabble-solver` have a `test` script. Tests are auto-discovered under `src/` matching `*.test.ts(x)`. The 180s timeout is needed because some solver tests build a real `Trie` from a downloaded dictionary.
+- `bunfig.toml` + `bun.test.preload.ts` register a SCSS loader stub (returns a `Proxy` whose keys are their own names) so component tests can import `*.scss` modules without a real compiler. If you add other non-JS imports to test-touched code (images, etc.), extend the preload.
+- Each package's `tsconfig.json` excludes `**/*.test.ts` from the build output. Tests are not part of published packages.
+- Cypress: tests in `cypress/e2e/`. Custom command setup in `cypress/support/commands.ts` (registers `@testing-library/cypress` and `cypress-real-events`). Two base URLs are in play: `cypress.config.ts` defaults to `http://localhost:3000` (matches `bun run dev`); `test-cypress:run` and CI override to `:3333` (matches `bun start`). Pick the script that matches the server you're actually running.
+
+## Tooling specifics
+
+- **Linting**: `oxlint` (Rust-based ESLint replacement) configured in `.oxlintrc.json`. Type-aware rules require `oxlint-tsgolint`. Adding a new top-level JS config file usually means adding it to `ignorePatterns`. The oxlint config still loads the `jest` plugin and `jest` global because Bun's test runner mirrors the Jest API; do not remove them.
+- **Formatting**: `oxfmt` covers `*.{js,ts,tsx,scss}`.
+- **TypeScript**: the project upgraded to TypeScript 7 via the native-preview compiler (PR #422). The runtime devDep is `typescript@^6.0.3` (kept for tooling that expects classic `tsc`), but the actual compiler used by the app's `type-check` and by `next build` is `tsgo` from `@typescript/native-preview` (a 7.x dev build). Plain `tsc` is not in the build path. Root `tsconfig.json` sets `types: ["bun"]` for global test-runner types and excludes `cypress` and `cypress.config.ts`; library packages extend it and additionally exclude `**/*.test.ts` from emitted output.
+- **Next.js**: built with `--webpack` flag explicitly (the default Turbopack is intentionally not used). `next.config.js` registers `@svgr/webpack` for SVG-as-component imports and the Workbox `InjectManifest` plugin for the service worker. SCSS load paths are extended to `./src` and `node_modules/include-media/dist`.
+- **Nx**: `nx.json` only defines a `build` target with `dependsOn: ["^build"]` and `cache: true`. It is used purely for dependency-aware build ordering and caching — there are no Nx generators or executors.
+
+## CI workflows
+
+`.github/workflows/`:
+
+- `build.yml` — `bun install --frozen-lockfile && bun run build`.
+- `unit-tests.yml` — `bun run build && bun run test-unit`.
+- `e2e-tests.yml` — Cypress against `bun start` on :3333. Uploads screenshots on failure.
+- `oxlint.yml` / `oxfmt.yml` — lint and format-check.
+- `bunx.yml` — runs daily and on PR. Installs the latest published `scrabble-solver` via `bun add --global scrabble-solver@latest`, runs Cypress against it. Catches packaging regressions in the `bin/scrabble-solver.js` launcher.
+- `deploy.yml` — `workflow_dispatch` only. SSHs into prod, pulls, builds, restarts `scrabble-solver.service`.
+
+When adding a workflow, match the existing pattern: trigger on `push`/`pull_request` to `master`, use `actions/checkout@v6` and `oven-sh/setup-bun@v2`, install with `bun install --frozen-lockfile`.
+
+## Versioning & publishing
+
+`bun run release` chains `reinstall → version:bump → np → lerna publish from-package`. `version:bump` runs `lerna version --force-publish` (bumps every package in lockstep) followed by `bump-version.js` to sync any other version references, then commits. Don't hand-edit `version` fields across packages — use the script.
+
+## Deploys
+
+The `Deploy` GitHub workflow (`workflow_dispatch` only) SSHs into the production host, pulls the chosen branch, runs `bun install && bun run build`, and restarts `scrabble-solver.service` via `systemctl`. There's no separate staging environment.
+
+## Runtime data
+
+The app reads/writes user data outside the project directory:
+
+- `$HOME/.scrabble-solver/dictionaries/` — cached `Trie`s, one per locale, refreshed when older than 1 day.
+- `$HOME/.scrabble-solver/logs/{all,error}.log` — Winston JSON logs.
+
+The `bunx scrabble-solver@latest` entry point (`bin/scrabble-solver.js`) just `cd`s to the package root and runs `bun start`. The app then serves on http://localhost:3333.
+
+## Recent migrations to keep in mind
+
+Look here when something seems set up oddly — the reason is usually one of these recent changes. Reference issue numbers, not dates, when grepping git log.
+
+- **#421 — Bun migration** (Apr 2026). npm/Jest → Bun. Top-level scripts now use `bun run --filter`, lockfile is `bun.lock`, unit tests run on `bun test`, the published binary's launcher (`bin/scrabble-solver.js`) shells out to `bun start`, and the old `npx.yml` workflow was renamed to `bunx.yml` (now installs the published package via `bun add --global`). All workflows use `oven-sh/setup-bun@v2`; `e2e-tests.yml` is the only one that also uses `setup-node` (Cypress action).
+- **#422 — TypeScript 7** (Apr 2026). Build/type-check use `tsgo` (native preview). Don't reintroduce `tsc` calls.
+- **#420 — ESLint → Oxlint**. The `eslint-plugin-*` packages still appear in devDeps because oxlint loads them as JS plugins (`jsPlugins` in `.oxlintrc.json`). Don't strip them.
+- **#321 — Auto-persisted settings** (Apr 2026). Settings, board, and rack are written through a single `useLocalStorage` effect. Don't dispatch save actions manually.
+- **#228 — CSS variables in JS** (Apr 2026). JS constants for colors/sizes flow from `_tokens.scss` → `variables.module.scss` `:export` → `parameters/index.ts`. Don't hard-code the same values in TS.
+- **#360 — Dart Sass deprecations**. SCSS files migrated to modern syntax (`@use`, `math.div`, etc.). New SCSS should follow that style; `next.config.js` sets `sassOptions.quietDeps: true` to keep upstream warnings out of build output.