scrabble-solver 2.16.7 → 2.18.0

package/packages/solver/README.md

@@ -3,3 +3,27 @@
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)
 
 The brains of Scrabble Solver.
+
+## Benchmarks
+
+`solve()` speed for a mid-game Scrabble position in English (US), English (GB), and Polish, grouped by the number of blank tiles on the rack.
+
+Rerun the benchmarks and refresh the results below with:
+
+```sh
+bun run benchmark
+```
+
+<!-- benchmark-results:start -->
+
+![Median solve() duration grouped by number of blanks on the rack](benchmarks/results/chart.svg)
+
+| Blanks | English (US) | English (GB) | Polish |
+| --- | --- | --- | --- |
+| 0 | 2 ms (1,559 results) | 2 ms (2,398 results) | 1 ms (1,826 results) |
+| 1 | 11 ms (7,546 results) | 15 ms (11,680 results) | 13 ms (15,291 results) |
+| 2 | 39 ms (25,659 results) | 52 ms (39,286 results) | 66 ms (70,693 results) |
+
+Median of 5 runs (after 5 warmup runs)
+
+<!-- benchmark-results:end -->

package/packages/solver/benchmarks/index.ts

@@ -0,0 +1,15 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { renderChart } from './renderChart';
+import { runBenchmarks } from './runBenchmarks';
+import { updateReadme } from './updateReadme';
+
+const RESULTS_DIRECTORY = path.join(import.meta.dir, 'results');
+
+const measurements = await runBenchmarks();
+
+fs.mkdirSync(RESULTS_DIRECTORY, { recursive: true });
+fs.writeFileSync(path.join(RESULTS_DIRECTORY, 'chart.svg'), `${renderChart(measurements)}\n`);
+updateReadme(measurements);
+console.log('Updated README.md and benchmarks/results/chart.svg');

package/packages/solver/benchmarks/lib.ts

@@ -0,0 +1,31 @@
+import { type Measurement } from './types';
+
+export const getMeasurement = (measurements: Measurement[], label: string, blanksCount: number): Measurement => {
+  const measurement = measurements.find(
+    (candidate) => candidate.label === label && candidate.blanksCount === blanksCount,
+  );
+
+  if (!measurement) {
+    throw new Error(`Missing measurement for "${label}" with ${blanksCount} blanks`);
+  }
+
+  return measurement;
+};
+
+export const median = (values: number[]): number => {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+};
+
+export const formatDuration = (milliseconds: number): string => {
+  return milliseconds < 1000 ? `${Math.round(milliseconds)} ms` : `${(milliseconds / 1000).toFixed(1)} s`;
+};
+
+export const formatBlanksCount = (blanksCount: number): string => {
+  return blanksCount === 1 ? '1 blank' : `${blanksCount} blanks`;
+};
+
+export const formatInteger = (value: number): string => value.toLocaleString('en-US');
+
+export const unique = <T>(values: T[]): T[] => [...new Set(values)];

package/packages/solver/benchmarks/renderChart.ts

@@ -0,0 +1,165 @@
+import { formatBlanksCount, formatDuration, getMeasurement, median, unique } from './lib';
+import { type Measurement } from './types';
+
+const WIDTH = 720;
+const HEIGHT = 420;
+const PLOT_TOP = 96;
+const PLOT_BOTTOM = HEIGHT - 48;
+const PLOT_LEFT = 56;
+const PLOT_RIGHT = WIDTH - 24;
+const BAR_WIDTH = 24;
+const BAR_PITCH = 44;
+const CORNER_RADIUS = 4;
+const MAX_TICKS = 6;
+const TICK_STEP_MULTIPLIERS = [1, 2, 2.5, 5, 10];
+const SCALE_HEADROOM = 1.08;
+
+const STYLE = `
+    text { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; }
+    .axis { stroke: #c3c2b7; }
+    .grid { stroke: #e1e0d9; }
+    .group-label, .legend-label { fill: #52514e; font-size: 12px; }
+    .series-0 { fill: #2a78d6; }
+    .series-1 { fill: #eb6834; }
+    .series-2 { fill: #1baf7a; }
+    .subtitle { fill: #898781; font-size: 12px; }
+    .surface { fill: #fcfcfb; }
+    .tick-label { fill: #898781; font-size: 11px; font-variant-numeric: tabular-nums; }
+    .title { fill: #0b0b0b; font-size: 15px; font-weight: 600; }
+    .value-label { fill: #52514e; font-size: 11px; }
+    @media (prefers-color-scheme: dark) {
+      .axis { stroke: #383835; }
+      .grid { stroke: #2c2c2a; }
+      .group-label, .legend-label, .value-label { fill: #c3c2b7; }
+      .series-0 { fill: #3987e5; }
+      .series-1 { fill: #d95926; }
+      .series-2 { fill: #199e70; }
+      .surface { fill: #1a1a19; }
+      .title { fill: #ffffff; }
+    }`;
+
+export const renderChart = (measurements: Measurement[]): string => {
+  const blanksCounts = unique(measurements.map((measurement) => measurement.blanksCount)).sort((a, b) => a - b);
+  const labels = unique(measurements.map((measurement) => measurement.label));
+  const maxDuration = Math.max(...measurements.map((measurement) => median(measurement.durations)));
+  const tickStep = getTickStep(maxDuration * SCALE_HEADROOM);
+  const scaleMax = Math.ceil((maxDuration * SCALE_HEADROOM) / tickStep) * tickStep;
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}" viewBox="0 0 ${WIDTH} ${HEIGHT}" role="img" aria-label="Median solve() duration by number of blanks on the rack, for ${labels.join(', ')}">`,
+    `  <style>${STYLE}</style>`,
+    `  <rect class="surface" width="${WIDTH}" height="${HEIGHT}" rx="8" />`,
+    `  <text class="title" x="24" y="32">solve() median duration</text>`,
+    `  <text class="subtitle" x="24" y="50">Scrabble, mid-game board, 7 tiles on the rack, letters replaced by blanks</text>`,
+    renderLegend(labels),
+    renderScale(tickStep, scaleMax),
+    renderBars(measurements, blanksCounts, labels, scaleMax),
+    renderGroupLabels(blanksCounts),
+    '</svg>',
+  ].join('\n');
+};
+
+const renderLegend = (labels: string[]): string => {
+  let x = 24;
+
+  return labels
+    .map((label, index) => {
+      const item = [
+        `  <rect class="series-${index}" x="${x}" y="63" width="10" height="10" rx="2" />`,
+        `  <text class="legend-label" x="${x + 16}" y="73">${label}</text>`,
+      ].join('\n');
+      x += 16 + Math.ceil(label.length * 6.7) + 24;
+      return item;
+    })
+    .join('\n');
+};
+
+const renderScale = (tickStep: number, scaleMax: number): string => {
+  const lines: string[] = [];
+
+  for (let tick = 0; tick <= scaleMax; tick += tickStep) {
+    const y = getY(tick, scaleMax);
+    const lineClass = tick === 0 ? 'axis' : 'grid';
+    lines.push(`  <line class="${lineClass}" x1="${PLOT_LEFT}" y1="${y}" x2="${PLOT_RIGHT}" y2="${y}" />`);
+    lines.push(
+      `  <text class="tick-label" text-anchor="end" x="${PLOT_LEFT - 8}" y="${y + 4}">${formatTick(tick)}</text>`,
+    );
+  }
+
+  return lines.join('\n');
+};
+
+const renderBars = (
+  measurements: Measurement[],
+  blanksCounts: number[],
+  labels: string[],
+  scaleMax: number,
+): string => {
+  return blanksCounts
+    .flatMap((blanksCount, groupIndex) =>
+      labels.map((label, seriesIndex) => {
+        const measurement = getMeasurement(measurements, label, blanksCount);
+        const duration = median(measurement.durations);
+        const x = getBarX(groupIndex, seriesIndex, blanksCounts.length, labels.length);
+        const y = getY(duration, scaleMax);
+        return [
+          `  <path class="series-${seriesIndex}" d="${getBarPath(x, y)}" />`,
+          `  <text class="value-label" text-anchor="middle" x="${round(x + BAR_WIDTH / 2)}" y="${round(y - 6)}">${formatDuration(duration)}</text>`,
+        ].join('\n');
+      }),
+    )
+    .join('\n');
+};
+
+const renderGroupLabels = (blanksCounts: number[]): string => {
+  const bandWidth = (PLOT_RIGHT - PLOT_LEFT) / blanksCounts.length;
+
+  return blanksCounts
+    .map((blanksCount, groupIndex) => {
+      const x = round(PLOT_LEFT + bandWidth * (groupIndex + 0.5));
+      return `  <text class="group-label" text-anchor="middle" x="${x}" y="${PLOT_BOTTOM + 22}">${formatBlanksCount(blanksCount)}</text>`;
+    })
+    .join('\n');
+};
+
+const getBarPath = (x: number, y: number): string => {
+  const radius = Math.min(CORNER_RADIUS, (PLOT_BOTTOM - y) / 2);
+  return [
+    `M ${round(x)} ${PLOT_BOTTOM}`,
+    `L ${round(x)} ${round(y + radius)}`,
+    `Q ${round(x)} ${round(y)} ${round(x + radius)} ${round(y)}`,
+    `L ${round(x + BAR_WIDTH - radius)} ${round(y)}`,
+    `Q ${round(x + BAR_WIDTH)} ${round(y)} ${round(x + BAR_WIDTH)} ${round(y + radius)}`,
+    `L ${round(x + BAR_WIDTH)} ${PLOT_BOTTOM}`,
+    'Z',
+  ].join(' ');
+};
+
+const getBarX = (groupIndex: number, seriesIndex: number, groupsCount: number, seriesCount: number): number => {
+  const bandWidth = (PLOT_RIGHT - PLOT_LEFT) / groupsCount;
+  const contentWidth = (seriesCount - 1) * BAR_PITCH + BAR_WIDTH;
+  return round(PLOT_LEFT + bandWidth * groupIndex + (bandWidth - contentWidth) / 2 + seriesIndex * BAR_PITCH);
+};
+
+const getY = (duration: number, scaleMax: number): number => {
+  return round(PLOT_BOTTOM - (duration / scaleMax) * (PLOT_BOTTOM - PLOT_TOP));
+};
+
+const getTickStep = (maxValue: number): number => {
+  const magnitude = 10 ** Math.floor(Math.log10(maxValue / MAX_TICKS));
+  const step = TICK_STEP_MULTIPLIERS.map((multiplier) => multiplier * magnitude).find(
+    (candidate) => maxValue / candidate <= MAX_TICKS,
+  );
+
+  if (!step) {
+    throw new Error(`Cannot pick a tick step for ${maxValue}`);
+  }
+
+  return step;
+};
+
+const formatTick = (milliseconds: number): string => {
+  return milliseconds === 0 ? '0' : `${Number((milliseconds / 1000).toFixed(2))}s`;
+};
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/packages/solver/benchmarks/results/chart.svg

@@ -0,0 +1,65 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="720" height="420" viewBox="0 0 720 420" role="img" aria-label="Median solve() duration by number of blanks on the rack, for English (US), English (GB), Polish">
+  <style>
+    text { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; }
+    .axis { stroke: #c3c2b7; }
+    .grid { stroke: #e1e0d9; }
+    .group-label, .legend-label { fill: #52514e; font-size: 12px; }
+    .series-0 { fill: #2a78d6; }
+    .series-1 { fill: #eb6834; }
+    .series-2 { fill: #1baf7a; }
+    .subtitle { fill: #898781; font-size: 12px; }
+    .surface { fill: #fcfcfb; }
+    .tick-label { fill: #898781; font-size: 11px; font-variant-numeric: tabular-nums; }
+    .title { fill: #0b0b0b; font-size: 15px; font-weight: 600; }
+    .value-label { fill: #52514e; font-size: 11px; }
+    @media (prefers-color-scheme: dark) {
+      .axis { stroke: #383835; }
+      .grid { stroke: #2c2c2a; }
+      .group-label, .legend-label, .value-label { fill: #c3c2b7; }
+      .series-0 { fill: #3987e5; }
+      .series-1 { fill: #d95926; }
+      .series-2 { fill: #199e70; }
+      .surface { fill: #1a1a19; }
+      .title { fill: #ffffff; }
+    }</style>
+  <rect class="surface" width="720" height="420" rx="8" />
+  <text class="title" x="24" y="32">solve() median duration</text>
+  <text class="subtitle" x="24" y="50">Scrabble, mid-game board, 7 tiles on the rack, letters replaced by blanks</text>
+  <rect class="series-0" x="24" y="63" width="10" height="10" rx="2" />
+  <text class="legend-label" x="40" y="73">English (US)</text>
+  <rect class="series-1" x="145" y="63" width="10" height="10" rx="2" />
+  <text class="legend-label" x="161" y="73">English (GB)</text>
+  <rect class="series-2" x="266" y="63" width="10" height="10" rx="2" />
+  <text class="legend-label" x="282" y="73">Polish</text>
+  <line class="axis" x1="56" y1="372" x2="696" y2="372" />
+  <text class="tick-label" text-anchor="end" x="48" y="376">0</text>
+  <line class="grid" x1="56" y1="303" x2="696" y2="303" />
+  <text class="tick-label" text-anchor="end" x="48" y="307">0.02s</text>
+  <line class="grid" x1="56" y1="234" x2="696" y2="234" />
+  <text class="tick-label" text-anchor="end" x="48" y="238">0.04s</text>
+  <line class="grid" x1="56" y1="165" x2="696" y2="165" />
+  <text class="tick-label" text-anchor="end" x="48" y="169">0.06s</text>
+  <line class="grid" x1="56" y1="96" x2="696" y2="96" />
+  <text class="tick-label" text-anchor="end" x="48" y="100">0.08s</text>
+  <path class="series-0" d="M 106.67 372 L 106.67 368.78 Q 106.67 365.55 109.9 365.55 L 127.45 365.55 Q 130.67 365.55 130.67 368.78 L 130.67 372 Z" />
+  <text class="value-label" text-anchor="middle" x="118.67" y="359.55">2 ms</text>
+  <path class="series-1" d="M 150.67 372 L 150.67 368.22 Q 150.67 364.44 154.45 364.44 L 170.89 364.44 Q 174.67 364.44 174.67 368.22 L 174.67 372 Z" />
+  <text class="value-label" text-anchor="middle" x="162.67" y="358.44">2 ms</text>
+  <path class="series-2" d="M 194.67 372 L 194.67 369.59 Q 194.67 367.17 197.08 367.17 L 216.26 367.17 Q 218.67 367.17 218.67 369.59 L 218.67 372 Z" />
+  <text class="value-label" text-anchor="middle" x="206.67" y="361.17">1 ms</text>
+  <path class="series-0" d="M 320 372 L 320 337.05 Q 320 333.05 324 333.05 L 340 333.05 Q 344 333.05 344 337.05 L 344 372 Z" />
+  <text class="value-label" text-anchor="middle" x="332" y="327.05">11 ms</text>
+  <path class="series-1" d="M 364 372 L 364 325.84 Q 364 321.84 368 321.84 L 384 321.84 Q 388 321.84 388 325.84 L 388 372 Z" />
+  <text class="value-label" text-anchor="middle" x="376" y="315.84">15 ms</text>
+  <path class="series-2" d="M 408 372 L 408 330.12 Q 408 326.12 412 326.12 L 428 326.12 Q 432 326.12 432 330.12 L 432 372 Z" />
+  <text class="value-label" text-anchor="middle" x="420" y="320.12">13 ms</text>
+  <path class="series-0" d="M 533.33 372 L 533.33 239.86 Q 533.33 235.86 537.33 235.86 L 553.33 235.86 Q 557.33 235.86 557.33 239.86 L 557.33 372 Z" />
+  <text class="value-label" text-anchor="middle" x="545.33" y="229.86">39 ms</text>
+  <path class="series-1" d="M 577.33 372 L 577.33 195.63 Q 577.33 191.63 581.33 191.63 L 597.33 191.63 Q 601.33 191.63 601.33 195.63 L 601.33 372 Z" />
+  <text class="value-label" text-anchor="middle" x="589.33" y="185.63">52 ms</text>
+  <path class="series-2" d="M 621.33 372 L 621.33 147.51 Q 621.33 143.51 625.33 143.51 L 641.33 143.51 Q 645.33 143.51 645.33 147.51 L 645.33 372 Z" />
+  <text class="value-label" text-anchor="middle" x="633.33" y="137.51">66 ms</text>
+  <text class="group-label" text-anchor="middle" x="162.67" y="394">0 blanks</text>
+  <text class="group-label" text-anchor="middle" x="376" y="394">1 blank</text>
+  <text class="group-label" text-anchor="middle" x="589.33" y="394">2 blanks</text>
+</svg>

package/packages/solver/benchmarks/runBenchmarks.ts

@@ -0,0 +1,66 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { getConfig } from '@scrabble-solver/configs';
+import { BLANK } from '@scrabble-solver/constants';
+import { dictionaries } from '@scrabble-solver/dictionaries';
+import { Board, type Config, Game, Tile } from '@scrabble-solver/types';
+
+import { solve } from '../src';
+
+import { formatBlanksCount, formatDuration, median } from './lib';
+import { LANGUAGE_SCENARIOS } from './scenarios';
+import { type LanguageScenario, type Measurement } from './types';
+
+const GAME = Game.Scrabble;
+export const MEASURED_RUNS = 5;
+export const WARMUP_RUNS = 5;
+
+export const runBenchmarks = async (): Promise<Measurement[]> => {
+  const measurements: Measurement[] = [];
+
+  for (const scenario of LANGUAGE_SCENARIOS) {
+    const config = getConfig(GAME, scenario.locale);
+    const gaddag = await dictionaries.get(scenario.locale);
+
+    for (let blanksCount = 0; blanksCount <= config.blanksCount; blanksCount++) {
+      const measurement = measureScenario(gaddag, config, scenario, blanksCount);
+      console.log(
+        `${scenario.label} - ${formatBlanksCount(blanksCount)} - median ${formatDuration(median(measurement.durations))} - ${measurement.resultsCount} results`,
+      );
+      measurements.push(measurement);
+    }
+  }
+
+  return measurements;
+};
+
+const measureScenario = (
+  gaddag: Gaddag,
+  config: Config,
+  scenario: LanguageScenario,
+  blanksCount: number,
+): Measurement => {
+  const durations: number[] = [];
+  let resultsCount = 0;
+
+  for (let run = 0; run < WARMUP_RUNS + MEASURED_RUNS; run++) {
+    const board = Board.fromStringArray(scenario.boardRows);
+    const tiles = generateRack(scenario.baseRack, blanksCount);
+    const start = performance.now();
+    const results = solve(gaddag, config, board, tiles);
+    const duration = performance.now() - start;
+
+    if (run >= WARMUP_RUNS) {
+      durations.push(Number(duration.toFixed(2)));
+    }
+
+    resultsCount = results.length;
+  }
+
+  return { blanksCount, durations, label: scenario.label, locale: scenario.locale, resultsCount };
+};
+
+const generateRack = (baseRack: string[], blanksCount: number): Tile[] => {
+  return baseRack
+    .map((character, index) => (index < baseRack.length - blanksCount ? character : BLANK))
+    .map((character) => new Tile({ character, isBlank: character === BLANK }));
+};

package/packages/solver/benchmarks/scenarios.ts

@@ -0,0 +1,64 @@
+import { Locale } from '@scrabble-solver/types';
+
+import { type LanguageScenario } from './types';
+
+const ENGLISH_BOARD_ROWS = [
+  '               ',
+  '               ',
+  '               ',
+  '               ',
+  '               ',
+  '  cozy         ',
+  '   a           ',
+  '   flames a    ',
+  '        taxi   ',
+  '    ratio e    ',
+  '    a   n      ',
+  '    verge      ',
+  '    e          ',
+  '    n          ',
+  '               ',
+];
+
+const ENGLISH_BASE_RACK = ['r', 'e', 't', 'i', 'n', 'a', 's'];
+
+const POLISH_BOARD_ROWS = [
+  '               ',
+  '               ',
+  '               ',
+  '               ',
+  '   s           ',
+  '   mysz        ',
+  '   a           ',
+  '   korale      ',
+  '        tor    ',
+  '     wino a    ',
+  '     a  s k    ',
+  '  kier         ',
+  '               ',
+  '               ',
+  '               ',
+];
+
+const POLISH_BASE_RACK = ['a', 'e', 'i', 'n', 'o', 'r', 's'];
+
+export const LANGUAGE_SCENARIOS: LanguageScenario[] = [
+  {
+    baseRack: ENGLISH_BASE_RACK,
+    boardRows: ENGLISH_BOARD_ROWS,
+    label: 'English (US)',
+    locale: Locale.EN_US,
+  },
+  {
+    baseRack: ENGLISH_BASE_RACK,
+    boardRows: ENGLISH_BOARD_ROWS,
+    label: 'English (GB)',
+    locale: Locale.EN_GB,
+  },
+  {
+    baseRack: POLISH_BASE_RACK,
+    boardRows: POLISH_BOARD_ROWS,
+    label: 'Polish',
+    locale: Locale.PL_PL,
+  },
+];

package/packages/solver/benchmarks/types.ts

@@ -0,0 +1,16 @@
+import { type Locale } from '@scrabble-solver/types';
+
+export interface LanguageScenario {
+  baseRack: string[];
+  boardRows: string[];
+  label: string;
+  locale: Locale;
+}
+
+export interface Measurement {
+  blanksCount: number;
+  durations: number[];
+  label: string;
+  locale: Locale;
+  resultsCount: number;
+}

package/packages/solver/benchmarks/updateReadme.ts

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { formatDuration, formatInteger, getMeasurement, median, unique } from './lib';
+import { MEASURED_RUNS, WARMUP_RUNS } from './runBenchmarks';
+import { type Measurement } from './types';
+
+const README_PATH = path.join(import.meta.dir, '..', 'README.md');
+
+const START_MARKER = '<!-- benchmark-results:start -->';
+const END_MARKER = '<!-- benchmark-results:end -->';
+
+export const updateReadme = (measurements: Measurement[]): void => {
+  const readme = fs.readFileSync(README_PATH, 'utf-8');
+  const startIndex = readme.indexOf(START_MARKER);
+  const endIndex = readme.indexOf(END_MARKER);
+
+  if (startIndex === -1 || endIndex === -1) {
+    throw new Error(`Cannot update ${README_PATH} - missing "${START_MARKER}" / "${END_MARKER}" markers`);
+  }
+
+  const prefix = readme.slice(0, startIndex + START_MARKER.length);
+  const suffix = readme.slice(endIndex);
+  fs.writeFileSync(README_PATH, `${prefix}\n\n${generateResults(measurements)}\n\n${suffix}`);
+};
+
+const generateResults = (measurements: Measurement[]): string => {
+  return [
+    '![Median solve() duration grouped by number of blanks on the rack](benchmarks/results/chart.svg)',
+    generateTable(measurements),
+    generateFootnote(),
+  ].join('\n\n');
+};
+
+const generateTable = (measurements: Measurement[]): string => {
+  const blanksCounts = unique(measurements.map((measurement) => measurement.blanksCount)).sort((a, b) => a - b);
+  const labels = unique(measurements.map((measurement) => measurement.label));
+  const header = `| Blanks | ${labels.join(' | ')} |`;
+  const separator = `| ${['---', ...labels.map(() => '---')].join(' | ')} |`;
+  const rows = blanksCounts.map((blanksCount) => {
+    const cells = labels.map((label) => {
+      const measurement = getMeasurement(measurements, label, blanksCount);
+      return `${formatDuration(median(measurement.durations))} (${formatInteger(measurement.resultsCount)} results)`;
+    });
+    return `| ${[blanksCount, ...cells].join(' | ')} |`;
+  });
+
+  return [header, separator, ...rows].join('\n');
+};
+
+const generateFootnote = (): string => {
+  return `Median of ${MEASURED_RUNS} runs (after ${WARMUP_RUNS} warmup runs)`;
+};

package/packages/solver/build/MoveGenerator.d.ts

@@ -0,0 +1,116 @@
+import { type Gaddag } from '@kamilmielnik/gaddag';
+import { type Board, type Config, type ResultJson, type Tile } from '@scrabble-solver/types';
+/**
+ * Anchor-based move generation over a {@link Gaddag} (Gordon, 1994).
+ *
+ * For every anchor (an empty cell adjacent to a tile, or the board center when
+ * the board is empty) the generator extends leftwards from the anchor through
+ * the reversed-prefix part of the GADDAG, crosses the separator, and extends
+ * rightwards — validating perpendicular words with precomputed cross-check
+ * masks. Both directions run the same code path: the vertical pass remaps
+ * (line, position) to transposed coordinates. Each placement is scored and
+ * emitted as a compact {@link ResultJson} — placed tiles plus placement — from
+ * which {@link Result.fromJson} rebuilds the full cells and collisions against
+ * the board.
+ */
+export declare class MoveGenerator {
+    private readonly gaddag;
+    private readonly config;
+    private readonly width;
+    private readonly height;
+    private readonly cellsCount;
+    private readonly alphaSize;
+    private readonly alphaChars;
+    private readonly alphaLetter1;
+    private readonly alphaLetter2;
+    private readonly alphaPoints;
+    private readonly leftAlphaStart;
+    private readonly leftAlphaList;
+    private readonly rightAlphaStart;
+    private readonly rightAlphaList;
+    private readonly alphaSecondLeft;
+    private readonly alphaSecondRight;
+    private readonly rackCounts;
+    private blanksLeft;
+    private rackTotal;
+    private readonly bonusType;
+    private readonly bonusMult;
+    private readonly bonusReq;
+    private readonly boardFilled;
+    private readonly boardChar;
+    private readonly boardIsBlank;
+    private readonly boardScore;
+    private readonly boardLetter1;
+    private readonly boardLetter2;
+    private readonly anchor;
+    private boardIsEmpty;
+    private isHorizontal;
+    private lineLength;
+    private linesCount;
+    private readonly passFilled;
+    private readonly passLetter1;
+    private readonly passLetter2;
+    private readonly passScore;
+    private readonly passGlobal;
+    private readonly passAnchor;
+    private readonly maskLo;
+    private readonly maskHi;
+    private readonly crossBase;
+    private readonly hasCross;
+    private line;
+    private lineBase;
+    private anchorPos;
+    private limit;
+    private anchorRightOpen;
+    private leftMost;
+    private readonly placedAt;
+    private readonly placedBlankAt;
+    private placedCount;
+    private readonly digraphs;
+    private readonly blankScore;
+    private readonly rackSize;
+    private readonly seenSingleTiles;
+    private readonly results;
+    private readonly sortKeys;
+    private readonly rankKeys;
+    private readonly alphaFirstRackIndex;
+    private blankRackIndex;
+    constructor(gaddag: Gaddag, config: Config, board: Board, tiles: Tile[]);
+    run(): ResultJson[];
+    private runPass;
+    private setupPass;
+    /**
+     * For every empty cell with perpendicular neighbors, computes the set of
+     * placeable tile characters (as a 64-bit mask), the sum of the existing
+     * perpendicular tiles' scores, and the perpendicular word span.
+     */
+    private computeCrossChecks;
+    /**
+     * A digraph must be played as its single tile, so a candidate that would
+     * spell a digraph with the adjacent perpendicular tile is not placeable.
+     * {@link record} enforces the same rule along the main word.
+     */
+    private spellsDigraphWithNeighbor;
+    private isOpen;
+    private generateLeft;
+    private generateRight;
+    /**
+     * Tries every rack tile (and blank interpretation) at an empty cell,
+     * recursing further. Iterates the state's arcs instead of the alphabet:
+     * deep GADDAG states have very few arcs, so this is much cheaper than
+     * probing every letter.
+     */
+    private placeAt;
+    private pushPlacement;
+    private popPlacement;
+    private afterPlacement;
+    /**
+     * Records a word that ends at the anchor (a pure reversed-word GADDAG path).
+     * Words spanning a single cell are skipped: a lone tile's word is the
+     * perpendicular one, generated by the other pass.
+     */
+    private recordLeftIfWord;
+    private record;
+    private hasInvalidDigraph;
+    private characterAt;
+}