@johnmorrisdotca/jirai 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -6,6 +6,48 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-06
+
+Nothing that was exported has changed. The README is the family's one layout, in full.
+
+### 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 rule set and outline (square, orthogonal, hexagonal, wraparound, a heart, a star), of the explained hint and of the slate board with flowers on a phone, an Examples section of twelve examples that run, examples for React, Vue, Svelte and Angular, tables of the entry points, the calls to learn first and every theme property, and an Accessibility section.
+- `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) in `pnpm check`; `pnpm test:package` fails if a picture or anything under `docs/` is in the packed package.
+
+### Fixed
+
+- The README told readers to import `DEFAULT_SETTINGS` from `@johnmorrisdotca/jirai/play`, which does not export it (it is in the main entry), and showed `opening="clear"` on `<jirai-board>`, which does not read an `opening` attribute (the tag reads `width`, `height`, `mines`, `seed`, `grid`, `shape`, `no-guess`, `material`, `pieces` and `lang`). Both examples are corrected, and every TypeScript example is now type-checked and run.
+
+### Changed
+
+- `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, and the presentation check looks for the hero pictures there instead.
+- Repository only: the package and everything it exports are unchanged. `CONTRIBUTING.md` is the family's one text with a section of its own for Jirai, 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 `Jirai · pitch`, like the rest of the family's.
+- The demo's own stylesheet is `demo/jirai.css`, named for the package like the family's.
+- The demo is built into `site/`, where the Pages workflow and every other package look for it.
+
+### Fixed
+
+- The API reference page wraps a long entry path instead of running about 2 px wider than a 360 px screen. Nothing the package exports has changed.
+
+## [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

@@ -13,10 +13,24 @@ Minesweeper across four-neighbour, eight-neighbour, hexagonal and wraparound gri
 
 <p align="center"><a href="https://johnmorrisdotca.github.io/jirai/"><strong>Play Jirai →</strong></a> · <a href="https://johnmorrisdotca.github.io/jirai/api.html">API reference</a></p>
 
-<p align="center">
-  <img src="docs/desktop.jpg" alt="Jirai on a desktop: the Minesweeper board and its shape, grid, size, mine-count and material controls in the shared family demo style" width="680">
-  <img src="docs/phone.jpg" alt="Jirai on a phone: a square minefield with touch controls and clear number clues" width="220">
-</p>
+<table align="center">
+<tr>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hero-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the page header with the language chooser, the API reference link, five cloth patches and the Help switch, the Your field choices (board, shape, level, width, height, mines, no-guess, first opening, material, markers and seed), and the Hexagonal field on green felt: a nine by nine board of hexagons on a wooden tray with the opened cells showing blue and green number clues, the counters Mines left 10, Time 0:00 and Moves 1, and the Start over, Open, Hint and Just the board buttons" width="600">
+</picture>
+<br><em>The demo on a desk: a hexagonal field, opened at its middle.</em>
+</td>
+<td align="center" valign="top">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hero-phone-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: an orthogonal nine by nine field with opened cells and number clues, the status line 数字を手がかりに、安全なマスをすべて開けましょう, the buttons やり直す, 開く, ヒント and 盤だけ, and the start of the rules under it" width="190">
+</picture>
+<br><em>On a phone, in Japanese, in the device's light or dark.</em>
+</td>
+</tr>
+</table>
 
 Jirai is a Minesweeper rules engine and player for TypeScript and JavaScript. The core is plain functions; drawing, browser controls, a custom element and an optional React wrapper are separate imports. The package has no runtime dependencies and needs Node 22 or a modern browser.
 
@@ -39,12 +53,18 @@ For a dedicated four-neighbour variant, its entry fixes the topology for you:
 ```ts
 import { makeOrthogonalBoard, newOrthogonalGame } from "@johnmorrisdotca/jirai/orthogonal";
 
-const settings = { width: 9, height: 9, mines: 10, noGuess: true, opening: "clear", seed: 42 };
+const settings = { width: 9, height: 9, mines: 10, noGuess: true, opening: "clear" as const, seed: 42 };
 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,12 +76,96 @@ 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
+### What's in it
+
+Each picture is the real player, drawn by the package and taken from [the demo](https://johnmorrisdotca.github.io/jirai/) with `pnpm screenshots:readme`, in light and dark. Every field is the same seed, opened at the same cell, so the pictures are the same each run.
+
+<table>
+<tr>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/square-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/square-desk-light.webp" alt="A nine by nine square field on a wooden tray on a desk, opened at its middle cell, with blue, green and red number clues, the counters Mines left 10, Time 0:00 and Moves 1, and the Start over, Open, Hint and Just the board buttons" width="360">
+</picture>
+<br><em><strong>Square.</strong> A number counts the eight cells around it.</em>
+</td>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/orthogonal-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/orthogonal-desk-light.webp" alt="A nine by nine orthogonal field on a desk, opened at its middle cell: the opened patch is larger and the clues are fewer, the title Orthogonal field and the counters Mines left 10" width="360">
+</picture>
+<br><em><strong>Orthogonal.</strong> A number counts only the four cells that share an edge.</em>
+</td>
+</tr>
+<tr>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hex-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hex-desk-light.webp" alt="A nine by nine hexagonal field on a desk: rows of hexagons offset along a slanting parallelogram, opened at its middle with blue and green clues, titled Hexagonal field" width="360">
+</picture>
+<br><em><strong>Hexagonal.</strong> A number counts the six cells around a hexagon.</em>
+</td>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/wraparound-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/wraparound-desk-light.webp" alt="A nine by nine wraparound field on a desk, opened at its middle, with clues along its edges that count cells on the opposite edge, titled Wraparound field" width="360">
+</picture>
+<br><em><strong>Wraparound.</strong> Opposite edges join, so a clue on an edge counts across it.</em>
+</td>
+</tr>
+<tr>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/heart-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/heart-desk-light.webp" alt="A heart-shaped sixteen by sixteen field on a desk, made of square cells with the cut-out corners missing, opened in its middle, with many number clues and the counters Mines left 27" width="360">
+</picture>
+<br><em><strong>A heart.</strong> Outlines cut cells out of the field: a heart, a star or a hexagon, with the level's share of mines.</em>
+</td>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/star-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/star-desk-light.webp" alt="A star-shaped sixteen by sixteen orthogonal field on a desk, a five-pointed star of square cells with its points cut out of the rectangle, opened in its middle, with the counters Mines left 14" width="360">
+</picture>
+<br><em><strong>A star.</strong> Shaped boards work on every rule; here the four-neighbour rule.</em>
+</td>
+</tr>
+<tr>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hint-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/hint-desk-light.webp" alt="A nine by nine square field on a desk after the Hint button: one cell is outlined in pale green, and the status line says This cell is safe. The neighbouring count settles it." width="360">
+</picture>
+<br><em><strong>The explained hint.</strong> The cell is outlined and the line says why it is certain.</em>
+</td>
+<td align="center" valign="top" width="50%">
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/slate-flowers-phone-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/jirai/main/docs/images/slate-flowers-phone-light.webp" alt="A nine by nine field on a phone in the slate material with flowers as markers: dark grey cells with white numbers, three flowers marking covered cells, the counters Mines left 8, Time 0:00 and Moves 3, the status line, the buttons Start over, Open, Hint and Just the board, and the line of help under them" width="240">
+</picture>
+<br><em><strong>On a phone.</strong> Slate with flowers; a tap opens, and a long press or the Open button marks.</em>
+</td>
+</tr>
+</table>
+
+## Use it in your project
+
+### Install
+
+```sh
+npm install @johnmorrisdotca/jirai
+pnpm add @johnmorrisdotca/jirai
+yarn add @johnmorrisdotca/jirai
+```
+
+It is ES modules only, with its types included, and needs Node 22 or later outside a browser. A page with no bundler loads the tag from a CDN (`@0` is the major version).
+
+### A player from a script
 
 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.
 
-```ts
-import { DEFAULT_SETTINGS, mountJirai } from "@johnmorrisdotca/jirai/play";
+```ts no-run
+import { DEFAULT_SETTINGS } from "@johnmorrisdotca/jirai";
+import { mountJirai } from "@johnmorrisdotca/jirai/play";
 
 const board = mountJirai(document.querySelector<HTMLElement>("#game")!, {
   settings: { ...DEFAULT_SETTINGS, grid: "orthogonal", seed: 7 },
@@ -79,6 +183,8 @@ board.destroy();
 
 The handle also provides `game()`, `progress()`, `play(cell, mark?)`, `hint()`, and `load(settings, progress?)`. Set `controls: false` when your page supplies its own controls and status. Change options with `set`; call `destroy` when the host is removed.
 
+### The tag
+
 Use the custom element without a mount call:
 
 ```html
@@ -86,12 +192,313 @@ Use the custom element without a mount call:
   import "@johnmorrisdotca/jirai/element/define";
 </script>
 <jirai-board width="9" height="9" mines="10" seed="42"
-  grid="orthogonal" opening="clear" no-guess="true"
+  grid="orthogonal" no-guess="true"
   material="wood" pieces="stones" lang="ja"></jirai-board>
 ```
 
+The tag reads `width`, `height`, `mines`, `seed`, `grid`, `shape`, `no-guess`, `material`, `pieces` and `lang`, and mounts again when one changes; the first opening is the default (`clear`), and `jirai-error` is the event it fires when a field cannot be dealt.
+
+### The React component
+
 The optional React entry exports `JiraiBoard` from `@johnmorrisdotca/jirai/react`; React is an optional peer dependency. Its options are read when mounted. Use a new React `key` to start with a different settings object.
 
+### In a framework
+
+Two ways: the `<jirai-board>` tag, which every framework can carry, and `JiraiBoard`, the React component. The player deals a board in a module worker, so the page must be served over HTTP.
+
+#### React
+
+```jsx
+import { JiraiBoard } from "@johnmorrisdotca/jirai/react";
+
+export function Game({ seed }) {
+  // The options are read when it mounts: a new key starts it with different settings.
+  return <JiraiBoard key={seed} settings={{ grid: "orthogonal", width: 9, height: 9, mines: 10, seed }} material="wood" onFinish={(game) => console.log(game.status)} />;
+}
+```
+
+#### Vue
+
+Vue needs to be told that `jirai-board` is a custom element, a compiler option.
+
+```vue
+<script setup>
+import "@johnmorrisdotca/jirai/element/define";
+defineProps({ seed: Number });
+</script>
+
+<template>
+  <jirai-board width="9" height="9" mines="10" :seed="seed" grid="hex" material="slate" pieces="flowers"></jirai-board>
+</template>
+```
+
+```js no-check
+// vite.config.js
+import vue from "@vitejs/plugin-vue";
+
+export default { plugins: [vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === "jirai-board" } } })] };
+```
+
+#### Svelte
+
+```svelte
+<script>
+  import "@johnmorrisdotca/jirai/element/define";
+  export let seed = 42;
+</script>
+
+<jirai-board width="16" height="16" mines="40" {seed} grid="square" lang="ja"></jirai-board>
+```
+
+#### Angular
+
+```ts no-check
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+import "@johnmorrisdotca/jirai/element/define";
+
+@Component({
+  selector: "app-game",
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<jirai-board width="9" height="9" mines="10" seed="42" grid="orthogonal"></jirai-board>`,
+})
+export class GameComponent {}
+```
+
+## Examples
+
+Each example is a whole recipe: copy it and it works. The ones in TypeScript are run in CI against the built package (`pnpm test:readme`), so none of them is a guess, and the output shown is what they print.
+
+### A game on a page with no script of your own
+
+Save this as a file, serve it over HTTP (the player deals in a module worker, which a `file:` page cannot load) and open it: a hexagonal field, dealt from a seed that is proved to need no guess.
+
+```html
+<!doctype html>
+<meta charset="utf-8">
+<title>Jirai</title>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@johnmorrisdotca/jirai@0/dist/element-define.js"></script>
+<jirai-board width="12" height="12" mines="22" seed="2026" grid="hex" material="wood" pieces="flowers"></jirai-board>
+```
+
+### The first move deals the board
+
+`newGame` makes a ready game with no mines in it. The first reveal deals the seeded field, with that cell and, by default, its neighbours safe, so nobody loses on the first move.
+
+```ts
+import { DEFAULT_SETTINGS, newGame, play } from "@johnmorrisdotca/jirai";
+
+let game = newGame({ ...DEFAULT_SETTINGS, width: 9, height: 9, mines: 10, seed: 42 });
+console.log(game.status, game.board);                           // ready, nothing dealt yet
+game = play(game, { kind: "reveal", cell: 40 });
+console.log(game.status, "dealt around cell", game.board!.first, "with", game.board!.mines.filter(Boolean).length, "mines");
+console.log(play(game, { kind: "reveal", cell: 999 }) === game);   // a move that cannot be made returns the same game
+```
+
+```text
+ready null
+playing dealt around cell 40 with 10 mines
+true
+```
+
+### A hint that proves its answer
+
+`hintFor` reads only what is opened, never the hidden mines, and says which cells are certain, and from which clue. Flags are marks and never evidence.
+
+```ts
+import { DEFAULT_SETTINGS, hintFor, newGame, play, visibleGame } from "@johnmorrisdotca/jirai";
+
+let game = newGame({ ...DEFAULT_SETTINGS, seed: 42 });
+game = play(game, { kind: "reveal", cell: 40 });
+const hint = hintFor(visibleGame(game))!;
+console.log(hint);
+```
+
+```text
+{
+  safe: [ 5 ],
+  mines: [],
+  reason: 'count',
+  sources: [ 6 ],
+  contradiction: false
+}
+```
+
+### Solve a field with nothing but hints
+
+A no-guess field can be finished by deduction alone, so a bot needs no luck: ask for a hint, open what is safe, flag what is a mine, and repeat. A medium field and a hex star at the hard level are both cleared.
+
+```ts
+import { DEFAULT_SETTINGS, gameProgress, hintFor, levelSettings, newGame, play, visibleGame } from "@johnmorrisdotca/jirai";
+
+for (const [label, extra] of [["square", {}], ["hex star", { grid: "hex", shape: "star" }]] as const) {
+  const level = label === "square" ? "medium" : "hard";
+  const settings = { ...DEFAULT_SETTINGS, ...extra, ...levelSettings(level, extra), seed: 3, noGuess: true };
+  let game = play(newGame(settings), { kind: "reveal", cell: Math.floor(settings.height / 2) * settings.width + Math.floor(settings.width / 2) });
+  let hints = 0;
+  while (game.status === "playing") {
+    const hint = hintFor(visibleGame(game));
+    if (hint === null || (hint.safe.length === 0 && hint.mines.length === 0)) break;
+    hints += 1;
+    for (const cell of hint.safe) game = play(game, { kind: "reveal", cell });
+    for (const cell of hint.mines) if (game.marks[cell] !== "flag") game = play(game, { kind: "mark", cell });
+  }
+  console.log(label, game.status, `after ${hints} hints and ${game.moves.length} moves; saved in ${gameProgress(game).length} characters`);
+}
+```
+
+```text
+square won after 51 hints and 77 moves; saved in 2334 characters
+hex star won after 34 hints and 50 moves; saved in 1601 characters
+```
+
+### Levels, outlines and huge fields
+
+Four levels step up in size and mine share, on every rule and outline; a shaped board keeps the level's share of mines over the cells it has left. `hugeSettings` is the same on a field of four times the area.
+
+```ts
+import { hugeSettings, levelSettings } from "@johnmorrisdotca/jirai";
+
+console.log(levelSettings("hard"));
+console.log(levelSettings("extra-hard", { grid: "hex", shape: "star" }));
+console.log(hugeSettings("hard"));
+```
+
+```text
+{ width: 30, height: 16, mines: 99 }
+{ width: 40, height: 24, mines: 85 }
+{ width: 32, height: 32, mines: 211 }
+```
+
+### Deal a field and check it
+
+`makeBoard` deals at a first cell; with `noGuess` it returns only a board its solver can finish. `measureBoard` grades it with the same deductions the hints use, so levels can be put in order.
+
+```ts
+import { DEFAULT_SETTINGS, isSolvable, makeBoard, measureBoard } from "@johnmorrisdotca/jirai";
+
+const board = makeBoard({ ...DEFAULT_SETTINGS, noGuess: true, seed: 7 }, 40);
+console.log(isSolvable(board), board.mines.filter(Boolean).length, "mines; dealt on attempt", board.attempt);
+const grade = measureBoard(board);
+console.log(`score ${grade.score}, depth ${grade.depth}, solvable ${grade.solvable}`);
+```
+
+```text
+true 10 mines; dealt on attempt 0
+score 27.2, depth 10, solvable true
+```
+
+### Who touches whom
+
+The rule sets differ only in which cells a number counts. `neighbours` says, for any cell, which cells those are.
+
+```ts
+import { DEFAULT_SETTINGS, neighbours } from "@johnmorrisdotca/jirai";
+
+for (const grid of ["square", "orthogonal", "hex", "wrap"] as const) {
+  console.log(grid.padEnd(10), "cell 40:", neighbours({ ...DEFAULT_SETTINGS, grid }, 40).length, "neighbours; cell 0:", neighbours({ ...DEFAULT_SETTINGS, grid }, 0).length);
+}
+```
+
+```text
+square     cell 40: 8 neighbours; cell 0: 3 neighbours
+orthogonal cell 40: 4 neighbours; cell 0: 2 neighbours
+hex        cell 40: 6 neighbours; cell 0: 2 neighbours
+wrap       cell 40: 8 neighbours; cell 0: 8 neighbours
+```
+
+### Keep a game and read it back
+
+A saved game is the settings and the moves, not an answer anybody could edit. Reading it replays every move under the rules, so a record that is not a game is `null`.
+
+```ts
+import { DEFAULT_SETTINGS, gameFromProgress, gameProgress, newGame, play } from "@johnmorrisdotca/jirai";
+
+let game = newGame({ ...DEFAULT_SETTINGS, seed: 42 });
+game = play(game, { kind: "reveal", cell: 40 });
+const saved = gameProgress(game);
+console.log(saved);
+console.log(gameFromProgress(saved)?.status, gameFromProgress("not a game"), gameFromProgress(saved.slice(0, 60)));
+```
+
+```text
+{"version":1,"settings":{"width":9,"height":9,"mines":10,"grid":"square","noGuess":true,"opening":"clear","seed":42},"moves":[{"kind":"reveal","cell":40}],"helped":false}
+playing null null
+```
+
+### Today's field
+
+`dailySeed` is the same seed for everyone on a date (UTC), per rule set, so a site can offer a daily field with nothing stored.
+
+```ts
+import { dailySeed } from "@johnmorrisdotca/jirai";
+
+console.log(dailySeed("2026-10-01"), dailySeed("2026-10-01", "hex"), dailySeed("2026-10-01") === dailySeed("2026-10-01"));
+```
+
+```text
+1293497838 968579362 true
+```
+
+### Draw it yourself
+
+`boardModel` is the board as row-major labelled cells with no DOM, for a page that draws its own. Each cell says where it is, what it reads aloud and what state it is in.
+
+```ts
+import { DEFAULT_SETTINGS, newGame, play } from "@johnmorrisdotca/jirai";
+import { boardModel } from "@johnmorrisdotca/jirai/draw";
+
+const game = play(newGame({ ...DEFAULT_SETTINGS, seed: 42 }), { kind: "reveal", cell: 40 });
+const model = boardModel(game, {});
+console.log(model.width, "by", model.height, "=", model.cells.length, "cells");
+console.log(model.cells[40]);
+```
+
+```text
+9 by 9 = 81 cells
+{
+  cell: 40,
+  x: 4,
+  y: 4,
+  width: 1,
+  height: 1,
+  label: '5, 5: empty',
+  text: '',
+  kind: 'open',
+  hint: false
+}
+```
+
+### A player you steer from code
+
+```ts no-run
+import { DEFAULT_SETTINGS } from "@johnmorrisdotca/jirai";
+import { mountJirai } from "@johnmorrisdotca/jirai/play";
+
+const board = mountJirai(document.querySelector<HTMLElement>("#game")!, {
+  settings: { ...DEFAULT_SETTINGS, grid: "wrap", seed: 7 },
+  material: "slate",
+  pieces: "flowers",
+  language: "ja",
+  onChange: () => localStorage.setItem("jirai", board.progress()),     // keep the game as it is played
+  onFinish: (game) => console.log(game.status, game.helped),           // won or lost, and whether a hint was used
+});
+const kept = localStorage.getItem("jirai");
+if (kept) board.load({ ...DEFAULT_SETTINGS, grid: "wrap", seed: 7 }, kept);   // play a kept game back
+```
+
+### A look of your own
+
+The player is themed by custom properties, and `material` and `pieces` change how the cells and markers look, never the rules.
+
+```css
+jirai-board .jr-root[data-material] {   /* as specific as the material's own rule, so that it wins */
+  --jr-cover: #cfd8dc;
+  --jr-open: #eceff1;
+  --jr-ink: #263238;
+}
+```
+
 ## Rules and settings
 
 | Setting | Values and limits |
@@ -153,13 +560,52 @@ 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.
+
+### Entry points
+
+| Import | What it holds |
+| --- | --- |
+| `@johnmorrisdotca/jirai` | The rules engine, grid and shape utilities, levels, the dealer and solver, hints and saved progress |
+| `@johnmorrisdotca/jirai/orthogonal` | The explicit four-neighbour game, board, hint and version-2 save helpers |
+| `@johnmorrisdotca/jirai/draw` | `boardModel`, `JIRAI_STYLE` and the drawing model types |
+| `@johnmorrisdotca/jirai/play` | `mountJirai` and the player's types and options |
+| `@johnmorrisdotca/jirai/element` | `JiraiElement` and `defineJirai`, which registers nothing until called |
+| `@johnmorrisdotca/jirai/element/define` | Defines `<jirai-board>` by being imported |
+| `@johnmorrisdotca/jirai/react` | The optional `JiraiBoard` component; React is an optional peer |
+
+### The calls to learn first
+
+| Call | What it does |
+| --- | --- |
+| `newGame(settings)` and `play(game, move)` | A ready game, and the game after a move; a move that cannot be made returns the same game |
+| `visibleGame(game)` and `hintFor(visible)` | What a player can see, and the cells that are certain from it |
+| `makeBoard(settings, first, options)` and `isSolvable(board)` | A seeded field dealt at a first cell, and whether deduction can finish it |
+| `levelSettings(level, options)` and `hugeSettings(level, options)` | The size and mines of a level, on any rule and outline |
+| `gameProgress(game)` and `gameFromProgress(text)` | A game as text, and back; `null` for a record that is not a game |
+| `boardModel(game, options)` | The board as labelled cells, for a page that draws its own |
+| `mountJirai(element, options)` | The player |
+
+## 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
+| Property | What it colours | Ivory | Wood | Slate |
+| --- | --- | --- | --- | --- |
+| `--jr-ground` | the tray round the board | `#a98954` | `#ae804a` | `#252e32` |
+| `--jr-cover` | a covered cell | `#fbf8f1` | `#e0bb7e` | `#455359` |
+| `--jr-open` | an opened cell | `#efe8d8` | `#c69d63` | `#303c41` |
+| `--jr-line` | the lines between cells | `#cfc6b2` | `#936e40` | `#62747a` |
+| `--jr-ink` | the digits and marks | `#1f2320` | `#352c20` | `#f3f0e5` |
+| `--jr-accent` | the cell a hint outlines | `#2f7a4f` | `#2f7a4f` | `#b7d298` |
+
+They are set on `.jr-root`, and the material sets them again with `.jr-root[data-material=…]`, so a host rule must be as specific (`.jr-root[data-material]`) to win. The buttons take `--jr-ui-ink`, `--jr-ui-line` and `--jr-ui-surface`, which follow the page's `--ink`, `--rule` and `--surface` when it has them, as the family's demos do.
+
+## 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 +628,81 @@ 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.
 
+## Accessibility
+
+- **Every cell is a button with a name.** A screen reader hears the cell's place and state ("5, 5: empty", "3, 2: flag", the number a clue shows), and the board is a labelled group, with `aria-busy` while a field is being dealt. `boardModel` gives the same label for a board you draw yourself.
+- **The status line is spoken.** What to do next, what a hint proved and how the game ended is a `role="status"` line, so a change is announced without moving focus. A hint says which cell is certain and why, so it teaches the deduction as well as giving the answer.
+- **The keyboard plays the whole game.** The board has one tab stop and the arrow keys move between cells; Enter opens, F or Space marks, and an open number whose flags match clears its neighbours. The buttons (Start over, Open or Mark, Hint, Just the board) are native buttons.
+- **Touch and pointer.** Tap opens, a long press or right-click marks, and a Mark button switches a touch screen between opening and marking (`aria-pressed`), so nothing needs a long press. The buttons are at least 44 pixels high.
+- **A number is not told by colour alone.** The clue is a digit, in a colour per value for those who see it; flags, stones and flowers are different shapes, not different colours, and every cell state has its name in the label.
+- **Reduced motion.** The only transition, a cell's background, is on only for `prefers-reduced-motion: no-preference`.
+- **Not yet.** The colour pairs of the three materials have not been measured against WCAG contrast ratios. A very wide field (30 and 40 columns) scrolls sideways inside its box on a narrow screen. The Japanese has not been read by a native reader (see [Languages](#languages)).
+
+## 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
-
-```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/
-```
+## Where it comes from, and where it is used
 
-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.
+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.
 
-## Licence
+### Used by
 
-[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.
+Using Jirai in something? Open an *Add my project* issue and we will add you.
 
-## 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 +727,34 @@ 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
 
-See [Contributing](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).
+```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 site/
+pnpm test:readme    # run every example in this README against the built package
+pnpm screenshots:readme  # take the README's pictures from the built demo, in light and dark
+```
+
+The standalone game is `site/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
+
+Every release is written up in [CHANGELOG.md](./CHANGELOG.md). The latest release, 0.4.2, adds no code: it is this README in full, with pictures of every rule set and outline, examples that are run on every change, examples for React, Vue, Svelte and Angular, and an Accessibility section.
+
+## 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.2";
 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.2";
 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.2",
+  "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"
     }
   },
@@ -106,7 +113,8 @@
     "test:package": "pnpm build && node scripts/check-package.mjs",
     "prepublishOnly": "pnpm check && pnpm test:package",
     "check:presentation": "node scripts/check-presentation.mjs",
-    "pictures": "pnpm site && node scripts/readme-pictures.mjs"
+    "screenshots:readme": "pnpm site && node scripts/readme-pictures.mjs",
+    "test:readme": "pnpm build && node scripts/check-readme-examples.mjs"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -121,8 +129,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,13 +15,19 @@ 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",
   "scripts/community/SECURITY.md": "ff6f650be7789396233671d2558439736efe7f96a1d1d39115dd5cf94d29275c",
   "scripts/community/CODE_OF_CONDUCT.md": "34da1f56f004ce8f7f95d4449b64d2ecb5827dd9f0d4eea1da351a20713ebe70",
+  "scripts/community/CONTRIBUTING.md": "3225201be4f66531c27e849f0bb219f8c7274e5815b726a93565bccadbc6a43c",
 };
+// The Pages workflow is one text in every package. A package that also builds a documentation site adds the one step that
+// builds it, and that line is left out before the text is compared.
+const PAGES_SHA256 = "f45c33dd0403551588b8b00882cfd0c1d953d2095e558ffab0f7451b8cdb6ef6";
 
 describe("the family template", () => {
   it("is the one file, byte for byte, in every package", () => {
@@ -32,7 +38,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));
@@ -49,13 +55,41 @@ describe("the family template", () => {
 });
 
 describe("the files every package shares", () => {
-  it("are copied unchanged: the README writer, the release notes, and the family's SECURITY.md and CODE_OF_CONDUCT.md", () => {
+  it("are copied unchanged: the README writer, the release notes, and the family's SECURITY.md, CODE_OF_CONDUCT.md and CONTRIBUTING.md", () => {
     for (const [path, hash] of Object.entries(FILES)) expect(sha(path), path).toBe(hash);
   });
 
   it("SECURITY.md and CODE_OF_CONDUCT.md are the master text of github.com/johnmorrisdotca/.github, which scripts/community keeps a copy of", () => {
     for (const file of ["SECURITY.md", "CODE_OF_CONDUCT.md"]) expect(read(file), file).toBe(read(`scripts/community/${file}`));
   });
+
+  it("CONTRIBUTING.md is the master text of github.com/johnmorrisdotca/.github, which scripts/community keeps a copy of, and then what is particular to this package", () => {
+    const master = read("scripts/community/CONTRIBUTING.md");
+    const own = read("CONTRIBUTING.md");
+    const name = FAMILY.find((one) => one.id === id).name;
+    expect(own.startsWith(`${master}\n## Particular to ${name}\n`), "CONTRIBUTING.md is the master text, a blank line and '## Particular to <Name>'").toBe(true);
+    expect(own.split("\n## Particular to ").length - 1).toBe(1);
+  });
+});
+
+describe("the workflows", () => {
+  const ci = read(".github/workflows/ci.yml");
+
+  it("ci.yml has the family's three jobs, check, demo and package, and runs `pnpm check` rather than its parts, with jobs of the package's own after them", () => {
+    expect(ci).toMatch(/^name: CI$/m);
+    const jobs = [...ci.slice(ci.indexOf("\njobs:\n")).matchAll(/^ {2}([a-z][a-z-]*):$/gm)].map((match) => match[1]);
+    expect(jobs.slice(0, 3)).toEqual(["check", "demo", "package"]);
+    expect(ci).toContain("      - run: pnpm check\n");
+    expect(ci).not.toMatch(/- run: pnpm (lint|typecheck|test)$/m);
+    expect(ci).toContain("os: [ubuntu-latest, macos-latest, windows-latest]");
+    expect(ci).toContain("run: pnpm test:package");
+  });
+
+  it("pages.yml is the same text in every package, named Pages, apart from one step that builds a documentation site", () => {
+    const pages = read(".github/workflows/pages.yml").replace("\n      - run: pnpm docs:site\n", "\n");
+    expect(pages).toMatch(/^name: Pages$/m);
+    expect(createHash("sha256").update(pages).digest("hex")).toBe(PAGES_SHA256);
+  });
 });
 
 describe("the README's family", () => {
@@ -75,13 +109,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 +138,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.2";
 
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 

package/src/readme.test.js

@@ -0,0 +1,70 @@
+// The README, held to the family's README standard (johnmorrisdotca/.github, README-STANDARD.md): its sections, its examples'
+// languages, its pictures and their files, its tables and its tone. The rules are in scripts/readme-lint.mjs, the same file in
+// every package. A fault names the line and what to do.
+import { describe, expect, it } from "vitest";
+
+import { lintReadme, readInputs, REQUIRED_SECTIONS } from "../scripts/readme-lint.mjs";
+
+describe("the README keeps the family's standard", () => {
+  it("has no fault", () => {
+    expect(lintReadme(readInputs("."))).toEqual([]);
+  });
+
+  it("lists the sections in the order the standard gives", () => {
+    expect(REQUIRED_SECTIONS.map(([name]) => name)).toEqual([
+      "In 30 seconds", "Who it is for", "Features", "Use it in your project", "Examples", "API", "Theming", "Limits", "Accessibility",
+      "Browser support", "Languages", "Roadmap", "Architecture", "The name", "Where it comes from, and where it is used", "Development",
+      "Contributing", "Changes", "Licence",
+    ]);
+  });
+});
+
+describe("the standard's checks catch what they are for", () => {
+  const pkg = { name: "@johnmorrisdotca/sample", version: "2.1.0", files: ["dist", "README.md"] };
+  const raw = "https://raw.githubusercontent.com/johnmorrisdotca/sample/main/docs/images/";
+  const ok = (name) => ({ file: name, bytes: 1000 });
+  const faultsFor = (readme, pictures = []) => lintReadme({ readme, pkg, pictures, minSubjects: 0 });
+
+  it("refuses a fenced block with no language, and a language that is not listed", () => {
+    expect(faultsFor("# T\n\n```\nx\n```\n\n```pascal\nx\n```\n").join("\n")).toMatch(/no language[\s\S]*pascal/);
+  });
+
+  it("refuses a picture that is not this repository's docs/images, has no alt text, or has no dark twin", () => {
+    const readme = `# T\n\n<picture><img src="docs/a.webp" alt="x" width="1"></picture>\n\n<picture><source media="(prefers-color-scheme: dark)" srcset="${raw}z-desk-dark.webp"><img src="${raw}z-desk-light.webp" alt="" width="1"></picture>\n`;
+    const faults = faultsFor(readme, [ok("z-desk-light.webp")]).join("\n");
+    expect(faults).toMatch(/not https:\/\/raw\.githubusercontent\.com\/johnmorrisdotca\/sample\/main\/docs\/images\//);
+    expect(faults).toMatch(/no alt text/);
+    expect(faults).toMatch(/has no dark twin/);
+    expect(faults).toMatch(/docs\/images\/z-desk-dark\.webp does not exist/);
+  });
+
+  it("refuses a picture over its budget, an unused file and a badly named one", () => {
+    const faults = faultsFor("# T\n", [{ file: "big-desk-light.webp", bytes: 300 * 1024 }, { file: "big-desk-dark.webp", bytes: 1000 }, { file: "photo.jpg", bytes: 10 }]).join("\n");
+    expect(faults).toMatch(/big-desk-light\.webp is 300 KB; the budget for it is 200 KB/);
+    expect(faults).toMatch(/big-desk-dark\.webp is not used/);
+    expect(faults).toMatch(/photo\.jpg is not named/);
+  });
+
+  it("refuses marketing words and exclamation marks in prose but not in code", () => {
+    const faults = faultsFor("# T\n\nA powerful, seamless library. It works!\n\n```ts\nconst powerful = !x; // magic!\n```\n").join("\n");
+    expect(faults).toMatch(/"powerful"/);
+    expect(faults).toMatch(/"seamless"/);
+    expect(faults).toMatch(/exclamation mark/);
+    expect(faults).not.toMatch(/"magic"/);
+  });
+
+  it("refuses a table row of the wrong width, a skipped heading level and a stale version pin", () => {
+    const faults = faultsFor("# T\n\n| a | b |\n| - | - |\n| 1 |\n\n## A\n\n#### Skips\n\nUse `@johnmorrisdotca/sample@1` from the CDN.\n").join("\n");
+    expect(faults).toMatch(/1 cells where its header has 2/);
+    expect(faults).toMatch(/skips a heading level/);
+    expect(faults).toMatch(/@johnmorrisdotca\/sample@1; the package is at 2\.1\.0, so the pin is @2/);
+  });
+
+  it("refuses a README longer than npm will show", () => {
+    expect(faultsFor(`# T\n\n${"word ".repeat(13_000)}\n`).join("\n")).toMatch(/npm shows only the first 65,536/);
+  });
+
+  it("refuses a package whose files ship the pictures", () => {
+    expect(lintReadme({ readme: "# T\n", pkg: { ...pkg, files: ["dist", "docs"] }, pictures: [], minSubjects: 0 }).join("\n")).toMatch(/"files" lists docs/);
+  });
+});