@slugbugblue/trax 0.16.0 → 0.18.0

package/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm test

package/CHANGELOG.md

@@ -1,12 +1,38 @@
 # @slugbugblue/trax
 
+## 0.18.0 - 2023-02-05
+
+- Analysis improvements:
+
+  - Add `count.b(level)` and `count.w(level)` methods to an analysis to quickly
+    count the number of threats at a given level
+  - Remove faulty threats from an analysis
+  - Add additional threats for more puzzle solving mojo
+
+- Development environment enhancements:
+
+  - Added an initial benchmarking framework with puzzle benchmarks so far
+  - Added husky pre-commit hook to ensure npm test is run before a commit
+
+- CLI improvements:
+
+  - Puzzle information is now stored as notes, to make it searchable
+
+- More puzzles:
+
+  - Martin M. S. Pedersen contributed eleven new puzzles
+
+## 0.17.0 - 2022-12-29
+
+- The `import` CLI command now loads comments from a .trx file
+
 ## 0.16.0 - 2022-12-27
 
 - Added a `notes` command to the CLI to add comments to a game
 
-  - can be used as a text filter by the `list` command
-  - will be displayed by the `view` command
-  - will be included in the output generated by the `export` command
+  - all comments are included in the output generated by the `export` command
+  - the latest comment can be used as a text filter by the `list` command
+  - the latest comment is displayed by the `view` and `list` commands
 
 - Minor analysis improvements
 
@@ -22,9 +48,9 @@
   - Adjust puzzle category levels for harder puzzles
   - Add multiple hints when the puzzle can be solved multiple ways
 
-- Analysis engine improvements:
+- Analysis improvements:
 
-  - Analysis engine suggestions now "solve" all tough puzzles
+  - Analysis suggestions now "solve" all tough puzzles
   - Reworked threats to be more precise
   - Reworked scoring to add more nuance
 
@@ -35,9 +61,9 @@
   - `trax puzzles ls`: see all the puzzles
   - `trax puzzle new`: start a new puzzle
 
-- Analysis engine tests now include correctly suggesting the first move for
-  solving all tutorial and easy puzzles. As the threats database improves, we
-  will add more puzzles to the tests.
+- Analysis tests now include correctly suggesting the first move for solving all
+  tutorial and easy puzzles. As the threats database improves, we will add more
+  puzzles to the tests.
 
 ## 0.13.0 - 2022-11-25
 
@@ -130,7 +156,7 @@ variables from snake_case to camelCase.
   - `to`: the normalized position code of the board after the move
   - `via`: the move notation to go from `from` to `to`
 
-### 0.3.1 - 2022-01-07
+## 0.3.1 - 2022-01-07
 
 - Make a faster implementation of `trax.possible_locations()`
 - Display updates for tentative moves

package/Dockerfile

@@ -0,0 +1,5 @@
+FROM node:19.5.0-slim
+COPY . /src
+WORKDIR /src
+RUN npm install -g @slugbugblue/trax
+ENTRYPOINT ["/usr/local/bin/trax"]

package/README.md

@@ -13,7 +13,7 @@ Trax is a two-player boardless board game invented by David Smith. For more
 information about Trax, including its [rules][traxrules] and
 [history][traxhistory], see the official website at [traxgame.com][traxgame].
 
-This goal of this javascript project is to allow Trax to be played
+The goal of this javascript project is to allow Trax to be played
 programmatically. It can be used as an engine in a web browser, for example at
 [slugbugblue.com][sbb]; or in nodejs, for example by using the `trax` CLI
 provided as part of this project.
@@ -27,7 +27,7 @@ changes to the engine should meet the same standard.
 # Install into a javascript project
 npm install @slugbugblue/trax
 
-# Or install globally to use the trax CLI
+# Or install globally to use the trax CLI more easily
 npm install -g @slugbugblue/trax
 ```
 
@@ -43,11 +43,12 @@ avoid worries about the need to escape certain characters from the shell, and it
 can be easier to run multiple commands back to back.
 
 Help is available for the CLI through the use of the `help` command. Type
-`trax help` to see a list of the available commands, and `trax help play` to see
-information about the `play` command. Aliases and abbreviations are provided to
-minimize typing and to try to avoid the requirement of memorizing the commands.
-For example, the `list` command has an alias of `ls`, and the `select` command
-can be activated using `#`.
+`trax help` (or `npx trax help` with a local installation, or simply `help` if
+run interactively) to see a list of the available commands, and `trax help play`
+to see information about the `play` command. Aliases and abbreviations are
+provided to minimize typing and to try to avoid the requirement of memorizing
+the commands. For example, the `list` command has an alias of `ls`, and the
+`select` command can be activated using `#`.
 
 When you first launch the CLI, you can create a new game using the `new`
 command, and then enter moves for that game using `play`. Since `play` is likely
@@ -186,9 +187,14 @@ always ready to share his insights on the mechanics of the game, as well as
 various approaches to encoding its complexities. His undeserved kindness and
 infinite patience in indulging my many questions can never be repaid.
 
+Thanks for [Martin M. S. Pedersen][traxplayer] for contributing ideas, code, and
+puzzles to this effort. He's been [curating Trax puzzles][puzzlebook] and
+[coding solutions for Trax][gnutrax] for over two decades, and brings a lot of
+expertise.
+
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2019-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain
@@ -216,12 +222,15 @@ David Smith and heirs, and are not to be used without permission.
 [docs-engine]: docs/engine.md
 [docs-analyst]: docs/analyst.md
 [env-path]: https://www.npmjs.com/package/env-paths
+[gnutrax]: https://gnutrax.com
 [goldtoken]: https://goldtoken.com/
+[puzzlebook]: https://gnutrax.com/book
 [repo]: https://gitlab.com/slugbugblue/trax
 [sbb]: https://slugbugblue.com/
 [traxbook]: http://traxgame.com/shop_book.php
 [traxgame]: http://traxgame.com/
 [traxhistory]: http://www.traxgame.com/about_history.php
+[traxplayer]: mailto:traxplayer@gmail.com
 [traxpuzzles]: http://www.traxgame.com/games_puzzles.php
 [traxrules]: http://www.traxgame.com/about_rules.php
 [xdg]:

package/benchmark/benchmarks.json

@@ -0,0 +1,42 @@
+{
+  "0.17.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 2007
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 16,
+      "ms": 2664
+    },
+    "puzzles.firstmove.tough": {
+      "count": 1,
+      "ms": 76
+    },
+    "puzzles.firstmove.total": {
+      "count": 33,
+      "ms": 4838
+    }
+  },
+  "0.18.0": {
+    "puzzles.firstmove.tutorial": {
+      "count": 16,
+      "ms": 10164
+    },
+    "puzzles.firstmove.beginner": {
+      "count": 15,
+      "ms": 17864
+    },
+    "puzzles.firstmove.tough": {
+      "count": 26,
+      "ms": 30349
+    },
+    "puzzles.firstmove.advanced": {
+      "count": 1,
+      "ms": 427
+    },
+    "puzzles.firstmove.total": {
+      "count": 58,
+      "ms": 59031
+    }
+  }
+}

package/benchmark/puzzles.bench.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+/** Let's try to solve the puzzles
+ * @copyright 2023
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+import fs from 'node:fs'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { Trax } from '@slugbugblue/trax'
+import { suggest } from '@slugbugblue/trax/analyst'
+import { puzzles } from '@slugbugblue/trax/puzzles'
+import { version } from '@slugbugblue/trax/version'
+
+import * as tty from '@slugbugblue/trax/tty'
+
+let STUMPED = false
+const FINAL = {}
+
+const record = (name, data) => {
+  FINAL['puzzles.firstmove.' + name] = data
+}
+
+const timeString = (ms) => {
+  if (ms < 1000) {
+    return (ms === Math.floor(ms) ? String(ms) : ms.toFixed(2)) + ' ms'
+  }
+
+  ms /= 1000
+  if (ms < 60) return ms.toFixed(3) + ' sec'
+
+  const min = Math.floor(ms / 60)
+  ms -= min * 60
+  return String(min) + ' min ' + ms.toFixed(3) + ' sec'
+}
+
+const time = (ms) => timeString(Date.now() - ms)
+
+const out = (messages) => {
+  tty.outty(messages.join(' '))
+}
+
+const section = (title) => {
+  out([tty.color('===', 250), tty.color(title, 39), tty.color('===', 250)])
+}
+
+const success = (puzzle, ms) => {
+  out([tty.color('✓', 35), tty.color(puzzle, 250), tty.color(ms, 240)])
+}
+
+const puzzled = (puzzle, move) => {
+  tty.display(new Trax(puzzle.game, puzzle.notation))
+  tty.outty('Puzzled by ' + puzzle.id, 205)
+  out([
+    tty.color('  played', 250),
+    tty.color(move, 127),
+    tty.color('instead of', 250),
+    tty.color(puzzle.hint || puzzle.hints.join(' '), 39),
+  ])
+  STUMPED = true
+}
+
+const finalize = (name, ms, count) => {
+  out([
+    tty.color('Finished', 195),
+    tty.color(String(count) + ' ' + name + ' puzzles', 123),
+    tty.color('in ' + time(ms), 195),
+  ])
+}
+
+const solvePuzzleLevel = (name, level) => {
+  if (STUMPED) return 0
+  section(name + ' puzzles')
+  name = name.toLowerCase()
+  let count = 0
+  const begin = Date.now()
+  for (const puzzle of puzzles) {
+    if (puzzle.level !== level) continue
+    const start = Date.now()
+    const game = new Trax(puzzle.game, puzzle.notation)
+    const { move } = suggest(game).pick
+    const solved = puzzle.hint
+      ? move === puzzle.hint
+      : puzzle.hints
+      ? puzzle.hints.includes(move)
+      : false
+    if (solved) {
+      success(puzzle.id, time(start))
+      count++
+      record(name, { count, ms: Date.now() - begin })
+    } else {
+      puzzled(puzzle, move)
+      process.exitCode = level + 1
+      return count
+    }
+  }
+
+  finalize(name, begin, count)
+  return count
+}
+
+// Gather the benchmark data
+let total = 0
+const timer = Date.now()
+total += solvePuzzleLevel('Tutorial', 0)
+total += solvePuzzleLevel('Beginner', 1)
+total += solvePuzzleLevel('Tough', 2)
+total += solvePuzzleLevel('Advanced', 3)
+total += solvePuzzleLevel('Genius', 4)
+
+record('total', { count: total, ms: Date.now() - timer })
+tty.outty(
+  'Benchmark: ' + total + ' puzzles in ' + time(timer),
+  STUMPED ? 205 : 35,
+)
+
+tty.outty()
+
+// Load the previous benchmarks
+const FILE = new URL('benchmarks.json', import.meta.url)
+let CONTENTS
+try {
+  CONTENTS = fs.readFileSync(FILE, 'utf8')
+} catch {
+  CONTENTS = '{}'
+}
+
+const BENCHMARK = JSON.parse(CONTENTS)
+
+const PREV = Object.values(BENCHMARK).pop() || {}
+
+// Report the benchmark data
+const size = [0, 0, 0, 0, 0]
+const REPORT = []
+for (const name of Object.keys(FINAL)) {
+  const report = [
+    name,
+    String(FINAL[name].count) + ' puzzles',
+    'in ' + timeString(FINAL[name].ms),
+    'avg ' + timeString(FINAL[name].ms / FINAL[name].count),
+  ]
+  if (PREV[name]) {
+    const diff =
+      FINAL[name].ms / FINAL[name].count - PREV[name].ms / PREV[name].count
+    if (diff <= 0) {
+      report.push('-' + timeString(Math.abs(diff)), '35')
+    } else {
+      report.push('+' + timeString(diff), '208')
+    }
+  } else {
+    report.push('new', '250')
+  }
+
+  size[0] = Math.max(size[0], report[0].length)
+  size[1] = Math.max(size[1], report[1].length)
+  size[2] = Math.max(size[2], report[2].length)
+  size[3] = Math.max(size[3], report[3].length)
+  size[4] = Math.max(size[4], report[4].length)
+  REPORT.push(report)
+}
+
+for (const line of REPORT) {
+  out([
+    tty.color(line[0].padEnd(size[0]), 39),
+    tty.color(line[1].padStart(size[1]), 123),
+    tty.color(line[2].padStart(size[2]), 195),
+    tty.color(line[3].padEnd(size[3]), 245),
+    tty.color(line[4].padStart(size[4]), Number(line[5])),
+  ])
+}
+
+tty.outty()
+
+// Save the benchmark data to a file
+if (BENCHMARK[version]) {
+  tty.outty('Not overwriting existing benchmark data')
+} else {
+  BENCHMARK[version] = FINAL
+  try {
+    fs.writeFileSync(FILE, JSON.stringify(BENCHMARK, null, 2), 'utf8')
+    const filename = fileURLToPath(FILE)
+    tty.outty('Saved benchmark data to ' + tty.color(filename, 74))
+  } catch (error) {
+    tty.outty('Error saving benchmark data', 205)
+    tty.outty(String(error.code) + ' ' + error.message, 127)
+  }
+}

package/docs/analyst.md

@@ -79,6 +79,7 @@ themselves. The following keys are present in each edge space representation:
   connectable pair of lines with this color.
 - `zb` and `zw`: The character used in the black or white string representation
   of this space.
+- `idx`: The index of this edge space in the edge array.
 
 For the edge string, the following characters are used as a hopefully useful
 shorthand summary of the tiles surrounding the space. To make regex pattern
@@ -90,7 +91,7 @@ so that it appears as though all black tiles are white tiles.
 - `l`: both a black and a white line enter this space.
 - `a`: a white line enters this space, and the next white line in the edge is
   the other end of this line.
-- 'c': a white line enters this space, and the next white line in the edge forms
+- `c`: a white line enters this space, and the next white line in the edge forms
   a connectable pair with this line.
 - `m`: both a black and a white line enter this space, and the next white line
   in the edge is the other end of the white line.
@@ -119,6 +120,11 @@ following keys:
   may or may not be exactly the same as the pattern.
 - `at`: The index of the edge string at which the pattern match began.
 
+##### `faulty`
+
+Contains the same information as `threats` but for removed threats that were
+found to be faulty.
+
 ##### `score`
 
 Computes a rough "score" of the current position using the list of threats. A
@@ -135,6 +141,14 @@ because the scores can change depending on who has the initiative.
 
 #### methods
 
+##### `count.w(level)`
+
+Returns the number of threats for white at the given level.
+
+##### `count.b(level)`
+
+Returns the number of threats for black at the given level.
+
 ##### `inCave(loc)`
 
 For any given location, returns true if that location is found within a cave.
@@ -188,7 +202,7 @@ suggestion.
 
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2022-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain

package/docs/engine.md

@@ -42,7 +42,7 @@ class properties and methods:
 - `Trax.point(x, y)`: quick access to the [Point class][point-docs], for
   two-dimensional locations used internally by the Trax engine and which are
   required for some of the lower-level engine functions. Operates as a
-  constructor (without `new`) and returns a Point instance.
+  constructor (without `new`) and returns a [Point instance][point-docs].
 
 - `Trax.colorOf(playerNumber)`: Player 1 is white and Player 2 is black. So this
   is a quick function to turn `1` into `'w'` and `2` into `'b'`. Quick and
@@ -414,7 +414,7 @@ tie.
 
 ## License
 
-Copyright 2019-2022 Chad Transtrum
+Copyright 2019-2023 Chad Transtrum
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use
 the files in this project except in compliance with the License. You may obtain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",
@@ -26,9 +26,11 @@
     "trax": "./src/cli.js"
   },
   "scripts": {
+    "benchmark": "node benchmark/puzzles.bench.js",
     "test": "xo && c8 ava",
+    "prepare": "husky install",
     "preversion": "npm test",
-    "version": "genversion --es6 src/version.js && git add src/version.js",
+    "version": "genversion --es6 src/version.js && npm run benchmark || git add src/version.js benchmark/benchmarks.json",
     "postversion": "git push && git push --tags && npm publish"
   },
   "dependencies": {
@@ -40,6 +42,7 @@
     "ava": "^5.1.0",
     "c8": "^7.11.0",
     "genversion": "^3.0.2",
+    "husky": "^8.0.3",
     "prettier": "^2.6.1",
     "xo": "0.*"
   },

package/src/analyst.js

@@ -1,5 +1,5 @@
 /** Analyst module: provides analysis functions for Trax games.
- * @copyright 2022
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
@@ -170,6 +170,7 @@ const pairUp = (rawEdge) => {
  */
 const label = (rawEdge) => {
   const final = { w: '', b: '', edge: rawEdge }
+  let index = 0
   for (const space of rawEdge) {
     for (const bw of ['b', 'w']) {
       const colors = new Set([bw, 'l'])
@@ -186,6 +187,9 @@ const label = (rawEdge) => {
       space['z' + bw] = z
       final[bw] += z
     }
+
+    space.idx = index
+    index += 1
   }
 
   return final
@@ -260,14 +264,21 @@ export const Analysis = class {
   #game
   #scores = {}
   #threats = undefined
+  #faulty = { b: [], w: [] }
+  #partial = false
 
-  constructor(game) {
+  constructor(game, partial = false) {
     // Make a copy of the game
     this.#rules = game.rules
     this.#moves = game.moves
     this.#id = id()
     this.#notation = game.notation
     this.#game = new Trax(this.#rules, this.#moves, this.#id)
+    this.count = {
+      w: (level) => this.threats.w[level]?.length || 0,
+      b: (level) => this.threats.b[level]?.length || 0,
+    }
+    this.#partial = Boolean(partial)
   }
 
   get game() {
@@ -288,12 +299,20 @@ export const Analysis = class {
     return this.#edge
   }
 
+  /** Any faulty threats
+   * @returns {FaultyThreats}
+   */
+  get faulty() {
+    return this.#faulty
+  }
+
   /** All threats present in this position.
    * @returns {FoundThreatsCollection}
    */
   get threats() {
     if (!this.#threats) {
       this.#threats = { b: this.#applyThreats('b'), w: this.#applyThreats('w') }
+      if (!this.#partial) this.#validateThreats()
     }
 
     return this.#threats
@@ -528,7 +547,41 @@ export const Analysis = class {
       match: match[1], // The match is in the capturing group
       at: match.index,
       value: threat.value,
+      level: threat.depth,
+    }
+  }
+
+  /**
+   * @arg {FoundThreat} threat - a threat
+   * @arg {string} color - the player color
+   * @returns {InstanceType<typeof Point>[]} - locations relevant to the threat
+   */
+  #threatLocs(threat, color) {
+    const { edge } = this.edge
+    const max = edge.length
+    let index = threat.at
+    const locs = new Set([index])
+    while (threat.match.length > locs.size) {
+      index += 1
+      if (index >= max) index -= max
+      locs.add(index)
+      // Check to see if we have a connectable pair
+      if (edge[index]['p' + color]) {
+        const line = 'n' + color
+        const end = edge.find(
+          (space) =>
+            space.idx !== edge[index].idx && space[line] === edge[index][line],
+        )
+        if (end) {
+          // Add the opposite end and the space right before it, just in case
+          locs.add(end.idx)
+          locs.add(end.idx - 1)
+        }
+      }
     }
+
+    const value = [...locs].map((i) => new Point(edge[i]))
+    return value
   }
 
   /** Apply the threats to a color's regex-ready edge.
@@ -544,11 +597,10 @@ export const Analysis = class {
       const find = matches[threat.depth] || []
       for (const match of edge.matchAll(threat.rx)) {
         if (match.index >= length) break
+
+        // Avoid saving duplicates
         if (find.every((f) => f.at !== match.index || f.match !== match[1])) {
           find.push(this.#foundThreat(threat, match))
-        } else {
-          const duplicate = matches[99] || []
-          duplicate.push(this.#foundThreat(threat, match))
         }
       }
 
@@ -558,6 +610,74 @@ export const Analysis = class {
     return matches
   }
 
+  /** Clean up the list of matches, removing any false positives. */
+  #validateThreats() {
+    for (const bw of ['w', 'b']) {
+      /** @type FoundThreats */
+      const matches = this.#threats[bw]
+      for (const key of Object.keys(matches)) {
+        const level = Number(key)
+        if (level < 2) continue
+        /** @type {FoundThreat[]} */
+        const verified = []
+        const threats = matches[key]
+        for (const threat of threats) {
+          if (this.#canActivateThreat(threat, bw, level)) {
+            verified.push(threat)
+          } else {
+            this.#faulty[bw].push(threat)
+          }
+        }
+
+        if (verified.length > 0) {
+          matches[key] = verified
+        } else {
+          delete matches[key]
+        }
+      }
+    }
+  }
+
+  /** Determine if the given threat can be activated for this color
+   * @param {FoundThreat} threat - The threat to try to activate
+   * @param {string} color - The color this match belongs to
+   * @param {number} level - The depth level of this threat
+   * @returns {boolean}
+   */
+  #canActivateThreat(threat, color, level) {
+    const attacks = this.#threats[color][1]?.length ?? 0
+    const other = this.#threats[Trax.other(color)][1]?.length ?? 0
+    const higher = this.#threats[color][level - 1]?.length ?? 0
+    for (const loc of this.#threatLocs(threat, color)) {
+      for (const type of this.game.possibleTiles(loc)) {
+        const game = new Trax(this.game.rules, this.game.moves)
+        const result = game.dropTile(type, loc)
+        if (!result.valid) continue
+
+        // This might be a bad shortcut, but if we already have an attack here
+        // we just assume that this threat is also valid ...
+        if (game.over && game.turn === Trax.playerNumber(color)) return true
+
+        const { threats } = new Analysis(game, true)
+
+        // If we give our opponent an attack, this is a faulty move
+        const faulty = (threats[Trax.other(color)][1]?.length ?? 0) - other
+        if (faulty > 0) continue
+
+        // Activating the threat means we get an attack and a threat
+        const newAttacks = (threats[color][1]?.length ?? 0) - attacks
+        if (level === 2) {
+          if (newAttacks > 1) return true
+        } else {
+          const newThreats = (threats[color][level - 1]?.length ?? 0) - higher
+          if (newAttacks > 0 && newThreats > 0) return true
+        }
+      }
+    }
+
+    return false
+  }
+
   // Make a reasonable inspect representation of the analysis
   [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
     const sub = (object) => inspect(object, options).replace(/\n/g, '\n  ')

package/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/* Copyright 2022 Chad Transtrum
+/* Copyright 2022-2023 Chad Transtrum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -326,6 +326,14 @@ const CLI = {
     const id = newId(DATA)
     const trax = new Trax(puzzle.game, puzzle.notation, 'cli')
     const players = ['challenger', 'puzzlebot']
+    const notes = []
+    if (puzzle.title) notes.push({ move: 0, note: puzzle.title })
+    if (puzzle.desc) notes.push({ move: 0, note: puzzle.desc })
+    const player = [0, 'white', 'black'][puzzle.player]
+    notes.push(
+      { move: 0, note: 'Starting position ' + puzzle.notation },
+      { move: 0, note: `${puzzle.id}: ${player} to win by move ${puzzle.max}` },
+    )
     DATA.games[id] = {
       id,
       puzzle: puzzle.id,
@@ -335,6 +343,7 @@ const CLI = {
       max: puzzle.max,
       players: trax.turn === 1 ? players : players.reverse(),
       moves: trax.moves.join(' '),
+      notes,
     }
 
     if (DATA.puzzles[puzzle.id]) {

package/src/cmds/analyze.js

@@ -1,4 +1,4 @@
-/* Copyright 2022 Chad Transtrum
+/* Copyright 2022-2023 Chad Transtrum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -54,6 +54,17 @@ const listThreats = (threats, detailed) => {
   return summary.join('  ')
 }
 
+const listFaulty = (faulty) => {
+  const summary = []
+  for (const threat of faulty) {
+    summary.push(
+      `[L${threat.level} ${threat.at}:${threat.threat}:${threat.match}]`,
+    )
+  }
+
+  return 'Faulty: ' + summary.join(' ')
+}
+
 analyzeCmd.fn = (CLI, move) => {
   if (!String(CLI.GAME?.id)) {
     return CLI.error('No active game. Type "new" to start a game.')
@@ -75,18 +86,27 @@ analyzeCmd.fn = (CLI, move) => {
     return CLI.error('Game has ended.')
   }
 
-  const { edge, threats, scores } = analyze(trax)
+  const { edge, threats, scores, faulty } = analyze(trax)
 
-  if (detailed) CLI.out(edge.w)
+  if (detailed) CLI.out(CLI.color.white(edge.w))
   CLI.out(
     CLI.bubble('w', scores.w) +
       CLI.color.white(' ') +
       listThreats(threats.w, detailed),
   )
-  if (detailed) CLI.out(edge.b)
+
+  if (detailed) {
+    if (faulty.w.length > 0) CLI.out(CLI.color.white('') + listFaulty(faulty.w))
+    CLI.out(CLI.color.black(edge.b))
+  }
+
   CLI.out(
     CLI.bubble('b', scores.b) +
       CLI.color.black(' ') +
       listThreats(threats.b, detailed),
   )
+
+  if (detailed && faulty.b.length > 0) {
+    CLI.out(CLI.color.black('') + listFaulty(faulty.b))
+  }
 }

package/src/cmds/import-export.js

@@ -1,4 +1,4 @@
-/* Copyright 2022 Chad Transtrum
+/* Copyright 2022-2023 Chad Transtrum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -137,6 +137,79 @@ export const exportCmd = {
   ],
 }
 
+/** Interpret the rules string of a .trx file.
+ * @arg {string} r - rules string in lower case
+ * @returns {TraxVariant}
+ */
+const getRules = (r) =>
+  r.includes('loop') ? 'traxloop' : r.includes('8x8') ? 'trax8' : 'trax'
+
+/** Decode a .trx formatted string into a game, preserving players and comments.
+ * @arg {any} CLI - the CLI object
+ * @arg {string} content - the contents of the .trx file
+ * @returns {boolean} - true if a game was created
+ */
+const interpretFile = (CLI, content) => {
+  let rules
+  let trax
+  let players = []
+  const moves = []
+  const comments = []
+  for (const line of content.split('\n')) {
+    if (!line) continue
+    const [ln, ...comment] = line.split(/[#;]/)
+    if (ln) {
+      const lower = ln.toLowerCase()
+      if (!rules && lower.includes('trax')) {
+        rules = getRules(lower)
+      } else if (players.length === 0 && lower.includes(' vs ')) {
+        players = ln.split(' ').filter(Boolean)
+      } else {
+        moves.push(...ln.split(' '))
+      }
+    }
+
+    if (!trax && rules && (players.length > 0 || moves.length > 0)) {
+      trax = new Trax(rules)
+    }
+
+    if (moves.length > 0) {
+      if (!trax) return false
+      if (trax.gameOver) {
+        comments.push({
+          note: moves.map((c) => c.trim()).join(' '),
+          move: trax.move,
+        })
+      } else {
+        trax.playMoves(moves.filter(Boolean))
+        moves.splice(0, moves.length)
+      }
+    }
+
+    if (comment.length > 0) {
+      const note = comment.map((c) => c.trim()).join(' ')
+      if (!/^@slugbugblue\/trax cli\.js v/.test(note)) {
+        comments.push({
+          note,
+          move: trax?.move || 0,
+        })
+      }
+    }
+  }
+
+  if (!trax) return false
+
+  CLI.do('new', rules, ...players)
+  CLI.GAMES[String(CLI.GAME.id)].notes = comments
+  if (trax.moves.length > 0) {
+    CLI.do('play', ...trax.moves)
+  } else {
+    CLI.save()
+  }
+
+  return true
+}
+
 importCmd.fn = async (CLI, filename) => {
   cli = CLI
   if (!filename) {
@@ -156,35 +229,11 @@ importCmd.fn = async (CLI, filename) => {
       }
     }
 
-    if (!content) CLI.error(fsError.toString())
+    if (!content) return CLI.error(fsError.toString())
   }
 
-  if (content) {
-    let game
-    let players = []
-    const moves = []
-    for (const line of content.split('\n')) {
-      if (!line) continue
-      const ln = line.split(/[#;]/)[0]
-      if (!ln) continue
-      const lower = ln.toLowerCase()
-      if (!game && lower.includes('trax')) {
-        game = 'trax'
-        if (lower.includes('loop')) game = 'traxloop'
-        if (lower.includes('8x8')) game = 'trax8'
-      } else if (players.length === 0 && lower.includes(' vs ')) {
-        players = ln.split(' ').filter(Boolean)
-      } else {
-        moves.push(...ln.split(' '))
-      }
-    }
-
-    if (game) {
-      CLI.do('new', game, ...players)
-      CLI.do('play', ...moves.filter(Boolean))
-    } else {
-      CLI.error(filename + ' does not appear to be formatted correctly.')
-    }
+  if (!interpretFile(CLI, content)) {
+    CLI.error(filename + ' does not appear to be formatted correctly.')
   }
 }
 
@@ -204,6 +253,15 @@ const gameNotes = (move, notes) => {
   )
 }
 
+/** Join two strings together with a character with the appropriate joining
+ * character depending on the length of the strings.
+ * @arg {string} a - the first string
+ * @arg {string} b - the second string
+ * @returns {string} - both strings correctly joined
+ */
+const join = (a, b) =>
+  a.length === 0 ? b : a.length + b.length > 78 ? a + '\n' + b : a + ' ' + b
+
 /** Interleave the game moves with any notes, formatted for the export file.
  * @arg {string[]} moves - an array of move notations
  * @arg {GameNotes} notes? - The notes for a game
@@ -216,9 +274,7 @@ const interleaveNotation = (moves, notes) => {
   for (const move of moves) {
     const comments = gameNotes(moveNumber, notes)
     if (comments) {
-      const [lengthA, lengthC] = [annotation.length, comments.length]
-      const space = lengthA > 0 ? (lengthA + lengthC < 78 ? ' ' : '\n') : ''
-      content += space + annotation + comments
+      content += join(annotation, comments)
       annotation = ''
     }
 
@@ -234,9 +290,7 @@ const interleaveNotation = (moves, notes) => {
 
   const comments = gameNotes(moveNumber, notes)
   if (comments) {
-    const [lengthA, lengthC] = [annotation.length, comments.length]
-    const space = lengthA > 0 ? (lengthA + lengthC < 78 ? ' ' : '\n') : ''
-    content += space + annotation + comments
+    content += join(annotation, comments)
     annotation = ''
   }
 
@@ -278,12 +332,7 @@ exportCmd.fn = (CLI, id, filename) => {
         if (source.url) content += '\n; ' + source.url
       }
 
-      if (puzzle.title) content += '\n; ' + puzzle.title
-      if (puzzle.desc) content += '\n; ' + puzzle.desc
-      content += '\n; Starting position ' + puzzle.notation + '\n; '
-      const players = [0, 'white', 'black']
-      content += players[puzzle.player] + ' to win by move '
-      content += String(puzzle.max) + '\n'
+      content += '\n'
     }
   }
 

package/src/cmds/play-try.js

@@ -142,7 +142,7 @@ playCmd.fn = (CLI, ...moves) => {
 }
 
 tryCmd.fn = (CLI, move) => {
-  if (move.length === 0) {
+  if (!move || move.length === 0) {
     CLI.error('You must provide a move.')
     return CLI.do('help', 'try')
   }

package/src/cmds/view.js

@@ -1,4 +1,4 @@
-/* Copyright 2022 Chad Transtrum
+/* Copyright 2022-2023 Chad Transtrum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,6 +53,9 @@ viewCmd.fn = (CLI, move) => {
       CLI.bubble('b' + (trax.turn === 2 ? 'h' : ''), players[1]),
   )
   CLI.display(trax, players, undefined, show)
-  if (puzzle) CLI.out(CLI.color('Puzzle ' + puzzle))
+  if (puzzle && (!note || !note.includes(puzzle))) {
+    CLI.out(CLI.color('Puzzle ' + puzzle))
+  }
+
   if (note) CLI.out(CLI.color.help(note))
 }

package/src/engine.js

@@ -33,6 +33,13 @@ const notationRegex = /^([@a-z]+)(\d+)([/\\+])$/i
 const tileTypes = ['a', 'b', 'c', 'd', 'e', 'f']
 
 /** 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--+  +--#--+
+ *
  * Slashes are represented by / \ or +.
  * @readonly
  * @type {Record<ValidTiles, Slash>}

package/src/puzzles.js

@@ -1,5 +1,5 @@
 /** This is a collection of puzzles.
- * @copyright 2022
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
@@ -23,6 +23,10 @@ export const sources = {
     name: 'Donald G. Bailey',
     url: 'http://www.traxgame.com/games_puzzles.php',
   },
+  book1: {
+    name: 'Martin M. S. Pedersen',
+    url: 'https://gnutrax.com/book',
+  },
 }
 
 /** @type {Puzzle[]} */
@@ -396,7 +400,7 @@ export const puzzles = [
     level: 2,
     player: 2,
     max: 10,
-    hint: 'A0\\',
+    hints: ['A0\\', 'D0/'],
   },
   {
     id: 'eb8.trx',
@@ -440,7 +444,7 @@ export const puzzles = [
     level: 2,
     player: 1,
     max: 11,
-    hints: ['A0/', 'C4\\', 'D5/'],
+    hints: ['A0/', 'C4\\', 'D4/'],
   },
   {
     id: 'iw3.trx',
@@ -598,14 +602,15 @@ export const puzzles = [
   },
   {
     id: 'ib10.trx',
+    title: "Sucker's Opening",
     src: 'traxgame',
     game: 'traxloop',
-    notation: '@0/ A0\\ @2/',
+    notation: '@0/ @1/ B0\\',
     icon: '0a:cd',
     level: 3,
     player: 2,
-    max: 12,
-    hint: 'C1/',
+    max: 14,
+    hint: '@2\\',
   },
   {
     id: 'ib11.trx',
@@ -745,7 +750,7 @@ export const puzzles = [
     game: 'traxloop',
     notation: '@0/ A2+ A3+ A4\\ B3\\ B4+ B5\\ C5/ C4+ D4/ D5+ E5/ E4/',
     icon: 'd:b:ba:aeecd:0fdec',
-    level: 1,
+    level: 2,
     player: 2,
     max: 18,
     hints: ['B1+', 'B2/', 'D3+'],
@@ -758,8 +763,8 @@ export const puzzles = [
     icon: 'ecd',
     level: 3,
     player: 2,
-    max: 14,
-    hint: 'C2\\',
+    max: 16,
+    hints: ['A0+', 'C2\\'],
   },
   {
     id: 'hb4.trx',
@@ -805,6 +810,127 @@ export const puzzles = [
     max: 16,
     hint: 'B1+',
   },
+  {
+    id: 'book_01.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ @1+ B0/ C1+ D2/ C3/',
+    icon: 'dcba:bdcd:1dc',
+    level: 2,
+    player: 1,
+    max: 13,
+    hint: '@2/',
+  },
+  {
+    id: 'book_02.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0+ B1+ C1/ B0/ B0/ B0/ B0/ D5/ E5/ E6+ C4/ C3+ B6+',
+    icon: '0df:0ca:0df:cd:eecdc:0efae',
+    level: 2,
+    player: 2,
+    max: 18,
+    hints: ['D2\\', 'D3/'],
+  },
+  {
+    id: 'book_03.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ @1/ @1+ @1/ @1+ C0/ D1/ E1+ D0+ E1+ F1\\ E0+',
+    icon: '3e:1deef:1cdec:bdecd',
+    level: 3,
+    player: 1,
+    max: 19,
+    hint: 'C1\\',
+  },
+  {
+    id: 'book_04.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0+ B1/ @1/ A0/ C3/ A4+ @4+ @3/ a5\\',
+    icon: '1caf:1dec:dcafd:aeec:fd',
+    level: 3,
+    player: 2,
+    max: 16,
+    hint: 'C0/',
+  },
+  {
+    id: 'book_05.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ @1/ B0+ @2+ A0/ @2+',
+    icon: 'cd:ecde:0ecd',
+    level: 2,
+    player: 1,
+    max: 15,
+    hints: ['B4\\', 'C4/'],
+  },
+  {
+    id: 'book_07.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ A2+ A0+ @2\\ B0+ C1+ B0/ B0/ A2+',
+    icon: 'cdf:eca:0ee:0e:fd:0b',
+    level: 2,
+    player: 2,
+    max: 14,
+    hint: 'C6+',
+  },
+  {
+    id: 'book_08.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ @1/ A2/ A0/ B1/ @1+ @1/ A0/ @1/',
+    icon: 'cdfaf:0cbdc:0facd:0afdc',
+    level: 3,
+    player: 2,
+    max: 18,
+    hint: 'A0\\',
+  },
+  {
+    id: 'book_09.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ @1/ B0/ B0/ A0/ A5/ @3\\ @4/',
+    icon: '1d:1cd:dfdc:cacd:0fdc',
+    level: 3,
+    player: 1,
+    max: 15,
+    hint: 'A2\\',
+  },
+  {
+    id: 'book_10.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0/ A0+ A0/ A4+ A0/ A0/ B4+ C4/ @4+ @4/ @4/',
+    icon: '2caf:2dfa:2caf:cdeeec:fafd:2b',
+    level: 2,
+    player: 2,
+    max: 18,
+    hint: 'E6+',
+  },
+  {
+    id: 'book_11.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0+ B1+ C1/ C0/ B0/ @3+',
+    icon: '1d:1cd:eeec',
+    level: 1,
+    player: 1,
+    max: 9,
+    hint: 'B1\\',
+  },
+  {
+    id: 'book_12.trx',
+    src: 'book1',
+    game: 'traxloop',
+    notation: '@0+ B1+ C1/ C0/ B0/ D2+',
+    icon: '0d:0cde:eecd',
+    level: 3,
+    player: 1,
+    max: 15,
+    hint: 'B4\\',
+  },
 ]
 
 puzzles.sort(

package/src/threats.js

@@ -1,5 +1,5 @@
 /** Threats database: hand-coded threats
- * @copyright 2022
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
@@ -89,7 +89,7 @@ export const ThreatsDB = class {
 
   add(depth, pattern, reforms = false) {
     this.#depth = Math.max(depth, this.#depth)
-    if (pattern in this.#db) throw new Error('Duplicate pattern:' + pattern)
+    if (pattern in this.#db) throw new Error('Duplicate pattern: ' + pattern)
     this.#db[pattern] = new Threat(depth, pattern, reforms)
     return this.#db[pattern]
   }
@@ -175,6 +175,8 @@ for (const one of Object.keys(corners)) {
   threats.compose(3, one + '!bbrmW') // Same, but slightly different layout
   threats.compose(3, 'ab*lrb¡' + one) // Reverse
   threats.compose(3, 'alrbb¡' + one) // Reverse of different layout
+  threats.compose(4, one + '!b*b¡ra?lr') // Partial edge with attack into hollow
+  threats.compose(4, 'rm?wr!b*b¡' + one) // Reverse
 
   for (const two of Object.keys(corners)) {
     end = two.replace(/[aA]/, 'm').replace('C', 'p')
@@ -188,9 +190,14 @@ for (const one of Object.keys(corners)) {
     if (post) {
       threats.compose(2, one + post + '!' + end) // L
       threats.compose(3, one + post + '!br' + end) // Three-stage
+      threats.compose(3, one + post + 'r' + end) // Defense forms an L
       threats.compose(3, one + '!br¡?' + end) // Attack to form an L threat
     }
 
+    if (pre && post) {
+      threats.compose(3, start + 'r' + end) // Defense forms an L
+    }
+
     threats.compose(3, one + '!b*b¡' + two) // Edge threat
   }
 }
@@ -200,3 +207,17 @@ threats.add(3, 'Arlbmwr') // Reversed
 
 threats.add(4, 'rb¡c?w!br') // Connectable pair on an edge
 threats.add(4, 'ArlbmrW') // Wide cave ready for an attack
+
+// Threats to solve puzzle iw1.trx
+threats.add(5, 'A?rwarlrar?W') // Back to back white corners next to a corner
+threats.add(4, 'A?rlr!bralrar?W') // ... activated ... becomes:
+threats.add(4, 'A?rlrbrmrwar?W') // Corner surrounded by corners
+threats.add(4, 'A?rlr!bramrar?W') // ... activated ...
+threats.add(3, 'A?rlr!brm?wr!brmrW') // ... defended ...
+
+// Threats to solve puzzle ib10.trx
+threats.add(6, 'Arw!b?rarlr') // Sucker's Opening
+threats.add(5, 'Arw!b?brbralr') // ... activated ... becomes:
+threats.add(4, 'Arw!b?brb¡arbW') // Wide corner opposite nearly formed edge
+threats.add(5, 'Arw!b?brb¡rmrW') // ... or hollow corner opposite same edge
+threats.add(4, 'Arw!b?brb¡rmwr') // ... activated ...

package/src/types.d.ts

@@ -1,4 +1,5 @@
 /** Type information.
+ * @copyright 2022-2023
  * @author Chad Transtrum <chad@transtrum.net>
  * @license Apache-2.0
  */
@@ -44,6 +45,7 @@ type EdgeLocation = {
   pw?: boolean
   zb?: string
   zw?: string
+  idx?: number
 }
 
 type EdgeObject = {
@@ -53,7 +55,19 @@ type EdgeObject = {
 }
 
 /** Object representing a concrete threat found in a position. */
-type FoundThreat = { threat: string; match: string; at: number; value: number }
+type FoundThreat = {
+  threat: string
+  match: string
+  at: number
+  value: number
+  level: number
+}
+
+/** Threats found for each color that cannot actually be activated. */
+type FaultyThreats = {
+  b: FoundThreat[]
+  w: FoundThreat[]
+}
 
 /** An object with keys representing each level, with arrays for each threat of
  * that level. */

package/src/version.js

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