@johnmorrisdotca/jirai 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-05
+
+Nothing that was exported has changed.
+
+### Added
+
+- A test holds every `@johnmorrisdotca/jirai@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.
+- Every entry has an `import` condition beside `default`.
+- The README has the family's sections in the family's order (Who it is for, Features, Use it in your project, API, Theming, Limits, Browser support, Languages, Roadmap, Architecture, Where it comes from, Changes), the family list sits under "Where it comes from", and a test holds it to them.
+- The development tools are the family's: Vitest 5 and Playwright 1.63, as in the other packages.
+
 ## [0.4.0] - 2026-10-05
 
 - **Huge fields.** `hugeSettings(level, { grid, shape, size })` and `HUGE_SIZES` (32×32, 48×24 and 24×48) give each of the four levels on a field of four times the medium level's area, 1,024 to 1,152 squares, with the level's share of mines (a 32×32 has 126, 160, 211 and 256 mines at easy, medium, hard and extra-hard), on every rule set and outline. Every one is dealt and proved to need no guess in a median of 3 to 60 ms (73 ms the slowest of ten 32×32 seeds), on the square, orthogonal, hexagonal and wraparound grids and the heart, star and hexagon outlines, and `src/huge.test.ts` wins a 32×32 at easy and at extra-hard by the explained hints alone. The demo's Level menu offers them (`?level=huge-hard`).

package/README.md

@@ -44,7 +44,13 @@ const game = newOrthogonalGame(settings);
 const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing neighbours
 ```
 
-## What it does
+## Who it is for
+
+- **Puzzle and game sites** that want Minesweeper with boards a player can trust: seeded fields that deal the same everywhere, a safe opening, verified no-guess deals, and the words in English and Japanese.
+- **Developers of other front ends** who want the rules, the dealer and the deduction solver as plain functions, with no DOM, and their own drawing on top.
+- **Players and teachers** who want to learn why a cell is safe: the hints explain the deduction that proves it, and a level steps up a measured difficulty.
+
+## Features
 
 - **Four rule sets:** square grids count eight neighbours, orthogonal grids count four, hex grids count six axial neighbours, and wraparound grids join opposite square edges.
 - **Board outlines:** rectangles, hearts, stars and hexagon outlines. Shaped boards have cut-outs; wraparound works with rectangles.
@@ -56,7 +62,7 @@ const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing nei
 - **Accessible controls:** keyboard navigation, pointer and touch, long press to mark, English and Japanese strings, and board labels read by assistive technology.
 - **Materials and markers:** ivory, wood or slate; flags, stones or flowers. Host CSS can replace the palette.
 
-## Use it in a page
+## Use it in your project
 
 Mount a player into any element. The first reveal asks the module worker to deal the board, so serve the package over HTTP and allow same-origin module workers in your content security policy.
 
@@ -153,13 +159,17 @@ Orthogonal clues carry less information, so its numbers are smaller at every lev
 
 The full engine entry is `@johnmorrisdotca/jirai`; four-neighbour helpers are in `@johnmorrisdotca/jirai/orthogonal`. Drawing is `@johnmorrisdotca/jirai/draw`, browser play is `/play`, and the custom element is `/element` or `/element/define`. The [API guide](docs/API.md) lists the entries and public calls.
 
-## Drawing and theming
+## API
+
+Every export of every entry point is in the [API reference](https://johnmorrisdotca.github.io/jirai/api.html), made from the source when the demo is built, and the [API guide](docs/API.md) lists the entries and public calls in prose.
+
+## Theming
 
 `boardModel(game, options)` returns row-major labelled cells without touching the DOM. The draw entry exports `JIRAI_STYLE` and the board model. The player uses the same theme variables as its SVG and HTML controls; set `material`, `pieces`, and `language` on mount or override the CSS custom properties in your host.
 
 Materials are `ivory`, `wood` and `slate`. Marker sets are `flags`, `stones` and `flowers`. They change appearance only; the engine still stores covered, flag, question or open states.
 
-## Limits and browser support
+## Limits
 
 The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular.
 
@@ -182,34 +192,67 @@ The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at
 
 For synchronous server use, consider running a deal in a worker; a browser deals extra-hard in the board's own worker without a pause.
 
+## Browser support
+
 The browser player uses ES modules, SVG, custom elements, dialogs and module workers. Serve built files over HTTP; `file:` pages cannot load its worker. The engine and drawing functions do not need DOM globals. Development and tests require Node 22 or later.
 
+## Languages
+
+The player's words are English and Japanese, chosen with the `language` option or the `lang` attribute: the buttons, the status lines, the hints and the labels read by assistive technology. Corrections to the Japanese are welcome as issues.
+
+## Roadmap
+
+The engine, the dealer, the hints and the player are in. Nothing else is promised for a date; ideas are welcome in the [issues](https://github.com/johnmorrisdotca/jirai/issues).
+
+## Architecture
+
+```text
+src/
+├── deduce.ts
+├── draw-entry.ts
+├── draw.ts
+├── element-define.ts
+├── element.ts
+├── enumerate.ts
+├── flood.ts
+├── game.ts
+├── generate.ts
+├── grid.ts
+├── index.ts
+├── jirai.constants.ts
+├── jirai.types.ts
+├── keep.ts
+├── levels.ts
+├── measure.ts
+├── mount.ts
+├── orthogonal.ts
+├── play-entry.ts
+├── random.ts
+├── react.tsx
+├── react.types.ts
+├── repair.ts
+├── shape.ts
+├── solve.ts
+├── strings.ts
+├── style.ts
+├── ui.types.ts
+└── worker.ts
+```
+
 ## The name
 
 *Jirai* (地雷) is Japanese for a land mine, read じらい, said in three beats, *ji-ra-i*. It is made of 地 (*ji*,
 ground) and 雷 (*rai*, thunder): a mine is thunder buried in the ground. Every number on the board is a clue to
 where it lies. ([Wiktionary: 地雷](https://en.wiktionary.org/wiki/地雷).)
 
-## Development
+## Where it comes from
 
-```sh
-pnpm install --frozen-lockfile
-pnpm check          # lint, types and tests
-pnpm test:package   # build and import the actual npm tarball
-pnpm test:demo      # browser flows against the built page
-pnpm site           # build the standalone page into docs/
-```
+Minesweeper's rules are common property. Everything here, the rules, the dealer, the solver, the hints, the pictures and the words, is written for the package, and no third-party puzzle boards or artwork are included.
 
-The standalone game is `docs/index.html`. The preview binds to `127.0.0.1:6713`; see [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine or player.
-
-## Licence
-
-[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.
-
-## The family
+### The family
 
 <!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
-Jirai is one of twenty-two packages, each made for the same site, each at
+Jirai is one of twenty-four packages, each made for the same site, each at
 [github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). The code of every one is MIT.
 
 - [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
@@ -234,10 +277,32 @@ Jirai is one of twenty-two packages, each made for the same site, each at
 - [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
 - [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
 - [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
+- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
+- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
 
-**This package is Jirai.** The demos of all twenty-two share one header and footer, so each links the rest.
+**This package is Jirai.** The demos of all twenty-four share one header and footer, so each links the rest.
 <!-- family:end -->
 
-## Contributing and security
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check          # lint, types, tests and the presentation checks
+pnpm test:package   # build and import the actual npm tarball
+pnpm test:demo      # browser flows against the built page
+pnpm site           # build the standalone page into docs/
+```
+
+The standalone game is `docs/index.html`. The preview binds to `127.0.0.1:6713`; see [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine or player.
+
+## Contributing
+
+Bug reports and pull requests are welcome in the [issues](https://github.com/johnmorrisdotca/jirai/issues). See [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).
+
+## Changes
 
-See [Contributing](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).
+Every release is written up in [CHANGELOG.md](./CHANGELOG.md).
+
+## Licence
+
+[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
 /** Package version, kept in step with the release metadata. */
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.4.1";
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 export * from "./orthogonal.ts";
 export { measureBoard } from "./measure.ts";

package/dist/index.js

@@ -8,7 +8,7 @@ export * from "./deduce.js";
 export * from "./keep.js";
 export { seededRandom } from "./random.js";
 /** Package version, kept in step with the release metadata. */
-export const VERSION = "0.4.0";
+export const VERSION = "0.4.1";
 export { SHAPES, activeCell, activeCells } from "./shape.js";
 export * from "./orthogonal.js";
 export { measureBoard } from "./measure.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.4.0",
-  "description": "Minesweeper on square, orthogonal, hexagonal and wraparound boards: four levels up to extra-hard, seeded games, a safe opening, verified no-guess boards, explained hints, configurable materials and markers, and a playable board for any page. Zero runtime dependencies.",
+  "version": "0.4.1",
+  "description": "Minesweeper on square, orthogonal, hexagonal and wraparound boards: four levels up to extra-hard, seeded games, a safe opening, verified no-guess boards, explained hints and a playable board for any page. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
   "author": "John Morris",
@@ -54,30 +54,37 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./orthogonal": {
       "types": "./dist/orthogonal.d.ts",
+      "import": "./dist/orthogonal.js",
       "default": "./dist/orthogonal.js"
     },
     "./play": {
       "types": "./dist/play-entry.d.ts",
+      "import": "./dist/play-entry.js",
       "default": "./dist/play-entry.js"
     },
     "./draw": {
       "types": "./dist/draw-entry.d.ts",
+      "import": "./dist/draw-entry.js",
       "default": "./dist/draw-entry.js"
     },
     "./element": {
       "types": "./dist/element.d.ts",
+      "import": "./dist/element.js",
       "default": "./dist/element.js"
     },
     "./element/define": {
       "types": "./dist/element-define.d.ts",
+      "import": "./dist/element-define.js",
       "default": "./dist/element-define.js"
     },
     "./react": {
       "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
       "default": "./dist/react.js"
     }
   },
@@ -121,8 +128,8 @@
     "eslint": "^9.0.0",
     "typescript-eslint": "^8.0.0",
     "typescript": "^5.9.0",
-    "vitest": "^4.0.0",
-    "@playwright/test": "^1.58.0",
+    "vitest": "^5.0.0",
+    "@playwright/test": "^1.63.0",
     "@types/react": "^19.0.0",
     "react": "^19.0.0"
   },

package/src/family.test.js

@@ -15,7 +15,9 @@ const id = pkg.name.replace(/^@[^/]+\//, "");
 
 // The recorded hashes. The template's is the one that says every demo's header and footer, and every README's
 // list of the family, are the same text.
-const TEMPLATE = { version: "2026-10-05", sha256: "061b5ed89c345dccb6e029d5091dff0a5bbc4a9b57812fbcd0bd619038bdb7f1" };
+// The template of 2026-10-05 lists twenty-four packages, Karakuri and Houseki included. The family's list is swept again, in every
+// repository at once, when a package is added to it, and this hash is then the new one.
+const TEMPLATE = { version: "2026-10-05", sha256: "a2dc81808be980438bdef8b91f5c0bbff920a739bc50930cd4632cb017c8fa48" };
 const FILES = {
   "scripts/family-readme.mjs": "3c9d5b2cbf17a92d31bced98edac7f544616edb0dff90bf2d141722a9d4516c5",
   "scripts/release-notes.mjs": "efab0fb78ad05973a8885624c0d2ce3b458b55799c11eabaa5176603ce8cd1e9",
@@ -32,7 +34,7 @@ describe("the family template", () => {
   it("lists every package of the family, in order, each with its Japanese name and a line on it", () => {
     expect(FAMILY.map((one) => one.id)).toEqual([
       "korokoro", "kyuubu", "hitotsu", "toranpu", "tane", "narabe", "tenka", "kumimoji", "tsunagi", "jarajara",
-      "suido", "domino", "kotoba", "sugoroku", "kazu", "meikyuu", "hikidashi", "chizu", "bushu", "tobiishi", "jirai", "gunjin",
+      "suido", "domino", "kotoba", "sugoroku", "kazu", "meikyuu", "hikidashi", "chizu", "bushu", "tobiishi", "jirai", "gunjin", "karakuri", "houseki",
     ]);
     for (const one of FAMILY) {
       expect(one.name, one.id).toBe(one.id[0].toUpperCase() + one.id.slice(1));
@@ -75,13 +77,27 @@ describe("the README's family", () => {
   });
 });
 
+describe("the README's version pins", () => {
+  it("name this package's major version, never an older one: a CDN address says @2 once the package is 2.x", () => {
+    const major = pkg.version.split(".")[0];
+    const pins = read("README.md")
+      .split(`${pkg.name}@`)
+      .slice(1)
+      .map((rest) => /^\d+/.exec(rest)?.[0])
+      .filter((pin) => pin !== undefined);
+    for (const pin of pins) expect(pin, `${pkg.name}@${pin} in README.md`).toBe(major);
+  });
+});
+
 describe("the release notes", () => {
   it("are the changelog's section for the version, which the Release workflow puts on the GitHub release", () => {
     const log = "# Changelog\n\n## [Unreleased]\n\n## [1.2.0] - 2026-01-02\n\n### Added\n\n- A thing.\n\n## [1.1.0] - 2026-01-01\n\n- Older.\n\n[Unreleased]: https://example.test\n";
     expect(releaseNotes(log, "1.2.0")).toBe("### Added\n\n- A thing.");
     expect(releaseNotes(log, "1.1.0")).toBe("- Older.");
     expect(releaseNotes(log, "9.9.9")).toBeNull();
-    expect(releaseNotes(read("CHANGELOG.md"), pkg.version)?.length, `CHANGELOG.md has nothing under ## [${pkg.version}]`).toBeGreaterThan(40);
+    // Until a version is published its notes are under [Unreleased]; the release takes the heading with the version and the date.
+    const notes = releaseNotes(read("CHANGELOG.md"), pkg.version) ?? releaseNotes(read("CHANGELOG.md"), "Unreleased");
+    expect(notes?.length, `CHANGELOG.md has nothing under ## [${pkg.version}] or ## [Unreleased]`).toBeGreaterThan(40);
     const workflow = read(".github/workflows/release.yml");
     expect(workflow).toContain("scripts/release-notes.mjs");
     expect(workflow).not.toContain("See CHANGELOG.md.");
@@ -90,7 +106,8 @@ describe("the release notes", () => {
   it("come from a changelog in Keep a Changelog form: an Unreleased heading, then each version in brackets with its date", () => {
     const log = read("CHANGELOG.md");
     expect(log).toContain("\n## [Unreleased]\n");
-    expect(log).toMatch(/^## \[\d+\.\d+\.\d+\] - \d{4}-\d{2}-\d{2}$/m);
+    // Before the first release there is no versioned heading yet, only Unreleased.
+    if (/^## \[\d/m.test(log)) expect(log).toMatch(/^## \[\d+\.\d+\.\d+\] - \d{4}-\d{2}-\d{2}$/m);
     expect(log).not.toMatch(/^## \d/m);
   });
 });

package/src/index.ts

@@ -8,7 +8,7 @@ export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
 /** Package version, kept in step with the release metadata. */
-export const VERSION = "0.4.0";
+export const VERSION = "0.4.1";
 
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 

package/src/readme.test.js

@@ -0,0 +1,34 @@
+// readme.test.js: the README has the sections every package of the family has, in the family's order, each with something in it.
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const readme = readFileSync("README.md", "utf8").replace(/\r\n/g, "\n");
+const HOUSE = [
+  "In 30 seconds", "Who it is for", "Features", "Use it in your project", "API", "Theming", "Limits", "Browser support",
+  "Languages", "Roadmap", "Architecture", "The name", "Where it comes from", "Development", "Contributing", "Changes", "Licence",
+];
+
+describe("the README's shape", () => {
+  it("has the family's sections, in the family's order, each with something in it", () => {
+    const headings = [...readme.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
+    let from = 0;
+    for (const heading of HOUSE) {
+      const at = headings.indexOf(heading, from);
+      expect(at, `README.md has no "## ${heading}" after the section before it`).toBeGreaterThanOrEqual(from);
+      from = at + 1;
+      const start = readme.indexOf(`\n## ${heading}\n`) + 1;
+      const next = readme.indexOf("\n## ", start + 4);
+      const body = readme.slice(start + heading.length + 4, next < 0 ? undefined : next).trim();
+      expect(body.length, `"## ${heading}" is empty`).toBeGreaterThan(20);
+    }
+  });
+
+  it("puts the family under \"Where it comes from\", one level down", () => {
+    const from = readme.indexOf("\n## Where it comes from\n");
+    const family = readme.indexOf("\n### The family\n");
+    const next = readme.indexOf("\n## Development\n");
+    expect(from).toBeGreaterThan(0);
+    expect(family).toBeGreaterThan(from);
+    expect(family).toBeLessThan(next);
+  });
+});