Merge dev → main (automated)

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## v0.1.4 (2026-07-10)
+### Features
+- Migrate Gym scenes to Screen Layout Language (SLL) (CG-0MPF8WT920076RQ5)
+- Layout ownership runtime (CG-0MPFM2MJF0000TIF)
+- Help text in Gym scenes (CG-0MPXUDVRE006Y1Y6)
+- Shared Game over screen (CG-0MQJZUOPJ001USHB)
+- Generalize synergy bonus system to support per-card custom values (CG-0MQRA9QTA0012PNZ)
+- Income rounding error: fractional baseIncome lost via Math.floor in applyReputationMultiplier (CG-0MRER3RE300418SG)
+- Main Street income label: add Income: prefix, center on card, show in market (CG-0MRCQL9KO007SUUJ)
+- More intuitive chopsticks UX (CG-0MQK03TE4005FP3A)
+- Main Street upcoming cards stretched — fix image aspect ratio (CG-0MRCR08VB001N7EA)
+- CSV Auto-Balancing Tool and Card Cost/Reward Spread Pass (CG-0MRDE9EYB0013E20)
+- CLI framework with CSV I/O and backup management (CG-0MRDM4YGI002SK1E)
+- Npm script, guardrail updates, and integration (CG-0MRDM5BJQ009YL8N)
+- Event family balancing (CG-0MRDM5BJS006XU7X)
+- Upgrade and staff family balancing (CG-0MRDM5BJF004LUNC)
+- Business and Community Space family balancing (CG-0MRDM4YGO005X1H9)
+- Animate card reordering when sorting hand in Gym scene (CG-0MQFEXIIH009AUZF)
+- Feature: HandView animateAddCard + Gym migration (CG-0MQ6HR1H0000SA16)
+### Bug Fixes
+- Fix discard pile showing oversized empty card-back (CG-0MR9WK4BO003GTEM)
+- Fix findTextObject to search inside Phaser Containers (CG-0MRE3ZKEM003BUHJ)
+- Fix syncAllVisibility no-op in GymLayoutOwnershipScene (CG-0MRE3ZKE9000EAIZ)
+- Fix toggle label format inconsistency in GymLayoutOwnershipScene (CG-0MRE3ZKF10074GER)
+- Fix removeUngrouped to only target ungrouped items (CG-0MRE3ZKFW002S3ND)
+### Other
+- Migrate lost-cities SVG usage to core-engine SvgHelpers (CG-0MPAZX4KL002MXNX)
+- Migrate one Gym scene to SLL as proof-of-concept (CG-0MQQHESGK001BN55)
+- Migrate remaining Gym scenes to SLL (CG-0MQQHETFH004ARLQ)
+- Verify visual and functional parity after SLL migration (CG-0MQQHEUA4009S5ZG)
+- Browser regression tests for shared visibility helper (CG-0MPGVOA4H004E2WX)
+- Migrate existing games to use shared GameOverOverlay (CG-0MQQHETKK000K7YP)
+- Create GameOverOverlay component in core engine UI (CG-0MQQHESJ000187PR)
+- Tests: The Mind reduced motion support (CG-0MQLEMSVG001DU86)
+- Tests: Feudalism reduced motion support (CG-0MQLEMSW900437KM)
+- Tests: Lost Cities reduced motion support (CG-0MQLEMSWC00530R1)
+- Tests: Beleaguered Castle reduced motion support (CG-0MQLEMSWE001EUZ5)
+- Lost Cities: reduced motion support (CG-0MQLESCC3005I9IP)
+- The Mind: reduced motion support (CG-0MQLESCC5009PLXF)
+- Beleaguered Castle: reduced motion support (CG-0MQLESCCS004J9V4)
+- Feudalism: reduced motion support (CG-0MQLESCE4009A494)
+- Release Readiness Audit: Gym scenes and Games (CG-0MRCNVTS8008FTGF)
+- Release Readiness Audit: Gym — Layout Ownership (NEW) (CG-0MRCQBB1M004T63U)
+- Release Readiness Audit: Main Street (CG-0MRCQCWTO001FA3J)
+- Release Readiness Audit: The Mind (CG-0MRCQCWLR007VLZ9)
+- Clean up orphaned Mind fixture and comment references (CG-0MRDVOH8H007QQDL)
+- Release Readiness Audit: Gym — Overlay & UI Config (CG-0MRCQAXSP0047NVU)
+- Release Readiness Audit: Gym — Transcript Recording (CG-0MRCQAXUW009TWNU)
+- Release Readiness Audit: Gym — Undo / Redo (CG-0MRCQAXYO000IYNZ)
+- Release Readiness Audit: Gym — Save / Load State (CG-0MRCQAY00006NXIX)
+- Release Readiness Audit: Gym — Audio & Feedback Config (CG-0MRCQBB0N007XRPH)
+- Release Readiness Audit: Gym — Screen Layout Language (SLL) (CG-0MRCQBB1Z0047JP0)
+- Release Readiness Audit: Gym — Shader & Blend Spike (CG-0MRCQBB33005RPV4)
+- Release Readiness Audit: Gym — Tooltip Manager (NEW) (CG-0MRCQBB4Z0003RQ1)
+- Release Readiness Audit: Gym — Lighting Spike (CG-0MRCQBB80001A175)
+- Release Readiness Audit: Gym — HUD Components (NEW) (CG-0MRCQBB82007PFP5)
+- Release Readiness Audit: Gym (demo suite) (CG-0MRCQCWKW002U22T)
+- Release Readiness Audit: Beleaguered Castle (CG-0MRCQCWLU0003BDE)
+- Release Readiness Audit: Sushi Go! (CG-0MRCQCWMM003RUTQ)
+- Release Readiness Audit: Lost Cities (CG-0MRCQCWMT006O0LV)
+- Release Readiness Audit: Feudalism (CG-0MRCQCWNM000QYY5)
+- Release Readiness Audit: Golf (CG-0MRCQCWQK003WMHE)
+- Release Readiness Audit: Gym — Deck & Seeded RNG (CG-0MRCQAXSP006VUNL)
+- Core balancing algorithm unit tests (CG-0MRDM4F9F008A22D)
+- Upgrade and staff balancing algorithm tests (CG-0MRDM4NRM0051KD5)
+- Event balancing and Monte Carlo validation tests (CG-0MRDM4NRV0066Z9P)
+- Balancing methodology document and migration (CG-0MRDM5BJ3004AE1W)
+- Move tier definitions into the CSV (CG-0MR91VLA6009V1XG)
+- Round all coin displays to 3 decimal places in the UI (CG-0MREYZO7E00729S0)
+- Fix synergy calculations for adjacent businesses (CG-0MQQHBYA50060YPX)
+- Add visual synergy lines between adjacent businesses (CG-0MQQHBZ3D002J02E)
+- Test: GymHandPileScene animation integration tests (CG-0MQ6HQRSE006A9OJ)
+- Task: Documentation updates (CG-0MQ6HR1H0008RW3O)
+- Remove The Mind completely (CG-0MQK1N2XS000OSOI)
+

docs/main-street/balancing-methodology.md

@@ -0,0 +1,128 @@
+# Main Street Balancing Methodology
+
+## Overview
+
+This document describes the automated balancing methodology used by the `run-balance-cards` CLI tool to perform a data-driven balancing pass on the Main Street card data CSV. The tool implements a **hybrid approach** combining curve-fitting and tier-band analysis.
+
+## Algorithm Approach
+
+The tool uses two complementary techniques:
+
+### 1. Curve-Fitting
+
+Each card family has a family-specific expected cost function that models cost as a function of card stats:
+
+| Family | Input Variables | Formula |
+|--------|----------------|---------|
+| **Business / Community Space** | baseIncome, synergyTypes, synergyCoinBonus, synergyRepBonus, reputationPerTurn, incomeBonus, tier | `tier * 2 + 2 + baseIncome * 4 + synergyCount * 3 + bonuses` |
+| **Investment Events** | coinDelta, reputationDelta, targetSynergy, tier | `tier * 1.5 + 0.5 + coinDelta * 1.5 + repDelta * 2` | 
+| **Upgrades** | incomeBonus, synergyRangeBonus, requiredLevel, reputationBonus, tier | `tier * 1.5 + 1 + incomeBonus * 3 + synergyRange * 3 + repBonus * 10` |
+| **Staff** | ongoingCost, handSlotsAdded | `ongoingCost * 5 + handSlotsAdded * 5` |
+
+### 2. Tier Band Analysis
+
+Expected costs are mapped to cost bands using percentile-based assignment:
+
+| Band | Percentile | Cost Range | Label |
+|------|-----------|------------|-------|
+| **Budget** | 0–20% | 0–3 | Basic, affordable cards |
+| **Economy** | 20–40% | 4–5 | Entry-level value |
+| **Standard** | 40–60% | 6–7 | Mid-range cards |
+| **Premium** | 60–80% | 8–9 | High-value cards |
+| **Flagship** | 80–100% | 10–14 | Premium, high-impact cards |
+
+The algorithm ensures each band has representation by computing percentile position within each family's cost distribution.
+
+### 3. Cost Spread Enforcement
+
+After tier band assignment, a post-processing pass ensures no single cost value exceeds **1/3 of the cards** in any family. Excess cards at a clustered cost value are spread to adjacent values (±1, ±2) to improve strategic differentiation.
+
+### 4. Reward Spread
+
+When a card's cost changes, its reward fields (baseIncome, coinDelta, synergy bonuses, etc.) are adjusted proportionally:
+
+- **Cost increase of >10%**: Rewards scaled up proportionally (costRatio × 0.7)
+- **Cost decrease of >10%**: Rewards scaled down proportionally
+- **Premium/Flagship cards (cost ≥ 8)**: Awarded synergyCoinBonus and synergyRepBonus if missing
+
+### 5. Exclusion Rules
+
+| Rule | Cards Affected | Rationale |
+|------|---------------|-----------|
+| **Incidents remain free** | All 23 Incident-trigger events | Incidents are negative events; cost would make them purchaseable, changing game balance |
+
+### 6. Special Cases
+
+| Card | Handling |
+|------|----------|
+| **Pawn Shop** | No synergy bonuses; cost reduced by 2 from curve estimate |
+| **Clinic** | reputationPerTurn = +0.2 factored into cost calculation (weight × 30) |
+
+## Per-Family Strategy
+
+### Business (18 cards) and Community Space (2 cards)
+
+- **Goal**: Wider cost spread (target: range increase ≥ 30%)
+- **Inputs**: baseIncome, synergyCount, synergy bonuses, reputation, tier
+- **Algorithm**: Curve-fitted cost + tier-driven base → clamped to tier bands → spread enforcement
+
+### Investment Events (13 of 36 events)
+
+- **Goal**: Cost range wider than current 2–4 (target: range ≥ 3)
+- **Inputs**: coinDelta, reputationDelta, target scope (All vs SpecificSynergy)
+- **Scope multiplier**: All = 1.0×, SpecificSynergy = 1.2×
+
+### Incidents (23 of 36 events)
+
+- **Not adjusted** — all remain at cost 0
+
+### Upgrades (27 cards)
+
+- **Goal**: Wider cost spread (target: range ≥ 6)
+- **Inputs**: incomeBonus, synergyRangeBonus, requiredLevel, reputationBonus, tier
+- **Minimum cost**: 2
+
+### Staff (3 cards)
+
+- **Goal**: Cost spread maintained (target: range ≥ 9)
+- **Inputs**: ongoingCost, handSlotsAdded
+- **Ongoing cost adjusted proportionally**: Higher purchase cost → proportionally higher ongoing cost
+
+## Rationale Codes
+
+| Code | Description |
+|------|-------------|
+| `TIER_REASSIGN` | Cost adjusted due to tier band reassignment |
+| `BAND_BALANCE` | Minor band adjustment to improve cost distribution |
+| `COST_CURVE_FIT` | Cost adjusted via curve-fitting model |
+| `INCOME_ADJUST` | baseIncome adjusted to reflect new cost tier |
+| `SYNERGY_BONUS_ADJ` | Synergy bonus added/removed for premium cards |
+| `REPUTATION_ADJ` | Reputation bonus adjusted for cost tier |
+| `REWARD_SPREAD` | Reward fields widened to match new cost |
+| `ONGOING_COST_ADJ` | Staff ongoing cost adjusted proportionally |
+| `INCIDENT_FREE` | Incident event excluded from cost adjustment |
+| `SPECIAL_CASE` | Special handling (e.g., Pawn Shop no-synergy) |
+
+## Determinism
+
+The tool is fully deterministic — running on the same input CSV produces identical output on every run. No random noise is used in any phase of the algorithm.
+
+## Usage
+
+```bash
+# Run with defaults (reads card-data.csv, writes card-data.balanced.csv)
+npx tsx scripts/run-balance-cards.ts
+
+# Custom input/output paths
+npx tsx scripts/run-balance-cards.ts --input path/to/input.csv --output path/to/output.csv
+```
+
+## Migration
+
+This document consolidates all balancing methodology content previously scattered across:
+
+- `docs/main-street/content-design-and-progression.md` — Section 4 (Difficulty and Balance), 4.1 (Provisional Numeric Balance Targets), 4.2 (Tuning Levers)
+- `docs/main-street/the-build-gdd.md` — Section 4 (Difficulty and Balance)
+- `docs/main-street/card-catalog.md` — Event Balance Summary table, Upgrade Cost Distribution table
+
+The origin documents now contain cross-references to this document.

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

@@ -1,6 +1,6 @@
 {
   "source": "Tier 1 baseline from example-games/main-street/MainStreetTiers.ts",
-  "capturedAt": "2026-06-23T09:24:24.962Z",
+  "capturedAt": "2026-07-06T01:12:46.202Z",
   "perTier": {
     "tier1": {
       "business": 6,

docs/main-street/card-catalog.md

@@ -1,38 +1,44 @@
 # Main Street: Card Catalog
 
-> **Source of truth:** `example-games/main-street/MainStreetCards.ts`
-> **Last updated:** Expanded pool verification (work item CG-0MOKJPBOX006UQDO)
+> **Source of truth:** `example-games/main-street/card-data.csv` (CSV) — loaded by `MainStreetCards.ts` at build time (work item CG-0MR6ZR23J006ZDNZ)
+> **Last updated:** CSV externalisation (work item CG-0MR6ZR23J006ZDNZ)
 
-This document lists every card template in the Main Street card pool, organised by family (Business, Event, Upgrade). Each entry includes all gameplay-relevant fields and a short design rationale.
+This document lists every card template in the Main Street card pool, organised by family (Business, Event, Upgrade, Community Space, Staff). Each entry includes all gameplay-relevant fields and a short design rationale.
+
+Card templates are stored as rows in `card-data.csv` and parsed at build time by `MainStreetCards.ts`. To add cards, edit the CSV and regenerate metadata (see guidance below).
 
 **Deck sizes (default copies):**
 
-| Family   | Templates | Copies each | Total cards |
-|----------|-----------|-------------|-------------|
-| Business | 18        | 3           | 54          |
-| Event    | 18        | 3           | 54          |
-| Upgrade  | 27        | 2           | 54          |
+| Family        | Templates | Copies each | Total cards |
+|---------------|-----------|-------------|-------------|
+| Business      | 18        | 3           | 54          |
+| Event         | 36        | 3           | 108         |
+| Upgrade       | 27        | 2           | 54          |
+| Community Space | 2       | 3           | 6           |
+| Staff         | 3         | 3           | 9           |
 
 **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`) | 18 | 18 | 27 | 63 |
-| Net increase | +11 | +12 | +22 | +45 |
+| Snapshot | Business | Event | Upgrade | Community Space | Staff | Total templates |
+|---|---:|---:|---:|---:|---:|---:|
+| Tier 1 baseline (`docs/main-street/card-catalog-baseline.json`) | 7 | 6 | 5 | — | — | 18 |
+| Current catalog (`card-data.csv`) | 18 | 36 | 27 | 2 | 3 | 86 |
+| Net increase | +11 | +30 | +22 | +2 | +3 | +68 |
 
 - 2x target from baseline: `>= 36` templates
-- Current total: `63` templates (`3.50x` baseline)
+- Current total: `86` templates (`4.78x` baseline)
 - Non-baseline card IDs are tracked in `docs/main-street/expanded-card-manifest.json`
 
 ### Guidance: adding more cards safely
 
-1. Add card templates in `example-games/main-street/MainStreetCards.ts`.
+1. Add rows to `example-games/main-street/card-data.csv` using the correct family column value (`business`, `event`, `upgrade`, `community-space`, or `staff`).
 2. Regenerate metadata artifacts:
+   - `npx tsx scripts/generate-card-csv.ts` — regenerates `card-data.csv` from TS (only if editing TS directly; normally edit CSV)
    - `npx tsx scripts/generate-main-street-catalog-baseline.ts`
-   - `npx tsx scripts/generate-main-street-expanded-card-manifest.ts`
+   - `npx vite-node scripts/generate-main-street-expanded-card-manifest.ts`
+     _(uses Vite-aware ESM loader because it imports deck-building functions from `MainStreetCards.ts`)_
 3. Regenerate placeholder art:
    - `node scripts/generate-main-street-card-svgs.mjs`
 4. Run regression tests:

docs/main-street/card-dimensions.md

@@ -41,6 +41,7 @@ UI slot mappings (recommendations)
   - Market slot thumbnail / Street slot: 140×80 (Main Street canonical)
   - Street small thumbnail: fit to 105×110
   - UI small (compact hand): CARD_W × CARD_H (48×65 default runtime)
+  - Incident queue thumbnail: 120×69 (preserves 7:4 card SVG aspect ratio)
   - Selector thumbnail: 120×68 (scene screenshot)
 
 ## Layout notes (Main Street)

docs/main-street/content-design-and-progression.md

@@ -67,38 +67,9 @@ The core economic loop consists of two primary resources:
 
 ## 4. Difficulty and Balance
 
-Main Street is intended to be approachable for 10‑15‑minute play sessions while still offering strategic depth. Difficulty is managed through the following levers:
-
-| Lever | Effect |
-|-------|--------|
-| **Slot Count** | The base game uses 10 slots; increasing to 12 slots adds decision space without extending playtime significantly. |
-| **Coin Starting Amount** | Adjusting the initial budget (e.g., 8 → 10 coins) can make early rounds easier or tighter. |
-| **Synergy Bonus Value** | Changing the synergy bonus from `+1` to `+2` per matching neighbor raises the impact of placement decisions. |
-| **Event Frequency** | Adding more Incident events to the deck increases variance. The visible incident queue (2 cards) lets the player plan ahead. |
-| **Challenge Targets** | Scaling challenge thresholds (e.g., “Build a Foodie Row” requiring 3 Food businesses) adjusts difficulty. |
-
-Balancing targets are defined in the runtime difficulty config (Medium defaults: `maxTurns = 20`, `winThreshold = 150`, `startingCoins = 8`, `synergyBonusPerNeighbor = 1`). Playtesting should verify that a typical run reaches the score threshold in the mid-to-late game with meaningful risk from incidents.
-
-### 4.1 Provisional Numeric Balance Targets (Medium)
-
-These are draft targets for iterative tuning and are validated using deterministic Monte Carlo sweeps:
-
-| Metric | Target (draft) | Notes |
-|-------|-----------------|-------|
-| Win rate | 85%-97% over 100 deterministic seeds | Greedy market strategy baseline (`market-greedy`) |
-| Median final score | 150-170 | Should stay near the score-threshold band |
-| Dominant loss reason share | >= 50% of losses | Ensures one primary failure mode remains measurable |
-| Avg no-action turns | >= 0.75 turns/run | Confirms meaningful affordability tension |
-| Avg turn street reaches 5/10 slots | 4.5-7.5 | Early/mid-game growth checkpoint |
-| Avg turn street reaches 10/10 slots | 9-12 | Mid/late-game saturation checkpoint |
-
-### 4.2 Tuning Levers
-
-- `startingCoins`: early purchasing power and bankruptcy risk.
-- `winThreshold`: pacing pressure for score-based wins.
-- `synergyBonusPerNeighbor`: strength of adjacency strategy.
-- `maxTurns`: upper bound for pacing and turn-exhaustion pressure.
-- incident/event card composition and penalties: volatility and loss-vector mix.
+The balancing methodology and targets for Main Street have been consolidated into a dedicated document. See [balancing-methodology.md](balancing-methodology.md) for the full methodology.
+
+> **Migrated content**: Section 4 (Difficulty and Balance), 4.1 (Provisional Numeric Balance Targets), and 4.2 (Tuning Levers) have been moved to `balancing-methodology.md`. This section now serves as a cross-reference.
 
 ---
 

docs/main-street/expanded-card-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "Generated from MainStreetCards.ts and Tier 1 IDs from MainStreetTiers.ts",
-  "generatedAt": "2026-06-24T23:00:00.000Z",
+  "generatedAt": "2026-07-06T01:10:05.874Z",
   "baselineTier1CardIds": [
     "biz-bakery",
     "biz-bookshop",
@@ -19,8 +19,8 @@
     "upg-bistro",
     "upg-community-hub",
     "upg-garden",
-    "upg-readers-cafe",
     "upg-patisserie",
+    "upg-readers-cafe",
     "upg-vintage-shop"
   ],
   "expandedCardIds": {

docs/main-street/monte-carlo-baseline.json

@@ -1,11 +1,12 @@
 {
   "source": "Generated from MainStreetMonteCarlo.runMonteCarlo",
-  "generatedAt": "2026-06-30T14:25:29.089Z",
+  "generatedAt": "2026-07-10T10:29:03.028Z",
   "seeds": 200,
   "maxTurns": 25,
   "strategy": "greedy",
+  "note": "Updated after CG-0MRER3RE300418SG: fractional income fix removed Math.floor from applyReputationMultiplier and Math.round from applyActiveEffectMultiplier. Win rate and coins-per-turn increased because fractional income values are no longer truncated.",
   "metrics": {
-    "winRate": 0.505,
-    "averageCoinsPerTurn": 2.0112805746240356
+    "winRate": 0.65,
+    "averageCoinsPerTurn": 3.300755112659271
   }
 }