@scrabble-solver/scrabble-solver 2.17.0 → 2.18.1

package/src/state/localStorage.ts

@@ -1,13 +1,20 @@
-import { Board, type BoardJson } from '@scrabble-solver/types';
+import { Board, type BoardJson, isObject, type Locale } from '@scrabble-solver/types';
 import store2 from 'store2';
 
-import type { Rack } from '@/types';
+import type { Rack, Translations } from '@/types';
 
 import type { SettingsState } from './settings/types';
 
 const BOARD = 'board';
 const RACK = 'rack';
 const SETTINGS = 'settings';
+const TRANSLATIONS = 'translations';
+
+interface PersistedTranslations {
+  locale: Locale;
+  translations: Translations;
+  version: string;
+}
 
 const LEGACY_KEYS: Record<keyof SettingsState, string> = {
   autoGroupTiles: 'auto-group-tiles',
@@ -21,33 +28,15 @@ const LEGACY_KEYS: Record<keyof SettingsState, string> = {
 
 const store = store2.namespace('scrabble-solver');
 
-/**
- * Introduced in 2.15.26 on 2026/04/27.
- * Life expectancy: 1y.
- */
-const migrateLegacySettings = (): Partial<SettingsState> => {
-  const settings: Partial<SettingsState> = {};
-  let hasLegacy = false;
-
-  for (const [setting, legacyKey] of Object.entries(LEGACY_KEYS) as [keyof SettingsState, string][]) {
-    if (store.has(legacyKey)) {
-      settings[setting] = store.get(legacyKey);
-      store.remove(legacyKey);
-      hasLegacy = true;
-    }
-  }
-
-  if (hasLegacy) {
-    store.set(SETTINGS, settings, true);
-  }
-
-  return settings;
-};
-
 export const localStorage = {
   getBoard(): Board | undefined {
-    const serialized = store.get(BOARD) as string | undefined;
-    return serialized ? Board.fromJson(JSON.parse(serialized) as BoardJson) : undefined;
+    try {
+      const serialized = store.get(BOARD) as string | undefined;
+      return serialized ? Board.fromJson(JSON.parse(serialized) as BoardJson) : undefined;
+    } catch {
+      store.remove(BOARD);
+      return undefined;
+    }
   },
 
   setBoard(board: Board | undefined): void {
@@ -56,7 +45,14 @@ export const localStorage = {
   },
 
   getRack(): Rack | undefined {
-    return store.get(RACK) as Rack | undefined;
+    const rack = store.get(RACK) as Rack | undefined;
+
+    if (rack !== undefined && !Array.isArray(rack)) {
+      store.remove(RACK);
+      return undefined;
+    }
+
+    return rack;
   },
 
   setRack(rack: Rack | undefined): void {
@@ -65,10 +61,71 @@ export const localStorage = {
 
   getSettings(): Partial<SettingsState> {
     const stored = store.get(SETTINGS) as Partial<SettingsState> | undefined;
-    return stored ?? migrateLegacySettings();
+
+    if (stored !== undefined && !isObject(stored)) {
+      store.remove(SETTINGS);
+    }
+
+    return migrateHiddenShowCoordinates(isObject(stored) ? stored : migrateLegacySettings());
   },
 
   setSettings(settings: SettingsState): void {
     store.set(SETTINGS, settings, true);
   },
+
+  getTranslations(locale: Locale, version: string): Translations | undefined {
+    const stored = store.get(TRANSLATIONS) as PersistedTranslations | undefined;
+
+    if (typeof stored === 'undefined') {
+      return undefined;
+    }
+
+    if (!isObject(stored) || stored.locale !== locale || stored.version !== version || !isObject(stored.translations)) {
+      store.remove(TRANSLATIONS);
+      return undefined;
+    }
+
+    return stored.translations;
+  },
+
+  setTranslations(locale: Locale, version: string, translations: Translations): void {
+    store.set(TRANSLATIONS, { locale, translations, version } satisfies PersistedTranslations, true);
+  },
 };
+
+/**
+ * Introduced in 2.15.26 on 2026/04/27.
+ * Life expectancy: 1y.
+ */
+function migrateLegacySettings(): Partial<SettingsState> {
+  const settings: Partial<SettingsState> = {};
+  let hasLegacy = false;
+
+  for (const [setting, legacyKey] of Object.entries(LEGACY_KEYS) as [keyof SettingsState, string][]) {
+    if (store.has(legacyKey)) {
+      settings[setting] = store.get(legacyKey);
+      store.remove(legacyKey);
+      hasLegacy = true;
+    }
+  }
+
+  if (hasLegacy) {
+    store.set(SETTINGS, settings, true);
+  }
+
+  return settings;
+}
+
+/**
+ * The 'hidden' showCoordinates option was removed on 2026/08/13.
+ * Life expectancy: 1y.
+ */
+function migrateHiddenShowCoordinates(settings: Partial<SettingsState>): Partial<SettingsState> {
+  if (String(settings.showCoordinates) !== 'hidden') {
+    return settings;
+  }
+
+  const migrated: Partial<SettingsState> = { ...settings, showCoordinates: 'original' };
+  store.set(SETTINGS, migrated, true);
+  return migrated;
+}

package/src/state/rack/initialState.ts

@@ -1,6 +1,5 @@
 import { getConfig } from '@scrabble-solver/configs';
 
-import { localStorage } from '../localStorage';
 import { settingsInitialState } from '../settings';
 
 import type { RackState } from './types';
@@ -9,4 +8,4 @@ const defaultConfig = getConfig(settingsInitialState.game, settingsInitialState.
 
 export const rackDefaultState: RackState = Array(defaultConfig.rackSize).fill(null);
 
-export const rackInitialState: RackState = localStorage.getRack() ?? rackDefaultState;
+export const rackInitialState: RackState = rackDefaultState;

package/src/state/rack/slice.ts

@@ -1,7 +1,10 @@
 import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
 import { type Tile } from '@scrabble-solver/types';
 
-import { arrayEquals, createNullMovingComparator, inverseDirection, zipCharactersAndTiles } from '@/lib';
+import { arrayEquals } from '@/lib/arrayEquals';
+import { createNullMovingComparator } from '@/lib/createNullMovingComparator';
+import { inverseDirection } from '@/lib/inverseDirection';
+import { zipCharactersAndTiles } from '@/lib/zipCharactersAndTiles';
 import { type AutoGroupTiles, type Rack } from '@/types';
 
 import { rackDefaultState, rackInitialState } from './initialState';

package/src/state/results/lib.ts

@@ -1,6 +1,10 @@
 import { type Result, type ShowCoordinates } from '@scrabble-solver/types';
 
-import { createKeyComparator, createRegExp, createStringComparator, getCoordinate, reverseComparator } from '@/lib';
+import { createKeyComparator } from '@/lib/createKeyComparator';
+import { createRegExp } from '@/lib/createRegExp';
+import { createStringComparator } from '@/lib/createStringComparator';
+import { getCoordinate } from '@/lib/getCoordinate';
+import { reverseComparator } from '@/lib/reverseComparator';
 import {
   type CellFilter,
   type Comparator,
@@ -11,10 +15,6 @@ import {
 } from '@/types';
 
 export const getCoordinates = (result: Result, showCoordinates: ShowCoordinates): string => {
-  if (showCoordinates === 'hidden') {
-    return '';
-  }
-
   const firstCell = result.cells[0];
   const x = getCoordinate(firstCell.x, showCoordinates === 'original' ? 'letter' : 'number');
   const y = getCoordinate(firstCell.y, showCoordinates === 'original' ? 'number' : 'letter');

package/src/state/results/selectors.ts

@@ -1,6 +1,6 @@
 import { createSelector } from '@reduxjs/toolkit';
 
-import { createRegExp } from '@/lib';
+import { createRegExp } from '@/lib/createRegExp';
 
 import { selectCellFilters } from '../cellFilters';
 import { selectLocale, selectShowCoordinates } from '../settings';

package/src/state/sagas.ts

@@ -5,18 +5,23 @@
 
 import { type PayloadAction } from '@reduxjs/toolkit';
 import { hasConfig, languages } from '@scrabble-solver/configs';
-import { Board, type Locale, type Result } from '@scrabble-solver/types';
+import { Board, Locale, type Result } from '@scrabble-solver/types';
 import { call, delay, put, select, spawn, takeEvery, takeLatest } from 'redux-saga/effects';
 
-import { LOCALE_FEATURES } from '@/i18n';
-import { memoize } from '@/lib';
+import { LOCALE_FEATURES } from '@/i18n/constants';
+import { loadTranslations } from '@/i18n/i18n';
+import { memoize } from '@/lib/memoize';
+import { waitForFirstIntent, waitForIdleOrFirstIntent } from '@/lib/waitForIdleOrFirstIntent';
 import { findWordDefinitions, solve, verify, visit } from '@/sdk';
 import { prefetchDictionary } from '@/solver-worker';
 
 import { initialize, reset } from './actions';
+import { appSlice, selectVersion } from './app';
 import { boardSlice, selectBoard } from './board';
 import { cellFiltersSlice, selectCellFilter } from './cellFilters';
 import { dictionarySlice, selectDictionary } from './dictionary';
+import { i18nSlice, selectLoadedTranslations } from './i18n';
+import { localStorage } from './localStorage';
 import { rackSlice, selectCharacters, selectRack } from './rack';
 import { resultsSlice } from './results';
 import {
@@ -25,8 +30,11 @@ import {
   selectLocale,
   selectLocaleAutoGroupTiles,
   selectRemoveCellFilters,
+  settingsInitialState,
   settingsSlice,
+  type SettingsState,
 } from './settings';
+import { guessLocale } from './settings/lib';
 import { solveSlice } from './solve';
 import { verifySlice } from './verify';
 
@@ -119,13 +127,22 @@ function* onDictionarySubmit(): AnyGenerator {
   }
 }
 
-function* onInitialize(): AnyGenerator {
+function* onInitialize({ payload }: PayloadAction<{ version: string }>): AnyGenerator {
+  try {
+    yield* hydratePersistedState(payload.version);
+    // oxlint-disable-next-line no-empty
+  } catch {
+  } finally {
+    yield put(appSlice.actions.hydrated());
+  }
+
   const board = yield select(selectBoard);
   const locale = yield select(selectLocale);
 
-  yield spawn(prefetchDictionary, locale);
-  // Detached: offline, a failed visit would otherwise tear down the whole root saga.
-  yield spawn(visit);
+  yield spawn(prefetchDictionaryOnFirstIntent);
+  yield spawn(loadLocaleTranslations, locale);
+  yield spawn(preloadTranslationsWhenIdle);
+  yield spawn(visitWhenIdle);
 
   if (!board.isEmpty()) {
     yield* resetRack();
@@ -133,6 +150,100 @@ function* onInitialize(): AnyGenerator {
   }
 }
 
+function* hydratePersistedState(version: string): AnyGenerator {
+  const isTouchScreen = globalThis.matchMedia?.('(hover: none)').matches ?? false;
+  const settings: Pick<SettingsState, 'game' | 'inputMode' | 'locale'> & Partial<SettingsState> = {
+    game: settingsInitialState.game,
+    inputMode: isTouchScreen ? ('touchscreen' as const) : ('keyboard' as const),
+    locale: guessLocale(),
+    ...localStorage.getSettings(),
+  };
+
+  if (!hasConfig(settings.game, settings.locale)) {
+    const localeDefault = Object.values(languages).find((config) => config.locale === settings.locale);
+    settings.game = localeDefault?.game ?? settingsInitialState.game;
+    settings.locale = localeDefault?.locale ?? guessLocale();
+  }
+
+  yield put(settingsSlice.actions.init(settings));
+  yield* hydratePersistedTranslations(settings.locale, version);
+
+  const config = yield select(selectConfig);
+  const currentBoard: Board = yield select(selectBoard);
+  const board = localStorage.getBoard();
+
+  if (board) {
+    yield put(boardSlice.actions.init(board));
+  } else if (currentBoard.rows.length !== config.boardHeight || currentBoard.rows[0].length !== config.boardWidth) {
+    yield put(boardSlice.actions.init(Board.create(config.boardWidth, config.boardHeight)));
+  }
+
+  const currentRack = yield select(selectRack);
+  const rack = localStorage.getRack();
+
+  if (rack) {
+    yield put(rackSlice.actions.init(rack));
+  } else if (currentRack.length !== config.rackSize) {
+    yield put(rackSlice.actions.init(Array(config.rackSize).fill(null)));
+  }
+}
+
+// Applied synchronously so the first post-hydration paint is already translated
+function* hydratePersistedTranslations(locale: Locale, version: string): AnyGenerator {
+  const translations = localStorage.getTranslations(locale, version);
+
+  if (translations) {
+    yield put(i18nSlice.actions.loaded({ locale, translations }));
+  }
+}
+
+function* visitWhenIdle(): AnyGenerator {
+  yield call(waitForIdleOrFirstIntent);
+  yield call(visit);
+}
+
+function* prefetchDictionaryOnFirstIntent(): AnyGenerator {
+  yield call(waitForFirstIntent);
+  const locale = yield select(selectLocale);
+  yield call(prefetchDictionary, locale);
+}
+
+function* loadLocaleTranslations(locale: Locale): AnyGenerator {
+  const loaded = yield select(selectLoadedTranslations);
+
+  if (loaded[locale]) {
+    return;
+  }
+
+  const translations = yield call(loadTranslations, locale);
+  yield put(i18nSlice.actions.loaded({ locale, translations }));
+
+  const activeLocale = yield select(selectLocale);
+
+  if (locale === activeLocale) {
+    const version = yield select(selectVersion);
+    localStorage.setTranslations(locale, version, translations);
+  }
+}
+
+// The cache makes the next boot's first paint translated without waiting for a chunk download
+function* persistTranslationsCache(locale: Locale): AnyGenerator {
+  const loaded = yield select(selectLoadedTranslations);
+  const version = yield select(selectVersion);
+
+  if (loaded[locale]) {
+    localStorage.setTranslations(locale, version, loaded[locale]);
+  }
+}
+
+function* preloadTranslationsWhenIdle(): AnyGenerator {
+  yield call(waitForIdleOrFirstIntent);
+
+  for (const locale of Object.values(Locale)) {
+    yield spawn(loadLocaleTranslations, locale);
+  }
+}
+
 function* onReset(): AnyGenerator {
   const config = yield select(selectConfig);
 
@@ -146,7 +257,9 @@ function* onReset(): AnyGenerator {
 }
 
 function* onLocaleChange({ payload: locale }: PayloadAction<Locale>): AnyGenerator {
+  yield spawn(loadLocaleTranslations, locale);
   yield spawn(prefetchDictionary, locale);
+  yield* persistTranslationsCache(locale);
 
   const game = yield select(selectGame);
 
@@ -176,11 +289,14 @@ function* onResultCandidateChange({ payload: result }: PayloadAction<Result | nu
     return;
   }
 
-  yield delay(SUBMIT_DELAY);
-
   const locale: Locale = yield select(selectLocale);
   const uniqueWords = Array.from(new Set(result.words));
   const input = uniqueWords.join(LOCALE_FEATURES[locale].separator);
+
+  if (!memoizedFindWordDefinitions.hasCache(locale, input)) {
+    yield delay(SUBMIT_DELAY);
+  }
+
   yield put(dictionarySlice.actions.changeInput(input));
   yield put(dictionarySlice.actions.submit());
 }

package/src/state/selectors.ts

@@ -1,6 +1,6 @@
 import { createSelector } from '@reduxjs/toolkit';
 
-import { unorderedArraysEqual } from '@/lib';
+import { unorderedArraysEqual } from '@/lib/unorderedArraysEqual';
 
 import { selectBoard } from './board';
 import { getRemainingTiles } from './lib';

package/src/state/settings/initialState.ts

@@ -1,19 +1,16 @@
-import { Game } from '@scrabble-solver/types';
+import { Game, Locale } from '@scrabble-solver/types';
 
-import { localStorage } from '../localStorage';
-
-import { guessLocale } from './lib';
 import type { SettingsState } from './types';
 
-const isTouchScreen = typeof globalThis.matchMedia !== 'undefined' && globalThis.matchMedia('(hover: none)').matches;
-
+/**
+ * Deterministic defaults shared by the server render and the client's hydration render.
+ */
 export const settingsInitialState: SettingsState = {
   autoGroupTiles: null,
   game: Game.Scrabble,
   highlightUnreachableCells: false,
-  inputMode: isTouchScreen ? 'touchscreen' : 'keyboard',
-  locale: guessLocale(),
+  inputMode: 'keyboard',
+  locale: Locale.EN_US,
   removeCellFilters: 'always',
-  showCoordinates: 'hidden',
-  ...localStorage.getSettings(),
+  showCoordinates: 'original',
 };

package/src/state/settings/selectors.ts

@@ -3,8 +3,10 @@ import { getConfig } from '@scrabble-solver/configs';
 import { BLANK } from '@scrabble-solver/constants';
 import { type Cell, type Tile } from '@scrabble-solver/types';
 
-import { i18n, LOCALE_FEATURES } from '@/i18n';
+import { LOCALE_FEATURES } from '@/i18n/constants';
+import { englishTranslations } from '@/i18n/i18n';
 
+import { selectLoadedTranslations } from '../i18n';
 import type { RootState } from '../types';
 
 const selectCell = (_: unknown, cell: Cell): Cell => cell;
@@ -68,6 +70,9 @@ export const selectCellIsValid = createSelector([selectConfig, selectCell], (con
   return config.tiles.some((tile) => tile.character === cell.tile.character);
 });
 
-export const selectTranslations = createSelector([selectLocale], (locale) => i18n[locale]);
+export const selectTranslations = createSelector(
+  [selectLocale, selectLoadedTranslations],
+  (locale, translations) => translations[locale] ?? englishTranslations,
+);
 
 export const selectRemoveCellFilters = createSelector([selectSettings], (settings) => settings.removeCellFilters);

package/src/state/settings/slice.ts

@@ -44,8 +44,11 @@ export const settingsSlice = createSlice({
       return { ...state, removeCellFilters };
     },
 
-    init: (state, action: PayloadAction<Partial<Pick<typeof settingsInitialState, 'game' | 'locale'>>>) => {
-      return { ...state, ...action.payload };
+    init: (state, action: PayloadAction<Partial<typeof settingsInitialState>>) => {
+      const settings = { ...state, ...action.payload };
+      const keys = Object.keys(settings) as (keyof typeof settingsInitialState)[];
+      const hasDiff = keys.some((key) => settings[key] !== state[key]);
+      return hasDiff ? settings : state;
     },
   },
 });

package/src/state/store.ts

@@ -1,10 +1,12 @@
 import { configureStore } from '@reduxjs/toolkit';
 import reduxSaga from 'redux-saga';
 
+import { appSlice } from './app';
 import { boardSlice } from './board';
 import { cellFiltersSlice } from './cellFilters';
 import { dictionarySlice } from './dictionary';
 import { hoveredTileSlice } from './hoveredTile';
+import { i18nSlice } from './i18n';
 import { rackSlice } from './rack';
 import { resultsSlice } from './results';
 import { rootSaga } from './sagas';
@@ -16,10 +18,12 @@ const sagaMiddleware = reduxSaga();
 
 export const store = configureStore({
   reducer: {
+    app: appSlice.reducer,
     board: boardSlice.reducer,
     cellFilters: cellFiltersSlice.reducer,
     dictionary: dictionarySlice.reducer,
     hoveredTile: hoveredTileSlice.reducer,
+    i18n: i18nSlice.reducer,
     rack: rackSlice.reducer,
     results: resultsSlice.reducer,
     settings: settingsSlice.reducer,

package/src/state/types.ts

@@ -1,7 +1,9 @@
+import type { AppState } from './app';
 import type { BoardState } from './board';
 import type { CellFiltersState } from './cellFilters';
 import type { DictionaryState } from './dictionary';
 import type { HoveredTileState } from './hoveredTile';
+import type { I18nState } from './i18n';
 import type { RackState } from './rack';
 import type { ResultsState } from './results';
 import type { SettingsState } from './settings';
@@ -9,10 +11,12 @@ import type { SolveState } from './solve';
 import type { VerifyState } from './verify';
 
 export type RootState = {
+  app: AppState;
   board: BoardState;
   cellFilters: CellFiltersState;
   dictionary: DictionaryState;
   hoveredTile: HoveredTileState;
+  i18n: I18nState;
   rack: RackState;
   results: ResultsState;
   settings: SettingsState;

package/src/styles/_tokens.scss

@@ -57,3 +57,4 @@ $modal-width: 370px;
 $results-item-height: 40px;
 $solver-column-width: 580px;
 $text-input-height: 40px;
+$tile-size-max: 80px;

package/src/styles/global.scss

@@ -50,3 +50,12 @@ h4 {
 nextjs-portal {
   display: none;
 }
+
+/**
+ * Added pre-paint by _document's inline script when the persisted game differs from the
+ * prerendered default board; removed after hydration applies the persisted config.
+ * The class name must match CONFIG_PENDING_CLASS in parameters/index.ts.
+ */
+html.config-pending main {
+  visibility: hidden;
+}

package/src/styles/variables.module.scss

@@ -7,23 +7,16 @@
   breakpointL: strip-unit($breakpoint-l);
   breakpointXl: strip-unit($breakpoint-xl);
 
-  borderColor: $border-color;
   borderColorLight: $border-color-light;
-  borderRadius: strip-unit($border-radius);
   borderWidth: strip-unit($border-width);
 
-  colorBlue: $color-blue;
   colorBlueLight: $color-blue-light;
-  colorGreen: $color-green;
   colorGreenLight: $color-green-light;
-  colorRed: $color-red;
   colorRedLight: $color-red-light;
   colorVioletLight: $color-violet-light;
-  colorYellow: $color-yellow;
   colorYellowLight: $color-yellow-light;
 
   colorBackground: $color-background;
-  colorForegroundSecondary: $color-foreground-secondary;
 
   colorBonusCharacterMultiplier2: $color-bonus-character-multiplier-2;
   colorBonusCharacterMultiplier3: $color-bonus-character-multiplier-3;
@@ -32,22 +25,8 @@
   colorBonusWordMultiplier3: $color-bonus-word-multiplier-3;
   colorBonusWordMultiplier4: $color-bonus-word-multiplier-4;
 
-  spacingXs: strip-unit($spacing-xs);
-  spacingS: strip-unit($spacing-s);
-  spacingM: strip-unit($spacing-m);
-  spacingL: strip-unit($spacing-l);
-  spacingXl: strip-unit($spacing-xl);
-
   transitionDuration: strip-unit($transition-duration);
   transitionDurationLong: strip-unit($transition-duration-long);
 
-  buttonIconSize: strip-unit($button-icon-size);
-  dictionaryHeight: strip-unit($dictionary-height);
-  dictionaryHeightMobile: strip-unit($dictionary-height-mobile);
-  logoHeight: strip-unit($logo-height);
-  logoHeightSmall: strip-unit($logo-height-small);
-  modalWidth: strip-unit($modal-width);
   resultsItemHeight: strip-unit($results-item-height);
-  solverColumnWidth: strip-unit($solver-column-width);
-  textInputHeight: strip-unit($text-input-height);
 }

package/src/styles/variables.module.scss.d.ts

@@ -0,0 +1,27 @@
+// Generated by scripts/generate-scss-types.ts - do not edit.
+declare const styles: {
+  readonly borderColorLight: string;
+  readonly borderWidth: string;
+  readonly breakpointL: string;
+  readonly breakpointM: string;
+  readonly breakpointS: string;
+  readonly breakpointXl: string;
+  readonly breakpointXs: string;
+  readonly colorBackground: string;
+  readonly colorBlueLight: string;
+  readonly colorBonusCharacterMultiplier2: string;
+  readonly colorBonusCharacterMultiplier3: string;
+  readonly colorBonusCharacterMultiplier4: string;
+  readonly colorBonusWordMultiplier2: string;
+  readonly colorBonusWordMultiplier3: string;
+  readonly colorBonusWordMultiplier4: string;
+  readonly colorGreenLight: string;
+  readonly colorRedLight: string;
+  readonly colorVioletLight: string;
+  readonly colorYellowLight: string;
+  readonly resultsItemHeight: string;
+  readonly transitionDuration: string;
+  readonly transitionDurationLong: string;
+};
+
+export default styles;