@slugbugblue/trax 1.1.0 → 1.2.0

package/src/engine.js

@@ -1,45 +1,122 @@
-/** Trax engine.
- * @copyright 2019-2026
- * @author Chad Transtrum <chad@transtrum.net>
- * @license Apache-2.0
- */
-
-/// <reference path="./types.d.ts" />
-
+/**
+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'
 import { version } from './version.js'
 
+// Type definitions
+
+/** Color is a single character to represent white or black. */
+/** @typedef {'w' | 'b'} Color */
+
+/**
+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 - 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 - 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 - 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 - 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 */
+
+/** All of the variants supported by the engine. */
+/** @typedef {'trax' | 'traxloop' | 'trax8'} TraxVariant */
+
+/** Tile type names are single letters a-f encoding edge colors. */
+/** @typedef {'a' | 'b' | 'c' | 'd' | 'e' | 'f'} ValidTiles */
+
 // 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' },
@@ -50,13 +127,14 @@ const symmetry = {
 
 // Fun trax helper functions
 
-/** Apply certain combinations of symmetry.
- * @arg {TileType} 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 {TileType}
- */
+/**
+Apply certain combinations of symmetry.
+@param {ValidTiles} tile - the tile to apply symmetry to
+@param {boolean} [rightToLeft] - mirror the tile
+@param {boolean} [bottomToTop] - flip the tile
+@param {boolean} [rotate] - rotate the tile counterclockwise
+@returns {ValidTiles} the transformed tile
+*/
 const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
   if (rightToLeft) tile = symmetry.mirror[tile]
   if (bottomToTop) tile = symmetry.flip[tile]
@@ -64,42 +142,48 @@ const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
   return tile
 }
 
-// Unexpected note: str.includes(t) is true if t is '' but false if t is undefined
-/** The color at the top of the tile.
- * @arg {string} t - the tile to check
- * @returns {Color|false} the color or false if t is not a valid tile
- */
+// 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.
+@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(t) ? 'b' : 'def'.includes(t) ? 'w' : false
+  'abc'.includes(String(t)) ? 'b' : 'def'.includes(String(t)) ? 'w' : false
 
-/** The color at the bottom of the tile.
- * @arg {string} 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(t) ? 'b' : 'ace'.includes(t) ? 'w' : false
+  'bdf'.includes(String(t)) ? 'b' : 'ace'.includes(String(t)) ? 'w' : false
 
-/** The color at the right edge of the tile.
- * @arg {string} 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(t) ? 'b' : 'bcf'.includes(t) ? 'w' : false
+  'ade'.includes(String(t)) ? 'b' : 'bcf'.includes(String(t)) ? 'w' : false
 
-/** The color at the left edge of the tile.
- * @arg {string} 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(t) ? 'b' : 'abd'.includes(t) ? 'w' : false
+  '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 = code.codePointAt(code.length - 1) // This is NaN if code is empty, which is ok
+  const lastNumber = /** @type {number} */ (code.codePointAt(code.length - 1)) // Undefined if code is empty, which is ok
   if (lastNumber > 47 && lastNumber < 57) {
     return code.slice(0, -1) + String.fromCodePoint(lastNumber + 1)
   }
@@ -108,12 +192,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. */
@@ -121,7 +206,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',
@@ -130,31 +218,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
-   */
-  static colorOf = (playerNumber) => ({ 1: 'w', 2: 'b' })[playerNumber]
-  /** Given a color, get the player number.
-   * @arg {string} color - the color, w or b
-   * @returns {number} the player number, 1 or 2
-   */
-  static playerNumber = (color) => ({ b: 2, w: 1 })[color]
-  /** Given a color, get the other color.
-   * @arg {string} color - the color, w or b
-   * @returns {Color} the other color, b or w
-   */
-  static other = (color) => ({ b: 'w', w: 'b' })[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
-   */
+  /**
+  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.
+  @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.
+  @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.
+  @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 = ''
@@ -165,16 +270,18 @@ 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()
     let n = 0
     while (col.length > 0) {
-      n += (col.codePointAt(0) - 64) * 26 ** (col.length - 1)
+      const cp = /** @type {number} */ (col.codePointAt(0))
+      n += (cp - 64) * 26 ** (col.length - 1)
       col = col.slice(1)
     }
 
@@ -182,26 +289,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
@@ -210,10 +321,11 @@ export class Trax {
     }
   }
 
-  /** Save the current game data to a variable.
-   * @returns {SaveState} an opaque save state object
-   * @see restore for restoring the state
-   */
+  /**
+  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 {
@@ -225,28 +337,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
@@ -254,6 +368,69 @@ 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) {
+        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. */
@@ -261,9 +438,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. */
@@ -281,21 +458,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} */
@@ -304,6 +483,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)
@@ -313,17 +501,21 @@ export class Trax {
     return tile
   }
 
-  /** The type of tile at the given location.
-   * @arg {PointLike} loc - the location the tile is in
-   * @returns {TileType|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 (this.tiles[this.tileId(loc)] || {}).type
+    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'
@@ -342,13 +534,14 @@ 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[]}
-   */
+  /**
+  Get a list of possible tiles that can be played in this location.
+  @param {Point} loc - the location to check
+  @param {string | boolean} [s=false] - if provided, a direction modifier, '/', '\\', or '+'
+  @returns {TileType[]} the list of valid tile types for this location
+  */
   possibleTiles(loc, s = false) {
-    /** @type TileType[] */
+    /** @type {TileType[]} */
     const possibles = []
     for (const t of tileTypes) {
       if ((!s || s === slash[t]) && this.validTile(t, loc)) possibles.push(t)
@@ -365,10 +558,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
@@ -390,29 +584,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 = []
@@ -427,10 +615,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 = []
@@ -438,7 +627,7 @@ export class Trax {
     const invalids = {}
     let check = loc.around
     while (check.length > 0) {
-      const pos = check.shift()
+      const pos = /** @type {Point} */ (check.shift())
       if (this.validLocation(pos)) {
         const possibles = this.possibleTiles(pos)
         if (possibles.length === 1) {
@@ -448,7 +637,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
         }
       }
@@ -457,12 +646,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)
@@ -470,34 +660,37 @@ 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 = []
     let id = this.tileId(loc)
     let tile = this.tileAt(loc)
@@ -524,11 +717,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 = []
@@ -540,11 +734,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
@@ -552,26 +747,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) {
@@ -589,13 +790,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
@@ -610,11 +812,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
@@ -622,12 +825,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)) {
@@ -642,36 +845,38 @@ 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
+    return result
   }
 
-  /** An array of the moves made in the game. */
-  get moves() {
-    return this.notation
-      .replaceAll('\n', ' ')
-      .split(' ')
-      .filter((n) => Boolean(n) && !n.endsWith('.'))
-  }
-
-  /** 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
@@ -684,7 +889,7 @@ 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
     } else {
@@ -697,14 +902,14 @@ 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
+        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!
+          this.rewind(cp) // Abort! abort!
         } else {
           this.checkWin(dropped)
           if (!this.over) this.turn = this.turn === 1 ? 2 : 1
@@ -715,42 +920,44 @@ export class Trax {
     return { dropped, notation, valid }
   }
 
-  /** 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 normalized encoding of the starting position
+  @param {string} to - the normalized encoding of the ending position
+  @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) {
     // Test a provisional move against the current state
     const lines = from.slice(1).split(':')
@@ -768,13 +975,13 @@ export class Trax {
     }
 
     if (from === this.normalized) {
-      const saved = this.save() // Save this position
+      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
+          this.rewind(cp) // Put the board back how it was
         }
       }
     }
@@ -782,31 +989,34 @@ 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
@@ -820,10 +1030,12 @@ export class Trax {
       const loc = new Point(x, y)
       const tile = this.tileAt(loc) // Normal tile for normal orientation
       if (tile) {
-        /** @type string */
+        /** @type {string} */
         let encoded = applySymmetry(tile, rightToLeft, bottomToTop, rotate)
         if (this.path.includes(this.tileId(loc))) {
-          encoded = String.fromCodePoint(encoded.codePointAt(0) + this.turn * 6)
+          encoded = String.fromCodePoint(
+            /** @type {number} */ (encoded.codePointAt(0)) + this.turn * 6,
+          )
         }
 
         if (
@@ -846,7 +1058,7 @@ export class Trax {
           y = startY
           x += incX
           // Remove final number and add to code
-          code.push(line.replace(/\d+$/, ''))
+          code.push(line.replace(/\d$/v, ''))
           line = ''
         }
       } else {
@@ -856,7 +1068,7 @@ export class Trax {
           x = startX
           y += incY
           // Remove final number and add to code
-          code.push(line.replace(/\d+$/, ''))
+          code.push(line.replace(/\d$/v, ''))
           line = ''
         }
       }
@@ -871,10 +1083,11 @@ export class Trax {
     return code.join(':')
   }
 
-  /** 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.
+  @returns {string} a position code that matches all symmetrical positions
+  */
   normalize() {
     let norm = 'z'
     const bools = [true, false]
@@ -890,9 +1103,11 @@ export class Trax {
     return (this.color || 't').toUpperCase() + norm
   }
 
-  /** 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.
+  @returns {string} the normalized position code
+  */
   get normalized() {
     return this.normalize()
   }