qi 10.0.0 → 12.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a98ed653f1c1d21ae215f4a8ab481a0a19dd93551a9a3ba0faf9ee8e541291f
-  data.tar.gz: d1291d436f366c70e07a64a3a6390a3a9d99d56cfeb8b0b85c1002addbe7b540
+  metadata.gz: c916e1be3a5a9e6c40fe3fad735488b69a4663607d55f80989a8daf023fd84b5
+  data.tar.gz: d4ba55868fa1dbfce8cf9d46dde4ed3be9d839cf59320c7f9f90ee9973c60393
 SHA512:
-  metadata.gz: 154aa839e292e2cadfbafe8c64e324285216da01a491ef98815479bf1bd735dc2ec747ad31e6ef479ea4d913b262dbcb9ad6399f13cdf5199dddb3403d7091ee
-  data.tar.gz: 52c5ca680fb11577fc2aa84931900b9f8c712e6c300ca5774f918f144fd1c999f1e34387e8827fe5f7f3d55ed192d04dabb310acc538c19bee3b941effb68637
+  metadata.gz: a0bd0d10e698c1f80c2cd6d501bb5d5be865f9b4e53de224be4fb4b7b84a0cf1d6ee22428c1c01c5f0904a867923f294bc2beba21701d729d294e39e4323d504
+  data.tar.gz: df8c064144e6194743d3a9bf86f78d958c748d3e6ce8bbdeb792768a3852ce1ba15b3bababb2ce948b7cc8e12be91563b8cfd1e6dfcc5c4b5302bfc0c15777e9

data/README.md

@@ -1,108 +1,362 @@
-# Qi.rb
+# qi.rb
 
-[![Version](https://img.shields.io/github/v/tag/sashite/qi.rb?label=Version&logo=github)](https://github.com/sashite/qi.rb/releases)
-[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/qi.rb/main)
-[![CI](https://github.com/sashite/qi.rb/workflows/CI/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions?query=workflow%3Aci+branch%3Amain)
-[![RuboCop](https://github.com/sashite/qi.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions?query=workflow%3Arubocop+branch%3Amain)
-[![License](https://img.shields.io/github/license/sashite/qi.rb?label=License&logo=github)](https://github.com/sashite/qi.rb/raw/main/LICENSE.md)
+[![Version](https://img.shields.io/gem/v/qi.svg)](https://rubygems.org/gems/qi)
+[![Documentation](https://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/qi)
+[![CI](https://github.com/sashite/qi.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/qi.rb/actions)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/sashite/qi.rb/blob/main/LICENSE)
 
-**Qi** (Chinese: 棋; pinyin: _qí_) is a lightweight, flexible, and adaptable tool for representing board game positions, built in Ruby. It is designed to be game-agnostic and can be used with a variety of board games such as Chess, Four-Player Chess, Go, Makruk, Shogi, and Xiangqi.
+> An immutable, format-agnostic position model for two-player board games.
 
-Qi uses a unique approach where the state of a game is represented through capturing the pieces in play, the arrangement of pieces on the board, the sequence of turns, and other possible states that a game can have.
+## Quick Start
 
-## Features
+```ruby
+gem "qi", "~> 12.0"
+```
+
+```ruby
+require "qi"
 
-1. **Game Agnostic:** Qi can be used to represent board game positions for a wide variety of games. Whether you are playing Chess, Makruk, Shogi, or Xiangqi, Qi's flexible structure allows you to accurately capture the state of your game.
-2. **Flexible Position Representation:** Qi captures the state of the game by recording the pieces in play, their arrangement on the board, the sequence of turns, and other additional states of the game. This enables a comprehensive view of the game at any given point.
-3. **State Manipulation:** Qi allows for manipulation and update of game states through the `commit` method, allowing transitions between game states.
-4. **Equality Checks:** With the `eql?` method, Qi allows for comparisons between different game states, which can be useful for tracking game progress, detecting repeats, or even in creating AI for your games.
-5. **Turn Management:** Qi keeps track of the sequence of turns allowing users to identify whose turn it is currently.
-6. **Access to Game Data:** Qi provides methods to access the current arrangement of pieces on the board (`squares_hash`) and the pieces captured by each player (`captures_hash`), helping users understand the current status of the game. It also allows access to a list of captured pieces (`captures_array`).
-7. **Customizability:** Qi is flexible and allows for customization as per your needs. The keys and values of the `captures_hash` and `squares_hash` can be any kind of object, as well as the items from `turns` and values from `state`.
+# Create an empty 8×8 board with player styles
+pos = Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
 
-While `Qi` does not generate game moves itself, it serves as a solid foundation upon which game engines can be built. Its design is focused on providing a robust and adaptable representation of game states, paving the way for the development of diverse board game applications.
+# Place pieces and switch turn
+pos2 = pos
+  .board_diff(0 => "r", 1 => "n", 2 => "b", 3 => "q", 4 => "k")
+  .board_diff(60 => "K", 59 => "Q", 58 => "B", 57 => "N", 56 => "R")
+  .toggle
 
-## Installation
+pos2.turn  #=> :second
+```
+
+Every transformation returns a **new frozen instance**. The original is never modified.
 
-Add this line to your application's Gemfile:
+## Overview
+
+`Qi` models a board game position as defined by the [Sashité Game Protocol](https://sashite.dev/game-protocol/). A position encodes exactly four things:
+
+| Component | Accessors | Description |
+|-----------|-----------|-------------|
+| Board | `board` | Multi-dimensional grid (1D, 2D, or 3D) of squares |
+| Hands | `first_player_hand`, `second_player_hand` | Off-board pieces held by each player |
+| Styles | `first_player_style`, `second_player_style` | One style String per player side |
+| Turn | `turn` | The active player (`:first` or `:second`) |
+
+**Pieces and styles are Strings.** Every piece — whether on the board or in a hand — and every style value is stored as a `String`. This aligns naturally with the notation formats in the Sashité ecosystem ([FEEN](https://sashite.dev/specs/feen/1.0.0/), [EPIN](https://sashite.dev/specs/epin/1.0.0/), [PON](https://sashite.dev/specs/pon/1.0.0/), [SIN](https://sashite.dev/specs/sin/1.0.0/)), which all produce string representations. Empty squares are represented by `nil`.
+
+**String normalization.** All inputs (pieces and styles) are normalized to `String` via interpolation (`"#{value}"`). This guarantees internal consistency without relying on type checks, and accepts any value that responds to `to_s`.
 
 ```ruby
-gem "qi"
+pos.board_diff(0 => "K")               # String — stored as "K"
+pos.board_diff(0 => :K)                # Symbol — normalized to "K"
+pos.board_diff(0 => "C:K")             # Namespaced — stored as "C:K"
+pos.board_diff(0 => "+P")              # Promoted — stored as "+P"
 ```
 
-And then execute:
+## Installation
 
-```sh
-bundle install
+```ruby
+# In your Gemfile
+gem "qi", "~> 12.0"
 ```
 
-Or install it yourself as:
+Or install manually:
 
 ```sh
 gem install qi
 ```
 
-## Usage
+### Requirements
+
+`Qi` requires **Ruby 3.2+** (tested against 3.2, 3.3, 3.4, and 4.0) and has **zero runtime dependencies**.
 
-The following usage example is derived from a classic _tsume shogi_ (詰将棋) problem, which translates to _mate shogi_ - a popular genre of shogi problems where the goal is to checkmate the opponent's king.
-In the provided setup, the attacking side is in possession of a silver general (S), a promoted bishop (+B) positioned on square 43, and a promoted pawn (+P) on square 22.
+## API Reference
 
-On the defending side, there is a king (k) situated on square 4, surrounded by two silver generals (s) on squares 3 and 5 respectively.
+### Construction
 
-In this scenario, `Qi` allows us to represent the state of the game and apply changes as moves are made. Please follow the given example to understand how to create such a representation and how to update it:
+#### `Qi.new(*shape, first_player_style:, second_player_style:)` → `Qi`
+
+Creates an immutable position with an empty board.
+
+**Parameters:**
+
+- `*shape` — one to three `Integer` dimension sizes (each 1–255).
+- `first_player_style:` — style for the first player (any non-nil value, normalized to `String`).
+- `second_player_style:` — style for the second player (any non-nil value, normalized to `String`).
+
+The board starts with all squares empty (`nil`), both hands start empty, and the turn defaults to `:first`. Styles are normalized to `String` and frozen at construction.
 
 ```ruby
-require "qi"
+Qi.new(8, 8, first_player_style: "C", second_player_style: "c")   # 2D (8×8)
+Qi.new(8, first_player_style: "G", second_player_style: "g")      # 1D
+Qi.new(5, 5, 5, first_player_style: "R", second_player_style: "r") # 3D
+```
 
-# Initialize an array for each player's captured pieces
-north_captures = %w[r r b g g g g s n n n n p p p p p p p p p p p p p p p p p]
-south_captures = %w[S]
+**Raises** `ArgumentError` if shape constraints are violated or if a style is `nil` (see [Validation Errors](#validation-errors)).
 
-# Combine and count each player's captured pieces
-captures = Hash.new(0)
-(north_captures + south_captures).each { |piece| captures[piece] += 1 }
+### Constants
 
-# Define the squares occupied by each piece on the board
-squares = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `Qi::MAX_DIMENSIONS` | `3` | Maximum number of board dimensions |
+| `Qi::MAX_DIMENSION_SIZE` | `255` | Maximum size of any single dimension |
 
-# Create a new game position
-qi0 = Qi.new(captures, squares, [0, 1])
+### Accessors
 
-# Verify the properties of the game position
-qi0.captures_array                          # => ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
-qi0.captures_hash                           # => {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
-qi0.squares_hash                            # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"}
-qi0.state                                   # => {}
-qi0.turn                                    # => 0
-qi0.turns                                   # => [0, 1]
-qi0.eql?(Qi.new(captures, squares, [0, 1])) # => true
-qi0.eql?(Qi.new(captures, squares, [1, 0])) # => false
+All accessors are safe to call from any thread. Collections return independent copies; styles and turn return immutable values.
 
-# Move a piece on the board and check the game state
-qi1 = qi0.commit([], [], { 43 => nil, 13 => "+B" }, in_check: true)
+| Method | Returns | Copy behavior |
+|--------|---------|---------------|
+| `board` | `Array` | Nested array (independent copy). Each leaf is `nil` or `String`. |
+| `first_player_hand` | `Array<String>` | Independent copy. |
+| `second_player_hand` | `Array<String>` | Independent copy. |
+| `turn` | `Symbol` | `:first` or `:second` (immutable). |
+| `first_player_style` | `String` | Frozen value (returned directly, no allocation). |
+| `second_player_style` | `String` | Frozen value (returned directly, no allocation). |
+| `shape` | `Array<Integer>` | Independent copy (e.g., `[8, 8]`). |
+| `inspect` | `String` | Developer-friendly, unstable format. Do not parse. |
 
-qi1.captures_array                          # => ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
-qi1.captures_hash                           # => {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
-qi1.squares_hash                            # => {3=>"s", 4=>"k", 5=>"s", 22=>"+P", 13=>"+B"}
-qi1.state                                   # => {:in_check=>true}
-qi1.turn                                    # => 1
-qi1.turns                                   # => [1, 0]
-qi1.eql?(Qi.new(captures, squares, [0, 1])) # => false
-qi1.eql?(Qi.new(captures, squares, [1, 0])) # => false
+```ruby
+pos.board                #=> [["r", "n", "b", ...], ...]
+pos.first_player_hand    #=> []
+pos.second_player_hand   #=> []
+pos.turn                 #=> :first
+pos.first_player_style   #=> "C"
+pos.second_player_style  #=> "c"
+pos.shape                #=> [8, 8]
+pos.inspect              #=> "#<Qi shape=[8, 8] turn=:first>"
 ```
 
-In this example, we first create a `Qi` object to represent a game position with `Qi.new`. Then, we check various aspects of the game state using the methods provided by `Qi`. After that, we create a new game state `qi1` by committing changes to the existing state `qi0`. Finally, we again check various aspects of the new game state.
+**Note:** Styles are frozen Strings. Attempting to mutate a returned style raises `FrozenError`. If you need a mutable copy, call `.dup` on the returned value.
 
-## License
+### Transformations
+
+All transformation methods return a **new frozen `Qi` instance**. The original is never modified.
+
+#### `board_diff(**squares)` → `Qi`
+
+Returns a new position with modified squares.
+
+Keys are flat indices (`Integer`, 0-based, row-major order). Values are pieces (normalized to `String`) or `nil` (empty square).
+
+```ruby
+pos2 = pos.board_diff(12 => nil, 28 => "P")
+```
 
-The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+**Raises** `ArgumentError` if an index is out of range or if the resulting total piece count exceeds the board size.
 
-## About Sashité
+See [Flat Indexing](#flat-indexing) for computing flat indices from coordinates.
 
-This [gem](https://rubygems.org/gems/qi) is proudly maintained and developed by [Sashité](https://sashite.com/). Our mission is to promote intercultural understanding and appreciation through the universal language of board games.
+#### `first_player_hand_diff(**pieces)` → `Qi`
+#### `second_player_hand_diff(**pieces)` → `Qi`
+
+Returns a new position with a modified hand.
+
+Keys are piece identifiers (normalized to `String`); values are integer deltas (positive to add, negative to remove, zero is a no-op). Removal uses **value equality** (`==`).
+
+```ruby
+pos2 = pos.first_player_hand_diff("P": 1)           # Add one "P"
+pos3 = pos.first_player_hand_diff("B": -1, "P": 1)  # Remove one "B", add one "P"
+pos4 = pos.second_player_hand_diff("p": 1)           # Add one "p" to second hand
+```
+
+**String normalization:** Ruby keyword arguments produce Symbol keys. The hand diff methods normalize these to Strings internally (`"P": 1` becomes key `:P`, stored as `"P"`). This is transparent in normal usage — the example above stores `"P"`, `"B"`, and `"p"` as Strings in the hand.
+
+**Raises** `ArgumentError` if a delta is not an `Integer`, if removing a piece not present, or if the resulting total piece count exceeds the board size.
+
+#### `toggle` → `Qi`
+
+Returns a new position with the active player swapped. All other fields are preserved.
+
+```ruby
+pos.turn           #=> :first
+pos.toggle.turn    #=> :second
+```
+
+#### Chaining
+
+Transformations compose naturally. A typical move involves modifying the board, optionally updating a hand, and toggling the turn:
+
+```ruby
+# Simple move: slide a piece from index 12 to index 28
+pos2 = pos
+  .board_diff(12 => nil, 28 => "P")
+  .toggle
+
+# Capture: overwrite defender, add captured piece to hand, toggle
+pos3 = pos
+  .board_diff(12 => nil, 28 => "P")        # Attacker replaces defender
+  .first_player_hand_diff("p": 1)          # Captured piece goes to hand
+  .toggle
+```
+
+The Protocol does not prescribe how captures are modeled. In the example above, `board_diff(12 => nil, 28 => "P")` simultaneously vacates the source and overwrites the destination. The captured piece must be added to the hand separately — `board_diff` does not track what was previously on a square.
+
+## Board Structure
+
+### Shape and Dimensionality
+
+The nesting depth of the array returned by `board` matches the number of dimensions:
+
+| Dimensionality | Constructor | `board` returns |
+|----------------|-------------|-----------------|
+| 1D | `Qi.new(8, ...)` | `[square, square, ...]` |
+| 2D | `Qi.new(8, 8, ...)` | `[[square, ...], [square, ...], ...]` |
+| 3D | `Qi.new(5, 5, 5, ...)` | `[[[square, ...], ...], ...]` |
+
+Each `square` is either `nil` (empty) or a `String` (a piece).
+
+For a shape `[D1, D2, ..., DN]`, the total number of squares is `D1 × D2 × ... × DN`.
+
+### Flat Indexing
+
+`board_diff` addresses squares by **flat index** — a single integer in **row-major order** (C order).
+
+**1D board** with shape `[F]`:
+
+```
+flat_index = f
+```
 
-At Sashité, we believe in the power of games as a medium for sharing and appreciating the richness of different cultures. From Chinese to Japanese, and Western traditions, every culture has its unique representation in the world of board games, particularly in chess.
+**2D board** with shape `[R, F]` (R ranks, F files):
 
-Our `Qi` gem is a testament to this belief - a flexible, efficient, and inclusive software that allows for the representation and interaction of diverse chess systems. This piece of software is not just a tool; it is a bridge connecting different cultures under the love of strategic play.
+```
+flat_index = r × F + f
+```
+
+For example, on a 3×3 board (shape `[3, 3]`):
+
+```
+             file
+           0   1   2
+        ┌────┬────┬────┐
+rank 0  │  0 │  1 │  2 │
+        ├────┼────┼────┤
+rank 1  │  3 │  4 │  5 │
+        ├────┼────┼────┤
+rank 2  │  6 │  7 │  8 │
+        └────┴────┴────┘
+```
+
+Square `(rank=1, file=2)` → flat index `1 × 3 + 2 = 5`.
+
+**3D board** with shape `[L, R, F]` (L layers, R ranks, F files):
+
+```
+flat_index = l × R × F + r × F + f
+```
+
+### Piece Cardinality
+
+The total number of pieces across all locations (board squares + both hands) must never exceed the number of squares on the board. This invariant is enforced on every transformation.
+
+For a board with *n* squares and *p* total pieces: **0 ≤ p ≤ n**.
+
+```ruby
+pos = Qi.new(2, first_player_style: "C", second_player_style: "c")
+  .board_diff(0 => "a", 1 => "b")   # 2 pieces on 2 squares: OK
+
+pos.first_player_hand_diff("c": 1)
+# => ArgumentError: too many pieces for board size (3 pieces, 2 squares)
+```
+
+## Validation Errors
+
+### Validation Order
+
+Construction validates fields in a guaranteed order. When multiple errors exist, the **first** failing check determines the error message:
+
+1. **Shape** — dimension count, types, and bounds
+2. **Styles** — nil checks (first, then second)
+
+This order is part of the public API contract.
+
+### Construction Errors
+
+| Error message | Cause |
+|---------------|-------|
+| `"at least one dimension is required"` | No dimension sizes provided |
+| `"board exceeds 3 dimensions (got N)"` | More than 3 dimension sizes |
+| `"dimension size must be an Integer, got C"` | Non-integer dimension size |
+| `"dimension size must be at least 1, got N"` | Dimension size is zero or negative |
+| `"dimension size N exceeds maximum of 255"` | Dimension size exceeds 255 |
+| `"first player style must not be nil"` | First style is `nil` |
+| `"second player style must not be nil"` | Second style is `nil` |
+
+### Transformation Errors
+
+| Error message | Method | Cause |
+|---------------|--------|-------|
+| `"invalid flat index: I (board has N squares)"` | `board_diff` | Index out of range or non-integer key |
+| `"delta must be an Integer, got C for piece P"` | hand diffs | Non-integer delta |
+| `"cannot remove P: not found in hand"` | hand diffs | Removing more pieces than present |
+| `"too many pieces for board size (P pieces, N squares)"` | all | Total pieces would exceed board capacity |
+
+## Design Principles
+
+**Immutable by construction.** Every `Qi` instance is frozen at creation. Transformation methods return new instances rather than mutating state. This eliminates an entire class of bugs around shared mutable state and makes positions safe to use as hash keys, cache entries, or history snapshots.
+
+**Diff-based transformations.** Rather than rebuilding a full position from scratch, `board_diff` and hand diff methods express changes as deltas against the current state. This keeps the API surface small (four transformation methods cover all possible state transitions) while making the intent of each operation explicit.
+
+**String normalization.** Pieces and styles are normalized to `String` via interpolation (`"#{value}"`). This aligns with the notation formats in the Sashité ecosystem (FEEN, EPIN, PON, SIN) which all produce string representations, and eliminates type conversions between layers. Rather than rejecting non-string inputs, the library coerces them — guaranteeing internal consistency by construction rather than by validation.
+
+**Zero dependencies.** `Qi` relies only on the Ruby standard library. No transitive dependency tree to audit, no version conflicts to resolve.
+
+## Thread Safety
+
+`Qi` instances are frozen at construction. Accessors that return collections (`board`, hands, `shape`) produce independent copies on each call. Styles are frozen Strings returned directly. This makes positions inherently thread-safe: they can be shared freely across threads without synchronization.
+
+## Ecosystem
+
+`Qi` is the positional core of the [Sashité](https://sashite.dev/) ecosystem. It models *what a position is* (board, hands, styles, turn) without prescribing *how positions are serialized* or *what moves are legal*.
+
+Other libraries in the ecosystem build on `Qi` to provide those capabilities: [FEEN](https://sashite.dev/specs/feen/1.0.0/) defines a canonical string encoding for positions, [PON](https://sashite.dev/specs/pon/1.0.0/) provides a JSON-based position format, [EPIN](https://sashite.dev/specs/epin/1.0.0/) specifies piece token syntax, and [SIN](https://sashite.dev/specs/sin/1.0.0/) specifies style token syntax. The [Game Protocol](https://sashite.dev/game-protocol/) describes the conceptual foundation that all these specifications share.
+
+## Notes for Reimplementors
+
+This section provides guidance for porting `Qi` to other languages.
+
+### API Surface
+
+The complete public API consists of:
+
+- **1 constructor** — `Qi.new(*shape, first_player_style:, second_player_style:)`
+- **7 accessors** — `board`, `first_player_hand`, `second_player_hand`, `turn`, `first_player_style`, `second_player_style`, `shape`
+- **4 transformations** — `board_diff`, `first_player_hand_diff`, `second_player_hand_diff`, `toggle`
+- **1 debug** — `inspect`
+- **2 constants** — `MAX_DIMENSIONS`, `MAX_DIMENSION_SIZE`
+
+### API Naming
+
+The Ruby API separates **accessors** (read) from **transformations** (diff) using a `_diff` suffix. In languages where this convention is unusual, alternatives include `with_board(...)` / `with_first_hand(...)` for a fluent style, or `update_board(...)` / `update_hand(side, ...)` for a more imperative style.
+
+### Key Semantic Contracts
+
+**Pieces and styles are strings.** Board squares, hand contents, and style values are all stored as strings. The Ruby implementation normalizes inputs via interpolation (`"#{value}"`), accepting any value that responds to `to_s`. Statically typed languages should accept string parameters directly.
+
+**Piece equality is by value**, not by identity. Hand removal uses value-based matching (Ruby's `==`). Use the equivalent in your language (`Eq` in Rust, `__eq__` in Python, `equals()` in Java).
+
+**Piece cardinality is global.** The constraint `p ≤ n` counts pieces across all locations: board squares plus both hands. A transformation that adds a piece to a hand can exceed the limit even if the board has empty squares.
+
+**Nil means empty.** On the board, `nil` (or the language equivalent) represents an empty square. It is never coerced to a string. Styles must not be nil — this is the only nil-related error at construction.
+
+**Validation order is guaranteed**: shape → styles. Tests assert which error is reported when multiple inputs are invalid simultaneously.
+
+**Positions are immutable**: all transformation methods return a new instance. The original is never modified.
+
+**Accessors protect internal state**: mutable collections (`board`, hands, `shape`) return fresh copies. Styles are frozen Strings returned directly (zero-cost access). `turn` returns an immutable value.
+
+**The constructor creates an empty position**: board all null, hands empty, turn is first player. Pieces are added via `board_diff` and hand diff methods.
+
+### Hand Diff and String Normalization
+
+In Ruby, keyword arguments produce Symbol keys, so `first_player_hand_diff("P": 1)` passes `{P: 1}` with key `:P` (a Symbol). The implementation normalizes this to the String `"P"` before storing.
+
+This is a Ruby-specific concern. In other languages, hand diff methods should accept string keys directly. The important contract is that the hand always contains strings, matching the board's piece type.
+
+### Duplicate Key Policy
+
+In Ruby, passing the same keyword argument twice keeps only the last value (`board_diff(0 => "a", 0 => "b")` is equivalent to `board_diff(0 => "b")`). Reimplementations should define their own policy: last-write-wins, first-write-wins, or rejection.
+
+## License
 
-Join us in our journey as we continue to write [code](https://github.com/sashite/) to share the beauty of these cultures, one game at a time.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).

data/lib/qi/board.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+class Qi
+  # Pure validation functions for multi-dimensional board structures.
+  #
+  # A board is represented as a nested Array where:
+  #
+  # - A *1D board* is a flat array of squares: +[nil, "K^", nil]+
+  # - A *2D board* is an array of ranks: +[[nil, nil], ["K^", nil]]+
+  # - A *3D board* is an array of layers, each an array of ranks.
+  #
+  # Each leaf element (square) is either +nil+ (empty) or any non-nil
+  # object (a piece). String normalization of pieces is the responsibility
+  # of the +Qi+ class, not of this module.
+  #
+  # == Constraints
+  #
+  # - Maximum dimensionality: 3
+  # - Maximum size per dimension: 255
+  # - At least one square (non-empty board)
+  # - Rectangular structure: all sub-arrays at the same depth must have
+  #   identical length (enforced globally, not just per-sibling).
+  #
+  # @example Validate a 2D board
+  #   Qi::Board.validate([["a", nil], [nil, "b"]]) #=> [4, 2]
+  #
+  # @example Validate an empty board
+  #   Qi::Board.validate([[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]) #=> [9, 0]
+  module Board
+    MAX_DIMENSIONS    = 3
+    MAX_DIMENSION_SIZE = 255
+
+    # Validates a board and returns its square and piece counts.
+    #
+    # Validation is performed in a single recursive pass that simultaneously
+    # infers the board shape, verifies structural regularity, checks dimension
+    # limits, and counts squares and pieces.
+    #
+    # @param board [Object] the board structure to validate.
+    # @return [Array(Integer, Integer)] +[square_count, piece_count]+.
+    # @raise [ArgumentError] if the board is structurally invalid.
+    #
+    # @example A 2D board
+    #   Qi::Board.validate([["r", nil, nil], [nil, nil, "R"]]) #=> [6, 2]
+    #
+    # @example A 1D board
+    #   Qi::Board.validate(["k", nil, nil, "K"]) #=> [4, 2]
+    #
+    # @example A 3D board (2 layers × 2 ranks × 2 files)
+    #   Qi::Board.validate([[["a", nil], [nil, "b"]], [[nil, "c"], ["d", nil]]]) #=> [8, 4]
+    #
+    # @example Non-rectangular boards are rejected
+    #   Qi::Board.validate([["a", "b"], ["c"]])
+    #   # => ArgumentError: non-rectangular board: expected 2 elements, got 1
+    def self.validate(board)
+      unless board.is_a?(::Array)
+        raise ::ArgumentError, "board must be an Array"
+      end
+
+      if board.empty?
+        raise ::ArgumentError, "board must not be empty"
+      end
+
+      validate_recursive(board, nil, 0)
+    end
+
+    # Single-pass recursive validation.
+    #
+    # At each level, determines whether this is a leaf rank (contains
+    # non-Array elements) or an intermediate dimension (contains Arrays).
+    # Infers expected sizes from the first element at each level,
+    # validates all siblings match, and enforces dimension limits.
+    #
+    # @param node [Array] the current sub-array being validated.
+    # @param expected_size [Integer, nil] expected length (nil if first sibling).
+    # @param depth [Integer] current nesting depth (0-based).
+    # @return [Array(Integer, Integer)] +[square_count, piece_count]+.
+    def self.validate_recursive(node, expected_size, depth)
+      if expected_size && node.size != expected_size
+        raise ::ArgumentError, "non-rectangular board: expected #{expected_size} elements, got #{node.size}"
+      end
+
+      if node.size > MAX_DIMENSION_SIZE
+        raise ::ArgumentError, "dimension size #{node.size} exceeds maximum of #{MAX_DIMENSION_SIZE}"
+      end
+
+      if node.first.is_a?(::Array)
+        # Intermediate dimension: validate depth, then recurse.
+        if depth >= MAX_DIMENSIONS - 1
+          raise ::ArgumentError, "board exceeds #{MAX_DIMENSIONS} dimensions"
+        end
+
+        inner_size = node.first.size
+
+        if inner_size == 0
+          raise ::ArgumentError, "board must not be empty"
+        end
+
+        total_squares = 0
+        total_pieces  = 0
+
+        node.each do |sub|
+          unless sub.is_a?(::Array)
+            raise ::ArgumentError, "inconsistent board structure: mixed arrays and non-arrays at same level"
+          end
+
+          sq, pc = validate_recursive(sub, inner_size, depth + 1)
+          total_squares += sq
+          total_pieces  += pc
+        end
+
+        [total_squares, total_pieces]
+      else
+        # Leaf rank: validate structure, then count pieces.
+        node.each do |square|
+          if square.is_a?(::Array)
+            raise ::ArgumentError, "inconsistent board structure: expected flat squares at this level"
+          end
+        end
+
+        [node.size, node.count { |sq| !sq.nil? }]
+      end
+    end
+
+    private_class_method :validate_recursive
+
+    freeze
+  end
+end

data/lib/qi/hands.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Qi
+  # Pure validation functions for player hands.
+  #
+  # Hands are represented as a Hash with exactly two keys:
+  #
+  # - +:first+ — array of pieces held by the first player.
+  # - +:second+ — array of pieces held by the second player.
+  #
+  # Each piece in a hand can be any non-nil object. String normalization
+  # of pieces is the responsibility of the +Qi+ class, not of this module.
+  # The ordering of pieces within a hand carries no semantic meaning.
+  #
+  # @example Validate hands with pieces
+  #   Qi::Hands.validate({ first: ["+P", "+P"], second: ["b"] }) #=> 3
+  #
+  # @example Validate empty hands
+  #   Qi::Hands.validate({ first: [], second: [] }) #=> 0
+  module Hands
+    # Validates hands structure and returns the total piece count.
+    #
+    # Validation checks shape (exactly two keys), type (both values are
+    # arrays), and rejects +nil+ elements in each hand.
+    #
+    # @param hands [Object] the hands structure to validate.
+    # @return [Integer] the total number of pieces across both hands.
+    # @raise [ArgumentError] if the hands structure is invalid.
+    #
+    # @example Valid hands
+    #   Qi::Hands.validate({ first: ["P", "B"], second: ["p"] }) #=> 3
+    #
+    # @example Nil piece rejected
+    #   Qi::Hands.validate({ first: [nil], second: [] })
+    #   # => ArgumentError: hand pieces must not be nil
+    #
+    # @example Missing key
+    #   Qi::Hands.validate({ first: [] })
+    #   # => ArgumentError: hands must have exactly keys :first and :second
+    def self.validate(hands)
+      validate_shape(hands)
+      validate_arrays(hands)
+      validate_hand(hands[:first])
+      validate_hand(hands[:second])
+      hands[:first].size + hands[:second].size
+    end
+
+    # --- Shape validation -----------------------------------------------------
+
+    def self.validate_shape(hands)
+      unless hands.is_a?(::Hash)
+        raise ::ArgumentError, "hands must be a Hash with keys :first and :second"
+      end
+
+      return if hands.size == 2 && hands.key?(:first) && hands.key?(:second)
+
+      raise ::ArgumentError, "hands must have exactly keys :first and :second"
+    end
+
+    def self.validate_arrays(hands)
+      return if hands[:first].is_a?(::Array) && hands[:second].is_a?(::Array)
+
+      raise ::ArgumentError, "each hand must be an Array"
+    end
+
+    # --- Piece validation -----------------------------------------------------
+
+    def self.validate_hand(pieces)
+      pieces.each do |piece|
+        raise ::ArgumentError, "hand pieces must not be nil" if piece.nil?
+      end
+    end
+
+    private_class_method :validate_shape,
+                         :validate_arrays,
+                         :validate_hand
+
+    freeze
+  end
+end

data/lib/qi/styles.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+class Qi
+  # Pure validation functions for player styles.
+  #
+  # Styles are represented as a Hash with exactly two keys:
+  #
+  # - +:first+ — the style associated with the first player side.
+  # - +:second+ — the style associated with the second player side.
+  #
+  # Style values can be any non-nil object. String normalization is the
+  # responsibility of the +Qi+ class, not of this module. Semantic
+  # validation (e.g., SIN compliance) is the responsibility of the
+  # encoding layer (FEEN, PON, etc.).
+  #
+  # @example Validate string styles
+  #   Qi::Styles.validate({ first: "C", second: "c" }) #=> nil
+  #
+  # @example Validate symbol styles
+  #   Qi::Styles.validate({ first: :chess, second: :shogi }) #=> nil
+  module Styles
+    # Validates the styles structure.
+    #
+    # Returns +nil+ if the Hash has exactly keys +:first+ and +:second+ with
+    # non-nil values, or raises +ArgumentError+ otherwise.
+    #
+    # @param styles [Object] the styles structure to validate.
+    # @return [nil]
+    # @raise [ArgumentError] if the styles structure is invalid.
+    #
+    # @example Valid styles
+    #   Qi::Styles.validate({ first: "S", second: "s" }) #=> nil
+    #
+    # @example Nil first style
+    #   Qi::Styles.validate({ first: nil, second: "c" })
+    #   # => ArgumentError: first player style must not be nil
+    #
+    # @example Nil second style
+    #   Qi::Styles.validate({ first: "C", second: nil })
+    #   # => ArgumentError: second player style must not be nil
+    #
+    # @example Missing key
+    #   Qi::Styles.validate({ first: "C" })
+    #   # => ArgumentError: styles must have exactly keys :first and :second
+    #
+    # @example Not a Hash
+    #   Qi::Styles.validate("not a hash")
+    #   # => ArgumentError: styles must be a Hash with keys :first and :second
+    def self.validate(styles)
+      validate_shape(styles)
+      validate_non_nil(styles)
+    end
+
+    def self.validate_shape(styles)
+      unless styles.is_a?(::Hash)
+        raise ::ArgumentError, "styles must be a Hash with keys :first and :second"
+      end
+
+      return if styles.size == 2 && styles.key?(:first) && styles.key?(:second)
+
+      raise ::ArgumentError, "styles must have exactly keys :first and :second"
+    end
+
+    def self.validate_non_nil(styles)
+      raise ::ArgumentError, "first player style must not be nil" if styles[:first].nil?
+      raise ::ArgumentError, "second player style must not be nil" if styles[:second].nil?
+    end
+
+    private_class_method :validate_shape,
+                         :validate_non_nil
+
+    freeze
+  end
+end

data/lib/qi.rb

@@ -1,118 +1,398 @@
 # frozen_string_literal: true
 
-# The Qi class provides a consistent representation of a game state
-# and supports changes in the game state through the commit method.
-# It is designed to be used in board games such as chess, makruk, shogi, xiangqi.
+require_relative "qi/board"
+require_relative "qi/hands"
+require_relative "qi/styles"
+
+# A minimal, format-agnostic library for representing positions in
+# two-player, turn-based board games.
+#
+# Qi models the components of a position as defined by the
+# Sashité Game Protocol:
+#
+# - *Board* — a multi-dimensional rectangular grid (1D, 2D, or 3D)
+#   where each square is either empty (+nil+) or occupied by a piece
+#   (+String+).
+# - *Hands* — collections of off-board pieces (+String+) held by each player.
+# - *Styles* — one style +String+ per player side.
+# - *Turn* — which player is active (+:first+ or +:second+).
+#
+# Pieces and styles are normalized to +String+ via interpolation
+# (<tt>"#{value}"</tt>), aligning naturally with the notation formats
+# in the Sashité ecosystem (FEEN, EPIN, PON, SIN). Qi validates
+# structural integrity, not game semantics.
+#
+# == Construction
+#
+# A position is constructed from the board shape and player styles.
+# The board starts empty (all squares +nil+), both hands start empty,
+# and the turn starts as +:first+.
+#
+#   pos = Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
+#
+# == Accessors
+#
+# Use +board+, +first_player_hand+, +second_player_hand+, +turn+,
+# +first_player_style+, +second_player_style+, and +shape+ to read
+# field values. Mutable fields return defensive copies.
+#
+# == Transformations
+#
+# Use +board_diff+, +first_player_hand_diff+, +second_player_hand_diff+,
+# and +toggle+ to derive new positions. Transformation methods return
+# a new frozen +Qi+ instance and can be chained:
+#
+#   pos2 = pos.board_diff(12 => nil, 28 => "C:P").first_player_hand_diff("c:p": 1).toggle
+#
+# @example A chess starting position
+#   pos = Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
+#     .board_diff(
+#       0 => "r", 1 => "n", 2 => "b", 3 => "q", 4 => "k", 5 => "b", 6 => "n", 7 => "r",
+#       8 => "p", 9 => "p", 10 => "p", 11 => "p", 12 => "p", 13 => "p", 14 => "p", 15 => "p",
+#       48 => "P", 49 => "P", 50 => "P", 51 => "P", 52 => "P", 53 => "P", 54 => "P", 55 => "P",
+#       56 => "R", 57 => "N", 58 => "B", 59 => "Q", 60 => "K", 61 => "B", 62 => "N", 63 => "R"
+#     )
+#   pos.turn               #=> :first
+#   pos.first_player_hand  #=> []
 class Qi
-  # @!attribute [r] captures_hash
-  #   @return [Hash<Object, Integer>] a hash of captured pieces
-  #   @example
-  #     {"r"=>2, "b"=>1, "g"=>4, "s"=>1, "n"=>4, "p"=>17, "S"=>1}
-
-  # @!attribute [r] squares_hash
-  #   @return [Hash<Object, Object>] A hash where the keys represent square
-  #     identifiers and the values represent the piece that will occupy each square.
-  #     Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
-  #   @example
-  #     {A3: "s", E4: "k", B5: "s", C22: "+P", D43: "+B"}
-
-  # @!attribute [r] state
-  #   @return [Hash<Symbol, Object>] a hash of game states
-  #   @example
-  #     {:in_check=>true}
-
-  # @!attribute [r] turns
-  #   @return [Array<Object>] a rotation of turns
-  #   @example
-  #     ["Sente", "Gote"]
-
-  attr_reader :captures_hash, :squares_hash, :state, :turns
-
-  # @param captures_hash [Hash<Object, Integer>] a hash of captured pieces
-  # @param squares_hash [Hash<Object, Object>] A hash where the keys represent square
-  #   identifiers and the values represent the piece that will occupy each square.
-  #   Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
-  # @param turns [Array<Object>] a rotation of turns
-  # @param state [Hash<Symbol, Object>] a hash of game states
+  MAX_DIMENSIONS     = Board::MAX_DIMENSIONS
+  MAX_DIMENSION_SIZE = Board::MAX_DIMENSION_SIZE
+
+  # Creates a validated, immutable position with an empty board.
   #
-  # @example
-  #   captures = Hash.new(0)
-  #   north_captures = %w[r r b g g g g s n n n n p p p p p p p p p p p p p p p p p]
-  #   south_captures = %w[S]
-  #   (north_captures + south_captures).each { |piece| captures[piece] += 1 }
-  #   squares = { 3 => "s", 4 => "k", 5 => "s", 22 => "+P", 43 => "+B" }
-  #   Qi.new(captures, squares, [0, 1])
-  def initialize(captures_hash, squares_hash, turns, **state)
-    @captures_hash = ::Hash.new(0).merge(captures_hash.select { |_, v| v > 0 })
-    @squares_hash = squares_hash.compact
-    @turns = turns
-    @state = state.transform_keys(&:to_sym)
+  # The board starts with all squares empty (+nil+), both hands empty,
+  # and the turn set to +:first+. Styles are normalized to +String+
+  # and frozen.
+  #
+  # @param shape [Array<Integer>] dimension sizes (1 to 3 integers, each 1–255).
+  # @param first_player_style [#to_s] style for the first player (non-nil,
+  #   normalized to +String+).
+  # @param second_player_style [#to_s] style for the second player (non-nil,
+  #   normalized to +String+).
+  # @return [Qi] an immutable, validated position.
+  # @raise [ArgumentError] if any constraint is violated.
+  #
+  # @example 2D chess board
+  #   Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
+  #
+  # @example 3D board
+  #   Qi.new(5, 5, 5, first_player_style: "R", second_player_style: "r")
+  def initialize(*shape, first_player_style:, second_player_style:)
+    validate_shape(shape)
+    validate_not_nil(:first, first_player_style)
+    validate_not_nil(:second, second_player_style)
+
+    @shape               = shape.freeze
+    @chunk_sizes         = compute_chunk_sizes(shape).freeze
+    @square_count        = shape.reduce(:*)
+    @board               = ::Array.new(@square_count)
+    @first_hand          = []
+    @second_hand         = []
+    @first_player_style  = "#{first_player_style}".freeze
+    @second_player_style = "#{second_player_style}".freeze
+    @turn                = :first
+    @board_piece_count   = 0
 
     freeze
   end
 
-  # Return an array of captures containing piece names.
+  # --- Accessors ---------------------------------------------------------------
+
+  # Returns the board as a nested array matching the board shape.
+  #
+  # Each leaf element is +nil+ (empty square) or a +String+ (a piece).
+  # The returned structure is an independent copy.
+  #
+  # @return [Array] nested array (1D, 2D, or 3D depending on shape).
   #
-  # @return [Array<Object>] an array of captures
   # @example
-  #   ["S", "b", "g", "g", "g", "g", "n", "n", "n", "n", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "p", "r", "r", "s"]
-  def captures_array
-    captures_hash.flat_map { |piece, count| ::Array.new(count, piece) }.sort
+  #   pos = Qi.new(2, 3, first_player_style: "C", second_player_style: "c")
+  #     .board_diff(0 => "a", 5 => "b")
+  #   pos.board #=> [["a", nil, nil], [nil, nil, "b"]]
+  def board
+    unflatten(@board, @chunk_sizes, 0)
   end
 
-  # Commit a change to the game state and return a new Qi object.
+  # Returns the pieces held by the first player.
   #
-  # @param add_captures_array [Array<Object>] an array of pieces to be added to captures
-  # @param del_captures_array [Array<Object>] an array of pieces to be deleted from captures
-  # @param edit_squares_hash [Hash<Object, Object>] A hash where the keys represent square
-  #   identifiers and the values represent the piece that will occupy each square.
-  #   Both the keys and values can be any type of Ruby object, such as integers, strings, symbols, etc.
-  # @param state [Hash<Symbol, Object>] a hash of new game states
-  # @return [Qi] a new Qi object representing the updated game state
-  # @example
-  #   qi0.commit([], [], { D43: nil, B13: "+B" }, in_check: true)
-  def commit(add_captures_array, del_captures_array, edit_squares_hash, **state)
-    self.class.new(
-      edit_captures_hash(add_captures_array.compact, del_captures_array.compact, **captures_hash),
-      squares_hash.merge(edit_squares_hash),
-      turns.rotate,
-      **state
-    )
+  # @return [Array<String>] independent copy of the first player's hand.
+  def first_player_hand
+    @first_hand.dup
   end
 
-  # Check if the current Qi object is equal to another Qi object.
+  # Returns the pieces held by the second player.
   #
-  # @param other [Qi] another Qi object
-  # @return [Boolean] returns true if the captures_hash, squares_hash, turn, and state of both Qi objects are equal, false otherwise
-  def eql?(other)
-    return false unless other.captures_hash == captures_hash
-    return false unless other.squares_hash == squares_hash
-    return false unless other.turn == turn
-    return false unless other.state == state
-
-    true
+  # @return [Array<String>] independent copy of the second player's hand.
+  def second_player_hand
+    @second_hand.dup
   end
-  alias == eql?
 
-  # Get the current turn.
+  # Returns the active player's side.
   #
-  # @return [Object] the current turn
+  # @return [Symbol] +:first+ or +:second+.
   def turn
-    turns.fetch(0)
+    @turn
+  end
+
+  # Returns the first player's style.
+  #
+  # @return [String] frozen style value.
+  def first_player_style
+    @first_player_style
+  end
+
+  # Returns the second player's style.
+  #
+  # @return [String] frozen style value.
+  def second_player_style
+    @second_player_style
+  end
+
+  # Returns the board dimensions.
+  #
+  # @return [Array<Integer>] independent copy of the shape (e.g., +[8, 8]+).
+  def shape
+    @shape.dup
+  end
+
+  # --- Transformations ---------------------------------------------------------
+
+  # Returns a new position with modified squares on the board.
+  #
+  # Accepts keyword arguments where each key is a flat index (Integer,
+  # 0-based, row-major order) and each value is a piece (normalized to
+  # +String+) or +nil+ (empty square).
+  #
+  # @param squares [Hash{Integer => #to_s, nil}] flat index to piece mapping.
+  # @return [Qi] a new immutable position with the updated board.
+  # @raise [ArgumentError] if a key is not a valid flat index.
+  # @raise [ArgumentError] if the resulting piece count exceeds the board size.
+  #
+  # @example Move a piece from index 12 to index 28
+  #   pos2 = pos.board_diff(12 => nil, 28 => "C:P")
+  def board_diff(**squares)
+    new_board = @board.dup
+    delta = 0
+
+    squares.each do |flat_index, value|
+      unless flat_index.is_a?(::Integer) && flat_index >= 0 && flat_index < @square_count
+        raise ::ArgumentError, "invalid flat index: #{flat_index} (board has #{@square_count} squares)"
+      end
+
+      value = "#{value}" unless value.nil?
+
+      old_value = new_board[flat_index]
+      # Track net change in piece count: +1 if filling, -1 if emptying, 0 if replacing.
+      delta += (value.nil? ? 0 : 1) - (old_value.nil? ? 0 : 1)
+      new_board[flat_index] = value
+    end
+
+    derive(new_board, @first_hand, @second_hand, @turn, @board_piece_count + delta)
+  end
+
+  # Returns a new position with the first player's hand modified.
+  #
+  # Accepts keyword arguments where each key is a piece identifier
+  # (normalized to +String+) and each value is an integer delta:
+  # positive adds copies, negative removes matching pieces (by value
+  # equality). A delta of zero is a no-op.
+  #
+  # @param pieces [Hash{#to_s => Integer}] piece to delta mapping.
+  # @return [Qi] a new immutable position with the updated hand.
+  # @raise [ArgumentError] if a delta is not an Integer.
+  # @raise [ArgumentError] if removing more pieces than present.
+  # @raise [ArgumentError] if the resulting piece count exceeds the board size.
+  #
+  # @example Add a pawn and remove a bishop
+  #   pos2 = pos.first_player_hand_diff("S:P": 1, "S:B": -1)
+  def first_player_hand_diff(**pieces)
+    new_hand = apply_hand_changes(@first_hand, pieces)
+    derive(@board, new_hand, @second_hand, @turn, @board_piece_count)
+  end
+
+  # Returns a new position with the second player's hand modified.
+  #
+  # Accepts keyword arguments where each key is a piece identifier
+  # (normalized to +String+) and each value is an integer delta:
+  # positive adds copies, negative removes matching pieces (by value
+  # equality). A delta of zero is a no-op.
+  #
+  # @param pieces [Hash{#to_s => Integer}] piece to delta mapping.
+  # @return [Qi] a new immutable position with the updated hand.
+  # @raise [ArgumentError] if a delta is not an Integer.
+  # @raise [ArgumentError] if removing more pieces than present.
+  # @raise [ArgumentError] if the resulting piece count exceeds the board size.
+  #
+  # @example Add a captured pawn
+  #   pos2 = pos.second_player_hand_diff("c:p": 1)
+  def second_player_hand_diff(**pieces)
+    new_hand = apply_hand_changes(@second_hand, pieces)
+    derive(@board, @first_hand, new_hand, @turn, @board_piece_count)
+  end
+
+  # Returns a new position with the active player swapped.
+  #
+  # All other fields (board, hands, styles) are preserved unchanged.
+  #
+  # @return [Qi] a new immutable position with the opposite turn.
+  #
+  # @example
+  #   pos = Qi.new(8, 8, first_player_style: "C", second_player_style: "c")
+  #   pos.turn           #=> :first
+  #   pos.toggle.turn    #=> :second
+  def toggle
+    derive(@board, @first_hand, @second_hand, other_turn, @board_piece_count)
+  end
+
+  # Returns a developer-friendly string representation.
+  #
+  # The format is not stable and should not be parsed.
+  #
+  # @return [String]
+  def inspect
+    "#<#{self.class} shape=#{@shape.inspect} turn=#{@turn.inspect}>"
   end
 
   private
 
-  # Edits the captures hash and returns it.
+  def other_turn
+    @turn == :first ? :second : :first
+  end
+
+  # Fast-path constructor for derived positions.
+  #
+  # Skips shape and style validation since the source position already
+  # guarantees these invariants. Only checks cardinality.
+  #
+  # Unchanged fields are shared by reference — safe because both positions
+  # are frozen and accessors return defensive copies.
+  def derive(board, first_hand, second_hand, turn, board_piece_count)
+    hand_piece_count = first_hand.size + second_hand.size
+    validate_cardinality(@square_count, board_piece_count + hand_piece_count)
+
+    instance = self.class.allocate
+    instance.send(:init_derived, board, first_hand, second_hand, turn,
+                  @shape, @chunk_sizes, @square_count, board_piece_count,
+                  @first_player_style, @second_player_style)
+    instance
+  end
+
+  # Assigns instance variables for a derived position and freezes it.
+  def init_derived(board, first_hand, second_hand, turn, shape, chunk_sizes,
+                   square_count, board_piece_count, first_player_style,
+                   second_player_style)
+    @board               = board
+    @first_hand          = first_hand
+    @second_hand         = second_hand
+    @turn                = turn
+    @shape               = shape
+    @chunk_sizes         = chunk_sizes
+    @square_count        = square_count
+    @board_piece_count   = board_piece_count
+    @first_player_style  = first_player_style
+    @second_player_style = second_player_style
+
+    freeze
+  end
+
+  # --- Validation --------------------------------------------------------------
+
+  def validate_shape(shape)
+    if shape.empty?
+      raise ::ArgumentError, "at least one dimension is required"
+    end
+
+    if shape.size > MAX_DIMENSIONS
+      raise ::ArgumentError, "board exceeds #{MAX_DIMENSIONS} dimensions (got #{shape.size})"
+    end
+
+    shape.each do |dim|
+      unless dim.is_a?(::Integer)
+        raise ::ArgumentError, "dimension size must be an Integer, got #{dim.class}"
+      end
+
+      if dim < 1
+        raise ::ArgumentError, "dimension size must be at least 1, got #{dim}"
+      end
+
+      if dim > MAX_DIMENSION_SIZE
+        raise ::ArgumentError, "dimension size #{dim} exceeds maximum of #{MAX_DIMENSION_SIZE}"
+      end
+    end
+  end
+
+  def validate_not_nil(side, style)
+    raise ::ArgumentError, "#{side} player style must not be nil" if style.nil?
+  end
+
+  def validate_cardinality(square_count, piece_count)
+    return if piece_count <= square_count
+
+    raise ::ArgumentError, "too many pieces for board size (#{piece_count} pieces, #{square_count} squares)"
+  end
+
+  # --- Hand helpers ------------------------------------------------------------
+
+  # Applies delta changes to a hand array, returning a new array.
   #
-  # @param add_captures_array [Array<Object>] an array of pieces to be added to captures
-  # @param del_captures_array [Array<Object>] an array of pieces to be deleted from captures
-  # @param hash [Hash<Object, Integer>] the current captures hash
-  # @return [Hash<Object, Integer>] the updated captures hash
-  def edit_captures_hash(add_captures_array, del_captures_array, **hash)
-    add_captures_array.each { |piece_name| hash[piece_name] += 1 }
-    del_captures_array.each { |piece_name| hash[piece_name] -= 1 }
+  # Piece keys are normalized to String via interpolation.
+  def apply_hand_changes(hand, changes)
+    result = hand.dup
+
+    changes.each do |piece_key, delta|
+      unless delta.is_a?(::Integer)
+        raise ::ArgumentError, "delta must be an Integer, got #{delta.class} for piece #{piece_key.inspect}"
+      end
+
+      next if delta == 0
 
-    hash
+      piece = "#{piece_key}"
+
+      if delta > 0
+        delta.times { result << piece }
+      else
+        (-delta).times do
+          idx = result.index(piece)
+
+          unless idx
+            raise ::ArgumentError, "cannot remove #{piece.inspect}: not found in hand"
+          end
+
+          result.delete_at(idx)
+        end
+      end
+    end
+
+    result
   end
+
+  # --- Board helpers -----------------------------------------------------------
+
+  # Pre-computes chunk sizes for each dimension level.
+  # For shape [8, 8], returns [8, 1].
+  # For shape [5, 5, 5], returns [25, 5, 1].
+  # For shape [8], returns [1].
+  def compute_chunk_sizes(shape)
+    sizes = ::Array.new(shape.size)
+    sizes[-1] = 1
+    (shape.size - 2).downto(0) do |i|
+      sizes[i] = sizes[i + 1] * shape[i + 1]
+    end
+    sizes
+  end
+
+  # Reconstructs a nested board structure from a flat Array and
+  # pre-computed chunk sizes. Returns an independent copy.
+  def unflatten(flat, chunk_sizes, dim)
+    if dim == chunk_sizes.size - 1
+      return flat.dup
+    end
+
+    chunk = chunk_sizes[dim]
+    flat.each_slice(chunk).map do |slice|
+      unflatten(slice, chunk_sizes, dim + 1)
+    end
+  end
+
+  freeze
 end

metadata

@@ -1,31 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: qi
 version: !ruby/object:Gem::Version
-  version: 10.0.0
+  version: 12.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-05-29 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A flexible and customizable library for representing and manipulating
-  game states, ideal for developing board games like chess, shogi, or xiangqi.
+description: A minimal, format-agnostic library for representing positions in two-player,
+  turn-based board games (chess, shogi, xiangqi, and variants).
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
 - README.md
 - lib/qi.rb
+- lib/qi/board.rb
+- lib/qi/hands.rb
+- lib/qi/styles.rb
 homepage: https://github.com/sashite/qi.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -40,8 +40,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key: 
+rubygems_version: 4.0.5
 specification_version: 4
-summary: Versatile Board Game Position Representation
+summary: A minimal, format-agnostic position model for two-player board games.
 test_files: []

data/LICENSE.md

@@ -1,21 +0,0 @@
-# The MIT License
-
-Copyright (c) 2015-2023 Sashité
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.