feat(main-street): branching & multi-level upgrade chains for Business cards

[Copilot]

Business cards were capped at a single upgrade path with maxLevel: 1. This adds branching upgrade choices (pick one of N paths) and multi-level chains (apply level-0 then level-1 upgrades sequentially).

Schema changes (MainStreetCards.ts)

• UpgradeCard.requiredLevel?: number — gates when an upgrade may be applied; 0 = base business (default), 1 = after first upgrade. Optional for backward compat.
• BusinessCard.appliedUpgrades?: string[] — ordered list of applied upgrade IDs; initialized to [] by makeBusiness().
• maxLevel raised to 2 for Bakery, Diner, Cinema, Day Spa.
• +4 branching cards (alternative level-0 paths): Bread Factory, Fast Food, Drive-In Theater, Wellness Center.
• +4 level-2 cards (requiredLevel: 1): Grand Bakehouse, Restaurant, Multiplex, Luxury Retreat.

Market logic (MainStreetMarket.ts)

• canPurchaseUpgrade now enforces business.level === (card.requiredLevel ?? 0).
• purchaseUpgrade records card.id into business.appliedUpgrades and applies the same level match for explicit targetSlot paths.
• findTargetBusinessSlot(state, card) — shared helper; used by both market logic and the UI to avoid duplicating the matching predicate.
• getUpgradeBranchesForBusiness(state, slotIndex) — returns all market upgrades valid for a given street slot; >1 result signals a branching choice.

// Two cards target the same business at level 0 → player must choose
const branches = getUpgradeBranchesForBusiness(state, slotIndex);
// branches = [{ name: 'Upgrade to IMAX Theater', ... }, { name: 'Upgrade to Drive-In Theater', ... }]

UI (MainStreetScene.ts)

• onUpgradeCardClick calls findTargetBusinessSlot then checks getUpgradeBranchesForBusiness; when >1 branch exists it defers to a modal instead of applying immediately.
• showUpgradeChoiceModal(branches, targetSlot) — new full-screen Phaser overlay listing each branch as a button with name, cost, and stat deltas. Selecting a branch dispatches a buy-upgrade action with the resolved targetSlot; Cancel dismisses without side-effects.

Tests (tests/main-street/upgrades.test.ts)

18 new tests covering: requiredLevel allow/reject, state persistence (level, incomeBonus, synergyRangeBonus, appliedUpgrades), multi-level accumulation, branching detection, branch exclusion after one is taken, and real-pool template assertions (IMAX vs Drive-In trade-offs, Luxury Retreat requiredLevel).

Updated hardcoded template counts in game-state.test.ts and expanded-card-pool.test.ts (17 → 25 upgrade templates).

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Branching & Multi-Level Upgrades</issue_title>
<issue_description>

Summary: Support branching upgrade choices and multi-level upgrade chains for Business cards.

Acceptance Criteria

• PRD lists candidate cards with branching paths and multi-level upgrade examples.
• Card schema supports upgrade levels and branching metadata.
• UI presents an upgrade-choice modal when applicable; chosen branch applies correct stat changes.
• Tests validate upgrade transitions and state persistence.

Minimal Implementation

• Extend card templates with upgrades structure and implement minimal modal UI (placeholder).
• Update purchaseUpgrade flow to apply branch effects and increment level.
• Add tests for upgrade application.

Dependencies

• UI adjustments, Market changes

Deliverables

• PRD upgrade spec, code changes, tests, demo scenario</issue_description>

Comments on the Issue (you are @copilot in this section)

@SorraTheOrc \n\n**OpenCode**\n\nLinked test task: CG-0MMJ9O2AI0M3DKIM created for feature 'Expanded Card Pool (Business + Events)'. @SorraTheOrc \n\n**OpenCode**\n\nLinked test task: CG-0MMJ9O31O1M1845D created for feature 'New Synergy Types & Bridge Cards'. @SorraTheOrc \n\n**OpenCode**\n\nLinked test task: CG-0MMJ9O3T50PWYOBI created for feature 'Challenge System: Definitions, Selection, Evaluation'. @SorraTheOrc \n\n**OpenCode**\n\nLinked test task: CG-0MMJ9O5AP1VJH54C created for feature 'Branching & Multi-Level Upgrades'.

• Fixes TheWizardsCode/Tableau-Card-Engine#114

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.