> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcm.game/llms.txt
> Use this file to discover all available pages before exploring further.

# Sprint 12: Stack & Shift Overhaul

> Implementation of Combinatorial Card Stacking, Client-side Tactical HUD, and Codebase Refactoring.

# Sprint 12: Stack & Shift Overhaul

Sprint 12 introduces the **"Stack & Shift" combinatorial mechanics**, transforming PCMTG's battle system from single-card reveals to a sophisticated tactical staging system. Players can now chain modifiers (`ITEM` and `POLICY` cards) to their base `MEME` cards to shift coordinates, preview vectors in real-time on a glassmorphic Tactical HUD, and check economic cast requirements.

Additionally, this sprint includes a deep-cleaning **Technical Debt & Architectural Cleanup** pass to eliminate all `any` types, achieve a 100% warning-free Next.js production build, and extract duplicate 3D math and quadrant configurations into central, shared helper modules on both backend and frontend.

***

## 🛠 Context & Required Skills for AI Agents

When working on this sprint, agents must adhere to the following technical contexts:

1. **Combinatorial Stacking Rules**:
   * A valid hand stack must contain **exactly one** core `MEME` card acting as the base coordinate anchor.
   * Up to **two** modifier cards (`ITEM` or `POLICY`) can be stacked behind the `MEME` card, *only* if a core `MEME` is already staged.
   * Deselecting the base `MEME` card triggers a cascading selection clear, emptying the entire staged stack.
2. **Euclidean Shifting & Clamping**:
   * Accumulate all modifier axis shifts (`x`, `y`, `z`) *before* applying coordinate bounds limits. Clamping the final coordinate strictly between `[-10, 10]` once at the end (rather than step-by-step) ensures mathematical client-server parity.
3. **No-Implicit-Any Strictness**:
   * Explicit typescript interfaces must define all profile models, result payloads, and card states. The Next.js compiler must build clean in non-interactive production modes.

***

## 🗺 Sprint 12 Roadmap

### \[x] Phase 1: Balanced Hand Deals & Smart Ghost AI

* **Objective:** Ensure player hands have modifier diversity and bots can use them strategically.
* **Tasks**:
  * Refactored both `/queue` and `/inject-ghosts` in `backend/src/routes/debate.js` to deal exactly 2 core `MEME` cards matching the player's affinity, and 2 modifier cards (`ITEM` or `POLICY` type, centrist or matching affinity).
  * Upgraded high-ELO Ghost Bots (ELO >= 1200) to mathematically select and stack optimal modifiers on top of their base card during reveal simulations.

### \[x] Phase 2: Combinatorial Player Hand & 3D Staged HUD

* **Objective:** Give players the ability to stage card stacks with rich, tactile UI.
* **Tasks**:
  * Upgraded `frontend/components/PlayerHand.tsx` into a controlled component governed by `selectedCardIds`.
  * Implemented cascading deselection rules and margin overlapping card fans.
  * Engineered the **Staged Stack HUD** displaying modifier cards stacked behind the base `MEME` card via depth scaling and 3D CSS transforms (slight skewing, rotation, and custom glow backdrops).

### \[x] Phase 3: Tactical preview HUD & Live Wallet Sinks

* **Objective:** Calculate coordinate offsets in real-time and validate casting cost balances.
* **Tasks**:
  * Built a glassmorphic preview dashboard on the Arena page summarizing current coordinates, active offset deltas, and projected coordinate points.
  * Mapped faction currencies directly to player wallets. Enabled dynamic casting cost authorization checks, displaying an **Authorized** transaction status or a glowing **Insufficient Funds** warning panel.

### \[x] Phase 4: Technical Debt Reduction & Consolidated Utilities

* **Objective:** Refactor duplication out of the codebase and secure type-safety.
* **Tasks**:
  * **Shared Backend Module (`backend/src/utils/cardUtils.js`)**: Consolidated quadrant currency mapping arrays, card predicates (`isMeme`, `isModifier`), and coordinate vector summation logic.
  * **Shared Frontend Module (`frontend/lib/cardUtils.ts`)**: Built strong TypeScript typings (`Vector3D`, `UserProfile`, `PlayerResultEntry`) and centralized styling metadata registry entries `QUADRANT_REGISTRY`.
  * **TypeScript Integrity**: Cleared all occurrences of `any` variables inside the page states, hooks, and SVG map visualizers to achieve a compile-clean Next.js production build.

***

## 📡 E2E Verification & Type-Check Results

1. **Frontend Production Compile**:
   ```bash theme={null}
   npm run build
   ```
   * **Result**: `✓ Compiled successfully` and `✓ Finished TypeScript` in 2.4s. Clean, zero-warning production build achieved with all `any` types eliminated.

2. **Backend Post-Match Resolution Test**:
   ```bash theme={null}
   node test-resolve.js
   ```
   * **Result**: Passed 100% successfully. All coordinate summation, ELO calculations, ledger entries, and Firestore state sync operations verified.