name: game-engineering-team
description: AAA-caliber engineering council for building production-quality games. Use when implementing game systems, writing game code, designing data architecture, building UI components, creating tutorials, optimizing performance, or any technical game development task. Covers game programming patterns, casino/card game implementation, reward systems, game UI engineering, tutorial design, code architecture, data infrastructure, security, and quality assurance. Triggers on requests for game code, system implementation, refactoring, performance optimization, data design, or technical architecture decisions.

Game Engineering Team

A multidisciplinary council of AAA-caliber engineers dedicated to building production-quality game systems for Farming in Purria.

The Engineering Council

Core Game Engineers (6)

UI/UX Engineers (5)

Data & Infrastructure (5)

Quality & Craft (4)

Integration Specialists (4)

Part I: Core Engineering Principles

The Engineering Manifesto

┌─────────────────────────────────────────────────────────────────────────────┐
│                    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.                                             │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

The Technical Stack

┌─────────────────────────────────────────────────────────────────────────────┐
│                              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                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Part II: Game Programming Patterns

Pattern 1: Finite State Machines (FSM)

When to Use: Phase management, UI states, game mode transitions

// 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
  }
}

Pattern 2: Command Pattern (Undo/Redo)

When to Use: Bet placement, farm actions, any reversible operation

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();
    }
  }
}

Pattern 3: Observer Pattern (Event Bus)

When to Use: Cross-system communication, triggers, achievements

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();
  }
});

Pattern 4: Object Pool (Performance)

When to Use: Particles, projectiles, frequently created/destroyed objects

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;
  }
}

Pattern 5: Strategy Pattern (Interchangeable Algorithms)

When to Use: AI behaviors, scoring algorithms, difficulty modes

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);
  }
}

Part III: Casino & Card Game Implementation

Random Number Generation

Critical: Use cryptographically secure, seedable RNG for fair play.

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);

Card Deck Management

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);
  }
}

Poker Hand Evaluation

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);
  }
}

Pot/Betting System

type BetType = 'fold' | 'call' | 'raise' | 'all-in';

interface Pot {
  id: string;
  name: string;
  currentFill: number;     // 0-100
  thresholds: number[];    // [50, 80, 100]
  payoutMultipliers: Record<BetType, number[]>; // Per threshold
}

interface Bet {
  potId: string;
  betType: BetType;
  amount: number;
  placedAt: Date;
}

class BettingSystem {
  private bets: Bet[] = [];

  placeBet(potId: string, betType: BetType, amount: number): Bet {
    // Validate bet
    if (betType !== 'fold' && amount <= 0) {
      throw new Error('Bet amount must be positive');
    }

    // Check for existing bet on this pot
    const existing = this.bets.find(b => b.potId === potId);
    if (existing) {
      throw new Error('Already bet on this pot');
    }

    const bet: Bet = {
      potId,
      betType,
      amount: betType === 'fold' ? 0 : amount,
      placedAt: new Date(),
    };

    this.bets.push(bet);
    return bet;
  }

  resolveBets(pots: Pot[]): BetResult[] {
    const results: BetResult[] = [];

    for (const bet of this.bets) {
      const pot = pots.find(p => p.id === bet.potId);
      if (!pot) continue;

      const result = this.resolveSingleBet(bet, pot);
      results.push(result);
    }

    this.bets = [];
    return results;
  }

  private resolveSingleBet(bet: Bet, pot: Pot): BetResult {
    // Find highest threshold reached
    let thresholdIndex = -1;
    for (let i = pot.thresholds.length - 1; i >= 0; i--) {
      if (pot.currentFill >= pot.thresholds[i]) {
        thresholdIndex = i;
        break;
      }
    }

    // Fold always returns nothing
    if (bet.betType === 'fold') {
      return { bet, won: false, payout: 0, thresholdReached: thresholdIndex };
    }

    // No threshold reached = loss
    if (thresholdIndex < 0) {
      return { bet, won: false, payout: 0, thresholdReached: -1 };
    }

    // Calculate payout
    const multiplier = pot.payoutMultipliers[bet.betType][thresholdIndex];
    const payout = Math.floor(bet.amount * multiplier);

    return { 
      bet, 
      won: true, 
      payout, 
      thresholdReached: thresholdIndex,
      multiplier 
    };
  }
}

interface BetResult {
  bet: Bet;
  won: boolean;
  payout: number;
  thresholdReached: number;
  multiplier?: number;
}

Part IV: Reward & Progression Systems

Experience Curves

// Common XP curve formulas
const XP_CURVES = {
  // Linear: Simple, predictable
  linear: (level: number, base: number) => base * level,

  // Quadratic: Steeper growth
  quadratic: (level: number, base: number) => base * level * level,

  // Exponential: Slow start, rapid growth
  exponential: (level: number, base: number, rate: number) => 
    base * Math.pow(rate, level),

  // Polynomial: Customizable curve
  polynomial: (level: number, base: number, power: number) => 
    Math.floor(base * Math.pow(level, power)),

  // Fibonacci-like: Natural feeling progression
  fibonacci: (level: number, base: number) => {
    if (level <= 1) return base;
    let [a, b] = [base, base * 2];
    for (let i = 2; i < level; i++) {
      [a, b] = [b, a + b];
    }
    return b;
  },
};

class ProgressionSystem {
  constructor(
    private xpForLevel: (level: number) => number,
    private maxLevel: number = 100
  ) {}

  getLevel(totalXP: number): number {
    let level = 1;
    let xpNeeded = 0;

    while (level <= this.maxLevel) {
      xpNeeded += this.xpForLevel(level);
      if (totalXP < xpNeeded) break;
      level++;
    }

    return Math.min(level, this.maxLevel);
  }

  getProgress(totalXP: number): { level: number; current: number; needed: number; percent: number } {
    const level = this.getLevel(totalXP);
    const xpForCurrent = this.getTotalXPForLevel(level);
    const xpForNext = this.xpForLevel(level + 1);
    const current = totalXP - xpForCurrent;

    return {
      level,
      current,
      needed: xpForNext,
      percent: Math.floor((current / xpForNext) * 100),
    };
  }

  private getTotalXPForLevel(level: number): number {
    let total = 0;
    for (let i = 1; i < level; i++) {
      total += this.xpForLevel(i);
    }
    return total;
  }
}

// Simulin bonding uses gentle curve
const simulinProgression = new ProgressionSystem(
  (level) => XP_CURVES.polynomial(level, 100, 1.5),
  25 // Max bond level
);

Trigger & Combo System

interface DailyTrigger {
  type: TriggerType;
  earnedAt: Date;
  dayNumber: number;
  metadata?: Record<string, any>;
}

type TriggerType = 
  | 'first_bloom'
  | 'perfect_read'
  | 'trouble_slayer'
  | 'growth_spurt'
  | 'simulin_sync';

type ComboHandType = 
  | 'pair'
  | 'two_pair'
  | 'three_of_a_kind'
  | 'straight'
  | 'full_house'
  | 'flush'
  | 'four_of_a_kind'
  | 'straight_flush'
  | 'royal_flush';

class ComboEngine {
  private readonly HAND_VALUES: Record<ComboHandType, number> = {
    'pair': 2,
    'two_pair': 3,
    'three_of_a_kind': 5,
    'straight': 10,
    'full_house': 15,
    'flush': 20,
    'four_of_a_kind': 25,
    'straight_flush': 50,
    'royal_flush': 100,
  };

  evaluateWeek(triggers: DailyTrigger[]): ComboResult {
    // Group triggers by type
    const byType = new Map<TriggerType, number>();
    for (const trigger of triggers) {
      byType.set(trigger.type, (byType.get(trigger.type) || 0) + 1);
    }

    const counts = Array.from(byType.values()).sort((a, b) => b - a);
    const uniqueTypes = byType.size;
    const totalTriggers = triggers.length;

    // Evaluate hand (highest first)
    let handType: ComboHandType | null = null;

    // Royal Flush: All 5 types, perfect execution
    if (uniqueTypes === 5 && counts.every(c => c >= 1) && this.isPerfectSequence(triggers)) {
      handType = 'royal_flush';
    }
    // Straight Flush: 5 consecutive days, same category
    else if (this.isConsecutiveDays(triggers, 5) && this.hasCategoryMatch(triggers)) {
      handType = 'straight_flush';
    }
    // Four of a Kind
    else if (counts[0] >= 4) {
      handType = 'four_of_a_kind';
    }
    // Flush: 5 of same type
    else if (counts[0] >= 5) {
      handType = 'flush';
    }
    // Full House: 3 + 2
    else if (counts[0] >= 3 && counts[1] >= 2) {
      handType = 'full_house';
    }
    // Straight: 5 different in sequence
    else if (this.isConsecutiveDays(triggers, 5) && uniqueTypes >= 5) {
      handType = 'straight';
    }
    // Three of a Kind
    else if (counts[0] >= 3) {
      handType = 'three_of_a_kind';
    }
    // Two Pair
    else if (counts[0] >= 2 && counts[1] >= 2) {
      handType = 'two_pair';
    }
    // Pair
    else if (counts[0] >= 2) {
      handType = 'pair';
    }

    return {
      triggers,
      handType,
      multiplier: handType ? this.HAND_VALUES[handType] : 1,
      breakdown: Object.fromEntries(byType),
    };
  }

  private isConsecutiveDays(triggers: DailyTrigger[], required: number): boolean {
    const days = [...new Set(triggers.map(t => t.dayNumber))].sort((a, b) => a - b);
    let consecutive = 1;

    for (let i = 1; i < days.length; i++) {
      if (days[i] - days[i-1] === 1) {
        consecutive++;
        if (consecutive >= required) return true;
      } else {
        consecutive = 1;
      }
    }

    return consecutive >= required;
  }

  private hasCategoryMatch(triggers: DailyTrigger[]): boolean {
    // Define categories
    const categories: Record<string, TriggerType[]> = {
      betting: ['first_bloom', 'perfect_read'],
      farming: ['growth_spurt', 'trouble_slayer'],
      companion: ['simulin_sync'],
    };

    // Check if all triggers are from same category
    for (const types of Object.values(categories)) {
      if (triggers.every(t => types.includes(t.type))) {
        return true;
      }
    }
    return false;
  }

  private isPerfectSequence(triggers: DailyTrigger[]): boolean {
    // Perfect sequence: all 5 trigger types in optimal order
    const idealOrder: TriggerType[] = [
      'first_bloom', 'growth_spurt', 'trouble_slayer', 'perfect_read', 'simulin_sync'
    ];

    const byDay = new Map<number, TriggerType>();
    for (const t of triggers) {
      if (!byDay.has(t.dayNumber)) {
        byDay.set(t.dayNumber, t.type);
      }
    }

    const sequence = Array.from(byDay.entries())
      .sort(([a], [b]) => a - b)
      .map(([_, type]) => type);

    return sequence.length === 5 && 
           sequence.every((type, i) => type === idealOrder[i]);
  }
}

interface ComboResult {
  triggers: DailyTrigger[];
  handType: ComboHandType | null;
  multiplier: number;
  breakdown: Record<TriggerType, number>;
}

Part V: UI Engineering Patterns

Component Architecture

// Compound Component Pattern for complex UI
interface SlotMachineContext {
  spinning: boolean;
  result: SlotResult | null;
  spin: () => void;
}

const SlotMachineContext = createContext<SlotMachineContext | null>(null);

function SlotMachine({ children }: { children: React.ReactNode }) {
  const [spinning, setSpinning] = useState(false);
  const [result, setResult] = useState<SlotResult | null>(null);

  const spin = useCallback(async () => {
    setSpinning(true);
    const newResult = await api.spin();
    setResult(newResult);
    setSpinning(false);
  }, []);

  return (
    <SlotMachineContext.Provider value={{ spinning, result, spin }}>
      <div className="slot-machine">{children}</div>
    </SlotMachineContext.Provider>
  );
}

// Sub-components
SlotMachine.Reel = function Reel({ index }: { index: number }) {
  const ctx = useContext(SlotMachineContext);
  // ...render reel
};

SlotMachine.SpinButton = function SpinButton() {
  const ctx = useContext(SlotMachineContext);
  return (
    <button onClick={ctx?.spin} disabled={ctx?.spinning}>
      {ctx?.spinning ? 'Spinning...' : 'SPIN'}
    </button>
  );
};

// Usage
<SlotMachine>
  <SlotMachine.Reel index={0} />
  <SlotMachine.Reel index={1} />
  <SlotMachine.Reel index={2} />
  <SlotMachine.SpinButton />
</SlotMachine>

Animation Patterns

import { motion, AnimatePresence, useSpring, useTransform } from 'framer-motion';

// Juice: Satisfying feedback animations
const JUICE_VARIANTS = {
  // Pop in
  pop: {
    initial: { scale: 0, opacity: 0 },
    animate: { scale: 1, opacity: 1 },
    exit: { scale: 0, opacity: 0 },
    transition: { type: 'spring', stiffness: 500, damping: 30 },
  },

  // Bounce
  bounce: {
    animate: { 
      y: [0, -10, 0],
      transition: { duration: 0.3, times: [0, 0.5, 1] }
    },
  },

  // Shake (for errors/wrong)
  shake: {
    animate: { 
      x: [0, -10, 10, -10, 10, 0],
      transition: { duration: 0.4 }
    },
  },

  // Pulse (for attention)
  pulse: {
    animate: { 
      scale: [1, 1.05, 1],
      transition: { duration: 0.3, repeat: 2 }
    },
  },
};

// Number counter animation
function AnimatedNumber({ value }: { value: number }) {
  const spring = useSpring(value, { stiffness: 100, damping: 30 });
  const display = useTransform(spring, (v) => Math.floor(v).toLocaleString());

  useEffect(() => {
    spring.set(value);
  }, [value, spring]);

  return <motion.span>{display}</motion.span>;
}

// Stagger children animation
function StaggeredList({ items }: { items: React.ReactNode[] }) {
  return (
    <motion.ul
      initial="hidden"
      animate="visible"
      variants={{
        visible: { transition: { staggerChildren: 0.1 } },
      }}
    >
      {items.map((item, i) => (
        <motion.li
          key={i}
          variants={{
            hidden: { opacity: 0, x: -20 },
            visible: { opacity: 1, x: 0 },
          }}
        >
          {item}
        </motion.li>
      ))}
    </motion.ul>
  );
}

Responsive Game UI

// Hook for responsive game scaling
function useGameScale() {
  const [scale, setScale] = useState(1);
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const updateScale = () => {
      if (!containerRef.current) return;

      const container = containerRef.current;
      const parent = container.parentElement;
      if (!parent) return;

      const DESIGN_WIDTH = 390;  // iPhone 12/13 width
      const DESIGN_HEIGHT = 844;

      const scaleX = parent.clientWidth / DESIGN_WIDTH;
      const scaleY = parent.clientHeight / DESIGN_HEIGHT;

      // Use minimum to ensure everything fits
      setScale(Math.min(scaleX, scaleY, 1.5)); // Cap at 1.5x
    };

    updateScale();
    window.addEventListener('resize', updateScale);
    return () => window.removeEventListener('resize', updateScale);
  }, []);

  return { scale, containerRef };
}

// Usage
function GameScreen() {
  const { scale, containerRef } = useGameScale();

  return (
    <div className="game-container" ref={containerRef}>
      <div 
        className="game-content"
        style={{ transform: `scale(${scale})`, transformOrigin: 'top center' }}
      >
        {/* Fixed-size game UI designed for 390x844 */}
      </div>
    </div>
  );
}

Part VI: Data Architecture

Schema Design Principles

// Use branded types for IDs
type SeasonId = string & { readonly brand: unique symbol };
type SimulinId = string & { readonly brand: unique symbol };
type UserId = string & { readonly brand: unique symbol };

function createSeasonId(): SeasonId {
  return `season_${crypto.randomUUID()}` as SeasonId;
}

// Drizzle schema with relations
import { sqliteTable, text, integer, real } from 'drizzle-orm/sqlite-core';
import { relations } from 'drizzle-orm';

export const users = sqliteTable('users', {
  id: text('id').primaryKey(),
  email: text('email').notNull().unique(),
  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
});

export const seasons = sqliteTable('seasons', {
  id: text('id').primaryKey(),
  userId: text('user_id').notNull().references(() => users.id),
  seasonNumber: integer('season_number').notNull(),
  currentDay: integer('current_day').notNull().default(1),
  phase: text('phase', { enum: ['planting', 'growth', 'harvest'] }).notNull(),
  jackpotContribution: real('jackpot_contribution').notNull().default(0),
  startedAt: integer('started_at', { mode: 'timestamp' }).notNull(),
  completedAt: integer('completed_at', { mode: 'timestamp' }),
});

export const seasonsRelations = relations(seasons, ({ one, many }) => ({
  user: one(users, {
    fields: [seasons.userId],
    references: [users.id],
  }),
  triggers: many(dailyTriggers),
  simulins: many(simulins),
}));

export const dailyTriggers = sqliteTable('daily_triggers', {
  id: text('id').primaryKey(),
  seasonId: text('season_id').notNull().references(() => seasons.id),
  dayNumber: integer('day_number').notNull(),
  triggerType: text('trigger_type').notNull(),
  earnedAt: integer('earned_at', { mode: 'timestamp' }).notNull(),
  metadata: text('metadata', { mode: 'json' }),
});

export const simulins = sqliteTable('simulins', {
  id: text('id').primaryKey(),
  userId: text('user_id').notNull().references(() => users.id),
  seasonId: text('season_id').references(() => seasons.id),
  name: text('name').notNull(),
  stage: text('stage', { enum: ['sproutling', 'cultivar', 'bloomform', 'legendary'] }).notNull(),
  path: text('path', { enum: ['tender', 'watcher', 'lucky'] }),
  bondLevel: integer('bond_level').notNull().default(1),
  bondXP: integer('bond_xp').notNull().default(0),
  personality: text('personality', { mode: 'json' }).notNull(),
  createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
});

Logging & Telemetry

interface GameEvent {
  type: string;
  timestamp: Date;
  sessionId: string;
  userId?: string;
  properties: Record<string, any>;
}

class Telemetry {
  private queue: GameEvent[] = [];
  private flushInterval: Timer;

  constructor(
    private endpoint: string,
    private batchSize = 10,
    private flushIntervalMs = 5000
  ) {
    this.flushInterval = setInterval(() => this.flush(), flushIntervalMs);
  }

  track(type: string, properties: Record<string, any> = {}): void {
    const event: GameEvent = {
      type,
      timestamp: new Date(),
      sessionId: this.getSessionId(),
      userId: this.getUserId(),
      properties: {
        ...properties,
        // Auto-add context
        url: typeof window !== 'undefined' ? window.location.href : undefined,
        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
      },
    };

    this.queue.push(event);

    if (this.queue.length >= this.batchSize) {
      this.flush();
    }
  }

  private async flush(): Promise<void> {
    if (this.queue.length === 0) return;

    const batch = this.queue.splice(0, this.batchSize);

    try {
      await fetch(this.endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ events: batch }),
      });
    } catch (error) {
      // Re-queue failed events (with limit)
      if (this.queue.length < 100) {
        this.queue.unshift(...batch);
      }
      console.error('Telemetry flush failed:', error);
    }
  }

  private getSessionId(): string {
    // Session ID from storage or generate new
    let sessionId = sessionStorage.getItem('fip_session_id');
    if (!sessionId) {
      sessionId = crypto.randomUUID();
      sessionStorage.setItem('fip_session_id', sessionId);
    }
    return sessionId;
  }

  private getUserId(): string | undefined {
    // Get from auth state
    return undefined; // Implement based on auth system
  }

  destroy(): void {
    clearInterval(this.flushInterval);
    this.flush();
  }
}

// Standard events
const telemetry = new Telemetry('/api/telemetry');

// Usage
telemetry.track('day_started', { dayNumber: 5, phase: 'growth' });
telemetry.track('bet_placed', { potId: 'water', betType: 'raise', amount: 100 });
telemetry.track('trigger_earned', { triggerType: 'perfect_read' });
telemetry.track('session_ended', { duration: 1234, daysPlayed: 3 });

Security Patterns

// Input validation with Zod
import { z } from 'zod';

const PlaceBetSchema = z.object({
  potId: z.enum(['water', 'sun', 'pest', 'growth']),
  betType: z.enum(['fold', 'call', 'raise', 'all-in']),
  amount: z.number().int().min(0).max(10000),
});

// Rate limiting
class RateLimiter {
  private requests: Map<string, number[]> = new Map();

  constructor(
    private windowMs: number,
    private maxRequests: number
  ) {}

  isAllowed(key: string): boolean {
    const now = Date.now();
    const windowStart = now - this.windowMs;

    // Get and filter old requests
    const timestamps = (this.requests.get(key) || [])
      .filter(t => t > windowStart);

    if (timestamps.length >= this.maxRequests) {
      return false;
    }

    timestamps.push(now);
    this.requests.set(key, timestamps);
    return true;
  }
}

// Server-side validation wrapper
function validateRequest<T>(
  schema: z.ZodSchema<T>,
  data: unknown,
  context: { userId: string; ip: string }
): T {
  // Rate limit check
  const rateLimiter = new RateLimiter(60000, 100); // 100 req/min
  if (!rateLimiter.isAllowed(context.userId)) {
    throw new Error('Rate limit exceeded');
  }

  // Schema validation
  const result = schema.safeParse(data);
  if (!result.success) {
    console.warn('Validation failed', { 
      userId: context.userId, 
      errors: result.error.errors 
    });
    throw new Error('Invalid request data');
  }

  return result.data;
}

// Anti-cheat: Server-authoritative game state
class GameStateValidator {
  validateDayAdvance(
    currentState: GameState,
    proposedState: GameState
  ): boolean {
    // Server recalculates expected state
    const expectedState = this.calculateNextState(currentState);

    // Compare critical values
    if (proposedState.coins > expectedState.maxPossibleCoins) {
      this.flagSuspicious('coin_manipulation', currentState.userId);
      return false;
    }

    if (proposedState.dayNumber !== expectedState.dayNumber) {
      this.flagSuspicious('day_skip', currentState.userId);
      return false;
    }

    return true;
  }

  private calculateNextState(current: GameState): ExpectedState {
    // Server-side calculation of valid state ranges
    return {} as ExpectedState;
  }

  private flagSuspicious(type: string, userId: string): void {
    // Log for review
    console.warn('Suspicious activity', { type, userId });
  }
}

Part VII: Tutorial System Design

Progressive Disclosure Pattern

interface TutorialStep {
  id: string;
  trigger: TutorialTrigger;
  content: TutorialContent;
  completion: CompletionCondition;
  next?: string;
}

type TutorialTrigger = 
  | { type: 'first_visit'; screen: string }
  | { type: 'action'; action: string }
  | { type: 'state'; condition: (state: GameState) => boolean }
  | { type: 'time'; delayMs: number };

interface TutorialContent {
  title: string;
  body: string;
  highlight?: string;  // CSS selector to highlight
  position?: 'top' | 'bottom' | 'left' | 'right' | 'center';
  character?: 'simulin' | 'npc';
  allowSkip?: boolean;
}

type CompletionCondition = 
  | { type: 'click'; target: string }
  | { type: 'action'; action: string }
  | { type: 'dismiss' }
  | { type: 'state'; condition: (state: GameState) => boolean };

const TUTORIAL_FLOW: TutorialStep[] = [
  {
    id: 'welcome',
    trigger: { type: 'first_visit', screen: 'farm' },
    content: {
      title: 'Welcome to Purria!',
      body: 'Your adventure in tulip farming begins here.',
      character: 'simulin',
      position: 'center',
    },
    completion: { type: 'dismiss' },
    next: 'intro_hex',
  },
  {
    id: 'intro_hex',
    trigger: { type: 'action', action: 'tutorial_continue' },
    content: {
      title: 'Your Farm',
      body: 'Each hex is a plot for growing tulips. Tap one to plant!',
      highlight: '.hex-grid',
      position: 'bottom',
    },
    completion: { type: 'action', action: 'hex_tap' },
    next: 'intro_pots',
  },
  {
    id: 'intro_pots',
    trigger: { type: 'action', action: 'plant_tulip' },
    content: {
      title: 'The Meta-Pots',
      body: 'These four pots fill based on daily events. Place bets on which will hit their threshold!',
      highlight: '.pot-display',
      position: 'top',
    },
    completion: { type: 'click', target: '.pot-display' },
    next: 'first_bet',
  },
  // ... more steps
];

class TutorialManager {
  private completedSteps: Set<string> = new Set();
  private currentStep: TutorialStep | null = null;

  constructor(
    private steps: TutorialStep[],
    private onShow: (step: TutorialStep) => void,
    private onHide: () => void
  ) {
    this.loadProgress();
  }

  checkTriggers(context: { screen: string; action?: string; state: GameState }): void {
    for (const step of this.steps) {
      if (this.completedSteps.has(step.id)) continue;
      if (this.currentStep?.id === step.id) continue;

      if (this.matchesTrigger(step.trigger, context)) {
        this.showStep(step);
        break;
      }
    }
  }

  private matchesTrigger(trigger: TutorialTrigger, context: any): boolean {
    switch (trigger.type) {
      case 'first_visit':
        return context.screen === trigger.screen && 
               !this.hasVisited(trigger.screen);
      case 'action':
        return context.action === trigger.action;
      case 'state':
        return trigger.condition(context.state);
      default:
        return false;
    }
  }

  private showStep(step: TutorialStep): void {
    this.currentStep = step;
    this.onShow(step);
  }

  completeCurrentStep(): void {
    if (!this.currentStep) return;

    this.completedSteps.add(this.currentStep.id);
    this.saveProgress();

    const nextId = this.currentStep.next;
    this.currentStep = null;
    this.onHide();

    if (nextId) {
      const nextStep = this.steps.find(s => s.id === nextId);
      if (nextStep && nextStep.trigger.type === 'action') {
        // Auto-show chained steps
        this.showStep(nextStep);
      }
    }
  }

  private loadProgress(): void {
    const saved = localStorage.getItem('tutorial_progress');
    if (saved) {
      this.completedSteps = new Set(JSON.parse(saved));
    }
  }

  private saveProgress(): void {
    localStorage.setItem(
      'tutorial_progress', 
      JSON.stringify([...this.completedSteps])
    );
  }

  private hasVisited(screen: string): boolean {
    return localStorage.getItem(`visited_${screen}`) === 'true';
  }

  reset(): void {
    this.completedSteps.clear();
    localStorage.removeItem('tutorial_progress');
  }
}

Contextual Help System

interface HelpTopic {
  id: string;
  title: string;
  summary: string;
  content: string;
  relatedTopics?: string[];
  triggers?: string[];  // UI elements that show this help
}

const HELP_TOPICS: HelpTopic[] = [
  {
    id: 'betting',
    title: 'How Betting Works',
    summary: 'Place bets on which pots will fill',
    content: `
      Each day, the four Meta-Pots fill based on events on your farm.

      **Bet Types:**
      - **Fold**: Skip this pot (safe, no reward)
      - **Call**: Small bet, small reward
      - **Raise**: Medium bet, medium reward  
      - **All-In**: Big bet, big reward (or loss!)

      **Thresholds:**
      Pots have thresholds at 50%, 80%, and 100%. Higher thresholds = higher payouts.
    `,
    relatedTopics: ['pots', 'triggers', 'combos'],
    triggers: ['.bet-button', '.pot-display'],
  },
  // ... more topics
];

function HelpButton({ topicId }: { topicId: string }) {
  const [open, setOpen] = useState(false);
  const topic = HELP_TOPICS.find(t => t.id === topicId);

  if (!topic) return null;

  return (
    <>
      <button 
        onClick={() => setOpen(true)}
        className="help-button"
        aria-label={`Help: ${topic.title}`}
      >
        ?
      </button>

      <Dialog open={open} onClose={() => setOpen(false)}>
        <Dialog.Title>{topic.title}</Dialog.Title>
        <Dialog.Content>
          <Markdown>{topic.content}</Markdown>

          {topic.relatedTopics && (
            <div className="related-topics">
              <h4>Related:</h4>
              {topic.relatedTopics.map(id => (
                <HelpLink key={id} topicId={id} />
              ))}
            </div>
          )}
        </Dialog.Content>
      </Dialog>
    </>
  );
}

Part VIII: Quality Assurance

Testing Strategy

// Unit test example (Vitest)
import { describe, it, expect } from 'vitest';
import { ComboEngine } from './combo-engine';

describe('ComboEngine', () => {
  const engine = new ComboEngine();

  describe('evaluateWeek', () => {
    it('detects pair with 2 matching triggers', () => {
      const triggers = [
        { type: 'first_bloom', dayNumber: 1, earnedAt: new Date() },
        { type: 'first_bloom', dayNumber: 2, earnedAt: new Date() },
      ];

      const result = engine.evaluateWeek(triggers);

      expect(result.handType).toBe('pair');
      expect(result.multiplier).toBe(2);
    });

    it('detects three of a kind over pair', () => {
      const triggers = [
        { type: 'perfect_read', dayNumber: 1, earnedAt: new Date() },
        { type: 'perfect_read', dayNumber: 2, earnedAt: new Date() },
        { type: 'perfect_read', dayNumber: 3, earnedAt: new Date() },
        { type: 'first_bloom', dayNumber: 4, earnedAt: new Date() },
        { type: 'first_bloom', dayNumber: 5, earnedAt: new Date() },
      ];

      const result = engine.evaluateWeek(triggers);

      // Full house beats three of a kind
      expect(result.handType).toBe('full_house');
      expect(result.multiplier).toBe(15);
    });
  });
});

// Integration test example
describe('Betting Flow', () => {
  it('completes full betting cycle', async () => {
    const { gameState, bettingSystem } = createTestGame();

    // Place bets
    bettingSystem.placeBet('water', 'raise', 100);
    bettingSystem.placeBet('sun', 'fold', 0);

    // Simulate day completion
    gameState.advanceToResolution();

    // Resolve bets
    const results = bettingSystem.resolveBets(gameState.pots);

    expect(results).toHaveLength(2);
    expect(results[0].potId).toBe('water');
    expect(results[1].potId).toBe('sun');
    expect(results[1].payout).toBe(0); // Fold always 0
  });
});

Code Review Checklist

## Code Review Checklist

### Correctness
- [ ] Logic is correct and handles edge cases
- [ ] No off-by-one errors
- [ ] Null/undefined handled appropriately
- [ ] Async operations handle errors

### Type Safety
- [ ] No `any` types without justification
- [ ] Proper use of generics
- [ ] Return types explicit on public APIs
- [ ] Zod schemas match TypeScript types

### Performance
- [ ] No unnecessary re-renders (React.memo where needed)
- [ ] Large lists are virtualized
- [ ] Expensive calculations are memoized
- [ ] No memory leaks (cleanup in useEffect)

### Security
- [ ] User input is validated
- [ ] No secrets in client code
- [ ] Server validates all mutations
- [ ] Rate limiting considered

### Maintainability
- [ ] Functions are small and focused
- [ ] Clear variable/function names
- [ ] Comments explain "why", not "what"
- [ ] No magic numbers

### Testing
- [ ] Unit tests for logic
- [ ] Edge cases covered
- [ ] Tests are readable

### Accessibility
- [ ] Interactive elements are keyboard accessible
- [ ] ARIA labels where needed
- [ ] Color contrast sufficient
- [ ] Focus management correct

Reference Documents

The following reference documents provide deep-dive implementations:

Game Engineering Team - Building the Best Game Ever
For Farming in Purria v3