fix(SCOPONE-0008): refresh lag fix docs

docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Architecture
 
-> Last Updated: 2026-04-02T18:12:18.000Z
+> Last Updated: 2026-04-02T19:05:00.000Z
 
 ## Overview
 
@@ -27,7 +27,10 @@ scopone-phaser/
 |  |  |- types.ts
 |  |  |- engine.ts
 |  |  |- card-tracker.ts
-|  |  `- ai.ts
+|  |  |- ai.ts
+|  |  |- ai-worker-protocol.ts
+|  |  |- ai-worker-client.ts
+|  |  `- ai.worker.ts
 |  `- scenes/
 |     |- BootScene.ts
 |     |- MenuScene.ts
@@ -64,8 +67,9 @@ Observed architectural patterns in the current codebase:
 | Scene-based flow | `BootScene -> MenuScene -> GameScene` via Phaser scene registration |
 | Functional core / imperative shell | `src/game/` stays free of Phaser imports, while `src/scenes/` owns rendering and input |
 | Clone-before-mutate state transitions | `applyMove()` clones `GameState` before applying move effects |
+| Worker offload with fallback | `AIWorkerClient` runs heavy AI inside `ai.worker.ts` and falls back to in-thread `chooseMove()` if worker startup or messaging fails |
 | Determinization search | Master AI samples hidden hands before alpha-beta evaluation |
-| Callback-driven progress reporting | `chooseMove()` reports `AIDecisionProgress` to `GameScene` for the think bar |
+| Message-based progress reporting | Worker and main thread exchange typed request/result/progress messages through `ai-worker-protocol.ts` |
 
 ## Key Components
 
@@ -94,7 +98,7 @@ Observed architectural patterns in the current codebase:
 - Computes unseen cards from `played + myHand + table`.
 - Supplies probability helpers used by the AI for value-based inference.
 
-### `src/game/ai.ts` (1210 lines)
+### `src/game/ai.ts`
 
 - Exposes `chooseMove()` as an async entry point.
 - Implements three difficulty levels:
@@ -103,22 +107,38 @@ Observed architectural patterns in the current codebase:
     - `master`: determinization plus alpha-beta search with dynamic time budgets, batching, and progress callbacks.
 - Uses `yieldToBrowser()` between master-search batches so Phaser can repaint the think bar.
 
-### `src/scenes/BootScene.ts` (47 lines)
+### `src/game/ai-worker-protocol.ts`
+
+- Defines the typed message contract between the main thread and the worker.
+- Serializes requests around `GameState`, `Difficulty`, `PlayerIndex`, tracker snapshots, progress, results, and worker-safe errors.
+
+### `src/game/ai-worker-client.ts`
+
+- Wraps the worker lifecycle behind the same `chooseMove()` API the scene needs.
+- Creates module workers with `new Worker(new URL('./ai.worker.ts', import.meta.url), { type: 'module' })`.
+- Streams progress callbacks back into `GameScene` and degrades to direct `chooseMove()` execution when workers are unavailable.
+
+### `src/game/ai.worker.ts`
+
+- Rehydrates `CardTracker` from a snapshot, delegates move selection to `chooseMove()`, and posts progress/result/error messages back to the scene thread.
+- Keeps the expensive `master` search off the main rendering thread when worker support is available.
+
+### `src/scenes/BootScene.ts`
 
 - Loads the card atlas and card-back texture.
 - Shows a simple progress bar and transitions into the menu.
 
-### `src/scenes/MenuScene.ts` (103 lines)
+### `src/scenes/MenuScene.ts`
 
 - Renders the title screen and rules summary.
 - Lets the player choose `beginner`, `advanced`, or `master` difficulty.
 - Starts `GameScene` with the selected difficulty in scene data.
 
-### `src/scenes/GameScene.ts` (1446 lines)
+### `src/scenes/GameScene.ts`
 
 - Owns the match loop, HUD, think bar, card interaction, animation, FX, audio, and round transitions.
 - Uses `CardTracker` to record played and captured cards after each move.
-- Bridges async AI progress into a visible top-of-screen think bar.
+- Instantiates `AIWorkerClient`, bridges async AI progress into a visible top-of-screen think bar, and disposes worker resources on scene shutdown.
 - Handles end-of-round overlays and full-match restart flow.
 
 ### `android/app/src/main/java/com/phaser/scopa/MainActivity.java`
@@ -166,6 +186,10 @@ main.ts
     -> GameScene
              -> engine.ts
              -> ai.ts
+           -> ai-worker-client.ts
+               -> ai-worker-protocol.ts
+               -> ai.worker.ts
+                   -> ai.ts
              -> card-tracker.ts
              -> types.ts
 ```
@@ -184,10 +208,12 @@ Dependencies are one-directional at the application level:
 4. `GameScene.create()` initializes a new `CardTracker`, creates the initial `GameState`, and animates the opening deal.
 5. On each turn:
      - Human turns use click-driven selection and capture highlighting.
-     - AI turns call `chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
-6. `chooseMove()` either returns immediately for heuristic tiers or performs batched master search while reporting `AIDecisionProgress`.
-7. `GameScene.executeMove()` applies the move, updates the tracker, animates the result, refreshes the HUD, and advances the round.
-8. When all hands are empty, `engine.ts` finalizes scoring and `GameScene` displays the round summary or final match screen.
+    - AI turns call `AIWorkerClient.chooseMove(state, playerIdx, difficulty, tracker, onProgress)`.
+6. `AIWorkerClient` posts a typed request into `ai.worker.ts`; if worker setup fails, it falls back to in-thread `chooseMove()`.
+7. `chooseMove()` either returns immediately for heuristic tiers or performs batched master search while reporting `AIDecisionProgress`.
+8. Worker progress messages drive `GameScene.updateThinkBar()` until a result is posted back.
+9. `GameScene.executeMove()` applies the move, updates the tracker, animates the result, refreshes the HUD, and advances the round.
+10. When all hands are empty, `engine.ts` finalizes scoring and `GameScene` displays the round summary or final match screen.
 
 ## Build System