@drmxrcy/tcg-lorcana 0.0.0-202602060544

package/src/types/branded-types.ts

@@ -0,0 +1,106 @@
+/**
+ * Branded Types for Type-Safe IDs
+ *
+ * Task 1.2: Create branded types for domain-specific IDs
+ *
+ * Re-exports core branded types from @drmxrcy/tcg-core for consistency across the monorepo.
+ * Adds Lorcana-specific branded types using the same pattern.
+ *
+ * @example
+ * ```typescript
+ * const playerId = createPlayerId("player1");
+ * const cardId = createCardId("card-1");
+ *
+ * // TypeScript error: Type 'CardId' is not assignable to type 'PlayerId'
+ * const wrong: PlayerId = cardId;
+ * ```
+ */
+
+// Re-export core branded types for consistency
+export type { CardId, GameId, PlayerId, ZoneId } from "@drmxrcy/tcg-core";
+
+// Import the Brand type from core for creating additional branded types
+import type { CardId, GameId, PlayerId, ZoneId } from "@drmxrcy/tcg-core";
+
+/**
+ * AbilityId - Branded string for ability identification (Lorcana-specific)
+ *
+ * Uses the same pattern as @drmxrcy/tcg-core branded types for compatibility.
+ */
+declare const abilityIdBrand: unique symbol;
+export type AbilityId = string & { readonly [abilityIdBrand]: "AbilityId" };
+
+/**
+ * Create a PlayerId from a string
+ *
+ * @param value - The string value to brand as PlayerId
+ * @returns Branded PlayerId
+ */
+export const createPlayerId = (value: string): PlayerId => {
+  if (!value || value.length === 0) {
+    throw new Error("PlayerId cannot be empty");
+  }
+  return value as PlayerId;
+};
+
+/**
+ * Create a CardId from a string
+ *
+ * @param value - The string value to brand as CardId
+ * @returns Branded CardId
+ */
+export const createCardId = (value: string): CardId => {
+  if (!value || value.length === 0) {
+    throw new Error("CardId cannot be empty");
+  }
+  return value as CardId;
+};
+
+/**
+ * Create a ZoneId from a string
+ *
+ * @param value - The string value to brand as ZoneId
+ * @returns Branded ZoneId
+ */
+export const createZoneId = (value: string): ZoneId => {
+  if (!value || value.length === 0) {
+    throw new Error("ZoneId cannot be empty");
+  }
+  return value as ZoneId;
+};
+
+/**
+ * Create an AbilityId from a string
+ *
+ * @param value - The string value to brand as AbilityId
+ * @returns Branded AbilityId
+ */
+export const createAbilityId = (value: string): AbilityId => {
+  if (!value || value.length === 0) {
+    throw new Error("AbilityId cannot be empty");
+  }
+  return value as AbilityId;
+};
+
+/**
+ * Create a GameId from a string
+ *
+ * @param value - The string value to brand as GameId
+ * @returns Branded GameId
+ */
+export const createGameId = (value: string): GameId => {
+  if (!value || value.length === 0) {
+    throw new Error("GameId cannot be empty");
+  }
+  return value as GameId;
+};
+
+/**
+ * Type guard to check if a value is a non-empty string
+ *
+ * @param value - Value to check
+ * @returns True if value is a non-empty string
+ */
+export const isNonEmptyString = (value: unknown): value is string => {
+  return typeof value === "string" && value.length > 0;
+};

package/src/types/game-state.ts

@@ -0,0 +1,184 @@
+/**
+ * Game State Types
+ *
+ * Core game state types for Lorcana engine.
+ * Implements the @drmxrcy/tcg-core IState pattern.
+ */
+
+import type { CardId, IState, PlayerId } from "@drmxrcy/tcg-core";
+import type { LorcanaCardDefinition } from "@drmxrcy/tcg-lorcana-types";
+
+/** Card ready/exerted state */
+export type CardReadyState = "ready" | "exerted";
+
+/**
+ * Stack position for shifted cards (Rule 5.1.5-5.1.7)
+ */
+export interface StackPosition {
+  /** Is this card underneath another card? */
+  isUnder: boolean;
+  /** If this is the top card, what's its ID? */
+  topCardId?: CardId;
+  /** If this is the top card, IDs of cards underneath */
+  cardsUnderneath?: CardId[];
+}
+
+/**
+ * Active effect tracking (for "this turn" effects, etc.)
+ */
+export interface ActiveEffect {
+  id: string;
+  sourceCardId: CardId;
+  type: string;
+  params: Record<string, unknown>;
+  expiresAt?: "endOfTurn" | "startOfNextTurn" | "custom";
+}
+
+/**
+ * Bag entry for triggered abilities
+ */
+export interface BagEntry {
+  id: string;
+  abilityId: string;
+  sourceCardId: CardId;
+  controllerId: PlayerId;
+  triggerEvent: string;
+  timestamp: number;
+}
+
+/**
+ * Lorcana Card Metadata (Dynamic State)
+ *
+ * Stores mutable, game-specific card properties:
+ * - Ready/Exerted state
+ * - Damage
+ * - Drying (summoning sickness)
+ * - Stack position (Shift)
+ * - Location attachment
+ */
+export interface LorcanaCardMeta {
+  /** Ready or exerted (Rule 5.1.1-5.1.2) */
+  state: CardReadyState;
+
+  /** Damage counters (Rule 5.1.3-5.1.4) */
+  damage: number;
+
+  /** Drying = summoning sickness - can't quest/challenge/use exert abilities */
+  isDrying: boolean;
+
+  /** Stack position for Shift (Rule 5.1.5-5.1.7) */
+  stackPosition?: StackPosition;
+
+  /** Location this character is at (if any) */
+  atLocationId?: CardId;
+}
+
+/**
+ * Lorcana External State (Game Logic State)
+ *
+ * Game-specific state not managed by the framework.
+ */
+export interface LorcanaExternalState {
+  /** Lore scores for each player (win at 20+) */
+  loreScores: Record<PlayerId, number>;
+
+  /** The bag - triggered abilities waiting to resolve */
+  bag: BagEntry[];
+
+  /** Active effects (temporary modifiers) */
+  effects: ActiveEffect[];
+
+  /** Turn tracking */
+  turnNumber: number;
+  activePlayerId: PlayerId;
+  hasInkedThisTurn: boolean;
+  startingPlayerId: PlayerId;
+
+  /** Events that happened this turn (for conditions like "If you played a song this turn") */
+  turnHistory: TurnHistoryEvent[];
+
+  /** Current phase and step */
+  currentPhase: "beginning" | "main" | "end";
+  currentStep?: "ready" | "set" | "draw";
+
+  /** Game end state */
+  isGameOver: boolean;
+  winner?: PlayerId;
+  gameEndReason?: string;
+
+  /** Name of the card named by "Name a card" effects */
+  namedCard?: string;
+}
+
+export interface TurnHistoryEvent {
+  type:
+    | "played-song"
+    | "played-character"
+    | "played-action"
+    | "played-floodborn"
+    | "challenged"
+    | "quested"
+    | "banished-character"
+    | "damaged-character"
+    | "was-damaged"
+    | "inked";
+  sourceId?: CardId;
+  controllerId: PlayerId;
+  count: number; // For bulk events or just 1
+  params?: Record<string, any>;
+}
+
+/**
+ * Complete Lorcana Game State
+ *
+ * Combines framework-managed state (internal) with game-specific state (external).
+ */
+export type LorcanaGameState = IState<
+  LorcanaExternalState,
+  LorcanaCardDefinition,
+  LorcanaCardMeta
+>;
+
+/**
+ * Default card meta state for new cards
+ */
+export function createDefaultCardMeta(): LorcanaCardMeta {
+  return {
+    state: "ready",
+    damage: 0,
+    isDrying: true,
+  };
+}
+
+/**
+ * Create initial Lorcana game state
+ */
+export function createInitialLorcanaState(
+  player1Id: PlayerId,
+  player2Id: PlayerId,
+  startingPlayerId: PlayerId,
+): LorcanaGameState {
+  return {
+    internal: {
+      zones: {}, // Zones are initialized by the framework zone manager
+      cards: {}, // Cards are initialized by the framework
+      cardMetas: {}, // Card metas are initialized as cards are created
+    },
+    external: {
+      loreScores: {
+        [player1Id]: 0,
+        [player2Id]: 0,
+      },
+      bag: [],
+      effects: [],
+      turnNumber: 1,
+      activePlayerId: startingPlayerId,
+      hasInkedThisTurn: false,
+      turnHistory: [],
+      startingPlayerId,
+      currentPhase: "beginning",
+      currentStep: "ready",
+      isGameOver: false,
+    },
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Lorcana Type Definitions
+ *
+ * Public exports for all Lorcana-specific types
+ */
+
+// Card types and classifications - re-export from lorcana-types
+// Game state types - re-export from lorcana-types
+export type {
+  AbilityDefinition,
+  ActionAbilityDefinition,
+  ActionCard,
+  ActionSubtype,
+  ActivatedAbilityDefinition,
+  BaseAbilityDefinition,
+  BaseCardProperties,
+  CardType,
+  ChallengeState,
+  CharacterCard,
+  CharacterState,
+  Classification,
+  DeckStats,
+  DeckValidationError,
+  DeckValidationResult,
+  InkType,
+  ItemCard,
+  KeywordAbilityDefinition,
+  LocationCard,
+  LorcanaCard,
+  LorcanaCardDefinition,
+  LorcanaPhase,
+  LorcanaState,
+  PermanentState,
+  ReplacementAbilityDefinition,
+  StaticAbilityDefinition,
+  TooFewCardsError,
+  TooManyCopiesError,
+  TooManyInkTypesError,
+  TriggeredAbilityDefinition,
+  TurnMetadata,
+} from "@drmxrcy/tcg-lorcana-types";
+
+export {
+  CARD_TYPES,
+  CLASSIFICATIONS,
+  getFullName,
+  getInkColor,
+  getInkTypes,
+  INK_COLORS,
+  INK_TYPES,
+  isActionCard,
+  isCardType,
+  isCharacterCard,
+  isClassification,
+  isDreamborn,
+  isDualInk,
+  isFloodborn,
+  isItemCard,
+  isLocationCard,
+  isStoryborn,
+  isValidInkType,
+  MAX_COPIES_PER_CARD,
+  MAX_INK_TYPES,
+  MIN_DECK_SIZE,
+} from "@drmxrcy/tcg-lorcana-types";
+// Branded types (primary source for type-safe IDs)
+export * from "./branded-types";
+// Game state - exclude PlayerId/CardId/ZoneId (use branded-types)
+export type {
+  ActiveEffect,
+  BagEntry,
+  CardReadyState,
+  LorcanaCardMeta,
+  LorcanaExternalState,
+  LorcanaGameState,
+  StackPosition,
+} from "./game-state";
+export {
+  createDefaultCardMeta,
+  createInitialLorcanaState,
+} from "./game-state";
+
+// Move params - exclude LorcanaGameState to avoid conflict with game-state.ts
+export type {
+  LorcanaMoveParams,
+  PlayCardCost,
+} from "./move-params";

package/src/types/keywords.ts

@@ -0,0 +1,187 @@
+/**
+ * Keywords (Section 10)
+ *
+ * Lorcana has 12 keywords:
+ * - Simple keywords: Bodyguard, Evasive, Reckless, Rush, Support, Vanish, Ward
+ * - Parameterized keywords: Challenger +X, Resist +X (stacking)
+ * - Complex keywords: Shift, Singer X, Sing Together X
+ */
+
+/** Simple keywords that have no parameters */
+export const SIMPLE_KEYWORDS = [
+  "Alert",
+  "Bodyguard",
+  "Evasive",
+  "Reckless",
+  "Rush",
+  "Support",
+  "Vanish",
+  "Ward",
+] as const;
+
+export type SimpleKeyword = (typeof SIMPLE_KEYWORDS)[number];
+
+/** Parameterized keywords with numeric values that can stack */
+export interface ChallengerKeyword {
+  type: "Challenger";
+  value: number;
+}
+
+export interface ResistKeyword {
+  type: "Resist";
+  value: number;
+}
+
+export type ParameterizedKeyword = ChallengerKeyword | ResistKeyword;
+
+/** Complex keywords with special behaviors */
+export interface ShiftKeyword {
+  type: "Shift";
+  cost: number;
+  targetName: string;
+}
+
+export interface SingerKeyword {
+  type: "Singer";
+  value: number;
+}
+
+export interface SingTogetherKeyword {
+  type: "SingTogether";
+  value: number;
+}
+
+export type ComplexKeyword = ShiftKeyword | SingerKeyword | SingTogetherKeyword;
+
+/** All keyword types */
+export type Keyword = SimpleKeyword | ParameterizedKeyword | ComplexKeyword;
+
+/** All keyword type names for parameterized and complex keywords */
+export type KeywordType =
+  | SimpleKeyword
+  | "Challenger"
+  | "Resist"
+  | "Shift"
+  | "Singer"
+  | "SingTogether";
+
+/**
+ * Check if a keyword is a simple keyword
+ */
+export function isSimpleKeyword(keyword: Keyword): keyword is SimpleKeyword {
+  return typeof keyword === "string";
+}
+
+/**
+ * Check if a keyword is a parameterized keyword (Challenger or Resist)
+ */
+export function isParameterizedKeyword(
+  keyword: Keyword,
+): keyword is ParameterizedKeyword {
+  return (
+    typeof keyword === "object" &&
+    (keyword.type === "Challenger" || keyword.type === "Resist")
+  );
+}
+
+/**
+ * Check if a keyword is a complex keyword (Shift, Singer, SingTogether)
+ */
+export function isComplexKeyword(keyword: Keyword): keyword is ComplexKeyword {
+  return (
+    typeof keyword === "object" &&
+    (keyword.type === "Shift" ||
+      keyword.type === "Singer" ||
+      keyword.type === "SingTogether")
+  );
+}
+
+/**
+ * Get the type name of a keyword
+ */
+export function getKeywordTypeName(keyword: Keyword): KeywordType {
+  if (typeof keyword === "string") {
+    return keyword;
+  }
+  return keyword.type;
+}
+
+/**
+ * Check if a keyword array contains a specific keyword type
+ */
+export function hasKeywordType(
+  keywords: Keyword[] | undefined,
+  type: KeywordType,
+): boolean {
+  if (!keywords) return false;
+  return keywords.some((k) => getKeywordTypeName(k) === type);
+}
+
+/**
+ * Get the value of a parameterized keyword (Challenger or Resist)
+ * Returns null if the keyword is not found or is not parameterized
+ */
+export function getKeywordValue(
+  keywords: Keyword[] | undefined,
+  type: "Challenger" | "Resist",
+): number | null {
+  if (!keywords) return null;
+  const keyword = keywords.find(
+    (k) => typeof k === "object" && k.type === type,
+  ) as ParameterizedKeyword | undefined;
+  return keyword?.value ?? null;
+}
+
+/**
+ * Get the total value of a stacking keyword (sums all instances)
+ */
+export function getTotalKeywordValue(
+  keywords: Keyword[] | undefined,
+  type: "Challenger" | "Resist",
+): number {
+  if (!keywords) return 0;
+  return keywords
+    .filter(
+      (k): k is ParameterizedKeyword =>
+        typeof k === "object" && k.type === type,
+    )
+    .reduce((sum, k) => sum + k.value, 0);
+}
+
+/**
+ * Get Shift keyword data if present
+ */
+export function getShiftKeyword(
+  keywords: Keyword[] | undefined,
+): ShiftKeyword | null {
+  if (!keywords) return null;
+  const keyword = keywords.find(
+    (k): k is ShiftKeyword => typeof k === "object" && k.type === "Shift",
+  );
+  return keyword ?? null;
+}
+
+/**
+ * Get Singer keyword value if present
+ */
+export function getSingerValue(keywords: Keyword[] | undefined): number | null {
+  if (!keywords) return null;
+  const keyword = keywords.find(
+    (k): k is SingerKeyword => typeof k === "object" && k.type === "Singer",
+  );
+  return keyword?.value ?? null;
+}
+
+/**
+ * Get Sing Together keyword value if present
+ */
+export function getSingTogetherValue(
+  keywords: Keyword[] | undefined,
+): number | null {
+  if (!keywords) return null;
+  const keyword = keywords.find(
+    (k): k is SingTogetherKeyword =>
+      typeof k === "object" && k.type === "SingTogether",
+  );
+  return keyword?.value ?? null;
+}