sashite-pnn 2.0.0 → 3.1.0

data/README.md

@@ -9,512 +9,259 @@
 
 ## What is PNN?
 
-PNN (Piece Name Notation) extends [PIN (Piece Identifier Notation)](https://sashite.dev/specs/pin/1.0.0/) to provide style-aware piece representation in abstract strategy board games. PNN adds a derivation marker that distinguishes pieces by their style origin, enabling cross-style game scenarios and piece origin tracking.
+PNN (Piece Name Notation) is a formal, rule-agnostic naming system for identifying **pieces** in abstract strategy board games such as chess, shōgi, xiangqi, and their many variants. Each piece is represented by a canonical, human-readable ASCII name with optional state modifiers and optional terminal markers (e.g., `"KING"`, `"queen"`, `"+ROOK"`, `"-pawn"`, `"KING^"`).
 
-This gem implements the [PNN Specification v1.0.0](https://sashite.dev/specs/pnn/1.0.0/), providing a modern Ruby interface with immutable piece objects and full backward compatibility with PIN while adding style differentiation capabilities.
+This gem implements the [PNN Specification v1.0.0](https://sashite.dev/specs/pnn/1.0.0/), supporting validation, parsing, and comparison of piece names with integrated state management and terminal piece identification.
 
 ## Installation
-
 ```ruby
 # In your Gemfile
 gem "sashite-pnn"
 ```
 
 Or install manually:
-
 ```sh
 gem install sashite-pnn
 ```
 
 ## Usage
 
+### Basic Operations
 ```ruby
 require "sashite/pnn"
 
-# Parse PNN strings into piece objects
-piece = Sashite::Pnn.parse("K")          # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-piece.to_s                               # => "K"
-piece.type                               # => :K
-piece.side                               # => :first
-piece.state                              # => :normal
-piece.native?                            # => true
+# Parse PNN strings into piece name objects
+name = Sashite::Pnn.parse("KING")             # => #<Pnn::Name value="KING">
+name.to_s                                     # => "KING"
+name.value                                    # => "KING"
 
-# Create pieces directly
-piece = Sashite::Pnn.piece(:K, :first) # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-piece = Sashite::Pnn::Piece.new(:R, :second, :enhanced, false) # => #<Pnn::Piece type=:R side=:second state=:enhanced native=false>
+# Create from string or symbol
+name = Sashite::Pnn.name("queen")             # => #<Pnn::Name value="queen">
+name = Sashite::Pnn::Name.new(:ROOK)          # => #<Pnn::Name value="ROOK">
 
 # Validate PNN strings
-Sashite::Pnn.valid?("K")                 # => true
-Sashite::Pnn.valid?("+R'")               # => true
-Sashite::Pnn.valid?("invalid")           # => false
-
-# Style derivation with apostrophe suffix
-native_king = Sashite::Pnn.parse("K")    # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-foreign_king = Sashite::Pnn.parse("K'")  # => #<Pnn::Piece type=:K side=:first state=:normal native=false>
-
-native_king.to_s                         # => "K"
-foreign_king.to_s                        # => "K'"
-
-# State manipulation (returns new immutable instances)
-enhanced = piece.enhance                 # => #<Pnn::Piece type=:K side=:first state=:enhanced native=true>
-enhanced.to_s                            # => "+K"
-diminished = piece.diminish              # => #<Pnn::Piece type=:K side=:first state=:diminished native=true>
-diminished.to_s                          # => "-K"
-
-# Style derivation manipulation
-foreign_piece = piece.derive             # => #<Pnn::Piece type=:K side=:first state=:normal native=false>
-foreign_piece.to_s                       # => "K'"
-back_to_native = foreign_piece.underive  # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-back_to_native.to_s                      # => "K"
-
-# Side manipulation
-flipped = piece.flip                     # => #<Pnn::Piece type=:K side=:second state=:normal native=true>
-flipped.to_s                             # => "k"
-
-# Type manipulation
-queen = piece.with_type(:Q)              # => #<Pnn::Piece type=:Q side=:first state=:normal native=true>
-queen.to_s                               # => "Q"
-
-# Style queries
-piece.native?                            # => true
-foreign_king.derived?                    # => true
-
-# State queries
-piece.normal?                            # => true
-enhanced.enhanced?                       # => true
-diminished.diminished?                   # => true
-
-# Side queries
-piece.first_player?                      # => true
-flipped.second_player?                   # => true
-
-# Attribute access
-piece.letter                             # => "K"
-enhanced.prefix                          # => "+"
-foreign_king.suffix                      # => "'"
-piece.suffix                             # => ""
-
-# Type and side comparison
-king1 = Sashite::Pnn.parse("K")
-king2 = Sashite::Pnn.parse("k")
-queen = Sashite::Pnn.parse("Q")
-
-king1.same_type?(king2)                  # => true (both kings)
-king1.same_side?(queen)                  # => true (both first player)
-king1.same_type?(queen)                  # => false (different types)
-
-# Style comparison
-native_king = Sashite::Pnn.parse("K")
-foreign_king = Sashite::Pnn.parse("K'")
-
-native_king.same_style?(foreign_king) # => false (different derivation)
-
-# Functional transformations can be chained
-pawn = Sashite::Pnn.parse("P")
-enemy_foreign_promoted = pawn.flip.derive.enhance # => "+p'" (second player foreign promoted pawn)
+Sashite::Pnn.valid?("BISHOP")                 # => true
+Sashite::Pnn.valid?("King")                   # => false (mixed case not allowed)
+Sashite::Pnn.valid?("+ROOK")                  # => true (enhanced state)
+Sashite::Pnn.valid?("-pawn")                  # => true (diminished state)
+Sashite::Pnn.valid?("KING^")                  # => true (terminal piece)
+Sashite::Pnn.valid?("+KING^")                 # => true (enhanced terminal piece)
 ```
 
-## Format Specification
-
-### Structure
-```
-<pin>[<suffix>]
-```
-
-### Components
-
-- **PIN part** (`[<state>]<letter>`): Standard PIN notation
-  - **Letter** (`A-Z`, `a-z`): Represents piece type and side
-    - Uppercase: First player pieces
-    - Lowercase: Second player pieces
-  - **State** (optional prefix):
-    - `+`: Enhanced state (promoted, upgraded, empowered)
-    - `-`: Diminished state (weakened, restricted, temporary)
-    - No prefix: Normal state
-
-- **Derivation suffix** (optional):
-  - `'`: Foreign style (piece has opposite side's native style)
-  - No suffix: Native style (piece has current side's native style)
-
-### Regular Expression
+### State Modifiers
 ```ruby
-/\A[-+]?[A-Za-z]'?\z/
+# Enhanced pieces (+ prefix)
+enhanced = Sashite::Pnn.parse("+QUEEN")
+enhanced.enhanced?                            # => true
+enhanced.normal?                              # => false
+enhanced.base_name                            # => "QUEEN"
+
+# Diminished pieces (- prefix)
+diminished = Sashite::Pnn.parse("-pawn")
+diminished.diminished?                        # => true
+diminished.base_name                          # => "pawn"
+
+# Normal pieces (no prefix)
+normal = Sashite::Pnn.parse("KNIGHT")
+normal.normal?                                # => true
+normal.enhanced?                              # => false
+normal.diminished?                            # => false
 ```
 
-### Examples
-- `K` - First player king (native style, normal state)
-- `k'` - Second player king (foreign style, normal state)
-- `+R'` - First player rook (foreign style, enhanced state)
-- `-p` - Second player pawn (native style, diminished state)
-
-## Game Examples
-
-### Cross-Style Chess vs. Shōgi
-
+### Terminal Markers
 ```ruby
-# Match setup: First player uses Chess, Second player uses Shōgi
-# Native styles: first=Chess, second=Shōgi
-
-# Native pieces (no derivation suffix)
-white_king = Sashite::Pnn.piece(:K, :first)          # => "K" (Chess king)
-black_king = Sashite::Pnn.piece(:K, :second)         # => "k" (Shōgi king)
-
-# Foreign pieces (with derivation suffix)
-white_shogi_king = Sashite::Pnn.piece(:K, :first, :normal, false)   # => "K'" (Shōgi king for white)
-black_chess_king = Sashite::Pnn.piece(:K, :second, :normal, false)  # => "k'" (Chess king for black)
-
-# Promoted pieces in cross-style context
-white_promoted_rook = Sashite::Pnn.parse("+R'")  # White shōgi rook promoted to Dragon King
-black_promoted_pawn = Sashite::Pnn.parse("+p")   # Black shōgi pawn promoted to Tokin
-
-white_promoted_rook.enhanced?                     # => true
-white_promoted_rook.derived?                      # => true
-black_promoted_pawn.enhanced?                     # => true
-black_promoted_pawn.native?                       # => true
+# Terminal pieces (^ suffix)
+terminal = Sashite::Pnn.parse("KING^")
+terminal.terminal?                            # => true
+terminal.base_name                            # => "KING"
+
+# Non-terminal pieces (no suffix)
+non_terminal = Sashite::Pnn.parse("PAWN")
+non_terminal.terminal? # => false
+
+# Combined state and terminal marker
+enhanced_terminal = Sashite::Pnn.parse("+ROOK^")
+enhanced_terminal.enhanced?                   # => true
+enhanced_terminal.terminal?                   # => true
+enhanced_terminal.base_name                   # => "ROOK"
+
+diminished_terminal = Sashite::Pnn.parse("-king^")
+diminished_terminal.diminished?               # => true
+diminished_terminal.terminal?                 # => true
+diminished_terminal.base_name                 # => "king"
 ```
 
-### Single-Style Games (PIN Compatibility)
-
+### Player Assignment
 ```ruby
-# Traditional Chess (both players use Chess style)
-# All pieces are native, so PNN behaves exactly like PIN
-
-white_pieces = %w[K Q +R B N P].map { |pin| Sashite::Pnn.parse(pin) }
-black_pieces = %w[k q +r b n p].map { |pin| Sashite::Pnn.parse(pin) }
-
-white_pieces.all?(&:native?)                     # => true
-black_pieces.all?(&:native?)                     # => true
-
-# PNN strings match PIN strings for native pieces
-white_pieces.map(&:to_s)                         # => ["K", "Q", "+R", "B", "N", "P"]
-black_pieces.map(&:to_s)                         # => ["k", "q", "+r", "b", "n", "p"]
+# First player pieces (uppercase)
+first_player = Sashite::Pnn.parse("KING")
+first_player.first_player?                    # => true
+first_player.second_player?                   # => false
+
+first_player_terminal = Sashite::Pnn.parse("KING^")
+first_player_terminal.first_player?           # => true
+first_player_terminal.terminal?               # => true
+
+# Second player pieces (lowercase)
+second_player = Sashite::Pnn.parse("king")
+second_player.first_player?                   # => false
+second_player.second_player?                  # => true
+
+second_player_terminal = Sashite::Pnn.parse("king^")
+second_player_terminal.second_player?         # => true
+second_player_terminal.terminal?              # => true
 ```
 
-### Style Mutation During Gameplay
-
+### Normalization and Comparison
 ```ruby
-# Simulate capture with style change (Ōgi rules)
-chess_queen = Sashite::Pnn.parse("q'") # Black chess queen (foreign for shōgi player)
-captured = chess_queen.flip.with_type(:P).underive # Becomes white native pawn
-
-chess_queen.to_s                                 # => "q'" (black foreign queen)
-captured.to_s                                    # => "P" (white native pawn)
-
-# Style derivation changes during gameplay
-shogi_piece = Sashite::Pnn.parse("r")           # Black shōgi rook (native)
-foreign_piece = shogi_piece.derive              # Convert to foreign style
-foreign_piece.to_s                              # => "r'" (black foreign rook)
+a = Sashite::Pnn.parse("ROOK")
+b = Sashite::Pnn.parse("ROOK")
+
+a == b                                        # => true
+a.same_base_name?(Sashite::Pnn.parse("rook")) # => true (same piece, different player)
+a.same_base_name?(Sashite::Pnn.parse("ROOK^")) # => true (same piece, terminal marker)
+a.same_base_name?(Sashite::Pnn.parse("+rook")) # => true (same piece, different state)
+a.to_s # => "ROOK"
 ```
 
-## API Reference
-
-### Main Module Methods
-
-- `Sashite::Pnn.valid?(pnn_string)` - Check if string is valid PNN notation
-- `Sashite::Pnn.parse(pnn_string)` - Parse PNN string into Piece object
-- `Sashite::Pnn.piece(type, side, state = :normal, native = true)` - Create piece instance directly
-
-### Piece Class
-
-#### Creation and Parsing
-- `Sashite::Pnn::Piece.new(type, side, state = :normal, native = true)` - Create piece instance
-- `Sashite::Pnn::Piece.parse(pnn_string)` - Parse PNN string (same as module method)
-- `Sashite::Pnn::Piece.valid?(pnn_string)` - Validate PNN string (class method)
-
-#### Attribute Access
-- `#type` - Get piece type (symbol :A to :Z, always uppercase)
-- `#side` - Get player side (:first or :second)
-- `#state` - Get state (:normal, :enhanced, or :diminished)
-- `#native` - Get style derivation (true for native, false for foreign)
-- `#letter` - Get letter representation (string, case determined by side)
-- `#prefix` - Get state prefix (string: "+", "-", or "")
-- `#suffix` - Get derivation suffix (string: "'" or "")
-- `#to_s` - Convert to PNN string representation
-
-#### Style Queries
-- `#native?` - Check if native style (current side's native style)
-- `#derived?` - Check if foreign style (opposite side's native style)
-- `#foreign?` - Alias for `#derived?`
-
-#### State Queries
-- `#normal?` - Check if normal state (no modifiers)
-- `#enhanced?` - Check if enhanced state
-- `#diminished?` - Check if diminished state
-
-#### Side Queries
-- `#first_player?` - Check if first player piece
-- `#second_player?` - Check if second player piece
-
-#### State Transformations (immutable - return new instances)
-- `#enhance` - Create enhanced version
-- `#unenhance` - Remove enhanced state
-- `#diminish` - Create diminished version
-- `#undiminish` - Remove diminished state
-- `#normalize` - Remove all state modifiers
-
-#### Style Transformations (immutable - return new instances)
-- `#derive` - Convert to foreign style (add derivation suffix)
-- `#underive` - Convert to native style (remove derivation suffix)
-- `#flip` - Switch player (change side)
-
-#### Attribute Transformations (immutable - return new instances)
-- `#with_type(new_type)` - Create piece with different type
-- `#with_side(new_side)` - Create piece with different side
-- `#with_state(new_state)` - Create piece with different state
-- `#with_derivation(native)` - Create piece with different derivation
-
-#### Comparison Methods
-- `#same_type?(other)` - Check if same piece type
-- `#same_side?(other)` - Check if same side
-- `#same_state?(other)` - Check if same state
-- `#same_style?(other)` - Check if same style derivation
-- `#==(other)` - Full equality comparison
-
-### Constants
-- `Sashite::Pnn::Piece::NATIVE` - Constant for native style (`true`)
-- `Sashite::Pnn::Piece::FOREIGN` - Constant for foreign style (`false`)
-- `Sashite::Pnn::Piece::FOREIGN_SUFFIX` - Derivation suffix for foreign pieces (`"'"`)
-- `Sashite::Pnn::Piece::NATIVE_SUFFIX` - Derivation suffix for native pieces (`""`)
-
-**Note**: PNN validation leverages the existing `Sashite::Pin::Piece::PIN_PATTERN` for the PIN component, with additional logic for the optional derivation suffix.
-
-## Advanced Usage
-
-### Style Derivation Examples
-
+### Collections and Filtering
 ```ruby
-# Understanding native vs. foreign pieces
-# In a Chess vs. Shōgi match:
-# - First player native style: Chess
-# - Second player native style: Shōgi
-
-native_chess_king = Sashite::Pnn.parse("K")      # First player native (Chess king)
-foreign_shogi_king = Sashite::Pnn.parse("K'")    # First player foreign (Shōgi king)
-
-native_shogi_king = Sashite::Pnn.parse("k")      # Second player native (Shōgi king)
-foreign_chess_king = Sashite::Pnn.parse("k'")    # Second player foreign (Chess king)
-
-# Style queries
-native_chess_king.native?                        # => true
-foreign_shogi_king.derived?                      # => true
-native_shogi_king.native?                        # => true
-foreign_chess_king.derived?                      # => true
-```
+pieces = %w[KING^ queen +ROOK -pawn BISHOP knight^ GENERAL^].map { |n| Sashite::Pnn.parse(n) }
 
-### Immutable Transformations
-```ruby
-# All transformations return new instances
-original = Sashite::Pnn.piece(:K, :first)
-enhanced = original.enhance
-derived = original.derive
-flipped = original.flip
-
-# Original piece is never modified
-puts original    # => "K"
-puts enhanced    # => "+K"
-puts derived     # => "K'"
-puts flipped     # => "k"
-
-# Transformations can be chained
-result = original.flip.derive.enhance.with_type(:Q)
-puts result # => "+q'"
-```
+# Filter by player
+first_player_pieces = pieces.select(&:first_player?).map(&:to_s)
+# => ["KING^", "+ROOK", "BISHOP", "GENERAL^"]
 
-### Cross-Style Game State Management
-```ruby
-class CrossStyleGameBoard
-  def initialize(first_style, second_style)
-    @first_style = first_style
-    @second_style = second_style
-    @pieces = {}
-  end
-
-  def place(square, piece)
-    @pieces[square] = piece
-  end
-
-  def capture_with_style_change(from_square, to_square, new_type = nil)
-    captured = @pieces[to_square]
-    capturing = @pieces.delete(from_square)
-
-    return nil unless captured && capturing
-
-    # Style mutation: captured piece becomes native to capturing side
-    mutated = captured.flip.underive
-    mutated = mutated.with_type(new_type) if new_type
-
-    @pieces[to_square] = capturing
-    mutated # Return mutated captured piece for hand
-  end
-
-  def pieces_by_style_derivation
-    {
-      native:  @pieces.select { |_, piece| piece.native? },
-      foreign: @pieces.select { |_, piece| piece.derived? }
-    }
-  end
-end
-
-# Usage
-board = CrossStyleGameBoard.new(:chess, :shogi)
-board.place("e1", Sashite::Pnn.piece(:K, :first))               # Chess king
-board.place("e8", Sashite::Pnn.piece(:K, :second))              # Shōgi king
-board.place("d4", Sashite::Pnn.piece(:Q, :first, :normal, false)) # Chess queen using Shōgi style
-
-analysis = board.pieces_by_style_derivation
-puts analysis[:native].size    # => 2
-puts analysis[:foreign].size   # => 1
-```
+# Filter by state
+enhanced_pieces = pieces.select(&:enhanced?).map(&:to_s)
+# => ["+ROOK"]
 
-### PIN Compatibility Layer
-```ruby
-# PNN is fully backward compatible with PIN
-def convert_pin_to_pnn(pin_string)
-  # All PIN strings are valid PNN strings (native pieces)
-  Sashite::Pnn.parse(pin_string)
-end
+diminished_pieces = pieces.select(&:diminished?).map(&:to_s)
+# => ["-pawn"]
 
-def convert_pnn_to_pin(pnn_piece)
-  # Only native PNN pieces can be converted to PIN
-  return nil unless pnn_piece.native?
+# Filter by terminal status
+terminal_pieces = pieces.select(&:terminal?).map(&:to_s)
+# => ["KING^", "knight^", "GENERAL^"]
 
-  "#{pnn_piece.prefix}#{pnn_piece.letter}"
-end
+# Combine filters
+first_player_terminals = pieces.select { |p| p.first_player? && p.terminal? }.map(&:to_s)
+# => ["KING^", "GENERAL^"]
+```
 
-# Usage
-pin_pieces = %w[K Q +R -P k q r p]
-pnn_pieces = pin_pieces.map { |pin| convert_pin_to_pnn(pin) }
+## Format Specification
 
-pnn_pieces.all?(&:native?)                    # => true
-pnn_pieces.map { |p| convert_pnn_to_pin(p) }  # => ["K", "Q", "+R", "-P", "k", "q", "r", "p"]
+### Structure
 ```
-
-### Move Validation Example
-```ruby
-def can_promote_in_style?(piece, target_rank, style_rules)
-  return false unless piece.normal? # Already promoted pieces can't promote again
-
-  case [piece.type, piece.native? ? style_rules[:native] : style_rules[:foreign]]
-  when %i[P chess]  # Chess pawn
-    (piece.first_player? && target_rank == 8) ||
-      (piece.second_player? && target_rank == 1)
-  when %i[P shogi]  # Shōgi pawn
-    (piece.first_player? && target_rank >= 7) ||
-      (piece.second_player? && target_rank <= 3)
-  when %i[R shogi], %i[B shogi] # Shōgi major pieces
-    true
-  else
-    false
-  end
-end
-
-# Usage
-chess_pawn = Sashite::Pnn.piece(:P, :first)
-shogi_pawn = Sashite::Pnn.piece(:P, :first, :normal, false)
-
-style_rules = { native: :chess, foreign: :shogi }
-
-puts can_promote_in_style?(chess_pawn, 8, style_rules)  # => true (chess pawn on 8th rank)
-puts can_promote_in_style?(shogi_pawn, 8, style_rules)  # => true (shogi pawn on 8th rank)
+[<state-modifier>]<piece-name>[<terminal-marker>]
 ```
 
-## Implementation Architecture
-
-This gem uses **composition over inheritance** by building upon the proven [sashite-pin](https://github.com/sashite/pin.rb) gem:
+Where:
+- `<state-modifier>` is optional `+` (enhanced) or `-` (diminished)
+- `<piece-name>` is case-consistent alphabetic characters
+- `<terminal-marker>` is optional `^` (terminal piece)
 
-- **PIN Foundation**: All type, side, and state logic is handled by an internal `Pin::Piece` object
-- **PNN Extension**: Only the derivation (`native`) attribute and related methods are added
-- **Delegation Pattern**: Core PIN methods are delegated to the internal PIN piece
-- **Immutability**: All transformations return new instances, maintaining functional programming principles
+### Grammar (BNF)
+```bnf
+<pnn> ::= <state-modifier> <name-body> <terminal-marker>
+       | <state-modifier> <name-body>
+       | <name-body> <terminal-marker>
+       | <name-body>
 
-This architecture ensures:
-- **Reliability**: Reuses battle-tested PIN logic
-- **Maintainability**: PIN updates automatically benefit PNN
-- **Consistency**: PIN and PNN pieces behave identically for shared attributes
-- **Performance**: Minimal overhead over pure PIN implementation
+<state-modifier> ::= "+" | "-"
 
-## Protocol Mapping
+<name-body> ::= <uppercase-name> | <lowercase-name>
 
-Following the [Game Protocol](https://sashite.dev/game-protocol/):
+<uppercase-name> ::= <uppercase-letter>+
+<lowercase-name> ::= <lowercase-letter>+
 
-| Protocol Attribute | PNN Encoding | Examples | Notes |
-|-------------------|--------------|----------|-------|
-| **Type** | ASCII letter choice | `K`/`k` = King, `P`/`p` = Pawn | Type is always stored as uppercase symbol (`:K`, `:P`) |
-| **Side** | Letter case in display | `K` = First player, `k` = Second player | Case is determined by side during rendering |
-| **State** | Optional prefix | `+K` = Enhanced, `-K` = Diminished, `K` = Normal | |
-| **Style** | Derivation suffix | `K` = Native style, `K'` = Foreign style | |
+<terminal-marker> ::= "^"
 
-**Style Derivation Logic**:
-- **No suffix**: Piece has the **native style** of its current side
-- **Apostrophe suffix (`'`)**: Piece has the **foreign style** (opposite side's native style)
-
-**Canonical principle**: Identical pieces must have identical PNN representations.
+<uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
+<lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
+```
 
-## Properties
+### Regular Expression
+```ruby
+/\A[+-]?([A-Z]+|[a-z]+)\^?\z/
+```
 
-* **PIN Compatible**: All valid PIN strings are valid PNN strings
-* **Style Aware**: Distinguishes pieces by their style origin through derivation markers
-* **ASCII Compatible**: Maximum portability across systems
-* **Rule-Agnostic**: Independent of specific game mechanics
-* **Compact Format**: Minimal character usage (1-3 characters per piece)
-* **Visual Distinction**: Clear player and style differentiation
-* **Protocol Compliant**: Complete implementation of Sashité piece attributes
-* **Immutable**: All piece instances are frozen and transformations return new objects
-* **Functional**: Pure functions with no side effects
+## Design Principles
 
-## Implementation Notes
+* **Human-readable**: Names like `"KING"` or `"queen"` are intuitive and descriptive.
+* **State-aware**: Integrated state management through `+` and `-` modifiers.
+* **Terminal-aware**: Explicit identification of terminal pieces through `^` marker.
+* **Rule-agnostic**: Independent of specific game mechanics.
+* **Case-consistent**: Visual distinction between players through case.
+* **Canonical**: One valid name per piece state within a given context.
+* **ASCII-only**: Compatible with all systems.
 
-### Style Derivation Convention
+## Integration with PIN
 
-PNN follows a strict style derivation convention:
+PNN names serve as the formal source for PIN character identifiers. For example:
 
-1. **Native pieces** (no suffix): Use the current side's native style
-2. **Foreign pieces** (`'` suffix): Use the opposite side's native style
-3. **Match context**: Each side has a defined native style for the entire match
-4. **Style mutations**: Pieces can change derivation through gameplay mechanics
+| PNN        | PIN      | Description |
+| ---------- | -------- | ----------- |
+| `KING`     | `K`      | First player king |
+| `king`     | `k`      | Second player king |
+| `KING^`    | `K^`     | Terminal first player king |
+| `king^`    | `k^`     | Terminal second player king |
+| `+ROOK`    | `+R`     | Enhanced first player rook |
+| `+ROOK^`   | `+R^`    | Enhanced terminal first player rook |
+| `-pawn`    | `-p`     | Diminished second player pawn |
+| `-pawn^`   | `-p^`    | Diminished terminal second player pawn |
 
-### Example Flow
+Multiple PNN names may map to the same PIN character (e.g., `"KING"` and `"KHAN"` both → `K`), but PNN provides unambiguous naming within broader contexts.
 
+## Examples
 ```ruby
-# Match context: First player=Chess, Second player=Shōgi
-# Input: "K'" (first player foreign)
-# ↓ Parsing
-# type: :K, side: :first, state: :normal, native: false
-# ↓ Style resolution
-# Effective style: Shōgi (second player's native style)
-# ↓ Display
-# PNN: "K'" (first player king with foreign/Shōgi style)
+# Traditional pieces
+Sashite::Pnn.parse("KING")        # => #<Pnn::Name value="KING">
+Sashite::Pnn.parse("queen")       # => #<Pnn::Name value="queen">
+
+# Terminal pieces
+Sashite::Pnn.parse("KING^")       # => #<Pnn::Name value="KING^">
+Sashite::Pnn.parse("general^")    # => #<Pnn::Name value="general^">
+
+# State modifiers
+Sashite::Pnn.parse("+ROOK")       # => #<Pnn::Name value="+ROOK">
+Sashite::Pnn.parse("-pawn")       # => #<Pnn::Name value="-pawn">
+
+# Combined modifiers
+Sashite::Pnn.parse("+KING^")      # => #<Pnn::Name value="+KING^">
+Sashite::Pnn.parse("-pawn^")      # => #<Pnn::Name value="-pawn^">
+
+# Validation
+Sashite::Pnn.valid?("BISHOP")     # => true
+Sashite::Pnn.valid?("KING^")      # => true
+Sashite::Pnn.valid?("+ROOK^")     # => true
+Sashite::Pnn.valid?("Bishop")     # => false (mixed case)
+Sashite::Pnn.valid?("KING1")      # => false (no digits allowed)
+Sashite::Pnn.valid?("^KING")      # => false (terminal marker must be suffix)
 ```
 
-This ensures that `parse(pnn).to_s == pnn` for all valid PNN strings while enabling cross-style gameplay.
-
-## System Constraints
-
-- **Maximum 26 piece types** per game system (one per ASCII letter)
-- **Exactly 2 players** (uppercase/lowercase distinction)
-- **3 state levels** (enhanced, normal, diminished)
-- **2 style derivations** (native, foreign)
-- **Style context dependency**: Requires match-level side-style associations
+## API Reference
 
-## Related Specifications
+### Main Module
 
-- [PIN](https://sashite.dev/specs/pin/1.0.0/) - Piece Identifier Notation (style-agnostic base)
-- [Game Protocol](https://sashite.dev/game-protocol/) - Conceptual foundation for abstract strategy board games
-- [SNN](https://sashite.dev/specs/snn/1.0.0/) - Style Name Notation
-- [GAN](https://sashite.dev/specs/gan/1.0.0/) - General Actor Notation (alternative style-aware format)
-- [CELL](https://sashite.dev/specs/cell/) - Board position coordinates
-- [HAND](https://sashite.dev/specs/hand/) - Reserve location notation
-- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
+* `Sashite::Pnn.valid?(str)` — Returns `true` if the string is valid PNN.
+* `Sashite::Pnn.parse(str)` — Returns a `Sashite::Pnn::Name` object.
+* `Sashite::Pnn.name(sym_or_str)` — Alias for constructing a name.
 
-## Documentation
+### `Sashite::Pnn::Name`
 
-- [Official PNN Specification v1.0.0](https://sashite.dev/specs/pnn/1.0.0/)
-- [PNN Examples Documentation](https://sashite.dev/specs/pnn/1.0.0/examples/)
-- [Game Protocol Foundation](https://sashite.dev/game-protocol/)
-- [API Documentation](https://rubydoc.info/github/sashite/pnn.rb/main)
+* `#value` — Returns the canonical string value.
+* `#to_s` — Returns the string representation.
+* `#base_name` — Returns the name without state modifier or terminal marker.
+* `#enhanced?` — Returns `true` if piece has enhanced state (`+` prefix).
+* `#diminished?` — Returns `true` if piece has diminished state (`-` prefix).
+* `#normal?` — Returns `true` if piece has normal state (no prefix).
+* `#terminal?` — Returns `true` if piece is a terminal piece (`^` suffix).
+* `#first_player?` — Returns `true` if piece belongs to first player (uppercase).
+* `#second_player?` — Returns `true` if piece belongs to second player (lowercase).
+* `#same_base_name?(other)` — Returns `true` if both pieces have same base name.
+* `#==`, `#eql?`, `#hash` — Value-based equality.
 
 ## Development
-
 ```sh
 # Clone the repository
 git clone https://github.com/sashite/pnn.rb.git