┌─────────────────────────────────────────────────────────────────────────────┐
│                    FARMING IN PURRIA ENGINEERING PRINCIPLES                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. PLAYER FIRST                                                            │
│     Every technical decision serves the player experience.                  │
│     60fps on mobile. Instant feedback. No jank.                            │
│                                                                             │
│  2. TYPE SAFETY END-TO-END                                                  │
│     From database to UI, types are the contract.                           │
│     If it compiles, it should work.                                        │
│                                                                             │
│  3. EXPLICIT OVER CLEVER                                                    │
│     Readable code beats clever code.                                       │
│     The next developer is you in 6 months.                                 │
│                                                                             │
│  4. SMALL, COMPOSABLE PIECES                                                │
│     Functions do one thing. Components render one thing.                   │
│     Composition over inheritance.                                          │
│                                                                             │
│  5. FAIL FAST, RECOVER GRACEFULLY                                           │
│     Validate inputs immediately. Handle errors at boundaries.              │
│     Players should never see stack traces.                                 │
│                                                                             │
│  6. MEASURE EVERYTHING                                                       │
│     If we can't measure it, we can't improve it.                           │
│     Telemetry is not optional.                                             │
│                                                                             │
│  7. OPTIMIZE LAST                                                            │
│     Make it work. Make it right. Make it fast.                             │
│     Profile before optimizing.                                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              TECH STACK                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  FRONTEND                          BACKEND                                  │
│  ────────                          ───────                                  │
│  React 18+                         Hono                                     │
│  TanStack Router                   tRPC                                     │
│  Zustand                           Drizzle ORM                              │
│  Tailwind CSS                      SQLite/Turso                             │
│  shadcn/ui                         Bun runtime                              │
│  Framer Motion                     Zod validation                           │
│                                                                             │
│  TOOLING                           INFRASTRUCTURE                           │
│  ───────                           ──────────────                           │
│  TypeScript 5+                     Cloudflare Pages                         │
│  Biome (lint/format)               Cloudflare Workers                       │
│  Vitest                            GitHub Actions                           │
│  Playwright (E2E)                  PostHog analytics                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

// Type-safe FSM with explicit transitions
type GamePhase = 'morning' | 'action' | 'resolution' | 'night';

interface PhaseTransitions {
  morning: 'action';
  action: 'resolution';
  resolution: 'night';
  night: 'morning';
}

type NextPhase<T extends GamePhase> = PhaseTransitions[T];

class GamePhaseMachine {
  private phase: GamePhase = 'morning';
  
  transition(): void {
    const transitions: Record<GamePhase, GamePhase> = {
      morning: 'action',
      action: 'resolution',
      resolution: 'night',
      night: 'morning',
    };
    
    this.phase = transitions[this.phase];
    this.onPhaseEnter(this.phase);
  }
  
  private onPhaseEnter(phase: GamePhase): void {
    // Phase-specific initialization
  }
}

interface Command {
  execute(): void;
  undo(): void;
  description: string;
}

class PlaceBetCommand implements Command {
  constructor(
    private potId: string,
    private betType: BetType,
    private amount: number,
    private gameState: GameState
  ) {}
  
  execute(): void {
    this.gameState.placeBet(this.potId, this.betType, this.amount);
  }
  
  undo(): void {
    this.gameState.removeBet(this.potId);
    this.gameState.refundCoins(this.amount);
  }
  
  get description() {
    return `Bet ${this.amount} on ${this.potId}`;
  }
}

class CommandHistory {
  private history: Command[] = [];
  private pointer = -1;
  
  execute(command: Command): void {
    // Clear redo stack
    this.history = this.history.slice(0, this.pointer + 1);
    command.execute();
    this.history.push(command);
    this.pointer++;
  }
  
  undo(): void {
    if (this.pointer >= 0) {
      this.history[this.pointer].undo();
      this.pointer--;
    }
  }
  
  redo(): void {
    if (this.pointer < this.history.length - 1) {
      this.pointer++;
      this.history[this.pointer].execute();
    }
  }
}

type GameEvent = 
  | { type: 'POT_THRESHOLD_REACHED'; potId: string; threshold: number }
  | { type: 'TROUBLE_SPAWNED'; hexId: string; troubleType: TroubleType }
  | { type: 'SIMULIN_LEVELED'; simulinId: string; newLevel: number }
  | { type: 'TRIGGER_EARNED'; trigger: TriggerType }
  | { type: 'DAY_COMPLETED'; dayNumber: number };

type EventHandler<T extends GameEvent['type']> = (
  event: Extract<GameEvent, { type: T }>
) => void;

class GameEventBus {
  private handlers = new Map<GameEvent['type'], Set<EventHandler<any>>>();
  
  on<T extends GameEvent['type']>(type: T, handler: EventHandler<T>): () => void {
    if (!this.handlers.has(type)) {
      this.handlers.set(type, new Set());
    }
    this.handlers.get(type)!.add(handler);
    
    // Return unsubscribe function
    return () => this.handlers.get(type)?.delete(handler);
  }
  
  emit(event: GameEvent): void {
    const handlers = this.handlers.get(event.type);
    if (handlers) {
      handlers.forEach(handler => handler(event));
    }
  }
}

// Usage
const events = new GameEventBus();

// Trigger system listens for pot events
events.on('POT_THRESHOLD_REACHED', ({ potId, threshold }) => {
  if (threshold === 100) {
    checkForPerfectReadTrigger();
  }
});

class ObjectPool<T> {
  private pool: T[] = [];
  private activeCount = 0;
  
  constructor(
    private factory: () => T,
    private reset: (obj: T) => void,
    initialSize = 10
  ) {
    for (let i = 0; i < initialSize; i++) {
      this.pool.push(factory());
    }
  }
  
  acquire(): T {
    if (this.activeCount >= this.pool.length) {
      this.pool.push(this.factory());
    }
    return this.pool[this.activeCount++];
  }
  
  release(obj: T): void {
    const index = this.pool.indexOf(obj);
    if (index !== -1 && index < this.activeCount) {
      this.reset(obj);
      // Swap with last active
      [this.pool[index], this.pool[this.activeCount - 1]] = 
        [this.pool[this.activeCount - 1], this.pool[index]];
      this.activeCount--;
    }
  }
  
  releaseAll(): void {
    for (let i = 0; i < this.activeCount; i++) {
      this.reset(this.pool[i]);
    }
    this.activeCount = 0;
  }
}

interface ScoringStrategy {
  calculateScore(results: DayResults): number;
  getName(): string;
}

class StandardScoring implements ScoringStrategy {
  calculateScore(results: DayResults): number {
    return results.potsWon * 100 + results.troubleCleared * 50;
  }
  getName() { return 'Standard'; }
}

class HarvestPhaseScoring implements ScoringStrategy {
  calculateScore(results: DayResults): number {
    // 3x multiplier during harvest phase
    return (results.potsWon * 100 + results.troubleCleared * 50) * 3;
  }
  getName() { return 'Harvest Bonus'; }
}

class GameScorer {
  constructor(private strategy: ScoringStrategy) {}
  
  setStrategy(strategy: ScoringStrategy): void {
    this.strategy = strategy;
  }
  
  score(results: DayResults): number {
    return this.strategy.calculateScore(results);
  }
}

class SeededRNG {
  private seed: number;
  
  constructor(seed: number = Date.now()) {
    this.seed = seed;
  }
  
  // Mulberry32 - fast, good distribution
  next(): number {
    let t = this.seed += 0x6D2B79F5;
    t = Math.imul(t ^ t >>> 15, t | 1);
    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
    return ((t ^ t >>> 14) >>> 0) / 4294967296;
  }
  
  // Range helpers
  nextInt(min: number, max: number): number {
    return Math.floor(this.next() * (max - min + 1)) + min;
  }
  
  nextFloat(min: number, max: number): number {
    return this.next() * (max - min) + min;
  }
  
  // Shuffle array (Fisher-Yates)
  shuffle<T>(array: T[]): T[] {
    const result = [...array];
    for (let i = result.length - 1; i > 0; i--) {
      const j = this.nextInt(0, i);
      [result[i], result[j]] = [result[j], result[i]];
    }
    return result;
  }
  
  // Weighted random selection
  weightedChoice<T>(items: T[], weights: number[]): T {
    const totalWeight = weights.reduce((a, b) => a + b, 0);
    let random = this.next() * totalWeight;
    
    for (let i = 0; i < items.length; i++) {
      random -= weights[i];
      if (random <= 0) return items[i];
    }
    return items[items.length - 1];
  }
}

// Usage with verifiable seed
const daySeed = hashString(`${seasonId}-day-${dayNumber}`);
const rng = new SeededRNG(daySeed);

interface Card {
  suit: 'hearts' | 'diamonds' | 'clubs' | 'spades';
  rank: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
}

class Deck {
  private cards: Card[] = [];
  private discardPile: Card[] = [];
  
  constructor(private rng: SeededRNG) {
    this.reset();
  }
  
  reset(): void {
    this.cards = [];
    this.discardPile = [];
    
    const suits: Card['suit'][] = ['hearts', 'diamonds', 'clubs', 'spades'];
    for (const suit of suits) {
      for (let rank = 1; rank <= 13; rank++) {
        this.cards.push({ suit, rank: rank as Card['rank'] });
      }
    }
    
    this.shuffle();
  }
  
  shuffle(): void {
    this.cards = this.rng.shuffle(this.cards);
  }
  
  draw(count = 1): Card[] {
    if (this.cards.length < count) {
      // Reshuffle discard pile into deck
      this.cards = [...this.cards, ...this.rng.shuffle(this.discardPile)];
      this.discardPile = [];
    }
    
    return this.cards.splice(0, count);
  }
  
  discard(cards: Card[]): void {
    this.discardPile.push(...cards);
  }
  
  get remaining(): number {
    return this.cards.length;
  }
  
  peek(count = 1): Card[] {
    return this.cards.slice(0, count);
  }
}

type HandRank = 
  | 'high-card'
  | 'pair'
  | 'two-pair'
  | 'three-of-a-kind'
  | 'straight'
  | 'flush'
  | 'full-house'
  | 'four-of-a-kind'
  | 'straight-flush'
  | 'royal-flush';

interface HandResult {
  rank: HandRank;
  value: number;        // For comparing same-rank hands
  cards: Card[];        // The 5 cards making the hand
  kickers: Card[];      // Remaining cards for tiebreakers
}

class PokerHandEvaluator {
  evaluate(cards: Card[]): HandResult {
    if (cards.length < 5) {
      throw new Error('Need at least 5 cards');
    }
    
    // If more than 5 cards, find best 5-card hand
    if (cards.length > 5) {
      return this.findBestHand(cards);
    }
    
    const sorted = [...cards].sort((a, b) => b.rank - a.rank);
    const isFlush = this.checkFlush(sorted);
    const straightRank = this.checkStraight(sorted);
    const groups = this.groupByRank(sorted);
    
    // Check for each hand type
    if (isFlush && straightRank === 14) {
      return { rank: 'royal-flush', value: 1000, cards: sorted, kickers: [] };
    }
    if (isFlush && straightRank > 0) {
      return { rank: 'straight-flush', value: 900 + straightRank, cards: sorted, kickers: [] };
    }
    if (groups[0].length === 4) {
      return this.buildResult('four-of-a-kind', 800, groups, sorted);
    }
    if (groups[0].length === 3 && groups[1]?.length === 2) {
      return this.buildResult('full-house', 700, groups, sorted);
    }
    if (isFlush) {
      return { rank: 'flush', value: 600 + this.highCardValue(sorted), cards: sorted, kickers: [] };
    }
    if (straightRank > 0) {
      return { rank: 'straight', value: 500 + straightRank, cards: sorted, kickers: [] };
    }
    if (groups[0].length === 3) {
      return this.buildResult('three-of-a-kind', 400, groups, sorted);
    }
    if (groups[0].length === 2 && groups[1]?.length === 2) {
      return this.buildResult('two-pair', 300, groups, sorted);
    }
    if (groups[0].length === 2) {
      return this.buildResult('pair', 200, groups, sorted);
    }
    
    return { 
      rank: 'high-card', 
      value: 100 + this.highCardValue(sorted), 
      cards: sorted, 
      kickers: sorted.slice(1) 
    };
  }
  
  private checkFlush(cards: Card[]): boolean {
    return cards.every(c => c.suit === cards[0].suit);
  }
  
  private checkStraight(cards: Card[]): number {
    const ranks = cards.map(c => c.rank).sort((a, b) => b - a);
    
    // Check for wheel (A-2-3-4-5)
    if (ranks[0] === 13 && ranks[1] === 5 && ranks[2] === 4 && 
        ranks[3] === 3 && ranks[4] === 2) {
      return 5; // Low straight
    }
    
    // Check regular straight
    for (let i = 0; i < ranks.length - 1; i++) {
      if (ranks[i] - ranks[i + 1] !== 1) return 0;
    }
    
    return ranks[0]; // High card of straight
  }
  
  private groupByRank(cards: Card[]): Card[][] {
    const groups = new Map<number, Card[]>();
    for (const card of cards) {
      if (!groups.has(card.rank)) groups.set(card.rank, []);
      groups.get(card.rank)!.push(card);
    }
    return Array.from(groups.values()).sort((a, b) => {
      if (a.length !== b.length) return b.length - a.length;
      return b[0].rank - a[0].rank;
    });
  }
  
  private highCardValue(cards: Card[]): number {
    return cards.reduce((acc, c, i) => acc + c.rank * Math.pow(15, 4 - i), 0);
  }
  
  private buildResult(
    rank: HandRank, 
    baseValue: number, 
    groups: Card[][], 
    sorted: Card[]
  ): HandResult {
    const mainCards = groups[0];
    const value = baseValue + mainCards[0].rank;
    return { rank, value, cards: sorted, kickers: groups.slice(1).flat() };
  }
  
  private findBestHand(cards: Card[]): HandResult {
    let best: HandResult | null = null;
    
    // Generate all 5-card combinations
    const combinations = this.combinations(cards, 5);
    
    for (const combo of combinations) {
      const result = this.evaluate(combo);
      if (!best || result.value > best.value) {
        best = result;
      }
    }
    
    return best!;
  }
  
  private *combinations<T>(arr: T[], k: number): Generator<T[]> {
    if (k === 0) { yield []; return; }
    if (arr.length < k) return;
    
    const [first, ...rest] = arr;
    for (const combo of this.combinations(rest, k - 1)) {
      yield [first, ...combo];
    }
    yield* this.combinations(rest, k);
  }
}