@drmxrcy/tcg-core 0.0.0-202602060542

package/src/history/history-manager.ts

@@ -0,0 +1,312 @@
+/**
+ * History Manager
+ *
+ * Manages game move history with Immer-based immutable store.
+ * Tracks all move executions chronologically with player-aware visibility.
+ */
+
+import { nanoid } from "nanoid";
+import type { PlayerId } from "../types/branded";
+import type {
+  FormattedHistoryEntry,
+  HistoryEntry,
+  HistoryQueryOptions,
+  MessageTemplateData,
+  VerbosityLevel,
+  VerbosityMessages,
+} from "./types";
+
+/**
+ * History Manager Options
+ *
+ * Configuration for HistoryManager initialization.
+ */
+export type HistoryManagerOptions = {
+  /** Initial entries (for replay/restore) */
+  initialEntries?: HistoryEntry[];
+};
+
+/**
+ * History Manager
+ *
+ * In-memory store for game move history.
+ * Uses simple array storage (Immer patches handle immutability at engine level).
+ *
+ * @example
+ * ```typescript
+ * const manager = new HistoryManager();
+ *
+ * // Add entry
+ * manager.addEntry({
+ *   moveId: 'playCard',
+ *   playerId: 'p1',
+ *   params: { cardId: 'card-123' },
+ *   timestamp: Date.now(),
+ *   success: true,
+ *   messages: {
+ *     visibility: 'PUBLIC',
+ *     messages: {
+ *       casual: { key: 'moves.playCard', values: { card: 'Knight' } }
+ *     }
+ *   }
+ * });
+ *
+ * // Query history
+ * const entries = manager.query({ playerId: 'p1', verbosity: 'CASUAL' });
+ * ```
+ */
+export class HistoryManager {
+  private entries: HistoryEntry[];
+
+  /**
+   * Create a new HistoryManager
+   *
+   * @param options - Configuration options
+   */
+  constructor(options: HistoryManagerOptions = {}) {
+    this.entries = options.initialEntries ?? [];
+  }
+
+  /**
+   * Add a new history entry
+   *
+   * @param entry - Entry data (without id - will be generated)
+   * @returns The created entry with generated id
+   */
+  addEntry(entry: Omit<HistoryEntry, "id">): HistoryEntry {
+    const fullEntry: HistoryEntry = {
+      id: nanoid(),
+      ...entry,
+    };
+
+    this.entries.push(fullEntry);
+    return fullEntry;
+  }
+
+  /**
+   * Query history entries with filtering and formatting
+   *
+   * @param options - Query options
+   * @returns Formatted entries matching the query
+   */
+  query(options: HistoryQueryOptions = {}): FormattedHistoryEntry[] {
+    const {
+      playerId,
+      verbosity = "CASUAL",
+      since,
+      moveId,
+      includeSuccess = true,
+      includeFailures = true,
+    } = options;
+
+    // Filter entries
+    let filtered = this.entries;
+
+    // Filter by timestamp
+    if (since !== undefined) {
+      filtered = filtered.filter((entry) => entry.timestamp > since);
+    }
+
+    // Filter by move ID
+    if (moveId !== undefined) {
+      filtered = filtered.filter((entry) => entry.moveId === moveId);
+    }
+
+    // Filter by success/failure
+    if (!includeSuccess) {
+      filtered = filtered.filter((entry) => !entry.success);
+    }
+    if (!includeFailures) {
+      filtered = filtered.filter((entry) => entry.success);
+    }
+
+    // Filter by player visibility and format
+    return filtered
+      .map((entry) => this.formatEntry(entry, playerId, verbosity))
+      .filter((entry): entry is FormattedHistoryEntry => entry !== null);
+  }
+
+  /**
+   * Get all entries (raw, no filtering)
+   *
+   * Used for debugging and serialization.
+   *
+   * @returns All history entries
+   */
+  getAllEntries(): readonly HistoryEntry[] {
+    return this.entries;
+  }
+
+  /**
+   * Clear all history entries
+   *
+   * Used for testing.
+   */
+  clear(): void {
+    this.entries = [];
+  }
+
+  /**
+   * Get the number of entries
+   *
+   * @returns Entry count
+   */
+  getCount(): number {
+    return this.entries.length;
+  }
+
+  /**
+   * Check if player can see this entry
+   *
+   * @param entry - History entry
+   * @param playerId - Player requesting access (undefined = see all)
+   * @returns True if player can see this entry
+   */
+  private canPlayerSeeEntry(
+    entry: HistoryEntry,
+    playerId: PlayerId | undefined,
+  ): boolean {
+    // If no player filter, show all entries
+    if (playerId === undefined) {
+      return true;
+    }
+
+    const { messages } = entry;
+
+    // PUBLIC entries are visible to all
+    if (messages.visibility === "PUBLIC") {
+      return true;
+    }
+
+    // PRIVATE entries are visible only to specified players
+    if (messages.visibility === "PRIVATE") {
+      return (
+        messages.visibleTo === undefined ||
+        messages.visibleTo.some((id) => String(id) === String(playerId))
+      );
+    }
+
+    // PLAYER_SPECIFIC entries are visible if player has a message
+    if (messages.visibility === "PLAYER_SPECIFIC") {
+      return String(playerId) in messages.messages;
+    }
+
+    return false;
+  }
+
+  /**
+   * Format an entry for display
+   *
+   * @param entry - Raw history entry
+   * @param playerId - Player requesting the entry (for filtering)
+   * @param verbosity - Verbosity level for message selection
+   * @returns Formatted entry or null if player can't see it
+   */
+  private formatEntry(
+    entry: HistoryEntry,
+    playerId: PlayerId | undefined,
+    verbosity: VerbosityLevel,
+  ): FormattedHistoryEntry | null {
+    // Check visibility
+    if (!this.canPlayerSeeEntry(entry, playerId)) {
+      return null;
+    }
+
+    // Get message for this player and verbosity
+    const message = this.getMessageForPlayer(entry, playerId, verbosity);
+    if (!message) {
+      return null;
+    }
+
+    // Build formatted entry
+    const formatted: FormattedHistoryEntry = {
+      id: entry.id,
+      moveId: entry.moveId,
+      playerId: entry.playerId,
+      timestamp: entry.timestamp,
+      turn: entry.turn,
+      phase: entry.phase,
+      segment: entry.segment,
+      message,
+      success: entry.success,
+      error: entry.error,
+    };
+
+    // Include additional details for DEVELOPER mode
+    if (verbosity === "DEVELOPER") {
+      formatted.metadata = entry.metadata;
+      formatted.params = entry.params;
+    }
+
+    return formatted;
+  }
+
+  /**
+   * Get the appropriate message for a player and verbosity level
+   *
+   * @param entry - History entry
+   * @param playerId - Player requesting the message
+   * @param verbosity - Verbosity level
+   * @returns Message template data or null if no message available
+   */
+  private getMessageForPlayer(
+    entry: HistoryEntry,
+    playerId: PlayerId | undefined,
+    verbosity: VerbosityLevel,
+  ): MessageTemplateData | null {
+    const { messages } = entry;
+
+    // Get verbosity-specific messages
+    let verbosityMessages: VerbosityMessages | undefined;
+
+    if (messages.visibility === "PUBLIC" || messages.visibility === "PRIVATE") {
+      verbosityMessages = messages.messages;
+    } else if (messages.visibility === "PLAYER_SPECIFIC") {
+      // Get player-specific messages
+      if (playerId !== undefined) {
+        verbosityMessages = messages.messages[String(playerId)];
+      } else {
+        // If no player specified, use first available
+        const firstPlayerId = Object.keys(messages.messages)[0];
+        if (firstPlayerId) {
+          verbosityMessages = messages.messages[firstPlayerId];
+        }
+      }
+    }
+
+    if (!verbosityMessages) {
+      return null;
+    }
+
+    // Select message based on verbosity level with fallback
+    return this.selectMessageByVerbosity(verbosityMessages, verbosity);
+  }
+
+  /**
+   * Select message by verbosity level with fallback
+   *
+   * Falls back to less detailed level if requested level not available:
+   * DEVELOPER -> ADVANCED -> CASUAL
+   *
+   * @param messages - Verbosity-specific messages
+   * @param verbosity - Requested verbosity level
+   * @returns Message template data or null if no messages available
+   */
+  private selectMessageByVerbosity(
+    messages: VerbosityMessages,
+    verbosity: VerbosityLevel,
+  ): MessageTemplateData | null {
+    switch (verbosity) {
+      case "DEVELOPER":
+        return (
+          messages.developer ?? messages.advanced ?? messages.casual ?? null
+        );
+      case "ADVANCED":
+        return messages.advanced ?? messages.casual ?? null;
+      case "CASUAL":
+        return messages.casual ?? null;
+      default:
+        return messages.casual ?? null;
+    }
+  }
+}

package/src/history/history-operations.ts

@@ -0,0 +1,122 @@
+/**
+ * History Operations
+ *
+ * Operations API exposed to move reducers via MoveContext.
+ * Allows moves to log custom history entries with player-specific visibility.
+ */
+
+import type { PlayerId } from "../types/branded";
+import type { HistoryManager } from "./history-manager";
+import type { HistoryMessages } from "./types";
+
+/**
+ * History Operations
+ *
+ * API for logging history entries from within move reducers.
+ *
+ * @example
+ * ```typescript
+ * // In a move reducer
+ * reducer: (draft, context) => {
+ *   // Log a public message
+ *   context.history.log({
+ *     messages: {
+ *       visibility: 'PUBLIC',
+ *       messages: {
+ *         casual: { key: 'moves.draw', values: { count: 5 } },
+ *         advanced: { key: 'moves.draw.detailed', values: { cardIds: [...] } }
+ *       }
+ *     }
+ *   });
+ *
+ *   // Log a player-specific message (mulligan)
+ *   context.history.log({
+ *     messages: {
+ *       visibility: 'PLAYER_SPECIFIC',
+ *       messages: {
+ *         [playerId]: {
+ *           casual: { key: 'mulligan.self', values: { cards: [...] } }
+ *         },
+ *         [opponentId]: {
+ *           casual: { key: 'mulligan.opponent', values: { count: 3 } }
+ *         }
+ *       }
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export type HistoryOperations = {
+  /**
+   * Log a custom history entry
+   *
+   * Creates a history entry with custom messages.
+   * Used by move reducers to add detailed logging beyond the automatic entry.
+   *
+   * Note: The engine automatically creates a base history entry for each move.
+   * Use this method to add additional context or player-specific details.
+   *
+   * @param input - Message templates and metadata
+   *
+   * @example
+   * ```typescript
+   * // Log card draw with player-specific visibility
+   * context.history.log({
+   *   messages: {
+   *     visibility: 'PLAYER_SPECIFIC',
+   *     messages: {
+   *       [playerId]: {
+   *         casual: { key: 'draw.self', values: { cards: ['Knight', 'Wizard'] } }
+   *       },
+   *       [opponentId]: {
+   *         casual: { key: 'draw.opponent', values: { count: 2 } }
+   *       }
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  log(input: {
+    messages: HistoryMessages;
+    metadata?: Record<string, unknown>;
+  }): void;
+};
+
+/**
+ * Create History Operations
+ *
+ * Factory for creating HistoryOperations bound to a specific context.
+ *
+ * @param manager - History manager instance
+ * @param context - Move execution context
+ * @returns History operations API
+ */
+export function createHistoryOperations(
+  manager: HistoryManager,
+  context: {
+    moveId: string;
+    playerId: string;
+    params: unknown;
+    timestamp: number;
+    turn?: number;
+    phase?: string;
+    segment?: string;
+  },
+): HistoryOperations {
+  return {
+    log(input) {
+      manager.addEntry({
+        moveId: context.moveId,
+        playerId: context.playerId as PlayerId,
+        params: context.params,
+        timestamp: context.timestamp,
+        turn: context.turn,
+        phase: context.phase,
+        segment: context.segment,
+        success: true,
+        messages: input.messages,
+        metadata: input.metadata,
+      });
+    },
+  };
+}

package/src/history/index.ts

@@ -0,0 +1,9 @@
+/**
+ * History Module
+ *
+ * Game move history system with player-aware visibility and i18next localization.
+ */
+
+export * from "./history-manager";
+export * from "./history-operations";
+export * from "./types";

package/src/history/types.ts

@@ -0,0 +1,255 @@
+/**
+ * History Types
+ *
+ * Type definitions for the game move history system.
+ * Provides structured move logging with player-aware visibility and i18next localization.
+ */
+
+import type { PlayerId } from "../types/branded";
+
+/**
+ * Verbosity Level
+ *
+ * Controls the level of detail in history messages:
+ * - CASUAL: Simple, narrative descriptions for casual players
+ * - ADVANCED: Technical details for competitive players
+ * - DEVELOPER: Full internal details for debugging
+ */
+export type VerbosityLevel = "CASUAL" | "ADVANCED" | "DEVELOPER";
+
+/**
+ * Visibility Level
+ *
+ * Controls who can see a history entry:
+ * - PUBLIC: Visible to all players
+ * - PRIVATE: Visible only to specific player(s)
+ * - PLAYER_SPECIFIC: Different details shown to different players
+ */
+export type VisibilityLevel = "PUBLIC" | "PRIVATE" | "PLAYER_SPECIFIC";
+
+/**
+ * Message Template Data
+ *
+ * i18next-compatible message template with interpolation values.
+ *
+ * @example
+ * ```typescript
+ * // Template: "{{player}} drew {{count}} cards"
+ * {
+ *   key: "moves.draw.success",
+ *   values: { player: "Player 1", count: 5 }
+ * }
+ * ```
+ */
+export type MessageTemplateData = {
+  /** i18next translation key */
+  key: string;
+
+  /** Interpolation values for the template */
+  values?: Record<string, unknown>;
+};
+
+/**
+ * Verbosity-Specific Messages
+ *
+ * Different message templates for different verbosity levels.
+ * All levels are optional; if not provided, falls back to less detailed level.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   casual: { key: "moves.mulligan.casual", values: { count: 3 } },
+ *   advanced: { key: "moves.mulligan.advanced", values: { cardIds: [...] } },
+ *   developer: { key: "moves.mulligan.dev", values: { fullContext: {...} } }
+ * }
+ * ```
+ */
+export type VerbosityMessages = {
+  /** Message for casual players (simple, narrative) */
+  casual?: MessageTemplateData;
+
+  /** Message for advanced players (technical details) */
+  advanced?: MessageTemplateData;
+
+  /** Message for developers (full internal details) */
+  developer?: MessageTemplateData;
+};
+
+/**
+ * Player-Specific Message Data
+ *
+ * Different message templates shown to different players.
+ * Used for moves with private information (e.g., opponent mulligans).
+ *
+ * @example
+ * ```typescript
+ * // Mulligan: owning player sees cards, opponent sees count only
+ * {
+ *   player_one: {
+ *     casual: { key: "mulligan.self", values: { cards: ["card1", "card2"] } }
+ *   },
+ *   player_two: {
+ *     casual: { key: "mulligan.opponent", values: { count: 2 } }
+ *   }
+ * }
+ * ```
+ */
+export type PlayerSpecificMessages = Record<string, VerbosityMessages>;
+
+/**
+ * History Entry Messages
+ *
+ * Message templates for a history entry.
+ * Can be public (same for all) or player-specific (different per player).
+ */
+export type HistoryMessages =
+  | {
+      visibility: "PUBLIC" | "PRIVATE";
+      /** Messages at different verbosity levels */
+      messages: VerbosityMessages;
+      /** If PRIVATE, which player(s) can see this entry */
+      visibleTo?: PlayerId[];
+    }
+  | {
+      visibility: "PLAYER_SPECIFIC";
+      /** Different messages for different players */
+      messages: PlayerSpecificMessages;
+    };
+
+/**
+ * History Entry
+ *
+ * A single entry in the game move history.
+ * Contains all information about a move execution including messages,
+ * visibility, and raw data for debugging.
+ */
+export type HistoryEntry = {
+  /** Unique identifier for this entry */
+  id: string;
+
+  /** Move ID that was executed */
+  moveId: string;
+
+  /** Player who executed the move */
+  playerId: PlayerId;
+
+  /** Move-specific parameters */
+  params: unknown;
+
+  /** Timestamp when move was executed (milliseconds) */
+  timestamp: number;
+
+  /** Turn number when move was executed */
+  turn?: number;
+
+  /** Game phase when move was executed */
+  phase?: string;
+
+  /** Game segment when move was executed */
+  segment?: string;
+
+  /** Message templates for this entry */
+  messages: HistoryMessages;
+
+  /** Whether the move was successful */
+  success: boolean;
+
+  /** Error information if move failed */
+  error?: {
+    /** Error code */
+    code: string;
+    /** Error message */
+    message: string;
+    /** Additional error context */
+    context?: Record<string, unknown>;
+  };
+
+  /** Additional metadata for debugging */
+  metadata?: Record<string, unknown>;
+};
+
+/**
+ * Formatted History Entry
+ *
+ * A history entry with formatted message ready for display.
+ * Returned by getHistory() after filtering and formatting.
+ */
+export type FormattedHistoryEntry = {
+  /** Unique identifier for this entry */
+  id: string;
+
+  /** Move ID that was executed */
+  moveId: string;
+
+  /** Player who executed the move */
+  playerId: PlayerId;
+
+  /** Timestamp when move was executed (milliseconds) */
+  timestamp: number;
+
+  /** Turn number when move was executed */
+  turn?: number;
+
+  /** Game phase when move was executed */
+  phase?: string;
+
+  /** Game segment when move was executed */
+  segment?: string;
+
+  /** Formatted message ready for display */
+  message: MessageTemplateData;
+
+  /** Whether the move was successful */
+  success: boolean;
+
+  /** Error information if move failed */
+  error?: {
+    code: string;
+    message: string;
+    context?: Record<string, unknown>;
+  };
+
+  /** Additional metadata (only included in DEVELOPER mode) */
+  metadata?: Record<string, unknown>;
+
+  /** Raw parameters (only included in DEVELOPER mode) */
+  params?: unknown;
+};
+
+/**
+ * History Query Options
+ *
+ * Options for querying game history.
+ */
+export type HistoryQueryOptions = {
+  /** Filter to entries visible to this player (undefined = all entries) */
+  playerId?: PlayerId;
+
+  /** Verbosity level for message formatting */
+  verbosity?: VerbosityLevel;
+
+  /** Only return entries after this timestamp */
+  since?: number;
+
+  /** Only return entries for this move ID */
+  moveId?: string;
+
+  /** Include successful moves (default: true) */
+  includeSuccess?: boolean;
+
+  /** Include failed moves (default: true) */
+  includeFailures?: boolean;
+};
+
+/**
+ * Log Entry Input
+ *
+ * Input data for creating a history entry via context.history.log()
+ */
+export type LogEntryInput = {
+  /** Message templates for this entry */
+  messages: HistoryMessages;
+
+  /** Additional metadata for debugging */
+  metadata?: Record<string, unknown>;
+};