Merge dev → main (automated)

.ralph/event.pending

@@ -0,0 +1,6 @@
+{
+  "event_type": "pi_started",
+  "timestamp": "2026-06-14T22:46:53.758097+00:00",
+  "work_item_ids": [],
+  "cmd": "pi -p --session-id ralph-no-target-implementation-ae302828 --mode json --model Proxy/qwen3 'implement-single CG-0MQBOK2SQ0067ZBP\nComplete only this work item.\nContinue until the work item is completed, but do not merge.\nDo not ask the producer questions or pause for interactive input.\nIf you cannot continue safely without explicit producer input, stop and return a structured no_safe_path response with the missing decision.\nIMPORTANT: Use the existing feature branch '\"'\"'wl-CG-0MQ6IEM9F001JTQD-phase-3-port-high-risk-games-to-shared-handview-pi'\"'\"' for all commits. Run '\"'\"'git checkout wl-CG-0MQ6IEM9F001JTQD-phase-3-port-high-risk-games-to-shared-handview-pi'\"'\"' if not already on this branch. Do NOT create a new branch.\nWhen creating commit messages, include a '\"'\"'Related-Work: <child-id>'\"'\"' trailer where <child-id> is '\"'\"'CG-0MQBOK2SQ0067ZBP'\"'\"'. Example format:\n  CG-0MQBOK2SQ0067ZBP: <concise summary of changes>\n\n  Related-Work: CG-0MQBOK2SQ0067ZBP'"
+}

docs/DEVELOPER.md

@@ -197,6 +197,13 @@ This runs `scripts/tf-generate-synths.sh` and writes generated outputs under `bu
 
 See `docs/the-build/audio.md` for full details (module shape, mapping, runtime wiring, CI guidance).
 
+### SFX Key Naming Convention
+
+All sound effects use the `sfx-` prefix with no game identifier. Common cross-game
+keys are defined in `COMMON_SFX_KEYS` (exported from `src/core-engine/SoundManager.ts`).
+Audio assets are organized in `public/assets/audio/<game>/` with a fallback to
+`public/assets/audio/default/`. See `docs/SFX_CONVENTION.md` for the full convention.
+
 ## Project Structure
 
 ```
@@ -526,6 +533,22 @@ Screenshots are written as `turn-000.png`, `turn-001.png`, etc. in the output di
 4. The scene reconstructs visual state from the snapshot and emits a `state-settled` event when rendering is complete
 5. The tool captures a screenshot of the canvas after each `state-settled` event
 
+### Contact Sheet
+
+After a replay completes, a contact sheet image is automatically generated showing all per-turn screenshots arranged in a grid. The contact sheet is written to `contact-sheet.png` in the output directory.
+
+- Thumbnails are 225x175px arranged in 4 columns
+- Each thumbnail is labeled with its turn number
+- Generated using `sharp` (MIT-licensed, already a dependency)
+- The contact sheet path is included in `replay-summary.json` as `contactSheetPath`
+
+### In-Game Transcript Export Button
+
+During gameplay, an **Export Transcript** button appears on the end-of-round results screen, allowing you to download the current game transcript as a JSON file directly from the browser.
+
+- **End-of-round screen:** After the game ends, click `[ Export Transcript ]` to download the transcript as `golf-transcript-<timestamp>.json`
+- **Error-triggered export:** If an unhandled JavaScript error occurs during gameplay, an overlay appears with an `[ Export Transcript ]` button so the transcript can be saved for debugging before reloading
+
 ### Replay Adapters
 
 Each game has a `ReplayAdapter` implementation in `scripts/adapters/` that bridges the replay tool to the game's scene:
@@ -550,6 +573,76 @@ Adapters are registered in `scripts/adapters/index.ts`. Registration order matte
 4. Ensure the game scene implements `loadBoardState()` and emits `state-settled` events
 5. Test with: `npm run replay -- tests/fixtures/transcripts/<game>/fixture-game.json`
 
+## Engine Event System
+
+The core engine provides a typed event system for turn lifecycle events. It consists of two parts:
+
+- **`GameEventEmitter`** (`src/core-engine/GameEventEmitter.ts`) — A type-safe event emitter that works in both Node.js and browser environments. Events are defined with typed payloads.
+- **`PhaserEventBridge`** (`src/core-engine/PhaserEventBridge.ts`) — Bridges `GameEventEmitter` events to Phaser's scene event system and vice versa, allowing Phaser-based consumers (scenes, UI components) to subscribe to engine events using Phaser's native `scene.events`.
+
+### Event Types
+
+| Event | Payload | Fires When |
+|-------|---------|------------|
+| `turn-started` | `{ turnNumber: number, playerIndex: number, phase: string }` | A player's turn begins |
+| `turn-completed` | `{ turnNumber: number, playerIndex: number }` | A move is applied and recorded |
+| `animation-complete` | `{ turnNumber: number }` | All tween animations for a turn finish |
+| `state-settled` | `{ turnNumber: number, phase: string }` | The board is visually stable and safe to screenshot |
+| `game-ended` | `{ finalTurnNumber: number, winnerIndex: number, reason: string }` | The game ends after scoring |
+| `resume-replay` | (none) | Signals the replay tool to resume after takeover |
+
+### Subscribing to Events
+
+```typescript
+import { GameEventEmitter } from '@core-engine';
+
+const emitter = new GameEventEmitter();
+
+// Subscribe with full type safety
+emitter.on('state-settled', (payload) => {
+  console.log(`Turn ${payload.turnNumber} settled, phase: ${payload.phase}`);
+});
+
+// Unsubscribe
+const handler = (p: StateSettledPayload) => {};
+emitter.on('state-settled', handler);
+emitter.off('state-settled', handler);
+```
+
+### Emitting Events
+
+```typescript
+emitter.emit('state-settled', { turnNumber: 5, phase: 'draw' });
+```
+
+### Global Access
+
+During gameplay, the emitter is exposed globally as `window.__GAME_EVENTS__` so that tools (replay, testing) can subscribe from outside the Phaser scene:
+
+```typescript
+const emitter = (window as any).__GAME_EVENTS__;
+emitter.on('state-settled', (payload) => {
+  // e.g., capture screenshot
+});
+```
+
+### PhaserEventBridge
+
+When using Phaser scenes, the `PhaserEventBridge` forwards engine events to Phaser's scene events and vice versa:
+
+```typescript
+import { GameEventEmitter, PhaserEventBridge } from '@core-engine';
+
+const emitter = new GameEventEmitter();
+const bridge = new PhaserEventBridge(emitter, scene.events);
+
+// Now scene.events receives forwarded engine events:
+this.events.on('state-settled', (payload) => { /* ... */ });
+
+// Destroy on scene shutdown:
+bridge.destroy();
+```
+
 ## Managing Assets
 
 - All assets go in `public/assets/` and are served by Vite at the `/assets/` URL path
@@ -1359,7 +1452,7 @@ reusing base layout zones through composition.
 | `example-games/main-street/layouts/main-street.layout.json` | Canonical base layout (8 zones, position-only) |
 | `example-games/main-street/layouts/main-street-tutorial.layout.json` | Tutorial-specific layout (7 zones, position + dimensions) |
 | `example-games/main-street/scenes/MainStreetTutorialHints.ts` | Tutorial overlay manager |
-| `example-games/main-street/TutorialFlow.ts` | T1-T10 step definitions with `TutorialHighlightZone` type |
+| `example-games/main-street/TutorialFlow.ts` | T1-T13 unified step definitions with `TutorialHighlightZone` / `TutorialActionType` types |
 
 #### How composition works
 
@@ -1608,6 +1701,8 @@ The `CardGameScene` abstract class (at `src/ui/CardGameScene.ts`) provides share
 - Event system setup (`GameEventEmitter` + `PhaserEventBridge`)
 - Sound system setup (`SoundManager` + SFX registration)
 - Help and Settings panel initialization via `initHelpPanel()` and `initSettingsPanel()`
+- Undo/redo button creation via `initUndoRedoButtons()` with resolution-independent positioning
+- Undo/redo button state updates via `refreshUndoRedoButtons(canUndo, canRedo)`
 - Replay mode detection
 - Standard shutdown/cleanup via `shutdownBase()`
 
@@ -1624,6 +1719,10 @@ export class MyGameScene extends CardGameScene {
     if (!this.replayMode) {
       this.initHelpPanel(helpContent as HelpSection[]);
       this.initSettingsPanel();
+      this.initUndoRedoButtons(
+        () => this.turnController.performUndo(),
+        () => this.turnController.performRedo(),
+      );
     }
     // ... game-specific setup ...
   }
@@ -1636,6 +1735,23 @@ export class MyGameScene extends CardGameScene {
 
 The `initHelpPanel()` method creates both `HelpPanel` and `HelpButton`. The `initSettingsPanel()` method creates both `SettingsPanel` and `SettingsButton`. These are accessed via `this.helpPanel`, `this.helpButton`, `this.settingsPanel`, and `this.settingsButton` respectively.
 
+### Undo/Redo Buttons
+
+The `initUndoRedoButtons(onUndo, onRedo)` method creates standard undo/redo
+action buttons positioned to avoid overlap with the settings and help toggle
+buttons. The positioning is resolution-independent — computed dynamically from
+the scene viewport using the same formula as the settings button's default
+position.
+
+- **Undo button** is placed to the left of the settings button
+- **Redo button** is placed to the right of the undo button
+- Both buttons are parented into `hudContainer` for consistent depth ordering
+- Use `refreshUndoRedoButtons(canUndo, canRedo)` to update enabled/disabled
+  state (alpha 1.0 when enabled, 0.5 when disabled)
+- Both buttons are destroyed in `shutdownBase()`
+- This method is **opt-in**: only scenes that explicitly call it get undo/redo
+  buttons (games without undo/redo are unaffected)
+
 ### HUD Container Pattern
 
 Games that need to separate persistent overlay elements (help/settings buttons, panel input blockers) from transient HUD elements (score text, status bars) should use a two-container pattern:
@@ -1701,3 +1817,24 @@ wl close <id> --reason "..." --json  # close when done
 **Large bundle warning:**
 - The Phaser library is ~1.4 MB minified -- this is expected
 - Code-splitting can be added later via `build.rollupOptions.output.manualChunks` in `vite.config.ts`
+
+**Replay tool: Dev server not running:**
+- The replay tool (`npm run replay`) and transcript export (`npm run transcripts:export`) auto-start the dev server if `localhost:3000` is not responding
+- If auto-start fails, start the dev server manually: `npm run dev`
+- Check port 3000 availability: `lsof -i :3000`
+
+**Replay tool: Unsupported transcript version error:**
+- The transcript schema includes a `version` field; the replay tool validates this and exits with a clear error if the version is unsupported
+- Re-record the game to generate a transcript with the current version
+- Transcripts evolve independently per game type; check the game's adapter for supported versions
+
+**Transcript persistence: IndexedDB storage quota:**
+- The `TranscriptStore` uses IndexedDB with a rolling window of the last 10 transcripts per game type
+- If IndexedDB is unavailable (private browsing, storage quota exceeded), it falls back to localStorage with a console warning
+- Individual large transcripts can exceed localStorage's ~5-10MB limit; a size warning is logged to console
+- Use `npm run transcripts:export -- <game>` to offload transcripts to disk
+
+**Playwright not installed:**
+- The replay tool and transcript export use Playwright's Chromium browser
+- Install it: `npx playwright install chromium`
+- Verify installation: `npx playwright install --list`

docs/SFX_CONVENTION.md

@@ -0,0 +1,115 @@
+# SFX Key Naming Convention
+
+> **Last updated:** 2026-06-17
+> **Related work-item:** CG-0MM1OQN4E153GJY3 — SFX key naming inconsistency and potential collision
+
+## Overview
+
+All sound effects (SFX) across all games in the Tableau Card Engine use the `sfx-` prefix with **no game identifier**. This ensures a consistent, collision-safe naming convention.
+
+### Examples
+
+| ✅ Correct | ❌ Incorrect |
+|-----------|-------------|
+| `sfx-card-draw` | `bc-sfx-card-draw` |
+| `sfx-ui-click` | `ms-click` |
+| `sfx-turn-change` | `lc-sfx-turn-change` |
+
+## Shared Constants
+
+Common cross-game SFX keys are defined as a shared constants object (`COMMON_SFX_KEYS`) exported from `src/core-engine/SoundManager.ts`. Games import and use these constants instead of defining duplicate strings.
+
+```ts
+import { COMMON_SFX_KEYS } from '@core-engine/SoundManager';
+
+const MY_SFX_KEYS = {
+  UI_CLICK: COMMON_SFX_KEYS.UI_CLICK,
+  CARD_DRAW: 'sfx-card-draw',
+} as const;
+```
+
+### Available common keys
+
+| Constant | Value | Usage |
+|----------|-------|-------|
+| `COMMON_SFX_KEYS.UI_CLICK` | `sfx-ui-click` | Generic UI click / tap feedback |
+| `COMMON_SFX_KEYS.TURN_CHANGE` | `sfx-turn-change` | Active player changes |
+| `COMMON_SFX_KEYS.ROUND_END` | `sfx-round-end` | A round has ended |
+| `COMMON_SFX_KEYS.SCORE_REVEAL` | `sfx-score-reveal` | Scores are being revealed |
+
+## Audio Asset Organization
+
+Audio files are organized per game with a default fallback:
+
+```
+public/assets/audio/
+├── default/            # Fallback sounds for common SFX keys
+│   ├── card-draw.wav
+│   ├── card-flip.wav
+│   ├── ui-click.wav
+│   └── ...
+├── golf/               # Game-specific audio
+│   ├── card-draw.wav
+│   └── ...
+├── sushi-go/
+├── feudalism/
+├── beleaguered-castle/
+├── lost-cities/
+├── the-mind/
+└── main-street/        # (Main Street uses assets/games/main-street/audio/)
+```
+
+When loading audio, use the `audioPathWithFallback()` helper from `src/ui/CardGameScene.ts`:
+
+```ts
+import { audioPathWithFallback } from '@ui/CardGameScene';
+
+// Tries assets/audio/golf/card-draw.wav first,
+// then assets/audio/default/card-draw.wav
+this.load.audio('golf:sfx-card-draw', audioPathWithFallback('golf', 'card-draw.wav'));
+```
+
+## Collision Protection
+
+To prevent Phaser audio key collisions when multiple games are loaded:
+
+1. **Namespace-scoped audio keys**: Each game loads audio with a namespace-prefixed key: `game-name:sfx-card-draw`. This is transparent to game code — SoundManager handles the namespace mapping automatically via the `namespace` option.
+
+2. **Scene-scoped cleanup**: When a game scene shuts down, `SoundManager.destroy()` unsubscribes event listeners and `clearRegistrations()` removes registered keys.
+
+### Setting up namespace in a game scene
+
+```ts
+// In your scene's preload():
+const ns = 'my-game';
+this.load.audio(`${ns}:sfx-card-draw`, audioPathWithFallback('my-game', 'card-draw.wav'));
+
+// In your scene's create():
+this.initSoundSystem(Object.values(SFX_KEYS), mapping, { namespace: 'my-game' });
+```
+
+## Adding SFX to a New Game
+
+1. **Create audio files** in `public/assets/audio/<game>/`.
+2. **Define SFX keys** in a constants file, using `sfx-` prefix:
+   ```ts
+   import { COMMON_SFX_KEYS } from '@core-engine/SoundManager';
+
+   export const SFX_KEYS = {
+     UI_CLICK: COMMON_SFX_KEYS.UI_CLICK,
+     CARD_DRAW: 'sfx-card-draw',
+   } as const;
+   ```
+3. **Load audio** in `preload()` using namespace-prefixed keys and `audioPathWithFallback`.
+4. **Register and connect** in `create()` via `initSoundSystem()` with the namespace option.
+5. **Document** any new game-specific audio files in this document or the game's README.
+
+## Main Street Synth SFX
+
+Main Street uses ToneForge-generated synth audio in addition to WAV fallbacks. The synth key mapping is defined in `example-games/main-street/sfx-tf-mapping.ts` and uses the same `sfx-` prefix convention.
+
+## Testing
+
+- Run `npm test` to verify all SFX-related tests pass.
+- The `SoundManager.test.ts` includes tests for `COMMON_SFX_KEYS`, namespace collision protection, and registration inspection.
+- The `sfxTfMapping.test.ts` validates Main Street synth key mappings.

docs/gym/GYM_INDEX.md

@@ -39,6 +39,12 @@ npx vitest run --project browser tests/gym/*.browser.test.ts
 | Lighting Spike | `GymGraphicsLightingSpikeScene` | Point light, shadow evaluation, WebGL fallback | [`scenes/GymGraphicsLightingSpikeScene.ts`](../../example-games/gym/scenes/GymGraphicsLightingSpikeScene.ts) | [`GymSceneSmoke.browser.test.ts`](../../tests/gym/GymSceneSmoke.browser.test.ts) |
 | Screen Layout Language (SLL) | `GymSllScene` | `validateScreenLayoutDocument`, `parseScreenLayoutDocument`, `normalizedToPixels`, `getZoneRect`, `anchorPoint` | [`scenes/GymSllScene.ts`](../../example-games/gym/scenes/GymSllScene.ts) | [`GymSllLayout.test.ts`](../../tests/gym/GymSllLayout.test.ts), [`GymSllScene.browser.test.ts`](../../tests/gym/GymSllScene.browser.test.ts) |
 
+## Scene Navigation
+
+All Gym demo scenes that extend `GymSceneBase` include `[ < Prev ]` and `[ Next > ]` buttons in the header bar, positioned to the right of the `[ Menu ]` button. These cycle through the `GYM_SCENE_CATALOGUE` with wrap-around navigation.
+
+The `getAdjacentGymSceneKey()` helper in `GymRegistry.ts` provides the scene key for the previous or next scene. Unit tests in `GymSceneHeaderNavigation.test.ts` verify wrap-around behaviour and that the Router scene is excluded.
+
 ## Deterministic Headless Tests
 
 All Gym scenes are validated by deterministic headless smoke tests in [`GymHeadlessDeterminism.test.ts`](../../tests/gym/GymHeadlessDeterminism.test.ts), which assert: