pgn2 1.2.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 963f48df8fbfe5d69097030a9434a05b82e211c235772273f03bd11178afb8a5
-  data.tar.gz: 6bc38e0387e7061e3649fe52d22e5f01dabdc7029f8c27294d56b62a3779a76c
+  metadata.gz: 9d90a73cdcc2fc1b2765b35315935c6f20272a0e2374863d0d7c491a21f815ff
+  data.tar.gz: e4b34dfcb1e2d0c63ed479d338a0d58f3808f965db99000844cf7dcfa3af8fc9
 SHA512:
-  metadata.gz: e81b88377f5d1ab6102a5b15d4d006feb4201647125b5b3d434b826dfa55cac60c82048fc8d4d2a4c8aa7d1600d6ba4edd472f27d063d258703d8e225c0832cc
-  data.tar.gz: 06cb00152b81f2124749fbc743356a25a7ee44e049c7779fb397660a84ebfefee8afcf4679f86ac633ff12b771db007123308cd5c65520ae8329e7334b340ab9
+  metadata.gz: b222778b4e25b13fbe5e62fe694d1e5189099d8cafd7b5a15f579e3df7413aa60f43a69ee299d3a37fa312c3baf25e798a54e432ad199ec118ebd56e35b9949b
+  data.tar.gz: eacb82757bb6876272f320b6b5402a449d3954d0c39052ef4304682c00435b559b49a29379f77a9c7f34dbbf210c4b1865b59df66f19ae1a72bfb5c0050e1df7

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 1.4.0 (unreleased)
+
+### Summary
+
+New `PGN::Notation` module that *generates* Standard Algebraic Notation
+(SAN) for a single coordinate move (origin square, destination square,
+optional promotion) given the position before the move. The rest of the
+gem only *parses* SAN; this is the reverse direction, needed to render
+moves stored as coordinates (e.g. `e2`-`e4`) in standard chess notation.
+
+### Added
+- `PGN::Notation.san(position, from, to, promotion = nil)` and the
+  convenience `PGN::Notation.san_from_fen(fen, from, to, promotion = nil)`.
+  Builds full SAN: piece letter, capture (`x`), castling (`O-O`/`O-O-O`),
+  pawn capture file (`exd5`), promotion (`=Q`), legal-move disambiguation
+  (file / rank / full square, respecting pins), and check (`+`) / checkmate
+  (`#`) suffixes. Checkmate detection drives full legal-move generation for
+  the side to move (the gem's first move generator). Raise `ArgumentError`
+  if the origin square is empty.
+- New `spec/notation_spec.rb`; all 201 specs green. A round-trip harness over
+  every parseable fixture reproduces the original SAN of all 277 moves
+  exactly (including disambiguation and `+`/`#` suffixes).
+
+### Changed (parser performance)
+- `PGN::Lexer#scan_one` now dispatches on the leading byte of the next
+  token via a frozen `BYTE_DISPATCH` table (with an `ALL_RULES` fallback),
+  trying only the 1-2 rules that can match that byte instead of walking all
+  nine rules in order. Profiling had `StringScanner#scan` at ~23% of parse
+  CPU and the rule loop ~38% inclusive; the dispatch nearly halves scan time.
+- `PGN::PgnParser#next_token` mutates the lexer's `[type, value]` pair in
+  place rather than allocating a second translated pair — one array per token
+  is the Racc floor.
+- Net (500 immortal games): parse-only throughput +25% (305 → 203 ms/i),
+  parse allocations −17% (347037 → 288537 objects / 17977414 → 15640374
+  bytes), parse+replay allocations −7% (831530 → 773030 objects). Serialized
+  PGN/FEN output stays byte-identical; all 201 specs green.
+
+## 1.3.0 (2026-08-13)
+
+### Summary
+
+Replay (move-application) board-representation rewrite: `PGN::Board`
+internals move to the classic 0x88 scheme (a 128-cell array indexed by
+`rank*16+file`) and `PGN::MoveCalculator` works entirely in single-integer
+square indices, so the replay hot path no longer allocates `[file,rank]`
+coordinate arrays or square-name strings. No public API changes; serialized
+PGN/FEN output stays byte-identical.
+
+### Changed
+- **`PGN::Board`**: internals rewritten to a 0x88 array (`@cells`, 128
+  entries). The public file-major `squares` 8x8 API, `at` (string/coord
+  overloads), `update`, `change!`, `position_for`, `coordinates_for`, and
+  `dup` are preserved (computed/translated at the API boundary, off the
+  hot path). New internal 0x88 accessors `index_of`, `index_for`, `at_index`,
+  `update_index`, and `apply!` (integer-keyed batch update) serve the hot
+  path. `dup` copies the 128-cell array (cheaper than the prior column COW:
+  136 → 91 objects / 10336 → 3856 bytes per 45 dupes).
+- **`PGN::MoveCalculator`**: rewritten to address squares as 0x88 integer
+  indices throughout. `#compute_origin` returns an index; `#changes` is an
+  integer-keyed hash applied via `Board#apply!`; ray stepping (`first_piece`)
+  and off-board checks use a single integer add and the `(idx & 0x88).zero?`
+  bitmask (≈1.6x faster than a 0..7 four-integer bounds check, measured);
+  `castling_restrictions`/`en_passant_*` use integer corner indices. The
+  public `#origin` reader still returns an algebraic square string. Scan and
+  disambiguation algorithms are unchanged, so output is byte-identical.
+- **Plan B (piece-location index) — attempted, rejected**: a `piece → 0x88
+  indices` index maintained in `update`/`apply!`, used for O(1)
+  slider/leaper/king origin lookups, was implemented on top of the 0x88
+  board and passed all 182 specs, but regressed: replay 526 → 727 µs/i
+  (+38% slower), allocations 976 → 1591 objects (+63%). `Board#dup` (called
+  every move) must clone the index (≈12 piece arrays: Board#dup 91 → 676
+  objects), and every move pays per-update index maintenance that pawns —
+  the most common move type, whose origins are geometry-fixed and can't use
+  the index — pay for no benefit. The index helps move-*generation*
+  libraries (chess.js, python-chess) that enumerate all legal moves, but
+  not replay, which validates one given move where ray-scanning from the
+  destination is already cheap. Reverted; the 0x88 board alone is the
+  winner. Rationale recorded in `TODO.md`.
+- Performance vs 1.2.1 (immortal game, 45 plies; A/B batched median, 200
+  replies × 7, fresh process each): replay throughput 798 → 535 µs/i
+  (+49%); replay allocations 1571 → 976 objects (−38%) and 92440 → 62064
+  bytes (−33%). Full pipeline (`bench/profile_parse.rb`, 500 games):
+  parse+replay throughput 659 → 534 ms/i (+23%), allocations 1101586 →
+  831530 objects (−24.5%) and 62164136 → 47966112 bytes (−22.8%);
+  parse-only unchanged. 182 specs pass; byte-identical FEN/PGN output;
+  zero new rubocop offenses vs 1.2.1 (the rewrite is shorter on
+  ClassLength/AbcSize and leaves the same pre-existing metric offenses on
+  the same methods).
+
 ## 1.2.1 (2026-08-13)
 
 ### Summary

data/README.md

@@ -122,6 +122,29 @@ _ _ _ ♙ _ _ _ _
 => r1bk3r/p2pBpNp/n4n2/1p1NP2P/6P1/3P4/P1P1K3/q5b1 b - - 1 22
 ```
 
+### Generating SAN from coordinates
+
+{PGN::Notation} is the reverse of {PGN::Move}: it *builds* Standard
+Algebraic Notation for a coordinate move (origin square, destination square,
+optional promotion) given the position before the move. Use it to render
+moves stored as coordinates in standard chess notation.
+
+```
+> PGN::Notation.san(PGN::Position.start, "g1", "f3")
+=> "Nf3"
+
+> PGN::Notation.san_from_fen("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", "e2", "e4")
+=> "e4"
+
+> fen = "r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1"
+> PGN::Notation.san_from_fen(fen, "e1", "g1")
+=> "O-O"
+```
+
+It handles captures, en passant, promotions, legal-move disambiguation
+(file / rank / full square, respecting pins), and check (`+`) / checkmate
+(`#`) suffixes.
+
 ## Benchmarks
 
 A reproducible profiling harness lives in `bench/`. It measures the
@@ -169,24 +192,24 @@ Move pipeline — immortal game, 45 plies (`bench/profile_moves.rb`):
 
 | Metric | original `pgn` | pgn2 | Δ |
 |---|---:|---:|---:|
-| Replay allocations (objects) | 5124 | 1710 | -3414 (-66.7%) |
-| Replay allocations (bytes) | 262608 | 103760 | -158848 (-60.5%) |
-| `Board#dup` x45 (objects) | 451 | 136 | -315 (-69.8%) |
-| `Board#dup` x45 (bytes) | 43096 | 10336 | -32760 (-76.0%) |
+| Replay allocations (objects) | 5124 | 976 | -4148 (-80.9%) |
+| Replay allocations (bytes) | 262608 | 62064 | -200544 (-76.4%) |
+| `Board#dup` x45 (objects) | 451 | 91 | -360 (-79.8%) |
+| `Board#dup` x45 (bytes) | 43096 | 3856 | -39240 (-91.1%) |
 | `Board#at(str)` x1000 (objects) | 6000 | 0 | -6000 (-100%) |
 | `Board#at(str)` x1000 (bytes) | 240000 | 0 | -240000 (-100%) |
-| Replay throughput | 841 µs/i | 766 µs/i | ~1.10x faster |
+| Replay throughput | 841 µs/i | 517 µs/i | ~1.63x faster |
 
 Parser — 500 immortal games (`bench/profile_parse.rb`):
 
 | Metric | original `pgn` | pgn2 | Δ |
 |---|---:|---:|---:|
-| Parse-only allocations (objects) | 1248065 | 347037 | -901028 (-72.2%) |
-| Parse-only allocations (bytes) | 120370470 | 17977414 | -102393056 (-85.1%) |
-| Parse + replay allocations (objects) | 3778073 | 1170586 | -2607487 (-69.0%) |
-| Parse + replay allocations (bytes) | 249570048 | 67804136 | -181765912 (-72.8%) |
-| Parse-only throughput | 1461 ms/i | 305 ms/i | ~4.8x faster |
-| Parse + replay throughput | 1938 ms/i | 816 ms/i | ~2.4x faster |
+| Parse-only allocations (objects) | 1248065 | 288537 | -959528 (-76.9%) |
+| Parse-only allocations (bytes) | 120370470 | 15640374 | -104730096 (-87.0%) |
+| Parse + replay allocations (objects) | 3778073 | 773030 | -3005043 (-79.5%) |
+| Parse + replay allocations (bytes) | 249570048 | 45626128 | -203943920 (-81.7%) |
+| Parse-only throughput | 1461 ms/i | 203 ms/i | ~7.2x faster |
+| Parse + replay throughput | 1938 ms/i | 484 ms/i | ~4.0x faster |
 
 What changed to get there:
 
@@ -216,9 +239,42 @@ What changed to get there:
     tuple, so the parser hot path now allocates only the single `[type, value]`
     array Racc requires per token. Cuts parse allocations ~42% (603537 → 347037
     objects for 500 games).
+13. `PGN::MoveCalculator#valid_square?` — integer bounds (`file >= 0 && file < 8`)
+    instead of `(0..7).include?` (≈3.4x faster per call, zero-alloc, in the
+    board-scan inner loops); `#compute_origin` — string `case` dispatch instead
+    of regex `/[brq]/i` matches; `#first_piece` — returns only the `[file, rank]`
+    square via a `piece_at` helper instead of a `[piece, square]` tuple. Replay
+    throughput +8.2% (766 → 741 µs/i), replay allocations −8% (1710 → 1571
+    objects). Board-scanning origin lookup is ~46% of replay CPU; the
+    piece-location-index rewrite that would cut it remains deferred.
+14. `PGN::Board` / `PGN::MoveCalculator` — 0x88 board representation. `Board`
+    internals are now a 128-cell array indexed by `rank*16+file` (the classic
+    0x88 scheme), and `MoveCalculator` works entirely in single-integer square
+    indices via `Board#at_index`/`#apply!`, so the replay hot path no longer
+    allocates `[file,rank]` coordinate arrays or square-name strings.
+    Off-board is a single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a
+    0..7 bounds check) and ray stepping is a single integer add. Algorithm
+    unchanged → byte-identical output. Replay throughput +49% (798 → 517 µs/i),
+    replay allocations −38% (1571 → 976 objects) / −33% (92440 → 62064 bytes),
+    parse+replay +21% throughput. A companion piece-location index (piece →
+    0x88 indices for O(1) origin/king lookups) was implemented on top, passed
+    all specs, but *regressed* (replay 526→727 µs/i, allocations +63%): `dup`
+    must clone the index every move and every move pays maintenance that pawns
+    (the common case, geometry-fixed origins) can't use — so it was rejected
+    and reverted. The 0x88 board alone is the winner.
+15. `PGN::Lexer#scan_one` — byte-dispatch: the leading byte of the next
+    token selects the 1-2 `RULES` that can possibly match it (a frozen
+    `BYTE_DISPATCH` table; `ALL_RULES` fallback) instead of walking all nine
+    rules in order. `StringScanner#scan` was ~23% of parse CPU and the rule
+    loop ~38% inclusive; the dispatch nearly halves scan time. `PgnParser#
+    next_token` now mutates the lexer's `[type, value]` pair in place instead
+    of allocating a second translated pair (one array per token is the Racc
+    floor). Parse-only throughput +25% (305 → 203 ms/i), parse allocations
+    −17% (347037 → 288537 objects / 17977414 → 15640374 bytes for 500 games).
+    Output byte-identical.
 
 Public output (FEN, PGN) is byte-identical to the original gem; the full
-suite (182 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
+suite (201 examples) stays green. See `bench/IMPROVEMENTS.md` for the per-step
 before/after deltas that produced these tables.
 
 ## Installation

data/TODO.md

@@ -15,21 +15,33 @@
     `scan_one`'s `[type, m, discarded]` tuple to a single returned string
     (type/discarded stashed in ivars). The full `Token` is kept only for the
     `#tokens` spec helper. Parse allocations −42% (603537 → 347037 / 500 games).
-- Speed up replay via a board-representation rewrite (deferred "Approach B"):
-  per-line profiling shows the remaining replay allocations are architectural
-  — `MoveCalculator#first_piece` scan-return arrays (~5/ply, the #1 site) and
-  `Board#position_for` string joins (~3/ply). Do these as ONE coherent
-  rewrite (not separately, to avoid throwing away work):
-  (a) a piece-location index (piece → squares) so king/disambiguation/origin
-    lookups are O(1) instead of scanning 64 squares — kills `first_piece` scan
-    arrays AND the dominant replay compute (`valid_square?`/`at` ≈ 15/ply calls);
-  (b) a coordinate-only internal board (int square keys, no `"e4"` strings on
-    the hot path) — kills `position_for` strings + `changes` string keys.
-  Caveat: `change!`/`update`/`position_for`/`coordinates_for`/`squares` are
-  spec-tested public API, so the new representation must be additive (string
-  API kept). Realistic ceiling ~2× replay allocation + ~1.5–2× throughput;
-  medium-high risk (Board/MoveCalculator/Position/FEN). Only worth it given a
-  real hot-loop need (replay is already ~0.8 ms/ply).
+- Speed up replay via a board-representation rewrite ("Approach B"): done.
+  (b) ✓ (done in 1.3.0) Rewrote `Board` internals to the classic 0x88
+    representation (128-cell array indexed by `rank*16+file`) and rewrote
+    `MoveCalculator` to work entirely in single-integer square indices via
+    `Board#at_index`/`#apply!`, so the replay hot path no longer allocates
+    `[file,rank]` coordinate arrays or square-name strings. Off-board is a
+    single bitmask (`(idx & 0x88).zero?`, ~1.6x faster than a 0..7 bounds
+    check) and ray stepping is a single integer add. Algorithm unchanged, so
+    output is byte-identical. Measured (immortal game): replay 798→535 µs/i
+    (+49% throughput), allocations 1571→976 objects (−38%) / 92440→62064 bytes
+    (−33%); parse+replay +21% throughput. 182 specs green, 0 new rubocop
+    offenses vs main. The public string/coord API is preserved (additive).
+  (a) ✗ (attempted, rejected) A piece-location index (piece → 0x88 indices)
+    maintained in `update`/`apply!` and used for O(1) slider/leaper/king
+    origin lookups. Implemented on top of (b), all 182 specs green, but it
+    **regressed**: replay 526→727 µs/i (+38% slower), allocations 976→1591
+    objects (+63%). Root cause: `Board#dup` (called every move) must clone
+    the index (`transform_values(&:dup)` ≈ 12 piece arrays) — Board#dup went
+    91→676 objects — and every move pays per-update index maintenance
+    (`<<`/`delete`) that pawns (the most common move type, whose origins are
+    geometry-fixed and can't use the index) pay for no benefit. The index
+    helps sliders/leapers (minority of moves) but the dup + maintenance cost
+    is paid by every move. Conclusion: a global piece index is a loss for
+    replay (where only ONE given move is validated, so ray-scanning from the
+    destination is already cheap); it pays in move-*generation* libraries
+    (chess.js/python-chess) that enumerate ALL legal moves. Not worth a COW
+    variant either (maintenance + pawns). Reverted; (b) alone is the winner.
 - Replace the right-recursive `tag_section`/`variation_list` rules in
   `pgn_parser.y` with ordinary left-recursion plus one explicit `.reverse`
   at the point each list is consumed, so the legacy whittle-order

data/bench/baseline_moves.txt

@@ -1,12 +1,12 @@
 Workload: immortal game, 45 plies
 
 === 1. Replay allocations (45 plies, no parse) ===
-total_allocated objects: 1710
-total_allocated bytes:   103760
+total_allocated objects: 976
+total_allocated bytes:   62064
 
 === 2. Board#dup x45 (target of flat-board COW) ===
-total_allocated objects: 136
-total_allocated bytes:   10336
+total_allocated objects: 91
+total_allocated bytes:   3856
 
 === 3. Board#at(str) x1000 (target of coord-arithmetic at) ===
 total_allocated objects: 0
@@ -15,8 +15,8 @@ total_allocated bytes:   0
 === 4. Replay throughput (ips, excluding parse) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
-     replay immortal   112.000 i/100ms
+     replay immortal   193.000 i/100ms
 Calculating -------------------------------------
-     replay immortal      1.178k (± 4.6%) i/s  (848.64 μs/i) -      5.936k in   5.037516s
+     replay immortal      1.894k (± 2.9%) i/s  (528.02 μs/i) -      9.650k in   5.095389s
 
 Done. Compare this file against bench/baseline_moves.txt after optimizations.

data/bench/baseline_parse.txt

@@ -1,25 +1,25 @@
 Corpus: 500 copies of the immortal game
 
 === 1. Parse-only allocations (500 games) ===
-total_allocated objects: 347037
-total_allocated bytes:   17977414
+total_allocated objects: 288537
+total_allocated bytes:   15640374
 
 === 2. Parse + replay allocations (500 games) ===
-total_allocated objects: 1170586
-total_allocated bytes:   67804136
+total_allocated objects: 773030
+total_allocated bytes:   45626128
 
 === 3. Parse-only throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
      parse 500 games     1.000 i/100ms
 Calculating -------------------------------------
-     parse 500 games      4.086 (± 0.0%) i/s  (244.74 ms/i) -     21.000 in   5.139596s
+     parse 500 games      4.926 (±20.3%) i/s  (203.01 ms/i) -     25.000 in   5.075163s
 
 === 4. Parse + replay throughput (ips) ===
 ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
 Warming up --------------------------------------
 parse+replay 500 games     1.000 i/100ms
 Calculating -------------------------------------
-parse+replay 500 games      1.472 (± 0.0%) i/s  (679.56 ms/i) -      8.000 in   5.436470s
+parse+replay 500 games      2.065 (± 0.0%) i/s  (484.34 ms/i) -     11.000 in   5.327699s
 
 Done. Compare this file against bench/baseline_parse.txt after optimizations.

data/lib/pgn/board.rb

@@ -50,7 +50,17 @@ module PGN
       nil => '_'
     }.freeze
 
-    attr_accessor :squares
+    # 0x88 board representation (see chess.js / the classic 0x88 move-generation
+    # algorithm). A square is addressed by a single integer index
+    # `rank * 16 + file`; the extra files/ranks make off-board detection a
+    # single bitmask test -- `(idx & 0x88) != 0` -- which is faster than the
+    # four-integer comparison a 0..7 bounds check needs, and lets ray
+    # stepping be a single integer add. The public `squares` 8x8 API is built
+    # from this array on demand (it is off the replay hot path), and the
+    # MoveCalculator hot path works entirely in integer indices.
+    #
+    #   file = idx & 0x0F   (0..7)
+    #   rank = idx >> 4      (0..7)
 
     # @return [PGN::Board] a board in the starting position
     #
@@ -75,7 +85,24 @@ module PGN
     #
     def initialize(squares)
       self.squares = squares
-      @owned = Array.new(8, false)
+    end
+
+    # @return [Array<Array<String>>] the board as a file-major 8x8 array
+    #   (squares[file][rank]). Built on demand from the 0x88 array; equality
+    #   with the START constant and other boards is preserved.
+    #
+    def squares
+      (0..7).map { |f| (0..7).map { |r| @cells[(r * 16) + f] } }
+    end
+
+    def squares=(squares)
+      @cells = Array.new(128)
+      8.times do |f|
+        8.times do |r|
+          @cells[(r * 16) + f] = squares[f][r]
+        end
+      end
+      @cells
     end
 
     # @overload at(str)
@@ -91,12 +118,10 @@ module PGN
     #   board.at(4,3)  #=> "P"
     #   board.at("e4") #=> "P"
     #
-    # String squares are parsed with getbyte arithmetic (a=0x61, '1'=0x31)
-    # so the common string lookup allocates nothing.
     def at(arg0, arg1 = nil)
-      return squares[arg0][arg1] unless arg1.nil?
+      return @cells[(arg1 * 16) + arg0] unless arg1.nil?
 
-      squares[file_of(arg0)][rank_of(arg0)]
+      @cells[(rank_of(arg0) * 16) + file_of(arg0)]
     end
 
     # @param changes [Hash<String, <String, nil>>] changes to make to the board
@@ -105,9 +130,7 @@ module PGN
     #   board.change!({"e2" => nil, "e4" => "P"})
     #
     def change!(changes)
-      changes.each do |square, piece|
-        update(square, piece)
-      end
+      changes.each { |square, piece| update(square, piece) }
       self
     end
 
@@ -117,16 +140,8 @@ module PGN
     # @example
     #   board.update("e4", "P")
     #
-    # Copy-on-write: clone only the column being mutated, and only once per
-    # instance, so unchanged columns stay shared with any board this one was
-    # duped from.
     def update(square, piece)
-      file = file_of(square)
-      unless @owned[file]
-        squares[file] = squares[file].dup
-        @owned[file] = true
-      end
-      squares[file][rank_of(square)] = piece
+      @cells[(rank_of(square) * 16) + file_of(square)] = piece
       self
     end
 
@@ -146,9 +161,7 @@ module PGN
     #
     def position_for(coordinates)
       file, rank = coordinates
-      file_chr = INDEX_TO_FILE[file]
-      rank_chr = INDEX_TO_RANK[rank]
-      [file_chr, rank_chr].join('')
+      INDEX_TO_FILE[file] + INDEX_TO_RANK[rank]
     end
 
     # @return [String] the board in human readable format with unicode
@@ -160,12 +173,66 @@ module PGN
       end.join("\n")
     end
 
-    # @return [PGN::Board] a copy of self. The outer array is copied; the
-    # 8 column arrays are shared and cloned lazily by #update on first
-    # mutation (copy-on-write).
+    # @return [PGN::Board] a copy of self. Copies the 128-cell 0x88 array;
+    #   mutations to the copy do not affect the original.
     #
     def dup
-      PGN::Board.new(squares.dup)
+      copy = PGN::Board.allocate
+      copy.instance_variable_set(:@cells, @cells.dup)
+      copy
+    end
+
+    # -- 0x88 hot-path API (integer indices) ---------------------------------
+
+    # The 0x88 index of an algebraic square name.
+    #
+    # @param square [String] e.g. "e4"
+    # @return [Integer] idx = rank * 16 + file
+    #
+    def index_of(square)
+      (rank_of(square) * 16) + file_of(square)
+    end
+
+    # The 0x88 index of zero-indexed file/rank coordinates.
+    #
+    # @return [Integer] idx = rank * 16 + file
+    #
+    def index_for(file, rank)
+      (rank * 16) + file
+    end
+
+    # Looks up a piece by 0x88 index. The caller is responsible for having
+    # already verified the index is on-board (`(idx & 0x88).zero?`); reading
+    # an off-board index simply returns nil.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @return [String, nil] the piece on that square
+    #
+    def at_index(idx)
+      @cells[idx]
+    end
+
+    # Places a piece on a 0x88 index. Returns self.
+    #
+    # @param idx [Integer] a 0x88 square index
+    # @param piece [String, nil]
+    # @return [self]
+    #
+    def update_index(idx, piece)
+      @cells[idx] = piece
+      self
+    end
+
+    # Applies a batch of integer-indexed changes. The replay hot path uses
+    # this so it never allocates square-name strings or `[file, rank]`
+    # coordinate arrays.
+    #
+    # @param changes [Hash<Integer, <String, nil>>]
+    # @return [self]
+    #
+    def apply!(changes)
+      changes.each { |idx, piece| @cells[idx] = piece }
+      self
     end
 
     private

data/lib/pgn/lexer.rb

@@ -117,6 +117,39 @@ module PGN
       [:tag_name,         TAG_NAME,         false]
     ].freeze.each(&:freeze)
 
+    # Byte-dispatch table: maps the leading byte of the next token to the
+    # ordered list of RULES indices that could possibly match it. This lets
+    # {#scan_one} try one or two regexes for the common tokens instead of
+    # walking all nine rules in order (StringScanner#scan was ~23% of parse
+    # CPU and the rule loop ~38% inclusive per profiling). The order within
+    # each list mirrors RULES, so tokenization is byte-compatible with the
+    # linear scan. Indices: 0 wsp, 1 pgn_comment, 2 game_termination,
+    # 3 san_move, 4 move_number, 5 nag, 6 comment, 7 string, 8 tag_name.
+    BYTE_DISPATCH = begin
+      h = {
+        9 => [0], 10 => [0], 11 => [0], 12 => [0], 13 => [0], 32 => [0], # whitespace
+        37 => [1],                                            # % pgn_comment
+        42 => [2],                                            # * game_termination
+        34 => [7],                                            # " string
+        123 => [6],                                           # { comment
+        36 => [5], 63 => [5], 33 => [5], # $ ? ! nag
+        48 => [2, 3, 4, 8], 49 => [2, 4, 8], # 0, 1 (term/castle/num/tag)
+        95 => [8] # _ tag_name
+      }
+      (50..57).each { |b| h[b] = [4, 8] }                  # 2..9 move_number/tag_name
+      [66, 75, 78, 79, 81, 82].each { |b| h[b] = [3, 8] }  # B K N O Q R san_move/tag
+      (97..104).each { |b| h[b] = [3, 8] }                 # a-h pawn san_move/tag
+      # other tag_name letters
+      ((65..90).to_a + (105..122).to_a - [66, 75, 78, 79, 81, 82]).each do |b|
+        h[b] = [8]
+      end
+      h.each_value(&:freeze)
+      h.freeze
+    end
+
+    # Fallback for bytes not in BYTE_DISPATCH: try every rule in order.
+    ALL_RULES = (0...RULES.length).to_a.freeze
+
     # Single-character literals, matched by their byte value: [type, frozen value].
     LITERAL_BYTES = {
       91 => [:lbracket, '['], # [
@@ -185,14 +218,17 @@ module PGN
     # Try each terminal rule in order; return the matched string for the
     # first match (stashing its type and discarded flag in +@scan_type+ /
     # +@scan_discarded+ so the caller avoids allocating a 3-element tuple),
-    # or raise if nothing matches at the current position.
+    # or raise if nothing matches at the current position. Uses
+    # {BYTE_DISPATCH} to try only the rules that can match the leading byte.
     def scan_one
-      RULES.each do |(type, re, discarded)|
-        if (m = @ss.scan(re))
-          @scan_type = type
-          @scan_discarded = discarded
-          return m
-        end
+      indices = BYTE_DISPATCH[@input.getbyte(@ss.pos)] || ALL_RULES
+      indices.each do |i|
+        type, re, discarded = RULES[i]
+        next unless (m = @ss.scan(re))
+
+        @scan_type = type
+        @scan_discarded = discarded
+        return m
       end
       raise UnconsumedInputError,
             "Unmatched input #{@input.byteslice(@ss.pos..).inspect} on line #{@line}"