@johnmorrisdotca/kazu 1.0.0

package/dist/cells.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A GRID OF NUMBERS AS A STRING: for an address, a POST body, and a kept run.
+ *
+ * Row-major, one character per cell: a digit for a value, `.` for an empty cell. Past nine the
+ * values are letters, A for 10 up to G for 16, as a 16×16 Sudoku is printed (`symbolOf`), so one
+ * character is still one cell. Upper case only in a code, so one grid has one spelling. These are
+ * the spellings itsutsu.com has always stored, and they decode here unchanged.
+ */
+export declare const EMPTY_CELL = ".";
+/** How a value is written, in a code and on a cell: 1–9, then A–G. */
+export declare function symbolOf(value: number): string;
+/** The value a symbol names, or 0 for one that is not 1–9 or A–G (either case). */
+export declare function valueOfSymbol(symbol: string): number;
+/** `[0, 3, 0, 1]` → `".3.1"`. */
+export declare function encodeCells(cells: readonly number[]): string;
+/**
+ * `".3.1"` at a side of 2 → `[0, 3, 0, 1]`, or null for a string that is not a grid of that size:
+ * the wrong length, a value past the side, a stray character. Null rather than a grid with holes,
+ * because a grid with holes is a grid.
+ */
+export declare function decodeCells(code: string, size: number): number[] | null;
+/** A short fingerprint of a puzzle's givens (FNV-1a, eight hex characters): the same puzzle, however it was kept, has the same one. Not a credential. */
+export declare function kazuHash(givens: string): string;
+/**
+ * The number a tap on the chosen cell puts in it: one more, and after the largest the cell empties,
+ * and then it starts again at 1. A tap on a cell that is not chosen still only chooses it.
+ */
+export declare function stepEntry(value: number, size: number): number;

package/dist/cells.js

@@ -0,0 +1,65 @@
+/**
+ * A GRID OF NUMBERS AS A STRING: for an address, a POST body, and a kept run.
+ *
+ * Row-major, one character per cell: a digit for a value, `.` for an empty cell. Past nine the
+ * values are letters, A for 10 up to G for 16, as a 16×16 Sudoku is printed (`symbolOf`), so one
+ * character is still one cell. Upper case only in a code, so one grid has one spelling. These are
+ * the spellings itsutsu.com has always stored, and they decode here unchanged.
+ */
+export const EMPTY_CELL = ".";
+/** The letters after 9, in order: A is 10, G is 16. */
+const PAST_NINE = "ABCDEFG";
+/** How a value is written, in a code and on a cell: 1–9, then A–G. */
+export function symbolOf(value) {
+    return value <= 9 ? String(value) : PAST_NINE[value - 10];
+}
+/** The value a symbol names, or 0 for one that is not 1–9 or A–G (either case). */
+export function valueOfSymbol(symbol) {
+    if (symbol.length !== 1)
+        return 0;
+    if (symbol >= "1" && symbol <= "9")
+        return Number(symbol);
+    const at = PAST_NINE.indexOf(symbol.toUpperCase());
+    return at === -1 ? 0 : at + 10;
+}
+/** `[0, 3, 0, 1]` → `".3.1"`. */
+export function encodeCells(cells) {
+    return cells.map((value) => (value === 0 ? EMPTY_CELL : symbolOf(value))).join("");
+}
+/**
+ * `".3.1"` at a side of 2 → `[0, 3, 0, 1]`, or null for a string that is not a grid of that size:
+ * the wrong length, a value past the side, a stray character. Null rather than a grid with holes,
+ * because a grid with holes is a grid.
+ */
+export function decodeCells(code, size) {
+    if (typeof code !== "string" || code.length !== size * size)
+        return null;
+    const cells = [];
+    for (const character of code) {
+        if (character === EMPTY_CELL) {
+            cells.push(0);
+            continue;
+        }
+        const value = character === character.toUpperCase() ? valueOfSymbol(character) : 0;
+        if (value < 1 || value > size)
+            return null;
+        cells.push(value);
+    }
+    return cells;
+}
+/** A short fingerprint of a puzzle's givens (FNV-1a, eight hex characters): the same puzzle, however it was kept, has the same one. Not a credential. */
+export function kazuHash(givens) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < givens.length; i += 1) {
+        hash ^= givens.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * The number a tap on the chosen cell puts in it: one more, and after the largest the cell empties,
+ * and then it starts again at 1. A tap on a cell that is not chosen still only chooses it.
+ */
+export function stepEntry(value, size) {
+    return value >= size ? 0 : value + 1;
+}

package/dist/check.d.ts

@@ -0,0 +1,15 @@
+import { type KazuCheck, type KazuKind } from "./kinds.ts";
+/**
+ * Whether an answer solves a puzzle: O(cells), no search, nothing remembered between calls. A browser
+ * runs it to say "done"; a server runs it before it believes a solve, so a grid that is right is
+ * accepted and a grid that was merely posted is not. It refuses rather than repairs: a grid of the
+ * wrong size, a value out of range or a given moved is a "no" with its reason, never a best guess at
+ * what was meant.
+ *
+ * The rules of each puzzle are restated here rather than shared with the solver on purpose: the
+ * solver is what MADE the puzzle, and a check that reads the solver's mind proves only that the
+ * solver agrees with itself.
+ */
+export declare function checkKazu(kind: KazuKind, size: number, givens: string, answer: string): KazuCheck;
+/** Whether a puzzle's givens are a well-formed puzzle of that kind and side at all (a Jigsaw's regions sound, every code readable). */
+export declare function isKazuGivens(kind: KazuKind, size: number, givens: string): boolean;

package/dist/check.js

@@ -0,0 +1,189 @@
+import { decodeCells } from "./cells.js";
+import { readGivens } from "./givens.js";
+import { decodeJigsaw } from "./jigsaw.js";
+import { isKazuSize } from "./kinds.js";
+import { boxedLayout, regionLayout, regionsAreSound } from "./layout.js";
+import { decodeMoreOrLess } from "./moreOrLessCode.js";
+import { decodeKiller } from "./sumCages.js";
+import { decodeTowers, lineFrom, TOWER_SIDES } from "./towersCode.js";
+/**
+ * Whether an answer solves a puzzle: O(cells), no search, nothing remembered between calls. A browser
+ * runs it to say "done"; a server runs it before it believes a solve, so a grid that is right is
+ * accepted and a grid that was merely posted is not. It refuses rather than repairs: a grid of the
+ * wrong size, a value out of range or a given moved is a "no" with its reason, never a best guess at
+ * what was meant.
+ *
+ * The rules of each puzzle are restated here rather than shared with the solver on purpose: the
+ * solver is what MADE the puzzle, and a check that reads the solver's mind proves only that the
+ * solver agrees with itself.
+ */
+export function checkKazu(kind, size, givens, answer) {
+    if (!isKazuSize(kind, size))
+        return { ok: false, reason: `no ${kind} at ${size}` };
+    switch (kind) {
+        case "number-place":
+            return checkOnLayout(boxedLayout(size), decodeCells(givens, size), answer);
+        case "diagonal":
+            return checkOnLayout(boxedLayout(size, true), decodeCells(givens, size), answer);
+        case "jigsaw":
+            return checkJigsaw(size, givens, answer);
+        case "sum-cages":
+            return checkSumCages(size, givens, answer);
+        case "more-or-less":
+            return checkMoreOrLess(size, givens, answer);
+        case "towers":
+            return checkTowers(size, givens, answer);
+        default:
+            return { ok: false, reason: `no check for ${String(kind)}` };
+    }
+}
+/**
+ * A Jigsaw is checked against the regions it was handed, in its givens. They must be sound (`size`
+ * joined regions of `size` cells) or the grid is refused before it is read: regions of one cell each
+ * would make any grid whose rows and columns are right look like an answer.
+ */
+function checkJigsaw(size, givens, answer) {
+    const asked = decodeJigsaw(givens, size);
+    if (asked === null)
+        return { ok: false, reason: "the givens are not a grid with regions" };
+    if (!regionsAreSound(size, asked.regions))
+        return { ok: false, reason: "the regions do not divide the grid" };
+    return checkOnLayout(regionLayout(size, asked.regions), asked.cells, answer);
+}
+/**
+ * Sum Cages: a Sudoku grid, and every cage it was handed holds no number twice and adds to its sum.
+ * The cages come from the givens, as a Jigsaw's regions do; each cell is in exactly one, which the
+ * code's shape already guarantees.
+ */
+function checkSumCages(size, givens, answer) {
+    const asked = decodeKiller(givens, size);
+    if (asked === null)
+        return { ok: false, reason: "the givens are not a grid with cages" };
+    const plain = checkOnLayout(boxedLayout(size), asked.cells, answer);
+    if (!plain.ok)
+        return plain;
+    const filled = decodeCells(answer, size);
+    for (const [at, cage] of asked.cages.entries()) {
+        const values = cage.cells.map((index) => filled[index]);
+        if (new Set(values).size !== values.length)
+            return { ok: false, reason: `cage ${at + 1} repeats a number` };
+        if (values.reduce((total, value) => total + value, 0) !== cage.sum)
+            return { ok: false, reason: `cage ${at + 1} does not add to ${cage.sum}` };
+    }
+    return { ok: true };
+}
+/** Every group of the layout holds every number once, and no given was changed. One pass over the cells. */
+function checkOnLayout(layout, asked, answer) {
+    const { size } = layout;
+    const filled = decodeCells(answer, size);
+    if (asked === null)
+        return { ok: false, reason: "the givens are not a grid" };
+    if (filled === null)
+        return { ok: false, reason: "the answer is not a grid" };
+    if (filled.some((value) => value === 0))
+        return { ok: false, reason: "the answer has empty cells" };
+    for (let index = 0; index < asked.length; index += 1) {
+        if (asked[index] !== 0 && asked[index] !== filled[index])
+            return { ok: false, reason: "a given was changed" };
+    }
+    const seen = new Array(layout.groups.length).fill(0);
+    for (let index = 0; index < filled.length; index += 1) {
+        const bit = 1 << filled[index];
+        for (const group of layout.groupsOf[index]) {
+            if (seen[group] & bit)
+                return { ok: false, reason: `${groupName(layout, group)} repeats a number` };
+            seen[group] |= bit;
+        }
+    }
+    return { ok: true };
+}
+/** "row 3", "column 5", "box 2", "region 4", "a diagonal": the groups in `layout.ts`'s order. */
+function groupName(layout, group) {
+    const { size } = layout;
+    if (group < size)
+        return `row ${group + 1}`;
+    if (group < 2 * size)
+        return `column ${group - size + 1}`;
+    if (group < 3 * size)
+        return `${layout.regionWord} ${group - 2 * size + 1}`;
+    return "a diagonal";
+}
+function checkMoreOrLess(size, givens, answer) {
+    const asked = decodeMoreOrLess(givens, size);
+    if (asked === null)
+        return { ok: false, reason: "the givens are not a grid with marks" };
+    const square = checkLatinSquare(size, asked.cells, answer);
+    if (!square.ok)
+        return square;
+    const filled = decodeCells(answer, size);
+    for (const mark of asked.marks) {
+        if (!(filled[mark.less] < filled[mark.more]))
+            return { ok: false, reason: "a mark is not true" };
+    }
+    return { ok: true };
+}
+/** Every row and column a permutation of 1..size, nothing empty, and every given where it was: More or Less and Towers alike. */
+function checkLatinSquare(size, asked, answer) {
+    const filled = decodeCells(answer, size);
+    if (filled === null)
+        return { ok: false, reason: "the answer is not a grid" };
+    if (filled.some((value) => value === 0))
+        return { ok: false, reason: "the answer has empty cells" };
+    for (let index = 0; index < asked.length; index += 1) {
+        if (asked[index] !== 0 && asked[index] !== filled[index])
+            return { ok: false, reason: "a given was changed" };
+    }
+    const rows = Array.from({ length: size }, () => 0);
+    const cols = Array.from({ length: size }, () => 0);
+    for (let index = 0; index < filled.length; index += 1) {
+        const bit = 1 << filled[index];
+        const row = Math.floor(index / size);
+        const col = index % size;
+        if (rows[row] & bit)
+            return { ok: false, reason: `row ${row + 1} repeats a number` };
+        if (cols[col] & bit)
+            return { ok: false, reason: `column ${col + 1} repeats a number` };
+        rows[row] |= bit;
+        cols[col] |= bit;
+    }
+    return { ok: true };
+}
+/**
+ * Towers: a Latin square that keeps its givens, and from every clue exactly that many towers show.
+ * The counting is written out here rather than taken from `towersSeen`, which the solver that made
+ * the puzzle uses; only where each clue looks from is shared, because that is the spelling.
+ */
+function checkTowers(size, givens, answer) {
+    const asked = decodeTowers(givens, size);
+    if (asked === null)
+        return { ok: false, reason: "the givens are not a square with clues" };
+    const square = checkLatinSquare(size, asked.cells, answer);
+    if (!square.ok)
+        return square;
+    const filled = decodeCells(answer, size);
+    for (const side of TOWER_SIDES) {
+        for (let at = 0; at < size; at += 1) {
+            const clue = asked.clues[side][at];
+            if (clue === 0)
+                continue;
+            let tallest = 0;
+            let seen = 0;
+            for (const index of lineFrom(side, at, size)) {
+                if (filled[index] > tallest) {
+                    tallest = filled[index];
+                    seen += 1;
+                }
+            }
+            if (seen !== clue)
+                return { ok: false, reason: `the ${side} clue ${clue} sees ${seen}` };
+        }
+    }
+    return { ok: true };
+}
+/** Whether a puzzle's givens are a well-formed puzzle of that kind and side at all (a Jigsaw's regions sound, every code readable). */
+export function isKazuGivens(kind, size, givens) {
+    const read = readGivens(kind, size, givens);
+    if (read === null)
+        return false;
+    return kind !== "jigsaw" || (read.regions !== null && regionsAreSound(size, read.regions));
+}

package/dist/clock.d.ts

@@ -0,0 +1,2 @@
+/** A time taken, as a clock shows it: `m:ss`, and `h:mm:ss` past an hour. */
+export declare function kazuClockText(ms: number): string;

package/dist/clock.js

@@ -0,0 +1,9 @@
+/** A time taken, as a clock shows it: `m:ss`, and `h:mm:ss` past an hour. */
+export function kazuClockText(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    const s = seconds % 60;
+    const m = Math.floor(seconds / 60) % 60;
+    const h = Math.floor(seconds / 3600);
+    const two = (n) => String(n).padStart(2, "0");
+    return h > 0 ? `${h}:${two(m)}:${two(s)}` : `${m}:${two(s)}`;
+}

package/dist/conflicts.d.ts

@@ -0,0 +1,14 @@
+import type { KazuGivens } from "./givens.ts";
+/**
+ * THE CELLS THAT BREAK A RULE RIGHT NOW, read from the rules alone: no answer is needed, so it works
+ * on any puzzle, and it names a mistake the moment it is made rather than when it is checked.
+ *
+ * `values` is the whole grid as it stands: the printed numbers and what has been written, row-major,
+ * 0 for empty. A cell is in conflict when it shares a row, a column, a box, a region, a diagonal or a
+ * cage with a cell holding the same number; when a cage is full and does not add to its sum, or already
+ * adds to more; when a more-than mark between two filled cells is not true; or when the cells from a
+ * Towers clue show more towers than the clue says (or, once the line is full, any other number).
+ * An empty cell is never in conflict, and a grid with no conflict is not thereby right: it may
+ * simply not be finished.
+ */
+export declare function conflictsOf(givens: KazuGivens, values: readonly number[]): number[];

package/dist/conflicts.js

@@ -0,0 +1,79 @@
+import { layoutOfGivens } from "./givens.js";
+import { lineFrom, TOWER_SIDES } from "./towersCode.js";
+/**
+ * THE CELLS THAT BREAK A RULE RIGHT NOW, read from the rules alone: no answer is needed, so it works
+ * on any puzzle, and it names a mistake the moment it is made rather than when it is checked.
+ *
+ * `values` is the whole grid as it stands: the printed numbers and what has been written, row-major,
+ * 0 for empty. A cell is in conflict when it shares a row, a column, a box, a region, a diagonal or a
+ * cage with a cell holding the same number; when a cage is full and does not add to its sum, or already
+ * adds to more; when a more-than mark between two filled cells is not true; or when the cells from a
+ * Towers clue show more towers than the clue says (or, once the line is full, any other number).
+ * An empty cell is never in conflict, and a grid with no conflict is not thereby right: it may
+ * simply not be finished.
+ */
+export function conflictsOf(givens, values) {
+    const { size } = givens;
+    const bad = new Set();
+    const layout = layoutOfGivens(givens);
+    const groups = layout !== null
+        ? layout.groups
+        : [...Array.from({ length: size }, (_, r) => Array.from({ length: size }, (_, c) => r * size + c)), ...Array.from({ length: size }, (_, c) => Array.from({ length: size }, (_, r) => r * size + c))];
+    for (const group of groups) {
+        const first = new Map();
+        for (const index of group) {
+            const value = values[index];
+            if (value === 0)
+                continue;
+            const was = first.get(value);
+            if (was === undefined)
+                first.set(value, index);
+            else {
+                bad.add(was);
+                bad.add(index);
+            }
+        }
+    }
+    for (const cage of givens.cages ?? []) {
+        const filled = cage.cells.filter((index) => values[index] !== 0);
+        const total = filled.reduce((sum, index) => sum + values[index], 0);
+        if (total > cage.sum || (filled.length === cage.cells.length && total !== cage.sum))
+            for (const index of filled)
+                bad.add(index);
+    }
+    for (const mark of givens.marks) {
+        const less = values[mark.less];
+        const more = values[mark.more];
+        if (less !== 0 && more !== 0 && !(less < more)) {
+            bad.add(mark.less);
+            bad.add(mark.more);
+        }
+    }
+    if (givens.clues !== null) {
+        for (const side of TOWER_SIDES) {
+            for (let at = 0; at < size; at += 1) {
+                const clue = givens.clues[side][at];
+                if (clue === 0)
+                    continue;
+                const line = lineFrom(side, at, size);
+                let tallest = 0;
+                let seen = 0;
+                let reached = 0;
+                for (const index of line) {
+                    const value = values[index];
+                    if (value === 0)
+                        break;
+                    reached += 1;
+                    if (value > tallest) {
+                        tallest = value;
+                        seen += 1;
+                    }
+                }
+                if (seen > clue || (reached === size && seen !== clue))
+                    for (const index of line.slice(0, reached))
+                        bad.add(index);
+            }
+        }
+    }
+    return [...bad].sort((a, b) => a - b);
+}

package/dist/draw-entry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Kazu's drawing: a puzzle as SVG text, with the style that gives it its look, and where everything sits
+ * in it (so a page can tell which cell a finger is over). A separate entry
+ * (`@johnmorrisdotca/kazu/draw`), so a server that only checks an answer never loads any of it.
+ */
+export { drawKazu, kazuCellName, kazuWhere } from "./draw.ts";
+export type { KazuDrawOptions } from "./draw.ts";
+export { kazuGeometry, KAZU_CELL } from "./geometry.ts";
+export type { KazuGeometry } from "./geometry.ts";
+export { KAZU_STYLE } from "./style.ts";
+export { KAZU_STRINGS, kazuLanguageOf, kazuNameOf, kazuSay } from "./strings.ts";
+export type { KazuLanguage } from "./strings.ts";
+export { KAZU_NAMES, KAZU_SIZE_NAMES } from "./names.ts";
+export type { KazuName } from "./names.ts";

package/dist/draw-entry.js

@@ -0,0 +1,10 @@
+/**
+ * Kazu's drawing: a puzzle as SVG text, with the style that gives it its look, and where everything sits
+ * in it (so a page can tell which cell a finger is over). A separate entry
+ * (`@johnmorrisdotca/kazu/draw`), so a server that only checks an answer never loads any of it.
+ */
+export { drawKazu, kazuCellName, kazuWhere } from "./draw.js";
+export { kazuGeometry, KAZU_CELL } from "./geometry.js";
+export { KAZU_STYLE } from "./style.js";
+export { KAZU_STRINGS, kazuLanguageOf, kazuNameOf, kazuSay } from "./strings.js";
+export { KAZU_NAMES, KAZU_SIZE_NAMES } from "./names.js";

package/dist/draw.d.ts

@@ -0,0 +1,47 @@
+import type { KazuKind } from "./kinds.ts";
+import { type KazuLanguage } from "./strings.ts";
+/** What a drawing shows beyond the puzzle itself. Every part is optional: a puzzle alone is its printed grid. */
+export type KazuDrawOptions = {
+    /** What the player has written, row-major, 0 for empty. */
+    entries?: readonly number[];
+    /** Pencil marks, a bit mask a cell: bit `v` is the note `v` (`notesOf`). */
+    notes?: readonly number[];
+    /** The chosen cell. */
+    selected?: number | null;
+    /** Wash the chosen cell's row, column and group, and every cell holding its number. */
+    peers?: boolean;
+    /** Cells that break a rule, drawn in red with their numbers (`conflictsOf`). */
+    conflicts?: readonly number[];
+    /** Cells Check flagged wrong. */
+    wrong?: readonly number[];
+    /** The cell a hint pointed at. */
+    hint?: number | null;
+    /** A faint wash of green, and `data-solved="true"`. */
+    done?: boolean;
+    /** Put a transparent square over every cell, each with its `data-cell`, for a page to press on. `mountKazu` does. */
+    interactive?: boolean;
+    /** What a screen reader hears. */
+    language?: KazuLanguage;
+    /** A description instead of "Sudoku puzzle, 9 by 9". */
+    label?: string;
+    /** Put `KAZU_STYLE` inside, so the drawing stands alone as an image. */
+    style?: boolean;
+    /** Draw the wooden frame round the paper. Default false. */
+    frame?: boolean;
+};
+/** The words for the groups a number is ruled out by, for a hint's line: "its row, column and box". */
+export declare function kazuWhere(kind: KazuKind, language: KazuLanguage): string;
+/** A cell as a screen reader names it: "row 3, column 5". */
+export declare function kazuCellName(size: number, index: number, language: KazuLanguage): string;
+/**
+ * A PUZZLE AS SVG TEXT: the grid with its printed numbers, whatever has been written in it, pencil
+ * marks, and everything the kind of puzzle prints: the heavier rules round the boxes or a Jigsaw's
+ * regions, the shaded diagonals, a cage's dashed outline with its sum, the more-than marks between
+ * cells, and the tower clues round the edge. The chosen cell, the cells that break a rule, the cells
+ * Check flagged and the cell a hint pointed at are washed in colour.
+ *
+ * Returns the `<svg>` as a string: put it in a page, a file or an image, with nothing to load. It is
+ * one steady square whatever is drawn, so nothing moves as numbers are written. Nothing in it can be
+ * selected or dragged. Null for givens that are not a puzzle of that kind and side.
+ */
+export declare function drawKazu(kind: KazuKind, size: number, givensCode: string, options?: KazuDrawOptions): string | null;