sashite-ggn 0.5.0 → 0.6.0

data/lib/sashite/ggn/ruleset/source/destination/engine.rb

@@ -14,13 +14,23 @@ module Sashite
           # is valid under the basic movement constraints defined in GGN. It evaluates
           # require/prevent conditions and returns the resulting board transformation.
           #
+          # Since GGN focuses exclusively on board-to-board transformations, the Engine
+          # only handles pieces moving, capturing, or transforming on the game board.
+          #
           # The class uses a functional approach with filter_map for optimal performance
           # and clean, readable code that avoids mutation of external variables.
           #
-          # @example Evaluating a move
+          # @example Evaluating a simple move
           #   engine = destinations.to('e4')
-          #   result = engine.where(board_state, {}, 'CHESS')
-          #   puts "Move valid!" if result.any?
+          #   transitions = engine.where(board_state, 'CHESS')
+          #   puts "Move valid!" if transitions.any?
+          #
+          # @example Handling promotion choices
+          #   engine = destinations.to('e8')  # pawn promotion
+          #   transitions = engine.where(board_state, 'CHESS')
+          #   transitions.each_with_index do |t, i|
+          #     puts "Choice #{i + 1}: promotes to #{t.diff['e8']}"
+          #   end
           class Engine
             include MoveValidator
 
@@ -29,10 +39,19 @@ module Sashite
             # @param transitions [Array] Transition rules as individual arguments,
             #   each containing require/prevent conditions and perform actions.
             # @param actor [String] GAN identifier of the piece being moved
-            # @param origin [String] Source square or "*" for drops
+            # @param origin [String] Source square
             # @param target [String] Destination square
             #
             # @raise [ArgumentError] If parameters are invalid
+            #
+            # @example Creating an engine for a pawn move
+            #   transition_rules = [
+            #     {
+            #       "require" => { "e4" => "empty", "e3" => "empty" },
+            #       "perform" => { "e2" => nil, "e4" => "CHESS:P" }
+            #     }
+            #   ]
+            #   engine = Engine.new(*transition_rules, actor: "CHESS:P", origin: "e2", target: "e4")
             def initialize(*transitions, actor:, origin:, target:)
               raise ::ArgumentError, "actor must be a String" unless actor.is_a?(::String)
               raise ::ArgumentError, "origin must be a String" unless origin.is_a?(::String)
@@ -55,8 +74,8 @@ module Sashite
             #
             # @param board_state [Hash] Current board state mapping square labels
             #   to piece identifiers (nil for empty squares)
-            # @param captures [Hash] Available pieces in hand (for drops)
-            # @param turn [String] Current player's game identifier (e.g., 'CHESS', 'shogi')
+            # @param active_game [String] Current player's game identifier (e.g., 'CHESS', 'shogi').
+            #   This corresponds to the first element of the GAMES-TURN field in FEEN notation.
             #
             # @return [Array<Transition>] Array of Transition objects for all valid variants,
             #   empty array if no valid transitions exist
@@ -65,31 +84,35 @@ module Sashite
             #
             # @example Single valid move
             #   board_state = { 'e2' => 'CHESS:P', 'e3' => nil, 'e4' => nil }
-            #   results = engine.where(board_state, {}, 'CHESS')
-            #   results.size  # => 1
-            #   results.first.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
+            #   transitions = engine.where(board_state, 'CHESS')
+            #   transitions.size  # => 1
+            #   transitions.first.diff  # => { 'e2' => nil, 'e4' => 'CHESS:P' }
             #
             # @example Multiple promotion choices
             #   board_state = { 'e7' => 'CHESS:P', 'e8' => nil }
-            #   results = engine.where(board_state, {}, 'CHESS')
-            #   results.size  # => 4 (Queen, Rook, Bishop, Knight)
-            #   results.map { |r| r.diff['e8'] }  # => ['CHESS:Q', 'CHESS:R', 'CHESS:B', 'CHESS:N']
+            #   transitions = engine.where(board_state, 'CHESS')
+            #   transitions.size  # => 4 (Queen, Rook, Bishop, Knight)
+            #   transitions.map { |t| t.diff['e8'] }  # => ['CHESS:Q', 'CHESS:R', 'CHESS:B', 'CHESS:N']
+            #
+            # @example Invalid move (wrong piece)
+            #   board_state = { 'e2' => 'CHESS:Q', 'e3' => nil, 'e4' => nil }
+            #   transitions = engine.where(board_state, 'CHESS')  # => []
             #
             # @example Invalid move (blocked path)
             #   board_state = { 'e2' => 'CHESS:P', 'e3' => 'CHESS:N', 'e4' => nil }
-            #   results = engine.where(board_state, {}, 'CHESS')  # => []
-            def where(board_state, captures, turn)
+            #   transitions = engine.where(board_state, 'CHESS')  # => []
+            def where(board_state, active_game)
               # Validate all input parameters before processing
-              validate_parameters!(board_state, captures, turn)
+              validate_parameters!(board_state, active_game)
 
-              # Early return if basic move context is invalid (wrong piece, not in hand, etc.)
-              return [] unless valid_move_context?(board_state, captures, turn)
+              # Early return if basic move context is invalid (wrong piece, wrong player, etc.)
+              return [] unless valid_move_context?(board_state, active_game)
 
               # Use filter_map for functional approach: filter valid transitions and map to Transition objects
               # This avoids mutation and is more performant than select + map for large datasets
               @transitions.filter_map do |transition|
                 # Only create Transition objects for transitions that match current board state
-                create_transition(transition) if transition_matches?(transition, board_state, turn)
+                create_transition(transition) if transition_matches?(transition, board_state, active_game)
               end
             end
 
@@ -99,69 +122,54 @@ module Sashite
             # Uses the shared MoveValidator module for consistency across the codebase.
             #
             # This method performs essential pre-checks:
-            # - For drops: ensures the piece is available in hand
-            # - For board moves: ensures the piece is at the expected origin square
-            # - For all moves: ensures the piece belongs to the current player
+            # - Ensures the piece is at the expected origin square
+            # - Ensures the piece belongs to the current player
             #
             # @param board_state [Hash] Current board state
-            # @param captures [Hash] Available pieces in hand
-            # @param turn [String] Current player's game identifier
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if the move context is valid
-            def valid_move_context?(board_state, captures, turn)
-              # Check availability based on move type (drop vs regular move)
-              if @origin == DROP_ORIGIN
-                # For drops, piece must be available in player's hand
-                return false unless piece_available_in_hand?(@actor, captures)
-              else
-                # For regular moves, piece must be on the board at origin square
-                return false unless piece_on_board_at_origin?(@actor, @origin, board_state)
-              end
+            def valid_move_context?(board_state, active_game)
+              # For all moves, piece must be on the board at origin square
+              return false unless piece_on_board_at_origin?(@actor, @origin, board_state)
 
               # Verify piece ownership - only current player can move their pieces
-              piece_belongs_to_current_player?(@actor, turn)
+              piece_belongs_to_current_player?(@actor, active_game)
             end
 
             # Creates a new Transition object from a transition rule.
             # Extracted to improve readability and maintainability of the main logic.
             #
-            # @param transition [Hash] The transition rule containing gain, drop, and perform data
+            # Note: GGN no longer supports gain/drop fields, so Transition creation
+            # is simplified to only handle board transformations.
+            #
+            # @param transition [Hash] The transition rule containing perform data
             #
             # @return [Transition] A new immutable Transition object
             def create_transition(transition)
-              Transition.new(
-                transition["gain"],
-                transition["drop"],
-                **transition["perform"]
-              )
+              Transition.new(**transition["perform"])
             end
 
             # Validates all parameters in one consolidated method.
             # Provides comprehensive validation with clear error messages for debugging.
             #
             # @param board_state [Object] Should be a Hash
-            # @param captures [Object] Should be a Hash
-            # @param turn [Object] Should be a String
+            # @param active_game [Object] Should be a String
             #
             # @raise [ArgumentError] If any parameter is invalid
-            def validate_parameters!(board_state, captures, turn)
+            def validate_parameters!(board_state, active_game)
               # Type validation with clear error messages
               unless board_state.is_a?(::Hash)
                 raise ::ArgumentError, "board_state must be a Hash, got #{board_state.class}"
               end
 
-              unless captures.is_a?(::Hash)
-                raise ::ArgumentError, "captures must be a Hash, got #{captures.class}"
-              end
-
-              unless turn.is_a?(::String)
-                raise ::ArgumentError, "turn must be a String, got #{turn.class}"
+              unless active_game.is_a?(::String)
+                raise ::ArgumentError, "active_game must be a String, got #{active_game.class}"
               end
 
               # Content validation - ensures data integrity
               validate_board_state!(board_state)
-              validate_captures!(captures)
-              validate_turn!(turn)
+              validate_active_game!(active_game)
             end
 
             # Validates board_state structure and content.
@@ -178,7 +186,7 @@ module Sashite
             end
 
             # Validates a square label according to GGN requirements.
-            # Square labels must be non-empty strings and cannot conflict with reserved values.
+            # Square labels must be non-empty strings.
             #
             # @param square [Object] Square label to validate
             #
@@ -187,11 +195,6 @@ module Sashite
               unless square.is_a?(::String) && !square.empty?
                 raise ::ArgumentError, "Invalid square label: #{square.inspect}. Must be a non-empty String."
               end
-
-              # Prevent conflicts with reserved drop origin marker
-              if square == DROP_ORIGIN
-                raise ::ArgumentError, "Square label cannot be '#{DROP_ORIGIN}' (reserved for drops)."
-              end
             end
 
             # Validates a piece on the board.
@@ -213,61 +216,19 @@ module Sashite
               end
             end
 
-            # Validates captures structure and content.
-            # Ensures piece identifiers are base form GAN and counts are non-negative integers.
+            # Validates active_game format according to GAN specification.
+            # Active game must be a non-empty alphabetic game identifier.
             #
-            # @param captures [Hash] Captures to validate
+            # @param active_game [String] Active game identifier to validate
             #
-            # @raise [ArgumentError] If captures contains invalid data
-            def validate_captures!(captures)
-              captures.each do |piece, count|
-                validate_capture_piece!(piece)
-                validate_capture_count!(count, piece)
+            # @raise [ArgumentError] If active game format is invalid
+            def validate_active_game!(active_game)
+              if active_game.empty?
+                raise ::ArgumentError, "active_game cannot be empty"
               end
-            end
 
-            # Validates a piece identifier in captures.
-            # Captured pieces must be in base form (no modifiers) according to FEEN specification.
-            #
-            # @param piece [Object] Piece identifier to validate
-            #
-            # @raise [ArgumentError] If piece identifier is invalid
-            def validate_capture_piece!(piece)
-              unless piece.is_a?(::String) && !piece.empty?
-                raise ::ArgumentError, "Invalid piece identifier in captures: #{piece.inspect}. Must be a non-empty String."
-              end
-
-              unless valid_base_gan_identifier?(piece)
-                raise ::ArgumentError, "Invalid base GAN identifier in captures: #{piece.inspect}. Must be base form GAN (e.g., 'CHESS:P', 'shogi:k') without modifiers."
-              end
-            end
-
-            # Validates a capture count.
-            # Counts must be non-negative integers representing available pieces.
-            #
-            # @param count [Object] Count to validate
-            # @param piece [String] Associated piece for error context
-            #
-            # @raise [ArgumentError] If count is invalid
-            def validate_capture_count!(count, piece)
-              unless count.is_a?(::Integer) && count >= 0
-                raise ::ArgumentError, "Invalid count for piece #{piece}: #{count.inspect}. Must be a non-negative Integer."
-              end
-            end
-
-            # Validates turn format according to GAN specification.
-            # Turn must be a non-empty alphabetic game identifier.
-            #
-            # @param turn [String] Turn identifier to validate
-            #
-            # @raise [ArgumentError] If turn format is invalid
-            def validate_turn!(turn)
-              if turn.empty?
-                raise ::ArgumentError, "turn cannot be empty"
-              end
-
-              unless valid_game_identifier?(turn)
-                raise ::ArgumentError, "Invalid turn format: #{turn.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
+              unless valid_game_identifier?(active_game)
+                raise ::ArgumentError, "Invalid active_game format: #{active_game.inspect}. Must be a valid game identifier (alphabetic characters only, e.g., 'CHESS', 'shogi')."
               end
             end
 
@@ -297,57 +258,23 @@ module Sashite
               end
             end
 
-            # Validates if a string is a valid base GAN identifier (no modifiers).
-            # Used for pieces in hand which cannot have state modifiers.
-            #
-            # @param identifier [String] Base GAN identifier to validate
-            #
-            # @return [Boolean] true if valid base GAN format
-            def valid_base_gan_identifier?(identifier)
-              return false unless identifier.include?(':')
-
-              game_part, piece_part = identifier.split(':', 2)
-
-              return false unless valid_game_identifier?(game_part)
-              return false if piece_part.length != 1
-
-              # Check casing consistency for base form
-              if game_part == game_part.upcase
-                piece_part == piece_part.upcase && /\A[A-Z]\z/.match?(piece_part)
-              else
-                piece_part == piece_part.downcase && /\A[a-z]\z/.match?(piece_part)
-              end
-            end
-
-            # Validates if a string is a valid game identifier.
-            # Game identifiers must be purely alphabetic (all upper or all lower case).
-            #
-            # @param identifier [String] Game identifier to validate
-            #
-            # @return [Boolean] true if valid game identifier format
-            def valid_game_identifier?(identifier)
-              return false if identifier.empty?
-
-              /\A([A-Z]+|[a-z]+)\z/.match?(identifier)
-            end
-
             # Checks if a transition matches the current board state.
             # Evaluates both require conditions (must be true) and prevent conditions (must be false).
             #
             # @param transition [Hash] The transition rule to evaluate
             # @param board_state [Hash] Current board state
-            # @param turn [String] Current player identifier
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if the transition is valid for current state
-            def transition_matches?(transition, board_state, turn)
+            def transition_matches?(transition, board_state, active_game)
               # Ensure transition is properly formatted
               return false unless transition.is_a?(::Hash) && transition.key?("perform")
 
               # Check require conditions (all must be satisfied - logical AND)
-              return false if has_require_conditions?(transition) && !check_require_conditions(transition["require"], board_state, turn)
+              return false if has_require_conditions?(transition) && !check_require_conditions(transition["require"], board_state, active_game)
 
               # Check prevent conditions (none must be satisfied - logical NOR)
-              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, turn)
+              return false if has_prevent_conditions?(transition) && !check_prevent_conditions(transition["prevent"], board_state, active_game)
 
               true
             end
@@ -375,13 +302,13 @@ module Sashite
             #
             # @param require_conditions [Hash] Square -> required state mappings
             # @param board_state [Hash] Current board state
-            # @param turn [String] Current player identifier
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if all conditions are satisfied
-            def check_require_conditions(require_conditions, board_state, turn)
+            def check_require_conditions(require_conditions, board_state, active_game)
               require_conditions.all? do |square, required_state|
                 actual_piece = board_state[square]
-                matches_state?(actual_piece, required_state, turn)
+                matches_state?(actual_piece, required_state, active_game)
               end
             end
 
@@ -390,13 +317,13 @@ module Sashite
             #
             # @param prevent_conditions [Hash] Square -> forbidden state mappings
             # @param board_state [Hash] Current board state
-            # @param turn [String] Current player identifier
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if no forbidden conditions are satisfied
-            def check_prevent_conditions(prevent_conditions, board_state, turn)
+            def check_prevent_conditions(prevent_conditions, board_state, active_game)
               prevent_conditions.none? do |square, forbidden_state|
                 actual_piece = board_state[square]
-                matches_state?(actual_piece, forbidden_state, turn)
+                matches_state?(actual_piece, forbidden_state, active_game)
               end
             end
 
@@ -405,15 +332,15 @@ module Sashite
             #
             # @param actual_piece [String, nil] The piece currently on the square
             # @param expected_state [String] The expected/forbidden state
-            # @param turn [String] Current player identifier
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if the piece matches the expected state
-            def matches_state?(actual_piece, expected_state, turn)
+            def matches_state?(actual_piece, expected_state, active_game)
               case expected_state
               when "empty"
                 actual_piece.nil?
               when "enemy"
-                actual_piece && enemy_piece?(actual_piece, turn)
+                actual_piece && enemy_piece?(actual_piece, active_game)
               else
                 # Exact piece match
                 actual_piece == expected_state
@@ -421,30 +348,23 @@ module Sashite
             end
 
             # Determines if a piece belongs to the opposing player.
-            # Uses GAN casing conventions to determine ownership.
+            # Uses GAN casing conventions to determine ownership based on case correspondence.
             #
-            # @param piece [String] The piece identifier to check
-            # @param turn [String] Current player identifier
+            # @param piece [String] The piece identifier to check (must be GAN format)
+            # @param active_game [String] Current player identifier
             #
             # @return [Boolean] true if piece belongs to opponent
-            def enemy_piece?(piece, turn)
+            def enemy_piece?(piece, active_game)
               return false if piece.nil? || piece.empty?
+              return false unless piece.include?(':')
 
-              if piece.include?(':')
-                # Use GAN format for ownership determination
-                game_part = piece.split(':', 2).fetch(0)
-                piece_is_uppercase_player = game_part == game_part.upcase
-                current_is_uppercase_player = turn == turn.upcase
+              # Use GAN format for ownership determination
+              game_part = piece.split(':', 2).fetch(0)
+              piece_is_uppercase_player = game_part == game_part.upcase
+              current_is_uppercase_player = active_game == active_game.upcase
 
-                # Enemy if players have different casing
-                piece_is_uppercase_player != current_is_uppercase_player
-              else
-                # Fallback for non-GAN format (legacy support)
-                piece_is_uppercase = piece == piece.upcase
-                current_is_uppercase = turn == turn.upcase
-
-                piece_is_uppercase != current_is_uppercase
-              end
+              # Enemy if players have different casing
+              piece_is_uppercase_player != current_is_uppercase_player
             end
           end
         end

data/lib/sashite/ggn/ruleset/source/destination.rb

@@ -10,12 +10,20 @@ module Sashite
         #
         # A Destination instance contains all the target squares a piece can reach
         # from a given starting position, along with the conditional rules that
-        # govern each potential move.
+        # govern each potential move. Since GGN focuses exclusively on board-to-board
+        # transformations, all destinations represent squares on the game board.
         #
         # @example Basic usage
         #   destinations = source.from('e1')
         #   engine = destinations.to('e2')
-        #   result = engine.evaluate(board_state, captures, current_player)
+        #   transitions = engine.where(board_state, 'CHESS')
+        #
+        # @example Exploring all possible destinations
+        #   destinations = source.from('e1')
+        #   # destinations.to('e2') - one square forward
+        #   # destinations.to('f1') - one square right
+        #   # destinations.to('d1') - one square left
+        #   # Each destination has its own movement rules and conditions
         class Destination
           # Creates a new Destination instance from target square data.
           #
@@ -25,6 +33,17 @@ module Sashite
           # @param origin [String] The source position
           #
           # @raise [ArgumentError] If data is not a Hash
+          #
+          # @example Creating a Destination instance
+          #   destination_data = {
+          #     "e2" => [
+          #       { "require" => { "e2" => "empty" }, "perform" => { "e1" => nil, "e2" => "CHESS:K" } }
+          #     ],
+          #     "f1" => [
+          #       { "require" => { "f1" => "empty" }, "perform" => { "e1" => nil, "f1" => "CHESS:K" } }
+          #     ]
+          #   }
+          #   destination = Destination.new(destination_data, actor: "CHESS:K", origin: "e1")
           def initialize(data, actor:, origin:)
             raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
 
@@ -37,16 +56,28 @@ module Sashite
 
           # Retrieves the movement engine for a specific target square.
           #
-          # @param target [String] The destination square label (e.g., 'e2', '5h').
+          # This method creates an Engine instance that can evaluate whether the move
+          # to the specified target square is valid given the current board conditions.
+          # The engine encapsulates all the conditional logic (require/prevent/perform)
+          # for this specific source-to-destination move.
           #
-          # @return [Engine] An Engine instance that can evaluate whether the move
-          #   to this target is valid given current board conditions.
+          # @param target [String] The destination square label (e.g., 'e2', '5h', 'a8').
+          #
+          # @return [Engine] An Engine instance that can evaluate move validity
+          #   and return all possible transition variants for this move.
           #
           # @raise [KeyError] If the target square is not reachable from the source
           #
           # @example Getting movement rules to a specific square
           #   engine = destinations.to('e2')
-          #   result = engine.evaluate(board_state, captures, current_player)
+          #   transitions = engine.where(board_state, 'CHESS')
+          #
+          #   if transitions.any?
+          #     puts "Move is valid!"
+          #     transitions.each { |t| puts "Result: #{t.diff}" }
+          #   else
+          #     puts "Move is not valid under current conditions"
+          #   end
           #
           # @example Handling unreachable targets
           #   begin
@@ -54,9 +85,24 @@ module Sashite
           #   rescue KeyError => e
           #     puts "Cannot move to this square: #{e.message}"
           #   end
+          #
+          # @example Testing multiple destinations
+          #   ['e2', 'f1', 'd1'].each do |target|
+          #     begin
+          #       engine = destinations.to(target)
+          #       transitions = engine.where(board_state, 'CHESS')
+          #       puts "#{target}: #{transitions.size} possible transitions"
+          #     rescue KeyError
+          #       puts "#{target}: not reachable"
+          #     end
+          #   end
+          #
+          # @note The returned Engine handles all the complexity of move validation,
+          #   including require/prevent conditions and multiple move variants
+          #   (such as promotion choices).
           def to(target)
             transitions = @data.fetch(target)
-            Engine.new(*transitions, actor: @actor, origin: @origin, target:)
+            Engine.new(*transitions, actor: @actor, origin: @origin, target: target)
           end
         end
       end

data/lib/sashite/ggn/ruleset/source.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative File.join("..", "move_validator")
 require_relative File.join("source", "destination")
 
 module Sashite
@@ -8,26 +9,44 @@ module Sashite
       # Represents the possible source positions for a specific piece type.
       #
       # A Source instance contains all the starting positions from which
-      # a piece can move, including regular board squares and special
-      # positions like "*" for piece drops from hand.
+      # a piece can move on the board. Since GGN focuses exclusively on
+      # board-to-board transformations, all source positions are regular
+      # board squares.
       #
       # @example Basic usage with chess king
       #   piece_data = Sashite::Ggn.load_file('chess.json')
       #   source = piece_data.select('CHESS:K')
       #   destinations = source.from('e1')
       #
-      # @example Usage with Shogi pawn drops
-      #   piece_data = Sashite::Ggn.load_file('shogi.json')
-      #   pawn_source = piece_data.select('SHOGI:P')
-      #   drop_destinations = pawn_source.from('*')  # For piece drops from hand
+      # @example Complete move evaluation workflow
+      #   piece_data = Sashite::Ggn.load_file('chess.json')
+      #   king_source = piece_data.select('CHESS:K')
+      #   destinations = king_source.from('e1')
+      #   engine = destinations.to('e2')
+      #
+      #   board_state = { 'e1' => 'CHESS:K', 'e2' => nil }
+      #   transitions = engine.where(board_state, 'CHESS')
+      #
+      #   if transitions.any?
+      #     puts "King can move from e1 to e2"
+      #   end
       class Source
+        include MoveValidator
+
         # Creates a new Source instance from movement data.
         #
         # @param data [Hash] The movement data where keys are source positions
-        #   (square labels or "*" for drops) and values contain destination data.
+        #   (square labels) and values contain destination data.
         # @param actor [String] The GAN identifier for this piece type
         #
         # @raise [ArgumentError] If data is not a Hash
+        #
+        # @example Creating a Source instance
+        #   source_data = {
+        #     "e1" => { "e2" => [...], "f1" => [...] },
+        #     "d4" => { "d5" => [...], "e5" => [...] }
+        #   }
+        #   source = Source.new(source_data, actor: "CHESS:K")
         def initialize(data, actor:)
           raise ::ArgumentError, "Expected Hash, got #{data.class}" unless data.is_a?(::Hash)
 
@@ -39,8 +58,8 @@ module Sashite
 
         # Retrieves possible destinations from a specific source position.
         #
-        # @param origin [String] The source position label. Can be a regular
-        #   square label (e.g., 'e1', '5i') or "*" for piece drops from hand.
+        # @param origin [String] The source position label. Must be a regular
+        #   square label (e.g., 'e1', '5i', 'a1').
         #
         # @return [Destination] A Destination instance containing all possible
         #   target squares and their movement conditions from this origin.
@@ -51,19 +70,28 @@ module Sashite
         #   destinations = source.from('e1')
         #   engine = destinations.to('e2')
         #
-        # @example Getting drop moves (for games like Shogi)
-        #   drop_destinations = source.from('*')
-        #   engine = drop_destinations.to('5e')
-        #
         # @example Handling missing origins
         #   begin
         #     destinations = source.from('invalid_square')
         #   rescue KeyError => e
         #     puts "No moves from this position: #{e.message}"
         #   end
+        #
+        # @example Iterating through all possible origins
+        #   # Assuming you have access to the source data keys
+        #   available_origins = ['e1', 'd1', 'f1']  # example origins
+        #   available_origins.each do |pos|
+        #     begin
+        #       destinations = source.from(pos)
+        #       puts "Piece can move from #{pos}"
+        #       # Process destinations...
+        #     rescue KeyError
+        #       puts "No moves available from #{pos}"
+        #     end
+        #   end
         def from(origin)
           data = @data.fetch(origin)
-          Destination.new(data, actor: @actor, origin:)
+          Destination.new(data, actor: @actor, origin: origin)
         end
       end
     end