@slugbugblue/trax 1.3.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/gl-sast-report.json

@@ -1 +1 @@
-{"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.19.1"},"scanner":{"id":"semgrep","name":"Semgrep","url":"https://github.com/returntocorp/semgrep","vendor":{"name":"GitLab"},"version":"1.168.0"},"type":"sast","start_time":"2026-08-16T23:13:50","end_time":"2026-08-16T23:13:59","status":"success","observability":{"events":[{"event":"collect_sast_scan_metrics_from_pipeline","property":"b7450097-a7e5-4ab8-88e8-d42c900bb7ec","label":"semgrep","value":0,"version":"6.19.1","exit_code":0,"override_count":0,"passthrough_count":0,"custom_exclude_path_count":0,"time_s":8,"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.3.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,6 +41,7 @@
     "@slugbugblue/point": "^1.0.0"
   },
   "devDependencies": {
+    "@types/node": "^26.6.4",
     "ava": "^8.0.1",
     "c8": "^12.0.0",
     "genversion": "^3.0.2",

package/src/engine.d.ts

@@ -1,7 +1,7 @@
 /** A digital representation of a Trax game. */
 export class Trax {
   /** @readonly */
-  static readonly version: '1.3.0'
+  static readonly version: '1.3.1'
   /**
     @readonly
     @type {Record<TraxVariant, string>}
@@ -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[]
@@ -337,7 +336,6 @@ export class Trax {
     @returns {string} the canonical position code
     */
   get canonical(): string
-  #private
 }
 export type Color = 'w' | 'b'
 /**

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
@@ -209,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 {
@@ -330,125 +461,6 @@ export class Trax {
     }
   }
 
-  /**
-  Find the position code with the lowest sort order across all 8
-  combinations of mirroring, flipping, and rotating.
-  @param {boolean} [colorSwap] - swap tile colors before comparing
-  @returns {string} the minimal encoded position code
-  */
-  #minimalCode(colorSwap) {
-    let min = 'z'
-    const bools = [true, false]
-    for (const rightToLeft of bools) {
-      for (const bottomToTop of bools) {
-        for (const rotate of bools) {
-          const code = this.#encodePosition({
-            rightToLeft,
-            bottomToTop,
-            rotate,
-            colorSwap,
-          })
-          if (code < min) min = code
-        }
-      }
-    }
-
-    return min
-  }
-
-  /**
-  Encode a single tile for a position code: apply symmetry, highlight it if
-  it's part of the winning path, and highlight it if it was just dropped.
-  @param {ValidTiles} tile - the tile to encode
-  @param {Point} loc - the tile's location
-  @param {SymmetryOptions & {drops?: TileDrop}} options - the symmetry and
-  drop-highlighting options
-  @returns {string} the encoded tile
-  */
-  #encodeTile(tile, loc, options) {
-    const { colorSwap, drops } = options
-    /** @type {string} */
-    let encoded = applySymmetry(tile, options)
-    if (this.path.includes(this.tileId(loc))) {
-      // `this.turn` is whoever's winning path is highlighted (or 0 for a
-      // tie); canonicalizing colors also canonicalizes that turn, since a
-      // swapped black winner is presented as white.
-      const pathTurn =
-        colorSwap && this.turn
-          ? Trax.playerNumber(Trax.other(Trax.colorOf(this.turn)))
-          : this.turn
-      encoded = String.fromCodePoint(
-        /** @type {number} */ (encoded.codePointAt(0)) + pathTurn * 6,
-      )
-    }
-
-    if (drops?.dropped?.some((t) => loc.eq(t.loc))) {
-      encoded = encoded.toUpperCase()
-    }
-
-    return encoded
-  }
-
-  /**
-  Encode a position, applying optional symmetrical operations on it. Backs
-  both the public, color-blind `positionCode()` and the color-swap-aware
-  `#minimalCode()` used by `canonical`.
-  @param {SymmetryOptions & {drops?: TileDrop}} options - reverse order
-  horizontally/vertically, rotate the tiles by 90 degrees, swap tile colors,
-  and/or highlight the drops of the most recent play
-  @returns {string} an encoding of the position
-  */
-  #encodePosition(options) {
-    const { rightToLeft, bottomToTop, rotate } = options
-    const startX = rightToLeft ? this.right : this.left
-    const startY = bottomToTop ? this.bottom : this.top
-    const incX = rightToLeft ? -1 : 1
-    const incY = bottomToTop ? -1 : 1
-    const code = []
-    let line = ''
-    let x = startX
-    let y = startY
-    do {
-      const loc = new Point(x, y)
-      const tile = this.tileAt(loc) // Normal tile for normal orientation
-      if (tile) {
-        line += this.#encodeTile(tile, loc, options)
-      } else {
-        line = addBlank(line)
-      }
-
-      if (rotate) {
-        // Increment y more often than x
-        y += incY
-        if (y < this.top || y > this.bottom) {
-          y = startY
-          x += incX
-          // Remove final number and add to code
-          code.push(line.replace(/\d$/v, ''))
-          line = ''
-        }
-      } else {
-        // This is the standard order
-        x += incX
-        if (x < this.left || x > this.right) {
-          x = startX
-          y += incY
-          // Remove final number and add to code
-          code.push(line.replace(/\d$/v, ''))
-          line = ''
-        }
-      }
-    } while (
-      x >= this.left &&
-      x <= this.right &&
-      y >= this.top &&
-      y <= this.bottom
-    )
-
-    if (rotate) code.reverse()
-    return code.join(':')
-  }
-
   /**
   Save the current game data to a variable.
   @returns {SaveState} an opaque save state object
@@ -730,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() {
@@ -803,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
   }
@@ -1062,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?
@@ -1163,7 +1175,7 @@ export class Trax {
   @returns {string} an encoding of the position
   */
   positionCode(rightToLeft, bottomToTop, rotate, drops) {
-    return this.#encodePosition({ rightToLeft, bottomToTop, rotate, drops })
+    return encodePosition(this, { rightToLeft, bottomToTop, rotate, drops })
   }
 
   /**
@@ -1177,7 +1189,7 @@ export class Trax {
   @returns {string} a position code that matches all symmetrical positions
   */
   normalize() {
-    return (this.color || 't').toUpperCase() + this.#minimalCode()
+    return (this.color || 't').toUpperCase() + minimalCode(this)
   }
 
   /**
@@ -1201,6 +1213,6 @@ export class Trax {
   @returns {string} the canonical position code
   */
   get canonical() {
-    return this.#minimalCode(this.turn === 2)
+    return minimalCode(this, this.turn === 2)
   }
 }

package/src/version.js

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

package/RELEASE.v1.3.0.md

@@ -1,12 +0,0 @@
-## 1.3.0 - 2026-08-16
-
-- Add `canonical`: a position code that collapses color-swapped duplicates in
-  addition to the rotation/mirror symmetry `normalize()` already handled
-- Deprecate `normalize()`/`normalized` in favor of `canonical`, to be removed in
-  version 2
-- `provisionalMove()` now accepts either a `canonical` or a (deprecated)
-  `normalized` code for `from`/`to`, so provisional moves saved before migrating
-  to `canonical` keep resolving correctly
-- Update dependencies
-- Resolve all new xo rule findings
-