# Card Sorting Challenge - Arcade Room Port Plan

## Executive Summary

Porting the Card Sorting Challenge from standalone HTML to the arcade room platform as a single-player game. The game challenges players to arrange abacus cards in ascending order using only visual patterns (no numbers shown).

**Complexity**: Medium - Simpler than matching/memory-quiz (no multiplayer turn logic), but more complex scoring algorithm.

**Timeline Estimate**: 1-2 days for full implementation and testing

---

## 1. Game Analysis

### 1.1 Current Implementation (web_generator.py)

**Core Mechanics**:
- Player selects difficulty (5, 8, 12, or 15 cards)
- Cards displayed in random order with abacus SVGs only (numbers hidden)
- Player arranges cards using click-to-select + click-to-place interaction
- "Reveal Numbers" button available (affects scoring but not shown)
- Timer tracks duration
- Smart scoring algorithm (not just exact position matching)

**Key Features**:
1. **Card Pool**: Uses existing flashcard data (AbacusReact components)
2. **Interaction Model**:
   - Click card → select
   - Click position slot OR insert button (+) → place
   - Click placed card → remove back to available
3. **Position Slots**: Visual gradient from dark (smallest) to light (largest)
4. **Scoring Algorithm** (3 metrics):
   - Longest Common Subsequence (50% weight) - relative order
   - Exact Position Matches (30% weight)  - correct positions
   - Inversion Count (20% weight) - overall organization
5. **Feedback**: Detailed breakdown of score components
6. **Timer**: Tracks elapsed time, displayed in results

**State Management**:
```javascript
{
  cards: [],              // All available cards from flashcards
  sortingCards: [],       // Selected subset for this game
  selectedCount: 5,       // Difficulty setting
  currentOrder: [],       // Cards still available to place
  correctOrder: [],       // Sorted correct answer
  placedCards: [],        // Array of placed cards (null = empty slot)
  selectedCard: null,     // Currently selected card
  numbersRevealed: false, // Whether player used reveal button
  startTime: Date,        // For timer
  timerInterval: null     // Timer interval ID
}
```

### 1.2 Arcade Platform Requirements

**Must implement**:
- SDK-compatible types (GameConfig, GameState, GameMove)
- Server-side Validator class
- Client-side Provider with useArcadeSession
- React component structure (Setup, Playing, Results phases)
- Config persistence to database
- Move validation and state transitions

**Platform Conventions**:
- Phase-based: `setup` → `playing` → `results`
- Standard moves: `START_GAME`, `GO_TO_SETUP`, `SET_CONFIG`
- Pause/Resume pattern (optional for single-player)
- Config changes tracked and persisted

---

## 2. Architecture Design

### 2.1 Directory Structure

```
src/arcade-games/card-sorting/
├── index.ts                      # Game definition & registration
├── types.ts                      # TypeScript type definitions
├── Provider.tsx                  # Client-side state management
├── Validator.ts                  # Server-side game logic
├── components/
│   ├── index.ts                  # Component exports
│   ├── GameComponent.tsx         # Main wrapper component
│   ├── SetupPhase.tsx            # Configuration UI
│   ├── PlayingPhase.tsx          # Main game UI
│   └── ResultsPhase.tsx          # Score display & feedback
└── utils/
    ├── cardGeneration.ts         # Random card selection
    ├── scoringAlgorithm.ts       # LCS, inversions, etc.
    └── validation.ts             # Move validation helpers
```

### 2.2 Type Definitions (types.ts)

```typescript
import type { GameConfig, GameState } from '@/lib/arcade/game-sdk/types'

// ============================================================================
// Configuration
// ============================================================================

export interface CardSortingConfig extends GameConfig {
  cardCount: 5 | 8 | 12 | 15           // Difficulty (number of cards)
  showNumbers: boolean                  // Allow reveal numbers button
  timeLimit: number | null              // Optional time limit (seconds), null = unlimited
}

// ============================================================================
// Core Data Types
// ============================================================================

export type GamePhase = 'setup' | 'playing' | 'results'

export interface SortingCard {
  id: string                            // Unique ID for this card instance
  number: number                        // The abacus value (0-99+)
  svgContent: string                    // Serialized AbacusReact SVG
}

export interface PlacedCard {
  card: SortingCard                     // The card data
  position: number                      // Which slot it's in (0-indexed)
}

export interface ScoreBreakdown {
  finalScore: number                    // 0-100 weighted average
  exactMatches: number                  // Cards in exactly correct position
  lcsLength: number                     // Longest common subsequence length
  inversions: number                    // Number of out-of-order pairs
  relativeOrderScore: number            // 0-100 based on LCS
  exactPositionScore: number            // 0-100 based on exact matches
  inversionScore: number                // 0-100 based on inversions
  elapsedTime: number                   // Seconds taken
  numbersRevealed: boolean              // Whether player used reveal
}

// ============================================================================
// Game State
// ============================================================================

export interface CardSortingState extends GameState {
  // Configuration
  cardCount: 5 | 8 | 12 | 15
  showNumbers: boolean
  timeLimit: number | null

  // Game phase
  gamePhase: GamePhase

  // Player & timing
  playerId: string                      // Single player ID
  playerMetadata: PlayerMetadata        // Player display info
  gameStartTime: number | null
  gameEndTime: number | null

  // Cards
  selectedCards: SortingCard[]          // The N cards for this game
  correctOrder: SortingCard[]           // Sorted by number (answer key)
  availableCards: SortingCard[]         // Cards not yet placed
  placedCards: (SortingCard | null)[]   // Array of N slots (null = empty)

  // UI state (client-only, not in server state)
  selectedCardId: string | null         // Currently selected card
  numbersRevealed: boolean              // If player revealed numbers

  // Results
  scoreBreakdown: ScoreBreakdown | null // Final score details

  // Pause/Resume (standard pattern)
  originalConfig?: CardSortingConfig
  pausedGamePhase?: GamePhase
  pausedGameState?: {
    selectedCards: SortingCard[]
    availableCards: SortingCard[]
    placedCards: (SortingCard | null)[]
    gameStartTime: number
    numbersRevealed: boolean
  }
}

// ============================================================================
// Game Moves
// ============================================================================

export type CardSortingMove =
  | {
      type: 'START_GAME'
      playerId: string
      userId: string
      timestamp: number
      data: {
        playerMetadata: PlayerMetadata
        selectedCards: SortingCard[]  // Pre-selected random cards
      }
    }
  | {
      type: 'PLACE_CARD'
      playerId: string
      userId: string
      timestamp: number
      data: {
        cardId: string               // Which card to place
        position: number             // Which slot (0-indexed)
      }
    }
  | {
      type: 'REMOVE_CARD'
      playerId: string
      userId: string
      timestamp: number
      data: {
        position: number             // Which slot to remove from
      }
    }
  | {
      type: 'REVEAL_NUMBERS'
      playerId: string
      userId: string
      timestamp: number
      data: {}
    }
  | {
      type: 'CHECK_SOLUTION'
      playerId: string
      userId: string
      timestamp: number
      data: {}
    }
  | {
      type: 'GO_TO_SETUP'
      playerId: string
      userId: string
      timestamp: number
      data: {}
    }
  | {
      type: 'SET_CONFIG'
      playerId: string
      userId: string
      timestamp: number
      data: {
        field: 'cardCount' | 'showNumbers' | 'timeLimit'
        value: any
      }
    }
  | {
      type: 'RESUME_GAME'
      playerId: string
      userId: string
      timestamp: number
      data: {}
    }

// ============================================================================
// Component Props
// ============================================================================

export interface SortingCardProps {
  card: SortingCard
  isSelected: boolean
  isPlaced: boolean
  isCorrect?: boolean          // After checking solution
  onClick: () => void
  showNumber: boolean          // If revealed
}

export interface PositionSlotProps {
  position: number
  card: SortingCard | null
  isActive: boolean            // If slot is clickable
  isCorrect?: boolean          // After checking solution
  gradientStyle: React.CSSProperties
  onClick: () => void
}

export interface ScoreDisplayProps {
  breakdown: ScoreBreakdown
  correctOrder: SortingCard[]
  userOrder: SortingCard[]
  onNewGame: () => void
  onExit: () => void
}
```

### 2.3 Validator (Validator.ts)

**Responsibilities**:
- Validate all moves server-side
- Calculate scores when checking solution
- Manage state transitions
- Generate initial state from config

**Key Methods**:

```typescript
class CardSortingValidator implements GameValidator<CardSortingState, CardSortingMove> {

  validateMove(state, move, context): ValidationResult {
    switch (move.type) {
      case 'START_GAME':
        return this.validateStartGame(state, move.data)
      case 'PLACE_CARD':
        return this.validatePlaceCard(state, move.data.cardId, move.data.position)
      case 'REMOVE_CARD':
        return this.validateRemoveCard(state, move.data.position)
      case 'REVEAL_NUMBERS':
        return this.validateRevealNumbers(state)
      case 'CHECK_SOLUTION':
        return this.validateCheckSolution(state)
      case 'GO_TO_SETUP':
        return this.validateGoToSetup(state)
      case 'SET_CONFIG':
        return this.validateSetConfig(state, move.data.field, move.data.value)
      case 'RESUME_GAME':
        return this.validateResumeGame(state)
    }
  }

  // Core validation methods
  private validatePlaceCard(state, cardId, position): ValidationResult {
    // Must be in playing phase
    // Card must exist in availableCards
    // Position must be valid (0 to cardCount-1)
    // Position can be null (insert) or occupied (swap logic)

    const card = state.availableCards.find(c => c.id === cardId)
    if (!card) return { valid: false, error: 'Card not found' }

    if (position < 0 || position >= state.cardCount) {
      return { valid: false, error: 'Invalid position' }
    }

    // Create new state with card placed
    const newAvailable = state.availableCards.filter(c => c.id !== cardId)
    const newPlaced = [...state.placedCards]

    // Shift logic (compress gaps to left)
    // ... implementation similar to web_generator.py

    return {
      valid: true,
      newState: {
        ...state,
        availableCards: newAvailable,
        placedCards: newPlaced
      }
    }
  }

  private validateCheckSolution(state): ValidationResult {
    // All slots must be filled
    if (state.placedCards.some(c => c === null)) {
      return { valid: false, error: 'Must place all cards first' }
    }

    // Calculate score using scoring algorithms
    const userSequence = state.placedCards.map(c => c!.number)
    const correctSequence = state.correctOrder.map(c => c.number)

    const scoreBreakdown = this.calculateScore(
      userSequence,
      correctSequence,
      state.gameStartTime,
      state.numbersRevealed
    )

    return {
      valid: true,
      newState: {
        ...state,
        gamePhase: 'results',
        gameEndTime: Date.now(),
        scoreBreakdown
      }
    }
  }

  // Scoring algorithm (port from web_generator.py)
  private calculateScore(userSeq, correctSeq, startTime, revealed): ScoreBreakdown {
    const lcs = this.longestCommonSubsequence(userSeq, correctSeq)
    const exactMatches = userSeq.filter((n, i) => n === correctSeq[i]).length
    const inversions = this.countInversions(userSeq, correctSeq)

    const relativeOrderScore = (lcs / correctSeq.length) * 100
    const exactPositionScore = (exactMatches / correctSeq.length) * 100
    const maxInversions = (correctSeq.length * (correctSeq.length - 1)) / 2
    const inversionScore = Math.max(0, ((maxInversions - inversions) / maxInversions) * 100)

    const finalScore = Math.round(
      relativeOrderScore * 0.5 +
      exactPositionScore * 0.3 +
      inversionScore * 0.2
    )

    return {
      finalScore,
      exactMatches,
      lcsLength: lcs,
      inversions,
      relativeOrderScore: Math.round(relativeOrderScore),
      exactPositionScore: Math.round(exactPositionScore),
      inversionScore: Math.round(inversionScore),
      elapsedTime: Math.floor((Date.now() - startTime) / 1000),
      numbersRevealed: revealed
    }
  }

  private longestCommonSubsequence(seq1, seq2): number {
    // Dynamic programming LCS algorithm
    // Port from web_generator.py lines 9470-9486
  }

  private countInversions(userSeq, correctSeq): number {
    // Count out-of-order pairs
    // Port from web_generator.py lines 9488-9509
  }

  getInitialState(config: CardSortingConfig): CardSortingState {
    return {
      cardCount: config.cardCount,
      showNumbers: config.showNumbers,
      timeLimit: config.timeLimit,
      gamePhase: 'setup',
      playerId: '',
      playerMetadata: {},
      gameStartTime: null,
      gameEndTime: null,
      selectedCards: [],
      correctOrder: [],
      availableCards: [],
      placedCards: new Array(config.cardCount).fill(null),
      selectedCardId: null,
      numbersRevealed: false,
      scoreBreakdown: null
    }
  }
}
```

### 2.4 Provider (Provider.tsx)

**Responsibilities**:
- Wrap children with context provider
- Integrate with useArcadeSession hook
- Provide action creators (startGame, placeCard, etc.)
- Handle optimistic updates for smooth UX
- Manage local UI state (selected card highlight, etc.)

**Key Implementation**:

```typescript
export function CardSortingProvider({ children }: { children: ReactNode }) {
  const { data: viewerId } = useViewerId()
  const { roomData } = useRoomData()
  const { activePlayers, players } = useGameMode()
  const { mutate: updateGameConfig } = useUpdateGameConfig()

  // Get local player (single player game)
  const localPlayerId = useMemo(() => {
    return Array.from(activePlayers).find(id => {
      const player = players.get(id)
      return player?.isLocal
    })
  }, [activePlayers, players])

  // Merge saved config with defaults
  const initialState = useMemo((): CardSortingState => {
    const savedConfig = roomData?.gameConfig?.['card-sorting']

    return {
      cardCount: savedConfig?.cardCount ?? 5,
      showNumbers: savedConfig?.showNumbers ?? true,
      timeLimit: savedConfig?.timeLimit ?? null,
      gamePhase: 'setup',
      // ... rest of initial state
    }
  }, [roomData?.gameConfig])

  // Arcade session integration
  const {
    state: serverState,
    sendMove,
    exitSession,
    lastError,
    clearError,
  } = useArcadeSession<CardSortingState>({
    userId: viewerId || '',
    roomId: roomData?.id,
    initialState,
    applyMove: applyMoveOptimistically,  // For responsive UI
  })

  // Local UI state (not synced)
  const [localUIState, setLocalUIState] = useState({
    selectedCardId: null as string | null,
    highlightedSlot: null as number | null,
  })

  // Action creators
  const startGame = useCallback(() => {
    if (!localPlayerId) return

    const playerMetadata = buildPlayerMetadata(
      [localPlayerId],
      {},
      players,
      viewerId
    )

    // Generate random cards
    const selectedCards = generateRandomCards(serverState.cardCount)

    sendMove({
      type: 'START_GAME',
      playerId: localPlayerId,
      userId: viewerId || '',
      data: { playerMetadata, selectedCards }
    })
  }, [localPlayerId, serverState.cardCount, sendMove])

  const placeCard = useCallback((cardId: string, position: number) => {
    if (!localPlayerId) return

    sendMove({
      type: 'PLACE_CARD',
      playerId: localPlayerId,
      userId: viewerId || '',
      data: { cardId, position }
    })

    // Clear local selection
    setLocalUIState(prev => ({ ...prev, selectedCardId: null }))
  }, [localPlayerId, sendMove])

  const removeCard = useCallback((position: number) => {
    if (!localPlayerId) return

    sendMove({
      type: 'REMOVE_CARD',
      playerId: localPlayerId,
      userId: viewerId || '',
      data: { position }
    })
  }, [localPlayerId, sendMove])

  const checkSolution = useCallback(() => {
    if (!localPlayerId) return

    sendMove({
      type: 'CHECK_SOLUTION',
      playerId: localPlayerId,
      userId: viewerId || '',
      data: {}
    })
  }, [localPlayerId, sendMove])

  const revealNumbers = useCallback(() => {
    if (!localPlayerId) return

    sendMove({
      type: 'REVEAL_NUMBERS',
      playerId: localPlayerId,
      userId: viewerId || '',
      data: {}
    })
  }, [localPlayerId, sendMove])

  // ... other action creators (goToSetup, setConfig, etc.)

  // Computed values
  const canCheckSolution = serverState.placedCards.every(c => c !== null)
  const placedCount = serverState.placedCards.filter(c => c !== null).length
  const elapsedTime = serverState.gameStartTime
    ? Math.floor((Date.now() - serverState.gameStartTime) / 1000)
    : 0

  const contextValue = {
    state: serverState,
    localUIState,
    setLocalUIState,

    // Actions
    startGame,
    placeCard,
    removeCard,
    checkSolution,
    revealNumbers,
    goToSetup,
    setConfig,
    resumeGame,
    exitSession,

    // Computed
    canCheckSolution,
    placedCount,
    elapsedTime,

    // Helpers
    selectCard: (cardId: string | null) => {
      setLocalUIState(prev => ({ ...prev, selectedCardId: cardId }))
    },
  }

  return (
    <CardSortingContext.Provider value={contextValue}>
      {children}
    </CardSortingContext.Provider>
  )
}
```

### 2.5 Component Structure

#### SetupPhase.tsx

**Purpose**: Configure game before starting

**UI Elements**:
- Card count selector (5, 8, 12, 15) - button group
- Show numbers toggle - checkbox
- Time limit selector - dropdown (unlimited, 1min, 2min, 3min, 5min)
- Start Game button
- Resume Game button (if paused game exists)

**Implementation**:
```tsx
export function SetupPhase() {
  const { state, setConfig, startGame, resumeGame } = useCardSorting()
  const canResume = state.pausedGamePhase && !hasConfigChanged()

  return (
    <div className={css({ ... })}>
      <h2>Card Sorting Challenge</h2>
      <p>Arrange cards in order using only abacus patterns</p>

      <div className={css({ /* card count buttons */ })}>
        {[5, 8, 12, 15].map(count => (
          <button
            key={count}
            onClick={() => setConfig('cardCount', count)}
            className={css({ /* active if selected */ })}
          >
            {count} Cards
          </button>
        ))}
      </div>

      <label>
        <input
          type="checkbox"
          checked={state.showNumbers}
          onChange={(e) => setConfig('showNumbers', e.target.checked)}
        />
        Allow "Reveal Numbers" button
      </label>

      <div className={css({ /* button group */ })}>
        {canResume && (
          <button onClick={resumeGame}>Resume Game</button>
        )}
        <button onClick={startGame}>Start New Game</button>
      </div>
    </div>
  )
}
```

#### PlayingPhase.tsx

**Purpose**: Main game interface

**UI Sections**:
1. **Header (sticky)**:
   - Timer display (MM:SS)
   - Status message ("5/8 cards placed", etc.)
   - Action buttons: Check Solution, Reveal Numbers, End Game

2. **Two-column layout**:
   - Left: Available cards grid
   - Right: Position slots (sequential, gradient background)

3. **Card interaction**:
   - Click card → select (highlight border)
   - Click slot → place selected card
   - Click + button → insert at position
   - Click placed card → remove to available

**Implementation**:
```tsx
export function PlayingPhase() {
  const {
    state,
    localUIState,
    selectCard,
    placeCard,
    removeCard,
    checkSolution,
    revealNumbers,
    goToSetup,
    canCheckSolution,
    placedCount,
    elapsedTime
  } = useCardSorting()

  const handleCardClick = (card: SortingCard) => {
    if (localUIState.selectedCardId === card.id) {
      selectCard(null)  // Deselect
    } else {
      selectCard(card.id)
    }
  }

  const handleSlotClick = (position: number) => {
    if (!localUIState.selectedCardId) {
      // Remove card if slot is occupied
      if (state.placedCards[position]) {
        removeCard(position)
      }
    } else {
      // Place selected card
      placeCard(localUIState.selectedCardId, position)
    }
  }

  const formatTime = (seconds: number) => {
    const m = Math.floor(seconds / 60)
    const s = seconds % 60
    return `${m}:${s.toString().padStart(2, '0')}`
  }

  const getGradientStyle = (position: number, total: number) => {
    const intensity = position / (total - 1)
    const lightness = 30 + (intensity * 45)
    return {
      background: `hsl(220, 8%, ${lightness}%)`,
      color: lightness > 60 ? '#2c3e50' : '#ffffff',
    }
  }

  return (
    <div>
      {/* Sticky header */}
      <div className={css({ position: 'sticky', top: 0, ... })}>
        <div>
          <span>Time: {formatTime(elapsedTime)}</span>
          <span>{placedCount}/{state.cardCount} placed</span>
        </div>
        <div>
          <button
            onClick={checkSolution}
            disabled={!canCheckSolution}
          >
            Check Solution
          </button>
          {state.showNumbers && !state.numbersRevealed && (
            <button onClick={revealNumbers}>
              Reveal Numbers
            </button>
          )}
          <button onClick={goToSetup}>End Game</button>
        </div>
      </div>

      {/* Main game area */}
      <div className={css({ display: 'flex', gap: '2rem' })}>
        {/* Available cards */}
        <div className={css({ flex: 1 })}>
          <h3>Available Cards</h3>
          <div className={css({ display: 'grid', gap: '1rem', ... })}>
            {state.availableCards.map(card => (
              <SortingCard
                key={card.id}
                card={card}
                isSelected={localUIState.selectedCardId === card.id}
                isPlaced={false}
                showNumber={state.numbersRevealed}
                onClick={() => handleCardClick(card)}
              />
            ))}
          </div>
        </div>

        {/* Position slots */}
        <div className={css({ flex: 2 })}>
          <h3>Sort Positions (Smallest → Largest)</h3>
          <div className={css({ display: 'flex', flexDirection: 'column', gap: '0.5rem' })}>
            {state.placedCards.map((card, index) => (
              <div key={index} className={css({ display: 'flex', alignItems: 'center' })}>
                <PositionSlot
                  position={index}
                  card={card}
                  isActive={!!localUIState.selectedCardId || !!card}
                  gradientStyle={getGradientStyle(index, state.cardCount)}
                  onClick={() => handleSlotClick(index)}
                />
              </div>
            ))}
          </div>
        </div>
      </div>
    </div>
  )
}
```

#### ResultsPhase.tsx

**Purpose**: Display score and feedback

**UI Elements**:
- Final score (0-100%)
- Performance message (Perfect! / Excellent! / Good! / Keep practicing!)
- Detailed breakdown:
  - Exact position matches (X/N cards)
  - Relative order score (LCS-based)
  - Organization score (inversion-based)
  - Time taken
  - Whether numbers were revealed
- Visual comparison: user order vs correct order
- Action buttons: New Game, Change Settings, Exit

**Implementation**:
```tsx
export function ResultsPhase() {
  const { state, startGame, goToSetup, exitSession } = useCardSorting()
  const { scoreBreakdown } = state

  if (!scoreBreakdown) return null

  const getMessage = (score: number) => {
    if (score === 100) return '🎉 Perfect! All cards in correct order!'
    if (score >= 80) return '👍 Excellent! Very close to perfect!'
    if (score >= 60) return '👍 Good job! You understand the pattern!'
    return '💪 Keep practicing! Focus on reading each abacus carefully.'
  }

  const getEmoji = (score: number) => {
    if (score === 100) return '🏆'
    if (score >= 80) return '⭐'
    if (score >= 60) return '👍'
    return '📈'
  }

  return (
    <div className={css({ ... })}>
      {/* Score display */}
      <div className={css({ textAlign: 'center', mb: '2rem' })}>
        <div className={css({ fontSize: '4rem' })}>
          {getEmoji(scoreBreakdown.finalScore)}
        </div>
        <h2>Your Score: {scoreBreakdown.finalScore}%</h2>
        <p>{getMessage(scoreBreakdown.finalScore)}</p>
      </div>

      {/* Detailed breakdown */}
      <div className={css({ ... })}>
        <h3>Score Breakdown</h3>

        <div>
          <label>Exact Position Matches (30%)</label>
          <progress value={scoreBreakdown.exactPositionScore} max={100} />
          <span>{scoreBreakdown.exactMatches}/{state.cardCount} cards</span>
        </div>

        <div>
          <label>Relative Order (50%)</label>
          <progress value={scoreBreakdown.relativeOrderScore} max={100} />
          <span>{scoreBreakdown.lcsLength}/{state.cardCount} in correct sequence</span>
        </div>

        <div>
          <label>Organization (20%)</label>
          <progress value={scoreBreakdown.inversionScore} max={100} />
          <span>{scoreBreakdown.inversions} out-of-order pairs</span>
        </div>

        <div>
          <label>Time Taken</label>
          <span>{scoreBreakdown.elapsedTime}s</span>
        </div>

        {scoreBreakdown.numbersRevealed && (
          <div className={css({ color: 'orange' })}>
            ⚠️ Numbers were revealed during play
          </div>
        )}
      </div>

      {/* Visual comparison */}
      <div className={css({ ... })}>
        <h3>Comparison</h3>
        <div>
          <h4>Your Answer:</h4>
          <div className={css({ display: 'flex', gap: '0.5rem' })}>
            {state.placedCards.map((card, i) => (
              <MiniCard
                key={i}
                card={card!}
                isCorrect={card!.number === state.correctOrder[i].number}
              />
            ))}
          </div>
        </div>
        <div>
          <h4>Correct Order:</h4>
          <div className={css({ display: 'flex', gap: '0.5rem' })}>
            {state.correctOrder.map((card, i) => (
              <MiniCard key={i} card={card} showNumber />
            ))}
          </div>
        </div>
      </div>

      {/* Actions */}
      <div className={css({ ... })}>
        <button onClick={startGame}>New Game (Same Settings)</button>
        <button onClick={goToSetup}>Change Settings</button>
        <button onClick={exitSession}>Exit to Room</button>
      </div>
    </div>
  )
}
```

---

## 3. Implementation Details

### 3.1 Card Generation

**Source**: AbacusReact components from the existing flashcard system

**Approach**:
```typescript
// utils/cardGeneration.ts

import { AbacusReact } from '@soroban/abacus-react'
import { renderToString } from 'react-dom/server'
import type { SortingCard } from '../types'

/**
 * Generate random cards for sorting game
 * @param count Number of cards to generate
 * @param minValue Minimum abacus value (default 0)
 * @param maxValue Maximum abacus value (default 99)
 */
export function generateRandomCards(
  count: number,
  minValue: number = 0,
  maxValue: number = 99
): SortingCard[] {
  // Generate pool of unique random numbers
  const numbers = new Set<number>()
  while (numbers.size < count) {
    const num = Math.floor(Math.random() * (maxValue - minValue + 1)) + minValue
    numbers.add(num)
  }

  // Convert to sorted array (for answer key)
  const sortedNumbers = Array.from(numbers).sort((a, b) => a - b)

  // Create card objects with SVG content
  return sortedNumbers.map((number, index) => {
    // Render AbacusReact to SVG string
    const svgContent = renderToString(
      <AbacusReact
        value={number}
        width={200}
        height={120}
        // ... other props for consistent styling
      />
    )

    return {
      id: `card-${index}-${number}`,
      number,
      svgContent
    }
  })
}

/**
 * Shuffle array for random order
 */
export function shuffleCards(cards: SortingCard[]): SortingCard[] {
  const shuffled = [...cards]
  for (let i = shuffled.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1))
    ;[shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]]
  }
  return shuffled
}
```

### 3.2 Scoring Algorithms

**Port from web_generator.py** (lines 9425-9509)

```typescript
// utils/scoringAlgorithm.ts

/**
 * Calculate Longest Common Subsequence length
 * Measures how many cards are in correct relative order
 */
export function longestCommonSubsequence(seq1: number[], seq2: number[]): number {
  const m = seq1.length
  const n = seq2.length
  const dp: number[][] = Array(m + 1).fill(0).map(() => Array(n + 1).fill(0))

  for (let i = 1; i <= m; i++) {
    for (let j = 1; j <= n; j++) {
      if (seq1[i - 1] === seq2[j - 1]) {
        dp[i][j] = dp[i - 1][j - 1] + 1
      } else {
        dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1])
      }
    }
  }

  return dp[m][n]
}

/**
 * Count inversions (out-of-order pairs)
 * Measures how scrambled the sequence is
 */
export function countInversions(userSeq: number[], correctSeq: number[]): number {
  // Create mapping from value to correct position
  const correctPositions: Record<number, number> = {}
  correctSeq.forEach((val, idx) => {
    correctPositions[val] = idx
  })

  // Convert user sequence to correct-position sequence
  const userCorrectPositions = userSeq.map(val => correctPositions[val])

  // Count inversions
  let inversions = 0
  for (let i = 0; i < userCorrectPositions.length; i++) {
    for (let j = i + 1; j < userCorrectPositions.length; j++) {
      if (userCorrectPositions[i] > userCorrectPositions[j]) {
        inversions++
      }
    }
  }

  return inversions
}

/**
 * Calculate comprehensive score breakdown
 */
export function calculateScore(
  userSequence: number[],
  correctSequence: number[],
  startTime: number,
  numbersRevealed: boolean
): ScoreBreakdown {
  // LCS-based score (relative order)
  const lcsLength = longestCommonSubsequence(userSequence, correctSequence)
  const relativeOrderScore = (lcsLength / correctSequence.length) * 100

  // Exact position matches
  let exactMatches = 0
  for (let i = 0; i < userSequence.length; i++) {
    if (userSequence[i] === correctSequence[i]) {
      exactMatches++
    }
  }
  const exactPositionScore = (exactMatches / correctSequence.length) * 100

  // Inversion-based score (organization)
  const inversions = countInversions(userSequence, correctSequence)
  const maxInversions = (correctSequence.length * (correctSequence.length - 1)) / 2
  const inversionScore = Math.max(
    0,
    ((maxInversions - inversions) / maxInversions) * 100
  )

  // Weighted final score
  // - 50% for relative order (LCS)
  // - 30% for exact positions
  // - 20% for organization (inversions)
  const finalScore = Math.round(
    relativeOrderScore * 0.5 +
    exactPositionScore * 0.3 +
    inversionScore * 0.2
  )

  return {
    finalScore,
    exactMatches,
    lcsLength,
    inversions,
    relativeOrderScore: Math.round(relativeOrderScore),
    exactPositionScore: Math.round(exactPositionScore),
    inversionScore: Math.round(inversionScore),
    elapsedTime: Math.floor((Date.now() - startTime) / 1000),
    numbersRevealed
  }
}
```

### 3.3 Card Placement Logic

**Challenge**: Maintaining array compaction (no gaps) when placing/removing cards

**Approach**:
```typescript
// utils/validation.ts

/**
 * Place a card at a specific position, shifting existing cards
 * Returns new placedCards array with no gaps
 */
export function placeCardAtPosition(
  placedCards: (SortingCard | null)[],
  cardToPlace: SortingCard,
  position: number,
  totalSlots: number
): (SortingCard | null)[] {
  // Create working array
  const newPlaced = new Array(totalSlots).fill(null)

  // Copy existing cards, shifting those at/after position
  for (let i = 0; i < placedCards.length; i++) {
    if (placedCards[i] !== null) {
      if (i < position) {
        // Before insert position - stays same
        newPlaced[i] = placedCards[i]
      } else {
        // At or after position - shift right
        if (i + 1 < totalSlots) {
          newPlaced[i + 1] = placedCards[i]
        }
      }
    }
  }

  // Place new card
  newPlaced[position] = cardToPlace

  // Compact to remove gaps (shift all cards left)
  const compacted: SortingCard[] = []
  for (const card of newPlaced) {
    if (card !== null) {
      compacted.push(card)
    }
  }

  // Fill final array
  const result = new Array(totalSlots).fill(null)
  for (let i = 0; i < Math.min(compacted.length, totalSlots); i++) {
    result[i] = compacted[i]
  }

  // Any excess cards are returned (shouldn't happen)
  const excess = compacted.slice(totalSlots)

  return { placedCards: result, excessCards: excess }
}

/**
 * Remove card at position
 */
export function removeCardAtPosition(
  placedCards: (SortingCard | null)[],
  position: number
): { placedCards: (SortingCard | null)[], removedCard: SortingCard | null } {
  const removedCard = placedCards[position]

  if (!removedCard) {
    return { placedCards, removedCard: null }
  }

  // Remove card and compact
  const compacted: SortingCard[] = []
  for (let i = 0; i < placedCards.length; i++) {
    if (i !== position && placedCards[i] !== null) {
      compacted.push(placedCards[i]!)
    }
  }

  // Fill new array
  const newPlaced = new Array(placedCards.length).fill(null)
  for (let i = 0; i < compacted.length; i++) {
    newPlaced[i] = compacted[i]
  }

  return { placedCards: newPlaced, removedCard }
}
```

### 3.4 Styling with Panda CSS

**Pattern**: Use Panda CSS `css()` function for all styling

**Key Style Patterns**:

```typescript
// Gradient for position slots
const slotGradient = (position: number, total: number) => {
  const intensity = position / (total - 1)
  const lightness = 30 + intensity * 45  // 30% to 75%

  return css({
    background: `hsl(220, 8%, ${lightness}%)`,
    color: lightness > 60 ? '#2c3e50' : '#ffffff',
    borderColor: lightness > 60 ? '#2c5f76' : 'rgba(255,255,255,0.4)',
    padding: '1rem',
    borderRadius: '8px',
    border: '2px solid',
    transition: 'all 0.3s ease',
    cursor: 'pointer',

    '&:hover': {
      transform: 'translateY(-2px)',
      boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
    }
  })
}

// Card styling
const cardStyle = css({
  background: 'white',
  borderRadius: '8px',
  padding: '0.5rem',
  border: '2px solid',
  borderColor: 'gray.300',
  cursor: 'pointer',
  transition: 'all 0.2s ease',
  position: 'relative',

  '&:hover': {
    transform: 'translateY(-4px)',
    boxShadow: '0 6px 16px rgba(0,0,0,0.2)',
    borderColor: 'blue.500',
  },

  '&.selected': {
    borderColor: 'blue.600',
    background: 'blue.50',
    transform: 'scale(1.05)',
  },

  '&.placed': {
    opacity: 0.7,
    transform: 'scale(0.95)',
  },

  '&.correct': {
    borderColor: 'green.500',
    background: 'green.50',
  },

  '&.incorrect': {
    borderColor: 'red.500',
    background: 'red.50',
    animation: 'shake 0.5s ease',
  }
})

// Shake animation (for incorrect cards)
const shakeAnimation = css.raw({
  '@keyframes shake': {
    '0%, 100%': { transform: 'translateX(0)' },
    '25%': { transform: 'translateX(-10px)' },
    '75%': { transform: 'translateX(10px)' },
  }
})
```

---

## 4. Game Registration

### 4.1 Game Definition (index.ts)

```typescript
import { defineGame } from '@/lib/arcade/game-sdk'
import type { GameManifest } from '@/lib/arcade/game-sdk'
import { GameComponent } from './components/GameComponent'
import { CardSortingProvider } from './Provider'
import { cardSortingValidator } from './Validator'
import type { CardSortingConfig, CardSortingMove, CardSortingState } from './types'

const manifest: GameManifest = {
  name: 'card-sorting',
  displayName: 'Card Sorting Challenge',
  icon: '🔢',
  description: 'Sort abacus cards using pattern recognition',
  longDescription:
    'Challenge your abacus reading skills! Arrange cards in ascending order using only ' +
    'the visual patterns - no numbers shown. Perfect for practicing number recognition and ' +
    'developing mental math intuition.',
  maxPlayers: 1,  // Single player only
  difficulty: 'Intermediate',
  chips: ['🧠 Pattern Recognition', '🎯 Solo Challenge', '📊 Smart Scoring'],
  color: 'teal',
  gradient: 'linear-gradient(135deg, #99f6e4, #5eead4)',
  borderColor: 'teal.200',
  available: true,
}

const defaultConfig: CardSortingConfig = {
  cardCount: 8,
  showNumbers: true,
  timeLimit: null,
}

function validateCardSortingConfig(config: unknown): config is CardSortingConfig {
  if (typeof config !== 'object' || config === null) return false

  const c = config as any

  if (!('cardCount' in c) || ![5, 8, 12, 15].includes(c.cardCount)) {
    return false
  }

  if (!('showNumbers' in c) || typeof c.showNumbers !== 'boolean') {
    return false
  }

  if ('timeLimit' in c) {
    if (c.timeLimit !== null && (typeof c.timeLimit !== 'number' || c.timeLimit < 30)) {
      return false
    }
  }

  return true
}

export const cardSortingGame = defineGame<
  CardSortingConfig,
  CardSortingState,
  CardSortingMove
>({
  manifest,
  Provider: CardSortingProvider,
  GameComponent,
  validator: cardSortingValidator,
  defaultConfig,
  validateConfig: validateCardSortingConfig,
})
```

### 4.2 Registration in game-registry.ts

```typescript
// Add import
import { cardSortingGame } from '@/arcade-games/card-sorting'

// Add registration
registerGame(cardSortingGame)
```

### 4.3 Validator Registration

```typescript
// src/lib/arcade/validators.ts

import { cardSortingValidator } from '@/arcade-games/card-sorting/Validator'

export const validatorRegistry = {
  matching: matchingGameValidator,
  'memory-quiz': memoryQuizGameValidator,
  'complement-race': complementRaceValidator,
  'card-sorting': cardSortingValidator,  // ADD THIS
} as const
```

### 4.4 Config Types

```typescript
// src/lib/arcade/game-configs.ts

import type { cardSortingGame } from '@/arcade-games/card-sorting'

export type CardSortingGameConfig = InferGameConfig<typeof cardSortingGame>

export type GameConfigByName = {
  'memory-quiz': MemoryQuizGameConfig
  matching: MatchingGameConfig
  'complement-race': ComplementRaceGameConfig
  'card-sorting': CardSortingGameConfig,  // ADD THIS
}

export const DEFAULT_CARD_SORTING_CONFIG: CardSortingGameConfig = {
  cardCount: 8,
  showNumbers: true,
  timeLimit: null,
}
```

---

## 5. Testing Strategy

### 5.1 Unit Tests

**Scoring algorithms** (utils/scoringAlgorithm.test.ts):
```typescript
describe('longestCommonSubsequence', () => {
  it('should return length of identical sequences', () => {
    expect(longestCommonSubsequence([1,2,3], [1,2,3])).toBe(3)
  })

  it('should find LCS in scrambled sequence', () => {
    expect(longestCommonSubsequence([3,1,2], [1,2,3])).toBe(2) // [1,2]
  })
})

describe('countInversions', () => {
  it('should return 0 for sorted sequence', () => {
    expect(countInversions([1,2,3], [1,2,3])).toBe(0)
  })

  it('should count inversions correctly', () => {
    expect(countInversions([3,2,1], [1,2,3])).toBe(3)
  })
})

describe('calculateScore', () => {
  it('should return 100% for perfect solution', () => {
    const result = calculateScore([1,2,3], [1,2,3], Date.now(), false)
    expect(result.finalScore).toBe(100)
  })

  it('should apply weighted scoring correctly', () => {
    const result = calculateScore([2,1,3], [1,2,3], Date.now(), false)
    // Should be less than 100 but greater than 0
    expect(result.finalScore).toBeGreaterThan(0)
    expect(result.finalScore).toBeLessThan(100)
  })
})
```

**Card placement logic** (utils/validation.test.ts):
```typescript
describe('placeCardAtPosition', () => {
  it('should place card in empty slot', () => {
    const placed = [null, null, null]
    const card = { id: '1', number: 5, svgContent: '' }
    const result = placeCardAtPosition(placed, card, 0, 3)

    expect(result.placedCards[0]).toBe(card)
    expect(result.placedCards[1]).toBe(null)
  })

  it('should shift existing cards when inserting', () => {
    const card1 = { id: '1', number: 5, svgContent: '' }
    const card2 = { id: '2', number: 3, svgContent: '' }
    const placed = [card1, null, null]

    const result = placeCardAtPosition(placed, card2, 0, 3)

    expect(result.placedCards[0]).toBe(card2)
    expect(result.placedCards[1]).toBe(card1)
  })
})
```

### 5.2 Integration Tests

**Validator** (Validator.test.ts):
```typescript
describe('CardSortingValidator', () => {
  const validator = new CardSortingValidator()

  describe('validateMove', () => {
    it('should validate PLACE_CARD move', () => {
      const state = validator.getInitialState({ cardCount: 5, ... })
      // ... setup state with cards

      const move = {
        type: 'PLACE_CARD',
        data: { cardId: 'card-1', position: 0 }
      }

      const result = validator.validateMove(state, move)
      expect(result.valid).toBe(true)
    })

    it('should reject CHECK_SOLUTION when not all cards placed', () => {
      const state = validator.getInitialState({ cardCount: 5, ... })
      // ... partial placement

      const move = { type: 'CHECK_SOLUTION', ... }
      const result = validator.validateMove(state, move)

      expect(result.valid).toBe(false)
      expect(result.error).toContain('place all cards')
    })
  })
})
```

### 5.3 E2E Tests (Playwright)

**Full game flow**:
```typescript
test('complete card sorting game flow', async ({ page }) => {
  // Navigate to arcade room
  await page.goto('/arcade/room/test-room')

  // Start card sorting game
  await page.click('[data-game="card-sorting"]')

  // Setup phase
  await page.click('[data-card-count="5"]')
  await page.click('button:has-text("Start New Game")')

  // Playing phase
  await expect(page.locator('.available-cards')).toBeVisible()
  await expect(page.locator('.position-slots')).toBeVisible()

  // Place all 5 cards (automated for test)
  for (let i = 0; i < 5; i++) {
    await page.click('.available-cards .sort-card').first()
    await page.click(`.position-slot[data-position="${i}"]`)
  }

  // Check solution
  await page.click('button:has-text("Check Solution")')

  // Results phase
  await expect(page.locator('.results-phase')).toBeVisible()
  await expect(page.locator(':text("Your Score:")')).toBeVisible()
})
```

---

## 6. Migration Checklist

### Phase 1: Setup & Types (Day 1 Morning)
- [ ] Create directory structure
- [ ] Define types.ts (Config, State, Moves)
- [ ] Create Validator.ts skeleton
- [ ] Set up unit test files
- [ ] Register game in game-registry.ts
- [ ] Add to validators.ts
- [ ] Add config types to game-configs.ts

### Phase 2: Core Logic (Day 1 Afternoon)
- [ ] Implement scoring algorithms (LCS, inversions)
- [ ] Write unit tests for scoring
- [ ] Implement card generation utilities
- [ ] Implement placement logic utilities
- [ ] Write tests for placement logic
- [ ] Complete Validator implementation
- [ ] Write validator integration tests

### Phase 3: Provider & Components (Day 2 Morning)
- [ ] Implement Provider.tsx
- [ ] Create SetupPhase.tsx
- [ ] Create PlayingPhase.tsx component structure
- [ ] Implement card selection/placement interaction
- [ ] Test with mock state

### Phase 4: UI Polish & Results (Day 2 Afternoon)
- [ ] Complete ResultsPhase.tsx
- [ ] Implement timer display
- [ ] Add gradient styling for slots
- [ ] Add animations (card placement, shake for incorrect)
- [ ] Responsive design testing
- [ ] Accessibility (keyboard navigation)

### Phase 5: Testing & Refinement (Day 2 Evening)
- [ ] Manual testing full flow
- [ ] Write E2E tests
- [ ] Test config persistence
- [ ] Test pause/resume
- [ ] Performance testing (15 cards)
- [ ] Fix any bugs
- [ ] Code review & cleanup

### Phase 6: Documentation (Bonus)
- [ ] Update README.md
- [ ] Add JSDoc comments
- [ ] Create gameplay screenshots
- [ ] Update arcade games list

---

## 7. Known Challenges & Solutions

### Challenge 1: Rendering AbacusReact to String
**Issue**: Need SVG string for serialization, but AbacusReact is a React component

**Solution**: Use `renderToString` from `react-dom/server`
```typescript
import { renderToString } from 'react-dom/server'

const svgContent = renderToString(
  <AbacusReact value={number} width={200} height={120} />
)
```

**Alternative**: Pre-generate SVG strings for common values (0-99) and cache them

### Challenge 2: Card Array Compaction
**Issue**: Complex logic for maintaining no-gap array when inserting/removing

**Solution**:
- Extract to utility function with thorough tests
- Use two-pass approach: calculate new positions, then compact
- Return excess cards separately if overflow occurs

### Challenge 3: State Synchronization (Selected Card)
**Issue**: Selected card is UI-only state, shouldn't be in server state

**Solution**:
- Keep `selectedCardId` in local state (Provider's `localUIState`)
- Don't include in moves or server state
- Clear on successful placement

### Challenge 4: Timer in Single-Player
**Issue**: Timer should run client-side, not in server state

**Solution**:
- Store only `gameStartTime` in server state
- Calculate `elapsedTime` as computed value in Provider
- Use `useEffect` + `setInterval` for live updates

### Challenge 5: Scoring Algorithm Performance
**Issue**: LCS algorithm is O(n²), might be slow for 15 cards

**Solution**:
- 15 cards = 225 operations, negligible
- Run on server-side (Validator) only when checking solution
- No real-time performance concerns

---

## 8. Future Enhancements (Out of Scope)

**Multiplayer Mode**:
- Race mode: First to complete wins
- Turn-based: Take turns placing cards
- Collaborative: Work together on same puzzle

**Advanced Features**:
- Leaderboard (best scores per difficulty)
- Daily challenge (same cards for everyone)
- Hint system (show correct position for one card)
- Undo/redo functionality
- Custom card ranges (two-digit only, three-digit, etc.)

**Accessibility**:
- Keyboard-only controls (arrow keys + space)
- Screen reader announcements
- High contrast mode
- Configurable card sizes

---

## 9. Success Criteria

**Functional Requirements**:
✅ Player can select difficulty (5, 8, 12, 15 cards)
✅ Cards display only abacus patterns (no numbers)
✅ Cards can be placed/removed via click interaction
✅ Reveal numbers button works (if enabled)
✅ Timer tracks elapsed time
✅ Scoring algorithm matches original (LCS + exact + inversions)
✅ Results show detailed breakdown
✅ Config persists to database
✅ Pause/resume works

**Technical Requirements**:
✅ Follows arcade SDK patterns (defineGame, Validator, Provider)
✅ Uses Panda CSS for styling
✅ Type-safe (no `any` types)
✅ Passes all unit tests
✅ Passes validator tests
✅ E2E test covers full flow
✅ No console errors/warnings
✅ Responsive on mobile/tablet/desktop

**UX Requirements**:
✅ Smooth animations (card placement, results)
✅ Clear visual feedback (selected card, correct/incorrect)
✅ Intuitive controls (click-to-select, click-to-place)
✅ Accessible (keyboard, screen readers)
✅ Performant (60fps animations, instant interaction)

---

## 10. Appendix

### A. File Sizes Estimate

```
index.ts                 ~80 lines
types.ts                 ~350 lines
Provider.tsx             ~500 lines
Validator.ts             ~600 lines
GameComponent.tsx        ~100 lines
SetupPhase.tsx           ~150 lines
PlayingPhase.tsx         ~400 lines
ResultsPhase.tsx         ~300 lines
SortingCard.tsx          ~100 lines
PositionSlot.tsx         ~80 lines
cardGeneration.ts        ~100 lines
scoringAlgorithm.ts      ~200 lines
validation.ts            ~150 lines
-----------------------------------
TOTAL:                   ~3,110 lines
```

### B. Dependencies

**New dependencies**: None - all required packages already in project
- `@soroban/abacus-react` (already installed)
- `react-dom/server` (already available)
- Panda CSS (already configured)

### C. Performance Benchmarks

**Expected performance**:
- Card generation (15 cards): <50ms
- LCS calculation (15 cards): <5ms
- Inversion count (15 cards): <2ms
- Full score calculation: <10ms
- Card placement validation: <1ms
- State update cycle: <16ms (60fps)

### D. Accessibility Checklist

- [ ] All interactive elements keyboard accessible
- [ ] Tab order logical (cards → slots → buttons)
- [ ] Focus indicators visible
- [ ] ARIA labels for abacus SVGs
- [ ] Screen reader announcements for state changes
- [ ] Color contrast meets WCAG AA
- [ ] No reliance on color alone for feedback

---

## Summary

This plan provides a complete blueprint for porting the Card Sorting Challenge to the arcade platform. The game is well-scoped for single-player, has clear mechanics, and leverages existing patterns from matching/memory-quiz games.

**Key Simplifications vs Multiplayer Games**:
- No turn management
- No player-vs-player scoring
- Simpler state (one player, one set of cards)
- No real-time synchronization needs

**Key Complexities**:
- Sophisticated scoring algorithm (3 metrics)
- Card placement/removal logic (array compaction)
- Detailed results visualization

**Timeline**: 1-2 days for experienced developer familiar with the codebase

**Risk Level**: Low - well-defined scope, proven algorithms, existing patterns to follow
