@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/types/README.md

@@ -0,0 +1,303 @@
+# Types
+
+This directory contains TypeScript type definitions specific to Lorcana.
+
+## Structure
+
+- **`lorcana-state.ts`** - Game state type definitions
+- **`lorcana-moves.ts`** - Move parameter types
+- **`lorcana-cards.ts`** - Card type definitions
+- **`lorcana-abilities.ts`** - Ability type definitions
+- **`branded-types.ts`** - Branded type definitions for type safety
+- **`index.ts`** - Type exports
+
+## Purpose
+
+This directory provides strong TypeScript types that:
+
+1. Extend base types from `@drmxrcy/tcg-core` with Lorcana specifics
+2. Ensure type safety throughout the engine
+3. Enable IDE autocomplete and type checking
+4. Document the data structures through types
+
+## State Types
+
+### Game State
+
+The root state type for Lorcana games:
+
+```typescript
+import type { GameState, PlayerId, CardId } from "@drmxrcy/tcg-core";
+
+export type LorcanaState = GameState & {
+  lorcana: {
+    // Lore tracking (win condition at 20)
+    lore: Record<PlayerId, number>;
+    
+    // Ink tracking
+    ink: {
+      available: Record<PlayerId, number>;
+      total: Record<PlayerId, number>;
+    };
+    
+    // Challenge state during challenge resolution
+    challengeState?: {
+      attacker: CardId;
+      defender?: CardId;
+      attackerDamage: number;
+      defenderDamage: number;
+    };
+    
+    // Location state
+    locations: Record<CardId, {
+      characters: CardId[];
+    }>;
+    
+    // Turn metadata
+    turnMetadata: {
+      cardsPlayedThisTurn: CardId[];
+      charactersQuestingThisTurn: CardId[];
+      damageDealtThisTurn: Record<CardId, number>;
+    };
+  };
+};
+```
+
+### Zone Types
+
+Lorcana-specific zone types:
+
+```typescript
+export type LorcanaZone =
+  | "deck"
+  | "hand"
+  | "play"
+  | "discard"
+  | "inkwell";
+
+export type ZoneVisibility = 
+  | "all"        // All players can see
+  | "owner"      // Only owner can see
+  | "none";      // No one can see (face-down)
+```
+
+## Move Types
+
+Type-safe move parameters:
+
+```typescript
+export type PlayCardMoveParams = {
+  cardId: CardId;
+  shift?: {
+    targetCardId: CardId;  // Card to shift onto
+  };
+  targets?: TargetSelection[];
+};
+
+export type QuestMoveParams = {
+  cardId: CardId;
+};
+
+export type ChallengeMoveParams = {
+  attackerId: CardId;
+  defenderId: CardId;
+};
+
+export type InkCardMoveParams = {
+  cardId: CardId;
+};
+
+export type ActivateAbilityMoveParams = {
+  cardId: CardId;
+  abilityIndex: number;
+  targets?: TargetSelection[];
+};
+```
+
+## Card Types
+
+Lorcana card type definitions:
+
+```typescript
+export type LorcanaColor =
+  | "amber"
+  | "amethyst"
+  | "emerald"
+  | "ruby"
+  | "sapphire"
+  | "steel";
+
+export type LorcanaCardType =
+  | "character"
+  | "action"
+  | "item"
+  | "location"
+  | "song";
+
+export type LorcanaRarity =
+  | "common"
+  | "uncommon"
+  | "rare"
+  | "super_rare"
+  | "legendary"
+  | "enchanted";
+
+export type LorcanaCard = {
+  id: CardId;
+  name: string;
+  type: LorcanaCardType;
+  color: LorcanaColor;
+  cost: number;
+  inkCost: number;
+  inkable: boolean;
+  rarity: LorcanaRarity;
+  set: string;
+  number: number;
+  
+  // Character properties
+  strength?: number;
+  willpower?: number;
+  loreValue?: number;
+  classifications?: string[];  // "Hero", "Villain", "Princess", etc.
+  
+  // Abilities
+  abilities: LorcanaAbility[];
+  
+  // Text
+  text?: string;
+  flavorText?: string;
+};
+```
+
+## Ability Types
+
+Type-safe ability definitions:
+
+```typescript
+export type LorcanaAbility =
+  | KeywordAbility
+  | TriggeredAbility
+  | ActivatedAbility
+  | StaticAbility;
+
+export type KeywordAbility = {
+  type: "keyword";
+  keyword: LorcanaKeyword;
+  value?: number;  // For Challenger +N, Resist +N, etc.
+};
+
+export type LorcanaKeyword =
+  | "bodyguard"
+  | "challenger"
+  | "evasive"
+  | "reckless"
+  | "resist"
+  | "rush"
+  | "shift"
+  | "singer"
+  | "support"
+  | "ward";
+
+export type TriggeredAbility = {
+  type: "triggered";
+  trigger: TriggerTiming;
+  condition?: AbilityCondition;
+  effect: AbilityEffect;
+  target?: TargetDefinition;
+};
+
+export type TriggerTiming =
+  | "whenPlayed"
+  | "wheneverQuests"
+  | "wheneverChallenges"
+  | "wheneverDamaged"
+  | "atStartOfTurn"
+  | "atEndOfTurn"
+  | "whenLeaves";
+
+export type ActivatedAbility = {
+  type: "activated";
+  cost?: AbilityCost;
+  effect: AbilityEffect;
+  target?: TargetDefinition;
+  usesPerTurn?: number;
+};
+```
+
+## Branded Types
+
+Type-safe IDs to prevent mixing different ID types:
+
+```typescript
+// Branded type pattern
+export type Brand<K, T> = K & { __brand: T };
+
+// Specific ID types
+export type CardId = Brand<string, "CardId">;
+export type PlayerId = Brand<string, "PlayerId">;
+export type GameId = Brand<string, "GameId">;
+export type AbilityId = Brand<string, "AbilityId">;
+
+// Type guards
+export const isCardId = (value: string): value is CardId => {
+  return typeof value === "string" && value.length > 0;
+};
+
+// Constructor functions
+export const createCardId = (value: string): CardId => {
+  return value as CardId;
+};
+```
+
+## Effect Types
+
+Type-safe effect definitions:
+
+```typescript
+export type AbilityEffect = 
+  | DrawCardsEffect
+  | DealDamageEffect
+  | GainLoreEffect
+  | ExertEffect
+  | ReadyEffect
+  | ReturnToHandEffect
+  | DiscardEffect;
+
+export type DrawCardsEffect = {
+  type: "drawCards";
+  amount: number;
+  player?: "controller" | "opponent" | "target";
+};
+
+export type DealDamageEffect = {
+  type: "dealDamage";
+  amount: number;
+  target: TargetDefinition;
+};
+
+export type GainLoreEffect = {
+  type: "gainLore";
+  amount: number;
+};
+```
+
+## Type Utilities
+
+Helper types for common patterns:
+
+```typescript
+// Make specific properties optional
+export type PartialCard = Partial<LorcanaCard> & Pick<LorcanaCard, "id" | "name">;
+
+// Extract character cards only
+export type CharacterCard = LorcanaCard & { type: "character" };
+
+// Player-specific data
+export type PlayerState<T> = Record<PlayerId, T>;
+```
+
+## References
+
+- See `@packages/core/src/types/` for base framework types
+- See TypeScript handbook for branded types pattern
+

package/src/types/__tests__/lorcana-state.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "bun:test";
+import { createCardId, createPlayerId } from "../branded-types";
+import type { LorcanaState } from "../lorcana-state";
+
+/**
+ * Task 1.1: Tests for LorcanaState type structure
+ *
+ * Validates the complete Lorcana game state type definition:
+ * - Lore tracking (Rule 3.1.4 - starts at 0)
+ * - Ink management (total and available)
+ * - Character states (drying, damage, exerted)
+ * - Turn metadata
+ * - Challenge state
+ *
+ * References:
+ * - Rule 1.9.1.1 (Win at 20 lore)
+ * - Rule 4.2.2.1 (Drying characters)
+ * - Rule 4.3.3 (Ink once per turn)
+ * - Rule 4.3.6 (Challenge state)
+ * - Rule 9 (Damage counters)
+ */
+
+// Test helper to create base Lorcana state
+function createBaseLorcanaState(
+  players: string[],
+  overrides?: Partial<LorcanaState>,
+): LorcanaState {
+  const playerIds = players.map((p) => createPlayerId(p));
+  const lore: Record<string, number> = {};
+  const available: Record<string, number> = {};
+  const total: Record<string, number> = {};
+
+  for (const pid of playerIds) {
+    lore[pid] = 0;
+    available[pid] = 0;
+    total[pid] = 0;
+  }
+
+  return {
+    players: playerIds,
+    currentPlayerIndex: 0,
+    turnNumber: 1,
+    phase: "beginning",
+    lorcana: {
+      lore,
+      ink: { available, total },
+      turnMetadata: {
+        cardsPlayedThisTurn: [],
+        charactersQuesting: [],
+        inkedThisTurn: false,
+      },
+      characterStates: {},
+      permanentStates: {},
+    },
+    ...overrides,
+  };
+}
+
+describe("LorcanaState Type Structure", () => {
+  it("should have lore tracking for each player", () => {
+    const state = createBaseLorcanaState(["player1", "player2"]);
+    const [player1, player2] = state.players;
+
+    expect(state.lorcana.lore[player1]).toBe(0);
+    expect(state.lorcana.lore[player2]).toBe(0);
+  });
+
+  it("should track ink separately for each player", () => {
+    const state = createBaseLorcanaState(["player1", "player2"]);
+    const [player1, player2] = state.players;
+
+    // Set ink values
+    state.lorcana.ink.available[player1] = 3;
+    state.lorcana.ink.available[player2] = 2;
+    state.lorcana.ink.total[player1] = 5;
+    state.lorcana.ink.total[player2] = 4;
+
+    // Available ink is what can be spent this turn
+    expect(state.lorcana.ink.available[player1]).toBe(3);
+    // Total ink is maximum capacity
+    expect(state.lorcana.ink.total[player1]).toBe(5);
+  });
+
+  it("should track character states including drying status", () => {
+    const state = createBaseLorcanaState(["player1"], { phase: "main" });
+    const cardId = createCardId("card-character-1");
+
+    state.lorcana.characterStates[cardId] = {
+      playedThisTurn: true, // "drying" character (Rule 4.2.2.1)
+      damage: 0,
+      exerted: false,
+    };
+
+    const charState = state.lorcana.characterStates[cardId];
+    expect(charState.playedThisTurn).toBe(true);
+    expect(charState.damage).toBe(0);
+    expect(charState.exerted).toBe(false);
+  });
+
+  it("should track damage on characters", () => {
+    const state = createBaseLorcanaState(["player1"], { phase: "main" });
+    const cardId = createCardId("card-character-1");
+
+    state.lorcana.characterStates[cardId] = {
+      playedThisTurn: false,
+      damage: 3, // Has 3 damage counters (Rule 9)
+      exerted: true,
+    };
+
+    expect(state.lorcana.characterStates[cardId].damage).toBe(3);
+  });
+
+  it("should track turn metadata including cards played and characters questing", () => {
+    const state = createBaseLorcanaState(["player1"], { phase: "main" });
+    const card1 = createCardId("card-1");
+    const card2 = createCardId("card-2");
+
+    state.lorcana.turnMetadata = {
+      cardsPlayedThisTurn: [card1],
+      charactersQuesting: [card2],
+      inkedThisTurn: true, // Already inked this turn (Rule 4.3.3)
+    };
+
+    expect(state.lorcana.turnMetadata.cardsPlayedThisTurn).toContain(card1);
+    expect(state.lorcana.turnMetadata.charactersQuesting).toContain(card2);
+    expect(state.lorcana.turnMetadata.inkedThisTurn).toBe(true);
+  });
+
+  it("should optionally track challenge state during challenges", () => {
+    const state = createBaseLorcanaState(["player1"], { phase: "main" });
+    const attacker = createCardId("card-attacker");
+    const defender = createCardId("card-defender");
+
+    state.lorcana.challengeState = {
+      attacker,
+      defender,
+      attackerDamage: 5,
+      defenderDamage: 3,
+    };
+
+    expect(state.lorcana.challengeState).toBeDefined();
+    expect(state.lorcana.challengeState?.attacker).toBe(attacker);
+    expect(state.lorcana.challengeState?.defender).toBe(defender);
+    expect(state.lorcana.challengeState?.attackerDamage).toBe(5);
+  });
+
+  it("should track location and item states separately from characters", () => {
+    const state = createBaseLorcanaState(["player1"], { phase: "main" });
+    const locationId = createCardId("card-location-1");
+
+    state.lorcana.permanentStates[locationId] = {
+      damage: 2, // Locations can take damage
+    };
+
+    expect(state.lorcana.permanentStates[locationId].damage).toBe(2);
+  });
+
+  it("should have required base game properties", () => {
+    const state = createBaseLorcanaState(["player1", "player2"]);
+    const [player1, player2] = state.players;
+
+    // Verify base game properties exist
+    expect(state.players).toEqual([player1, player2]);
+    expect(state.currentPlayerIndex).toBe(0);
+    expect(state.turnNumber).toBe(1);
+    expect(state.phase).toBe("beginning");
+  });
+});

package/src/types/__tests__/move-enumeration.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "bun:test";
+import type { PlayerId } from "@drmxrcy/tcg-core";
+import type {
+  AvailableMoveInfo,
+  MoveParameterOptions,
+  MoveParamSchema,
+  MoveValidationError,
+  ParameterInfo,
+  ParamFieldSchema,
+} from "../move-enumeration";
+
+describe("Move Enumeration Types", () => {
+  describe("Type Compilation", () => {
+    it("should compile AvailableMoveInfo type", () => {
+      const moveInfo: AvailableMoveInfo = {
+        moveId: "chooseWhoGoesFirstMove",
+        displayName: "Choose First Player",
+        description: "Select which player goes first",
+        icon: "dice",
+        paramSchema: {
+          required: [
+            {
+              name: "playerId",
+              type: "playerId",
+              description: "Player to go first",
+            },
+          ],
+        },
+      };
+
+      expect(moveInfo.moveId).toBe("chooseWhoGoesFirstMove");
+      expect(moveInfo.displayName).toBe("Choose First Player");
+    });
+
+    it("should compile AvailableMoveInfo without optional fields", () => {
+      const moveInfo: AvailableMoveInfo = {
+        moveId: "passTurn",
+        displayName: "Pass Turn",
+        description: "End your turn",
+      };
+
+      expect(moveInfo.moveId).toBe("passTurn");
+      expect(moveInfo.icon).toBeUndefined();
+      expect(moveInfo.paramSchema).toBeUndefined();
+    });
+
+    it("should compile ParamFieldSchema type", () => {
+      const fieldSchema: ParamFieldSchema = {
+        name: "cardId",
+        type: "cardId",
+        description: "Card to play",
+        validValues: ["card1", "card2"],
+      };
+
+      expect(fieldSchema.name).toBe("cardId");
+      expect(fieldSchema.type).toBe("cardId");
+    });
+
+    it("should compile ParamFieldSchema with enum values", () => {
+      const fieldSchema: ParamFieldSchema = {
+        name: "choice",
+        type: "string",
+        description: "Choice to make",
+        enumValues: ["option1", "option2"],
+      };
+
+      expect(fieldSchema.enumValues).toEqual(["option1", "option2"]);
+    });
+
+    it("should compile MoveParamSchema type", () => {
+      const schema: MoveParamSchema = {
+        required: [
+          {
+            name: "playerId",
+            type: "playerId",
+            description: "Target player",
+          },
+        ],
+        optional: [
+          {
+            name: "targetId",
+            type: "cardId",
+            description: "Optional target",
+          },
+        ],
+      };
+
+      expect(schema.required).toHaveLength(1);
+      expect(schema.optional).toHaveLength(1);
+    });
+
+    it("should compile MoveParameterOptions type", () => {
+      const options: MoveParameterOptions = {
+        validCombinations: [
+          { playerId: "player_one" as PlayerId },
+          { playerId: "player_two" as PlayerId },
+        ],
+        parameterInfo: {
+          playerId: {
+            type: "playerId",
+            description: "Player to choose",
+            validValues: ["player_one", "player_two"],
+          },
+        },
+      };
+
+      expect(options.validCombinations).toHaveLength(2);
+      expect(options.parameterInfo.playerId.type).toBe("playerId");
+    });
+
+    it("should compile ParameterInfo type", () => {
+      const info: ParameterInfo = {
+        type: "number",
+        description: "Number of cards to draw",
+        validValues: [1, 2, 3],
+        min: 1,
+        max: 7,
+      };
+
+      expect(info.type).toBe("number");
+      expect(info.min).toBe(1);
+      expect(info.max).toBe(7);
+    });
+
+    it("should compile MoveValidationError type", () => {
+      const error: MoveValidationError = {
+        moveId: "playCard",
+        errorCode: "INSUFFICIENT_INK",
+        reason: "Not enough ink to play this card",
+        context: {
+          required: 5,
+          available: 3,
+        },
+        suggestions: ["Add more cards to your inkwell"],
+      };
+
+      expect(error.errorCode).toBe("INSUFFICIENT_INK");
+      expect(error.suggestions).toHaveLength(1);
+    });
+
+    it("should compile MoveValidationError without optional fields", () => {
+      const error: MoveValidationError = {
+        moveId: "quest",
+        errorCode: "INVALID_TARGET",
+        reason: "Character is exhausted",
+      };
+
+      expect(error.context).toBeUndefined();
+      expect(error.suggestions).toBeUndefined();
+    });
+  });
+
+  describe("Type Safety", () => {
+    it("should enforce valid parameter types", () => {
+      const paramInfo: ParameterInfo = {
+        type: "cardId",
+        description: "Card ID",
+      };
+
+      // Type should be one of the allowed values
+      expect(["cardId", "playerId", "number", "boolean", "object"]).toContain(
+        paramInfo.type,
+      );
+    });
+
+    it("should allow all valid ParamFieldSchema types", () => {
+      const types: Array<ParamFieldSchema["type"]> = [
+        "cardId",
+        "playerId",
+        "number",
+        "boolean",
+        "object",
+        "string",
+      ];
+
+      expect(types).toHaveLength(6);
+    });
+  });
+});