@slugbugblue/trax 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @slugbugblue/trax
 
+## 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
+
+- Minor analysis improvements
+
+## 0.15.0 - 2022-12-14
+
+- Added shared `puzzles` commands to the CLI:
+
+  - `trax ls puzzles`: see all the puzzles
+  - `trax new puzzle`: start a new puzzle
+
+- Puzzle improvements:
+
+  - Adjust puzzle category levels for harder puzzles
+  - Add multiple hints when the puzzle can be solved multiple ways
+
+- Analysis engine improvements:
+
+  - Analysis engine suggestions now "solve" all tough puzzles
+  - Reworked threats to be more precise
+  - Reworked scoring to add more nuance
+
 ## 0.14.0 - 2022-12-05
 
 - Added `puzzles` to the CLI:
@@ -7,8 +35,9 @@
   - `trax puzzles ls`: see all the puzzles
   - `trax puzzle new`: start a new puzzle
 
-- Bot tests now include solving all tutorial and easy puzzles. As the bot
-  improves, we will add more puzzles to the tests.
+- 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.
 
 ## 0.13.0 - 2022-11-25
 

package/README.md

@@ -1,6 +1,11 @@
 # Trax
 
-Trax game-playing engine and etc.
+This project aims to provide tools for working with Trax games in Javascript.
+
+- Trax game-playing engine
+- Position analysis engine
+- Over 50 puzzles to help hone your Trax skills
+- Command-line interface for ease of use
 
 ## Description
 
@@ -32,10 +37,10 @@ The command-line interface is provided as `trax`, available in your path if
 installed globally, or in the `node_modules/.bin` directory and runnable using
 `npx trax` if installed locally.
 
-The CLI can be used interactively by passing the `--interactive` or `-i` flag.
-When run interactively, you can avoid worries about the need to escape certain
-characters from the shell, and it can be easier to run multiple commands back to
-back.
+The CLI can be used interactively by running the command with no parameters or
+by passing the `--interactive` or `-i` flag. When run interactively, you can
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slugbugblue/trax",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Trax game engine and friends",
   "keywords": [
     "trax",

package/src/analyst.js

@@ -1,26 +1,15 @@
-/* Copyright 2022 Chad Transtrum
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *   http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+/** Analyst module: provides analysis functions for Trax games.
+ * @copyright 2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
  */
 
-// Analyst module: provides analysis functions for Trax games
-
 import { Point } from '@slugbugblue/trax/point'
 import { Trax } from '@slugbugblue/trax'
 
 import { threats } from '@slugbugblue/trax/threats'
 
-// Helpers
+/** Helper function to generate a unique id for the analysis. */
 const id = () => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789'
   let code = ''
@@ -31,14 +20,27 @@ const id = () => {
   return 'analysis-' + code
 }
 
-// A sort function for hashes with a numeric score property
+/** A sort function for hashes with a numeric score property.
+ * @arg {PositionScore} a - The first Position Score to be compared
+ * @arg {PositionScore} b - The second Position Score to be compared
+ * @returns {number} a.score <=> b.score
+ */
 const byScoreDesc = (a, b) => b.score - a.score
 
-// A filter function factory to remove scores not within x points of the highest score
+/** A filter function factory to remove scores not within x points of the
+ * highest score.
+ * @arg highest {number} - The highest score
+ * @arg tolerance {number} - How close another score must be to be included
+ * @returns {(s:PositionScore)=>boolean} a filter function
+ */
 const withinX = (highest, tolerance) => (s) =>
   s.score === highest || highest - s.score <= tolerance
 
-// Return a random element of an array
+/** Return a random element of an array.
+ * @template T
+ * @arg {T[]} array - an array of elements
+ * @returns {T} one of the elements at random
+ */
 const randomDraw = (array) => array[Math.floor(Math.random() * array.length)]
 
 // Make parseInt a little shorter
@@ -56,12 +58,16 @@ const edgeColor = (tile, dir) => {
 
 const encodeNumber = (n) => String.fromCodePoint(48 + n)
 
-// Explore a raw edge and update cave information
+/** Explore a raw edge and update cave information.
+ * @arg {RawEdge} rawEdge - the raw edge information
+ * @returns {RawEdge}
+ */
 const spelunk = (rawEdge) => {
   for (let index = 1; index < rawEdge.length - 1; index++) {
     if (rawEdge[index].t === 'C') {
-      const previous = rawEdge[index - 1] || {}
-      const next = rawEdge[index + 1] || {}
+      const blank = () => ({ x: 0, y: 0, c: '', t: '' })
+      const previous = rawEdge[index - 1] || blank()
+      const next = rawEdge[index + 1] || blank()
       if (next.t === 'c') next.t = 'C'
       if (previous.t === 'c') {
         previous.t = 'C'
@@ -78,7 +84,10 @@ const spelunk = (rawEdge) => {
   return rawEdge
 }
 
-// Combine hollows into a single item in the raw edge array
+/** Combine hollows into a single item in the raw edge array.
+ * @arg {RawEdge} rawEdge
+ * @returns {RawEdge}
+ */
 const hollowOut = (rawEdge) => {
   for (let index = 1; index < rawEdge.length - 1; index++) {
     const space = rawEdge[index]
@@ -93,8 +102,13 @@ const hollowOut = (rawEdge) => {
   return rawEdge
 }
 
-// Supposedly deep nesting is bad, so we broke this out of "pairUp" for
-// "better" code, even though this is useless on its own ...
+/** Supposedly deep nesting is bad, so we broke this out of "pairUp" for
+ * "better" code, even though this is useless on its own ...
+ * @arg {RawEdge} rawEdge
+ * @arg {number} index
+ * @arg {string} color
+ * @pairs {Record<string, number>}
+ */
 const findPair = (rawEdge, index, color, pairs) => {
   const colors = new Set([color, 'l'])
   const space = rawEdge[index]
@@ -131,8 +145,12 @@ const findPair = (rawEdge, index, color, pairs) => {
   }
 }
 
-// Find connectable pairs in the raw edge
+/** Find connectable pairs in the raw edge.
+ * @arg {RawEdge} rawEdge
+ * @returns {RawEdge}
+ */
 const pairUp = (rawEdge) => {
+  /** @type Record<string, number> */
   const pairs = {}
   for (const [index, space] of rawEdge.entries()) {
     for (const bw of ['w', 'b']) {
@@ -146,7 +164,10 @@ const pairUp = (rawEdge) => {
   return rawEdge
 }
 
-// Label and finalize the raw edge
+/** Label and finalize the raw edge.
+ * @arg {RawEdge} rawEdge
+ * @returns {EdgeObject}
+ */
 const label = (rawEdge) => {
   const final = { w: '', b: '', edge: rawEdge }
   for (const space of rawEdge) {
@@ -170,48 +191,73 @@ const label = (rawEdge) => {
   return final
 }
 
-const threatValues = (threatsArray) => {
-  return threatsArray.length
-  // Hm. Maybe we don't need this ...
-  // let count = 0
-  // for (const threat of threatsArray) count += threat.value
-  // return count
-}
+/** Quick way to get the number of items in an array.
+ * @returns {number} - length of the array
+ */
+const length = (array) => array?.length || 0
 
-const attackScore = (from, level) => {
-  const count = threatValues(from[level] || [])
-  if (level < 1) return count
-  return count * 10 ** (threats.maxDepth - level + 1)
+/** Calculate the points for the number of threats at a particular level.
+ * @arg {FoundThreats} from - the threats found for a certain player
+ * @arg {number} level - the level to calculate the points for
+ * @arg {number} [as] - if included, the level the points should be calculated as
+ * @return {number} the number of points for the level
+ */
+const attackScore = (from, level, as) => {
+  const count = length(from[level])
+  const calculateAs = Math.min(as === undefined ? level : as, threats.maxDepth)
+  if (calculateAs < 1) return count
+  return count * 10 ** (threats.maxDepth - calculateAs + 1)
 }
 
-// Shortcut to get the number of attacks
-const attackCount = (from) => threatValues(from['1'] || [])
+/** Shortcut to get the number of attacks.
+ * @arg {FoundThreats} from - the threats found for a certain player
+ * @returns {number} the number of attacks (win on next move) present
+ */
+const attackCount = (from) => length(from['1'])
 
-// Shortcut to get the number of passive threats
+/** Shortcut to get the number of passive threats
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {number} the number of passive threats (win in 2 or more moves)
+ */
 const threatCount = (from) => {
   let count = 0
   for (const [depth, array] of Object.entries(from)) {
-    count += int(depth) > 1 ? threatValues(array) : 0
+    count += int(depth) > 1 ? length(array) : 0
   }
 
   return count
 }
 
-const passiveAttack = (from) =>
+/** Shortcut to determine if we have an active attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
+const activeAttack = (from) =>
   attackCount(from) > 1 || (attackCount(from) === 1 && threatCount(from) > 0)
 
-// Maybe we don't need this one
-// const underAttack = (from) => attackCount(from) + threatCount(from) > 0
+/** Shortcut to determine if we have a passive attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
+const passiveAttack = (from) => threatCount(from) > 1
+
+/** Shortcut to determine if we are under attack.
+ * @arg {FoundThreats} from - the threats found for a player
+ * @returns {boolean}
+ */
+const underAttack = (from) => attackCount(from) + threatCount(from) > 0
 
 // Analysis class
 export const Analysis = class {
-  /** @type TraxVariant */
+  /** @type {TraxVariant} */
   #rules = 'trax'
   #id = 'analysis'
+  /** @type {string[]} - List of moves to arrive at this position */
   #moves = []
   #notation = ''
   #edge = undefined
-  #game = {}
+  /** @type {Trax} */
+  #game
   #scores = {}
   #threats = undefined
 
@@ -242,6 +288,9 @@ export const Analysis = class {
     return this.#edge
   }
 
+  /** All threats present in this position.
+   * @returns {FoundThreatsCollection}
+   */
   get threats() {
     if (!this.#threats) {
       this.#threats = { b: this.#applyThreats('b'), w: this.#applyThreats('w') }
@@ -274,6 +323,69 @@ export const Analysis = class {
     return count > 2
   }
 
+  /** Determine the points of the currently active player.
+   * @returns {[number, number]} - the points for this player, and the level
+   * of the most dangerous threat
+   */
+  #activeScore() {
+    let score = 0
+    let threatLevel = Number.POSITIVE_INFINITY
+    const { game } = this
+    const active = this.threats[game.color]
+
+    // First examine the active player
+    for (const level of Object.keys(active).map((i) => int(i))) {
+      if (level > 0) threatLevel = Math.min(threatLevel, level)
+      score += attackScore(active, level)
+    }
+
+    return [score, threatLevel]
+  }
+
+  /** Determine the points of the waiting player.
+   * @arg {Color} color - the color for which we are generating the score
+   * @arg {number} threatLevel - the lowest level for which the active player
+   * has an active threat
+   * @returns {[number, number]} - the points for this player and the multiplier
+   * to be applied to the other player's points
+   */
+  #inactiveScore(color, threatLevel) {
+    const { game } = this
+    const active = this.threats[game.color]
+    const inactive = this.threats[Trax.other(game.color)]
+
+    // Is the color we are looking at the passive player?
+    const passive = game.color !== color
+
+    // Is the inactive player activating known threats?
+    const attacking = activeAttack(inactive)
+
+    // Was the inactive player unable to clear all threats?
+    const defending = !attacking && underAttack(active)
+
+    // Does the inactive player have multiple threats
+    const threatening = !attacking && passiveAttack(inactive)
+
+    // If calc is false, attacks and threats are treated as corners
+    const calc = !passive || attacking || defending || threatening
+
+    // If the current player does not hold the initiative, reduce the score
+    const multiplier = passive && attacking && threatLevel > 1 ? 0.1 : 1
+
+    let score = 0
+
+    // Now calculate the effects of the passive player
+    for (const level of Object.keys(inactive).map((i) => int(i))) {
+      const calcLevel = level > 0 && defending ? level + threatLevel - 1 : level
+      let points = attackScore(inactive, level, calc ? calcLevel : 0)
+      if (level === threatLevel) points = passive ? Math.floor(points / 2) : 0
+      if (passive && threatening) points = Math.floor(points / 2)
+      score += points
+    }
+
+    return [score, multiplier]
+  }
+
   #score(color) {
     if (this.#scores[color] === undefined) {
       const { game } = this
@@ -283,30 +395,11 @@ export const Analysis = class {
         return this.#scores[color]
       }
 
-      let score = 0
+      const [currentPlayer, threatLevel] = this.#activeScore()
+      const [nextPlayer, multiplier] = this.#inactiveScore(color, threatLevel)
 
-      const active = this.threats[game.color]
-      const inactive = this.threats[Trax.other(game.color)]
-      let advantage = Number.POSITIVE_INFINITY
-
-      // First examine the active player
-      for (const level of Object.keys(active).map((i) => int(i))) {
-        if (level > 0 && level < advantage) advantage = level
-        score += attackScore(active, level)
-      }
-
-      const passive = game.color !== color
-      const calc = !passive || passiveAttack(inactive)
-
-      // Calculate the effects of the passive player first
-      for (const level of Object.keys(inactive).map((i) => int(i))) {
-        if (level > advantage) continue
-        let points = calc || level === 0 ? attackScore(inactive, level) : 1
-        if (level === advantage) points = passive ? Math.floor(points / 2) : 0
-        score -= points
-      }
-
-      if (passive) score *= -1
+      let score = Math.floor(currentPlayer * multiplier) - nextPlayer
+      if (score && game.color !== color) score *= -1
 
       this.#scores[color] = score
     }
@@ -369,6 +462,7 @@ export const Analysis = class {
   // Trace the edge of the playing area
   #traceEdge() {
     const { game } = this
+    /** @type {RawEdge} */
     const rawEdge = []
     const lines = {}
     const count = { w: 0, b: 0 }
@@ -423,8 +517,26 @@ export const Analysis = class {
     return label(pairUp(hollowOut(spelunk(rawEdge))))
   }
 
-  // Apply the threats to a color's regex-ready edge
+  /** Compose the threat into a FoundThreat object.
+   * @arg {Threat} threat - the threat that has been found
+   * @arg {RegExpMatchArray} match - the matching item
+   * @returns {FoundThreat}
+   */
+  #foundThreat(threat, match) {
+    return {
+      threat: threat.pattern,
+      match: match[1], // The match is in the capturing group
+      at: match.index,
+      value: threat.value,
+    }
+  }
+
+  /** Apply the threats to a color's regex-ready edge.
+   * @arg {Color} color - the color to find threats for
+   * @returns {FoundThreats}
+   */
   #applyThreats(color) {
+    /** @type {FoundThreats} */
     const matches = {}
     const { length } = this.edge[color]
     const edge = this.edge[color].repeat(2)
@@ -432,13 +544,11 @@ export const Analysis = class {
       const find = matches[threat.depth] || []
       for (const match of edge.matchAll(threat.rx)) {
         if (match.index >= length) break
-        if (find.every((f) => f.at !== match.index || f.match !== match[0])) {
-          find.push({
-            threat: threat.pattern,
-            match: match[0],
-            at: match.index,
-            value: threat.value,
-          })
+        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))
         }
       }
 
@@ -480,12 +590,19 @@ export const Analysis = class {
   }
 }
 
+/** Analyze a game position.
+ * @arg {Trax} game - the position to analyze
+ * @returns {Analysis}
+ */
 export const analyze = (game) => new Analysis(game)
 
 export const Suggestion = class {
+  /** @type {PositionScore[]} */
   all = []
+  /** @type {PositionScore[]} */
   options = []
-  pick = {}
+  /** @type {PositionScore} */
+  pick
   ms = 0
 
   constructor(analyzed, ms) {

package/src/cli.js

@@ -38,6 +38,7 @@ import {
 } from './cmds/import-export.js'
 import { listCmd } from './cmds/list.js'
 import { newCmd } from './cmds/new.js'
+import { notesCmd } from './cmds/notes.js'
 import { playCmd, tryCmd } from './cmds/play-try.js'
 import { puzzlesCmd } from './cmds/puzzles.js'
 import { selectCmd } from './cmds/select.js'
@@ -87,6 +88,7 @@ const plugins = [
   importCmd,
   listCmd,
   newCmd,
+  notesCmd,
   playCmd,
   puzzlesCmd,
   quitCmd,
@@ -197,14 +199,6 @@ const DATA = { games: {}, puzzles: {} }
 
 // CLI context object for plugins
 const CLI = {
-  // Notation manipulation
-  fixNotation(move) {
-    if (move.endsWith('b')) return move.slice(0, -1) + '\\'
-    if (move.endsWith('s')) return move.slice(0, -1) + '/'
-    if (move.endsWith('p')) return move.slice(0, -1) + '+'
-    return move
-  },
-
   // Quick access to all stored games
   get GAMES() {
     return DATA.games || {}
@@ -283,6 +277,28 @@ const CLI = {
     CLI.out(CLI.color.error(text))
   },
 
+  // Notation manipulation
+  fixNotation(move) {
+    if (move.endsWith('b')) return move.slice(0, -1) + '\\'
+    if (move.endsWith('s')) return move.slice(0, -1) + '/'
+    if (move.endsWith('p')) return move.slice(0, -1) + '+'
+    return move
+  },
+
+  load(id) {
+    if (!id) id = Object.keys(DATA.games || {})[0]
+    if (id && DATA.games?.[id] && DATA.games[id].rules) {
+      if (id !== String(CONFIG.id)) {
+        CONFIG.id = id
+        saveConfig()
+      }
+
+      const game = CLI.GAME
+      if (!game.players) game.players = ['white', 'black']
+      CLI.TRAX = new Trax(game.rules, game.moves, 'cli')
+    }
+  },
+
   newGame(rules, players, moves) {
     // Creates a new game
     const id = newId(DATA)
@@ -367,6 +383,11 @@ const CLI = {
     return undefined
   },
 
+  /** Write out the current data to disk. */
+  save() {
+    saveData()
+  },
+
   setGame(moves) {
     // Updates the moves for the current game
     const game = CLI.GAME
@@ -390,20 +411,6 @@ const CLI = {
     }
   },
 
-  load(id) {
-    if (!id) id = Object.keys(DATA.games || {})[0]
-    if (id && DATA.games?.[id] && DATA.games[id].rules) {
-      if (id !== String(CONFIG.id)) {
-        CONFIG.id = id
-        saveConfig()
-      }
-
-      const game = CLI.GAME
-      if (!game.players) game.players = ['white', 'black']
-      CLI.TRAX = new Trax(game.rules, game.moves, 'cli')
-    }
-  },
-
   // Pass through functions
   bubble: tty.bubble,
   display: tty.display,

package/src/cmds/analyze.js

@@ -22,7 +22,7 @@ const notationRx = /^[@a-z]+\d+[bps/\\+]$/i
 
 export const analyzeCmd = {
   name: 'analyze',
-  args: '[<move>]',
+  args: '[move]',
   comp: '<play>',
   desc: 'analyze a position',
   help: [
@@ -44,7 +44,7 @@ const listThreats = (threats, detailed) => {
     const items = []
     if (detailed) {
       for (const item of threats[level]) {
-        items.push('[' + item.at + ':' + item.match + ']')
+        items.push('[' + item.at + ':' + item.threat + ':' + item.match + ']')
       }
     }
 

package/src/cmds/import-export.js

@@ -188,6 +188,63 @@ importCmd.fn = async (CLI, filename) => {
   }
 }
 
+/** Get all the notes for a certain move.
+ * @arg {number} move - The move number
+ * @arg {GameNotes} notes? - The notes for a game
+ * @returns {string} - Notes formatted for this move, or empty string if none
+ */
+const gameNotes = (move, notes) => {
+  notes = notes || []
+  const moveNotes = notes.filter((n) => n.move === move)
+  if (moveNotes.length === 0) return ''
+  return (
+    '; ' +
+    moveNotes.map((n) => n.note.replaceAll('\n', '\n; ')).join('\n; ') +
+    '\n'
+  )
+}
+
+/** 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
+ * @returns {string} - A string that can be placed into an export file
+ */
+const interleaveNotation = (moves, notes) => {
+  let content = ''
+  let moveNumber = 0
+  let annotation = ''
+  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
+      annotation = ''
+    }
+
+    moveNumber += 1
+    const notation = String(moveNumber) + '. ' + move
+    if (annotation.length + notation.length < 79) {
+      annotation += (annotation.length > 0 ? ' ' : '') + notation
+    } else {
+      content += '\n' + annotation
+      annotation = notation
+    }
+  }
+
+  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
+    annotation = ''
+  }
+
+  content += annotation
+  if (!content.endsWith('\n')) content += '\n'
+  return content
+}
+
 exportCmd.fn = (CLI, id, filename) => {
   cli = CLI
   let game = CLI.GAME
@@ -218,7 +275,7 @@ exportCmd.fn = (CLI, id, filename) => {
       content += '; Puzzle ' + game.puzzle
       if (source) {
         content += ' provided courtesy of ' + source.name
-        if (source.url) content += ' (' + source.url + ')'
+        if (source.url) content += '\n; ' + source.url
       }
 
       if (puzzle.title) content += '\n; ' + puzzle.title
@@ -230,7 +287,8 @@ exportCmd.fn = (CLI, id, filename) => {
     }
   }
 
-  content += trax.notation + '\n'
+  content += interleaveNotation(trax.moves, game.notes)
+
   if (filename) filename = filename.replace(/[^ a-z\d.~/]/g, '')
   if (filename) {
     const fname = filename.split('/').pop()

package/src/cmds/list.js

@@ -15,6 +15,8 @@
 
 // CLI list command
 
+import process from 'node:process'
+
 import { Trax } from '@slugbugblue/trax'
 
 export const listCmd = {
@@ -35,7 +37,7 @@ export const listCmd = {
     '  #id: match a game or a certain number of moves',
     '  "active" or "over": whether a game is in progress or not',
     '  "loop" or "8x8" or "trax": filter by game type',
-    "  <other text>: match a player's name",
+    "  <other text>: match a player's name or the latest game note",
     'Add the "reverse" option to reverse the sort order.',
   ],
 }
@@ -80,14 +82,16 @@ const listSort = (list, filters) => {
     } else if (['over', 'active'].includes(by)) {
       list = list.filter((g) => (by === 'over' ? g.over : !g.over))
     } else {
-      list = list.filter(
-        (g) =>
+      list = list.filter((g) => {
+        return (
           g.id.endsWith(by) ||
           Trax.names[g.rules].toLowerCase().includes(by) ||
           g.p1.toLowerCase().includes(by) ||
           g.p2.toLowerCase().includes(by) ||
-          g.moves.startsWith(by + ' '),
-      )
+          g.moves.startsWith(by + ' ') ||
+          g.note.includes(by)
+        )
+      })
     }
   }
 
@@ -96,19 +100,37 @@ const listSort = (list, filters) => {
   return list
 }
 
+/** Find how many columns are left over after all the other columns arefilled.
+ * @arg {Record<string, number>} sizes
+ * @returns {number} number of columns left over
+ */
+const leftover = (sizes) => {
+  let left = process.stdout.columns
+  for (const size of Object.values(sizes)) {
+    left -= size
+  }
+
+  return left
+}
+
 listCmd.fn = (CLI, ...filters) => {
   if (Object.keys(CLI.GAMES).length === 0) {
     return CLI.error('No games. Type "new" to start a new game.')
   }
 
+  const puzzle = filters.find((f) => f.length > 1 && 'puzzles'.startsWith(f))
+  if (puzzle) return CLI.do('puzzles', ...filters.filter((f) => f !== puzzle))
+
   let list = []
   const size = {
+    spacing: 13, // Amount of space taken up by fixed-length and between columns
     id: 1,
     name: 1,
     moves: 1,
     p1: 1,
     p2: 1,
   }
+  let noteSize = Number.POSITIVE_INFINITY
 
   for (const game of Object.values(CLI.GAMES)) {
     const moves = game.moves.length === 0 ? 0 : game.moves.split(' ').length
@@ -117,13 +139,14 @@ listCmd.fn = (CLI, ...filters) => {
       id: (game.id === CLI.GAME.id ? '* #' : '#') + String(game.id),
       name: game.name?.length || 0,
       rules: game.rules,
-      moves: CLI.plural(moves, 'move'),
+      moves: game.over ? 'game over' : CLI.plural(moves, 'move'),
       smoves: game.over ? '9999' : String(moves).padStart(9, '0'),
       sturn: String(game.turn),
       p1: game.players?.[0] || 'white',
       p2: game.players?.[1] || 'black',
       turn: game.turn,
       over: game.over,
+      note: game.notes?.[game.notes.length - 1]?.note || '',
     })
   }
 
@@ -135,6 +158,7 @@ listCmd.fn = (CLI, ...filters) => {
     size.moves = Math.max(size.moves, game.moves.length)
     size.p1 = Math.max(size.p1, game.p1.length)
     size.p2 = Math.max(size.p2, game.p2.length)
+    noteSize = Math.min(noteSize, leftover(size))
   }
 
   for (const game of list) {
@@ -146,7 +170,8 @@ listCmd.fn = (CLI, ...filters) => {
         CLI.color('vs '.padStart(size.p1 - game.p1.length + 4)) +
         CLI.bubble(game.turn === 2 ? 'bh' : 'b', game.p2) +
         CLI.color(' '.padStart(size.p2 - game.p2.length + 1)) +
-        CLI.color(game.over ? 'game over' : game.moves),
+        CLI.color(game.moves.padEnd(size.moves)) +
+        CLI.color.help(' ' + game.note.slice(0, noteSize)),
     )
   }
 }

package/src/cmds/new.js

@@ -98,6 +98,9 @@ newCmd.fn = (CLI, variant, ...names) => {
   let rules = ''
   if (variant) {
     variant = variant.toLowerCase()
+    if (variant.length > 1 && 'puzzles'.startsWith(variant)) {
+      return CLI.do('puzzles', 'new', ...names)
+    }
 
     if (['8x8', '8', 'trax8x8', '8trax', '8x8trax'].includes(variant)) {
       rules = 'trax8'

package/src/cmds/notes.js

@@ -0,0 +1,34 @@
+/** Notes CLI command.
+ * @copyright 2022
+ * @author Chad Transtrum <chad@transtrum.net>
+ * @license Apache-2.0
+ */
+
+export const notesCmd = {
+  name: 'notes',
+  args: '[#id] <text>',
+  desc: 'add a note to a game',
+  help: [
+    'Add a short note to a game that will be shown when the game is',
+    'displayed, listed, or exported.',
+  ],
+}
+
+notesCmd.fn = (CLI, id, ...note) => {
+  const current = String(CLI.GAME.id)
+  if (!id) id = current
+  if (!/^#?\d+$/.test(id)) {
+    note.unshift(id)
+    id = current
+  }
+
+  if (id.startsWith('#')) id = id.slice(1)
+
+  const game = CLI.GAMES[id]
+  const notes = game.notes || []
+  const move = game.moves.length > 0 ? game.moves.split(' ').length : 0
+
+  notes.push({ move, note: note.join(' ') })
+  game.notes = notes
+  CLI.save()
+}

package/src/cmds/puzzles.js

@@ -19,7 +19,7 @@ const completions = [...validLevels, ...puzzleIds].join('|')
 
 export const puzzlesCmd = {
   name: 'puzzles',
-  args: '["list"|"start" [<difficulty>|<puzzleID>]]',
+  args: '["list"|"start"] [level|puzzle]',
   comp: 'list|ls|new|show|start|view ' + completions,
   desc: 'play puzzles',
   help: [
@@ -28,6 +28,11 @@ export const puzzlesCmd = {
   ],
 }
 
+const an = (word = '') => {
+  const a = /^[aeiou]/.test(word) ? 'an' : 'a'
+  return a + ' ' + word
+}
+
 const showPuzzle = (CLI, id) => {
   const puzzle = puzzles.find((p) => p.id === id)
   if (!puzzle) return CLI.error(`Puzzle ${id} not found`)
@@ -35,7 +40,7 @@ const showPuzzle = (CLI, id) => {
   const players = ['white', 'black']
   CLI.display(trax, players)
   let out = CLI.color.short(puzzle.id)
-  out += CLI.color(' is a ' + levels[puzzle.level] + ' puzzle') + '\n'
+  out += CLI.color(` is ${an(levels[puzzle.level])} puzzle`) + '\n'
   if (puzzle.title) out += CLI.color(puzzle.title) + '\n'
   if (puzzle.desc) out += CLI.color.help(puzzle.desc) + '\n'
   out += CLI.color(players[puzzle.player - 1] + ' to win by move ' + puzzle.max)
@@ -143,8 +148,9 @@ puzzlesCmd.fn = (CLI, action, id) => {
   }
 
   if (action) {
-    if (validLevels.includes(id)) return listLevel(CLI, id)
-    if (puzzleIds.includes(id)) return showPuzzle(CLI, id)
+    const x = id || action
+    if (validLevels.includes(x)) return listLevel(CLI, x)
+    if (puzzleIds.includes(x)) return showPuzzle(CLI, x)
     if (id) return CLI.error('Could not find puzzle ' + id)
   }
 

package/src/cmds/view.js

@@ -39,7 +39,10 @@ viewCmd.fn = (CLI, move) => {
     show = Number(move)
   }
 
-  const players = CLI.GAME.players || ['white', 'black']
+  const game = CLI.GAME
+  const players = game.players || ['white', 'black']
+  const puzzle = game.puzzle || ''
+  const { note } = [...(game.notes || [{}])].pop()
 
   CLI.out(
     CLI.color('#' + CLI.ID + ' ') +
@@ -50,4 +53,6 @@ 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 (note) CLI.out(CLI.color.help(note))
 }

package/src/engine.js

@@ -617,7 +617,7 @@ export const Trax = class {
     return this.notation
       .replace(/\n/g, ' ')
       .split(' ')
-      .filter((n) => !n.endsWith('.'))
+      .filter((n) => Boolean(n) && !n.endsWith('.'))
   }
 
   /** Drop a tile onto the board. This is a lower level call. Use play() if possible instead.

package/src/puzzles.js

@@ -440,7 +440,7 @@ export const puzzles = [
     level: 2,
     player: 1,
     max: 11,
-    hint: 'A0/',
+    hints: ['A0/', 'C4\\', 'D5/'],
   },
   {
     id: 'iw3.trx',
@@ -451,7 +451,7 @@ export const puzzles = [
     level: 2,
     player: 1,
     max: 11,
-    hint: 'B0/',
+    hints: ['B0/', 'C0\\'],
   },
   {
     id: 'iw4.trx',
@@ -462,7 +462,7 @@ export const puzzles = [
     level: 2,
     player: 1,
     max: 11,
-    hint: '@2/',
+    hints: ['@2/', 'C0/'],
   },
   {
     id: 'iw5.trx',
@@ -495,7 +495,7 @@ export const puzzles = [
     level: 2,
     player: 1,
     max: 13,
-    hint: 'A1+',
+    hints: ['A1+', 'D1/'],
   },
   {
     id: 'ib1.trx',
@@ -517,7 +517,7 @@ export const puzzles = [
     level: 2,
     player: 2,
     max: 12,
-    hint: 'A1\\',
+    hints: ['A1\\', 'E1/'],
   },
   {
     id: 'ib3.trx',
@@ -539,7 +539,7 @@ export const puzzles = [
     level: 2,
     player: 2,
     max: 12,
-    hint: 'B0/',
+    hints: ['B0/', 'C0+'],
   },
   {
     id: 'ib5.trx',
@@ -572,7 +572,7 @@ export const puzzles = [
     level: 2,
     player: 2,
     max: 10,
-    hint: 'A0/',
+    hints: ['A0/', 'D3/'],
   },
   {
     id: 'ib8.trx',
@@ -648,8 +648,8 @@ export const puzzles = [
     icon: '0ca:deef:0d',
     level: 2,
     player: 1,
-    max: 13,
-    hint: 'B0/',
+    max: 15,
+    hints: ['B0/', 'C0\\'],
   },
   {
     id: 'hw4.trx',
@@ -747,8 +747,8 @@ export const puzzles = [
     icon: 'd:b:ba:aeecd:0fdec',
     level: 1,
     player: 2,
-    max: 16,
-    hint: 'B1+',
+    max: 18,
+    hints: ['B1+', 'B2/', 'D3+'],
   },
   {
     id: 'hb3.trx',
@@ -767,7 +767,7 @@ export const puzzles = [
     game: 'traxloop',
     notation: '@0+ A0/ A0/ A4/ A5+ @5/ @5/ @5+ A4/ @5/',
     icon: '3d:3c:3e:0d1d:cbdcb',
-    level: 2,
+    level: 3,
     player: 1,
     max: 15,
     hint: 'D1\\',
@@ -778,7 +778,7 @@ export const puzzles = [
     game: 'traxloop',
     notation: '@0+ B1/ C1+ C0/ D1\\ E1\\ F1+ E0/ F1/',
     icon: '2cdc:1dfae:ecb',
-    level: 2,
+    level: 3,
     player: 2,
     max: 16,
     hint: 'F0/',
@@ -789,7 +789,7 @@ export const puzzles = [
     game: 'traxloop',
     notation: '@0/ @1+ A0/ A0/ B2+ @2\\ @2\\ E3\\ E4+',
     icon: '1ca:afde:1bdf:3b',
-    level: 2,
+    level: 3,
     player: 2,
     max: 16,
     hint: 'A1\\',
@@ -800,9 +800,13 @@ export const puzzles = [
     game: 'traxloop',
     notation: '@0/ B1+ C1/ C0/ C0\\ @3/ C1+ E2/ F2\\',
     icon: '1baf:1cdca:cdecd',
-    level: 2,
+    level: 3,
     player: 2,
     max: 16,
     hint: 'B1+',
   },
 ]
+
+puzzles.sort(
+  (a, b) => a.level - b.level || a.max - b.max || (a.id < b.id ? -1 : 1),
+)

package/src/threats.js

@@ -5,20 +5,26 @@
  */
 
 const REGEX = {
-  a: '[am]', // White that pairs with the next white (m=hollow)
-  c: '[cp]', // White that forms a connectable pair with next white (p=hollow)
-  l: '[lmp]', // White in a hollow
-  w: '[aclmpw]', // Any white
+  // Some of these are one for one:
+  // a: White that pairs with the next white
+  A: '[am]', // White maybe in a hollow that pairs with next white
+  // c: White that forms a connectable pair with next white
+  C: '[cp]', // White maybe in a hollow connectable pair with next white
+  l: '[lmp]', // Any White in a hollow
+  // m: "a" in a hollow
+  // p: "c" in a hollow)
+  w: '[acw]', // Any white except in hollows
+  W: '[aclmpw]', // Any white at all
   '!': '(?:b[acw])*?', // Ripple black/white
   '¡': '(?:[acw]b)*?', // Ripple white/black
   '*': 'b*?', // Zero or more black pieces
   '?': 'b?', // Zero or one black piece
 }
 
-class Threat {
+export const Threat = class {
   #depth = 0
   #pattern = ''
-  #rx = null
+  #rx
   #reforms = false
 
   constructor(depth, pattern, reforms = false) {
@@ -31,7 +37,8 @@ class Threat {
       rx += REGEX[char] || char
     }
 
-    this.#rx = new RegExp(rx, 'g')
+    // Create the regex with lookahead assertions to allow overlapping matches
+    this.#rx = new RegExp('(?=(' + rx + '))', 'g')
   }
 
   get depth() {
@@ -65,7 +72,7 @@ class Threat {
   }
 }
 
-class ThreatsDB {
+export const ThreatsDB = class {
   #db = {}
   #depth = 0
 
@@ -75,6 +82,11 @@ class ThreatsDB {
     }
   }
 
+  compose(depth, pattern) {
+    pattern = pattern.replaceAll(/(?<=.)A/g, 'a').replaceAll(/W(?=.)/g, 'w')
+    return this.add(depth, pattern)
+  }
+
   add(depth, pattern, reforms = false) {
     this.#depth = Math.max(depth, this.#depth)
     if (pattern in this.#db) throw new Error('Duplicate pattern:' + pattern)
@@ -97,37 +109,38 @@ class ThreatsDB {
   // To make life at the REPL a little easier
   [Symbol.for('nodejs.util.inspect.custom')](_, out) {
     const style = out.stylize
-    const inspection = '[' + style('Threats', 'special') + '] { '
+    const inspection = '[' + style('Threats', 'special') + ':'
     let total = 0
-    const keys = []
+    const keys = ['{']
 
     for (let x = 0; x <= this.#depth; x++) {
       const count = this.level(x).length
-      keys.push(style(x, 'string') + ': ' + style(count, 'number'))
+      keys.push(style(x, 'string') + ':' + style(count, 'number'))
       total += count
     }
 
-    return inspection + keys.join(', ') + ' } total: ' + total
+    return inspection + style(total, 'number') + '] ' + keys.join(' ') + ' }'
   }
 }
 
 const pre = true // This pattern can appear first in an L threat
 const post = true // This pattern can come second in an L threat
 const corners = {
-  arw: { pre, post }, // Simple corner
-  abrw: { post }, // Wide-first corner
-  arbw: { pre }, // Wide-second corner
-  abrbw: {}, // Wide corner
-  'ab?bw': { pre, post }, // Flat corner and wide flat corner
-  cw: { pre, post }, // Connectable pair
-  cbw: {}, // Wide connectable pair
+  ArW: { pre, post }, // Simple corner
+  AbrW: { post }, // Wide-first corner
+  ArbW: { pre }, // Wide-second corner
+  AbrbW: {}, // Wide corner
+  'ab?bW': { pre, post }, // Flat corner and wide flat corner
+  CW: { pre, post }, // Connectable pair
+  CbW: {}, // Wide connectable pair
 }
 
 export const threats = new ThreatsDB(Object.keys(corners))
 
 // Attacks
 const attacks = [
-  'a?w', // Simple attack and wide attack
+  'a?W', // Simple attack and wide attack
+  'm?W', // Simple and wide attack in a corner
 ]
 attacks.map((a) => threats.add(1, a))
 
@@ -135,34 +148,55 @@ attacks.map((a) => threats.add(1, a))
 const reformAttacks = [
   'rm?lr', // Cave/wide cave attack
   'rbm?lbr', // Deep cave/deep wide cave attack (impossibly rare?)
-  'ralmrw', // Attack at top of cave
+  'ralmrW', // Attack at top of cave
   'arlmwr', // Reversed
 ]
 reformAttacks.map((ra) => threats.add(1, ra, true))
 
 const reformThreats = [
   'rp?lr', // Cave/wide cave threat
-  'rbp?lbr', // Deep cave/deept wide cave attach (impossibly rare?)
+  'rbp?lbr', // Deep cave/deep wide cave threat (impossibly rare?)
+  'rmbb???w', // Black corner with a long white loop potential
+  'abb???lr', // Reverse
 ]
 reformThreats.map((rt) => threats.add(2, rt))
 
 // Create multi-stage threats
 for (const one of Object.keys(corners)) {
+  const start = one.replace('W', 'l')
+  let end = one.replace(/[aA]/, 'm').replace('C', 'p')
+  const pre = corners[one].post ? '?' : ''
+  let post = corners[one].pre ? '?' : ''
+  threats.compose(3, start + pre + '¡rm?W') // Attacking 3-stage threat
+  threats.compose(3, 'a?lr!' + post + end) // Reverse
+  threats.compose(3, one + '¡ab*bwr') // Corner by reforming hollow potential
+  threats.compose(3, 'rab*bw!' + one) // Reverse
+  threats.compose(3, one + '!brm*bW') // Corner by hollow attack, defends to edge
+  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
+
   for (const two of Object.keys(corners)) {
-    // L threats
-    const [before, after] = [corners[one].post, corners[two].pre]
-    if (before || after) {
-      const start = one.replace('w', 'l')
-      const pre = before ? '?' : ''
-      const post = after ? '?' : ''
-      threats.add(2, start + pre + '¡' + two) // Make an L
-      threats.add(3, start + pre + 'rb¡' + two) // Make a three-stage threat
-      const end = two.replace('a', 'm').replace('c', 'p')
-      threats.add(2, one + post + '!' + end) // L
-      threats.add(3, one + post + '!br' + end) // Three-stage
+    end = two.replace(/[aA]/, 'm').replace('C', 'p')
+    post = corners[two].pre ? '?' : ''
+    if (pre) {
+      threats.compose(2, start + pre + '¡' + two) // Make an L
+      threats.compose(3, start + pre + 'rb¡' + two) // Make a three-stage threat
+      threats.compose(3, start + '?!rb¡' + two) // Attack to form an L threat
     }
 
-    // Edge threats
-    threats.add(3, one + '!b*b¡' + two)
+    if (post) {
+      threats.compose(2, one + post + '!' + end) // L
+      threats.compose(3, one + post + '!br' + end) // Three-stage
+      threats.compose(3, one + '!br¡?' + end) // Attack to form an L threat
+    }
+
+    threats.compose(3, one + '!b*b¡' + two) // Edge threat
   }
 }
+
+threats.add(3, 'ralbmrW') // Attack into a wide cave
+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

package/src/tty.js

@@ -22,7 +22,7 @@ import { Trax } from '@slugbugblue/trax'
 const esc = '\u001B[' // Start of console color escape code
 const off = esc + 'm' // Color reset code
 const ENV = process.env
-const NERD = ENV.NERDFONT
+const NERD = ENV.NERDFONT || ENV.NERDFONTS
 const POWER = ENV.POWERLINE || ENV.P9K_TTY || ENV.P9K_SSH
 const leftBubble = NERD ? '' : POWER ? '' : '▐'
 const rightBubble = NERD ? '' : POWER ? '' : '▌'

package/src/types.d.ts

@@ -25,12 +25,65 @@ type Colorer = {
   white: Colorize
 }
 
+/** An object representing a space on the perimeter of a Trax position.
+ * x,y: the coordinates of the space
+ * c: the color present beside the space (w, b, l: both w and b, r: none)
+ * t: the type of possible moves: n-normal, x-none, c-cave, C-restricted cave
+ * b,w: if present, the number of the line to match with its other end
+ * pb, pw: if present, can pair with the next line in one turn
+ * xb, xw: the label of this space for each color
+ */
+type EdgeLocation = {
+  x: number
+  y: number
+  c: string
+  t: string
+  b?: number
+  w?: number
+  pb?: boolean
+  pw?: boolean
+  zb?: string
+  zw?: string
+}
+
+type EdgeObject = {
+  b: string
+  w: string
+  edge: RawEdge
+}
+
+/** Object representing a concrete threat found in a position. */
+type FoundThreat = { threat: string; match: string; at: number; value: number }
+
+/** An object with keys representing each level, with arrays for each threat of
+ * that level. */
+type FoundThreats = Record<string, FoundThreat[]>
+
+/** All the threats found for both the white and black player. */
+type FoundThreatsCollection = { b: ColorThreats; w: ColorThreats }
+
+/** A note with a move number */
+type GameNote = {
+  move: number
+  note: string
+}
+
+/** Notes saved in the game object in the CLI. */
+type GameNotes = GameNote[]
+
 /** A point-like object has numerical x and y properties. */
 type PointLike = {
   x: number
   y: number
 }
 
+/** An object used to track an analysis on a position. */
+type PositionScore = {
+  move: string
+  score: number
+  analysis?: Analysis
+}
+
 /** A puzzle. */
 type Puzzle = {
   id: string
@@ -53,6 +106,10 @@ type PuzzleSource = {
   url?: string
 }
 
+/** Array of objects representing the spaces surrounding the perimeter of a
+ * Trax position. */
+type RawEdge = EdgeLocation[]
+
 /** Treat the save state as an opaque object,
  * produced by save() and fed into restore().
  */
@@ -76,6 +133,14 @@ type SaveState = {
  */
 type Slash = '/' | '\\' | '+'
 
+/** Threat definition. */
+type Threat = {
+  depth: number
+  pattern: string
+  rx: RegExp
+  value: number
+}
+
 /** A single tile on the board. */
 type Tile = {
   id: TileId

package/src/version.js

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