@slugbugblue/trax 1.1.1 → 1.3.0

package/src/engine.js

@@ -1,8 +1,9 @@
-/** Trax engine.
- * @copyright 2019-2026
- * @author Chad Transtrum <chad@transtrum.net>
- * @license Apache-2.0
- */
+/**
+Trax engine.
+@copyright 2019-2026
+@author Chad Transtrum <chad@transtrum.net>
+@license Apache-2.0
+*/
 
 /** @import { PointLike } from '@slugbugblue/point' */
 import { Point } from '@slugbugblue/point'
@@ -14,63 +15,64 @@ import { version } from './version.js'
 /** @typedef {'w' | 'b'} Color */
 
 /**
- * One end of a line and the tiles taken to get there.
- * @typedef {Object} LineEnd
- * @property {Point} loc
- * @property {TileId[]} path
- */
+One end of a line and the tiles taken to get there.
+@typedef {object} LineEnd
+@property {Point} loc - the ending location
+@property {TileId[]} path - tile ids from start to end
+*/
 
 /** A notation of a move. */
 /** @typedef {string} Notation */
 
 /**
- * A tile type and a location determine a raw move.
- * @typedef {Object} RawMove
- * @property {TileType} type
- * @property {Point} loc
- */
+A tile type and a location determine a raw move.
+@typedef {object} RawMove
+@property {TileType} type - the tile type
+@property {Point} loc - the location
+*/
 
 /**
- * Treat the save state as an opaque object,
- * produced by save() and fed into restore().
- * @typedef {Object} SaveState
- * @property {string} id
- * @property {number} move
- * @property {number} turn
- * @property {boolean} over
- * @property {number} left
- * @property {number} right
- * @property {number} top
- * @property {number} bottom
- * @property {Notation} notation
- * @property {string} tiles
- * @property {string} path
- * @property {boolean} invalid
- */
+Treat the save state as an opaque object,
+produced by save() and fed into restore().
+@typedef {object} SaveState
+@property {string} id - game id
+@property {number} move - move number
+@property {number} turn - current player (1 or 2)
+@property {boolean} over - whether the game is over
+@property {number} left - leftmost tile column
+@property {number} right - rightmost tile column
+@property {number} top - topmost tile row
+@property {number} bottom - bottommost tile row
+@property {string[]} moves - move notations
+@property {[TileId, Point][]} frontier - frontier locations
+@property {string} tiles - serialized tiles
+@property {string} path - serialized winning path
+@property {boolean} invalid - whether an invalid tile was placed
+*/
 
 /** Representations of the different ways a tile can curve. */
 /** @typedef {'/' | '\\' | '+'} Slash */
 
 /**
- * A single tile on the board.
- * @typedef {Object} Tile
- * @property {TileId} id
- * @property {Point} loc
- * @property {TileType} type
- * @property {number} move
- * @property {number} seq
- */
+A single tile on the board.
+@typedef {object} Tile
+@property {TileId} id - unique tile identifier
+@property {Point} loc - board location
+@property {TileType} type - tile type letter
+@property {number} move - move number when placed
+@property {number} seq - sequence number among all tiles
+*/
 
 /** A TileId is just a string. */
 /** @typedef {string} TileId */
 
 /**
- * When a tile is dropped, this object represents the results.
- * @typedef {Object} TileDrop
- * @property {Tile[]} dropped
- * @property {Notation} notation
- * @property {boolean} valid
- */
+When a tile is dropped, this object represents the results.
+@typedef {object} TileDrop
+@property {Tile[]} dropped - all tiles placed, including forced moves
+@property {Notation} notation - the notation of the played move
+@property {boolean} valid - whether the move was legal
+*/
 
 /** Invalid tiles are represented by 'x'. */
 /** @typedef {ValidTiles | 'x'} TileType */
@@ -84,34 +86,37 @@ import { version } from './version.js'
 // Fun trax helper constants
 
 const zero = new Point(0, 0)
-const moveNumberRegex = /^(\d+)[.):]?$/
-const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
-
-/** Tiles are represented by the letters a-f.
- *     a         b        c        d        e        f
- *  +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
- *  |   # |   |  #  |  | #   |  | o   |  |  o  |  |   o |
- *  oo   ##   ooo#ooo  ##   oo  oo   ##  #######  ##   oo
- *  | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
- *  +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
- *
- * @readonly
- * @type ValidTiles[]
- * */
+const moveNumberRegex = /^\d+[\).:]?$/v
+const notationRegex = /^(?<col>[@a-z]+)(?<row>\d+)(?<slash>[+\/\\])$/iv
+
+/**
+Tiles are represented by the letters a-f.
+    a         b        c        d        e        f
+ +--#--+   +--#--+  +--#--+  +--o--+  +--o--+  +--o--+
+ |   # |   |  #  |  | #   |  | o   |  |  o  |  |   o |
+ oo   ##   ooo#ooo  ##   oo  oo   ##  #######  ##   oo
+ | o   |   |  #  |  |   o |  |   # |  |  o  |  | #   |
+ +--o--+   +--#--+  +--o--+  +--#--+  +--o--+  +--#--+
+
+@readonly
+@type {ValidTiles[]}
+*/
 const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
 
-/** Slashes indicate the direction the tile is placed. A forward slash or a
- * backslash indicate the tile is a "curve" and the plus sign indicates the
- * tile is a "straight".
- * @readonly
- * @type {Record<ValidTiles, Slash>}
- */
+/**
+Slashes indicate the direction the tile is placed. A forward slash or a
+backslash indicate the tile is a "curve" and the plus sign indicates the
+tile is a "straight".
+@readonly
+@type {Record<ValidTiles, Slash>}
+*/
 const slash = { a: '\\', b: '+', c: '/', d: '/', e: '+', f: '\\' }
 
-/** Symmetry helper to convert from one tile to another.
- * @readonly
- * @type {Record<string, Record<ValidTiles, ValidTiles>>}
- */
+/**
+Symmetry helper to convert from one tile to another.
+@readonly
+@type {Record<string, Record<ValidTiles, ValidTiles>>}
+*/
 const symmetry = {
   // Convert tile to different views
   flip: { a: 'd', b: 'b', c: 'f', d: 'a', e: 'e', f: 'c' },
@@ -122,14 +127,24 @@ const symmetry = {
 
 // Fun trax helper functions
 
-/** Apply certain combinations of symmetry.
- * @arg {ValidTiles} tile - the tile to apply symmetry to
- * @arg {boolean} [rightToLeft] - mirror the tile
- * @arg {boolean} [bottomToTop] - flip the tile
- * @arg {boolean} [rotate] - rotate the tile counterclockwise
- * @returns {ValidTiles}
- */
-const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
+/**
+Symmetry options for viewing a position from different angles.
+@typedef {object} SymmetryOptions
+@property {boolean} [rightToLeft] - mirror the tile
+@property {boolean} [bottomToTop] - flip the tile
+@property {boolean} [rotate] - rotate the tile counterclockwise
+@property {boolean} [colorSwap] - swap the tile's colors
+*/
+
+/**
+Apply certain combinations of symmetry.
+@param {ValidTiles} tile - the tile to apply symmetry to
+@param {SymmetryOptions} [options] - the symmetry to apply
+@returns {ValidTiles} the transformed tile
+*/
+const applySymmetry = (tile, options = {}) => {
+  const { rightToLeft, bottomToTop, rotate, colorSwap } = options
+  if (colorSwap) tile = symmetry.swap[tile]
   if (rightToLeft) tile = symmetry.mirror[tile]
   if (bottomToTop) tile = symmetry.flip[tile]
   if (rotate) tile = symmetry.counterclock[tile]
@@ -138,38 +153,43 @@ const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
 
 // Note: String(undefined) === 'undefined', which is never a valid tile letter,
 // so these functions correctly return false when t is undefined.
-/** The color at the top of the tile.
- * @arg {string | undefined} t - the tile to check
- * @returns {Color|false} the color or false if t is not a valid tile
- */
+/**
+The color at the top of the tile.
+@param {string | undefined} t - the tile to check
+@returns {Color|false} the color or false if t is not a valid tile
+*/
 const upColor = (t) =>
   'abc'.includes(String(t)) ? 'b' : 'def'.includes(String(t)) ? 'w' : false
 
-/** The color at the bottom of the tile.
- * @arg {string | undefined} t - the tile to check
- * @returns {Color|false} the color or false if t is not a valid tile
- */
+/**
+The color at the bottom of the tile.
+@param {string | undefined} t - the tile to check
+@returns {Color|false} the color or false if t is not a valid tile
+*/
 const downColor = (t) =>
   'bdf'.includes(String(t)) ? 'b' : 'ace'.includes(String(t)) ? 'w' : false
 
-/** The color at the right edge of the tile.
- * @arg {string | undefined} t - the tile to check
- * @returns {Color|false} the color or false if t is not a valid tile
- */
+/**
+The color at the right edge of the tile.
+@param {string | undefined} t - the tile to check
+@returns {Color|false} the color or false if t is not a valid tile
+*/
 const rightColor = (t) =>
   'ade'.includes(String(t)) ? 'b' : 'bcf'.includes(String(t)) ? 'w' : false
 
-/** The color at the left edge of the tile.
- * @arg {string | undefined} t - the tile to check
- * @returns {Color|false} the color or false if t is not a valid tile
- */
+/**
+The color at the left edge of the tile.
+@param {string | undefined} t - the tile to check
+@returns {Color|false} the color or false if t is not a valid tile
+*/
 const leftColor = (t) =>
   'cef'.includes(String(t)) ? 'b' : 'abd'.includes(String(t)) ? 'w' : false
 
-/** Add an empty space to the position encoding string.
- * @arg {string} code - The position encoding string
- * @returns {string}
- */
+/**
+Add an empty space to the position encoding string.
+@param {string} code - the position encoding string
+@returns {string} the updated encoding with a blank appended
+*/
 const addBlank = (code) => {
   // Encode missing tiles as digits 0-9, for 1-10 missing
   const lastNumber = /** @type {number} */ (code.codePointAt(code.length - 1)) // Undefined if code is empty, which is ok
@@ -181,12 +201,13 @@ const addBlank = (code) => {
 }
 
 // Ugh, this is a dirty little function to get
-/** The length of an encoded position row.
- * @arg {string} row - the encoded row
- * @returns {number} - the actual length of the row
- */
+/**
+The length of an encoded position row.
+@param {string} row - the encoded row
+@returns {number} the actual length of the row
+*/
 const codeRowLength = (row) =>
-  row.replaceAll(/\d/g, (n) => '.'.repeat(Number(n) + 1)).length
+  row.replaceAll(/\d/gv, (n) => '.'.repeat(Number(n) + 1)).length
 
 // This is where the magic happens
 /** A digital representation of a Trax game. */
@@ -194,7 +215,10 @@ export class Trax {
   // Static class properties
   /** @readonly */
   static version = version
-  /** @readonly @type {Record<TraxVariant, string>} */
+  /**
+  @readonly
+  @type {Record<TraxVariant, string>}
+  */
   static names = {
     trax: 'Trax',
     traxloop: 'Loop Trax',
@@ -203,43 +227,48 @@ export class Trax {
   /** @readonly */
   static variants = new Set(Object.keys(this.names)) // Known variants
   // Static class methods
-  /** Create an x,y Point object with special functions.
-   * @arg {number|PointLike} x - either the x value, or an object with x,y keys
-   * @arg {number} [y] - if x is a number, y must be provided as well
-   * @returns {Point} a new Point object
-   */
+  /**
+  Create an x,y Point object with special functions.
+  @param {number|PointLike} x - either the x value, or an object with x,y keys
+  @param {number} [y] - if x is a number, y must be provided as well
+  @returns {Point} a new Point object
+  */
   static point = (x, y) => new Point(x, y)
-  /** Given a player number, get the color.
-   * @arg {number} playerNumber - the player number, 1 or 2
-   * @returns {Color} the color of that player, w or b
-   */
+  /**
+  Given a player number, get the color.
+  @param {number} playerNumber - the player number, 1 or 2
+  @returns {Color} the color of that player, w or b
+  */
   static colorOf = (playerNumber) => {
     /** @type {Record<number, Color>} */
     const map = { 1: 'w', 2: 'b' }
     return map[playerNumber]
   }
-  /** Given a color, get the player number.
-   * @arg {string} color - the color, w or b
-   * @returns {number} the player number, 1 or 2
-   */
+  /**
+  Given a color, get the player number.
+  @param {string} color - the color, w or b
+  @returns {number} the player number, 1 or 2
+  */
   static playerNumber = (color) => {
     /** @type {Record<string, number>} */
     const map = { b: 2, w: 1 }
     return map[color]
   }
-  /** Given a color, get the other color.
-   * @arg {string} color - the color, w or b
-   * @returns {Color} the other color, b or w
-   */
+  /**
+  Given a color, get the other color.
+  @param {string} color - the color, w or b
+  @returns {Color} the other color, b or w
+  */
   static other = (color) => {
     /** @type {Record<string, Color>} */
     const map = { b: 'w', w: 'b' }
     return map[color]
   }
-  /** Encode a numeric column number into the Trax notation column letter.
-   * @arg {number} col - the colum number, with 0 just to the left of the tiles
-   * @returns {string} the encoded column letter
-   */
+  /**
+  Encode a numeric column number into the Trax notation column letter.
+  @param {number} col - the column number, with 0 just to the left of the tiles
+  @returns {string} the encoded column letter
+  */
   static encodeCol = (col) => {
     // For notation purposes: 0 -> @, 6 -> F, 28 -> AB
     let n = ''
@@ -250,10 +279,11 @@ export class Trax {
 
     return n || '@'
   }
-  /** Decode a Trax notation column letter back to a number.
-   * @arg {string} col - the Trax column letter
-   * @returns {number} the column number
-   */
+  /**
+  Decode a Trax notation column letter back to a number.
+  @param {string} col - the Trax column letter
+  @returns {number} the column number
+  */
   static decodeCol = (col) => {
     // Turn letters back into numbers
     col = col.toUpperCase()
@@ -268,26 +298,30 @@ export class Trax {
   }
 
   // Trax class constructor
-  /** Create a new Trax game
-   * @arg {TraxVariant} [rules='trax'] - the variant to play
-   * @arg {string|string[]} [moves=''] - the initial moves to pre-play
-   * @arg {string} [id='trax'] - an id used to differentiate tiles from multiple games
-   */
+  /**
+  Create a new Trax game
+  @param {TraxVariant} [rules='trax'] - the variant to play
+  @param {string|string[]} [moves=''] - the initial moves to pre-play
+  @param {string} [id='trax'] - an id used to differentiate tiles from multiple games
+  */
   constructor(rules = 'trax', moves = '', id = 'trax') {
     if (!Trax.variants.has(rules)) rules = 'trax'
     this.id = String(id)
     this.rules = rules
-    this.move = 0
     this.turn = 1
     this.over = false
     this.left = 1
     this.right = 0
     this.top = 1
     this.bottom = 0
-    this.notation = ''
+    this.count = 0
+    /** @type {string[]} */
+    this.moves = []
+    /** @type {Map<TileId, Point>} */
+    this.frontier = new Map()
     /** @type {Record<TileId, Tile>} */
     this.tiles = {}
-    /** @type TileId[] */
+    /** @type {TileId[]} */
     this.path = []
     this.invalid = false
     // Moves might be a notation string
@@ -296,10 +330,130 @@ export class Trax {
     }
   }
 
-  /** Save the current game data to a variable.
-   * @returns {SaveState} an opaque save state object
-   * @see restore for restoring the state
-   */
+  /**
+  Find the position code with the lowest sort order across all 8
+  combinations of mirroring, flipping, and rotating.
+  @param {boolean} [colorSwap] - swap tile colors before comparing
+  @returns {string} the minimal encoded position code
+  */
+  #minimalCode(colorSwap) {
+    let min = 'z'
+    const bools = [true, false]
+    for (const rightToLeft of bools) {
+      for (const bottomToTop of bools) {
+        for (const rotate of bools) {
+          const code = this.#encodePosition({
+            rightToLeft,
+            bottomToTop,
+            rotate,
+            colorSwap,
+          })
+          if (code < min) min = code
+        }
+      }
+    }
+
+    return min
+  }
+
+  /**
+  Encode a single tile for a position code: apply symmetry, highlight it if
+  it's part of the winning path, and highlight it if it was just dropped.
+  @param {ValidTiles} tile - the tile to encode
+  @param {Point} loc - the tile's location
+  @param {SymmetryOptions & {drops?: TileDrop}} options - the symmetry and
+  drop-highlighting options
+  @returns {string} the encoded tile
+  */
+  #encodeTile(tile, loc, options) {
+    const { colorSwap, drops } = options
+    /** @type {string} */
+    let encoded = applySymmetry(tile, options)
+    if (this.path.includes(this.tileId(loc))) {
+      // `this.turn` is whoever's winning path is highlighted (or 0 for a
+      // tie); canonicalizing colors also canonicalizes that turn, since a
+      // swapped black winner is presented as white.
+      const pathTurn =
+        colorSwap && this.turn
+          ? Trax.playerNumber(Trax.other(Trax.colorOf(this.turn)))
+          : this.turn
+      encoded = String.fromCodePoint(
+        /** @type {number} */ (encoded.codePointAt(0)) + pathTurn * 6,
+      )
+    }
+
+    if (drops?.dropped?.some((t) => loc.eq(t.loc))) {
+      encoded = encoded.toUpperCase()
+    }
+
+    return encoded
+  }
+
+  /**
+  Encode a position, applying optional symmetrical operations on it. Backs
+  both the public, color-blind `positionCode()` and the color-swap-aware
+  `#minimalCode()` used by `canonical`.
+  @param {SymmetryOptions & {drops?: TileDrop}} options - reverse order
+  horizontally/vertically, rotate the tiles by 90 degrees, swap tile colors,
+  and/or highlight the drops of the most recent play
+  @returns {string} an encoding of the position
+  */
+  #encodePosition(options) {
+    const { rightToLeft, bottomToTop, rotate } = options
+    const startX = rightToLeft ? this.right : this.left
+    const startY = bottomToTop ? this.bottom : this.top
+    const incX = rightToLeft ? -1 : 1
+    const incY = bottomToTop ? -1 : 1
+    const code = []
+    let line = ''
+    let x = startX
+    let y = startY
+    do {
+      const loc = new Point(x, y)
+      const tile = this.tileAt(loc) // Normal tile for normal orientation
+      if (tile) {
+        line += this.#encodeTile(tile, loc, options)
+      } else {
+        line = addBlank(line)
+      }
+
+      if (rotate) {
+        // Increment y more often than x
+        y += incY
+        if (y < this.top || y > this.bottom) {
+          y = startY
+          x += incX
+          // Remove final number and add to code
+          code.push(line.replace(/\d$/v, ''))
+          line = ''
+        }
+      } else {
+        // This is the standard order
+        x += incX
+        if (x < this.left || x > this.right) {
+          x = startX
+          y += incY
+          // Remove final number and add to code
+          code.push(line.replace(/\d$/v, ''))
+          line = ''
+        }
+      }
+    } while (
+      x >= this.left &&
+      x <= this.right &&
+      y >= this.top &&
+      y <= this.bottom
+    )
+
+    if (rotate) code.reverse()
+    return code.join(':')
+  }
+
+  /**
+  Save the current game data to a variable.
+  @returns {SaveState} an opaque save state object
+  @see restore for restoring the state
+  */
   save() {
     // In order to evaluate potential moves, we have to modify the state
     return {
@@ -311,28 +465,30 @@ export class Trax {
       right: this.right,
       top: this.top,
       bottom: this.bottom,
-      notation: this.notation,
+      moves: [...this.moves],
+      frontier: this.frontier.entries().toArray(),
       tiles: JSON.stringify(this.tiles),
       path: JSON.stringify(this.path),
       invalid: this.invalid,
     }
   }
 
-  /** Restore a previously saved position.
-   * @arg {SaveState} saved - the previously saved state
-   * @see save for saving the state
-   */
+  /**
+  Restore a previously saved position.
+  @param {SaveState} saved - the previously saved state
+  @see save for saving the state
+  */
   restore(saved) {
     // So we need to be able to restore it when we are done
     this.id = saved.id
-    this.move = saved.move
     this.turn = saved.turn
     this.over = saved.over
     this.left = saved.left
     this.right = saved.right
     this.top = saved.top
     this.bottom = saved.bottom
-    this.notation = saved.notation
+    this.moves = [...saved.moves]
+    this.frontier = new Map(saved.frontier)
     this.tiles = JSON.parse(saved.tiles)
     this.path = JSON.parse(saved.path)
     this.invalid = saved.invalid
@@ -340,6 +496,68 @@ export class Trax {
     for (const tile of Object.values(this.tiles)) {
       tile.loc = new Point(tile.loc)
     }
+
+    this.count = Object.keys(this.tiles).length
+  }
+
+  /**
+  Lightweight checkpoint for internal rollback. Valid only for ancestor restores.
+  Callers must be in a non-over, valid game state — rewind() restores those
+  fields to those fixed values rather than saving and restoring them.
+  @returns {Checkpoint} a lightweight snapshot of mutable board dimensions
+  @typedef {{ move: number, count: number, turn: number, left: number, right: number, top: number, bottom: number }} Checkpoint
+  */
+  checkpoint() {
+    return {
+      move: this.move,
+      count: this.count,
+      turn: this.turn,
+      left: this.left,
+      right: this.right,
+      top: this.top,
+      bottom: this.bottom,
+    }
+  }
+
+  /**
+  Rewind to a checkpoint. Only valid for ancestor restores.
+  @param {Checkpoint} cp - the checkpoint to rewind to
+  */
+  rewind(cp) {
+    this.count = cp.count
+    this.moves.length = cp.move
+    this.turn = cp.turn
+    this.left = cp.left
+    this.right = cp.right
+    this.top = cp.top
+    this.bottom = cp.bottom
+    this.over = false
+    this.invalid = false
+    this.path = []
+    /** @type {Tile[]} */
+    const deleted = []
+    for (const [key, tile] of Object.entries(this.tiles)) {
+      if (tile.move <= cp.move) continue
+      deleted.push(tile)
+      delete this.tiles[key]
+    }
+
+    for (const tile of deleted) {
+      if (tile.loc.around.some((adjacent) => this.tileAt(adjacent))) {
+        this.frontier.set(tile.id, tile.loc)
+      }
+
+      for (const neighbor of tile.loc.around) {
+        const neighborId = this.tileId(neighbor)
+        if (
+          !this.tileAt(neighbor) &&
+          this.frontier.has(neighborId) &&
+          neighbor.around.every((adjacent) => !this.tileAt(adjacent))
+        ) {
+          this.frontier.delete(neighborId)
+        }
+      }
+    }
   }
 
   /** The name of this variant. */
@@ -347,9 +565,9 @@ export class Trax {
     return Trax.names[this.rules]
   }
 
-  /** The number of tiles currently in play. */
-  get count() {
-    return Object.keys(this.tiles).length
+  /** The move number of the last-played move. */
+  get move() {
+    return this.moves.length
   }
 
   /** The color of the current player, w or b. */
@@ -367,21 +585,23 @@ export class Trax {
     return this.over ? this.turn : false
   }
 
-  /** Provides the tile ID for the tile at the given location.
-   * @arg {PointLike} loc
-   * returns {TileId}
-   */
+  /**
+  Provides the tile ID for the tile at the given location.
+  @param {PointLike} loc - the location
+  @returns {TileId} a string key encoding this game's id and the location
+  */
   tileId(loc) {
     return this.id + '-' + String(loc.x) + 'x' + String(loc.y)
   }
 
-  /** Add a tile to the board. Note that no validity checking is done here,
-   * except that invalid tiles are not actually placed on the board, so this
-   * should only be called externally.
-   * @arg {TileType} type
-   * @arg {Point} loc
-   * @returns {Tile} the tile placed on the board.
-   */
+  /**
+  Add a tile to the board. Note that no validity checking is done here,
+  except that invalid tiles are not actually placed on the board, so this
+  should only be called externally.
+  @param {TileType} type - letter 'a'-'f' for valid tiles, 'x' for invalid
+  @param {Point} loc - the location
+  @returns {Tile} the tile placed on the board
+  */
   addTile(type, loc) {
     const id = this.tileId(loc)
     /** @type {Tile} */
@@ -390,6 +610,15 @@ export class Trax {
       this.invalid = true // Invalid tile is being played
     } else {
       this.tiles[id] = tile
+      this.count++
+      this.frontier.delete(id)
+      for (const neighbor of loc.around) {
+        const neighborId = this.tileId(neighbor)
+        if (!Object.hasOwn(this.tiles, neighborId)) {
+          this.frontier.set(neighborId, neighbor)
+        }
+      }
+
       this.left = Math.min(this.left, loc.x)
       this.right = Math.max(this.right, loc.x)
       this.top = Math.min(this.top, loc.y)
@@ -399,19 +628,21 @@ export class Trax {
     return tile
   }
 
-  /** The type of tile at the given location.
-   * @arg {PointLike} loc - the location the tile is in
-   * @returns {ValidTiles|undefined} the type of tile, or undefined if no tile
-   */
+  /**
+  The type of tile at the given location.
+  @param {PointLike} loc - the location the tile is in
+  @returns {ValidTiles|undefined} the type of tile, or undefined if no tile
+  */
   tileAt(loc) {
     return /** @type {ValidTiles | undefined} */ (
       (this.tiles[this.tileId(loc)] || {}).type
     )
   }
 
-  /** Is this tile valid?
-   * @type {(type: string, loc: Point) => type is ValidTiles}
-   */
+  /**
+  Is this tile valid?
+  @type {(type: string, loc: Point) => type is ValidTiles}
+  */
   validTile(type, loc) {
     if (this.count === 0 && loc.x === 0 && loc.y === 0) {
       return type === 'd' || type === 'e'
@@ -430,16 +661,22 @@ export class Trax {
     )
   }
 
-  /** Get a list of possible tiles that can be played in this location.
-   * @arg {Point} loc - the location to check
-   * @arg {string | boolean} s=false - if provided, a direction modifier, '/', '\\', or '+'
-   * @returns {TileType[]}
-   */
-  possibleTiles(loc, s = false) {
-    /** @type TileType[] */
+  /**
+  Get a list of possible tiles that can be played in this location.
+  @param {Point} loc - the location to check
+  @param {string} [slashFilter] - if provided, a direction modifier, '/', '\\', or '+'
+  @returns {TileType[]} the list of valid tile types for this location
+  */
+  possibleTiles(loc, slashFilter) {
+    /** @type {TileType[]} */
     const possibles = []
     for (const t of tileTypes) {
-      if ((!s || s === slash[t]) && this.validTile(t, loc)) possibles.push(t)
+      if (
+        (!slashFilter || slashFilter === slash[t]) &&
+        this.validTile(t, loc)
+      ) {
+        possibles.push(t)
+      }
     }
 
     return possibles
@@ -453,10 +690,11 @@ export class Trax {
     return this.right - this.left + 1
   }
 
-  /** Determine if a location is valid to play in.
-   * @arg {Point} loc - the location to check
-   * @returns {boolean}
-   */
+  /**
+  Determine if a location is valid to play in.
+  @param {Point} loc - the location to check
+  @returns {boolean} true if a tile can be placed here
+  */
   validLocation(loc) {
     if (this.over) return false
     if (this.tileAt(loc)) return false
@@ -478,29 +716,23 @@ export class Trax {
     return false
   }
 
-  /** Find all possible locations to play in. Note that these are not
-   * necessarily valid locations, just empty ones that border existing tiles.
-   */
+  /**
+  Find all possible locations to play in. Note that these are not
+  necessarily valid locations, just empty ones that border existing tiles.
+  @returns {Point[]} all frontier locations
+  */
   possibleLocations() {
     if (this.count === 0) return [zero]
-    /** @type Record<TileId, Point> */
-    const possibles = {}
-
-    for (const tile of Object.values(this.tiles)) {
-      for (const loc of tile.loc.around) {
-        const id = this.tileId(loc)
-        if (!(id in this.tiles)) possibles[id] = loc
-      }
-    }
-
-    return Object.values(possibles)
+    return this.frontier.values().toArray()
   }
 
-  /** Find all possible moves as a list of notations,
-   * ie: ['@1+', '@1/', '@1\\', ...]
-   *
-   * Note that moves are not guaranteed to be valid.
-   */
+  /**
+  Find all possible moves as a list of notations,
+  ie: ['@1+', '@1/', '@1\\', ...]
+
+  Note that moves are not guaranteed to be valid.
+  @returns {string[]} all valid move notations from the current position
+  */
   possibleMoves() {
     /** @type {string[]} */
     const possibles = []
@@ -515,10 +747,11 @@ export class Trax {
     return possibles
   }
 
-  /** Called after a move was just played, to determine the forced moves.
-   * @arg {Point} loc - the location just played at
-   * @returns {Tile[]} a list of tiles that should be added as part of the move
-   */
+  /**
+  Called after a move was just played, to determine the forced moves.
+  @param {Point} loc - the location just played at
+  @returns {Tile[]} a list of tiles that should be added as part of the move
+  */
   forcedMoves(loc) {
     /** @type {Tile[]} */
     const forced = []
@@ -536,7 +769,7 @@ export class Trax {
         } else if (possibles.length === 0) {
           // No possible moves at all
           const invalid = this.addTile('x', pos)
-          if (!invalids[invalid.id]) forced.push(invalid)
+          if (!Object.hasOwn(invalids, invalid.id)) forced.push(invalid)
           invalids[invalid.id] = true
         }
       }
@@ -545,12 +778,13 @@ export class Trax {
     return forced
   }
 
-  /** Determine the notation for a move. Note that this must be determined
-   * BEFORE the move is placed on the board.
-   * @arg {ValidTiles} type - the tile placed on the board
-   * @arg {Point} loc - the location the tile is placed
-   * @returns {string} the notation of the move
-   */
+  /**
+  Determine the notation for a move. Note that this must be determined
+  BEFORE the move is placed on the board.
+  @param {ValidTiles} type - the tile placed on the board
+  @param {Point} loc - the location the tile is placed
+  @returns {string} the notation of the move
+  */
   notate(type, loc) {
     let notation = Trax.encodeCol(loc.x - this.left + 1)
     notation += String(loc.y - this.top + 1)
@@ -558,33 +792,35 @@ export class Trax {
     return notation
   }
 
-  /** Turn a move notation into a tile type and location.
-   * @arg {string} notation - a notation for a single move to be played at
-   * the current board position
-   * @returns {RawMove} the tile type and location of the move
-   */
+  /**
+  Turn a move notation into a tile type and location.
+  @param {string} notation - a notation for a single move to be played at
+  the current board position
+  @returns {RawMove} the tile type and location of the move
+  */
   decodeNotation(notation) {
     /** @type {RawMove} */
     const bad = { type: 'x', loc: zero }
     const match = notation.match(notationRegex)
     if (match === null) return bad
     const loc = new Point(
-      this.left - 1 + Trax.decodeCol(match[1]),
-      this.top - 1 + Number(match[2]),
+      this.left - 1 + Trax.decodeCol(match.groups.col),
+      this.top - 1 + Number(match.groups.row),
     )
-    const possible = this.possibleTiles(loc, match[3])
+    const possible = this.possibleTiles(loc, match.groups.slash)
     if (possible.length > 0) return { type: possible[0], loc }
     return bad
   }
 
-  /** Follow a color from one location through one or more tiles to the other
-   * end of the color line.
-   * @arg {Color} color - the color to follow
-   * @arg {Point} loc - the location to start
-   * @arg {string} from - the edge of the tile to start from
-   * @returns {LineEnd} the ending location and a list of the tile ids the path
-   * takes to get there.
-   */
+  /**
+  Follow a color from one location through one or more tiles to the other
+  end of the color line.
+  @param {Color} color - the color to follow
+  @param {Point} loc - the location to start
+  @param {string} from - the edge of the tile to start from
+  @returns {LineEnd} the ending location and a list of the tile ids the path
+  takes to get there
+  */
   follow(color, loc, from) {
     /** @type {TileId[]} */
     const path = []
@@ -613,11 +849,12 @@ export class Trax {
     return { loc, path }
   }
 
-  /** Given a tile and a color, follow the line for that color to each end.
-   * @arg {Color} color - the color of ends of interest
-   * @arg { Point} loc - the location of the tile of interest
-   * @returns {LineEnd[]} a list of two items, each one end of the line
-   */
+  /**
+  Given a tile and a color, follow the line for that color to each end.
+  @param {Color} color - the color of ends of interest
+  @param {Point} loc - the location of the tile of interest
+  @returns {LineEnd[]} a list of two items, each one end of the line
+  */
   findEnds(color, loc) {
     /** @type {LineEnd[]} */
     const ends = []
@@ -629,11 +866,12 @@ export class Trax {
     return ends
   }
 
-  /** Determine if a given line ends the game.
-   * @arg {Point} locA - one end of the line
-   * @arg {Point} locB - the other end of the line
-   * @returns {boolean} - true if this line wins the game
-   */
+  /**
+  Determine if a given line ends the game.
+  @param {Point} locA - one end of the line
+  @param {Point} locB - the other end of the line
+  @returns {boolean} true if this line wins the game
+  */
   lineWin(locA, locB) {
     if (this.rules === 'traxloop') return false
     if (this.width > 7 && locA.distX(locB) > this.width) return true
@@ -641,26 +879,32 @@ export class Trax {
     return false
   }
 
-  /** Determine if the game has ended.
-   * @arg {Tile[]} tiles - a list of the tiles placed during the last move.
-   */
+  /**
+  Determine if the game has ended.
+  @param {Tile[]} tiles - a list of the tiles placed during the last move
+  */
   checkWin(tiles) {
     /** @type {Color|false} */
     let winner = false
     const colors = [this.color, Trax.other(this.color)] // Check win for current player first
     for (const color of colors) {
       if (winner) continue // Skip the second player if the first has won
-      for (const tile of tiles) {
-        if (winner) continue // Skip the remaining tiles once we find a win
+      tiles.some((tile) => {
         const [end1, end2] = this.findEnds(color, tile.loc)
         if (end1.loc.eq(end2.loc)) {
           winner = color // Loop win
-          this.path = end1.path // Both paths are essentially the same
-        } else if (this.lineWin(end1.loc, end2.loc)) {
+          this.path = end1.path
+          return true
+        }
+
+        if (this.lineWin(end1.loc, end2.loc)) {
           winner = color // Line win, paths need to be combined
-          this.path = [...end1.path.reverse(), ...end2.path.slice(1)]
+          this.path = [...end1.path.toReversed(), ...end2.path.slice(1)]
+          return true
         }
-      }
+
+        return false
+      })
     }
 
     if (winner) {
@@ -678,13 +922,14 @@ export class Trax {
     }
   }
 
-  /** Play a move. Can be called either as:
-   * - play(moveNumber, notation) to ensure move safety, or
-   * - play(notation) for quicker access.
-   * @arg moveNumber {(number|string)} the move number or the notation
-   * @arg {string} [notation] - the notation, if a move number was provided
-   * @returns {{dropped: Tile[], notation: string, valid: boolean}}
-   */
+  /**
+  Play a move. Can be called either as:
+  - play(moveNumber, notation) to ensure move safety, or
+  - play(notation) for quicker access.
+  @param {number|string} moveNumber - the move number or the notation
+  @param {string} [notation] - the notation, if a move number was provided
+  @returns {{dropped: Tile[], notation: string, valid: boolean}} the result of the move
+  */
   play(moveNumber, notation) {
     // Generic API call for playing a move with move number safety
     // or, alternately, pass only a single value, notation, for a quick play
@@ -699,11 +944,12 @@ export class Trax {
     return this.dropTile(notation)
   }
 
-  /** Play one or more moves.
-   * @arg {string|string[]} moves - the list of moves, provided either as a
-   * space-separated string of notations, or as a list of notations. Move
-   * numbers are optional, but if provided will be checked for accuracy.
-   */
+  /**
+  Play one or more moves.
+  @param {string|string[]} moves - the list of moves, provided either as a
+  space-separated string of notations, or as a list of notations. Move
+  numbers are optional, but if provided will be checked for accuracy.
+  */
   playMoves(moves) {
     // Play one or more moves, from a string or a list of moves
     // If move numbers are included, ensure they are accurate
@@ -711,12 +957,12 @@ export class Trax {
       moves = moves.join(' ')
     }
 
-    moves = moves.replaceAll('\n', ' ').split(/\s+/)
+    moves = moves.replaceAll('\n', ' ').split(/\s+/v)
 
     let moveNumber = 0
     for (const move of moves) {
       if (moveNumberRegex.test(move)) {
-        moveNumber = Number(move.replaceAll(/\D/g, ''))
+        moveNumber = Number(move.replaceAll(/\D/gv, ''))
       }
 
       if (notationRegex.test(move)) {
@@ -731,39 +977,41 @@ export class Trax {
     }
   }
 
-  /** Add the current move notation to the notation string
-   * @arg {string} notation - the notation of the current move
-   */
-  updateNotation(notation) {
-    this.move++
-    let note = this.move + '. ' + notation
-    const line = this.notation.split('\n').pop()
-    if (line) {
-      note = (line.length + note.length > 79 ? '\n' : ' ') + note
+  /** The formatted notation string for the current game, wrapped at 80 columns. */
+  get notation() {
+    let result = ''
+    let lineLength = 0
+    for (const [i, move] of this.moves.entries()) {
+      const note = `${i + 1}. ${move}`
+      if (result) {
+        if (lineLength + 1 + note.length > 79) {
+          result += `\n${note}`
+          lineLength = note.length
+        } else {
+          result += ` ${note}`
+          lineLength += 1 + note.length
+        }
+      } else {
+        result = note
+        lineLength = note.length
+      }
     }
 
-    this.notation += note
-  }
-
-  /** An array of the moves made in the game. */
-  get moves() {
-    return this.notation
-      .replaceAll('\n', ' ')
-      .split(' ')
-      .filter((n) => Boolean(n) && !n.endsWith('.'))
+    return result
   }
 
-  /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
-   * @arg {string|ValidTiles} type - a special move, a tile type, or a notation
-   * @arg {Point} [loc] - a location if type is a tile type
-   * @arg {string|boolean} [tentative] - if truthy, the move will not be saved
-   * @returns {TileDrop} an object representing the results of the drop
-   */
+  /**
+  Drop a tile onto the board. This is a lower level call. Use play() if possible instead.
+  @param {string|ValidTiles} type - a special move, a tile type, or a notation
+  @param {Point} [loc] - a location if type is a tile type
+  @param {string|boolean} [tentative] - if truthy, the move will not be saved
+  @returns {TileDrop} an object representing the results of the drop
+  */
   dropTile(type, loc, tentative) {
-    /** @type Tile[] */
+    /** @type {Tile[]} */
     let dropped = []
     let notation = ''
-    let valid = false
+    let isValid = false
     if (['timeout', 'resign', 'draw', 'puzzled'].includes(type)) {
       // Handle special events
       this.over = true
@@ -773,9 +1021,9 @@ export class Trax {
         if (type === 'draw') this.turn = 0 // Draw means we both win
       }
 
-      this.updateNotation(type)
+      this.moves.push(type)
       notation = type
-      valid = true
+      isValid = true
     } else {
       if (type.search(notationRegex) === 0) {
         // We were passed a notation
@@ -785,15 +1033,15 @@ export class Trax {
       }
 
       if (loc && this.validLocation(loc) && this.validTile(type, loc)) {
-        valid = true
-        const saved = this.save() // Just in case we need to roll back
+        isValid = true
+        const cp = this.checkpoint() // Just in case we need to roll back
         notation = this.notate(type, loc) // Determine notation BEFORE we play the move
-        this.updateNotation(notation)
+        this.moves.push(notation)
         dropped.push(this.addTile(type, loc)) // Play the tile
         dropped = [...dropped, ...this.forcedMoves(loc)] // Play all forced moves
         if (this.invalid || tentative) {
-          if (this.invalid) valid = false
-          this.restore(saved) // Abort! abort!
+          if (this.invalid) isValid = false
+          this.rewind(cp) // Abort! abort!
         } else {
           this.checkWin(dropped)
           if (!this.over) this.turn = this.turn === 1 ? 2 : 1
@@ -801,48 +1049,63 @@ export class Trax {
       }
     }
 
-    return { dropped, notation, valid }
+    return { dropped, notation, valid: isValid }
   }
 
-  /** Symmetry helper. Rotates a move around the board in case we are trying to
-   * play a symmetrical rather than an exact move.
-   * @arg {string} move - the notation of the move to be rotated
-   * @returns {string[]} the four rotations of this move
-   */
+  /**
+  Symmetry helper. Rotates a move around the board in case we are trying to
+  play a symmetrical rather than an exact move.
+  @param {string} move - the notation of the move to be rotated
+  @returns {string[]} the four rotations of this move
+  */
   moveRotations(move) {
     // Symmetry helper, rotate a move around the board
     const match = move.match(notationRegex)
     if (match === null) return []
-    const x = Trax.decodeCol(match[1])
-    const y = Number(match[2])
+    const x = Trax.decodeCol(match.groups.col)
+    const y = Number(match.groups.row)
     const X = this.height - x + 1
     const Y = this.width - y + 1
-    const s = match[3]
+    const s = match.groups.slash
     const slashes = s === '+' ? [s] : ['/', '\\']
     const moves = new Set()
     // This isn't super precise, but it limits the search space ... maybe #TODO?
-    for (const slash of slashes) {
-      moves.add(Trax.encodeCol(x) + String(y) + slash)
-      moves.add(Trax.encodeCol(y) + String(x) + slash)
-      moves.add(Trax.encodeCol(X) + String(Y) + slash)
-      moves.add(Trax.encodeCol(Y) + String(X) + slash)
+    for (const slashChar of slashes) {
+      moves.add(Trax.encodeCol(x) + String(y) + slashChar)
+      moves.add(Trax.encodeCol(y) + String(x) + slashChar)
+      moves.add(Trax.encodeCol(X) + String(Y) + slashChar)
+      moves.add(Trax.encodeCol(Y) + String(X) + slashChar)
     }
 
     return [...moves]
   }
 
-  /** Play a provisional move if it is valid.
-   * @arg {string} from - the normalized encoding of the starting position
-   * @arg {string} to - the normalized encoding of the ending position
-   * @arg {string} via - the move to be used to transition
-   * @returns {false|string} if the provisional move is invalid: false; if the
-   * provisional move will never be valid for any future moves:
-   * 'delete-provisional'; if the provisional move is valid, the correct
-   * notation, which may be symmetrically adjusted as needed
-   */
+  /**
+  Play a provisional move if it is valid.
+  @param {string} from - the canonical encoding of the starting position (or,
+  during the `normalize()` deprecation period, a normalized encoding)
+  @param {string} to - the canonical (or normalized) encoding of the ending
+  position, in the same encoding as `from`
+  @param {string} via - the move to be used to transition
+  @returns {false|string} if the provisional move is invalid: false; if the
+  provisional move will never be valid for any future moves:
+  'delete-provisional'; if the provisional move is valid, the correct
+  notation, which may be symmetrically adjusted as needed
+  */
   provisionalMove(from, to, via) {
+    // A normalized code always starts with W/B/T (normalize() forces it);
+    // a canonical code never does, since it's built purely from tile
+    // letters, digits, and ':'. That makes the two formats
+    // self-distinguishing, so provisional moves saved under the deprecated
+    // normalize() keep resolving correctly without callers having to say
+    // which encoding they used. Once normalize() is removed, this check (and
+    // the corresponding slice below) can be deleted - `code` and `target`
+    // become just `from`/`to` and `this.canonical`.
+    const isLegacy = ['W', 'B', 'T'].includes(from[0])
+    const code = isLegacy ? from.slice(1) : from
+
     // Test a provisional move against the current state
-    const lines = from.slice(1).split(':')
+    const lines = code.split(':')
     let cols = 0
     for (const line of lines) {
       cols = Math.max(cols, codeRowLength(line))
@@ -856,14 +1119,14 @@ export class Trax {
       return 'delete-provisional' // Current board is bigger than the provisional move
     }
 
-    if (from === this.normalized) {
-      const saved = this.save() // Save this position
+    if (from === (isLegacy ? this.normalized : this.canonical)) {
+      const cp = this.checkpoint() // Save this position
       for (const move of this.moveRotations(via)) {
         // Try all symmetrical moves
         const drop = this.dropTile(move)
         if (drop.valid) {
-          if (to === this.normalized) return move // This move matched!
-          this.restore(saved) // Put the board back how it was
+          if (to === (isLegacy ? this.normalized : this.canonical)) return move // This move matched!
+          this.rewind(cp) // Put the board back how it was
         }
       }
     }
@@ -871,120 +1134,73 @@ export class Trax {
     return false
   }
 
-  /** Get an encoded representation of the current position, useful for drawing
-   * the board without having to do much analysis.
-   * @returns {string} the current position code
-   */
+  /**
+  Get an encoded representation of the current position, useful for drawing
+  the board without having to do much analysis.
+  @returns {string} the current position code
+  */
   get icon() {
     return this.positionCode()
   }
 
-  /** Get an encoded representation of the current position, with a set of
-   * tiles highlighted differently, useful for showing the effects of a move.
-   * @arg {TileDrop} drops - the drops of the most recent play
-   * @returns {string} the current position code, with drops highlighted
-   */
+  /**
+  Get an encoded representation of the current position, with a set of
+  tiles highlighted differently, useful for showing the effects of a move.
+  @param {TileDrop} drops - the drops of the most recent play
+  @returns {string} the current position code, with drops highlighted
+  */
   dropsIcon(drops) {
     return this.positionCode(undefined, undefined, undefined, drops)
   }
 
-  /** Symmetry helper, draw the board from different angles.
-   * @arg {boolean} [rightToLeft] - reverse order horizontally
-   * @arg {boolean} [bottomToTop] - reverse order vertically
-   * @arg {boolean} [rotate] - rotate the tiles by 90 degrees
-   * @arg {TileDrop} [drops] - the drops of the most recent play, if you want
-   * them highlighted
-   * @returns {string} an encoding of the position
-   */
+  /**
+  Symmetry helper, draw the board from different angles.
+  @param {boolean} [rightToLeft] - reverse order horizontally
+  @param {boolean} [bottomToTop] - reverse order vertically
+  @param {boolean} [rotate] - rotate the tiles by 90 degrees
+  @param {TileDrop} [drops] - the drops of the most recent play, if you want
+  them highlighted
+  @returns {string} an encoding of the position
+  */
   positionCode(rightToLeft, bottomToTop, rotate, drops) {
-    const startX = rightToLeft ? this.right : this.left
-    const startY = bottomToTop ? this.bottom : this.top
-    const incX = rightToLeft ? -1 : 1
-    const incY = bottomToTop ? -1 : 1
-    const code = []
-    let line = ''
-    let x = startX
-    let y = startY
-    do {
-      const loc = new Point(x, y)
-      const tile = this.tileAt(loc) // Normal tile for normal orientation
-      if (tile) {
-        /** @type string */
-        let encoded = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
-        if (this.path.includes(this.tileId(loc))) {
-          encoded = String.fromCodePoint(
-            /** @type {number} */ (encoded.codePointAt(0)) + this.turn * 6,
-          )
-        }
-
-        if (
-          drops &&
-          drops.dropped &&
-          drops.dropped.some((t) => loc.eq(t.loc))
-        ) {
-          encoded = encoded.toUpperCase()
-        }
-
-        line += encoded
-      } else {
-        line = addBlank(line)
-      }
-
-      if (rotate) {
-        // Increment y more often than x
-        y += incY
-        if (y < this.top || y > this.bottom) {
-          y = startY
-          x += incX
-          // Remove final number and add to code
-          code.push(line.replace(/\d+$/, ''))
-          line = ''
-        }
-      } else {
-        // This is the standard order
-        x += incX
-        if (x < this.left || x > this.right) {
-          x = startX
-          y += incY
-          // Remove final number and add to code
-          code.push(line.replace(/\d+$/, ''))
-          line = ''
-        }
-      }
-    } while (
-      x >= this.left &&
-      x <= this.right &&
-      y >= this.top &&
-      y <= this.bottom
-    )
-
-    if (rotate) code.reverse()
-    return code.join(':')
+    return this.#encodePosition({ rightToLeft, bottomToTop, rotate, drops })
   }
 
-  /** Trax has the potential for symmetry, so this gives us the ability to
-   * examine horizontal, vertical, and rotational symmetry for a color.
-   * @returns {string} a position code that matches all symmetrical positions
-   */
+  /**
+  Trax has the potential for symmetry, so this gives us the ability to
+  examine horizontal, vertical, and rotational symmetry for a color.
+  @deprecated Prefer `canonical`, which also collapses color-swapped
+  duplicates - the same puzzle played by the other side. `normalize()` is
+  kept for callers (such as `provisionalMove()`) that need a code sensitive
+  to which color is to move, and is likely to be removed in a future major
+  version.
+  @returns {string} a position code that matches all symmetrical positions
+  */
   normalize() {
-    let norm = 'z'
-    const bools = [true, false]
-    for (const rightToLeft of bools) {
-      for (const bottomToTop of bools) {
-        for (const rotate of bools) {
-          const code = this.positionCode(rightToLeft, bottomToTop, rotate)
-          if (code < norm) norm = code
-        }
-      }
-    }
-
-    return (this.color || 't').toUpperCase() + norm
+    return (this.color || 't').toUpperCase() + this.#minimalCode()
   }
 
-  /** Get the normalized code for this position. All symmetrical positions will
-   * result in the same normalized code.
-   */
+  /**
+  Get the normalized code for this position. All symmetrical positions will
+  result in the same normalized code.
+  @deprecated Prefer `canonical`; see `normalize()`.
+  @returns {string} the normalized position code
+  */
   get normalized() {
     return this.normalize()
   }
+
+  /**
+  Get the canonical code for this position: colors are swapped, if needed,
+  so the code always reads as though white were about to move (or, once the
+  game is over, as though white won), then minimized across all 8
+  rotations/mirrors. Two positions that are identical up to a color swap and
+  board symmetry - the same puzzle, played by the other side - produce the
+  same canonical code. A tied game has no winner to canonicalize around, so
+  its colors are left as-is.
+  @returns {string} the canonical position code
+  */
+  get canonical() {
+    return this.#minimalCode(this.turn === 2)
+  }
 }