@slugbugblue/trax 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @slugbugblue/trax
 
+## 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 +25,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.15.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 (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/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/list.js

@@ -101,6 +101,9 @@ listCmd.fn = (CLI, ...filters) => {
     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 = {
     id: 1,

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/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/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,54 @@ 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, '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,56 @@ 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 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 +97,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 +124,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.15.0'