feen 5.0.0.beta8 → 5.0.0.beta10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4b55ca0d1584708dbb732475262b5c22ce42fc8c77b6822a51a19832fde6ca
-  data.tar.gz: 9662571dc247824251d1d256783dac5236e5f54acbdb5fb9041d4c2471733f0a
+  metadata.gz: 3038a2be98c26b830833d6f7fece5d050605da9ead72ee8cdedecf98e31f30ef
+  data.tar.gz: 2868f4ca7e04b472f059e982023129c36af9718ad819f07f09343ad34a0d611c
 SHA512:
-  metadata.gz: 5d8c6e55a5d6ec7809af8df89ee212503dccc67590384ec9c6e403a4dab5a8b54bcc2c4dd93a6fef0060e23f327e592a8263779bc1060ab74738306b0ce7a117
-  data.tar.gz: 68cc013cef6eac0309a2241c697133459f242fa472325e2dd0e8a97ec2c7d134c372883e16f1532ba7ba8a3ca8bb793ed93e1f2a670427bc6698a9a2601cb95b
+  metadata.gz: 1ec8030d85d0c06bc11f63cdde1bc32a1ad2b709fb982cde496478d5c8dd9ea607c1b6089451e0ff3442857cb1936ded576143f9a7781419626905a04c3b8e01
+  data.tar.gz: 047e36e257acdca693fd88cceb99e946bfa3b0eefe86719f72f3addbc9adef543fc0ce82bcafe59dae7fbc7dad7ede27848550280de1a7adf288a89d795cf4ba

data/README.md

@@ -5,7 +5,7 @@
 ![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
 
-> A Ruby library for **FEEN** (Forsyth–Edwards Enhanced Notation) - a flexible format for representing positions in two-player piece-placement games.
+> A Ruby library for **FEEN** (Forsyth–Edwards Enhanced Notation) - a compact, canonical, and rule-agnostic textual format for representing static board positions in two-player piece-placement games.
 
 ## What is FEEN?
 
@@ -13,18 +13,19 @@ FEEN is like taking a snapshot of any board game position and turning it into a
 
 **Key Features:**
 
-- **Versatile**: Supports Chess, Shōgi, Xiangqi, and similar games
-- **Bidirectional**: Convert positions to text and back
-- **Compact**: Efficient representation
 - **Rule-agnostic**: No knowledge of specific game rules required
-- **Multi-dimensional**: Supports 2D, 3D, and higher dimensions
+- **Canonical**: Equivalent positions yield identical strings
+- **Cross-style support**: Handles hybrid configurations with different piece sets
+- **Multi-dimensional**: Supports 2D, 3D, and higher dimensional boards
+- **Captured pieces**: Full support for pieces-in-hand mechanics
+- **Compact**: Efficient representation with compression for empty spaces
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "feen", ">= 5.0.0.beta8"
+gem "feen", ">= 5.0.0.beta10"
 ```
 
 Or install it directly:
@@ -45,8 +46,8 @@ board = [["r", "k", "r"]]
 
 feen_string = Feen.dump(
   piece_placement: board,
-  pieces_in_hand:  [],           # No captured pieces
-  games_turn:      ["GAME", "game"]  # GAME player's turn
+  pieces_in_hand:  [],              # No captured pieces
+  style_turn:      ["GAME", "game"] # GAME player's turn
 )
 
 feen_string # => "rkr / GAME/game"
@@ -62,7 +63,7 @@ position = Feen.parse(feen_string)
 
 position[:piece_placement]  # => ["r", "k", "r"]
 position[:pieces_in_hand]   # => []
-position[:games_turn]       # => ["GAME", "game"]
+position[:style_turn]       # => ["GAME", "game"]
 ```
 
 ## Understanding FEEN Format
@@ -70,62 +71,98 @@ position[:games_turn]       # => ["GAME", "game"]
 A FEEN string has exactly **three parts separated by single spaces**:
 
 ```
-<BOARD> <CAPTURED_PIECES> <TURN_INFO>
+<PIECE-PLACEMENT> <PIECES-IN-HAND> <STYLE-TURN>
 ```
 
-### Part 1: Board Representation
+### Part 1: Piece Placement
 
-The board shows where pieces are placed:
+The board shows where pieces are placed, always from the point of view of the player who plays first in the initial position:
 
-- **Pieces**: Represented by letters (case matters!)
-  - `K` = piece belonging to first player (uppercase)
-  - `k` = piece belonging to second player (lowercase)
+- **Pieces**: Represented by PNN notation (case matters!)
+  - `K` = piece belonging to first player (uppercase style)
+  - `k` = piece belonging to second player (lowercase style)
+  - `+P` = enhanced piece (modifier allowed on board only)
+  - `-R` = diminished piece (modifier allowed on board only)
+  - `N'` = intermediate state piece (modifier allowed on board only)
 - **Empty spaces**: Represented by numbers
   - `3` = three empty squares in a row
 - **Ranks (rows)**: Separated by `/`
+- **Higher dimensions**: Use multiple `/` characters (`//`, `///`, etc.)
 
 **Examples:**
 
 ```ruby
-"K"           # Single piece on 1x1 board
-"3"           # Three empty squares
-"Kqr"         # Three pieces: K, q, r
-"K2r"         # K, two empty squares, then r
-"Kqr/3/R2k"   # 3x3 board with multiple ranks
+"K"         # Single piece on 1x1 board
+"3"         # Three empty squares
+"Kqr"       # Three pieces: K, q, r
+"K2r"       # K, two empty squares, then r
+"Kqr/3/R2k" # 3x3 board with multiple ranks
+"+K-r/N'"   # Board with piece modifiers
 ```
 
-### Part 2: Captured Pieces (Pieces in Hand)
+### Part 2: Pieces in Hand
 
-Shows pieces that have been captured and can potentially be used again:
+Shows pieces that have been captured and are available for future placement:
 
 - Format: `UPPERCASE_PIECES/lowercase_pieces`
 - **Always separated by `/`** even if empty
-- Count notation: `3P` means three `P` pieces
-- **Base form only**: No special modifiers allowed here
+- **Base form only**: No modifiers allowed (captured pieces revert to base type)
+- Count notation: `3P` means three `P` pieces (never `1P` for single pieces)
+- **Canonical sorting**: By quantity (descending), then alphabetical
 
 **Examples:**
 
 ```ruby
-"/"          # No pieces captured
-"P/"         # First player has one P piece
-"/p"         # Second player has one p piece
-"2PK/3p"     # First player: 2 P's + 1 K, Second player: 3 p's
+"/"         # No pieces captured
+"P/"        # First player has one P piece
+"/p"        # Second player has one p piece
+"2PK/3p"    # First player: 2 P's + 1 K, Second player: 3 p's
+"3P2RK/2pb" # Sorted by quantity, then alphabetical
 ```
 
-### Part 3: Turn Information
+**Critical: Canonical Piece Sorting Algorithm**
 
-Shows whose turn it is and identifies the game types:
+Captured pieces are automatically sorted according to the FEEN specification:
+
+1. **By player**: Uppercase pieces first, then lowercase pieces (separated by `/`)
+2. **By quantity** (descending): Most frequent pieces first
+3. **By base letter** (ascending): Alphabetical within same quantity
+4. **By prefix** (specific order): For same base letter and quantity: `-`, `+`, then no prefix
+5. **By suffix** (specific order): For same prefix: no suffix, then `'`
+
+**Detailed sorting example:**
+
+```ruby
+# Input pieces: PP+P'PPP+P'KS'S-PB+B+B+P'BBBPPPSP-P-P'-PRB
+# Step 1 - Group by base letter and modifiers:
+# B: +B+B+BBBBB = 2+B + 5B
+# K: K = K
+# P: -P-P-P-P' + +P'+P'+P' + PPPPPPPPP = 3-P + -P' + 3+P' + 9P
+# R: R = R
+# S: SS + S' = 2S + S'
+
+# Step 2 - Sort by quantity (desc), then letter (asc), then prefix/suffix:
+# Result: "2+B5BK3-P-P'3+P'9PR2SS'"
+
+# Canonical form: "2+B5BK3-P-P'3+P'9PR2SS'/"
+```
+
+### Part 3: Style Turn
+
+Identifies the style type associated with each player and whose turn it is:
 
 - Format: `ACTIVE_PLAYER/INACTIVE_PLAYER`
-- **One must be uppercase, other lowercase**
-- The uppercase/lowercase corresponds to piece ownership
+- **One must be uppercase, other lowercase** (semantically significant casing)
+- The uppercase name identifies the style system for uppercase pieces
+- The lowercase name identifies the style system for lowercase pieces
+- First name refers to the player to move
 
 **Examples:**
 
 ```ruby
-"CHESS/chess"    # CHESS player (uppercase pieces) to move
-"shogi/SHOGI"    # shogi player (lowercase pieces) to move
-"GAME1/game2"    # Mixed game types
+"CHESS/chess" # CHESS player (uppercase pieces) to move
+"shogi/SHOGI" # shogi player (lowercase pieces) to move
+"CHESS/makruk" # Cross-style: CHESS vs makruk, CHESS to move
 ```
 
 ## Complete API Reference
@@ -138,24 +175,24 @@ Converts position components into a FEEN string.
 
 **Parameters:**
 - `piece_placement:` [Array] - Nested array representing the board
-- `pieces_in_hand:` [Array] - List of captured pieces (strings)
-- `games_turn:` [Array] - Two-element array: [active_player, inactive_player]
+- `pieces_in_hand:` [Array] - List of captured pieces (strings, base form only)
+- `style_turn:` [Array] - Two-element array: [active_player, inactive_player]
 
-**Returns:** String - FEEN notation
+**Returns:** String - Canonical FEEN notation
 
 **Example:**
 
 ```ruby
 board = [
-  ["r", "n", "k", "n", "r"],   # Back rank
-  ["", "", "", "", ""],        # Empty rank
-  ["P", "P", "P", "P", "P"]    # Front rank
+  ["r", "n", "k", "n", "r"],  # Back rank
+  ["", "", "", "", ""],       # Empty rank
+  ["P", "P", "P", "P", "P"]   # Front rank
 ]
 
 feen = Feen.dump(
   piece_placement: board,
   pieces_in_hand:  ["Q", "p"],
-  games_turn:      ["WHITE", "black"]
+  style_turn:      ["WHITE", "black"]
 )
 # => "rnknr/5/PPPPP Q/p WHITE/black"
 ```
@@ -172,7 +209,7 @@ Converts a FEEN string back into position components.
 
 - `:piece_placement` - The board as nested arrays
 - `:pieces_in_hand` - Captured pieces as array of strings
-- `:games_turn` - [active_player, inactive_player]
+- `:style_turn` - [active_player, inactive_player]
 
 **Example:**
 
@@ -185,7 +222,7 @@ position[:piece_placement]
 position[:pieces_in_hand]
 # => ["Q", "p"]
 
-position[:games_turn]
+position[:style_turn]
 # => ["WHITE", "black"]
 ```
 
@@ -198,7 +235,7 @@ Like `parse()` but returns `nil` instead of raising exceptions for invalid input
 ```ruby
 # Valid input
 result = Feen.safe_parse("k/K / GAME/game")
-# => { piece_placement: [["k"], ["K"]], pieces_in_hand: [], games_turn: ["GAME", "game"] }
+# => { piece_placement: [["k"], ["K"]], pieces_in_hand: [], style_turn: ["GAME", "game"] }
 
 # Invalid input
 result = Feen.safe_parse("invalid")
@@ -214,9 +251,9 @@ Checks if a string is valid, canonical FEEN notation.
 **Example:**
 
 ```ruby
-Feen.valid?("k/K / GAME/game")        # => true
-Feen.valid?("invalid")                # => false
-Feen.valid?("k/K P3K/ GAME/game")     # => false (wrong piece order)
+Feen.valid?("k/K / GAME/game")    # => true
+Feen.valid?("invalid")            # => false
+Feen.valid?("k/K 3PK/ GAME/game") # => false (wrong piece order)
 ```
 
 ## Working with Different Board Sizes
@@ -235,7 +272,7 @@ board[8][8] = "R"  # Bottom-right
 feen = Feen.dump(
   piece_placement: board,
   pieces_in_hand:  [],
-  games_turn:      ["PLAYERA", "playerb"]
+  style_turn:      ["PLAYERA", "playerb"]
 )
 
 feen # => "r8/9/9/9/9/9/9/9/8R / PLAYERA/playerb"
@@ -253,7 +290,7 @@ board_3d = [
 feen = Feen.dump(
   piece_placement: board_3d,
   pieces_in_hand:  [],
-  games_turn:      ["UP", "down"]
+  style_turn:      ["UP", "down"]
 )
 # => "ab/cd//AB/CD / UP/down"
 ```
@@ -271,7 +308,7 @@ irregular_board = [
 feen = Feen.dump(
   piece_placement: irregular_board,
   pieces_in_hand:  [],
-  games_turn:      ["GAME", "game"]
+  style_turn:      ["GAME", "game"]
 )
 # => "rkr/pp/PPPP / GAME/game"
 ```
@@ -288,59 +325,87 @@ captured = ["P", "P", "P", "R", "p", "p"]
 feen = Feen.dump(
   piece_placement: [["k"], ["K"]],  # Minimal board
   pieces_in_hand:  captured,
-  games_turn:      ["FIRST", "second"]
+  style_turn:      ["FIRST", "second"]
 )
 # => "k/K 3PR/2p FIRST/second"
 ```
 
-### Understanding Piece Sorting
+### Understanding Canonical Piece Sorting
+
+Captured pieces are automatically sorted in canonical order according to the FEEN specification:
 
-Captured pieces are automatically sorted in canonical order:
+1. **By player**: Uppercase pieces first, then lowercase pieces (separated by `/`)
+2. **By quantity** (descending): Most frequent pieces first
+3. **By base letter** (ascending): Alphabetical within same quantity
+4. **By prefix** (specific order): For same base letter and quantity: `-`, `+`, then no prefix
+5. **By suffix** (specific order): For same prefix: no suffix, then `'`
 
-1. **By quantity** (most frequent first)
-2. **By letter** (alphabetical within same quantity)
+**Complex sorting example:**
 
 ```ruby
-pieces = ["B", "B", "P", "P", "P", "R", "R"]
-# Result: "3P2B2R/" (3P first, then 2B and 2R alphabetically)
+# Mixed pieces with modifiers
+pieces = ["-B", "+B", "+B", "B", "B", "B", "B", "B", "K", "-P", "-P", "-P", "-P'", "+P'", "+P'", "+P'", "P", "P", "P", "P", "P", "P", "P", "P", "P", "R", "S", "S", "S'", "b", "p"]
+
+# After canonical sorting: "2+B5BK3-P-P'3+P'9PR2SS'/bp"
+# Breakdown:
+# - Uppercase: 2+B (2 enhanced B), 5B (5 regular B), K (1 King), 3-P (3 diminished P), -P' (1 diminished P with intermediate state), 3+P' (3 enhanced P with intermediate state), 9P (9 regular P), R (1 Rook), 2S (2 regular S), S' (1 S with intermediate state)
+# - Lowercase: b (1 bishop), p (1 pawn)
 ```
 
 ## Advanced Features
 
-### Special Piece States (On Board Only)
+### Special Piece States (Board Only)
 
-For games that need special piece states, use modifiers **only on the board**:
+For games that need special piece states, use PNN modifiers **only on the board**:
 
 ```ruby
 board = [
-  ["+P", "K", "-R"],    # Enhanced pawn, King, diminished rook
-  ["N'", "", "B"]       # Knight with special state, empty, Bishop
+  ["+P", "K", "-R"],  # Enhanced pawn, King, diminished rook
+  ["N'", "", "B"]     # Knight with intermediate state, empty, Bishop
 ]
 
-# Note: Modifiers (+, -, ') are ONLY allowed on the board
-# Pieces in hand must be in base form only
+# Note: Modifiers are allowed on the board
+# Pieces in hand may or may not have modifiers depending on game rules
 feen = Feen.dump(
   piece_placement: board,
-  pieces_in_hand:  ["P", "R"],  # Base form only!
-  games_turn:      ["GAME", "game"]
+  pieces_in_hand:  ["P", "+R'"],  # Modifiers allowed in hand per FEEN spec
+  style_turn:      ["GAME", "game"]
 )
 
-feen # => "+PK-R/N'1B PR/ GAME/game"
+feen # => "+PK-R/N'1B P+R'/ GAME/game"
 ```
 
-### Cross-Game Scenarios
+### Cross-Style Scenarios
 
 FEEN can represent positions mixing different game systems:
 
 ```ruby
-# FOO pieces vs bar pieces
-mixed_feen = Feen.dump(
-  piece_placement: ["K", "G", "k", "r"],    # Mixed piece types
-  pieces_in_hand:  ["P", "g"],              # Captured from both sides
-  games_turn:      ["bar", "FOO"]           # Different game systems
+# CHESS pieces vs makruk pieces
+cross_style_feen = Feen.dump(
+  piece_placement: [["K", "Q", "k", "m"]],  # Mixed piece types
+  pieces_in_hand:  ["P", "s"],              # Captured from both sides
+  style_turn:      ["CHESS", "makruk"]      # Different game systems
 )
 
-mixed_feen # => "KGkr P/g bar/FOO"
+cross_style_feen # => "KQkm P/s CHESS/makruk"
+```
+
+### Dynamic Piece Ownership
+
+FEEN supports piece ownership changes through capture and redeployment:
+
+```ruby
+# A piece's current owner is determined by its case
+# Regardless of its original style system
+board = [["r", "K"]]  # lowercase 'r' owned by second player
+                      # uppercase 'K' owned by first player
+
+feen = Feen.dump(
+  piece_placement: board,
+  pieces_in_hand:  [],
+  style_turn:      ["CHESS", "shogi"]  # Cross-style game
+)
+# => "rK / CHESS/shogi"
 ```
 
 ## Error Handling
@@ -350,25 +415,33 @@ mixed_feen # => "KGkr P/g bar/FOO"
 ```ruby
 # ERROR: Wrong argument types
 Feen.dump(
-  piece_placement: "not an array",    # Must be Array
-  pieces_in_hand:  "not an array",   # Must be Array
-  games_turn:      "not an array"    # Must be Array[2]
+  piece_placement: "not an array",  # Must be Array
+  pieces_in_hand:  "not an array",  # Must be Array
+  style_turn:      "not an array"   # Must be Array[2]
 )
 # => ArgumentError
 
-# ERROR: Modifiers in captured pieces
+# ERROR: Invalid pieces in captured pieces (if validation enabled)
+Feen.dump(
+  piece_placement: [["K"]],
+  pieces_in_hand:  ["invalid_piece"], # Must follow PNN specification
+  style_turn:      ["GAME", "game"]
+)
+# => ArgumentError (if validation enabled)
+
+# ERROR: Same case in style_turn
 Feen.dump(
   piece_placement: [["K"]],
-  pieces_in_hand:  ["+P"],           # Invalid: no modifiers allowed
-  games_turn:      ["GAME", "game"]
+  pieces_in_hand:  [],
+  style_turn:      ["GAME", "ALSO"] # Must be different cases
 )
 # => ArgumentError
 
-# ERROR: Same case in games_turn
+# ERROR: Invalid style identifiers
 Feen.dump(
   piece_placement: [["K"]],
   pieces_in_hand:  [],
-  games_turn:      ["GAME", "ALSO"]  # Must be different cases
+  style_turn:      ["game-1", "game2"] # Must follow SNN specification
 )
 # => ArgumentError
 ```
@@ -390,6 +463,69 @@ end
 
 ## Real-World Examples
 
+### International Chess Starting Position
+
+```ruby
+chess_start = Feen.dump(
+  piece_placement: [
+    ["r", "n", "b", "q", "k", "b", "n", "r"],
+    ["p", "p", "p", "p", "p", "p", "p", "p"],
+    ["", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", ""],
+    ["P", "P", "P", "P", "P", "P", "P", "P"],
+    ["R", "N", "B", "Q", "K", "B", "N", "R"]
+  ],
+  pieces_in_hand: [],
+  style_turn: ["CHESS", "chess"]
+)
+# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
+```
+
+### Japanese Shōgi Starting Position
+
+```ruby
+shogi_start = Feen.dump(
+  piece_placement: [
+    ["l", "n", "s", "g", "k", "g", "s", "n", "l"],
+    ["", "r", "", "", "", "", "", "b", ""],
+    ["p", "p", "p", "p", "p", "p", "p", "p", "p"],
+    ["", "", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", "", ""],
+    ["P", "P", "P", "P", "P", "P", "P", "P", "P"],
+    ["", "B", "", "", "", "", "", "R", ""],
+    ["L", "N", "S", "G", "K", "G", "S", "N", "L"]
+  ],
+  pieces_in_hand: [],
+  style_turn: ["SHOGI", "shogi"]
+)
+# => "lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL / SHOGI/shogi"
+```
+
+### Shōgi Position with Captured Pieces
+
+```ruby
+# Game in progress with captured pieces
+shogi_midgame = Feen.dump(
+  piece_placement: [
+    ["l", "n", "s", "g", "k", "g", "s", "n", "l"],
+    ["", "r", "", "", "", "", "", "", ""],
+    ["p", "p", "p", "p", "p", "p", "p", "p", "p"],
+    ["", "", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", "", ""],
+    ["", "", "", "", "", "", "", "", ""],
+    ["P", "P", "P", "P", "P", "P", "P", "P", "P"],
+    ["", "B", "", "", "", "", "", "R", ""],
+    ["L", "N", "S", "G", "K", "G", "S", "N", "L"]
+  ],
+  pieces_in_hand: ["B", "P", "P", "b", "p"],  # Captured pieces
+  style_turn: ["SHOGI", "shogi"]
+)
+# => "lnsgkgsnl/1r7/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL 2PB/bp SHOGI/shogi"
+```
+
 ### Save/Load Game State
 
 ```ruby
@@ -398,7 +534,7 @@ class GameState
     feen = Feen.dump(
       piece_placement: board,
       pieces_in_hand:  captured,
-      games_turn:      [current_player, opponent]
+      style_turn:      [current_player, opponent]
     )
 
     File.write("game_save.feen", feen)
@@ -426,7 +562,7 @@ class PositionDatabase
     feen = Feen.dump(
       piece_placement: board,
       pieces_in_hand:  captured,
-      games_turn:      turn_info
+      style_turn:      turn_info
     )
 
     @positions[name] = feen
@@ -450,7 +586,7 @@ end
 db = PositionDatabase.new
 db.store_position("start", [["r", "k", "r"]], [], ["GAME", "game"])
 position = db.retrieve_position("start")
-# => {piece_placement: [["r", "k", "r"]], pieces_in_hand: [], games_turn: ["GAME", "game"]}
+# => { piece_placement: [["r", "k", "r"]], pieces_in_hand: [], style_turn: ["GAME", "game"] }
 ```
 
 ## Best Practices
@@ -467,7 +603,7 @@ def create_feen_safely(board, captured, turn)
   Feen.dump(
     piece_placement: board,
     pieces_in_hand:  captured,
-    games_turn:      turn
+    style_turn:      turn
   )
 rescue ArgumentError => e
   puts "FEEN creation failed: #{e.message}"
@@ -475,27 +611,44 @@ rescue ArgumentError => e
 end
 ```
 
-### 2. Use Consistent Naming
+### 2. Use Consistent Style Naming
 
 ```ruby
-# Good: Clear piece type distinctions
-PLAYER_1_PIECES = %w[K Q R B N P]
-PLAYER_2_PIECES = %w[k q r b n p]
-
-# Good: Descriptive game identifiers
-GAME_TYPES = {
+# Good: Follow SNN specification conventions
+STYLE_IDENTIFIERS = {
   chess_white: "CHESS",
   chess_black: "chess",
   shogi_sente: "SHOGI",
-  shogi_gote: "shogi"
+  shogi_gote: "shogi",
+  xiangqi_red: "XIANGQI",
+  xiangqi_black: "xiangqi"
 }
+
+# Good: Clear piece type distinctions following PNN
+CHESS_PIECES = %w[K Q R B N P]  # Uppercase for first player
+CHESS_PIECES_LOWER = %w[k q r b n p]  # Lowercase for second player
+```
+
+### 3. Handle Cross-Style Scenarios Carefully
+
+```ruby
+def validate_cross_style_position(feen_string)
+  position = Feen.parse(feen_string)
+  styles = position[:style_turn]
+
+  # Check if it's a cross-style game
+  if styles[0].downcase != styles[1].downcase
+    puts "Cross-style game detected: #{styles[0]} vs #{styles[1]}"
+    # Consider piece identity ambiguity implications
+  end
+end
 ```
 
-### 3. Round-trip Validation
+### 4. Round-trip Validation
 
 ```ruby
 def verify_feen_consistency(original_feen)
-  # Parse and re-dump to check consistency
+  # Parse and re-dump to check canonical format
   position = Feen.parse(original_feen)
   regenerated = Feen.dump(**position)
 
@@ -509,17 +662,52 @@ def verify_feen_consistency(original_feen)
 end
 ```
 
+## FEEN Specification Compliance
+
+This library implements **FEEN v1.0.0** specification with the following features:
+
+### Core Properties ✓
+- Rule-agnostic representation
+- Canonical format enforcement
+- Cross-style/hybrid position support
+- Multi-dimensional board support
+- Two-player limitation (exactly)
+- 26-piece limit per player (a-z, A-Z)
+
+### Field Support ✓
+- **Piece Placement**: Full PNN notation with modifiers on board
+- **Pieces in Hand**: Full PNN notation with modifiers (as per specification), canonical sorting
+- **Style Turn**: SNN-compliant identifiers with semantic casing
+
+### Advanced Features ✓
+- Dynamic piece ownership through capture
+- Irregular board shapes
+- 3D and higher-dimensional boards
+- Empty space compression
+- Proper dimension separators (`/`, `//`, `///`)
+- **Strict canonical piece sorting** per FEEN specification
+
+### Canonical Sorting Implementation ✓
+The library implements the exact sorting algorithm specified in FEEN v1.0.0:
+1. Player separation (uppercase/lowercase)
+2. Quantity (descending)
+3. Base letter (ascending)
+4. Prefix order: `-`, `+`, no prefix
+5. Suffix order: no suffix, `'`
+
 ## Compatibility and Performance
 
 - **Ruby Version**: >= 3.2.0
 - **Thread Safety**: All operations are thread-safe
 - **Memory**: Efficient array-based representation
 - **Performance**: O(n) parsing and generation complexity
+- **Format**: Full compliance with FEEN v1.0.0 specification
 
 ## Related Resources
 
 - [FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/) - Complete format specification
 - [PNN Specification v1.0.0](https://sashite.dev/documents/pnn/1.0.0/) - Piece notation details
+- [SNN Specification v1.0.0](https://sashite.dev/documents/snn/1.0.0/) - Style name notation
 - [GAN Specification v1.0.0](https://sashite.dev/documents/gan/1.0.0/) - Game-qualified identifiers
 
 ## Contributing