@johnmorrisdotca/kazu 1.0.0

package/dist/generate.js

@@ -0,0 +1,35 @@
+import { isKazuKind, isKazuLevel, isKazuSize } from "./kinds.js";
+import { generateJigsaw } from "./jigsaw.js";
+import { generateMoreOrLess } from "./moreOrLess.js";
+import { generateDiagonal, generateNumberPlace } from "./numberPlace.js";
+import { isKazuSeed } from "./random.js";
+import { generateSumCages } from "./sumCages.js";
+import { generateTowers } from "./towers.js";
+const GENERATORS = {
+    "number-place": generateNumberPlace,
+    jigsaw: generateJigsaw,
+    diagonal: generateDiagonal,
+    "sum-cages": generateSumCages,
+    "more-or-less": generateMoreOrLess,
+    towers: generateTowers,
+};
+/**
+ * A puzzle of any of the six, from a seed: the one door. The same kind, size, level and seed make the
+ * same puzzle in every browser and every Node, for ever, which is what lets a solve be kept as those
+ * four and a race be handed one number. Every puzzle has exactly one answer, and an easy one yields
+ * to singles alone.
+ *
+ * Throws a RangeError for a kind, size, level or seed it does not make, rather than a puzzle made
+ * from something else.
+ */
+export function generateKazu(kind, size, level, seed) {
+    if (!isKazuKind(kind))
+        throw new RangeError(`Kazu has no puzzle called ${String(kind)}.`);
+    if (!isKazuSize(kind, size))
+        throw new RangeError(`Kazu makes no ${kind} at ${size}×${size}.`);
+    if (!isKazuLevel(level))
+        throw new RangeError(`Kazu has no level called ${String(level)}.`);
+    if (!isKazuSeed(seed))
+        throw new RangeError(`${String(seed)} is not a seed: a whole number from 1 to 2147483647.`);
+    return GENERATORS[kind](size, level, seed);
+}

package/dist/geometry.d.ts

@@ -0,0 +1,33 @@
+import type { KazuKind } from "./kinds.ts";
+/**
+ * WHERE EVERYTHING IS IN A DRAWING, so a page of your own can play it: the drawing is a square of
+ * `side` units, every cell `cell` units across, and a Towers square sits inside a ring one cell deep
+ * that holds its clues. Pure arithmetic, no page needed.
+ */
+export type KazuGeometry = {
+    /** The side of the drawing, in its own units (the viewBox is `0 0 side side`). */
+    side: number;
+    /** The side of one cell. */
+    cell: number;
+    /** Where the grid's top left corner is. */
+    origin: number;
+    /** How many cells deep the ring round the grid is: 1 for Towers, which keeps its clues there, 0 for the rest. */
+    ring: number;
+    size: number;
+    /** The top left corner of a cell. */
+    corner: (index: number) => {
+        x: number;
+        y: number;
+    };
+    /** The middle of a cell. */
+    centre: (index: number) => {
+        x: number;
+        y: number;
+    };
+    /** The cell a point is over, or -1 for a point outside the grid. */
+    cellAt: (x: number, y: number) => number;
+};
+/** The units of a cell, and the margin round the drawing. */
+export declare const KAZU_CELL = 100;
+/** Where everything is in the drawing of a puzzle of this kind and side. */
+export declare function kazuGeometry(kind: KazuKind, size: number): KazuGeometry;

package/dist/geometry.js

@@ -0,0 +1,27 @@
+/** The units of a cell, and the margin round the drawing. */
+export const KAZU_CELL = 100;
+const MARGIN = 10;
+/** Where everything is in the drawing of a puzzle of this kind and side. */
+export function kazuGeometry(kind, size) {
+    const ring = kind === "towers" ? 1 : 0;
+    const origin = MARGIN + ring * KAZU_CELL;
+    const side = 2 * MARGIN + (size + 2 * ring) * KAZU_CELL;
+    const corner = (index) => ({ x: origin + (index % size) * KAZU_CELL, y: origin + Math.floor(index / size) * KAZU_CELL });
+    return {
+        side,
+        cell: KAZU_CELL,
+        origin,
+        ring,
+        size,
+        corner,
+        centre: (index) => {
+            const at = corner(index);
+            return { x: at.x + KAZU_CELL / 2, y: at.y + KAZU_CELL / 2 };
+        },
+        cellAt: (x, y) => {
+            const col = Math.floor((x - origin) / KAZU_CELL);
+            const row = Math.floor((y - origin) / KAZU_CELL);
+            return col < 0 || row < 0 || col >= size || row >= size ? -1 : row * size + col;
+        },
+    };
+}

package/dist/givens.d.ts

@@ -0,0 +1,30 @@
+import type { KazuKind } from "./kinds.ts";
+import { type Layout } from "./layout.ts";
+import { type Mark } from "./moreOrLessCode.ts";
+import { type Cage } from "./sumCages.ts";
+import { type TowerClues } from "./towersCode.ts";
+/**
+ * WHAT A PUZZLE WAS PRINTED WITH, read from its givens code: the printed cells, and for a Jigsaw its
+ * regions, for Sum Cages its cages, for More or Less its marks, for Towers its clues. Each kind
+ * writes them after the cells. The drawing, the play and the hint all read a puzzle through this.
+ */
+export type KazuGivens = {
+    kind: KazuKind;
+    size: number;
+    /** The printed numbers, row-major; 0 where nothing is printed. */
+    cells: number[];
+    /** The region each cell is drawn in (a box, or a Jigsaw's own region), which the heavy rules go round; null for More or Less and Towers. */
+    regions: number[] | null;
+    /** Whether the two long diagonals are groups too (Diagonal). */
+    diagonals: boolean;
+    /** Sum Cages: the cages and their sums. */
+    cages: Cage[] | null;
+    /** More or Less: which of two neighbouring cells is bigger. */
+    marks: Mark[];
+    /** Towers: the clues round the edge. */
+    clues: TowerClues | null;
+};
+/** The givens of a puzzle, or null for a code that is not one of that kind and side. Null rather than a puzzle with holes. */
+export declare function readGivens(kind: KazuKind, size: number, code: string): KazuGivens | null;
+/** The groups that must each hold every number once, for the four kinds made of groups; null for More or Less and Towers, which only have rows and columns. */
+export declare function layoutOfGivens(givens: KazuGivens): Layout | null;

package/dist/givens.js

@@ -0,0 +1,43 @@
+import { decodeCells } from "./cells.js";
+import { decodeJigsaw } from "./jigsaw.js";
+import { boxedLayout, cagedLayout, KAZU_BOXES, regionLayout } from "./layout.js";
+import { decodeMoreOrLess } from "./moreOrLessCode.js";
+import { decodeKiller } from "./sumCages.js";
+import { decodeTowers } from "./towersCode.js";
+/** The givens of a puzzle, or null for a code that is not one of that kind and side. Null rather than a puzzle with holes. */
+export function readGivens(kind, size, code) {
+    const plain = { kind, size, regions: null, diagonals: false, cages: null, marks: [], clues: null };
+    const boxed = KAZU_BOXES[size] === undefined ? null : boxedLayout(size).region;
+    if (kind === "number-place" || kind === "diagonal") {
+        const cells = decodeCells(code, size);
+        return cells === null || boxed === null ? null : { ...plain, cells, regions: boxed, diagonals: kind === "diagonal" };
+    }
+    if (kind === "jigsaw") {
+        const read = decodeJigsaw(code, size);
+        return read === null ? null : { ...plain, cells: read.cells, regions: read.regions };
+    }
+    if (kind === "sum-cages") {
+        const read = decodeKiller(code, size);
+        return read === null || boxed === null ? null : { ...plain, cells: read.cells, regions: boxed, cages: read.cages };
+    }
+    if (kind === "more-or-less") {
+        const read = decodeMoreOrLess(code, size);
+        return read === null ? null : { ...plain, cells: read.cells, marks: read.marks };
+    }
+    if (kind === "towers") {
+        const read = decodeTowers(code, size);
+        return read === null ? null : { ...plain, cells: read.cells, clues: read.clues };
+    }
+    return null;
+}
+/** The groups that must each hold every number once, for the four kinds made of groups; null for More or Less and Towers, which only have rows and columns. */
+export function layoutOfGivens(givens) {
+    const { kind, size } = givens;
+    if (kind === "number-place" || kind === "diagonal")
+        return boxedLayout(size, kind === "diagonal");
+    if (kind === "jigsaw")
+        return givens.regions === null ? null : regionLayout(size, givens.regions);
+    if (kind === "sum-cages")
+        return givens.cages === null ? null : cagedLayout(size, givens.cages);
+    return null;
+}

package/dist/groupSolve.d.ts

@@ -0,0 +1,68 @@
+import type { Layout } from "./layout.ts";
+/**
+ * The solver for every puzzle made of groups: counting, singles, and how deep a guess goes.
+ *
+ * Three questions, one small engine, for Sudoku, Diagonal, Jigsaw and Sum Cages alike.
+ *
+ *  - `countSolutions` says whether a puzzle has exactly one answer, which is the whole difference
+ *    between a puzzle and a guessing game. It stops at two, so "many" costs no more than "two".
+ *  - `applySingles` fills what pure reasoning fills: a cell with one candidate, or a value with one
+ *    place left in a group.
+ *  - `guessDepth` is the level: 0 when singles finish it, 1 when one guess and singles do, more when
+ *    more. A level is what the solver needed, not how many givens were printed: twenty-four givens
+ *    can be an easy grid.
+ *
+ * It reads a `Layout`, the groups that must each hold every number once, so classic Sudoku, Diagonal
+ * and Jigsaw are one solver with three lists of groups (see `layout.ts`).
+ */
+/** A grid as cells, row-major; 0 is empty, 1..size is a value. */
+export type Grid = number[];
+/** The bitmask of values each group already holds. */
+export declare function used(grid: Grid, layout: Layout): number[];
+export declare function candidatesAt(layout: Layout, index: number, taken: number[], work: Grid): number;
+export declare function bitCount(mask: number): number;
+export declare function lowestBit(mask: number): number;
+/**
+ * How many solutions the grid has, up to `limit`. Most-constrained cell
+ * first, so a grid with one answer is confirmed in a few hundred steps.
+ */
+export declare function countSolutions(grid: Grid, layout: Layout, limit?: number): number;
+/**
+ * The same count, giving up after `budget` steps — null then, never a number,
+ * because "I stopped looking" is not "there are none". A Killer's generator
+ * asks this of layouts that are sometimes slow to settle, and draws another
+ * rather than keeping a browser waiting.
+ */
+export declare function countSolutionsWithin(grid: Grid, layout: Layout, limit: number, budget: number, first?: (answer: Grid) => void): number | null;
+/**
+ * THE ANSWER, WORKED OUT FROM THE GIVENS: a finished puzzle kept before its
+ * grid was, drawn solved rather than as dealt. Every puzzle made here has
+ * exactly one answer, so the search stops at two and hands back the first
+ * only when there was no second. Null when there is none, or more than one,
+ * or the search ran past `budget`: a grid this cannot vouch for is never drawn
+ * as though it were the one that was solved.
+ */
+export declare function solutionOf(grid: Grid, layout: Layout, budget?: number): Grid | null;
+export type SinglesResult = {
+    grid: Grid;
+    solved: boolean;
+    contradiction: boolean;
+};
+/**
+ * Fill every cell that reasoning fills, until nothing more can be: naked
+ * singles (one candidate in a cell) and hidden singles (one cell for a value
+ * in a group). Returns a new grid; the input is left as it was.
+ */
+export declare function applySingles(grid: Grid, layout: Layout): SinglesResult;
+/**
+ * How many guesses, each followed by every single it lets loose, a solver
+ * needs to finish the grid: 0 when singles do it all, `Infinity` when the grid
+ * has no answer. Meant for a grid already known to have exactly one.
+ */
+export declare function guessDepth(grid: Grid, layout: Layout): number;
+/**
+ * A full grid for this layout, drawn at random, or null when the search runs
+ * past `budget` steps — which for a jigsaw means these regions are a poor
+ * layout to fill, and the caller draws others.
+ */
+export declare function fillLayout(layout: Layout, random: () => number, budget?: number): Grid | null;

package/dist/groupSolve.js

@@ -0,0 +1,284 @@
+const ALL = (size) => (1 << (size + 1)) - 2; // bits 1..size set
+/** The bitmask of values each group already holds. */
+export function used(grid, layout) {
+    const taken = new Array(layout.groups.length).fill(0);
+    grid.forEach((value, index) => {
+        if (value === 0)
+            return;
+        for (const group of layout.groupsOf[index])
+            taken[group] |= 1 << value;
+    });
+    return taken;
+}
+export function candidatesAt(layout, index, taken, work) {
+    let blocked = 0;
+    for (const group of layout.groupsOf[index])
+        blocked |= taken[group];
+    const open = ALL(layout.size) & ~blocked;
+    return layout.cages === undefined ? open : open & cageAllows(layout, index, work, open);
+}
+/**
+ * The values a cell may take and still leave its cage able to reach its sum:
+ * whatever is left of the sum after this cell, made of the cage's other empty
+ * cells with numbers not yet in it. Checked by bounds — the smallest and
+ * largest those cells could add to — which is exact for the cell that fills
+ * the cage and a sound pruning before it.
+ */
+function cageAllows(layout, index, work, open) {
+    const cage = layout.cages[layout.cageOf[index]];
+    let placed = 0;
+    let inCage = 0;
+    let empties = 0;
+    for (const cell of cage.cells) {
+        const value = work[cell];
+        if (value === 0)
+            empties += 1;
+        else {
+            placed += value;
+            inCage |= 1 << value;
+        }
+    }
+    const others = empties - 1;
+    let allowed = 0;
+    for (let left = open; left !== 0; left &= left - 1) {
+        const value = lowestBit(left);
+        const rest = cage.sum - placed - value;
+        if (others === 0 ? rest === 0 : reachable(rest, others, ALL(layout.size) & ~inCage & ~(1 << value), layout.size))
+            allowed |= 1 << value;
+    }
+    return allowed;
+}
+/** Whether `count` different values from `from` can add to `sum`, by the smallest and largest they could. */
+function reachable(sum, count, from, size) {
+    let low = 0;
+    let taken = 0;
+    for (let value = 1; value <= size && taken < count; value += 1) {
+        if ((from & (1 << value)) !== 0) {
+            low += value;
+            taken += 1;
+        }
+    }
+    if (taken < count)
+        return false;
+    let high = 0;
+    taken = 0;
+    for (let value = size; value >= 1 && taken < count; value -= 1) {
+        if ((from & (1 << value)) !== 0) {
+            high += value;
+            taken += 1;
+        }
+    }
+    return low <= sum && sum <= high;
+}
+function place(layout, taken, index, value) {
+    for (const group of layout.groupsOf[index])
+        taken[group] |= 1 << value;
+}
+function lift(layout, taken, index, value) {
+    for (const group of layout.groupsOf[index])
+        taken[group] &= ~(1 << value);
+}
+export function bitCount(mask) {
+    let count = 0;
+    for (let m = mask; m !== 0; m &= m - 1)
+        count += 1;
+    return count;
+}
+export function lowestBit(mask) {
+    return 31 - Math.clz32(mask & -mask);
+}
+/** The empty cell with fewest candidates, or -1 when none is empty. A cell with none gives mask 0. */
+function mostConstrained(work, layout, taken) {
+    let best = -1;
+    let bestMask = 0;
+    let bestCount = layout.size + 1;
+    for (let index = 0; index < work.length; index += 1) {
+        if (work[index] !== 0)
+            continue;
+        const mask = candidatesAt(layout, index, taken, work);
+        const count = bitCount(mask);
+        if (count < bestCount) {
+            best = index;
+            bestMask = mask;
+            bestCount = count;
+            if (count <= 1)
+                break;
+        }
+    }
+    return { index: best, mask: bestMask };
+}
+/**
+ * How many solutions the grid has, up to `limit`. Most-constrained cell
+ * first, so a grid with one answer is confirmed in a few hundred steps.
+ */
+export function countSolutions(grid, layout, limit = 2) {
+    return countSolutionsWithin(grid, layout, limit, Infinity);
+}
+/**
+ * The same count, giving up after `budget` steps — null then, never a number,
+ * because "I stopped looking" is not "there are none". A Killer's generator
+ * asks this of layouts that are sometimes slow to settle, and draws another
+ * rather than keeping a browser waiting.
+ */
+export function countSolutionsWithin(grid, layout, limit, budget, first) {
+    const work = [...grid];
+    const taken = used(work, layout);
+    let found = 0;
+    let steps = 0;
+    const step = () => {
+        if (found >= limit || steps > budget)
+            return;
+        steps += 1;
+        const { index, mask } = mostConstrained(work, layout, taken);
+        if (index === -1) {
+            if (found === 0)
+                first?.([...work]);
+            found += 1;
+            return;
+        }
+        for (let left = mask; left !== 0; left &= left - 1) {
+            const value = lowestBit(left);
+            work[index] = value;
+            place(layout, taken, index, value);
+            step();
+            lift(layout, taken, index, value);
+            work[index] = 0;
+            if (found >= limit || steps > budget)
+                return;
+        }
+    };
+    step();
+    return steps > budget && found < limit ? null : found;
+}
+/**
+ * THE ANSWER, WORKED OUT FROM THE GIVENS: a finished puzzle kept before its
+ * grid was, drawn solved rather than as dealt. Every puzzle made here has
+ * exactly one answer, so the search stops at two and hands back the first
+ * only when there was no second. Null when there is none, or more than one,
+ * or the search ran past `budget`: a grid this cannot vouch for is never drawn
+ * as though it were the one that was solved.
+ */
+export function solutionOf(grid, layout, budget = 2000000) {
+    let answer = null;
+    const found = countSolutionsWithin(grid, layout, 2, budget, (first) => (answer = first));
+    return found === 1 ? answer : null;
+}
+/**
+ * Fill every cell that reasoning fills, until nothing more can be: naked
+ * singles (one candidate in a cell) and hidden singles (one cell for a value
+ * in a group). Returns a new grid; the input is left as it was.
+ */
+export function applySingles(grid, layout) {
+    const work = [...grid];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        const taken = used(work, layout);
+        // Naked singles.
+        for (let index = 0; index < work.length; index += 1) {
+            if (work[index] !== 0)
+                continue;
+            const mask = candidatesAt(layout, index, taken, work);
+            if (mask === 0)
+                return { grid: work, solved: false, contradiction: true };
+            if (bitCount(mask) === 1) {
+                const value = lowestBit(mask);
+                work[index] = value;
+                place(layout, taken, index, value);
+                changed = true;
+            }
+        }
+        // Hidden singles, group by group. Only a group that holds every number (a row, a column, a box, a
+        // region, a diagonal) has one: a cage holds some of them, so a number with one place left in a cage
+        // is no reason to put it there.
+        for (let group = 0; group < layout.groups.length; group += 1) {
+            if (layout.groups[group].length !== layout.size)
+                continue;
+            for (let value = 1; value <= layout.size; value += 1) {
+                const bit = 1 << value;
+                if ((taken[group] & bit) !== 0)
+                    continue;
+                let at = -1;
+                let places = 0;
+                for (const index of layout.groups[group]) {
+                    if (work[index] !== 0)
+                        continue;
+                    if ((candidatesAt(layout, index, taken, work) & bit) !== 0) {
+                        at = index;
+                        places += 1;
+                        if (places > 1)
+                            break;
+                    }
+                }
+                if (places === 0)
+                    return { grid: work, solved: false, contradiction: true };
+                if (places === 1) {
+                    work[at] = value;
+                    place(layout, taken, at, value);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return { grid: work, solved: work.every((value) => value !== 0), contradiction: false };
+}
+/**
+ * How many guesses, each followed by every single it lets loose, a solver
+ * needs to finish the grid: 0 when singles do it all, `Infinity` when the grid
+ * has no answer. Meant for a grid already known to have exactly one.
+ */
+export function guessDepth(grid, layout) {
+    const singles = applySingles(grid, layout);
+    if (singles.contradiction)
+        return Infinity;
+    if (singles.solved)
+        return 0;
+    const work = singles.grid;
+    const { index, mask } = mostConstrained(work, layout, used(work, layout));
+    let deepest = Infinity;
+    for (let left = mask; left !== 0; left &= left - 1) {
+        const next = [...work];
+        next[index] = lowestBit(left);
+        const depth = guessDepth(next, layout);
+        if (depth < deepest)
+            deepest = depth;
+    }
+    return deepest === Infinity ? Infinity : deepest + 1;
+}
+/**
+ * A full grid for this layout, drawn at random, or null when the search runs
+ * past `budget` steps — which for a jigsaw means these regions are a poor
+ * layout to fill, and the caller draws others.
+ */
+export function fillLayout(layout, random, budget = 200000) {
+    const work = new Array(layout.size * layout.size).fill(0);
+    const taken = used(work, layout);
+    let steps = 0;
+    const step = () => {
+        steps += 1;
+        if (steps > budget)
+            return false;
+        const { index, mask } = mostConstrained(work, layout, taken);
+        if (index === -1)
+            return true;
+        const values = [];
+        for (let left = mask; left !== 0; left &= left - 1)
+            values.push(lowestBit(left));
+        for (let i = values.length - 1; i > 0; i -= 1) {
+            const j = Math.floor(random() * (i + 1));
+            [values[i], values[j]] = [values[j], values[i]];
+        }
+        for (const value of values) {
+            work[index] = value;
+            place(layout, taken, index, value);
+            if (step())
+                return true;
+            lift(layout, taken, index, value);
+            work[index] = 0;
+            if (steps > budget)
+                return false;
+        }
+        return false;
+    };
+    return step() ? work : null;
+}

package/dist/hint.d.ts

@@ -0,0 +1,39 @@
+import type { KazuKind } from "./kinds.ts";
+/**
+ * A HINT: the next cell a person could fill in by looking, and why.
+ *
+ * It reasons from what is right on the grid so far (the printed numbers and every entry that agrees
+ * with the answer; a wrong entry is treated as empty, so a hint never builds on a mistake) the way a
+ * person does, one step at a time:
+ *
+ *  1. a cell that only one number fits (`only-number`): every other number is already in its row,
+ *     column, box, region, diagonal or cage, or a cage's sum, a Futoshiki mark or a Skyscrapers clue
+ *     rules it out (`by` says which, when one did);
+ *  2. a number that fits only one cell of a group (`only-place`): the row, column, box, region,
+ *     diagonal or cage it must go in, and where.
+ *
+ * When neither is left (a hard puzzle asks for a guess here) it says so (`answer`): the tightest
+ * cell, whose number is the answer's, with no reason a single step gives. Null when every cell is
+ * already right.
+ */
+export type KazuHint = {
+    cell: number;
+    value: number;
+    why: "only-number" | "only-place" | "answer";
+    /** `only-place`: the group the number has one place in. */
+    group?: {
+        type: "row" | "column" | "box" | "region" | "diagonal";
+        index: number;
+    };
+    /** `only-number`: what ruled the others out beyond the groups, if anything did. */
+    by?: "cage" | "marks" | "clues";
+    /** Whether the cell holds a wrong number now, which this one replaces. */
+    replaces: boolean;
+};
+/**
+ * The next cell a person could fill in, and why (see `KazuHint`). `entries` is what the player has
+ * written, row-major (0 for empty; printed cells are ignored). `answer` is the puzzle's solution as a
+ * cells code; left out, it is worked out from the givens. Null when every cell is right, or when
+ * the givens are not a puzzle with exactly one answer: there is nothing true to say.
+ */
+export declare function hintKazu(kind: KazuKind, size: number, givens: string, entries: readonly number[], answer?: string): KazuHint | null;