@slugbugblue/trax 1.2.0 → 1.3.1

package/RELEASE.v1.3.1.md

@@ -0,0 +1,8 @@
+## 1.3.1 - 2026-10-03
+
+- Fix `positionCode()`, `normalize()`/`normalized`, and `canonical` throwing
+  "Receiver must be an instance of class Trax" when called on an object held in
+  reactive state (such as vue's), by replacing the private class methods added
+  in 1.3.0 with module-level helpers. Private class members are now avoided on
+  purpose; a test guards this.
+

package/benchmark/benchmarks.json

@@ -1,25 +1,138 @@
 {
   "1.1.1": {
     "tutorial.01": {
-      "construction": { "count": 5000, "ms": 0.0843 },
-      "save+restore": { "count": 1000, "ms": 0.0058 },
-      "possibleMoves": { "count": 1000, "ms": 0.7045 },
-      "play": { "count": 1000, "ms": 0.1158 },
-      "normalized": { "count": 5000, "ms": 0.0092 }
+      "construction": {
+        "count": 5000,
+        "ms": 0.0843
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.0058
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 0.7045
+      },
+      "play": {
+        "count": 1000,
+        "ms": 0.1158
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.0092
+      }
     },
     "book.20": {
-      "construction": { "count": 5000, "ms": 0.2955 },
-      "save+restore": { "count": 1000, "ms": 0.0131 },
-      "possibleMoves": { "count": 1000, "ms": 2.3677 },
-      "play": { "count": 1000, "ms": 0.2953 },
-      "normalized": { "count": 5000, "ms": 0.0433 }
+      "construction": {
+        "count": 5000,
+        "ms": 0.2955
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.0131
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 2.3677
+      },
+      "play": {
+        "count": 1000,
+        "ms": 0.2953
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.0433
+      }
     },
     "book.30": {
-      "construction": { "count": 5000, "ms": 1.3156 },
-      "save+restore": { "count": 1000, "ms": 0.0486 },
-      "possibleMoves": { "count": 1000, "ms": 6.785 },
-      "play": { "count": 1000, "ms": 1.3788 },
-      "normalized": { "count": 5000, "ms": 0.1611 }
+      "construction": {
+        "count": 5000,
+        "ms": 1.3156
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.0486
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 6.785
+      },
+      "play": {
+        "count": 1000,
+        "ms": 1.3788
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.1611
+      }
+    }
+  },
+  "1.2.0": {
+    "tutorial.01": {
+      "construction": {
+        "count": 5000,
+        "ms": 0.0898032286
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.008606527000000029
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 0.897647975
+      },
+      "play": {
+        "count": 1000,
+        "ms": 0.12720280200000003
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.010315181600000006
+      }
+    },
+    "book.20": {
+      "construction": {
+        "count": 5000,
+        "ms": 0.3137343523999999
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.016668513000000076
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 2.691874038
+      },
+      "play": {
+        "count": 1000,
+        "ms": 0.3145682210000004
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.05063697260000008
+      }
+    },
+    "book.30": {
+      "construction": {
+        "count": 5000,
+        "ms": 1.125999694
+      },
+      "save+restore": {
+        "count": 1000,
+        "ms": 0.055884163000000625
+      },
+      "possibleMoves": {
+        "count": 1000,
+        "ms": 4.9472956880000005
+      },
+      "play": {
+        "count": 1000,
+        "ms": 1.125647703999999
+      },
+      "normalized": {
+        "count": 5000,
+        "ms": 0.17698205720000043
+      }
     }
   }
 }

package/benchmark/engine.bench.js

@@ -98,7 +98,7 @@ function benchPosition(game, notation, baseline) {
     const g = new Trax(game, notation)
     g.play(/** @type {string} */ (lastMove))
   }, 1000)
-  const normalized = bench(() => instance.normalized, 5000)
+  const canonical = bench(() => instance.canonical, 5000)
 
   /** @type {Record<string, { count: number, ms: number }>} */
   const results = {
@@ -106,7 +106,7 @@ function benchPosition(game, notation, baseline) {
     'save+restore': saveRestore,
     possibleMoves: possibleMovesResult,
     play,
-    normalized,
+    canonical,
   }
 
   /** @type {MetricRow[]} */

package/gl-sast-report.json

@@ -1 +1 @@
-{"version":"15.2.2","vulnerabilities":[],"scan":{"analyzer":{"id":"semgrep","name":"Semgrep","url":"https://gitlab.com/gitlab-org/security-products/analyzers/semgrep","vendor":{"name":"GitLab"},"version":"6.18.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.145.0"},"type":"sast","start_time":"2026-06-26T00:29:40","end_time":"2026-06-26T00:29:52","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"c0b9149f-1c82-4346-9e3c-34727b5f04e6","label":"semgrep","value":0,"version":"6.18.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":12,"file_count":8}]}}}
+{"version":"15.2.4","vulnerabilities":[],"scan":{"analyzer":{"id":"semgrep","name":"Semgrep","url":"https://gitlab.com/gitlab-org/security-products/analyzers/semgrep","vendor":{"name":"GitLab"},"version":"6.26.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.174.0"},"type":"sast","start_time":"2026-10-03T17:30:51","end_time":"2026-10-03T17:31:00","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"b0a96e4b-7b13-4045-a6a0-5e00f358eec7","label":"semgrep","value":0,"version":"6.26.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":9,"file_count":8}]}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Trax game engine",
   "keywords": [
     "trax",
@@ -32,7 +32,7 @@
     "ts-build": "tsc -p tsconfig.build.json && rm -f src/version.d.ts",
     "test": "xo && c8 ava",
     "prepare": "[ -n \"$CI\" ] || husky",
-    "preversion": "npm audit --audit-level=high && npm test",
+    "preversion": "npm audit --omit=dev --audit-level=high && npm test",
     "version": "npm run genversion ; npm run ts-build ; npm run git-add",
     "postversion": "git push && git push --tags"
   },
@@ -41,12 +41,13 @@
     "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
     "ava": "^8.0.1",
-    "c8": "^11.0.0",
+    "c8": "^12.0.0",
     "genversion": "^3.0.2",
     "husky": "^9.1.7",
     "prettier": "^3.6.2",
-    "xo": "^3.0.2"
+    "xo": "^4.0.0"
   },
   "type": "module",
   "engines": {

package/src/engine.d.ts

@@ -1,7 +1,7 @@
 /** A digital representation of a Trax game. */
 export class Trax {
   /** @readonly */
-  static readonly version: '1.2.0'
+  static readonly version: '1.3.1'
   /**
     @readonly
     @type {Record<TraxVariant, string>}
@@ -147,10 +147,10 @@ export class Trax {
   /**
     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 '+'
+    @param {string} [slashFilter] - if provided, a direction modifier, '/', '\\', or '+'
     @returns {TileType[]} the list of valid tile types for this location
     */
-  possibleTiles(loc: Point, s?: string | boolean): TileType[]
+  possibleTiles(loc: Point, slashFilter?: string): TileType[]
   get height(): number
   get width(): number
   /**
@@ -169,7 +169,6 @@ export class Trax {
     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[]
@@ -269,8 +268,10 @@ export class Trax {
   moveRotations(move: string): string[]
   /**
     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} 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:
@@ -309,15 +310,32 @@ export class Trax {
   /**
     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.
+    @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
 }
 export type Color = 'w' | 'b'
 /**
@@ -452,5 +470,26 @@ export type TileDrop = {
 export type TileType = ValidTiles | 'x'
 export type TraxVariant = 'trax' | 'traxloop' | 'trax8'
 export type ValidTiles = 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
+/**
+ * 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'

package/src/engine.js

@@ -89,6 +89,15 @@ const zero = new Point(0, 0)
 const moveNumberRegex = /^\d+[\).:]?$/v
 const notationRegex = /^(?<col>[@a-z]+)(?<row>\d+)(?<slash>[+\/\\])$/iv
 
+/**
+Named groups of a successful `notationRegex` match. TypeScript types
+`groups` as possibly undefined, but it is always set when the regex matches.
+@param {RegExpMatchArray} match - a match of `notationRegex`
+@returns {{col: string, row: string, slash: string}} the notation parts
+*/
+const notationGroups = (match) =>
+  /** @type {{col: string, row: string, slash: string}} */ (match.groups)
+
 /**
 Tiles are represented by the letters a-f.
     a         b        c        d        e        f
@@ -127,15 +136,24 @@ const symmetry = {
 
 // Fun trax helper functions
 
+/**
+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 {boolean} [rightToLeft] - mirror the tile
-@param {boolean} [bottomToTop] - flip the tile
-@param {boolean} [rotate] - rotate the tile counterclockwise
+@param {SymmetryOptions} [options] - the symmetry to apply
 @returns {ValidTiles} the transformed tile
 */
-const applySymmetry = (tile, rightToLeft, bottomToTop, rotate) => {
+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]
@@ -200,6 +218,128 @@ The length of an encoded position row.
 const codeRowLength = (row) =>
   row.replaceAll(/\d/gv, (n) => '.'.repeat(Number(n) + 1)).length
 
+/**
+Find the position code with the lowest sort order across all 8
+combinations of mirroring, flipping, and rotating.
+@param {Trax} trax - the game to encode
+@param {boolean} [colorSwap] - swap tile colors before comparing
+@returns {string} the minimal encoded position code
+*/
+const minimalCode = (trax, 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 = encodePosition(trax, {
+          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 {Trax} trax - the game the tile is in
+@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
+*/
+const encodeTile = (trax, tile, loc, options) => {
+  const { colorSwap, drops } = options
+  /** @type {string} */
+  let encoded = applySymmetry(tile, options)
+  if (trax.path.includes(trax.tileId(loc))) {
+    // `trax.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 && trax.turn
+        ? Trax.playerNumber(Trax.other(Trax.colorOf(trax.turn)))
+        : trax.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 {Trax} trax - the game to encode
+@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
+*/
+const encodePosition = (trax, options) => {
+  const { rightToLeft, bottomToTop, rotate } = options
+  const startX = rightToLeft ? trax.right : trax.left
+  const startY = bottomToTop ? trax.bottom : trax.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 = trax.tileAt(loc) // Normal tile for normal orientation
+    if (tile) {
+      line += encodeTile(trax, tile, loc, options)
+    } else {
+      line = addBlank(line)
+    }
+
+    if (rotate) {
+      // Increment y more often than x
+      y += incY
+      if (y < trax.top || y > trax.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 < trax.left || x > trax.right) {
+        x = startX
+        y += incY
+        // Remove final number and add to code
+        code.push(line.replace(/\d$/v, ''))
+        line = ''
+      }
+    }
+  } while (
+    x >= trax.left &&
+    x <= trax.right &&
+    y >= trax.top &&
+    y <= trax.bottom
+  )
+
+  if (rotate) code.reverse()
+  return code.join(':')
+}
+
 // This is where the magic happens
 /** A digital representation of a Trax game. */
 export class Trax {
@@ -409,10 +549,9 @@ export class Trax {
     /** @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]
-      }
+      if (tile.move <= cp.move) continue
+      deleted.push(tile)
+      delete this.tiles[key]
     }
 
     for (const tile of deleted) {
@@ -537,14 +676,19 @@ export class Trax {
   /**
   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 '+'
+  @param {string} [slashFilter] - if provided, a direction modifier, '/', '\\', or '+'
   @returns {TileType[]} the list of valid tile types for this location
   */
-  possibleTiles(loc, s = false) {
+  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
@@ -598,7 +742,6 @@ export class Trax {
   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() {
@@ -671,11 +814,12 @@ export class Trax {
     const bad = { type: 'x', loc: zero }
     const match = notation.match(notationRegex)
     if (match === null) return bad
+    const { col, row, slash: slashType } = notationGroups(match)
     const loc = new Point(
-      this.left - 1 + Trax.decodeCol(match.groups.col),
-      this.top - 1 + Number(match.groups.row),
+      this.left - 1 + Trax.decodeCol(col),
+      this.top - 1 + Number(row),
     )
-    const possible = this.possibleTiles(loc, match.groups.slash)
+    const possible = this.possibleTiles(loc, slashType)
     if (possible.length > 0) return { type: possible[0], loc }
     return bad
   }
@@ -879,7 +1023,7 @@ export class Trax {
     /** @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
@@ -891,7 +1035,7 @@ export class Trax {
 
       this.moves.push(type)
       notation = type
-      valid = true
+      isValid = true
     } else {
       if (type.search(notationRegex) === 0) {
         // We were passed a notation
@@ -901,14 +1045,14 @@ export class Trax {
       }
 
       if (loc && this.validLocation(loc) && this.validTile(type, loc)) {
-        valid = true
+        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.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
+          if (this.invalid) isValid = false
           this.rewind(cp) // Abort! abort!
         } else {
           this.checkWin(dropped)
@@ -917,7 +1061,7 @@ export class Trax {
       }
     }
 
-    return { dropped, notation, valid }
+    return { dropped, notation, valid: isValid }
   }
 
   /**
@@ -930,11 +1074,11 @@ export class Trax {
     // Symmetry helper, rotate a move around the board
     const match = move.match(notationRegex)
     if (match === null) return []
-    const x = Trax.decodeCol(match.groups.col)
-    const y = Number(match.groups.row)
+    const { col, row, slash: s } = notationGroups(match)
+    const x = Trax.decodeCol(col)
+    const y = Number(row)
     const X = this.height - x + 1
     const Y = this.width - y + 1
-    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?
@@ -950,8 +1094,10 @@ export class Trax {
 
   /**
   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} 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:
@@ -959,8 +1105,19 @@ export class Trax {
   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))
@@ -974,13 +1131,13 @@ export class Trax {
       return 'delete-provisional' // Current board is bigger than the provisional move
     }
 
-    if (from === this.normalized) {
+    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!
+          if (to === (isLegacy ? this.normalized : this.canonical)) return move // This move matched!
           this.rewind(cp) // Put the board back how it was
         }
       }
@@ -1018,97 +1175,44 @@ export class Trax {
   @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$/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(':')
+    return encodePosition(this, { 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.
+  @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() + minimalCode(this)
   }
 
   /**
   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 minimalCode(this, this.turn === 2)
+  }
 }

package/src/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '1.2.0'
+export const version = '1.3.1'

package/RELEASE.v1.2.0.md

@@ -1,10 +0,0 @@
-## 1.2.0 - 2026-06-25
-
-- Implement an initial benchmarking record
-- Swap the notation / moves storage (store moves, calculate notation)
-- Maintain the tile count and possible locations candidate set incrementally
-- Combined speedup of about 30% on new games and per-move play
-- Around 35% for `possibleMoves` on large boards vs 1.1.1
-- Update docs to reflect changes
-- Update dependencies
-