Add roadmap docs

docs/cards_wip/card_system_implementation_summary.md

@@ -0,0 +1,112 @@
+# Card State Machine Implementation Summary
+
+## Architecture Overview
+
+**Isolated State Pattern** using Pixelplacement StateMachine:
+
+```
+Card (RectTransform - primary animation target)
+├─ CardDisplay (always visible)
+├─ CardContext (shared references)
+├─ CardAnimator (reusable animations)
+└─ CardStateMachine (AppleMachine)
+    ├─ IdleState/
+    ├─ FlippingState/
+    │   └─ CardBackVisual ← State owns this
+    ├─ EnlargedNewState/
+    │   └─ NewCardBadge ← State owns this
+    └─ EnlargedRepeatState/
+        └─ ProgressBarUI ← State owns this
+```
+
+## Key Design Decisions
+
+### 1. State-Owned Visuals
+- State-specific GameObjects (CardBackVisual, NewCardBadge, etc.) are **children of their state GameObject**
+- When state activates → children activate automatically
+- When state deactivates → children deactivate automatically
+- **No manual visibility management needed!**
+
+### 2. Transform Animation
+- **Root Card.transform** is animated for position/scale (affects all children via Unity hierarchy)
+- **State child visuals** can be animated independently (e.g., rotating CardBackVisual during flip)
+- States decide WHAT to animate, CardAnimator provides HOW
+
+### 3. Shared Resources
+- `CardContext` component provides states access to:
+  - CardDisplay
+  - CardAnimator
+  - StateMachine
+  - CardData
+  - IsNewCard flag
+- States call `_context.Animator.PlayFlip(...)` instead of duplicating tween code
+
+### 4. State Transitions
+States explicitly transition via `_context.StateMachine.ChangeState("StateName")`
+
+Example flow:
+```
+IdleState 
+  [click] → FlippingState 
+    [flip complete + IsNew] → EnlargedNewState 
+      [tap] → RevealedState
+```
+
+## Files Created
+
+**Core Components:**
+- `CardContext.cs` - Shared context accessible to all states
+- `CardAnimator.cs` - Reusable animation methods
+- `CardAnimationConfig.cs` - ScriptableObject for designer tweaks
+
+**State Implementations:**
+- `States/CardIdleState.cs` - Hover animation, click to flip
+- `States/CardFlippingState.cs` - Owns CardBackVisual, flip animation
+- `States/CardRevealedState.cs` - Waiting for interaction
+- `States/CardEnlargedNewState.cs` - Owns NewCardBadge, tap to dismiss
+- `States/CardEnlargedRepeatState.cs` - Owns ProgressBarUI, tap to dismiss
+
+## Next Steps
+
+1. **Create remaining states:**
+   - `CardDraggingState` (for album placement flow)
+   - `CardPlacedInSlotState` (album slot interaction)
+   - `CardAlbumEnlargedState` (enlarge from album)
+
+2. **Build Card prefab:**
+   - Setup hierarchy with state children
+   - Assign CardBackVisual, NewCardBadge, ProgressBarUI to states
+   - Create CardAnimationConfig asset
+
+3. **Migrate existing code:**
+   - Update BoosterOpeningPage to use new Card
+   - Update AlbumViewPage to use new Card
+   - Remove old wrapper scripts (FlippableCard, AlbumCard, etc.)
+
+## Benefits vs Old System
+
+| Aspect | Old System | New System |
+|--------|-----------|------------|
+| Components per card | 5+ wrappers | 1 root + states |
+| Animation code duplication | ~150 lines across 4 files | 0 (shared CardAnimator) |
+| State tracking | 12+ boolean flags | 1 state machine |
+| Visual element management | Manual SetActive calls | Automatic via state activation |
+| Adding new behaviors | Modify 3-4 components | Add 1 new state GameObject |
+| Prefab nesting | 5 layers deep | Flat (states as children) |
+| Debugging state | Check 12 booleans | Look at active state name |
+
+## Example: Adding New State
+
+Want to add a "Trading" state where card shows trade UI?
+
+**Old system:** Modify FlippableCard, AlbumCard, add new wrapper, update events, etc.
+
+**New system:**
+1. Create `CardTradingState.cs`
+2. Add `TradingState` GameObject under CardStateMachine
+3. Add trade UI as child of TradingState
+4. Implement `OnEnterState()` to show UI
+5. Call `ChangeState("TradingState")` from wherever needed
+
+Done! No other files touched.
+