sweepwright

A fast Minesweeper solver bot framework built with Node.js + Playwright. The project ships with a local Minesweeper demo, a pluggable DOM adapter system, and a solver tuned for speedy deterministic play with graceful fallbacks when guessing is required.

Requirements

• Node.js 18+

Setup

Install dependencies once before running any scripts:

npm install

Quick start

Use the bundled demo or point the solver at a supported remote page.

• Open the bundled Minesweeper demo and solve it automatically:

  npm run dev -- --level expert --speed 10

• Point the solver at an allowed remote page (for example, Minesweeper Online):

  npm run dev -- --url "https://minesweeperonline.com" --speed 20

  The runner appends the appropriate hash for the chosen difficulty:

  • beginner → https://minesweeperonline.com/#beginner
  • intermediate → https://minesweeperonline.com/#intermediate
  • expert (default) → https://minesweeperonline.com/#

When --serve is enabled (the default for npm run dev), the project hosts the local demo at http://localhost:4173 and the solver attaches to it automatically. Use npm run serve if you only need the static demo without launching Playwright.

Features

• Deterministic-first solver that builds constraints from the visible board, searches for forced moves, and only guesses as a last resort.
• Pluggable adapters so the solver can target the bundled demo or other allowed Minesweeper pages.
• HUD overlays inside the controlled page that display elapsed time, move count, solver mode, and guess count while the bot runs.
• Scriptable CLI with presets for common flows (local demo, Minesweeper Online, or custom URLs).

CLI reference

Common flags are documented below; combine them as needed when invoking npm run dev or npm run run:

• --level beginner|intermediate|expert (default: beginner)
• --seed seed for deterministic board (default: timestamp)
• --speed delay in ms between action batches (default: 0)
• --headless run browser headless (default: false)
• --serve start the built-in static server (enabled by default in npm run dev)
• --url point the runner at a different page; omit to use the local demo
• --keepOpen keep the Playwright window open after solving (default: true)

The solver overlays a HUD showing elapsed time, moves, guesses, and the active mode (deterministic, search, or guess).

Helpful scripts

• npm run serve – start the demo server without launching the solver.
• npm run run – run the solver without forcing the local server (useful if you are already hosting a page).
• npm run run:beginner, npm run run:intermediate, npm run run:expert – convenience presets for Minesweeper Online with --keepOpen enabled.

Configuration tips

• Increase --speed (ms) to slow the solver for debugging and to watch the HUD update.
• Pass --headless for automated runs when you do not need to watch the browser.
• Disable serving with --url when pointing at an already-hosted page.

How the bot works

At a high level, the CLI runner starts a browser, chooses an adapter based on the target page, loops through reading board state, computing solver actions, applying them, and updating the HUD, then prints a summary. See docs/how-the-bot-works.md for a deeper walkthrough.

Project layout

• src/solver/* – pure solver logic (board helpers, constraint builder, search enumerator)
• src/adapter/* – automation interfaces, including the Playwright DOM adapter used for the local app
• src/run.ts – CLI entry point that spins up the server, launches Playwright, and drives the solver
• web/ – static Minesweeper demo used for local runs
• tests/ – vitest unit tests for constraint components and pruning

Adding a new adapter

Implement the DomAdapter interface from src/adapter/types.ts with readState, applyActions, and updateHud methods. The adapter should return the board state as an Int8Array using the encoding:

• -1 unknown
• -2 flagged
• 0..8 revealed numbers

See PlaywrightDomAdapter for an example that uses in-page APIs exposed by the demo app.

Testing

npm test