@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/operations/lorcana-operations.ts

@@ -0,0 +1,288 @@
+/**
+ * Lorcana Operations Layer
+ *
+ * Domain-specific operations for Disney Lorcana.
+ * Provides high-level Lorcana semantics on top of generic engine operations.
+ *
+ * These operations encapsulate Lorcana rules and can be used across multiple moves.
+ * Each operation is pure and operates through the MoveContext API.
+ */
+
+import type { CardId, MoveContext, PlayerId } from "@drmxrcy/tcg-core";
+import type { Draft } from "immer";
+import type { LorcanaCardMeta, LorcanaGameState } from "../types";
+
+/**
+ * Lorcana Operations Type
+ *
+ * Extension of MoveContext with Lorcana-specific operations.
+ * This type can be used in move reducers for cleaner code.
+ */
+export type LorcanaOperations = {
+  /**
+   * Exert a card (turn sideways)
+   *
+   * Rule 5.1.2: Exerted cards are turned sideways
+   *
+   * @param cardId - Card to exert
+   */
+  exertCard(cardId: CardId): void;
+
+  /**
+   * Ready a card (return to upright position)
+   *
+   * Rule 4.2.1.1: Cards are readied at start of turn
+   *
+   * @param cardId - Card to ready
+   */
+  readyCard(cardId: CardId): void;
+
+  /**
+   * Add lore to a player's total
+   *
+   * Rule 4.3.5.8: Gain lore from questing
+   * Rule 1.9.1.1: Win condition - first to 20 lore
+   *
+   * @param draft - Game state draft
+   * @param playerId - Player gaining lore
+   * @param amount - Amount of lore to add
+   * @returns New lore total
+   */
+  addLore(
+    draft: Draft<LorcanaGameState>,
+    playerId: PlayerId,
+    amount: number,
+  ): number;
+
+  /**
+   * Get lore total for a player
+   *
+   * @param state - Game state
+   * @param playerId - Player to check
+   * @returns Current lore total
+   */
+  getLore(state: LorcanaGameState, playerId: PlayerId): number;
+
+  /**
+   * Add damage to a card
+   *
+   * Rule 9.1: Each counter represents 1 damage
+   * Rule 1.9.1.3: Banished when damage >= Willpower
+   *
+   * @param cardId - Card taking damage
+   * @param amount - Damage amount
+   * @returns New damage total
+   */
+  addDamage(cardId: CardId, amount: number): number;
+
+  /**
+   * Get damage on a card
+   *
+   * @param cardId - Card to check
+   * @returns Current damage amount
+   */
+  getDamage(cardId: CardId): number;
+
+  /**
+   * Remove damage from a card
+   *
+   * @param cardId - Card to heal
+   * @param amount - Amount to heal (default: all damage)
+   * @returns New damage total
+   */
+  removeDamage(cardId: CardId, amount?: number): number;
+
+  /**
+   * Mark a card as "drying" (played this turn)
+   *
+   * Rule 4.2.2.1: Characters are "drying" the turn they're played
+   *
+   * @param cardId - Card that was played
+   */
+  markAsDrying(cardId: CardId): void;
+
+  /**
+   * Mark a card as "dry" (ready to act)
+   *
+   * Rule 4.2.2.1: Becomes dry at Set step of next turn
+   *
+   * @param cardId - Card to mark as dry
+   */
+  markAsDry(cardId: CardId): void;
+
+  /**
+   * Check if a card is "drying"
+   *
+   * @param cardId - Card to check
+   * @returns True if card was played this turn
+   */
+  isDrying(cardId: CardId): boolean;
+
+  /**
+   * Check if a card is exerted
+   *
+   * @param cardId - Card to check
+   * @returns True if card is exerted
+   */
+  isExerted(cardId: CardId): boolean;
+
+  /**
+   * Get card type from registry
+   *
+   * @param cardId - Card to check
+   * @returns Card type (character, action, item, location)
+   */
+  getCardType(cardId: CardId): string | undefined;
+
+  /**
+   * Move a character to a location
+   *
+   * Rule 6.5: Characters can move to locations
+   *
+   * @param characterId - Character to move
+   * @param locationId - Target location
+   */
+  moveToLocation(characterId: CardId, locationId: CardId): void;
+
+  /**
+   * Remove a character from a location
+   *
+   * @param characterId - Character to move
+   */
+  leaveLocation(characterId: CardId): void;
+
+  /**
+   * Get the location a character is at
+   *
+   * @param characterId - Character to check
+   * @returns Location ID, or undefined if not at a location
+   */
+  getLocation(characterId: CardId): CardId | undefined;
+};
+
+/**
+ * Create Lorcana operations from a MoveContext
+ *
+ * Factory function that creates Lorcana-specific operations
+ * using the provided context's zones, cards, and other APIs.
+ *
+ * @param context - Move context
+ * @returns Lorcana operations object
+ *
+ * @example
+ * ```typescript
+ * // In a move reducer:
+ * const ops = createLorcanaOperations(context);
+ * ops.exertCard(cardId);
+ * ops.addLore(draft, playerId, 2);
+ * ```
+ */
+export function createLorcanaOperations<TParams>(
+  context: MoveContext<TParams, LorcanaCardMeta>,
+): LorcanaOperations {
+  return {
+    exertCard(cardId: CardId): void {
+      context.cards.updateCardMeta(cardId, { state: "exerted" });
+    },
+
+    readyCard(cardId: CardId): void {
+      context.cards.updateCardMeta(cardId, { state: "ready" });
+    },
+
+    addLore(
+      draft: Draft<LorcanaGameState>,
+      playerId: PlayerId,
+      amount: number,
+    ): number {
+      const current = draft.external.loreScores[playerId] ?? 0;
+      const newTotal = current + amount;
+      draft.external.loreScores[playerId] = newTotal;
+
+      // Check win condition (Rule 1.9.1.1)
+      if (newTotal >= 20 && context.endGame) {
+        context.endGame({
+          winner: playerId,
+          reason: "lore_victory",
+          metadata: { finalLore: newTotal },
+        });
+      }
+
+      return newTotal;
+    },
+
+    getLore(state: LorcanaGameState, playerId: PlayerId): number {
+      return state.external.loreScores[playerId] ?? 0;
+    },
+
+    addDamage(cardId: CardId, amount: number): number {
+      const current = context.cards.getCardMeta(cardId)?.damage ?? 0;
+      const newDamage = current + amount;
+      context.cards.updateCardMeta(cardId, { damage: newDamage });
+      return newDamage;
+    },
+
+    getDamage(cardId: CardId): number {
+      return context.cards.getCardMeta(cardId)?.damage ?? 0;
+    },
+
+    removeDamage(cardId: CardId, amount?: number): number {
+      const current = context.cards.getCardMeta(cardId)?.damage ?? 0;
+      const newDamage =
+        amount === undefined ? 0 : Math.max(0, current - amount);
+      context.cards.updateCardMeta(cardId, { damage: newDamage });
+      return newDamage;
+    },
+
+    markAsDrying(cardId: CardId): void {
+      context.cards.updateCardMeta(cardId, { isDrying: true });
+    },
+
+    markAsDry(cardId: CardId): void {
+      context.cards.updateCardMeta(cardId, { isDrying: false });
+    },
+
+    isDrying(cardId: CardId): boolean {
+      return context.cards.getCardMeta(cardId)?.isDrying ?? false;
+    },
+
+    isExerted(cardId: CardId): boolean {
+      return context.cards.getCardMeta(cardId)?.state === "exerted";
+    },
+
+    getCardType(cardId: CardId): string | undefined {
+      const card = context.registry?.getCard(cardId);
+      return card?.type;
+    },
+
+    moveToLocation(characterId: CardId, locationId: CardId): void {
+      context.cards.updateCardMeta(characterId, { atLocationId: locationId });
+    },
+
+    leaveLocation(characterId: CardId): void {
+      context.cards.updateCardMeta(characterId, { atLocationId: undefined });
+    },
+
+    getLocation(characterId: CardId): CardId | undefined {
+      return context.cards.getCardMeta(characterId)?.atLocationId;
+    },
+  };
+}
+
+/**
+ * Helper function to use in move reducers
+ *
+ * Provides a shorthand for creating operations in reducers.
+ *
+ * @param context - Move context
+ * @returns Lorcana operations
+ *
+ * @example
+ * ```typescript
+ * reducer: (draft, context) => {
+ *   const ops = useLorcanaOps(context);
+ *   ops.exertCard(context.params.cardId);
+ *   ops.addLore(draft, context.playerId, 2);
+ * }
+ * ```
+ */
+export const useLorcanaOps = createLorcanaOperations;

package/src/queries/README.md

@@ -0,0 +1,56 @@
+# Queries
+
+This directory contains helper functions for querying Lorcana game state.
+
+## Purpose
+
+Provides type-safe, reusable functions for reading game state without modifying it. These queries are used by move validators, ability effects, and UI integrations.
+
+## Structure
+
+- **`card-queries.ts`** - Query cards and their properties
+- **`game-queries.ts`** - Query game-level state
+- **`player-queries.ts`** - Query player-specific state
+- **`zone-queries.ts`** - Query zone contents
+- **`ability-queries.ts`** - Query available abilities
+- **`index.ts`** - Public exports
+
+## Example Queries
+
+```typescript
+// Get all ready characters a player controls
+export const getReadyCharacters = (
+  state: LorcanaState,
+  playerId: PlayerId
+): CardId[] => {
+  return getCardsInZone(state, "play", playerId).filter(
+    cardId => !isExerted(state, cardId)
+  );
+};
+
+// Check if player can afford to play a card
+export const canAffordCard = (
+  state: LorcanaState,
+  playerId: PlayerId,
+  cardId: CardId
+): boolean => {
+  const cost = getCardCost(state, cardId);
+  const available = getAvailableInk(state, playerId);
+  return available >= cost;
+};
+
+// Get characters that can quest
+export const getQuestableCharacters = (
+  state: LorcanaState,
+  playerId: PlayerId
+): CardId[] => {
+  return getReadyCharacters(state, playerId).filter(
+    cardId => canQuest(state, cardId)
+  );
+};
+```
+
+## References
+
+- See `@packages/core` for base query utilities
+

package/src/resolvers/__tests__/condition-resolver.test.ts

@@ -0,0 +1,301 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import type { CardId, PlayerId, ZoneId } from "@drmxrcy/tcg-core";
+import { isConditionMet } from "../condition-resolver";
+import "../conditions/index"; // Register all
+import type { CardInstance, CardRegistry } from "@drmxrcy/tcg-core";
+import type {
+  Condition,
+  HasNamedCharacterCondition,
+  LorcanaCardDefinition,
+  TurnCondition,
+  UsedShiftCondition,
+} from "@drmxrcy/tcg-lorcana-types";
+import {
+  createDefaultCardMeta,
+  createInitialLorcanaState,
+  type LorcanaCardMeta,
+  type LorcanaGameState,
+} from "../../types/game-state";
+
+describe("Condition Resolver", () => {
+  let state: LorcanaGameState;
+  let registry: CardRegistry<LorcanaCardDefinition>;
+  let sourceCard: CardInstance<LorcanaCardMeta>;
+
+  beforeEach(() => {
+    state = createInitialLorcanaState(
+      "player1" as PlayerId,
+      "player2" as PlayerId,
+      "player1" as PlayerId,
+    );
+    // Explicitly seed lore scores for comparison tests
+    state.external.loreScores = {
+      player1: 10,
+      player2: 5,
+    } as Record<PlayerId, number>;
+
+    registry = {
+      getCard: (id: string) => {
+        if (id === "def-elsa")
+          return {
+            id: "def-elsa",
+            name: "Elsa",
+            fullName: "Elsa - Snow Queen",
+            cardType: "character",
+            inkType: ["amethyst"],
+            cost: 3,
+            inkable: true,
+            set: "1",
+          } as LorcanaCardDefinition;
+        return undefined;
+      },
+      hasCard: () => true,
+      getAllCards: () => [],
+    } as any;
+
+    sourceCard = {
+      id: "card-1" as CardId,
+      definitionId: "def-elsa",
+      owner: "player1" as PlayerId,
+      controller: "player1" as PlayerId,
+      zone: "play" as ZoneId,
+      tapped: false,
+      flipped: false,
+      revealed: false,
+      phased: false,
+      state: "ready",
+      damage: 0,
+      isDrying: true,
+    } as any;
+
+    state.internal.cards["card-1"] = sourceCard;
+  });
+
+  describe("Basic Conditions", () => {
+    it("should check turn correctly", () => {
+      state.external.activePlayerId = "player1" as PlayerId;
+      const cond: TurnCondition = { type: "turn", whose: "your" };
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+
+      state.external.activePlayerId = "player2" as PlayerId;
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+    });
+
+    it("should check exerted/ready", () => {
+      sourceCard.state = "ready";
+      expect(
+        isConditionMet({ type: "is-ready" }, sourceCard, state, registry),
+      ).toBe(true);
+      expect(
+        isConditionMet({ type: "is-exerted" }, sourceCard, state, registry),
+      ).toBe(false);
+
+      sourceCard.state = "exerted";
+      expect(
+        isConditionMet({ type: "is-ready" }, sourceCard, state, registry),
+      ).toBe(false);
+      expect(
+        isConditionMet({ type: "is-exerted" }, sourceCard, state, registry),
+      ).toBe(true);
+    });
+  });
+
+  describe("Resolution Conditions", () => {
+    it("should check bodyguard context", () => {
+      const cond: Condition = { type: "resolution", value: "bodyguard" };
+
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+
+      const context = { resolutionContext: "bodyguard" } as any;
+      expect(isConditionMet(cond, sourceCard, state, registry, context)).toBe(
+        true,
+      );
+    });
+
+    it("should check generic shift usage via stack", () => {
+      const cond: UsedShiftCondition = { type: "used-shift" };
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+
+      sourceCard.stackPosition = {
+        isUnder: false,
+        cardsUnderneath: ["card-under-1" as CardId],
+        topCardId: "card-1" as CardId,
+      };
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+    });
+  });
+
+  describe("Existence Conditions", () => {
+    it("should find named character", () => {
+      const cond: HasNamedCharacterCondition = {
+        type: "has-named-character",
+        name: "Elsa",
+        controller: "you",
+      };
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+
+      state.internal.cards = {}; // empty
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+    });
+  });
+
+  describe("Logical Conditions", () => {
+    it("should handle AND logic", () => {
+      const cond: Condition = {
+        type: "and",
+        conditions: [{ type: "is-ready" }, { type: "no-damage" }],
+      };
+
+      sourceCard.state = "ready";
+      sourceCard.damage = 0;
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+
+      sourceCard.damage = 1;
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+    });
+
+    it("should handle nested NOT logic", () => {
+      const cond: Condition = {
+        type: "not",
+        condition: { type: "is-exerted" },
+      };
+      sourceCard.state = "ready";
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+    });
+
+    it("should handle OR logic", () => {
+      const cond: Condition = {
+        type: "or",
+        conditions: [
+          { type: "is-exerted" }, // False
+          { type: "no-damage" }, // True
+        ],
+      };
+
+      sourceCard.state = "ready";
+      sourceCard.damage = 0;
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+    });
+  });
+
+  describe("Comparison Conditions", () => {
+    it("should compare lore scores", () => {
+      const condition: Condition = {
+        type: "comparison",
+        left: { type: "lore", controller: "you" },
+        comparison: "gt" as any,
+        right: { type: "lore", controller: "opponent" },
+      };
+
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(true);
+
+      (state.external.loreScores as any).player2 = 15;
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("History Conditions", () => {
+    it("should check if event happened this turn", () => {
+      state.external.turnHistory = [
+        {
+          type: "played-song",
+          controllerId: "player1" as PlayerId,
+          count: 1,
+        },
+      ];
+
+      const condition: Condition = {
+        type: "this-turn-happened",
+        event: "played-song",
+        who: "you",
+      };
+
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(true);
+    });
+
+    it("should count events this turn", () => {
+      state.external.turnHistory = [
+        {
+          type: "played-action",
+          controllerId: "player1" as PlayerId,
+          count: 1,
+        },
+        {
+          type: "played-action",
+          controllerId: "player1" as PlayerId,
+          count: 1,
+        },
+      ];
+
+      const condition: Condition = {
+        type: "this-turn-count",
+        event: "played-action",
+        who: "you",
+        comparison: "gte" as any,
+        count: 2,
+      };
+
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(true);
+    });
+  });
+
+  describe("Zone Conditions", () => {
+    it("should check if character is at location", () => {
+      sourceCard.atLocationId = "loc-1" as CardId;
+
+      const condition: Condition = {
+        type: "at-location",
+      };
+
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(true);
+
+      sourceCard.atLocationId = undefined;
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(
+        false,
+      );
+    });
+
+    it("should check general zone content", () => {
+      const discardCard: CardInstance<LorcanaCardMeta> = {
+        id: "card-discard" as CardId,
+        definitionId: "def-elsa",
+        owner: "player1" as PlayerId,
+        controller: "player1" as PlayerId,
+        zone: "discard" as ZoneId,
+        tapped: false,
+        flipped: false,
+        revealed: false,
+        phased: false,
+        ...createDefaultCardMeta(),
+      };
+      state.internal.cards["card-discard"] = discardCard;
+
+      const condition: Condition = {
+        type: "zone",
+        zone: "discard",
+        controller: "you",
+        hasCards: true,
+      };
+
+      expect(isConditionMet(condition, sourceCard, state, registry)).toBe(true);
+    });
+  });
+
+  describe("Card State Conditions", () => {
+    it("should check for card under", () => {
+      const cond: Condition = { type: "has-card-under" };
+
+      sourceCard.stackPosition = undefined;
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(false);
+
+      sourceCard.stackPosition = {
+        isUnder: false,
+        cardsUnderneath: ["card-under" as CardId],
+        topCardId: "card-1" as CardId,
+      };
+      expect(isConditionMet(cond, sourceCard, state, registry)).toBe(true);
+    });
+  });
+});

package/src/resolvers/condition-registry.ts

@@ -0,0 +1,70 @@
+import type { CardInstance, CardRegistry } from "@drmxrcy/tcg-core";
+import type { Condition, LorcanaCardDefinition } from "@drmxrcy/tcg-lorcana-types";
+import type { LorcanaContext } from "../targeting/lorcana-target-dsl";
+import type { LorcanaCardMeta, LorcanaGameState } from "../types/game-state";
+
+/**
+ * Context for condition evaluation
+ */
+export interface ConditionEvaluationContext {
+  state: LorcanaGameState;
+  registry: CardRegistry<LorcanaCardDefinition>;
+  context?: LorcanaContext;
+}
+
+/**
+ * Handler for a specific condition type
+ */
+export interface ConditionHandler<T extends Condition = Condition> {
+  /**
+   * Evaluate the condition
+   */
+  evaluate: (
+    condition: T,
+    sourceCard: CardInstance<LorcanaCardMeta>,
+    ctx: ConditionEvaluationContext,
+  ) => boolean;
+
+  /**
+   * Complexity rank for sorting (lower = evaluated first)
+   *
+   * Suggestions:
+   * 0-10: Simple property checks (exerted, ready)
+   * 11-20: Turn/Phase checks
+   * 21-40: Count checks (resources)
+   * 41-60: Simple Filters (has card named X)
+   * 61-90: Complex Filters / Queries
+   * 99+: Deep recursion / expensive checks
+   */
+  complexity: number;
+}
+
+/**
+ * Registry for condition handlers
+ */
+class ConditionRegistry {
+  private handlers = new Map<Condition["type"], ConditionHandler<any>>();
+
+  /**
+   * Register a new condition handler
+   */
+  register<T extends Condition>(type: T["type"], handler: ConditionHandler<T>) {
+    this.handlers.set(type, handler);
+  }
+
+  /**
+   * Get handler for a condition type
+   */
+  get<T extends Condition>(type: T["type"]): ConditionHandler<T> | undefined {
+    return this.handlers.get(type) as ConditionHandler<T> | undefined;
+  }
+
+  /**
+   * Check if a handler exists for a type
+   */
+  has(type: string): boolean {
+    return this.handlers.has(type as Condition["type"]);
+  }
+}
+
+export const conditionRegistry = new ConditionRegistry();