@johnmorrisdotca/kazu 1.2.0 → 1.4.0

package/dist/hitoriBuild.js

@@ -0,0 +1,117 @@
+import { hitoriNeighbors } from "./hitoriBoard.js";
+import { hitoriModel } from "./hitoriLogic.js";
+import { countCsp, openSlots } from "./csp.js";
+import { shuffled } from "./random.js";
+export const SHARE = { easy: .26, medium: .27, hard: .28, "extra-hard": .3 };
+/** A board with one answer, or null when the random choices did not lead to one. How the numbers are chosen leans on the level. */
+export function candidateHitori(size, level, random, base = latinSquare(size, random) ?? []) {
+    const total = size * size;
+    if (base.length !== total)
+        return null;
+    const target = Math.round(total * SHARE[level] * (.9 + random() * .2));
+    const shaded = Array(total).fill(false);
+    let count = 0;
+    const around = Array.from({ length: total }, (_, cell) => hitoriNeighbors(size, cell));
+    const mark = new Int32Array(total), stack = new Int32Array(total);
+    let stamp = 0;
+    const connected = () => {
+        const first = shaded.indexOf(false);
+        stamp += 1;
+        let top = 0, reached = 1;
+        stack[top++] = first;
+        mark[first] = stamp;
+        while (top)
+            for (const next of around[stack[--top]])
+                if (!shaded[next] && mark[next] !== stamp) {
+                    mark[next] = stamp;
+                    reached += 1;
+                    stack[top++] = next;
+                }
+        return reached === total - count;
+    };
+    for (const cell of shuffled(Array.from({ length: total }, (_, i) => i), random)) {
+        if (count >= target)
+            break;
+        if (around[cell].some(next => shaded[next]))
+            continue;
+        shaded[cell] = true;
+        count += 1;
+        if (!connected()) {
+            shaded[cell] = false;
+            count -= 1;
+        }
+    }
+    if (count < Math.max(2, target - 2))
+        return null;
+    const numbers = isotope(base, size, random).map((n, cell) => shaded[cell] ? 0 : n);
+    const partnersOf = (cell) => {
+        const x = cell % size, y = Math.floor(cell / size), found = [];
+        for (let k = 0; k < size; k += 1) {
+            if (k !== x && !shaded[y * size + k])
+                found.push(y * size + k);
+            if (k !== y && !shaded[k * size + x])
+                found.push(k * size + x);
+        }
+        return found;
+    };
+    const blacks = shaded.flatMap((on, cell) => on ? [cell] : []);
+    for (const cell of blacks) {
+        const options = partnersOf(cell);
+        if (!options.length)
+            return null;
+        numbers[cell] = numbers[options[Math.floor(random() * options.length)]];
+    }
+    const board = { size, numbers };
+    const { csp } = hitoriModel(board, 2);
+    let proof = countCsp(csp, openSlots(csp), 2, 20000);
+    for (let repair = 0; repair < 60 && proof.count > 1 && !proof.exhausted; repair += 1) {
+        const other = proof.solutions[1].slice(), mine = (alive, cell) => alive[2 * cell + 1] === 1;
+        const candidates = shuffled(blacks.filter(cell => !mine(other, cell)), random);
+        let changed = false;
+        for (const cell of candidates) {
+            const keepers = partnersOf(cell).filter(p => !mine(other, p));
+            if (!keepers.length)
+                continue;
+            numbers[cell] = numbers[keepers[Math.floor(random() * keepers.length)]];
+            changed = true;
+            break;
+        }
+        if (!changed)
+            return null;
+        proof = countCsp(csp, openSlots(csp), 2, 20000);
+    }
+    if (proof.count !== 1 || proof.exhausted)
+        return null;
+    return { board, shaded };
+}
+/** A random Latin square: every number once in each row and column, built row by row with backtracking. */
+export function latinSquare(size, random) {
+    const cells = Array(size * size).fill(0);
+    let steps = 0;
+    const fill = (at) => {
+        if (at === cells.length)
+            return true;
+        if (++steps > 20000)
+            return false;
+        const x = at % size, y = Math.floor(at / size);
+        const used = new Set();
+        for (let k = 0; k < x; k += 1)
+            used.add(cells[y * size + k]);
+        for (let k = 0; k < y; k += 1)
+            used.add(cells[k * size + x]);
+        for (const n of shuffled(Array.from({ length: size }, (_, i) => i + 1).filter(i => !used.has(i)), random)) {
+            cells[at] = n;
+            if (fill(at + 1))
+                return true;
+        }
+        cells[at] = 0;
+        return false;
+    };
+    return fill(0) ? cells : null;
+}
+/** The same square with its rows, columns and numbers renamed at random: still one of each in every line. */
+export function isotope(square, size, random) {
+    const rows = shuffled(Array.from({ length: size }, (_, i) => i), random), cols = shuffled(Array.from({ length: size }, (_, i) => i), random);
+    const names = shuffled(Array.from({ length: size }, (_, i) => i + 1), random);
+    return Array.from({ length: size * size }, (_, cell) => names[square[rows[Math.floor(cell / size)] * size + cols[cell % size]] - 1]);
+}

package/dist/hitoriGenerate.d.ts

@@ -1,3 +1,10 @@
-import type { HitoriPuzzle } from "./hitori.types.ts";
-/** Seeded number relabelings and board symmetries of original layouts, accepted only after a uniqueness proof. */
-export declare function generateHitori(size?: 5 | 7, seed?: number): HitoriPuzzle;
+import type { HitoriLevel, HitoriPuzzle } from "./hitori.types.ts";
+/**
+ * Makes a seeded puzzle and proves its answer is the only one. The shaded squares are chosen first (never touching,
+ * the rest in one piece), the white squares get numbers that repeat nowhere in their row or column, and every shaded
+ * square takes a number that a white square in its row or column already has. Boards with more than one answer are
+ * repaired by renumbering a shaded square so that the other answer repeats a number, and the result is rated:
+ * easy by the plain rules, medium once the whites must stay in one piece, hard by supposing, and extra-hard the
+ * most-supposing of several boards.
+ */
+export declare function generateHitori(size?: number, seed?: number, level?: HitoriLevel): HitoriPuzzle;

package/dist/hitoriGenerate.js

@@ -1,163 +1,65 @@
-import { HITORI_MAX_NODES, HITORI_SIZES } from "./hitori.constants.js";
+import { HITORI_LEAST_SIDE, HITORI_LEVELS, HITORI_MOST_ATTEMPTS, HITORI_MOST_SIDE } from "./hitori.constants.js";
 import { checkHitori } from "./hitoriBoard.js";
+import { candidateHitori, latinSquare } from "./hitoriBuild.js";
+import { hitoriModel } from "./hitoriLogic.js";
 import { solveHitori } from "./hitoriSolve.js";
-import { isKazuSeed, seededRandom, shuffled } from "./random.js";
-const layouts = {
-    5: [
-        {
-            numbers: [
-                1, 3, 3, 1, 5, 2, 3,
-                4, 5, 1, 3, 4, 5, 1,
-                2, 4, 5, 1, 2, 3, 5,
-                1, 2, 3, 4,
-            ],
-            shade: [
-                false, true, false, true, false, ...Array(20).fill(false),
-            ],
-        },
-        {
-            numbers: [
-                1, 2, 3, 4, 5, 2, 3,
-                4, 1, 1, 3, 4, 5, 1,
-                2, 3, 5, 1, 4, 3, 5,
-                1, 2, 3, 4,
-            ],
-            shade: [
-                false, false, false, false, false, false, false,
-                false, true, false, false, false, false, false,
-                false, true, false, false, true, false, false,
-                false, false, false, false,
-            ],
-        },
-        {
-            numbers: [
-                1, 4, 3, 4, 1, 2, 3,
-                4, 5, 1, 3, 4, 5, 1,
-                2, 4, 5, 1, 2, 3, 5,
-                1, 2, 3, 4,
-            ],
-            shade: [
-                false, true, false, false, true, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false,
-            ],
-        },
-        {
-            numbers: [
-                1, 4, 3, 4, 5, 2, 3,
-                2, 5, 1, 2, 4, 5, 1,
-                2, 4, 5, 1, 2, 3, 5,
-                5, 2, 3, 4,
-            ],
-            shade: [
-                false, true, false, false, false, false, false,
-                true, false, false, true, false, false, false,
-                false, false, false, false, false, false, false,
-                true, false, false, false,
-            ],
-        },
-    ],
-    7: [
-        {
-            numbers: [
-                1, 2, 3, 4, 2, 6, 7,
-                2, 6, 4, 5, 6, 7, 1,
-                3, 4, 5, 6, 1, 1, 1,
-                4, 5, 6, 7, 1, 2, 3,
-                5, 6, 7, 1, 2, 3, 4,
-                6, 7, 1, 2, 3, 4, 5,
-                7, 1, 2, 3, 4, 5, 6,
-            ],
-            shade: [
-                false, false, false, false, true, false, false,
-                false, true, false, false, false, false, false,
-                false, false, false, false, true, false, true,
-                ...Array(28).fill(false),
-            ],
-        },
-        {
-            numbers: [
-                1, 2, 4, 4, 5, 7, 7,
-                2, 3, 4, 5, 5, 7, 1,
-                3, 4, 5, 6, 7, 1, 2,
-                4, 5, 6, 7, 1, 2, 7,
-                5, 6, 7, 1, 2, 3, 4,
-                6, 2, 1, 2, 3, 4, 5,
-                7, 1, 2, 3, 7, 5, 6,
-            ],
-            shade: [
-                false, false, true, false, false, true, false,
-                false, false, false, false, true, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, true,
-                false, false, false, false, false, false, false,
-                false, true, false, false, false, false, false,
-                false, false, false, false, true, false, false,
-            ],
-        },
-        {
-            numbers: [
-                1, 2, 3, 4, 5, 6, 7,
-                2, 3, 4, 5, 6, 7, 1,
-                3, 4, 5, 6, 1, 1, 6,
-                4, 6, 6, 6, 1, 2, 3,
-                5, 6, 7, 1, 2, 3, 4,
-                6, 7, 1, 2, 3, 4, 5,
-                7, 1, 2, 3, 4, 5, 6,
-            ],
-            shade: [
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, true, false, true,
-                false, true, false, true, false, false, false,
-                false, false, false, false, false, false, false,
-                false, ...Array(13).fill(false),
-            ],
-        },
-        {
-            numbers: [
-                1, 2, 3, 4, 6, 6, 7,
-                2, 2, 4, 5, 6, 2, 1,
-                3, 4, 5, 6, 7, 1, 2,
-                4, 5, 6, 7, 1, 2, 3,
-                5, 6, 7, 1, 2, 3, 4,
-                6, 7, 1, 2, 3, 4, 5,
-                7, 1, 2, 3, 6, 5, 6,
-            ],
-            shade: [
-                false, false, false, false, true, false, false,
-                false, true, false, false, false, true, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, false, false, false,
-                false, false, false, false, true, false, false,
-            ],
-        },
-    ],
-};
-/** Seeded number relabelings and board symmetries of original layouts, accepted only after a uniqueness proof. */
-export function generateHitori(size = 5, seed = 1) {
-    if (!HITORI_SIZES.includes(size) || !isKazuSeed(seed))
+import { logicCsp, openSlots } from "./csp.js";
+import { isKazuSeed, seededRandom } from "./random.js";
+/**
+ * Makes a seeded puzzle and proves its answer is the only one. The shaded squares are chosen first (never touching,
+ * the rest in one piece), the white squares get numbers that repeat nowhere in their row or column, and every shaded
+ * square takes a number that a white square in its row or column already has. Boards with more than one answer are
+ * repaired by renumbering a shaded square so that the other answer repeats a number, and the result is rated:
+ * easy by the plain rules, medium once the whites must stay in one piece, hard by supposing, and extra-hard the
+ * most-supposing of several boards.
+ */
+export function generateHitori(size = 5, seed = 1, level = "medium") {
+    if (!Number.isInteger(size) || size < HITORI_LEAST_SIDE || size > HITORI_MOST_SIDE || !isKazuSeed(seed) || !HITORI_LEVELS.includes(level)) {
         throw new RangeError("Invalid Hitori settings");
-    const random = seededRandom(seed), templates = layouts[size];
-    const template = templates[Math.floor(random() * templates.length)];
-    const labels = shuffled(Array.from({ length: size }, (_, index) => index + 1), random);
-    const turns = Math.floor(random() * 4), reflected = random() < 0.5;
-    const numbers = Array(size * size), solution = Array(size * size);
-    for (let y = 0; y < size; y += 1)
-        for (let x = 0; x < size; x += 1) {
-            let tx = reflected ? size - 1 - x : x, ty = y;
-            for (let turn = 0; turn < turns; turn += 1)
-                [tx, ty] = [size - 1 - ty, tx];
-            const source = y * size + x, destination = ty * size + tx;
-            numbers[destination] = labels[template.numbers[source] - 1];
-            solution[destination] = template.shade[source];
+    }
+    const random = seededRandom(seed);
+    const base = latinSquare(size, random);
+    if (!base)
+        throw new Error("No Hitori found within the generation budget; try another seed");
+    for (let aim = HITORI_LEVELS.indexOf(level); aim >= 0; aim -= 1) {
+        const aimed = HITORI_LEVELS[aim];
+        const wanted = aimed === "extra-hard" ? 4 : 1;
+        let best = null, found = 0;
+        for (let attempt = 0; attempt < HITORI_MOST_ATTEMPTS && found < wanted; attempt += 1) {
+            const built = candidateHitori(size, aimed, random, base);
+            const made = built && rated(built.board, built.shaded, aimed);
+            if (!made)
+                continue;
+            found += 1;
+            if (!best || made.score > best.score)
+                best = made;
+        }
+        if (best) {
+            const proof = solveHitori(best.board);
+            if (proof.complete && proof.count === 1 && proof.solution && checkHitori(best.board, proof.solution).ok) {
+                return { ...best.board, seed, level, solution: proof.solution };
+            }
         }
-    const board = { size, numbers }, proof = solveHitori(board, { nodes: HITORI_MAX_NODES });
-    if (!checkHitori(board, solution).ok || !proof.complete || proof.count !== 1 || !proof.solution) {
-        throw new Error("No uniquely solvable Hitori found within the generation budget; try another seed");
     }
-    return { ...board, seed, solution: proof.solution };
+    throw new Error("No uniquely solvable Hitori found within the generation budget; try another seed");
+}
+function rated(board, shaded, level) {
+    const total = board.size * board.size;
+    const solved = (strength, depth) => {
+        const { csp } = hitoriModel(board, strength);
+        const run = logicCsp(csp, openSlots(csp), depth);
+        return run.solved && checkHitori(board, Array.from({ length: total }, (_, cell) => run.alive[2 * cell + 1] === 1)).ok ? run : null;
+    };
+    if (level === "easy")
+        return solved(0, 0) ? { board, shaded, score: 0 } : null;
+    if (solved(0, 0))
+        return null;
+    if (level === "medium")
+        return solved(2, 0) ? { board, shaded, score: 0 } : null;
+    if (solved(2, 0))
+        return null;
+    const probing = solved(2, 1);
+    if (!probing)
+        return level === "extra-hard" ? { board, shaded, score: 1000 } : null;
+    return { board, shaded, score: probing.probes };
 }

package/dist/hitoriLogic.d.ts

@@ -0,0 +1,12 @@
+import type { Csp } from "./csp.ts";
+import type { HitoriBoard } from "./hitori.types.ts";
+/**
+ * Hitori as variables: one per square, slot 0 for left white and slot 1 for shaded.
+ * `strength` is how much of the rules the pruning uses: 0 has the duplicates, the ban on touching shades, the
+ * pair and the sandwich; 1 adds that every white square must stay in reach of the others; 2 adds that a square
+ * whose shading would cut the whites in two must stay white. A finished answer must be one piece, which the
+ * search checks whatever the strength.
+ */
+export declare function hitoriModel(board: HitoriBoard, strength?: 0 | 1 | 2): {
+    csp: Csp;
+};

package/dist/hitoriLogic.js

@@ -0,0 +1,189 @@
+import { hitoriNeighbors } from "./hitoriBoard.js";
+/**
+ * Hitori as variables: one per square, slot 0 for left white and slot 1 for shaded.
+ * `strength` is how much of the rules the pruning uses: 0 has the duplicates, the ban on touching shades, the
+ * pair and the sandwich; 1 adds that every white square must stay in reach of the others; 2 adds that a square
+ * whose shading would cut the whites in two must stay white. A finished answer must be one piece, which the
+ * search checks whatever the strength.
+ */
+export function hitoriModel(board, strength = 2) {
+    const size = board.size, total = size * size;
+    const neighbours = Array.from({ length: total }, (_, cell) => Int32Array.from(hitoriNeighbors(size, cell)));
+    const partners = Array.from({ length: total }, (_, cell) => {
+        const x = cell % size, y = Math.floor(cell / size), found = [];
+        for (let k = 0; k < size; k += 1) {
+            if (k !== x && board.numbers[y * size + k] === board.numbers[cell])
+                found.push(y * size + k);
+            if (k !== y && board.numbers[k * size + x] === board.numbers[cell])
+                found.push(k * size + x);
+        }
+        return Int32Array.from(found);
+    });
+    // A pair of equal numbers side by side shades every other equal number of that line; a number on both sides of a square keeps it white.
+    const pairs = [];
+    const sandwiches = [];
+    for (let y = 0; y < size; y += 1)
+        for (let x = 0; x < size; x += 1) {
+            const cell = y * size + x;
+            for (const [dx, dy] of [[1, 0], [0, 1]]) {
+                const nx = x + dx, ny = y + dy;
+                if (nx >= size || ny >= size)
+                    continue;
+                const next = ny * size + nx;
+                if (board.numbers[cell] === board.numbers[next]) {
+                    const others = partners[cell].filter(other => other !== next && (dx ? Math.floor(other / size) === y : other % size === x));
+                    if (others.length)
+                        pairs.push({ a: cell, b: next, others });
+                }
+                const fx = x + 2 * dx, fy = y + 2 * dy;
+                if (fx < size && fy < size && board.numbers[cell] === board.numbers[fy * size + fx])
+                    sandwiches.push(next);
+            }
+        }
+    const starts = Int32Array.from({ length: total + 1 }, (_, i) => i * 2);
+    const disc = new Int32Array(total), low = new Int32Array(total), whitesBelow = new Int32Array(total);
+    const propagate = (alive) => {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (let c = 0; c < total; c += 1) {
+                const white = alive[2 * c], shaded = alive[2 * c + 1];
+                if (!white && !shaded)
+                    return false;
+                if (shaded && !white) {
+                    const around = neighbours[c];
+                    for (let k = 0; k < around.length; k += 1) {
+                        const n = around[k];
+                        if (alive[2 * n + 1]) {
+                            alive[2 * n + 1] = 0;
+                            changed = true;
+                            if (!alive[2 * n])
+                                return false;
+                        }
+                    }
+                }
+                if (white && !shaded) {
+                    const same = partners[c];
+                    for (let k = 0; k < same.length; k += 1) {
+                        const p = same[k];
+                        if (alive[2 * p]) {
+                            alive[2 * p] = 0;
+                            changed = true;
+                            if (!alive[2 * p + 1])
+                                return false;
+                        }
+                    }
+                }
+                if (shaded) {
+                    // A square is shaded only to settle a duplicate, so some equal number in its row or column must stay white.
+                    const same = partners[c];
+                    let free = 0, last = -1;
+                    for (let k = 0; k < same.length; k += 1)
+                        if (alive[2 * same[k]]) {
+                            free += 1;
+                            last = same[k];
+                        }
+                    if (free === 0) {
+                        if (!white)
+                            return false;
+                        alive[2 * c + 1] = 0;
+                        changed = true;
+                    }
+                    else if (free === 1 && !white && alive[2 * last + 1]) {
+                        alive[2 * last + 1] = 0;
+                        changed = true;
+                    }
+                }
+            }
+            for (const { a, b, others } of pairs) {
+                if (!alive[2 * a] && !alive[2 * b])
+                    continue;
+                for (let k = 0; k < others.length; k += 1) {
+                    const o = others[k];
+                    if (alive[2 * o]) {
+                        alive[2 * o] = 0;
+                        changed = true;
+                        if (!alive[2 * o + 1])
+                            return false;
+                    }
+                }
+            }
+            for (let k = 0; k < sandwiches.length; k += 1) {
+                const m = sandwiches[k];
+                if (alive[2 * m + 1]) {
+                    alive[2 * m + 1] = 0;
+                    changed = true;
+                    if (!alive[2 * m])
+                        return false;
+                }
+            }
+            if (strength > 0) {
+                const verdict = reach(alive);
+                if (verdict < 0)
+                    return false;
+                if (verdict > 0)
+                    changed = true;
+            }
+        }
+        return true;
+    };
+    const cutList = new Int32Array(total);
+    let clock = 0, cutCount = 0, whiteTotal = 0, current = new Uint8Array(0), power = 0;
+    const visit = (u, parent) => {
+        disc[u] = low[u] = ++clock;
+        let below = current[2 * u + 1] ? 0 : 1, cutWhites = 0, cutParts = 0;
+        const around = neighbours[u];
+        for (let k = 0; k < around.length; k += 1) {
+            const n = around[k];
+            if (!current[2 * n] || n === parent)
+                continue;
+            if (disc[n]) {
+                if (disc[n] < low[u])
+                    low[u] = disc[n];
+                continue;
+            }
+            visit(n, u);
+            if (low[n] < low[u])
+                low[u] = low[n];
+            below += whitesBelow[n];
+            if (low[n] >= disc[u] && whitesBelow[n] > 0) {
+                cutParts += 1;
+                cutWhites += whitesBelow[n];
+            }
+        }
+        whitesBelow[u] = below;
+        if (power > 1 && current[2 * u] && current[2 * u + 1] && cutParts + (whiteTotal - cutWhites > 0 ? 1 : 0) >= 2)
+            cutList[cutCount++] = u;
+    };
+    /** -1 when the white squares cannot be one piece, 1 when a square was forced white, 0 when nothing moved. */
+    const reach = (alive) => {
+        let root = -1;
+        whiteTotal = 0;
+        for (let c = 0; c < total; c += 1)
+            if (!alive[2 * c + 1]) {
+                whiteTotal += 1;
+                if (root < 0)
+                    root = c;
+            }
+        if (root < 0)
+            return 0;
+        if (!alive[2 * root])
+            return -1;
+        disc.fill(0);
+        clock = 0;
+        cutCount = 0;
+        current = alive;
+        power = strength;
+        visit(root, -1);
+        let seenWhites = 0;
+        for (let c = 0; c < total; c += 1)
+            if (!alive[2 * c + 1] && disc[c])
+                seenWhites += 1;
+        if (seenWhites !== whiteTotal)
+            return -1;
+        for (let k = 0; k < cutCount; k += 1)
+            alive[2 * cutList[k] + 1] = 0;
+        return cutCount ? 1 : 0;
+    };
+    return { csp: { starts, propagate } };
+}

package/dist/hitoriRate.d.ts

@@ -0,0 +1,3 @@
+import type { HitoriBoard, HitoriRating } from "./hitori.types.ts";
+/** Rates a board with one answer by solving it: with the plain rules, with the whites-stay-together rule, then by supposing. */
+export declare function rateHitori(board: HitoriBoard): HitoriRating;

package/dist/hitoriRate.js

@@ -0,0 +1,32 @@
+import { checkHitori, isHitoriBoard } from "./hitoriBoard.js";
+import { hitoriModel } from "./hitoriLogic.js";
+import { logicCsp, openSlots, solveCsp } from "./csp.js";
+/** Rates a board with one answer by solving it: with the plain rules, with the whites-stay-together rule, then by supposing. */
+export function rateHitori(board) {
+    if (!isHitoriBoard(board))
+        throw new RangeError("Invalid Hitori board");
+    const strong = hitoriModel(board, 2).csp;
+    const proof = solveCsp(strong, openSlots(strong), 2, 300000);
+    if (proof.count !== 1 || proof.exhausted)
+        throw new RangeError("Hitori rating needs a board with one answer");
+    const shaded = Array.from({ length: board.size ** 2 }, (_, cell) => proof.solution[2 * cell + 1] === 1);
+    const solvedBy = (strength, depth) => {
+        const { csp } = hitoriModel(board, strength);
+        const run = logicCsp(csp, openSlots(csp), depth);
+        return { ...run, solved: run.solved && checkHitori(board, Array.from({ length: board.size ** 2 }, (_, cell) => run.alive[2 * cell + 1] === 1)).ok };
+    };
+    const plain = solvedBy(0, 0), reach = plain.solved ? plain : solvedBy(2, 0);
+    const probing = reach.solved ? reach : solvedBy(2, 1);
+    const repeats = board.numbers.filter((_, cell) => {
+        const x = cell % board.size, y = Math.floor(cell / board.size);
+        return board.numbers.some((other, at) => at !== cell && other === board.numbers[cell] && (at % board.size === x || Math.floor(at / board.size) === y));
+    }).length;
+    return {
+        depth: reach.solved ? 0 : probing.solved ? 1 : 2,
+        reach: !plain.solved && reach.solved,
+        probes: reach.solved ? 0 : probing.probes,
+        shaded: shaded.filter(Boolean).length,
+        shadedShare: shaded.filter(Boolean).length / shaded.length,
+        repeatShare: repeats / shaded.length,
+    };
+}

package/dist/hitoriSolve.d.ts

@@ -1,5 +1,8 @@
 import type { HitoriBoard, HitoriSolve } from "./hitori.types.ts";
-/** Counts distinct minimal shade patterns. A non-complete result never asserts uniqueness. */
+/**
+ * Counts distinct minimal shade patterns: an answer shades only squares that settle a duplicate, so extra shades
+ * are never a second answer. A non-complete result never asserts uniqueness.
+ */
 export declare function solveHitori(board: HitoriBoard, options?: {
     limit?: number;
     nodes?: number;