Merge dev → main (automated)

.gitignore

@@ -93,3 +93,4 @@ Worklog Specific Ignores
 .opencode/tmp/
 
 ### End of Worklog Specific Ignores
+.pi/

README.md

@@ -79,7 +79,7 @@ tableau-card-engine/
 | Sushi Go! | `example-games/sushi-go/` | Card drafting game (human vs. AI). Pick and pass hands over 3 rounds, collect sets of sushi dishes, and score the most points |
 | Feudalism | `example-games/feudalism/` | Engine-building card game (human vs. AI). Collect gem tokens, purchase development cards for bonuses, attract nobles, and reach 15 prestige to win. Checkpoint autosaves after each turn (human + AI) with startup recovery |
 | Lost Cities | `example-games/lost-cities/` | Two-player expedition card game (human vs. AI). Bet on up to 5 colored expeditions across a 3-round match with investment multipliers, ascending-play rules, and cumulative scoring |
-| Main Street | `example-games/main-street/` | Single-player tableau builder. Buy businesses/upgrades/events, place businesses on a 10-slot street rendered as a responsive 2x5 grid, and optimize score over 20 turns. Tutorial overlay zones are defined in a separate SLL layout file (`main-street-tutorial.layout.json`) composed with the base layout. |
+| Main Street | `example-games/main-street/` | Single-player tableau builder. Buy businesses/upgrades/events, place businesses on a 10-slot street rendered as a responsive 2x5 grid, and optimize score over 20 turns. **Multi-Use Card Economy**: cards can be held in hand for synergy bonuses; staff cards expand hand capacity with ongoing costs. Market cycles each turn. Tutorial overlay zones are defined in a separate SLL layout file (`main-street-tutorial.layout.json`) composed with the base layout. |
 | Scenario: Tutorial | `example-games/main-street/scenes/MainStreetTutorialScene.ts` | Guided introduction to Main Street. Non-interactive tutorial overlays walk through the market, street placement, synergies, events, and scoring. Easy difficulty, 25 turns. Accessible from the Game Selector. |
 
 More games are planned: Coloretto.
@@ -96,7 +96,7 @@ When a Business card is upgraded (level > 0), the renderer applies visual overla
 |---------|----------|-------------|
 | **Level badge** | Top-right | Gold bold text showing "Lvl N" (e.g., "Lvl 2") |
 | **Income display** | Bottom-center | Green bold text showing combined income (baseIncome + incomeBonus), e.g., "+8" |
-| **Name overlay** | Top-center | White bold text with dark semi-transparent background showing the upgraded card name (e.g., "Library" instead of "Bookshop") |
+| **Name overlay** | Top-center | White bold text with dark semi-transparent background showing the upgraded card name (e.g., "Reader's Café" instead of "Bookshop") |
 | **Upgrade border** | Card perimeter | 3px golden stroke (`#ffaa22`) for visual distinction from base cards |
 
 ### Architecture

docs/DEVELOPER.md

@@ -125,14 +125,17 @@ MONTE_SEEDS=50 npm run monte-carlo
 MONTE_SEEDS=200 MONTE_MIN_WIN_RATE=0.20 MONTE_MAX_WIN_RATE=0.80 npm test
 ```
 
-Tests use [Vitest](https://vitest.dev/) configured inline in `vite.config.ts` with two test projects:
+Tests use [Vitest](https://vitest.dev/) configured inline in `vite.config.ts` with three test projects:
 
 | Project | Environment | File Pattern | Purpose |
 |---------|-------------|-------------|---------|
 | `unit` | Node.js | `tests/**/*.test.ts` | Logic, data, and integration tests |
-| `browser` | Chromium (Playwright) | `tests/**/*.browser.test.ts` | Phaser UI and rendering tests |
+| `browser` | Chromium (Playwright) | `tests/**/*.browser.test.ts` (excludes tutorial E2E) | Phaser UI and rendering tests |
+| `tutorial` | Chromium (Playwright) | `tests/e2e/main-street-tutorial-e2e-*.browser.test.ts` | Main Street tutorial E2E tests (run separately to avoid GPU context exhaustion) |
 
-Both projects run together via `npm test`. The browser project runs in headless Chromium using `@vitest/browser` with the Playwright provider.
+All three projects run together via `npm test`. The browser and tutorial projects run in headless Chromium using `@vitest/browser` with the Playwright provider.
+
+The tutorial E2E tests are split into 6 part files (1-6 tests per file) and run via `scripts/run-tutorial-tests.sh`, which spawns a separate Chromium instance for each part to avoid the Phaser 4 RC GPU/Canvas context exhaustion that occurs after ~8 game create/destroy cycles in a single browser process. The helper module at `tests/helpers/main-street-tutorial-e2e.ts` contains shared game lifecycle utilities (`bootGameWithTutorial`, `destroyGame` with CanvasPool drain) and click helpers for tutorial step advancement.
 
 During Vitest runs, the dev-only transcript persistence middleware (`POST /api/transcripts`) is intentionally disabled even though Vitest browser mode uses an internal Vite server. This prevents file-system side effects and reduces harness noise/flakiness during test execution.
 
@@ -212,6 +215,7 @@ src/
 │   ├── GameState.ts        GameState<T>, createGameState (deprecated for setup — use SetupOptions)
 │   ├── SetupOptions.ts     BaseSetupOptions, MultiplayerSetupOptions, resolveSetupOptions
 │   ├── SeededRng.ts        createSeededRng — deterministic PRNG (LCG) for shuffles and AI
+│   ├── ActiveEffect.ts     Duration-based modifier system (create, decay, apply, query)
 │   ├── CheckpointManager.ts   Checkpoint save-and-resume abstraction (save, load, clear, checkAndResume)
 │   ├── CheckpointResumeOverlay.ts Built-in default resume overlay component
 │   ├── TranscriptRecorder.ts BaseTranscript interface, TranscriptRecorderBase<T> abstract base class
@@ -615,6 +619,48 @@ The `CheckpointManager` delegates all storage to `SaveLoadStore` (IndexedDB
 with localStorage fallback). See `src/core-engine/CheckpointManager.ts` for
 full API documentation.
 
+## ActiveEffect System
+
+The `ActiveEffect` module (`src/core-engine/ActiveEffect.ts`) provides a
+duration-based modifier system that tracks ongoing effects over multiple turns.
+
+### Core Types
+
+- **`ActiveEffect`** – interface with `effectType`, `multiplier`, `turnsRemaining`,
+  `sourceEventId`, and `description`.
+- **`DecayResult`** – result of a decay operation with `active`, `expired`, and
+  `effects` arrays.
+
+### API Functions
+
+All functions are exported from `@core-engine/index`:
+
+| Function | Purpose |
+|----------|---------|
+| `createActiveEffect(type, mult, turns, sourceId, desc)` | Create a new effect |
+| `decayActiveEffects(effects)` | Decrement all effects, return active/expired sets |
+| `applyActiveEffectMultiplier(effects, type, baseValue)` | Apply matching multipliers (rounded) |
+| `hasActiveEffectOfType(effects, type)` | Check if any effect of given type exists |
+
+### Usage Pattern
+
+Duration-based Event cards (e.g. `evt-flu-outbreak`) extend `EventCard` with
+`duration`, `effectType`, and `multiplier` fields. The engine's `resolveEvent()`
+function detects `DurationEventCard` instances via the `isDurationEventCard()`
+type guard and creates an `ActiveEffect` instead of applying one-shot deltas.
+
+Income-modifier effects are applied per-slot during `applyIncome()` _before_
+the reputation coin multiplier. Effects decay at the end of each turn during
+`EndCheck` in `processEndOfTurn()`.
+
+### Main Street Integration
+
+- `MainStreetState.activeEffects` stores the active effects array
+- Serialization/deserialization includes `activeEffects` with migration for
+  old saves (missing field defaults to `[]`)
+- Duration computation for `evt-flu-outbreak` scans the street grid for
+  Clinic/Medical Center cards
+
 ## Replay Tool
 
 The replay tool (`scripts/replay.ts`) replays a fixture transcript through the game's Phaser scene in a headless browser, capturing per-turn screenshots. It is the foundation for thumbnail generation and visual regression testing.
@@ -1106,7 +1152,7 @@ this.applyUpgradeOverlays(cardContainer, biz, renderW, renderH);
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                     Game State Update                           │
-│  Player upgrades Bookshop → Library (level 1→2, income +3→+8)  │
+│  Player upgrades Bookshop → Reader's Café (level 1→2, income +3→+8)  │
 └──────────────────────────┬──────────────────────────────────────┘
                            │
                            ▼
@@ -1610,7 +1656,7 @@ The tutorial layout defines these zones (all use normalized coordinates with opt
 |---------|-------------|-----------------|
 | `hud` | HUD strip (top bar with coins, reputation, score) | Yes (full-width bounding box) |
 | `marketBusinessRow` | Business card row in the market area | Yes |
-| `streetGrid` | The 2×5 street grid for placing businesses | Yes (full-width) |
+| `streetGrid` | The 2×5 street grid for placing businesses | Yes (stops before right column) |
 | `endTurnButton` | End Turn action button area | Yes |
 | `incidentQueue` | Scrollable incident cards queue | Yes |
 | `investmentsRow` | Investment/upgrade card row | Yes |
@@ -1917,6 +1963,8 @@ wl close <id> --reason "..." --json  # close when done
 **Vite dev server won't start:**
 - Check port 3000 is not already in use: `lsof -i :3000`
 - Try `npm run dev -- --port 3001` for an alternate port
+- **Stale lock file:** If port 3000 appears free but the dev server fails, remove any stale lock file: `rm -f tmp/dev-server-lock.json`
+- **Orphaned Vite process:** If `lsof -i :3000` shows a Node.js process, kill it: `kill -9 $(lsof -t -i :3000)`
 
 **TypeScript errors on build:**
 - Run `npx tsc --noEmit` to see detailed errors
@@ -1932,6 +1980,7 @@ wl close <id> --reason "..." --json  # close when done
 - Check that `@vitest/browser` version matches `vitest` version
 - Browser tests boot a real Phaser game and may take 8-10 seconds each
 - If tests hang, check for unresolved game instances (ensure `afterEach` destroys the game)
+- **Process/resource leak cleanup:** All browser tests should clean up Phaser.Game instances in `afterEach` using `game.destroy(true, false)` and remove the game container div. The dev server utilities (`scripts/dev-server-utils.ts`) include SIGTERM/SIGINT handlers to clean up orphaned Vite processes and stale lock files on forced exit.
 
 **Large bundle warning:**
 - The Phaser library is ~1.4 MB minified -- this is expected
@@ -1941,6 +1990,7 @@ wl close <id> --reason "..." --json  # close when done
 - 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`
+- **Port conflict detection:** The `ensureDevServer()` helper now checks for existing processes on port 3000 before starting, logs warnings for potential conflicts, and cleans up stale lock files automatically.
 
 **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

docs/main-street/card-catalog-baseline.json

@@ -1,16 +1,16 @@
 {
   "source": "Tier 1 baseline from example-games/main-street/MainStreetTiers.ts",
-  "capturedAt": "2026-05-12T00:15:46.437Z",
+  "capturedAt": "2026-06-23T09:24:24.962Z",
   "perTier": {
     "tier1": {
-      "business": 7,
+      "business": 6,
       "event": 6,
-      "upgrade": 5,
-      "total": 18
+      "upgrade": 8,
+      "total": 20
     }
   },
   "totals": {
-    "baselineTotal": 18,
-    "targetAtLeast": 36
+    "baselineTotal": 20,
+    "targetAtLeast": 40
   }
 }

docs/main-street/card-catalog.md

@@ -9,22 +9,22 @@ This document lists every card template in the Main Street card pool, organised
 
 | Family   | Templates | Copies each | Total cards |
 |----------|-----------|-------------|-------------|
-| Business | 17        | 3           | 51          |
-| Event    | 17        | 3           | 51          |
-| Upgrade  | 25        | 2           | 50          |
+| Business | 18        | 3           | 54          |
+| Event    | 18        | 3           | 54          |
+| Upgrade  | 27        | 2           | 54          |
 
-**Synergy types:** Food, Culture, Commerce, Service (M2), Entertainment (M2)
+**Synergy types:** Food, Culture, Commerce, Service (M2), Entertainment (M2), Health (M2)
 
 ## Expansion summary (baseline vs current)
 
 | Snapshot | Business | Event | Upgrade | Total templates |
 |---|---:|---:|---:|---:|
 | Tier 1 baseline (`docs/main-street/card-catalog-baseline.json`) | 7 | 6 | 5 | 18 |
-| Current catalog (`MainStreetCards.ts`) | 17 | 17 | 25 | 59 |
-| Net increase | +10 | +11 | +20 | +41 |
+| Current catalog (`MainStreetCards.ts`) | 18 | 18 | 27 | 63 |
+| Net increase | +11 | +12 | +22 | +45 |
 
 - 2x target from baseline: `>= 36` templates
-- Current total: `59` templates (`3.28x` baseline)
+- Current total: `63` templates (`3.50x` baseline)
 - Non-baseline card IDs are tracked in `docs/main-street/expanded-card-manifest.json`
 
 ### Guidance: adding more cards safely
@@ -71,7 +71,14 @@ Park has been reclassified as a **Community Space** card (see below).
 |----|------|------|--------|---------|--------------|-------------|-----------|
 | `biz-laundromat` | Laundromat | 3 | 2 | Service | Laundromat | Self-serve laundry. +1/adj Service. | Budget Service entry point. |
 | `biz-barbershop` | Barbershop | 3 | 2 | Service | Barbershop | Classic cuts. +1/adj Service. | Pairs with Laundromat for early Service cluster. |
-| `biz-clinic` | Clinic | 5 | 3 | Service | Clinic | Walk-in medical care. +1/adj Service. | Premium Service; high cost/income mirrors Hardware Store. |
+
+#### Health (new synergy type)
+
+| ID | Name | Cost | Income | Synergy | Upgrade Path | Description | Rationale |
+|----|------|------|--------|---------|--------------|-------------|-----------|
+| `biz-clinic` | Clinic | 10 | 0 (rep +0.2/turn) | Health | Clinic | Walk-in medical care. Provides +0.2 rep/turn. | Non-profit community health provider; reputation instead of income. |
+| `biz-private-clinic` | Private Clinic | 8 | 2 | Health | Private Clinic | Private medical practice. Gains +1 coin per adjacent Health business. | For-profit counterpart to Clinic; income-focused. |
+| `biz-pharmacy` | Pharmacy | 6 | 1 | Health | — | Provides essential medications. Gains +1 coin per adjacent Health business. | Standalone Health card (no upgrade). |
 
 #### Entertainment (new synergy type)
 
@@ -153,6 +160,7 @@ Events fall into two categories:
 | `evt-construction` | Road Construction | Incident | 0 | All | -- | -1 | 0 | -1 coin to all biz. | Mild universal disruption. |
 | `evt-viral-review` | Viral Review | Incident | 0 | All | -- | +2 | +1 | +2 coins, +1 rep from online fame. | Positive windfall; universal. |
 | `evt-vandalism` | Vandalism | Incident | 0 | All | -- | -1 | -1 | -1 coin, -1 rep. | Dual-penalty universal disruption. |
+| `evt-flu-outbreak` | Flu Outbreak | Incident | 0 | All | -- | 0 | 0 | 80% income for 5 turns. Duration reduced by Clinic/Medical Center. | Duration-based modifier (see ActiveEffect system). |
 
 ### Event Balance Summary
 
@@ -164,6 +172,9 @@ Events fall into two categories:
 | M1 Incident (positive) | 1 | 0.0 | +2.0 |
 | M2 Incident (negative) | 5 | -1.4 | -0.4 |
 | M2 Incident (positive) | 3 | +1.33 | +1.0 |
+| M2 Incident (duration) | 1 | 0.0 | 0.0 |
+
+> Duration-based incidents (e.g. `evt-flu-outbreak`) apply an ActiveEffect instead of a one-shot delta. Their impact is listed as 0 coin/rep delta because the effect is applied over multiple turns via an income multiplier.
 
 The M2 incident pool is more balanced than M1: 5 negative vs. 3 positive incidents (compared to M1's 3 negative vs. 1 positive). This reduces the punishing feel while maintaining strategic tension.
 
@@ -179,7 +190,7 @@ Each Upgrade targets a specific Business by name. Applying an upgrade increments
 |----|------|--------|------|---------|--------|-------------|-----------|
 | `upg-patisserie` | Upgrade to Patisserie | Bakery | 4 | +1 | +1 | Bakery -> Patisserie. | Classic upgrade; income + range. |
 | `upg-bistro` | Upgrade to Bistro | Diner | 4 | +1 | +1 | Diner -> Bistro. | Matches Patisserie in cost/power. |
-| `upg-library` | Upgrade to Library | Bookshop | 3 | +1 | +0 | Bookshop -> Library. | Cheaper; income only, no range. |
+| `upg-readers-cafe` | Upgrade to Reader's Café | Bookshop | 3 | +1 | +0 | Bookshop -> Reader's Café (+0.1 rep/turn). | Cheaper; income only, no range; reputation bonus. |
 
 ### M2 Standard Upgrade Templates (14)
 
@@ -199,7 +210,8 @@ Each Upgrade targets a specific Business by name. Applying an upgrade increments
 | `upg-museum` | Upgrade to Museum | Art Gallery | 4 | +1 | +1 | Art Gallery -> Museum. | Premium bridge upgrade. |
 | `upg-resort-spa` | Upgrade to Resort Spa | Day Spa | 5 | +2 | +1 | Day Spa -> Resort Spa. | Tied with IMAX for highest cost/power. |
 | `upg-garden-center` | Upgrade to Garden Center | Florist | 3 | +1 | +1 | Florist -> Garden Center. | Budget bridge upgrade with range. |
-| `upg-medical-center` | Upgrade to Medical Center | Clinic | 5 | +2 | +1 | Clinic -> Medical Center. | Premium Service upgrade. |
+| `upg-medical-center` | Upgrade to Medical Center | Clinic | 5 | 0 (rep +0.1/turn) | +1 | Clinic -> Medical Center. Provides +0.1 rep/turn. | Reputation bonus upgrade; no income. |
+| `upg-private-medical-center` | Upgrade to Private Medical Center | Private Clinic | 4 | +2 | 0 | Private Clinic -> Private Medical Center. | Income-focused upgrade; no range or reputation. |
 
 ### M2 Branching Upgrade Templates (4)
 
@@ -228,7 +240,7 @@ Multi-level upgrades require the business to already be at Level 1 (`requiredLev
 | Cost | Count | Cards |
 |------|-------|-------|
 | 2 | 1 | Gourmet Truck |
-| 3 | 9 | Library (Bookshop upgrade), Garden, Vintage Shop, Dry Cleaners, Salon, Roastery, Garden Center, Bread Factory, Fast Food |
+| 3 | 9 | Reader's Café (Bookshop upgrade), Garden, Vintage Shop, Dry Cleaners, Salon, Roastery, Garden Center, Bread Factory, Fast Food |
 | 4 | 8 | Patisserie, Bistro, Designer Store, Gaming Lounge, Museum, Drive-In Theater, Wellness Center, Community Hub |
 | 5 | 6 | Home Improvement, IMAX Theater, Resort Spa, Medical Center, Grand Bakehouse, Restaurant |
 | 6 | 2 | Multiplex, Luxury Retreat |
@@ -248,8 +260,9 @@ M2 introduces 5 bridge cards that belong to two synergy types simultaneously. Th
 | Food | 2 (Bakery, Diner) | 2 (Cafe, Food Truck) | 4 |
 | Culture | 1 (Bookshop) | 3 (Cafe, Art Gallery, Florist) | 4 (plus Park as Community Space) |
 | Commerce | 3 (Hardware, Pawn Shop, Boutique) | 1 (Florist) | 4 |
-| Service | 3 (Laundromat, Barbershop, Clinic) | 1 (Day Spa) | 4 |
+| Service | 2 (Laundromat, Barbershop) | 1 (Day Spa) | 3 |
 | Entertainment | 2 (Arcade, Cinema) | 3 (Food Truck, Art Gallery, Day Spa) | 5 |
+| Health | 3 (Clinic, Private Clinic, Pharmacy) | 0 | 3 |
 
 Culture and Entertainment have the most bridge-card representation, making them easiest to chain synergies with. Commerce and Service rely more on dedicated single-type cards.