sudoku-pro 1.0.11 → 1.0.12

package/README.md

@@ -1,53 +1,166 @@
-# sudoku-pro: Sudoku Generator and Sudoku Solver
+# sudoku-pro — Sudoku Generator, Solver & CLI (Node + Frontend)
 
-sudoku-pro is a JavaScript package that provides functionalities to generate, solve, and print Sudoku puzzles of varying difficulty levels using the backtracking algorithm. It offers an easy-to-use interface to create and solve Sudoku puzzles for both recreational and educational purposes.
+`sudoku-pro` is a lightweight JavaScript library (plus optional CLI) to **generate**, **solve**, and **play** Sudoku puzzles with built-in difficulty levels.
 
-## Installation
+✅ Works in **Node.js** (CommonJS)
+✅ Works in **Frontend apps** (ES Modules via bundlers like Vite/Webpack)
+✅ Includes a **CLI** for terminal play (hint + complete solution)
 
-You can install the package via npm:
+---
+
+## Install
 
 ```bash
-npm i sudoku-pro
+npm install sudoku-pro
 ```
 
-## Usage
+---
+
+## Difficulty Levels
+
+| Code | Level      |
+|------|------------|
+| `e`  | Easy       |
+| `m`  | Medium     |
+| `h`  | Hard       |
+| `v`  | Very Hard  |
+
+---
 
-```npm
-npm run easy
-npm run medium
-npm run hard
-npm run very
+## CLI (Terminal) Usage
+
+### Run via npx
+
+```bash
+npx sudoku-pro e
+npx sudoku-pro m
+npx sudoku-pro h
+npx sudoku-pro v
 ```
 
-## Example: How to use the functions in your applications
+### CLI Controls
 
-```javascript
-// Import the module
+When the puzzle prints:
+
+- **h** → apply a hint (fills one correct empty cell)
+- **c** → print the complete solution and exit
+
+---
+
+## Node.js Usage (CommonJS)
+
+```js
 const {
   generateSudoku,
   printSudoku,
   solveSudoku,
   getHint,
-  waitForHint,
+  waitForHint
 } = require("sudoku-pro");
 
-// Get the difficulty level
-const args = process.argv.slice(2);
+const { sudoku, solvedSudoku } = generateSudoku("m");
+printSudoku(sudoku);
+waitForHint(sudoku, solvedSudoku);
+```
 
-const difficulty = args[0]; // Get the difficulty level from command line arguments
+---
 
-// Generate a Sudoku puzzle
-const { sudoku, solvedSudoku } = generateSudoku(difficulty);
+## Solve an Existing Puzzle
 
-// Print the puzzle
-printSudoku(sudoku);
+```js
+const { solveSudoku } = require("sudoku-pro");
 
-// Function to wait for user input for hint or complete solution
-waitForHint(sudoku, solvedSudoku);
+const grid = [
+  [0,0,0,0,4,0,0,0,1],
+  [0,0,0,7,0,0,4,6,2],
+  [1,4,6,0,0,3,0,7,0],
+  [0,2,0,3,0,4,0,0,7],
+  [0,9,0,0,0,8,6,1,0],
+  [0,6,0,0,5,0,3,0,0],
+  [0,0,0,8,0,7,2,4,3],
+  [0,8,7,0,0,0,0,5,0],
+  [4,1,2,0,3,6,0,0,0]
+];
+
+solveSudoku(grid);
+console.log(grid);
+```
+
+---
+
+## Frontend Usage (Browser)
+
+### Important
+
+You **cannot** import npm packages directly in plain HTML (`file://`).
+
+You **must** use a bundler such as:
+- Vite (recommended)
+- Webpack
+- Parcel
+
+---
+
+## Frontend Quick Start (Vite)
 
-// This script will continue running until the user chooses to exit
+```bash
+npm create vite@latest sudoku-demo -- --template vanilla
+cd sudoku-demo
+npm install
+npm install sudoku-pro
+npm run dev
+```
+
+---
+
+## Frontend Example
 
-process.exit();
+```js
+import { generateSudoku, getHint } from "sudoku-pro";
+
+const { sudoku, solvedSudoku } = generateSudoku("m");
+const hint = getHint(sudoku, solvedSudoku);
+console.log(hint);
 ```
 
-Now, in addition to generating and solving Sudoku puzzles, users can also request hints or print the complete solution while the script is running.
+---
+
+## API Reference
+
+### generateSudoku(difficulty)
+
+Returns:
+
+```js
+{ sudoku, solvedSudoku }
+```
+
+`sudoku` uses `0` for empty cells.
+
+---
+
+### solveSudoku(grid)
+
+Solves the puzzle **in place**.
+
+---
+
+### getHint(sudoku, solvedSudoku, opts?)
+
+Returns:
+
+```js
+{ row, col, value }
+```
+
+---
+
+### waitForHint(sudoku, solvedSudoku)
+
+Terminal-only interactive mode.
+
+---
+
+## License
+
+MIT © Ashish Vashisht

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sudoku-pro",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Sudoku generator, solver, and CLI tool. Works in terminal and frontend apps with a clean library-first design.",
   "license": "MIT",
   "author": "Ashish Vashisht",