scrabble-solver 2.16.7 → 2.17.0

package/packages/scrabble-solver/src/solver-worker/client.ts

@@ -0,0 +1,106 @@
+import { type Locale, type ResultJson } from '@scrabble-solver/types';
+
+import { type SolveRequestPayload, type VerifyRequestPayload } from '@/types';
+
+import { type SolverWorkerRequest, type SolverWorkerResponse, type VerifyResult } from './messages';
+
+/**
+ * A worker that never answers - killed under memory pressure, or a message lost
+ * with it - must not hold the UI in a loading state with no server fallback.
+ */
+const REQUEST_TIMEOUT = 30 * 1000;
+
+interface PendingRequest {
+  resolve: (response: SolverWorkerResponse) => void;
+  timeout: ReturnType<typeof setTimeout>;
+}
+
+let worker: Worker | undefined;
+let nextId = 0;
+let latestSolveId = 0;
+let latestSolve: Promise<ResultJson[] | undefined> = Promise.resolve(undefined);
+const pending = new Map<number, PendingRequest>();
+
+export function solveLocally(payload: SolveRequestPayload): Promise<ResultJson[] | undefined> {
+  const id = ++nextId;
+  const solve = readSolveResponse(id, payload);
+  latestSolveId = id;
+  latestSolve = solve;
+  return solve;
+}
+
+export async function verifyLocally(payload: VerifyRequestPayload): Promise<VerifyResult | undefined> {
+  const response = await request({ id: ++nextId, type: 'verify', payload });
+  return response.outcome === 'answered' ? (response.data as VerifyResult) : undefined;
+}
+
+export function prefetchDictionary(locale: Locale): void {
+  getWorker()?.postMessage({ id: ++nextId, locale, type: 'prefetch' } satisfies SolverWorkerRequest);
+}
+
+async function readSolveResponse(id: number, payload: SolveRequestPayload): Promise<ResultJson[] | undefined> {
+  const response = await request({ id, type: 'solve', payload });
+
+  /**
+   * The worker skipped this solve for a newer one; answer with the newer result
+   * rather than an empty list a caller could render as "no moves found".
+   */
+  if (response.outcome === 'superseded' && id !== latestSolveId) {
+    return latestSolve;
+  }
+
+  return response.outcome === 'answered' ? (response.data as ResultJson[]) : undefined;
+}
+
+function request(message: SolverWorkerRequest): Promise<SolverWorkerResponse> {
+  const targetWorker = getWorker();
+
+  if (!targetWorker) {
+    return Promise.resolve({ id: message.id, outcome: 'unavailable' });
+  }
+
+  return new Promise((resolve) => {
+    const timeout = setTimeout(() => settle({ id: message.id, outcome: 'unavailable' }), REQUEST_TIMEOUT);
+    pending.set(message.id, { resolve, timeout });
+    targetWorker.postMessage(message);
+  });
+}
+
+function settle(response: SolverWorkerResponse): void {
+  const entry = pending.get(response.id);
+
+  if (!entry) {
+    return;
+  }
+
+  pending.delete(response.id);
+  clearTimeout(entry.timeout);
+  entry.resolve(response);
+}
+
+function getWorker(): Worker | undefined {
+  if (typeof Worker === 'undefined' || !('caches' in globalThis)) {
+    return undefined;
+  }
+
+  if (!worker) {
+    worker = new Worker(new URL('./index.worker.ts', import.meta.url));
+    worker.addEventListener('message', ({ data }: MessageEvent<SolverWorkerResponse>) => settle(data));
+    worker.addEventListener('error', handleWorkerFailure);
+  }
+
+  return worker;
+}
+
+/**
+ * Settles every in-flight request as locally unanswerable - callers fall back
+ * to the server - and discards the worker so the next call starts a fresh one.
+ */
+function handleWorkerFailure(): void {
+  for (const id of pending.keys()) {
+    settle({ id, outcome: 'unavailable' });
+  }
+
+  worker?.terminate();
+  worker = undefined;
+}

package/packages/scrabble-solver/src/solver-worker/dictionaries/constants.ts

@@ -0,0 +1,9 @@
+export const DICTIONARY_CACHE = 'dictionary-api-cache';
+
+export const REVALIDATED_AT_CACHE = 'dictionary-revalidated-at';
+
+export const DAY = 24 * 60 * 60 * 1000;
+
+// Staleness is handled by conditional revalidation; expiration only cleans up
+// dictionaries of locales the user no longer plays.
+export const DICTIONARY_CACHE_MAX_AGE = 30 * DAY;

package/packages/scrabble-solver/src/solver-worker/dictionaries/getDictionary.ts

@@ -0,0 +1,21 @@
+import { type Locale } from '@scrabble-solver/types';
+
+import { DICTIONARY_CACHE } from './constants';
+import { getDictionaryUrl } from './getDictionaryUrl';
+import { resetRevalidationThrottle } from './revalidateDictionary';
+
+export async function getDictionary(locale: Locale): Promise<Response | undefined> {
+  const cache = await caches.open(DICTIONARY_CACHE);
+  return cache.match(getDictionaryUrl(locale));
+}
+
+export async function deleteDictionary(locale: Locale): Promise<void> {
+  const cache = await caches.open(DICTIONARY_CACHE);
+  await cache.delete(getDictionaryUrl(locale));
+  /**
+   * Reset last: resetting first leaves a window in which a revalidation starts,
+   * reads the doomed entry's ETag, takes the 304 it answers with, and arms the
+   * throttle against a dictionary this call is about to delete.
+   */
+  await resetRevalidationThrottle(locale);
+}

package/packages/scrabble-solver/src/solver-worker/dictionaries/index.ts

@@ -0,0 +1,2 @@
+export { deleteDictionary, getDictionary } from './getDictionary';
+export { revalidateDictionary } from './revalidateDictionary';

package/packages/scrabble-solver/src/solver-worker/dictionaries/revalidateDictionary.test.ts

@@ -0,0 +1,199 @@
+import { Locale } from '@scrabble-solver/types';
+import { afterAll, beforeEach, describe, expect, it, mock } from 'bun:test';
+
+import { DICTIONARY_CACHE, REVALIDATED_AT_CACHE } from './constants';
+import type * as getDictionaryModule from './getDictionary';
+import { getDictionaryUrl } from './getDictionaryUrl';
+import type * as revalidateDictionaryModule from './revalidateDictionary';
+
+const HOUR = 60 * 60 * 1000;
+
+const fetchCalls: { cache: RequestCache | undefined; ifNoneMatch: string | undefined; url: string }[] = [];
+const updatedTimestamps: string[] = [];
+let respond: () => Promise<Response> = () => Promise.resolve(notModified());
+
+await mock.module('./expirationManager', () => ({
+  expirationManager: {
+    expireEntries: () => Promise.resolve(),
+    updateTimestamp: (url: string) => {
+      updatedTimestamps.push(url);
+      return Promise.resolve();
+    },
+  },
+}));
+
+const globals = { caches: globalThis.caches, fetch: globalThis.fetch };
+
+Object.assign(globalThis, {
+  caches: createCacheStorage(),
+  fetch: (url: string, { cache, headers }: RequestInit) => {
+    fetchCalls.push({ cache, ifNoneMatch: (headers as Record<string, string>)['If-None-Match'], url });
+    return respond();
+  },
+});
+
+afterAll(() => {
+  Object.assign(globalThis, globals);
+});
+
+const { resetRevalidationThrottle, revalidateDictionary }: typeof revalidateDictionaryModule =
+  await import('./revalidateDictionary');
+const { deleteDictionary }: typeof getDictionaryModule = await import('./getDictionary');
+
+describe('revalidateDictionary', () => {
+  beforeEach(() => {
+    fetchCalls.length = 0;
+    updatedTimestamps.length = 0;
+    respond = () => Promise.resolve(notModified());
+  });
+
+  /**
+   * `no-store` would look equivalent, but makes the browser send
+   * `Cache-Control: no-cache`, which Next.js answers with the whole body.
+   */
+  it('sends a conditional request the HTTP cache cannot answer', async () => {
+    const locale = await unthrottled(Locale.EN_US);
+    await cacheDictionary(locale, 'dictionary', '"v1"');
+    await revalidateDictionary(locale);
+    expect(fetchCalls).toEqual([{ cache: 'no-cache', ifNoneMatch: '"v1"', url: '/api/dictionary/en-US' }]);
+  });
+
+  it('keeps the cached body on 304', async () => {
+    const locale = await unthrottled(Locale.EN_GB);
+    await cacheDictionary(locale, 'dictionary', '"v1"');
+    await revalidateDictionary(locale);
+    expect(await readCachedDictionary(locale)).toBe('dictionary');
+    expect(updatedTimestamps).toEqual([getDictionaryUrl(locale)]);
+  });
+
+  it('replaces the cached body on 200', async () => {
+    const locale = await unthrottled(Locale.DE_DE);
+    await cacheDictionary(locale, 'old', '"v1"');
+    respond = () => Promise.resolve(new Response('new', { headers: { etag: '"v2"' } }));
+    await revalidateDictionary(locale);
+    expect(await readCachedDictionary(locale)).toBe('new');
+    expect(updatedTimestamps).toEqual([getDictionaryUrl(locale)]);
+  });
+
+  it('omits If-None-Match when nothing is cached', async () => {
+    const locale = await unthrottled(Locale.ES_ES);
+    respond = () => Promise.resolve(new Response('dictionary'));
+    await revalidateDictionary(locale);
+    expect(fetchCalls[0].ifNoneMatch).toBeUndefined();
+    expect(await readCachedDictionary(locale)).toBe('dictionary');
+  });
+
+  it('rejects a failed response without arming the throttle', async () => {
+    const locale = await unthrottled(Locale.FA_IR);
+    respond = () => Promise.resolve(new Response(null, { status: 503, statusText: 'Service Unavailable' }));
+    const failure = await revalidateDictionary(locale).catch((error: Error) => error.message);
+    expect(failure).toBe('HTTP 503: Service Unavailable');
+    respond = () => Promise.resolve(notModified());
+    await revalidateDictionary(locale);
+    expect(fetchCalls).toHaveLength(2);
+  });
+
+  it('revalidates at most once per interval', async () => {
+    const locale = await unthrottled(Locale.FR_FR);
+    await revalidateDictionary(locale);
+    await revalidateDictionary(locale);
+    expect(fetchCalls).toHaveLength(1);
+  });
+
+  it('shares one request between concurrent callers', async () => {
+    const locale = await unthrottled(Locale.EN_US);
+    await Promise.all([revalidateDictionary(locale), revalidateDictionary(locale), revalidateDictionary(locale)]);
+    expect(fetchCalls).toHaveLength(1);
+  });
+
+  it('persists the throttle, so a later page load can honour it', async () => {
+    const locale = await unthrottled(Locale.PL_PL);
+    await revalidateDictionary(locale);
+    expect(await readPersistedRevalidatedAt(locale)).toBeGreaterThan(Date.now() - HOUR);
+  });
+
+  /**
+   * This locale and the next are used nowhere else: the worker is created per
+   * page, so only a locale unseen in memory exercises a fresh page's read.
+   */
+  it('honours a throttle persisted by an earlier page load', async () => {
+    await persistRevalidatedAt(Locale.RO_RO, Date.now() - 1000);
+    await revalidateDictionary(Locale.RO_RO);
+    expect(fetchCalls).toHaveLength(0);
+  });
+
+  it('revalidates when a throttle persisted by an earlier page load has expired', async () => {
+    await persistRevalidatedAt(Locale.TR_TR, Date.now() - 2 * HOUR);
+    await revalidateDictionary(Locale.TR_TR);
+    expect(fetchCalls).toHaveLength(1);
+  });
+
+  it('lets the next access revalidate after the dictionary is deleted', async () => {
+    const locale = await unthrottled(Locale.DE_DE);
+    await revalidateDictionary(locale);
+    await revalidateDictionary(locale);
+    await deleteDictionary(locale);
+    await revalidateDictionary(locale);
+    expect(fetchCalls).toHaveLength(2);
+  });
+
+  it('does not arm the throttle when the dictionary is deleted mid-revalidation', async () => {
+    const locale = await unthrottled(Locale.EN_GB);
+    let release: (response: Response) => void = () => undefined;
+    respond = () => new Promise((resolve) => (release = resolve));
+    const revalidation = revalidateDictionary(locale);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await resetRevalidationThrottle(locale);
+    release(notModified());
+    await revalidation;
+    respond = () => Promise.resolve(notModified());
+    await revalidateDictionary(locale);
+    expect(fetchCalls).toHaveLength(2);
+  });
+});
+
+/** Throttle state outlives a test, so tests sharing a locale start it un-throttled. */
+async function unthrottled(locale: Locale): Promise<Locale> {
+  await resetRevalidationThrottle(locale);
+  return locale;
+}
+
+async function cacheDictionary(locale: Locale, body: string, etag: string): Promise<void> {
+  const cache = await caches.open(DICTIONARY_CACHE);
+  await cache.put(getDictionaryUrl(locale), new Response(body, { headers: { etag } }));
+}
+
+async function readCachedDictionary(locale: Locale): Promise<string | undefined> {
+  const cache = await caches.open(DICTIONARY_CACHE);
+  return (await cache.match(getDictionaryUrl(locale)))?.text();
+}
+
+async function persistRevalidatedAt(locale: Locale, timestamp: number): Promise<void> {
+  const cache = await caches.open(REVALIDATED_AT_CACHE);
+  await cache.put(getDictionaryUrl(locale), new Response(String(timestamp)));
+}
+
+async function readPersistedRevalidatedAt(locale: Locale): Promise<number> {
+  const cache = await caches.open(REVALIDATED_AT_CACHE);
+  return Number(await (await cache.match(getDictionaryUrl(locale)))?.text());
+}
+
+function notModified(): Response {
+  return new Response(null, { status: 304 });
+}
+
+function createCacheStorage(): CacheStorage {
+  const entries = new Map<string, Response>();
+
+  return {
+    open: (name: string) =>
+      Promise.resolve({
+        delete: (url: string) => Promise.resolve(entries.delete(`${name} ${url}`)),
+        match: (url: string) => Promise.resolve(entries.get(`${name} ${url}`)?.clone()),
+        put: (url: string, response: Response) => {
+          entries.set(`${name} ${url}`, response);
+          return Promise.resolve();
+        },
+      }),
+  } as unknown as CacheStorage;
+}

package/packages/scrabble-solver/src/solver-worker/dictionaries/revalidateDictionary.ts

@@ -0,0 +1,86 @@
+import { type Locale } from '@scrabble-solver/types';
+
+import { DICTIONARY_CACHE } from './constants';
+import { expirationManager } from './expirationManager';
+import { getDictionaryUrl } from './getDictionaryUrl';
+import { clearRevalidatedAt, readRevalidatedAt, writeRevalidatedAt } from './revalidatedAt';
+
+const REVALIDATION_INTERVAL = 60 * 60 * 1000;
+
+const requests: Partial<Record<Locale, Promise<void> | undefined>> = {};
+const resetWhileRevalidating = new Set<Locale>();
+
+export function revalidateDictionary(locale: Locale): Promise<void> {
+  const inFlight = requests[locale];
+
+  if (inFlight) {
+    return inFlight;
+  }
+
+  // Registered before the first await, so concurrent callers share this request.
+  const request = revalidateWhenStale(locale).finally(() => {
+    requests[locale] = undefined;
+  });
+
+  requests[locale] = request;
+  return request;
+}
+
+/**
+ * Lets the next access revalidate immediately - used when the cached dictionary
+ * is deleted, so its replacement is not stuck behind the throttle.
+ * A revalidation already in flight when this runs saw the deleted entry, so it
+ * must not arm the throttle when it finishes.
+ * Both in-memory guards are raised before the first await, so a caller that
+ * runs this straight after deleting the entry leaves no gap for a revalidation
+ * to slip into.
+ */
+export async function resetRevalidationThrottle(locale: Locale): Promise<void> {
+  resetWhileRevalidating.add(locale);
+  await clearRevalidatedAt(locale);
+}
+
+async function revalidateWhenStale(locale: Locale): Promise<void> {
+  if (Date.now() - (await readRevalidatedAt(locale)) < REVALIDATION_INTERVAL) {
+    return;
+  }
+
+  resetWhileRevalidating.delete(locale);
+  await revalidate(locale);
+
+  if (!resetWhileRevalidating.has(locale)) {
+    await writeRevalidatedAt(locale, Date.now());
+  }
+}
+
+/**
+ * `no-cache` revalidates against the server without letting the HTTP cache
+ * answer, while still allowing a 304 that keeps the multi-megabyte cached body
+ * untouched; only a real 200 rewrites it. `no-store` would look equivalent but
+ * makes the browser send `Cache-Control: no-cache`, which Next.js reads as an
+ * unconditional request and answers with the whole body every time.
+ */
+async function revalidate(locale: Locale): Promise<void> {
+  await expirationManager.expireEntries();
+
+  const url = getDictionaryUrl(locale);
+  const cache = await caches.open(DICTIONARY_CACHE);
+  const cached = await cache.match(url);
+  const etag = cached?.headers.get('etag');
+  const response = await fetch(url, {
+    cache: 'no-cache',
+    headers: etag ? { 'If-None-Match': etag } : {},
+  });
+
+  if (response.status === 304) {
+    await expirationManager.updateTimestamp(url);
+    return;
+  }
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+  }
+
+  await cache.put(url, response);
+  await expirationManager.updateTimestamp(url);
+}

package/packages/scrabble-solver/src/solver-worker/dictionaries/revalidatedAt.ts

@@ -0,0 +1,43 @@
+import { type Locale } from '@scrabble-solver/types';
+
+import { REVALIDATED_AT_CACHE } from './constants';
+import { getDictionaryUrl } from './getDictionaryUrl';
+
+const timestamps: Partial<Record<Locale, number>> = {};
+
+/**
+ * A dedicated worker is created per page, so a timestamp kept only in memory
+ * would let every navigation revalidate again. The Cache API is the only
+ * storage a worker shares with other tabs, so the throttle lives there and is
+ * read at most once per locale per worker.
+ */
+export async function readRevalidatedAt(locale: Locale): Promise<number> {
+  const known = timestamps[locale];
+
+  if (typeof known !== 'undefined') {
+    return known;
+  }
+
+  const persisted = await readPersistedRevalidatedAt(locale);
+  // A reset that landed while reading wins over the value it invalidated.
+  return (timestamps[locale] ??= persisted);
+}
+
+export async function writeRevalidatedAt(locale: Locale, timestamp: number): Promise<void> {
+  timestamps[locale] = timestamp;
+  const cache = await caches.open(REVALIDATED_AT_CACHE);
+  await cache.put(getDictionaryUrl(locale), new Response(String(timestamp)));
+}
+
+export async function clearRevalidatedAt(locale: Locale): Promise<void> {
+  timestamps[locale] = 0;
+  const cache = await caches.open(REVALIDATED_AT_CACHE);
+  await cache.delete(getDictionaryUrl(locale));
+}
+
+async function readPersistedRevalidatedAt(locale: Locale): Promise<number> {
+  const cache = await caches.open(REVALIDATED_AT_CACHE);
+  const response = await cache.match(getDictionaryUrl(locale));
+  const timestamp = Number(await response?.text());
+  return Number.isFinite(timestamp) ? timestamp : 0;
+}

package/packages/scrabble-solver/src/solver-worker/getGaddag.test.ts

@@ -0,0 +1,109 @@
+import { Gaddag } from '@kamilmielnik/gaddag';
+import { Locale } from '@scrabble-solver/types';
+import { describe, expect, it, mock } from 'bun:test';
+
+import type * as getGaddagModule from './getGaddag';
+
+let dictionary: Response | undefined;
+const deletedLocales: Locale[] = [];
+
+await mock.module('./dictionaries', () => ({
+  deleteDictionary: (locale: Locale) => {
+    deletedLocales.push(locale);
+    return Promise.resolve();
+  },
+  getDictionary: () => Promise.resolve(dictionary),
+}));
+
+const { getGaddag }: typeof getGaddagModule = await import('./getGaddag');
+
+describe('getGaddag', () => {
+  it('returns undefined when there is no cached dictionary', async () => {
+    dictionary = undefined;
+    expect(await getGaddag(Locale.EN_US)).toBeUndefined();
+  });
+
+  it('deserializes a cached dictionary', async () => {
+    dictionary = createDictionary(['scrabble', 'solver']);
+    const gaddag = await getGaddag(Locale.EN_US);
+
+    expect(gaddag?.has('scrabble')).toBe(true);
+    expect(gaddag?.has('trie')).toBe(false);
+  });
+
+  it('deletes a dictionary cached by an app version with an incompatible format', async () => {
+    dictionary = new Response('serialized trie from a previous app version');
+
+    expect(await getGaddag(Locale.PL_PL)).toBeUndefined();
+    expect(deletedLocales).toContain(Locale.PL_PL);
+  });
+
+  it('deletes a corrupted dictionary', async () => {
+    dictionary = new Response(Gaddag.fromArray(['scrabble']).serialize().subarray(0, 10));
+
+    expect(await getGaddag(Locale.FA_IR)).toBeUndefined();
+    expect(deletedLocales).toContain(Locale.FA_IR);
+  });
+
+  it('reuses the deserialized dictionary while the cached response is unchanged', async () => {
+    dictionary = createDictionary(['scrabble'], { etag: '"v1"' });
+    const first = await getGaddag(Locale.EN_GB);
+    dictionary = createDictionary(['scrabble'], { etag: '"v1"' });
+    const second = await getGaddag(Locale.EN_GB);
+
+    expect(first?.has('scrabble')).toBe(true);
+    expect(second).toBe(first);
+  });
+
+  it('reuses the deserialized dictionary when a revalidation only refreshes the Date header', async () => {
+    dictionary = createDictionary(['scrabble'], { date: 'Thu, 06 Aug 2026 00:00:00 GMT', etag: '"v1"' });
+    const first = await getGaddag(Locale.FR_FR);
+    dictionary = createDictionary(['scrabble'], { date: 'Fri, 07 Aug 2026 00:00:00 GMT', etag: '"v1"' });
+    const second = await getGaddag(Locale.FR_FR);
+
+    expect(first?.has('scrabble')).toBe(true);
+    expect(second).toBe(first);
+  });
+
+  it('picks up a dictionary another tab wrote into the shared cache', async () => {
+    dictionary = createDictionary(['scrabble'], { etag: '"v1"' });
+    const first = await getGaddag(Locale.TR_TR);
+    dictionary = createDictionary(['solver'], { etag: '"v2"' });
+    const second = await getGaddag(Locale.TR_TR);
+
+    expect(first?.has('scrabble')).toBe(true);
+    expect(second).not.toBe(first);
+    expect(second?.has('solver')).toBe(true);
+  });
+
+  it('falls back to the Date header for responses without an ETag', async () => {
+    dictionary = createDictionary(['scrabble'], { date: 'Thu, 06 Aug 2026 00:00:00 GMT' });
+    const first = await getGaddag(Locale.DE_DE);
+    dictionary = createDictionary(['scrabble'], { date: 'Thu, 06 Aug 2026 00:00:00 GMT' });
+    const second = await getGaddag(Locale.DE_DE);
+    dictionary = createDictionary(['scrabble'], { date: 'Fri, 07 Aug 2026 00:00:00 GMT' });
+    const third = await getGaddag(Locale.DE_DE);
+
+    expect(first?.has('scrabble')).toBe(true);
+    expect(second).toBe(first);
+    expect(third).not.toBe(first);
+    expect(third?.has('scrabble')).toBe(true);
+  });
+
+  it('memoizes each locale independently', async () => {
+    dictionary = createDictionary(['scrabble'], { etag: '"es"' });
+    const spanish = await getGaddag(Locale.ES_ES);
+    dictionary = createDictionary(['solver'], { etag: '"ro"' });
+    const romanian = await getGaddag(Locale.RO_RO);
+    dictionary = createDictionary(['scrabble'], { etag: '"es"' });
+    const spanishAgain = await getGaddag(Locale.ES_ES);
+
+    expect(spanish?.has('scrabble')).toBe(true);
+    expect(romanian?.has('solver')).toBe(true);
+    expect(spanishAgain).toBe(spanish);
+  });
+});
+
+function createDictionary(words: string[], headers: Record<string, string> = {}): Response {
+  return new Response(Gaddag.fromArray(words).serialize(), { headers });
+}

package/packages/scrabble-solver/src/solver-worker/getGaddag.ts

@@ -0,0 +1,62 @@
+import { Gaddag } from '@kamilmielnik/gaddag';
+import { type Locale } from '@scrabble-solver/types';
+
+import { deleteDictionary, getDictionary } from './dictionaries';
+
+interface DeserializedDictionary {
+  gaddag: Gaddag;
+  version: string;
+}
+
+const deserializedDictionaries: Partial<Record<Locale, DeserializedDictionary>> = {};
+
+/**
+ * Returns undefined when there is no cached dictionary or when the cached
+ * dictionary cannot be deserialized (it was downloaded by an app version with
+ * an incompatible format). An undeserializable entry is deleted before
+ * returning, so the revalidation the caller triggers next downloads a fresh
+ * dictionary instead of getting a 304 for the broken bytes.
+ */
+export async function getGaddag(locale: Locale): Promise<Gaddag | undefined> {
+  const response = await getDictionary(locale);
+
+  if (typeof response === 'undefined') {
+    return undefined;
+  }
+
+  const version = readVersion(response);
+  const deserialized = deserializedDictionaries[locale];
+
+  if (deserialized && deserialized.version === version) {
+    return deserialized.gaddag;
+  }
+
+  try {
+    const gaddag = Gaddag.deserialize(new Uint8Array(await response.arrayBuffer()));
+
+    if (typeof version !== 'undefined') {
+      deserializedDictionaries[locale] = { gaddag, version };
+    }
+
+    return gaddag;
+  } catch {
+    delete deserializedDictionaries[locale];
+    await deleteDictionary(locale);
+    return undefined;
+  }
+}
+
+/**
+ * Read from the cached response rather than tracked in memory, so a dictionary
+ * another tab downloaded into the shared cache is picked up here too.
+ */
+function readVersion(response: Response): string | undefined {
+  const etag = response.headers.get('etag');
+
+  if (etag !== null) {
+    return etag;
+  }
+
+  const parts = ['date', 'content-length'].map((name) => response.headers.get(name) ?? '');
+  return parts.every((part) => part === '') ? undefined : parts.join('|');
+}

package/packages/scrabble-solver/src/solver-worker/index.ts

@@ -0,0 +1 @@
+export { prefetchDictionary, solveLocally, verifyLocally } from './client';