Add solution reveal trace export and visualizer

Author: SaridakisStamatisChristos

README.md

@@ -73,6 +73,11 @@ sudoku-dlx stats-file --in puzzles.txt --json stats.json --csv diff_hist.csv
 # Minimal & symmetry (slower; strict guarantee)
 sudoku-dlx gen   --seed 123 --givens 28 --minimal
 sudoku-dlx gen   --seed 123 --givens 28 --minimal --symmetry rot180
+
+# Trace & Visualize
+sudoku-dlx solve --grid "<81chars>" --trace out.json
+# Then open web/visualizer.html in your browser and load out.json
+# (works on GitHub Pages)
 ```
 
 What this gives you

src/sudoku_dlx/__init__.py

@@ -10,6 +10,7 @@
     analyze,
     solve,
     to_string,
+    build_reveal_trace,
 )
 from .canonical import canonical_form
 from .generate import generate
@@ -33,6 +34,7 @@
     "SolveResult",
     "from_string",
     "to_string",
+    "build_reveal_trace",
     "is_valid",
     "solve",
     "analyze",

src/sudoku_dlx/api.py

@@ -2,7 +2,7 @@
 
 from dataclasses import dataclass
 from time import perf_counter
-from typing import List, Optional, Dict, Any
+from typing import List, Optional, Dict, Any, Iterable, Tuple
 
 Grid = List[List[int]]
 
@@ -91,6 +91,33 @@ def count_solutions(grid: Grid, limit: int = 2) -> int:
     return engine.count(rows, limit=limit)
 
 
+def build_reveal_trace(initial: Grid, solved: Grid, stats: Stats) -> Dict[str, Any]:
+    """
+    Build a simple, deterministic 'solution_reveal' trace:
+      - initial: 81-char string (with '.')
+      - solution: 81-char string
+      - steps: list of {r,c,v} filling all blanks in row-major order
+      - stats: ms, nodes, backtracks
+    This is NOT a DLX cover/uncover trace, but is ideal for visual replay.
+    """
+    init_s = to_string(initial)
+    sol_s = to_string(solved)
+    steps: List[Dict[str, int]] = []
+    for i, ch in enumerate(init_s):
+        if ch == ".":
+            r, c = divmod(i, 9)
+            v = int(sol_s[i])
+            steps.append({"r": r, "c": c, "v": v})
+    return {
+        "version": "reveal-1",
+        "kind": "solution_reveal",
+        "initial": init_s,
+        "solution": sol_s,
+        "steps": steps,
+        "stats": {"ms": int(round(stats.ms)), "nodes": int(stats.nodes), "backtracks": int(stats.backtracks)},
+    }
+
+
 def analyze(grid: Grid) -> Dict[str, Any]:
     """
     Return a compact analysis dict for a Sudoku grid. Keys:
@@ -140,6 +167,7 @@ def analyze(grid: Grid) -> Dict[str, Any]:
     "SolveResult",
     "from_string",
     "to_string",
+    "build_reveal_trace",
     "is_valid",
     "solve",
     "count_solutions",

src/sudoku_dlx/cli.py

@@ -9,7 +9,7 @@
 import time
 from typing import Optional
 
-from .api import analyze, from_string, is_valid, solve, to_string
+from .api import analyze, build_reveal_trace, from_string, is_valid, solve, to_string
 from .canonical import canonical_form
 from .generate import generate
 from .rating import rate
@@ -60,6 +60,11 @@ def cmd_solve(ns: argparse.Namespace) -> int:
         _print_grid(result.grid)
     else:
         print(to_string(result.grid))
+    if ns.trace:
+        trace = build_reveal_trace(grid, result.grid, result.stats)
+        outp = pathlib.Path(ns.trace)
+        outp.parent.mkdir(parents=True, exist_ok=True)
+        outp.write_text(json.dumps(trace, indent=2, sort_keys=True), encoding="utf-8")
     if ns.stats:
         print(
             f"# solved in {result.stats.ms:.2f} ms · nodes {result.stats.nodes} · backtracks {result.stats.backtracks}",
@@ -279,6 +284,7 @@ def main(argv: Optional[list[str]] = None) -> int:
     solve_parser.add_argument("--file", help="path to a file with 9 lines of 9 chars")
     solve_parser.add_argument("--pretty", action="store_true", help="print 9x9 grid format")
     solve_parser.add_argument("--stats", action="store_true", help="print timing & node stats to stderr")
+    solve_parser.add_argument("--trace", help="write a solution-reveal trace JSON to this path")
     solve_parser.set_defaults(func=cmd_solve)
 
     rate_parser = sub.add_parser("rate", help="estimate difficulty in [0,10]")

tests/test_trace.py

@@ -0,0 +1,49 @@
+from textwrap import dedent
+import json
+from sudoku_dlx import cli, from_string, to_string, solve, build_reveal_trace
+
+PUZ = dedent(
+    """
+    53..7....
+    6..195...
+    .98....6.
+    8...6...3
+    4..8.3..1
+    7...2...6
+    .6....28.
+    ...419..5
+    ....8..79
+    """
+).strip()
+
+
+def _apply_reveal(initial81: str, steps):
+    grid = [list(initial81[r * 9 : (r + 1) * 9]) for r in range(9)]
+    for step in steps:
+        r, c, v = step["r"], step["c"], step["v"]
+        grid[r][c] = str(v)
+    return "".join("".join(row) for row in grid)
+
+
+def test_build_reveal_trace_roundtrip():
+    g = from_string(PUZ)
+    res = solve(g)
+    assert res is not None
+    tr = build_reveal_trace(g, res.grid, res.stats)
+    assert tr["kind"] == "solution_reveal"
+    assert len(tr["initial"]) == 81 and len(tr["solution"]) == 81
+    # replay steps produces the solved string
+    after = _apply_reveal(tr["initial"], tr["steps"])
+    assert after == tr["solution"]
+
+
+def test_cli_solve_writes_trace(tmp_path):
+    out = tmp_path / "trace.json"
+    rc = cli.main(["solve", "--grid", PUZ, "--trace", str(out)])
+    assert rc == 0
+    data = json.loads(out.read_text(encoding="utf-8"))
+    assert data["kind"] == "solution_reveal"
+    assert "stats" in data and "steps" in data
+    # steps must fill exactly the blanks from initial
+    blanks = sum(1 for ch in data["initial"] if ch == ".")
+    assert blanks == len(data["steps"])

web/visualizer.html

@@ -0,0 +1,119 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Sudoku DLX — Solution Replay</title>
+  <style>
+    body { font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; margin: 24px; }
+    .grid { border-collapse: collapse; margin: 16px 0; }
+    .grid td { width: 32px; height: 32px; text-align: center; font-size: 18px; border: 1px solid #ccc; }
+    .grid td.bold-right { border-right: 2px solid #000; }
+    .grid td.bold-bottom { border-bottom: 2px solid #000; }
+    .stats { margin: 8px 0; color: #444; }
+    .controls button { margin-right: 8px; }
+    .filled { background: #eaf7ff; }
+    .given  { background: #f6f6f6; font-weight: 600; }
+  </style>
+</head>
+<body>
+  <h1>Sudoku DLX — Solution Replay</h1>
+  <p>Load a <code>solution_reveal</code> JSON produced by <code>sudoku-dlx solve --trace out.json</code>.</p>
+  <input type="file" id="file" accept="application/json" />
+  <div class="stats" id="stats"></div>
+  <div class="controls">
+    <button id="btn-begin" disabled>&laquo; Begin</button>
+    <button id="btn-prev" disabled>&lsaquo; Step</button>
+    <button id="btn-play" disabled>Play</button>
+    <button id="btn-next" disabled>Step &rsaquo;</button>
+    <button id="btn-end" disabled>End &raquo;</button>
+  </div>
+  <table class="grid" id="grid"></table>
+
+  <script>
+    const gridEl = document.getElementById('grid');
+    const statsEl = document.getElementById('stats');
+    let trace = null, idx = 0, playing = null, initial = null, givenMask = null;
+
+    function buildGrid() {
+      gridEl.innerHTML = '';
+      for (let r = 0; r < 9; r++) {
+        const tr = document.createElement('tr');
+        for (let c = 0; c < 9; c++) {
+          const td = document.createElement('td');
+          td.id = `cell-${r}-${c}`;
+          if ((c+1) % 3 === 0 && c < 8) td.classList.add('bold-right');
+          if ((r+1) % 3 === 0 && r < 8) td.classList.add('bold-bottom');
+          tr.appendChild(td);
+        }
+        gridEl.appendChild(tr);
+      }
+    }
+    function setCell(r,c,val,klass) {
+      const td = document.getElementById(`cell-${r}-${c}`);
+      td.textContent = val || '';
+      td.classList.remove('filled', 'given');
+      if (klass) td.classList.add(klass);
+    }
+    function loadInitial(initial81) {
+      initial = initial81;
+      givenMask = [];
+      for (let i=0;i<81;i++) {
+        const r = Math.floor(i/9), c = i%9;
+        const ch = initial81[i];
+        const isGiven = ch !== '.';
+        givenMask.push(isGiven);
+        setCell(r,c,isGiven ? ch : '', isGiven ? 'given' : null);
+      }
+    }
+    function replayTo(k) {
+      // reset to initial
+      loadInitial(initial);
+      for (let i=0;i<k;i++) {
+        const {r,c,v} = trace.steps[i];
+        setCell(r,c,String(v),'filled');
+      }
+      idx = k;
+      updateButtons();
+    }
+    function updateButtons() {
+      const disabled = !trace;
+      document.getElementById('btn-begin').disabled = disabled || idx===0;
+      document.getElementById('btn-prev').disabled  = disabled || idx===0;
+      document.getElementById('btn-next').disabled  = disabled || idx>=trace.steps.length;
+      document.getElementById('btn-end').disabled   = disabled || idx>=trace.steps.length;
+      document.getElementById('btn-play').disabled  = disabled;
+      document.getElementById('btn-play').textContent = playing ? 'Pause' : 'Play';
+    }
+
+    document.getElementById('file').addEventListener('change', async (e) => {
+      const file = e.target.files[0];
+      if (!file) return;
+      const text = await file.text();
+      const data = JSON.parse(text);
+      if (data.kind !== 'solution_reveal') { alert('Unexpected trace kind'); return; }
+      trace = data; idx = 0;
+      buildGrid();
+      loadInitial(trace.initial);
+      statsEl.textContent = `steps: ${trace.steps.length} · ${trace.stats.ms} ms · nodes ${trace.stats.nodes} · backtracks ${trace.stats.backtracks}`;
+      updateButtons();
+    });
+
+    document.getElementById('btn-begin').onclick = () => replayTo(0);
+    document.getElementById('btn-prev').onclick  = () => replayTo(Math.max(0, idx-1));
+    document.getElementById('btn-next').onclick  = () => replayTo(Math.min(trace.steps.length, idx+1));
+    document.getElementById('btn-end').onclick   = () => replayTo(trace.steps.length);
+    document.getElementById('btn-play').onclick  = () => {
+      if (!trace) return;
+      if (playing) { clearInterval(playing); playing = null; updateButtons(); return; }
+      playing = setInterval(() => {
+        if (idx >= trace.steps.length) { clearInterval(playing); playing = null; updateButtons(); return; }
+        replayTo(idx+1);
+      }, 60);
+      updateButtons();
+    };
+
+    buildGrid();
+  </script>
+</body>
+</html>