puzzle-lib 2.0.0-alpha.2 → 2.0.0-beta.2

package/src/ngrams/unigrams.ts

@@ -0,0 +1,34 @@
+// Log-probabilities of English letter unigrams.
+// Derived from bigram frequencies (sum of P(xy) over all y for each x).
+// Original bigram source: Peter Norvig, Google Web Trillion Word Corpus (public domain)
+// http://norvig.com/ngrams/count_2l.txt
+export const UNIGRAM_LOG_PROB: Record<string, number> = {
+  e: -2.186224,
+  a: -2.448764,
+  t: -2.47288,
+  o: -2.501531,
+  i: -2.516878,
+  n: -2.681277,
+  r: -2.700564,
+  s: -2.800337,
+  l: -3.133597,
+  c: -3.206786,
+  h: -3.266123,
+  d: -3.428238,
+  u: -3.464367,
+  m: -3.543925,
+  p: -3.613343,
+  f: -3.87574,
+  g: -3.926056,
+  b: -4.025837,
+  w: -4.158706,
+  y: -4.284818,
+  v: -4.386163,
+  k: -4.895394,
+  x: -5.875251,
+  j: -5.90304,
+  q: -6.558017,
+  z: -6.560645,
+};
+
+export const MIN_UNIGRAM_LOG_PROB = -11.560645;

package/src/phone/index.ts

@@ -0,0 +1,2 @@
+export {lettersToPhone, phoneToLetters, phoneToText} from './phone.js';
+export type {PhoneResult} from './phone.js';

package/src/phone/phone-mapping.ts

@@ -0,0 +1,27 @@
+/**
+ * Standard telephone keypad mapping (ITU E.161 / T9).
+ * Maps digit characters to their corresponding letters.
+ */
+export const PHONE_MAPPING: Partial<Record<string, readonly string[]>> = {
+  '2': ['a', 'b', 'c'],
+  '3': ['d', 'e', 'f'],
+  '4': ['g', 'h', 'i'],
+  '5': ['j', 'k', 'l'],
+  '6': ['m', 'n', 'o'],
+  '7': ['p', 'q', 'r', 's'],
+  '8': ['t', 'u', 'v'],
+  '9': ['w', 'x', 'y', 'z'],
+};
+
+/**
+ * Reverse mapping: letter to digit.
+ * Built automatically from PHONE_MAPPING.
+ */
+export const LETTER_TO_DIGIT: Record<string, string> = {};
+for (const [digit, letters] of Object.entries(PHONE_MAPPING)) {
+  if (letters) {
+    for (const letter of letters) {
+      LETTER_TO_DIGIT[letter] = digit;
+    }
+  }
+}

package/src/phone/phone.ts

@@ -0,0 +1,77 @@
+import {scoreNextLetter} from '../ngrams/ngrams.js';
+import {LETTER_TO_DIGIT, PHONE_MAPPING} from './phone-mapping.js';
+
+export interface PhoneResult {
+  /** The candidate text string. */
+  text: string;
+  /** Log-probability score (higher = more likely). */
+  score: number;
+}
+
+/**
+ * Returns the possible letters for a single digit.
+ * Returns an empty array for digits without letter mappings (0, 1).
+ */
+export function phoneToLetters(digit: string): readonly string[] {
+  return PHONE_MAPPING[digit] ?? [];
+}
+
+/**
+ * Converts a string of letters to their corresponding phone digits.
+ * Non-letter characters are passed through unchanged.
+ */
+export function lettersToPhone(text: string): string {
+  return text
+    .split('')
+    .map(ch => LETTER_TO_DIGIT[ch.toLowerCase()] ?? ch)
+    .join('');
+}
+
+/**
+ * Converts a string of phone digits (2-9) to ranked text candidates
+ * using beam search with n-gram scoring (unigram + bigram + trigram).
+ * Starts with unigram scoring for the first letter, bigram for the
+ * second, and trigrams for all subsequent letters.
+ *
+ * @param digits - String of digit characters (e.g., "43556")
+ * @param maxResults - Maximum number of results to return (default: 20, clamped to [1, 1000])
+ * @returns Array of PhoneResult sorted by score (highest first)
+ */
+export function phoneToText(digits: string, maxResults = 20): PhoneResult[] {
+  const clampedMax = Math.max(1, Math.min(Math.trunc(maxResults) || 1, 1000));
+  const beamWidth = Math.max(100, clampedMax);
+  // Filter to valid digits with letter mappings
+  const validDigits = digits.split('').filter(d => PHONE_MAPPING[d]);
+
+  if (validDigits.length === 0) {
+    return [];
+  }
+
+  // Start with letters from the first digit, scored by unigram frequency
+  let candidates: PhoneResult[] = phoneToLetters(validDigits[0]).map(ch => ({
+    text: ch,
+    score: scoreNextLetter('', ch),
+  }));
+
+  // Expand one digit at a time with beam search
+  for (let i = 1; i < validDigits.length; i++) {
+    const letters = phoneToLetters(validDigits[i]);
+    const next: PhoneResult[] = [];
+
+    for (const candidate of candidates) {
+      for (const letter of letters) {
+        const text = candidate.text + letter;
+        const score = candidate.score + scoreNextLetter(candidate.text, letter);
+        next.push({text, score});
+      }
+    }
+
+    // Keep only top beamWidth candidates
+    next.sort((a, b) => b.score - a.score);
+    candidates = next.slice(0, beamWidth);
+  }
+
+  // Final sort and trim
+  candidates.sort((a, b) => b.score - a.score);
+  return candidates.slice(0, clampedMax);
+}

package/src/pigpen/encoding.ts

@@ -0,0 +1,66 @@
+import {PigpenSegment} from './segment.js';
+
+export enum PigpenEncoding {
+  None = 0,
+
+  // Grid without dot (A-I)
+  LetterA = PigpenSegment.East | PigpenSegment.South,
+  LetterB = PigpenSegment.West | PigpenSegment.East | PigpenSegment.South,
+  LetterC = PigpenSegment.West | PigpenSegment.South,
+  LetterD = PigpenSegment.North | PigpenSegment.East | PigpenSegment.South,
+  LetterE = PigpenSegment.North |
+    PigpenSegment.East |
+    PigpenSegment.South |
+    PigpenSegment.West,
+  LetterF = PigpenSegment.North | PigpenSegment.West | PigpenSegment.South,
+  LetterG = PigpenSegment.North | PigpenSegment.East,
+  LetterH = PigpenSegment.North | PigpenSegment.West | PigpenSegment.East,
+  LetterI = PigpenSegment.North | PigpenSegment.West,
+
+  // Grid with dot (J-R)
+  LetterJ = PigpenSegment.East | PigpenSegment.South | PigpenSegment.Dot,
+  LetterK = PigpenSegment.West |
+    PigpenSegment.East |
+    PigpenSegment.South |
+    PigpenSegment.Dot,
+  LetterL = PigpenSegment.West | PigpenSegment.South | PigpenSegment.Dot,
+  LetterM = PigpenSegment.North |
+    PigpenSegment.East |
+    PigpenSegment.South |
+    PigpenSegment.Dot,
+  LetterN = PigpenSegment.North |
+    PigpenSegment.East |
+    PigpenSegment.South |
+    PigpenSegment.West |
+    PigpenSegment.Dot,
+  LetterO = PigpenSegment.North |
+    PigpenSegment.West |
+    PigpenSegment.South |
+    PigpenSegment.Dot,
+  LetterP = PigpenSegment.North | PigpenSegment.East | PigpenSegment.Dot,
+  LetterQ = PigpenSegment.North |
+    PigpenSegment.West |
+    PigpenSegment.East |
+    PigpenSegment.Dot,
+  LetterR = PigpenSegment.North | PigpenSegment.West | PigpenSegment.Dot,
+
+  // X without dot (S-V)
+  LetterS = PigpenSegment.NorthWest | PigpenSegment.NorthEast,
+  LetterT = PigpenSegment.NorthWest | PigpenSegment.SouthWest,
+  LetterU = PigpenSegment.NorthEast | PigpenSegment.SouthEast,
+  LetterV = PigpenSegment.SouthWest | PigpenSegment.SouthEast,
+
+  // X with dot (W-Z)
+  LetterW = PigpenSegment.NorthWest |
+    PigpenSegment.NorthEast |
+    PigpenSegment.Dot,
+  LetterX = PigpenSegment.NorthWest |
+    PigpenSegment.SouthWest |
+    PigpenSegment.Dot,
+  LetterY = PigpenSegment.NorthEast |
+    PigpenSegment.SouthEast |
+    PigpenSegment.Dot,
+  LetterZ = PigpenSegment.SouthWest |
+    PigpenSegment.SouthEast |
+    PigpenSegment.Dot,
+}

package/src/pigpen/index.ts

@@ -0,0 +1,11 @@
+export {
+  canTogglePigpenSegment,
+  decodePigpenStream,
+  hasPigpenSegment,
+  isCardinal,
+  isIntercardinal,
+  lookupPigpenEncoding,
+  togglePigpenSegment,
+} from './pigpen.js';
+export {PigpenEncoding} from './encoding.js';
+export {PigpenSegment} from './segment.js';

package/src/pigpen/pigpen.ts

@@ -0,0 +1,168 @@
+import {EncodingCategory} from '../common/encoding-category.js';
+import {EncodingEntry} from '../common/encoding-entry.js';
+import {EncodingLookupResult} from '../common/encoding-lookup-result.js';
+import {PigpenEncoding} from './encoding.js';
+import {PigpenSegment} from './segment.js';
+
+// Build the lookup table once
+const PIGPEN_ENTRIES: Array<EncodingEntry<PigpenEncoding>> = [];
+
+function addEntry(
+  encoding: PigpenEncoding,
+  category: EncodingCategory,
+  display: string,
+) {
+  PIGPEN_ENTRIES.push(new EncodingEntry(encoding, category, display));
+}
+
+// Letters
+addEntry(PigpenEncoding.LetterA, EncodingCategory.Letter, 'A');
+addEntry(PigpenEncoding.LetterB, EncodingCategory.Letter, 'B');
+addEntry(PigpenEncoding.LetterC, EncodingCategory.Letter, 'C');
+addEntry(PigpenEncoding.LetterD, EncodingCategory.Letter, 'D');
+addEntry(PigpenEncoding.LetterE, EncodingCategory.Letter, 'E');
+addEntry(PigpenEncoding.LetterF, EncodingCategory.Letter, 'F');
+addEntry(PigpenEncoding.LetterG, EncodingCategory.Letter, 'G');
+addEntry(PigpenEncoding.LetterH, EncodingCategory.Letter, 'H');
+addEntry(PigpenEncoding.LetterI, EncodingCategory.Letter, 'I');
+addEntry(PigpenEncoding.LetterJ, EncodingCategory.Letter, 'J');
+addEntry(PigpenEncoding.LetterK, EncodingCategory.Letter, 'K');
+addEntry(PigpenEncoding.LetterL, EncodingCategory.Letter, 'L');
+addEntry(PigpenEncoding.LetterM, EncodingCategory.Letter, 'M');
+addEntry(PigpenEncoding.LetterN, EncodingCategory.Letter, 'N');
+addEntry(PigpenEncoding.LetterO, EncodingCategory.Letter, 'O');
+addEntry(PigpenEncoding.LetterP, EncodingCategory.Letter, 'P');
+addEntry(PigpenEncoding.LetterQ, EncodingCategory.Letter, 'Q');
+addEntry(PigpenEncoding.LetterR, EncodingCategory.Letter, 'R');
+addEntry(PigpenEncoding.LetterS, EncodingCategory.Letter, 'S');
+addEntry(PigpenEncoding.LetterT, EncodingCategory.Letter, 'T');
+addEntry(PigpenEncoding.LetterU, EncodingCategory.Letter, 'U');
+addEntry(PigpenEncoding.LetterV, EncodingCategory.Letter, 'V');
+addEntry(PigpenEncoding.LetterW, EncodingCategory.Letter, 'W');
+addEntry(PigpenEncoding.LetterX, EncodingCategory.Letter, 'X');
+addEntry(PigpenEncoding.LetterY, EncodingCategory.Letter, 'Y');
+addEntry(PigpenEncoding.LetterZ, EncodingCategory.Letter, 'Z');
+
+/** Mask covering all cardinal segments (grid shapes). */
+const CARDINAL_MASK =
+  PigpenSegment.North |
+  PigpenSegment.East |
+  PigpenSegment.South |
+  PigpenSegment.West;
+
+/** Mask covering all intercardinal segments (X shapes). */
+const INTERCARDINAL_MASK =
+  PigpenSegment.NorthEast |
+  PigpenSegment.SouthEast |
+  PigpenSegment.SouthWest |
+  PigpenSegment.NorthWest;
+
+/**
+ * Looks up a pigpen encoding in the data table.
+ */
+export function lookupPigpenEncoding(
+  encoding: PigpenEncoding,
+  category: EncodingCategory = EncodingCategory.All,
+): EncodingLookupResult<PigpenEncoding> {
+  const result = new EncodingLookupResult<PigpenEncoding>();
+
+  for (const entry of PIGPEN_ENTRIES) {
+    if ((entry.category & category) !== 0) {
+      if (entry.encoding === encoding) {
+        result.exact.push(entry);
+      } else if ((entry.encoding & encoding) === encoding) {
+        result.partial.push(entry);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Toggles a segment flag in an encoding. Returns the encoding unchanged
+ * if toggling the segment on would mix cardinal and intercardinal segments.
+ * Toggling a segment off or toggling the dot is always allowed.
+ */
+export function togglePigpenSegment(
+  encoding: PigpenEncoding,
+  segment: PigpenSegment,
+): PigpenEncoding {
+  if (!canTogglePigpenSegment(encoding, segment)) {
+    return encoding;
+  }
+  return (encoding ^ segment) as PigpenEncoding;
+}
+
+/**
+ * Checks if a segment flag is set in an encoding.
+ */
+export function hasPigpenSegment(
+  encoding: PigpenEncoding,
+  segment: PigpenSegment,
+): boolean {
+  return (encoding & segment) === segment;
+}
+
+/**
+ * Returns true if the encoding uses cardinal (grid) segments.
+ */
+export function isCardinal(encoding: PigpenEncoding): boolean {
+  return ((encoding as number) & CARDINAL_MASK) !== 0;
+}
+
+/**
+ * Returns true if the encoding uses intercardinal (X) segments.
+ */
+export function isIntercardinal(encoding: PigpenEncoding): boolean {
+  return ((encoding as number) & INTERCARDINAL_MASK) !== 0;
+}
+
+/**
+ * Checks if a segment can be toggled without mixing cardinal and intercardinal
+ * segments. Toggling off and toggling the dot are always allowed.
+ */
+export function canTogglePigpenSegment(
+  encoding: PigpenEncoding,
+  segment: PigpenSegment,
+): boolean {
+  // Toggling off is always allowed
+  if (hasPigpenSegment(encoding, segment)) {
+    return true;
+  }
+  // Dot is always compatible
+  if (segment === PigpenSegment.Dot) {
+    return true;
+  }
+  // Reject masks that mix cardinal and intercardinal bits
+  const segmentAsEncoding = segment as number as PigpenEncoding;
+  const segmentHasCardinal = isCardinal(segmentAsEncoding);
+  const segmentHasIntercardinal = isIntercardinal(segmentAsEncoding);
+  if (segmentHasCardinal && segmentHasIntercardinal) {
+    return false;
+  }
+  if (segmentHasCardinal) {
+    return !isIntercardinal(encoding);
+  }
+  return !isCardinal(encoding);
+}
+
+/**
+ * Decodes an array of pigpen encodings to a string.
+ */
+export function decodePigpenStream(encodings: PigpenEncoding[]): string {
+  let result = '';
+
+  for (const ch of encodings) {
+    if (ch === PigpenEncoding.None) {
+      result += ' ';
+    } else {
+      const lookup = lookupPigpenEncoding(ch, EncodingCategory.Letter);
+      if (lookup.exact.length > 0) {
+        result += lookup.exact[0].toString();
+      }
+    }
+  }
+
+  return result;
+}

package/src/pigpen/segment.ts

@@ -0,0 +1,12 @@
+export enum PigpenSegment {
+  None = 0,
+  North = 1 << 0,
+  NorthEast = 1 << 1,
+  East = 1 << 2,
+  SouthEast = 1 << 3,
+  South = 1 << 4,
+  SouthWest = 1 << 5,
+  West = 1 << 6,
+  NorthWest = 1 << 7,
+  Dot = 1 << 8,
+}

package/src/resistor/index.ts

@@ -0,0 +1,9 @@
+export {
+  getResistorDisplayValue,
+  getResistorValue,
+  hasResistorTolerance,
+  hasResistorValue,
+  INVALID_RESISTOR,
+  RESISTOR_COLOR_TABLE,
+} from './resistor.js';
+export type {ResistorColor} from './resistor.js';

package/src/{Semaphore/SemaphoreEncoding.ts → semaphore/encoding.ts}

@@ -1,4 +1,4 @@
-import {SemaphoreDirection} from './SemaphoreDirection';
+import {SemaphoreDirection} from './direction.js';
 
 export enum SemaphoreEncoding {
   None = 0,

package/src/semaphore/index.ts

@@ -0,0 +1,13 @@
+export {
+  addSemaphoreDirection,
+  decodeSemaphoreStream,
+  degreesToSemaphoreDirection,
+  directionsToEncoding,
+  getEncodingDegrees,
+  hasSemaphoreDirection,
+  lookupSemaphoreEncoding,
+  removeSemaphoreDirection,
+  semaphoreDirectionToDegrees,
+} from './semaphore.js';
+export {SemaphoreDirection} from './direction.js';
+export {SemaphoreEncoding} from './encoding.js';

package/src/{Semaphore → semaphore}/semaphore.ts

@@ -1,8 +1,8 @@
-import {EncodingCategory} from '../Common/EncodingCategory';
-import {EncodingEntry} from '../Common/EncodingEntry';
-import {EncodingLookupResult} from '../Common/EncodingLookupResult';
-import {SemaphoreDirection} from './SemaphoreDirection';
-import {SemaphoreEncoding} from './SemaphoreEncoding';
+import {EncodingCategory} from '../common/encoding-category.js';
+import {EncodingEntry} from '../common/encoding-entry.js';
+import {EncodingLookupResult} from '../common/encoding-lookup-result.js';
+import {SemaphoreDirection} from './direction.js';
+import {SemaphoreEncoding} from './encoding.js';
 
 // Build the lookup table once
 const SEMAPHORE_ENTRIES: Array<EncodingEntry<SemaphoreEncoding>> = [];

package/src/trie-prefix-tree.d.ts

@@ -4,8 +4,6 @@
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.8
 
-// The published typings don't seem to work correctly with ES6 module syntax,
-// switch to CommonJS module syntax instead.
 declare module 'trie-prefix-tree' {
   function Trie(strings: string[]): {
     /**
@@ -66,5 +64,5 @@ declare module 'trie-prefix-tree' {
     getSubAnagrams(word: string): string[];
   };
 
-  export = Trie;
+  export default Trie;
 }

package/src/word-search/index.ts

@@ -0,0 +1,5 @@
+export type {WordSearchPoint} from './point.js';
+export {WordSearchResult} from './result.js';
+export {WordSearchDirection} from './direction.js';
+export {findWords, parseWordSearchGrid} from './word-search.js';
+export type {WordSearchOptions} from './word-search.js';

package/src/word-search/point.ts

@@ -0,0 +1,4 @@
+export interface WordSearchPoint {
+  x: number;
+  y: number;
+}

package/src/word-search/result.ts

@@ -0,0 +1,10 @@
+import {WordSearchPoint} from './point.js';
+
+export class WordSearchResult {
+  word: string;
+  points: WordSearchPoint[];
+  constructor(word: string, wordPoints: WordSearchPoint[]) {
+    this.word = word;
+    this.points = Array.from(wordPoints);
+  }
+}