Skip to the content

Kazu数

Generate checked Sudoku and logic puzzles, read native rules and hints, and draw or embed playable boards.

Kazu is the Japanese word 数 for number. About the name

Contents

Changelog

All notable changes to this project are written here. The format follows Keep a Changelog, and the project uses Semantic Versioning.

[Unreleased]

[2.1.0] - 2026-10-14

The puzzle boards are custom elements with the family's standard embed attributes and a shared builder, and the package has an English and Japanese documentation site with a checked example for every export. The rules, generators, puzzle codes and saved progress are unchanged.

Added

  • Add the bilingual documentation site, checked public examples, paired guides, local search and machine-readable pages.
  • Add a shared builder and validated, storage-free iframe for seeded and UTC daily number puzzles.
  • Add display sizes, grid, width, theme and spoken label while retaining numeric size aliases and existing methods. Native events now cross shadow boundaries with JSON-safe detail.
  • Share a package-independent embed builder for option controls, preview adapters, code tabs and shareable links.

Changed

  • The README's section on drawing a puzzle moved to docs/DRAWING.md, so that the README, which now lists the sports packages too, stays under npm's 65,536 characters; the README keeps a summary and a link.
  • The API link in the header reads "API" in English, so that the header takes the same number of rows in English and in Japanese on a phone, as the demo's test of a language change asks.
  • Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
  • Keep complete resource catalogues on the documentation entry index and the active resource beside core navigation; render valid default imports in HTML and Markdown.
  • Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
  • Update the shared family description for addresses in all seven supported countries, including France and Germany.

[2.0.1] - 2026-10-06

Nothing that was exported has changed. The README is the family's one layout, in full, and the reference for the puzzles with a page of their own moved to pages under docs/.

Added

  • The README has a picture of the demo on a desk and on a phone, in light and dark, taken from the demo by pnpm screenshots:readme (the pictures are in docs/images/ and are not in the package), a picture of each of the eighteen puzzles, an Examples section of nine examples that run (making a puzzle and counting its answers, the levels, a hint that is a reason, a run as a short string, the drawing as SVG text on a server, the other puzzles' engines, and playing from a script), tables of the entry points and the calls to learn first, and an Accessibility section.
  • docs/PUZZLES.md, docs/PLAYING.md and docs/ARCHITECTURE.md hold the sections of the README that were its reference (each puzzle with a page of its own, the levels of the grid puzzles, playing it in a page, and the source tree), word for word. npm shows only the first 65,536 characters of a README and this one was 78,097 (the registry's copy ended mid-sentence in the Roadmap, before the puzzles' sections, Architecture, the family and the Licence); it is 61,617 now, and each moved section keeps its heading, a summary and a link. scripts/full-readme.mjs puts the moved sections back, so that the tests that hold the documentation to the code read the whole.
  • pnpm test:readme type-checks and runs every TypeScript and JavaScript example in the README against the built package, as a job of its own in CI; src/readme.test.js holds the README to the family's standard (sections in order, languages on code fences, pictures with alt text and a caption, no marketing words, version pins, at most 64,000 characters) in pnpm check; pnpm test:package fails if a picture or anything under docs/ is in the packed package.

Changed

  • The README's sections are in the family's order: Hitori and Nurikabe, which came after the Licence, and the other puzzles, which came after the Roadmap, are under the puzzles; and the Features list no longer says "Seven puzzles" beside "Six number puzzles".
  • pnpm pictures is pnpm screenshots:readme, and takes WebP pictures in light and dark under docs/images/; docs/desktop.jpg and docs/phone.jpg are gone.

[2.0.0] - 2026-10-06

The package is named for the puzzles it makes, not for the names another site printed them under: Slitherlink is Loop, Kakuro is Cross Sums and Fillomino is Regions, in every address, file, export and attribute. Nothing is kept under an old name, so this is a major version. The puzzles themselves are unchanged: the same seed makes the same board.

Breaking

  • Package entries. Each is renamed with its /play and /draw:

    1.x2.0
    @johnmorrisdotca/kazu/slitherlink (/play, /draw)@johnmorrisdotca/kazu/loop (/play, /draw)
    @johnmorrisdotca/kazu/kakuro (/play, /draw)@johnmorrisdotca/kazu/cross-sums (/play, /draw)
    @johnmorrisdotca/kazu/fillomino (/play, /draw)@johnmorrisdotca/kazu/regions (/play, /draw)

  • Exports. Every name carrying an old puzzle name carries the new one, in the same place: Slitherlink becomes Loop, Kakuro becomes CrossSums and Fillomino becomes Regions, and SLITHERLINK_, KAKURO_ and FILLOMINO_ become LOOP_, CROSS_SUMS_ and REGIONS_. For example generateSlitherlink is generateLoop, drawSlitherlink is drawLoop, mountSlitherlink is mountLoop, SlitherlinkBoard is LoopBoard, SLITHERLINK_SIZES is LOOP_SIZES, slitherlinkCellEdges is loopCellEdges; checkKakuro is checkCrossSums, kakuroRuns is crossSumsRuns, KAKURO_LEVELS is CROSS_SUMS_LEVELS, KakuroPuzzle is CrossSumsPuzzle; generateFillomino is generateRegions, checkFillomino is checkRegions, fillominoFinished is regionsFinished, FILLOMINO_SIZES is REGIONS_SIZES, FillominoBoard is RegionsBoard. The types, the *Options and *Language and the play style and strings constants follow the same rule.

  • Two names that would have met an existing one. encodeFillomino and decodeFillomino are encodeRegionsGame and decodeRegionsGame, because encodeRegions and decodeRegions already encode a Jigsaw's regions; and fillominoRegions is entryRegions.

  • Saved progress. The player keeps its progress under kazu-loop-v1, kazu-cross-sums-v1 and kazu-regions-v1, where it used kazu-slitherlink-v1, kazu-kakuro-v1 and kazu-fillomino-v1; a run saved under the old key is not read, and a new one begins.

  • The demo's pages are loop.html, cross-sums.html and regions.html on the project's site; the old pages are gone.

Changed

  • Source files are named in kebab-case, and a lint rule keeps them so.
  • The README, the documentation and the player's titles say Loop, Cross Sums and Regions, and say once where each is also known as Slitherlink, Kakuro or Fillomino. docs/FILLOMINO.md is docs/REGIONS.md.
  • CONTRIBUTING.md is the family's one text with a section of its own for Kazu, held to the master in johnmorrisdotca/.github by src/family.test.js; ci.yml and pages.yml are the family's one text (pnpm check, the demo, and the package on Linux, macOS and Windows), and any jobs of the package's own after them.
  • The demo's page titles read Kazu · pitch, like the rest of the family's.

Fixed

  • The Regions demo page asked for its worker at ../dist/, which resolved only on a server serving the site from its root; on the project's site at /kazu/ it reached /dist/ and found nothing. It and the Shikaku page now name ./dist/.
  • The demo test that draws More or Less at each size no longer fails now and then: a fresh seed makes the puzzle, and about one 4×4 in seventy prints no mark, so it asked for at least one .kz-mark and got none. It now holds the marks drawn to the marks the package prints for the seed on the board.
  • The API reference page wraps a long entry path instead of running about 2 px wider than a 360 px screen.

[1.4.1] - 2026-10-05

Nothing that was exported has changed.

Added

  • A test holds every @johnmorrisdotca/kazu@N version pin in the README to this package's major version.

Changed

  • The family's list, in the README and in the demo's footer, names all twenty-four packages, Karakuri and Houseki included.
  • The npm description is one sentence of 250 characters or fewer, so npm and its search show it whole; it is also the repository's About text. homepage is the demo site and author is "John Morris", the same in every package.
  • The GitHub Actions workflows use the current versions of the actions (checkout 7, setup-node 7, pnpm/action-setup 6; configure-pages 6, upload-pages-artifact 5 and deploy-pages 5 for Pages), which clears GitHub's Node 20 deprecation warning.

[1.4.0] - 2026-10-05

Added

  • A 25×25 Sudoku, the Colossus. number-place takes a side of 25 (KAZU_SPECS["number-place"].sizes is now 4, 6, 9, 16, 25; boxes of 5×5; mostCells 625) at easy, medium and hard, every puzzle with exactly one answer. Its symbols go on from the 16×16's: 1 to 9, then A to P for 10 to 25 (symbolOf, valueOfSymbol, decodeCells and the run and note codes read A to P). Easy yields to singles alone (366 numbers printed), medium to one guess (305), hard to two nested guesses (283). The player's pad has 25 keys and the eraser in three rows, and the keyboard types the letters up to P; because N is the number 23 there, Pencil moves to the slash key on this size (keysColossus says so in English and Japanese). Made in a browser's time, over seeds 1 to 50 on a Mac: easy a median 13 ms (slowest 30), medium 81 ms (161), hard 308 ms (590). Hard is the one a phone may take a few seconds over, so a page that deals one for a person should do it in a worker, as the demo's slower generators do.
  • A 25×25 is made and checked by proof, not by counting every answer: provedByGuessing(grid, layout, guesses) is what a person's reasoning proves (singles, then guesses at the most constrained cell, each shown wrong or finished by singles), and countKazuSolutions, solveKazu and kazuGuessDepth use singles inside the search from the 25×25 up, which takes a medium or hard 25×25 from minutes to a few milliseconds. Every smaller size is searched exactly as before.

Fixed

  • Akari never returns the old fixed lattice. When a level found no random board within its 60 attempts, 1.3.0 returned the fixed rooms of 1.2.0 without saying so: 74% black squares and five full black rows at 14×14, which was about 45% of 14×14 easy seeds (and 17% of 12×12, 35% of 13×13, 65% of 15×15 and 83% of 16×16 easy seeds, and some medium ones at 13×13 and larger). The generator now tries again with more black squares (1.5, 1.8, 2.1 and 2.4 times the usual share, thirty attempts each), which a large board needs to be solvable by its numbers. Every seed that made a random board in 1.3.0 makes the identical one (src/levels.pins.test.js, and a comparison over 12×12 to 16×16 at every level); only the seeds that used to return the lattice make a different board, and they make a random one. src/akariLattice.test.ts asserts, over every size from 3 to 16 and every level, that no seed returns the lattice, and that the black share and the boards vary. Generation time is unchanged where it was already random (14×14 extra-hard: median 212 ms, slowest 362 ms) and the old lattice cases take a median of 9 ms at 14×14 easy.

[1.3.0] - 2026-10-05

Added

  • Four levels on six grid puzzles. Shikaku, Akari, Slitherlink, Hitori, Fillomino and Kakuro each make easy, medium, hard and extra-hard boards (the level types and SHIKAKU_LEVELS, AKARI_LEVELS, SLITHERLINK_LEVELS, HITORI_LEVELS, FILLOMINO_LEVELS and KAKURO_LEVELS), every one with exactly one answer, and every puzzle now carries its level. Easy and medium are solved by plain rules (easy keeps more of its numbers, medium has as few as the rules allow); hard needs supposing something and seeing it break; extra-hard needs the most of that.
  • More sizes. AKARI_SIZES (5, 7, 10, 14), SLITHERLINK_SIZES (5, 7, 10), HITORI_SIZES (5, 6, 7, 8, 9, 10, 12), FILLOMINO_SIZES (6, 8, 10, 12), KAKURO_SIZES (6, 8, 10, 12) and SHIKAKU_SIZES (5, 7, 10, 14) list what the demo offers. Hitori takes any side from 4 to 12 (was 5 and 7), Kakuro any side from 5 to 12 (was one size, 10), Fillomino any side from 4 to 12 (was 4 to 8 and 36 squares).
  • A measured difficulty. rateShikaku, rateAkari, rateSlitherlink, rateHitori, rateFillomino and rateKakuro solve a board with one answer the way a person does (the rules alone, then supposing one thing, then more) and report how deep that went (depth, probes) and what the board is made of (numbers, runs, regions, loop length). docs/LEVELS.md defines each level per kind and tables the measures and the generation times by size and level; node scripts/measure-levels.mjs makes the tables again, and draws a puzzle as text with --show.
  • A shared engine (src/csp.ts) under the six kinds: counting answers, reasoning with and without supposing, and proving one answer by reasoning when that is enough.
  • generateAkari, generateSlitherlink, generateHitori and generateKakuro take the level as a last argument (generateAkari(width, height, seed, level?), generateSlitherlink(width, height, seed, level?), generateHitori(size, seed, level?), generateKakuro(seed, level?, size?)), "medium" if left out; Shikaku and Fillomino keep (width, height, level, seed) and add extra-hard.
  • The demo has a Level choice, in English and Japanese, on all six pages, and the sizes above.

Changed

  • The six generators make new boards. Akari, Slitherlink, Hitori and Kakuro used fixed layouts (the Akari rooms, a loop of one or two blocks with nearly every square numbered and most of them 0, three or four shaded squares in Hitori, a 10×10 of 2×2 to 3×3 blocks) and made the same few motifs again and again; they now build random boards: Akari scatters black squares and takes numbers away, Slitherlink grows a winding loop and takes numbers away (few say 0), Hitori shades about a quarter of the squares and repairs the numbers until the answer is single, Kakuro lays runs out row by row and repairs digits, and Shikaku packs interlocking rectangles instead of cutting straight lines. Fillomino's generator is new and no longer slow (a 6×6 took up to 1.7 s). A seed makes a different puzzle from the one 1.2.0 made for Shikaku, Akari, Slitherlink, Hitori, Kakuro and Fillomino; a progress code carries its board, so a saved game is unaffected, but a site that keeps a game as kind, size, level and seed will find that seed is another puzzle. The six number puzzles are untouched, and src/site.fixture.json still makes all 3,600 of them again, byte for byte.
  • The six solvers count answers with a shared engine that reasons first: a board that the rules (or one supposition) settle is proved with no search at all, and others are searched from what reasoning left. Counts are the same as before on every board the tests compare (exhaustive enumeration of small boards, and the old solvers); only the node counts, and so what a given nodes budget reaches, are different, and answers are found in far fewer nodes. hint* calls are quicker as a result.
  • If a generator cannot make a board of the level within its attempts it makes one of the next level down, and finally a plain one, rather than throw; the rating of the board shows what it is. On the 20,800 boards of docs/LEVELS.md (seeds 1 to 200 at every size and level) this happened on none.
  • Fillomino's number choice in the player offers only numbers a board can hold (up to the biggest given, or the biggest stretch of squares with none), not up to the square count.

Fixed

  • generateKakuro(97) threw "No uniquely solvable Kakuro board was proved within the generation budget"; no seed throws now, at any level or size.
  • solveHitori could count one shade pattern twice (so a board with two answers could be reported as having three, and a limit could be reached early); it counts each distinct pattern once.

[1.2.0] - 2026-10-05

Added

  • Hitori and Nurikabe: independent shading rules, bounded solution counting, original proof-backed puzzle families, bilingual players and package entry points.

  • Juosan: a dedicated territory model, verified small training layouts and a bilingual player for supplied boards.

  • Nine named Shikaku challenges across square, wide and tall routes.

  • Akari: a separate rule engine, bounded solution counter, seeded unique puzzle generator, immutable play, accessible bilingual player, drawing and demo.

  • Slitherlink: a dedicated edge-loop engine, bounded unique-puzzle generation, accessible bilingual player, demo and package entry points.

  • Ripple Effect: a dedicated room and spacing engine, bounded unique 9×9 generation, bilingual accessible player, demo and package entries.

  • Kakuro: a seeded uniquely proved crossword-sum family, independent bounded solver, immutable progress, SVG and accessible English/Japanese player.

  • Masyu and Yajilin: cell-centre loop engines, bounded proof-backed 5×5 families, drawing, bilingual players and saved progress.

  • Fillomino: connected numbered regions, bounded original rectangular generation, independent checks, hints and a bilingual player.

  • Heyawake: rectangular rooms, shading and white-path rules, bounded original small-board generation, hints and a bilingual player.

[1.1.0] - 2026-10-04

Added

  • Shikaku: unique seeded rectangle puzzles, exact-cover solving, immutable play and progress, SVG drawing, accessible bilingual controls and worker-backed generation.
  • Square, wide, tall and custom rectangle demos using the shared family styling. Existing six number-entry kinds and saved codes remain compatible.

[1.0.0] - 2026-10-01

The Numbers family of grid puzzles, taken out of itsutsu.com so that the site can import them as it imports its other family packages. Every puzzle the site made before the move is made again here, givens and solution, byte for byte: src/site.fixture.json holds 3,600 of them (every puzzle, size and level, sixty seeds each) and six tests make each again.

  • Six puzzles, by key: number-place (Sudoku, 4×4 to a 16×16 Giant), jigsaw, diagonal, sum-cages (Killer Sudoku), more-or-less (Futoshiki) and towers (Skyscrapers), each at easy, medium and hard.
  • @johnmorrisdotca/kazu: generateKazu, solveKazu, countKazuSolutions, kazuGuessDepth, checkKazu (the O(cells) check, with the site's own reasons), hintKazu (the next cell and why), conflictsOf, readGivens, the string codes of givens, runs, pencil marks and step logs (the site's own spellings, which decode unchanged), and a game in play as pure functions.
  • @johnmorrisdotca/kazu/draw: a puzzle as SVG text with entries, pencil marks, the chosen cell and its lines, conflicts, diagonals, dashed cages with their sums, more-than marks and the tower clues round the edge, in light and dark, with generic colours as custom properties.
  • @johnmorrisdotca/kazu/play: mountKazu plays a puzzle in any element by touch, mouse and keyboard, with a number pad, pencil marks, Undo, Hint, Check, a clock and events; English and Japanese.
  • <kazu-board> (/element, /element/define): the same in a tag.
  • A demo with a chooser, a Help switch, the cloth patches, and browser tests (pnpm test:demo) at a phone's width and a desk's, in Chromium and WebKit.

View sourceEdit on GitHubMade from the source of @johnmorrisdotca/kazu 2.1.0.