scopone/docs/FINDINGS.md

# Findings

> Last Updated: 2026-04-10T20:33:00.000Z

## Summary

Documentation refresh for the current repository state. `docs/ARCHITECTURE.md` and `docs/FINDINGS.md` were updated to remove stale workflow-specific notes and now reflect the live source tree directly. `docs/CODE_STYLE.md` remains valid without changes.

## Codebase Observations

- Primary gameplay code currently lives in 17 TypeScript source files under `src/`; the Android wrapper adds 3 Java files under `android/app/src/`.
- The project is structurally split between framework-free gameplay modules in `src/game/` and Phaser scene code in `src/scenes/`.
- `src/scenes/GameScene.ts` and `src/game/ai.ts` remain the two largest concentrations of application logic.
- A dedicated audio preference seam exists in `src/game/preferences.ts`, and it is consumed from both `MenuScene` and `SettingsScene`.
- `main.ts` imports and registers `SettingsScene` directly in the Phaser scene list.
- The AI transport layer is a stable three-file path: `ai-worker-protocol.ts`, `ai-worker-client.ts`, and `ai.worker.ts`.
- The AI exposes three difficulty levels: `beginner`, `advanced`, and `master`.
- `advanced` and `master` both use `CardTracker` to reason about unseen cards without directly reading hidden hands.
- The base `master` search profile is `4300 ms / 8 samples / depth 5 / batch 2`, with tighter endgame branches down to `3200 ms / 4 samples / exact remaining depth / batch 1` when 4 cards remain.
- `GameScene` consumes AI progress callbacks to update an on-screen think bar while a worker request is running.
- `GameScene` enforces `AI_MIN_THINK_MS = 1000` and `MOVE_OUTCOME_STATUS_MS = 2000` through timer-backed scene logic.
- `AIWorkerClient` fails over pending work to in-thread `chooseMove()` if worker creation, posting, or deserialization fails.
- `MenuScene` includes a compact-viewport layout path driven by calculated panel bounds and camera zoom.
- The AI benchmark harness lives in source under `src/game/ai-benchmark.ts` and `src/game/ai-benchmark-fixtures.ts`, and `package.json` exposes it as `npm run benchmark:ai-quality`.
- The current benchmark contract is iteration 5: 13 fixed fixtures, 6 critical concepts, and 48 self-play matches.
- The Android wrapper targets SDK 36 with `minSdkVersion` 24 and applies immersive mode from the native activity.
- Audio remains procedural via Web Audio; no dedicated audio asset pipeline was discovered in the source tree.
- No ESLint or Prettier configuration was discovered.
- No top-level `tests/` directory was discovered during analysis.

## Potential Improvement Areas

- `GameScene.ts` still centralizes layout, turn flow, HUD updates, effects, audio, status messaging, and AI orchestration in one scene class.
- `ai.ts` still combines heuristic tiers, inference helpers, determinization, move ordering, and alpha-beta evaluation in one module.
- `MenuScene.ts` carries responsive layout and decorative rendering logic in the same scene that handles navigation and difficulty selection.
- Worker transport is isolated cleanly, but progress rendering and fallback behavior remain coupled to scene-level UI concerns.
- A 3.2 to 4.3 second master search window may still be noticeable on slower mobile devices even with yielding and minimum-think pacing already in place.
- No dedicated automated rules test suite was discovered beyond type checking and the AI benchmark harness.
- Formatting and style are enforced socially rather than by automated linting or formatting tools.

## Current Rule / Implementation Notes

### Capture behavior in `engine.ts`

- Direct-match capture has priority over subset-sum capture.
- When multiple direct matches exist, `findCaptures()` returns one single-card option per matching card.
- Subset-sum captures are considered only when no direct match exists.
- `applyMove()` defaults to the first legal capture if no explicit capture choice is supplied.
- Scopa is awarded only when a capture clears the table before the final play of the round.

### AI implementation snapshot

- `beginner` uses a simpler heuristic with noise to remain beatable.
- `advanced` adds race awareness, anti-scopa logic, partner setup, denari pressure, and tracker-based probability estimates.
- `master` orders legal moves with a quick evaluator, samples hidden hands, and scores them with alpha-beta search under a dynamic deadline.
- Progress is reported through `AIDecisionProgress` so the scene can keep the think bar responsive.
- `CardTracker` remains the inference surface for unseen-card reasoning across higher difficulties.

### Worker execution snapshot

- `GameScene` creates `AIWorkerClient` during `create()` and disposes it on both `shutdown` and `destroy`.
- `AIWorkerClient` serializes `CardTracker` state through `toSnapshot()` instead of attempting to transfer the class instance.
- `ai.worker.ts` rebuilds tracker state with `CardTracker.fromSnapshot()` before calling `chooseMove()`.
- Progress, result, and serialized error payloads all travel through `ai-worker-protocol.ts`.
- If worker execution becomes unavailable, pending requests are rerun with the in-thread AI path rather than being dropped.

### Scene / UI implementation snapshot

- `BootScene` loads atlas assets and presents a simple loading bar.
- `main.ts` registers `BootScene`, `MenuScene`, `GameScene`, and `SettingsScene` directly in the Phaser game config.
- `MenuScene` exposes both difficulty selection and a dedicated entry point into `SettingsScene`, with a separate compact-layout branch for smaller viewports.
- `SettingsScene` persists music and effects toggles immediately through `saveAudioPreferences()`.
- `GameScene` reads normalized audio preferences from scene data or persisted storage before match start.
- `GameScene` tracks played and captured cards in `CardTracker` as the round evolves.
- The scene owns score HUD rendering, player labels, status text, think-bar rendering, procedural audio, and particle effects.
- Round-end and match-end flows remain managed inside the scene instead of separate overlay components.

### Benchmark snapshot

- `ai-benchmark.ts` uses a simulated timing source for fixture and self-play evaluation rather than only wall-clock timing.
- The benchmark summary records per-seed aggregates, dual-loss seeds, and a regression watchlist intersection.
- The harness remains source-local under `src/`, so it is covered by the default TypeScript include set.

## Research Performed

### Web Research: Scopone Scientifico Rules (2026-03-31)

**Sources**: Wikipedia (*Scopa* article, Scopone section), Pagat.com (*Scopone* page by John McLeod)

#### Core Rules (Scopone Scientifico variant)
- 4 players, 2 fixed teams of 2 (sit opposite): Team A = players 0+2, Team B = players 1+3.
- 40-card Napoletane deck: 4 suits (`bastoni`, `coppe`, `denara`, `spade`), values 1-10.
- All 40 cards are dealt at the start of the round; the table begins empty.
- Turns advance in the implementation as `0 -> 1 -> 2 -> 3`.

#### Capture Rules
1. If the played card matches one or more table cards by value, a direct match must be taken.
2. If multiple direct matches exist, one matching table card is chosen.
3. If no direct match exists, a subset of table cards may be captured when their values sum to the played value.
4. A direct match has priority over any possible sum capture.
5. Scopa awards a point only when the table is cleared before the final play of the round.

#### Scoring
| Category | Rule |
|----------|------|
| Carte | Majority of captured cards |
| Denari | Majority of `denara` suit cards |
| Settebello | Team that captures the 7 of `denara` |
| Primiera | Highest best-of-each-suit prime value |
| Scope | One point per scopa |

#### Primiera values used in code
| Card value | Primiera value |
|------------|----------------|
| 7 | 21 |
| 6 | 18 |
| 1 | 16 |
| 5 | 15 |
| 4 | 14 |
| 3 | 13 |
| 2 | 12 |
| 8, 9, 10 | 10 |

### SCOPONE-0008: AI progress rendering notes (2026-04-02)

- The current implementation does not use Phaser `TimerEvent` progress helpers.
- Instead, `chooseMove()` emits its own normalized progress payload through `AIDecisionProgress`.
- `GameScene.updateThinkBar()` renders remaining time from that callback.
- The yielding behavior in the master search path is necessary so the browser can repaint while search batches continue.

### SCOPONE-0009: Phaser scene lifecycle notes (2026-04-08)

- Source: Context7 `/websites/phaser_io_api-documentation`, query `Phaser 3.87 Scene lifecycle create restart shutdown destroy event listeners scene restart preserving external state`.
- Phaser dispatches `shutdown` when a scene stops being active but may be re-used later; resource cleanup that should also cover final teardown can additionally listen to `destroy`.
- The current `GameScene` pattern of registering one-shot shutdown and destroy handlers is aligned with Phaser guidance for worker disposal and UI cleanup.
- Dealer rotation and next-round state changes can stay inside the existing in-scene orchestration without requiring a different Phaser lifecycle primitive.

### SCOPONE-0010: UI, settings, and benchmark refresh notes (2026-04-09)

- `src/game/preferences.ts` is the authoritative audio preference seam. It normalizes stored values and shields scenes from malformed storage state.
- `src/scenes/MenuScene.ts` reads persisted audio preferences and exposes a dedicated settings entry point.
- `src/scenes/SettingsScene.ts` exists as a real scene and persists music and effects toggles independently through `saveAudioPreferences()`.
- `src/scenes/GameScene.ts` contains the current pacing and status behavior: `AI_MIN_THINK_MS = 1000`, `MOVE_OUTCOME_STATUS_MS = 2000`, timer-backed status updates, and shutdown cleanup.
- `src/game/ai-benchmark.ts` enforces an iteration 5 contract with simulated timing, cross-seed aggregation, dual-loss reporting, and a regression watchlist intersection.
- `src/main.ts` imports and registers `SettingsScene` directly.

### SCOPONE-0011: AI opening, render config, and HUD layout notes (2026-04-10)

- Source: Context7 `/websites/phaser_io_api-documentation`, query `Phaser 3.87 game config antialias antialiasGL roundPixels pixelArt text resolution sharp text image smoothing camera round pixels texture filtering`.
- Phaser 3.87 render config keeps `antialias` and `antialiasGL` enabled by default, while `pixelArt: true` would forcibly disable antialiasing and enable `roundPixels`; `roundPixels` also snaps texture-based objects to integer positions.
- `src/main.ts` currently relies on Phaser defaults and does not declare an explicit `render` block, so card filtering behavior is not pinned in project code.
- `src/scenes/MenuScene.ts` and `src/scenes/SettingsScene.ts` already use `resolution: 2` text styles broadly. `src/scenes/GameScene.ts` uses `resolution: 2` in score-bar and some label text, but `buildStatusBar()` and several large overlay texts (`SCOPA!`, `7♦`, match-end copy) omit it.
- `src/scenes/GameScene.ts` currently drives card pacing with `PLAYED_CARD_TRAVEL_MS = 400`, `CAPTURE_COLLAPSE_MS = 480`, `NON_CAPTURE_TABLE_TWEEN_MS = 560`, and separate hand/table relayout tweens at `160 ms`.
- `src/scenes/GameScene.ts` places player names with `buildPlayerLabels()` at depth `2`; deal/gameplay cards render at depths `5-15`, and status/dialog overlays render at depths `9-50`, so names can be obscured by both cards and bottom-center status UI.
- `src/game/ai.ts` already concentrates opening-role and duplicate-rank logic in `scoreDumpAdv()`, `scoreCaptureAdv()`, `summarizeMoveTactics()`, `scoreControlOverrideCandidate()`, and `findStrategicControlOverride()`.
- `src/game/ai.ts` calls `findStrategicControlOverride()` in the master path before determinized search, so first-player opening and safe-scopa heuristics must be aligned across both advanced scoring and master root selection.
- `src/game/ai-benchmark-fixtures.ts` currently includes 13 fixtures and 6 critical concepts; it has coverage for `full-table-scopa`, `anti-scopa-safe-dump`, and `only-safe-release`, but no fixture isolates the new "safe scopa when there is no repercussion" rule or the new first-hand duplicate-rank opening preference on an empty/unknown table.