@slugbugblue/trax 1.1.1 → 1.3.0

package/src/engine.d.ts

@@ -1,175 +1,236 @@
 /** A digital representation of a Trax game. */
 export class Trax {
   /** @readonly */
-  static readonly version: '1.1.1'
-  /** @readonly @type {Record<TraxVariant, string>} */
+  static readonly version: '1.3.0'
+  /**
+    @readonly
+    @type {Record<TraxVariant, string>}
+    */
   static readonly names: Record<TraxVariant, string>
   /** @readonly */
   static readonly variants: Set<string>
-  /** 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: number | PointLike, y?: number) => Point
-  /** 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: number) => Color
-  /** 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: string) => number
-  /** 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: string) => 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: number) => string
-  /** 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: string) => number
-  /** 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?: TraxVariant, moves?: string | string[], id?: string)
   id: string
   rules: TraxVariant
-  move: number
   turn: number
   over: boolean
   left: number
   right: number
   top: number
   bottom: number
-  notation: string
+  count: number
+  /** @type {string[]} */
+  moves: string[]
+  /** @type {Map<TileId, Point>} */
+  frontier: Map<TileId, Point>
   /** @type {Record<TileId, Tile>} */
   tiles: Record<TileId, Tile>
-  /** @type TileId[] */
+  /** @type {TileId[]} */
   path: TileId[]
   invalid: boolean
-  /** 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(): SaveState
-  /** 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: SaveState): void
+  /**
+    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(): {
+    move: number
+    count: number
+    turn: number
+    left: number
+    right: number
+    top: number
+    bottom: number
+  }
+  /**
+    Rewind to a checkpoint. Only valid for ancestor restores.
+    @param {Checkpoint} cp - the checkpoint to rewind to
+    */
+  rewind(cp: {
+    move: number
+    count: number
+    turn: number
+    left: number
+    right: number
+    top: number
+    bottom: number
+  }): void
   /** The name of this variant. */
   get name(): string
-  /** The number of tiles currently in play. */
-  get count(): number
+  /** The move number of the last-played move. */
+  get move(): number
   /** The color of the current player, w or b. */
   get color(): Color
   /** True if the game is over. */
   get gameOver(): boolean
   /** 1 or 2 for a win, 0 for a tie, false if the game is still in progress. */
   get winner(): number | false
-  /** Provides the tile ID for the tile at the given location.
-   * @arg {PointLike} loc
-   * returns {TileId}
-   */
-  tileId(loc: PointLike): string
-  /** 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.
-   */
+  /**
+    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: PointLike): TileId
+  /**
+    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: TileType, loc: Point): 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: PointLike): ValidTiles | undefined
   validTile(type: string, loc: Point): type is ValidTiles
-  /** 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: Point, s?: string | boolean): 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: Point, slashFilter?: string): TileType[]
   get height(): number
   get width(): number
-  /** 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: Point): boolean
-  /** 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(): Point[]
-  /** 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(): string[]
-  /** 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: Point): Tile[]
-  /** 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: ValidTiles, loc: Point): string
-  /** 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: string): RawMove
-  /** 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: Color, loc: Point, from: string): LineEnd
-  /** 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: Color, loc: Point): LineEnd[]
-  /** 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: Point, locB: Point): boolean
-  /** 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: Tile[]): void
-  /** 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: number | string,
     notation?: string,
@@ -178,86 +239,118 @@ export class Trax {
     notation: string
     valid: boolean
   }
-  /** 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: string | string[]): void
-  /** Add the current move notation to the notation string
-   * @arg {string} notation - the notation of the current move
-   */
-  updateNotation(notation: string): void
-  /** An array of the moves made in the game. */
-  get moves(): string[]
-  /** 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
-   */
+  /** The formatted notation string for the current game, wrapped at 80 columns. */
+  get notation(): string
+  /**
+    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: string | ValidTiles,
     loc?: Point,
     tentative?: string | boolean,
   ): TileDrop
-  /** 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: string): string[]
-  /** 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: string, to: string, via: string): false | string
-  /** 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(): string
-  /** 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: TileDrop): string
-  /** 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?: boolean,
     bottomToTop?: boolean,
     rotate?: boolean,
     drops?: TileDrop,
   ): string
-  /** 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(): string
-  /** 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(): string
+  /**
+    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(): string
+  #private
 }
 export type Color = 'w' | 'b'
 /**
  * One end of a line and the tiles taken to get there.
  */
 export type LineEnd = {
+  /**
+   * - the ending location
+   */
   loc: Point
+  /**
+   * - tile ids from start to end
+   */
   path: TileId[]
 }
 export type Notation = string
@@ -265,7 +358,13 @@ export type Notation = string
  * A tile type and a location determine a raw move.
  */
 export type RawMove = {
+  /**
+   * - the tile type
+   */
   type: TileType
+  /**
+   * - the location
+   */
   loc: Point
 }
 /**
@@ -273,17 +372,57 @@ export type RawMove = {
  * produced by save() and fed into restore().
  */
 export type SaveState = {
+  /**
+   * - game id
+   */
   id: string
+  /**
+   * - move number
+   */
   move: number
+  /**
+   * - current player (1 or 2)
+   */
   turn: number
+  /**
+   * - whether the game is over
+   */
   over: boolean
+  /**
+   * - leftmost tile column
+   */
   left: number
+  /**
+   * - rightmost tile column
+   */
   right: number
+  /**
+   * - topmost tile row
+   */
   top: number
+  /**
+   * - bottommost tile row
+   */
   bottom: number
-  notation: Notation
+  /**
+   * - move notations
+   */
+  moves: string[]
+  /**
+   * - frontier locations
+   */
+  frontier: [TileId, Point][]
+  /**
+   * - serialized tiles
+   */
   tiles: string
+  /**
+   * - serialized winning path
+   */
   path: string
+  /**
+   * - whether an invalid tile was placed
+   */
   invalid: boolean
 }
 export type Slash = '/' | '\\' | '+'
@@ -291,10 +430,25 @@ export type Slash = '/' | '\\' | '+'
  * A single tile on the board.
  */
 export type Tile = {
+  /**
+   * - unique tile identifier
+   */
   id: TileId
+  /**
+   * - board location
+   */
   loc: Point
+  /**
+   * - tile type letter
+   */
   type: TileType
+  /**
+   * - move number when placed
+   */
   move: number
+  /**
+   * - sequence number among all tiles
+   */
   seq: number
 }
 export type TileId = string
@@ -302,12 +456,42 @@ export type TileId = string
  * When a tile is dropped, this object represents the results.
  */
 export type TileDrop = {
+  /**
+   * - all tiles placed, including forced moves
+   */
   dropped: Tile[]
+  /**
+   * - the notation of the played move
+   */
   notation: Notation
+  /**
+   * - whether the move was legal
+   */
   valid: boolean
 }
 export type TileType = ValidTiles | 'x'
 export type TraxVariant = 'trax' | 'traxloop' | 'trax8'
 export type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
-import type { PointLike } from '@slugbugblue/point'
+/**
+ * Symmetry options for viewing a position from different angles.
+ */
+export type SymmetryOptions = {
+  /**
+   * - mirror the tile
+   */
+  rightToLeft?: boolean | undefined
+  /**
+   * - flip the tile
+   */
+  bottomToTop?: boolean | undefined
+  /**
+   * - rotate the tile counterclockwise
+   */
+  rotate?: boolean | undefined
+  /**
+   * - swap the tile's colors
+   */
+  colorSwap?: boolean | undefined
+}
 import { Point } from '@slugbugblue/point'
+import type { PointLike } from '@slugbugblue/point'