@johnmorrisdotca/kazu 1.2.0 → 1.3.0

package/dist/shikakuGenerate.d.ts

@@ -1,3 +1,8 @@
 import type { ShikakuLevel, ShikakuPuzzle } from "./shikaku.types.ts";
-/** Seeded partitions with an independently counted, unique answer. Levels choose rectangle sizes, not a promised human rating. */
+/**
+ * Seeded rectangles packed into the board, one number each, with an independently counted, unique answer. The board
+ * is rated by solving it: easy by the first two rules (a number with one fitting rectangle, a square one rectangle can
+ * cover), medium once the third rule is needed too, hard by supposing, extra-hard the most-supposing of several boards. If no board of the level is found within the attempts
+ * the next level down is tried, and the first generator is the last resort.
+ */
 export declare function generateShikaku(width?: number, height?: number, level?: ShikakuLevel, seed?: number): ShikakuPuzzle;

package/dist/shikakuGenerate.js

@@ -1,43 +1,58 @@
-import { SHIKAKU_LEVELS, SHIKAKU_MOST_ATTEMPTS } from "./shikaku.constants.js";
-import { isShikakuBoard, shikakuCells } from "./shikakuBoard.js";
+import { SHIKAKU_LEVELS, SHIKAKU_MOST_ATTEMPTS, SHIKAKU_MOST_SIDE } from "./shikaku.constants.js";
+import { checkShikaku } from "./shikakuBoard.js";
+import { candidateShikaku } from "./shikakuBuild.js";
+import { shikakuModel } from "./shikakuLogic.js";
 import { solveShikaku } from "./shikakuSolve.js";
+import { templateShikaku } from "./shikakuTemplate.js";
+import { logicCsp, openSlots } from "./csp.js";
 import { isKazuSeed, seededRandom } from "./random.js";
-/** Seeded partitions with an independently counted, unique answer. Levels choose rectangle sizes, not a promised human rating. */
+/**
+ * Seeded rectangles packed into the board, one number each, with an independently counted, unique answer. The board
+ * is rated by solving it: easy by the first two rules (a number with one fitting rectangle, a square one rectangle can
+ * cover), medium once the third rule is needed too, hard by supposing, extra-hard the most-supposing of several boards. If no board of the level is found within the attempts
+ * the next level down is tried, and the first generator is the last resort.
+ */
 export function generateShikaku(width = 7, height = width, level = "medium", seed = 1) {
-    if (![width, height].every(n => Number.isInteger(n) && n >= 2 && n <= 16))
-        throw new RangeError("Invalid Shikaku dimensions");
-    const empty = { width, height, clues: Array(width * height).fill(0) };
-    if (!isKazuSeed(seed) || !SHIKAKU_LEVELS.includes(level)
-        || !isShikakuBoard({ ...empty, clues: [width * height, ...empty.clues.slice(1)] }))
+    if (![width, height].every(n => Number.isInteger(n) && n >= 2 && n <= SHIKAKU_MOST_SIDE)
+        || !isKazuSeed(seed) || !SHIKAKU_LEVELS.includes(level))
         throw new RangeError("Invalid Shikaku settings");
-    const random = seededRandom(seed), maximum = { easy: 5, medium: 9, hard: 15 }[level];
-    for (let attempt = 0; attempt < SHIKAKU_MOST_ATTEMPTS; attempt += 1) {
-        const solution = [];
-        const split = (r) => {
-            if (r.width * r.height <= maximum && (r.width * r.height < 3 || random() < .6)) {
-                solution.push(r);
-                return;
-            }
-            const vertical = r.height === 1 || (r.width > 1 && random() < .5);
-            const cut = 1 + Math.floor(random() * ((vertical ? r.width : r.height) - 1));
-            if (vertical) {
-                split({ ...r, width: cut });
-                split({ ...r, x: r.x + cut, width: r.width - cut });
-            }
-            else {
-                split({ ...r, height: cut });
-                split({ ...r, y: r.y + cut, height: r.height - cut });
+    const random = seededRandom(seed);
+    for (let aim = SHIKAKU_LEVELS.indexOf(level); aim >= 0; aim -= 1) {
+        const aimed = SHIKAKU_LEVELS[aim];
+        const wanted = aimed === "extra-hard" ? 3 : 1;
+        let best = null, found = 0;
+        for (let attempt = 0; attempt < SHIKAKU_MOST_ATTEMPTS && found < wanted; attempt += 1) {
+            const built = candidateShikaku(width, height, aimed, random);
+            if (!built)
+                continue;
+            const score = scored(built.board, aimed);
+            if (score === null)
+                continue;
+            found += 1;
+            if (!best || score > best.score)
+                best = { board: built.board, score };
+        }
+        if (best) {
+            const proof = solveShikaku(best.board);
+            if (proof.complete && proof.count === 1 && proof.solution && checkShikaku(best.board, proof.solution).ok) {
+                return { ...best.board, seed, level, solution: proof.solution };
             }
-        };
-        split({ x: 0, y: 0, width, height });
-        const clues = [...empty.clues];
-        for (const r of solution) {
-            const cells = shikakuCells(empty, r);
-            clues[cells[Math.floor(random() * cells.length)]] = cells.length;
         }
-        const board = { width, height, clues }, counted = solveShikaku(board);
-        if (counted.complete && counted.count === 1)
-            return { ...board, seed, level, solution: counted.solution };
     }
-    throw new Error("No unique Shikaku found within the generation budget; try another seed");
+    return { ...templateShikaku(width, height, level === "extra-hard" ? "hard" : level, seed), level };
+}
+/** Whether a board suits a level, and how well: higher is harder. */
+function scored(board, level) {
+    const models = [shikakuModel(board, 1), shikakuModel(board, 2)];
+    const solves = (index, depth) => logicCsp(models[index].csp, openSlots(models[index].csp), depth);
+    if (solves(0, 0).solved)
+        return level === "easy" ? 0 : null;
+    if (level === "easy")
+        return null;
+    if (solves(1, 0).solved)
+        return level === "medium" ? 0 : null;
+    if (level === "medium")
+        return null;
+    const probing = solves(1, 1);
+    return probing.solved ? probing.probes : level === "extra-hard" ? 1000 : null;
 }

package/dist/shikakuLogic.d.ts

@@ -0,0 +1,13 @@
+import type { Csp } from "./csp.ts";
+import type { ShikakuBoard, ShikakuRectangle } from "./shikaku.types.ts";
+/**
+ * Shikaku as variables: one per numbered square, its slots the rectangles it could be the one number of. A rectangle
+ * that is settled keeps every other rectangle off its squares. With `strength` 1 a square only one rectangle can
+ * still cover is covered by it, and with 2 a square only one number can still reach forces that number's rectangle to cover it.
+ */
+export declare function shikakuModel(board: ShikakuBoard, strength?: 0 | 1 | 2): {
+    csp: Csp;
+    clues: readonly number[];
+    rectangles: readonly ShikakuRectangle[];
+    owner: Int32Array;
+};

package/dist/shikakuLogic.js

@@ -0,0 +1,84 @@
+import { shikakuCandidates, shikakuCells } from "./shikakuBoard.js";
+/**
+ * Shikaku as variables: one per numbered square, its slots the rectangles it could be the one number of. A rectangle
+ * that is settled keeps every other rectangle off its squares. With `strength` 1 a square only one rectangle can
+ * still cover is covered by it, and with 2 a square only one number can still reach forces that number's rectangle to cover it.
+ */
+export function shikakuModel(board, strength = 2) {
+    const clues = board.clues.flatMap((n, cell) => n ? [cell] : []);
+    const rectangles = [], owner = [], covers = [], starts = [0];
+    clues.forEach((cell, variable) => {
+        for (const rectangle of shikakuCandidates(board, cell)) {
+            rectangles.push(rectangle);
+            owner.push(variable);
+            covers.push(Int32Array.from(shikakuCells(board, rectangle)));
+        }
+        starts.push(rectangles.length);
+    });
+    const through = Array.from({ length: board.clues.length }, () => []);
+    covers.forEach((cells, slot) => cells.forEach(cell => through[cell].push(slot)));
+    const propagate = (alive) => {
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (let v = 0; v < clues.length; v += 1) {
+                let left = 0, only = -1;
+                for (let s = starts[v]; s < starts[v + 1]; s += 1)
+                    if (alive[s]) {
+                        left += 1;
+                        only = s;
+                    }
+                if (!left)
+                    return false;
+                if (left !== 1)
+                    continue;
+                const cells = covers[only];
+                for (let k = 0; k < cells.length; k += 1) {
+                    const others = through[cells[k]];
+                    for (let j = 0; j < others.length; j += 1) {
+                        const t = others[j];
+                        if (t !== only && alive[t] && owner[t] !== v) {
+                            alive[t] = 0;
+                            changed = true;
+                        }
+                    }
+                }
+            }
+            if (strength < 1)
+                continue;
+            for (let cell = 0; cell < through.length; cell += 1) {
+                const slots = through[cell];
+                let count = 0, only = -1, single = true, first = -1;
+                for (let k = 0; k < slots.length; k += 1) {
+                    const s = slots[k];
+                    if (!alive[s])
+                        continue;
+                    count += 1;
+                    only = s;
+                    if (first < 0)
+                        first = owner[s];
+                    else if (owner[s] !== first)
+                        single = false;
+                }
+                if (!count)
+                    return false;
+                if (count === 1) {
+                    for (let s = starts[owner[only]]; s < starts[owner[only] + 1]; s += 1)
+                        if (s !== only && alive[s]) {
+                            alive[s] = 0;
+                            changed = true;
+                        }
+                }
+                else if (single && strength > 1) {
+                    for (let s = starts[first]; s < starts[first + 1]; s += 1)
+                        if (alive[s] && !covers[s].includes(cell)) {
+                            alive[s] = 0;
+                            changed = true;
+                        }
+                }
+            }
+        }
+        return true;
+    };
+    return { csp: { starts: Int32Array.from(starts), propagate }, clues, rectangles, owner: Int32Array.from(owner) };
+}

package/dist/shikakuRate.d.ts

@@ -0,0 +1,3 @@
+import type { ShikakuBoard, ShikakuRating } from "./shikaku.types.ts";
+/** Rates a board with one answer by solving it with the first rule, with the first two, with all three, then by supposing. */
+export declare function rateShikaku(board: ShikakuBoard): ShikakuRating;

package/dist/shikakuRate.js

@@ -0,0 +1,27 @@
+import { isShikakuBoard } from "./shikakuBoard.js";
+import { shikakuModel } from "./shikakuLogic.js";
+import { logicCsp, openSlots, solveCsp } from "./csp.js";
+/** Rates a board with one answer by solving it with the first rule, with the first two, with all three, then by supposing. */
+export function rateShikaku(board) {
+    if (!isShikakuBoard(board))
+        throw new RangeError("Invalid Shikaku board");
+    const first = shikakuModel(board, 0), second = shikakuModel(board, 1), strong = shikakuModel(board, 2);
+    const proof = solveCsp(strong.csp, openSlots(strong.csp), 2, 100000);
+    if (proof.count !== 1 || proof.exhausted)
+        throw new RangeError("Shikaku rating needs a board with one answer");
+    const one = logicCsp(first.csp, openSlots(first.csp), 0);
+    const two = one.solved ? one : logicCsp(second.csp, openSlots(second.csp), 0);
+    const rules = two.solved ? two : logicCsp(strong.csp, openSlots(strong.csp), 0);
+    const probing = rules.solved ? rules : logicCsp(strong.csp, openSlots(strong.csp), 1);
+    const areas = strong.clues.map(cell => board.clues[cell]);
+    const options = strong.clues.map((_, v) => strong.csp.starts[v + 1] - strong.csp.starts[v]);
+    return {
+        depth: rules.solved ? 0 : probing.solved ? 1 : 2,
+        rules: one.solved ? 1 : two.solved ? 2 : 3,
+        probes: rules.solved ? 0 : probing.probes,
+        rectangles: areas.length,
+        meanArea: board.clues.length / areas.length,
+        largest: Math.max(...areas),
+        ambiguity: options.reduce((a, b) => a + b, 0) / options.length,
+    };
+}

package/dist/shikakuSolve.d.ts

@@ -1,5 +1,5 @@
 import type { ShikakuBoard, ShikakuRectangle, ShikakuSolve } from "./shikaku.types.ts";
-/** Exact cover over cells. A bounded search reports incompleteness instead of claiming uniqueness. */
+/** Exact cover over squares. A bounded search reports incompleteness instead of claiming uniqueness. */
 export declare function solveShikaku(board: ShikakuBoard, placed?: readonly ShikakuRectangle[], options?: {
     limit?: number;
     nodes?: number;

package/dist/shikakuSolve.js

@@ -1,54 +1,33 @@
 import { SHIKAKU_MOST_NODES } from "./shikaku.constants.js";
-import { checkShikaku, isShikakuBoard, shikakuCandidates, shikakuCells } from "./shikakuBoard.js";
-/** Exact cover over cells. A bounded search reports incompleteness instead of claiming uniqueness. */
+import { checkShikaku, isShikakuBoard } from "./shikakuBoard.js";
+import { shikakuModel } from "./shikakuLogic.js";
+import { decide, openSlots, solveCsp } from "./csp.js";
+/** Exact cover over squares. A bounded search reports incompleteness instead of claiming uniqueness. */
 export function solveShikaku(board, placed = [], options = {}) {
     if (!isShikakuBoard(board))
         throw new RangeError("Invalid Shikaku board");
     const limit = options.limit ?? 2, budget = options.nodes ?? SHIKAKU_MOST_NODES;
     if (!Number.isInteger(limit) || limit < 1 || !Number.isInteger(budget) || budget < 1)
         throw new RangeError("Invalid search bounds");
-    const maskOf = (r) => shikakuCells(board, r).reduce((m, c) => m | 1n << BigInt(c), 0n);
     if (checkShikaku(board, placed).errors.length)
         return { count: 0, solution: null, complete: true, nodes: 0 };
-    const all = (1n << BigInt(board.clues.length)) - 1n;
-    let occupied = 0n;
-    for (const r of placed)
-        occupied |= maskOf(r);
-    const candidates = board.clues.flatMap((n, c) => n ? shikakuCandidates(board, c).map(r => ({ r, mask: maskOf(r) })) : []);
-    const byCell = board.clues.map((_, c) => candidates.filter(r => (r.mask & 1n << BigInt(c)) !== 0n));
-    let count = 0, nodes = 0, complete = true, solution = null;
-    const visit = (mask, rectangles) => {
-        if (++nodes > budget) {
-            complete = false;
-            return;
-        }
-        if (mask === all) {
-            count += 1;
-            solution ?? (solution = rectangles.map(r => ({ ...r })));
-            return;
-        }
-        let choices = null;
-        for (let c = 0; c < board.clues.length; c += 1) {
-            if ((mask & 1n << BigInt(c)) !== 0n)
-                continue;
-            const available = byCell[c].filter(r => (mask & r.mask) === 0n);
-            if (!available.length)
-                return;
-            if (!choices || available.length < choices.length)
-                choices = available;
-            if (choices.length === 1)
-                break;
-        }
-        for (const next of choices ?? []) {
-            visit(mask | next.mask, [...rectangles, next.r]);
-            if (!complete)
-                return;
-            if (count >= limit) {
-                complete = false;
-                return;
-            }
-        }
-    };
-    visit(occupied, placed);
-    return { count, solution, complete, nodes };
+    const { csp, rectangles, clues } = shikakuModel(board);
+    const start = openSlots(csp);
+    for (const r of placed) {
+        const slot = rectangles.findIndex(c => c.x === r.x && c.y === r.y && c.width === r.width && c.height === r.height);
+        if (slot < 0)
+            return { count: 0, solution: null, complete: true, nodes: 0 };
+        decide(csp, start, clues.indexOf(clueOf(board, r)), slot);
+    }
+    const found = solveCsp(csp, start, limit, budget);
+    const solution = found.solution ? [...placed.map(r => ({ ...r })), ...rectangles.filter((_, slot) => found.solution[slot] === 1 && !placed.some(r => sameRectangle(r, rectangles[slot])))] : null;
+    return { count: found.count, solution, complete: !found.exhausted && !found.stopped, nodes: found.nodes };
 }
+const sameRectangle = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+const clueOf = (board, r) => {
+    for (let y = r.y; y < r.y + r.height; y += 1)
+        for (let x = r.x; x < r.x + r.width; x += 1)
+            if (board.clues[y * board.width + x])
+                return y * board.width + x;
+    return -1;
+};

package/dist/shikakuTemplate.d.ts

@@ -0,0 +1,3 @@
+import type { ShikakuLevel, ShikakuPuzzle } from "./shikaku.types.ts";
+/** The first generator, kept as the fallback that cannot fail on a board it can make: seeded cuts into rectangles, accepted when the answer is single. */
+export declare function templateShikaku(width?: number, height?: number, level?: ShikakuLevel, seed?: number): ShikakuPuzzle;

package/dist/shikakuTemplate.js

@@ -0,0 +1,43 @@
+import { SHIKAKU_LEVELS, SHIKAKU_MOST_ATTEMPTS } from "./shikaku.constants.js";
+import { isShikakuBoard, shikakuCells } from "./shikakuBoard.js";
+import { solveShikaku } from "./shikakuSolve.js";
+import { isKazuSeed, seededRandom } from "./random.js";
+/** The first generator, kept as the fallback that cannot fail on a board it can make: seeded cuts into rectangles, accepted when the answer is single. */
+export function templateShikaku(width = 7, height = width, level = "medium", seed = 1) {
+    if (![width, height].every(n => Number.isInteger(n) && n >= 2 && n <= 16))
+        throw new RangeError("Invalid Shikaku dimensions");
+    const empty = { width, height, clues: Array(width * height).fill(0) };
+    if (!isKazuSeed(seed) || !SHIKAKU_LEVELS.includes(level)
+        || !isShikakuBoard({ ...empty, clues: [width * height, ...empty.clues.slice(1)] }))
+        throw new RangeError("Invalid Shikaku settings");
+    const random = seededRandom(seed), maximum = { easy: 5, medium: 9, hard: 15, "extra-hard": 20 }[level];
+    for (let attempt = 0; attempt < SHIKAKU_MOST_ATTEMPTS; attempt += 1) {
+        const solution = [];
+        const split = (r) => {
+            if (r.width * r.height <= maximum && (r.width * r.height < 3 || random() < .6)) {
+                solution.push(r);
+                return;
+            }
+            const vertical = r.height === 1 || (r.width > 1 && random() < .5);
+            const cut = 1 + Math.floor(random() * ((vertical ? r.width : r.height) - 1));
+            if (vertical) {
+                split({ ...r, width: cut });
+                split({ ...r, x: r.x + cut, width: r.width - cut });
+            }
+            else {
+                split({ ...r, height: cut });
+                split({ ...r, y: r.y + cut, height: r.height - cut });
+            }
+        };
+        split({ x: 0, y: 0, width, height });
+        const clues = [...empty.clues];
+        for (const r of solution) {
+            const cells = shikakuCells(empty, r);
+            clues[cells[Math.floor(random() * cells.length)]] = cells.length;
+        }
+        const board = { width, height, clues }, counted = solveShikaku(board);
+        if (counted.complete && counted.count === 1)
+            return { ...board, seed, level, solution: counted.solution };
+    }
+    throw new Error("No unique Shikaku found within the generation budget; try another seed");
+}

package/dist/slitherlink-entry.d.ts

@@ -4,6 +4,7 @@ export * from "./slitherlink.constants.ts";
 export * from "./slitherlinkBoard.ts";
 export * from "./slitherlinkSolve.ts";
 export * from "./slitherlinkGenerate.ts";
+export * from "./slitherlinkRate.ts";
 export * from "./slitherlinkGame.ts";
 export { drawSlitherlink } from "./slitherlinkDraw.ts";
 export type { SlitherlinkDrawOptions } from "./slitherlinkPlay.types.ts";

package/dist/slitherlink-entry.js

@@ -4,6 +4,7 @@ export * from "./slitherlink.constants.js";
 export * from "./slitherlinkBoard.js";
 export * from "./slitherlinkSolve.js";
 export * from "./slitherlinkGenerate.js";
+export * from "./slitherlinkRate.js";
 export * from "./slitherlinkGame.js";
 export { drawSlitherlink } from "./slitherlinkDraw.js";
 export { mountSlitherlink } from "./slitherlinkMount.js";

package/dist/slitherlink.constants.d.ts

@@ -1,2 +1,7 @@
 export declare const SLITHERLINK_MOST_SIDE = 10;
 export declare const SLITHERLINK_MOST_NODES = 300000;
+/** How hard a puzzle is made, by what a person must do to solve it; see `rateSlitherlink`. */
+export declare const SLITHERLINK_LEVELS: readonly ["easy", "medium", "hard", "extra-hard"];
+/** The sides on offer for a square board; any side from 2 to `SLITHERLINK_MOST_SIDE` can be made. */
+export declare const SLITHERLINK_SIZES: readonly [5, 7, 10];
+export declare const SLITHERLINK_MOST_ATTEMPTS = 40;

package/dist/slitherlink.constants.js

@@ -1,2 +1,7 @@
 export const SLITHERLINK_MOST_SIDE = 10;
 export const SLITHERLINK_MOST_NODES = 300000;
+/** How hard a puzzle is made, by what a person must do to solve it; see `rateSlitherlink`. */
+export const SLITHERLINK_LEVELS = ["easy", "medium", "hard", "extra-hard"];
+/** The sides on offer for a square board; any side from 2 to `SLITHERLINK_MOST_SIDE` can be made. */
+export const SLITHERLINK_SIZES = [5, 7, 10];
+export const SLITHERLINK_MOST_ATTEMPTS = 40;

package/dist/slitherlink.types.d.ts

@@ -3,10 +3,28 @@ export type SlitherlinkBoard = {
     height: number;
     clues: readonly (number | null)[];
 };
+export type SlitherlinkLevel = "easy" | "medium" | "hard" | "extra-hard";
 export type SlitherlinkPuzzle = SlitherlinkBoard & {
     seed: number;
+    level: SlitherlinkLevel;
     solution: readonly number[];
 };
+/**
+ * How hard a board is, measured by solving it. `depth` 0 means the plain rules solve it, 1 that somebody has to
+ * suppose an edge drawn or crossed and watch it break, 2 that more than that is needed; `probes` is how many
+ * suppositions depth 1 needed. The rest describes the board.
+ */
+export type SlitherlinkRating = {
+    depth: 0 | 1 | 2;
+    probes: number;
+    clues: number;
+    /** Numbered squares as a share of all squares. */
+    clueShare: number;
+    /** Squares numbered 0 as a share of the numbered ones. */
+    zeroShare: number;
+    /** Edges in the loop. */
+    loop: number;
+};
 export type SlitherlinkCheck = {
     ok: boolean;
     errors: readonly number[];

package/dist/slitherlinkGenerate.d.ts

@@ -1,3 +1,10 @@
-import type { SlitherlinkPuzzle } from "./slitherlink.types.ts";
-/** Makes a proved puzzle from a seeded rectangle or L-shaped tile-region loop. */
-export declare function generateSlitherlink(width?: number, height?: number, seed?: number): SlitherlinkPuzzle;
+import type { SlitherlinkLevel, SlitherlinkPuzzle } from "./slitherlink.types.ts";
+/**
+ * Makes a seeded puzzle and proves it has one answer. A random winding loop is grown cell by cell, every square is
+ * numbered with how many of its edges the loop uses, and then numbers are taken away for as long as the puzzle can
+ * still be solved the way the level asks: easy and medium by the rules alone (easy keeps most numbers), hard by
+ * supposing one edge at a time, extra-hard the most-supposing of several such boards. Numbers that say 0 are
+ * taken away first, because they say least. If no board of the level is found within the attempts the next level
+ * down is tried, and the first generator, which cannot fail, is the last.
+ */
+export declare function generateSlitherlink(width?: number, height?: number, seed?: number, level?: SlitherlinkLevel): SlitherlinkPuzzle;