@johnmorrisdotca/houseki 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,10 +1,55 @@
 # Changelog
 
-## 0.1.0
-
-- Add original Falling Triplets, Colour Chains, Stone Collapse and Gem Swap engines with immutable state, seeded play, validated settings and canonical saves.
-- Include 300 graded challenges and three bilingual lessons per game.
-- Provide family-style keyboard, keypad and touch demos, configurable boards, stored tools, goal progress and shared animation preferences.
-- Add optional Black Hole powers, Shizen magnetic stones and bounded rebound, and optional Arashi jumble/lightning schedules.
-- Include an experimental Magnetic Blocks engine with bonded squares, magnetic floor schedules, a Floor Switch and impact drops.
-- Publish typed entry points, a generated API reference, MIT license and reproducible package checks.
+All notable changes to this package are written here, newest first, in the form of [Keep a Changelog](https://keepachangelog.com), and this package follows [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-06
+
+### Added
+
+- Three dedicated fifty-level campaigns: Magnetic Blocks, Shizen and Arashi, bringing the package to 450 original graded challenges. Exact boards, finite queues, stable IDs, measured difficulty, winning witnesses and deterministic generation are published with the engines.
+- Campaign selectors, fixed rule displays, goal progress, replay and next-level recovery in the players.
+
+### Fixed
+
+- Clear game-over results and disabled play controls; fixed challenge settings; exact save recovery; responsive goal text; shared cloth and piece appearance; generated API imports and markup.
+- Stable board geometry when switching English and Japanese at phone, tablet and desktop widths.
+
+
+### Changed
+
+- `CONTRIBUTING.md` is the family's one text with a section of its own for Houseki, 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 shared stylesheet is `demo/houseki.css` (it was `game.css`), named for the package like the family's.
+
+## [0.1.1] - 2026-10-05
+
+### Changed
+
+- The package is brought to the family's standard: the same checks (`pnpm check` is lint, types and tests), tests run by Vitest, a CI workflow on Node 22 and 24, a release workflow that publishes by trusted publishing, and a Pages workflow, all on current action versions; `pnpm test:package` packs, installs and imports every entry point.
+- `package.json` is made like the family's: a description short enough for npm, homepage, author, `module` and `sideEffects`.
+- The README follows the family's order and lists all twenty-four packages of the family, made from the shared template.
+- The demo's four pages are made under the family's header, footer, language chooser, Help switch and table cloths, with a description, an icon and a title in the family's form, and an API reference in the same header. The page's own Theme button is gone: light and dark follow the device, as in the other demos.
+- The demo's tests are Playwright tests that run at a phone's width and a desk's, in Chromium, and the pages themselves in WebKit too.
+
+### Fixed
+
+- A new game on a page served over plain http, from an address other than localhost, no longer fails: the seed falls back to random bytes where `crypto.randomUUID` does not exist.
+- The API reference no longer widens the page on a phone for a doc comment that names a long entry path.
+- Unused imports and variables are removed from the source; no public export, signature or behaviour changes.
+
+## [0.1.0] - 2026-10-05
+
+### Added
+
+- Original Falling Triplets, Colour Chains, Stone Collapse and Gem Swap engines with immutable state, seeded play, validated settings and canonical saves.
+- 300 graded challenges and three bilingual lessons for each game.
+- Family-style keyboard, keypad and touch demos, configurable boards, stored tools, goal progress and shared animation preferences.
+- Optional Black Hole powers, Shizen magnetic stones with bounded rebound, and Arashi jumble and lightning schedules.
+- An experimental Magnetic Blocks engine with bonded squares, magnetic floor schedules, a Floor Switch and impact drops.
+- Typed entry points, a generated API reference, an MIT licence and reproducible package checks.
+
+[Unreleased]: https://github.com/johnmorrisdotca/houseki/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/johnmorrisdotca/houseki/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/johnmorrisdotca/houseki/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/johnmorrisdotca/houseki/releases/tag/v0.1.0

package/README.md

@@ -1,80 +1,293 @@
-# Houseki · 宝石
+<h1 align="center">Houseki <sub>宝石</sub></h1>
 
-[![Checks](https://github.com/johnmorrisdotca/houseki/actions/workflows/check.yml/badge.svg)](https://github.com/johnmorrisdotca/houseki/actions/workflows/check.yml) [![MIT licence](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+<p align="center"><strong>Five original gem and stone puzzle games for JavaScript and TypeScript.</strong><br>
+Falling Triplets, Colour Chains, Stone Collapse and Gem Swap: each an immutable, seeded rules engine that runs anywhere, with graded challenges and lessons, saves that replay to the same board, and a keyboard, keypad and touch player in the demo. Magnetic Blocks adds bonded squares, a magnetic floor and its own campaign. Shizen and Arashi each add a separate Colour Chains campaign. In English and Japanese. No dependencies.</p>
 
-Original gem and stone puzzle games with immutable TypeScript rules and a shared English/Japanese player.
+<p align="center">
+  <a href="https://github.com/johnmorrisdotca/houseki/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/houseki/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/houseki"><img alt="npm" src="https://img.shields.io/npm/v/@johnmorrisdotca/houseki?color=2f5d4a"></a>
+  <a href="./LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-2f5d4a"></a>
+  <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-2f5d4a">
+  <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-2f5d4a">
+</p>
 
-**Initial release:** four playable games with tested rules, campaigns and demos. Physical-device feel, fluent Japanese copy and human difficulty review remain ongoing. Magnetic Blocks and nature variants are experimental. Website integration is maintained separately.
+<p align="center"><a href="https://johnmorrisdotca.github.io/houseki/"><strong>Play a game →</strong></a> · <a href="https://johnmorrisdotca.github.io/houseki/api.html">API reference</a></p>
 
-| Game | Distinctive mechanic |
-| --- | --- |
-| Falling Triplets | Cycle a falling vertical triplet; clear horizontal, vertical and diagonal lines |
-| Stone Collapse | Select connected groups; plan removal order and column compression |
-| Colour Chains | Rotate falling pairs; build connected groups and cascading chains |
-| Gem Swap | Swap neighbours; create and combine specials to complete objectives |
+<p align="center">
+  <img src="docs/images/gem-swap-desktop.png" alt="Gem Swap on a full board in the demo: a grid of red, blue, green, gold, purple and teal gems with permanent symbols on them, the tool tray beside it with Bomb, Row clear and Colour clear, and the family's header above" width="620">
+  <img src="docs/images/tool-tray-phone.png" alt="The same tool tray on a phone, under the board" width="200">
+</p>
+
+Houseki is a set of match-style puzzle games made to be dropped into a page or a server. Every game is a set of plain functions on plain data: a state in, a new state out, nothing read from the page, the clock or the network. The demo's players draw those states, and a person can play them with the keyboard, a keypad or a finger.
 
-An optional experimental `magnetic-blocks` entry point provides bonded 2×2 squares, magnetic floor schedules, a one-use Floor Switch and impact drops. [Play its demo](https://johnmorrisdotca.github.io/houseki/blocks.html). It has no graded campaign yet. The `nature` entry point exposes deterministic attraction, rebound and environment utilities.
+## In 30 seconds
 
-![Falling Triplets demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/falling-triplets-desktop.png)
+```sh
+npm install @johnmorrisdotca/houseki
+```
 
-![Colour Chains demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/colour-chains-desktop.png)
+```ts
+import { createGame, applyAction, advanceTicks } from "@johnmorrisdotca/houseki/falling-triplets";
+
+let game = createGame({ mode: "relaxed", seed: "first-game" });
+game = applyAction(game, { kind: "cycle-forward" }).state;
+game = applyAction(game, { kind: "place" }).state;
+game = advanceTicks(game, 22).state;
+```
 
-![Gem Swap demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/gem-swap-desktop.png)
+Every engine is a path of its own, and the main entry groups them by game:
 
-![Stone Collapse demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/stone-collapse-desktop.png)
+```ts
+import { colourChains } from "@johnmorrisdotca/houseki";
 
-[API reference](https://johnmorrisdotca.github.io/houseki/api.html) is generated locally by `pnpm site`; the hosted page becomes available after deployment. [Incremental draft PR](https://github.com/johnmorrisdotca/houseki/pull/1).
+const firstChallenge = colourChains.createLevel(1);
+const goal = firstChallenge.settings.goal;
+```
 
-## Design and progression
+Or straight from a page, with nothing to build:
 
-The [design pack](https://github.com/johnmorrisdotca/houseki/blob/main/docs/design/README.md) specifies rules, controls, materials, accessibility, generation, grading, persistence and acceptance checks. [Level generation](https://github.com/johnmorrisdotca/houseki/blob/main/docs/design/LEVEL-GENERATION.md) follows a deliberate complete count and measured progression: generate and prove original boards, remove duplicates, grade player-facing decisions, then sort and number from easy to hard. Stable content IDs preserve saved progress across future ordering changes.
+```html
+<script type="module">
+  import { createGame } from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/houseki@0/dist/gem-swap.js";
+  const game = createGame({ seed: "hello" });
+</script>
+```
 
-The shared player uses the family's ivory, brass and felt palette, permanent colour symbols and configurable boards. Each set of three interactive lessons is separate from the graded campaign. Physical-device feel testing and fluent Japanese copy review are recorded independently from automated checks.
+## Who it is for
 
-## Local development
+- **Game and puzzle sites** that want match games with the rules already right: challenges everybody plays alike, a win that is witnessed, and saves that cannot drift.
+- **Anyone who needs the rules without a screen**: a server that checks a finished game, a test that plays a campaign, a bot, a solver. Every engine is deterministic from its seed.
+- **Teachers and parents**: nothing is timed against you in Relaxed play, every colour has its own permanent symbol, and every word is plain.
 
-Requires Node.js 22 or newer and pnpm.
+## Features
 
-```sh
-pnpm install
-pnpm build
-pnpm test
-pnpm demo
+- **Five games**, each its own engine and its own entry point: [Falling Triplets](docs/design/01-FALLING-TRIPLETS.md), [Stone Collapse](docs/design/02-STONE-COLLAPSE.md), [Colour Chains](docs/design/03-COLOUR-CHAINS.md) [Gem Swap](docs/design/04-GEM-SWAP.md) and [Magnetic Blocks](docs/design/CAMPAIGN-EXTENSIONS.md).
+- **Graded campaigns and lessons**: 100 Falling Triplets, 50 Colour Chains, 100 Stone Collapse, 50 Gem Swap, 50 Magnetic Blocks, 50 Shizen and 50 Arashi challenges (450 total), ordered by measured difficulty, each with a recorded winning play that the tests replay, and three guided lessons for each game. The boards are original, regenerated from a script, and a challenge keeps its identity if the order changes.
+- **Three modes**: Relaxed (no clock, plan each move), Arcade (a timer drops the pieces) and Daily (the same board for everyone on a date).
+- **Seeded and replayable**: a state is made from a seed and a list of actions, so a save is that list, and it decodes to exactly the board it came from.
+- **Configurable boards**: presets from compact to extra wide and deep, custom sizes within stated limits, up to six colours, and shaped boards (heart, star, hexagon) for the full-board games.
+- **Stored tools** for Gem Swap (Bomb, Row clear, Colour clear) and Stone Collapse (Bomb, Pick): select a tool and a stone, look at the highlighted effect, then confirm or cancel. A run that uses a tool is marked assisted. An optional earned Black Hole shrinks as it consumes nearby gems.
+- **Nature, optional**: Shizen magnetic stones with one bounded rebound, and Arashi weather, a rare or frequent earthquake that jumbles stones and lightning that removes exposed ones, on a seeded schedule.
+- **Magnetic Blocks**: bonded 2×2 squares, a floor that turns magnetic on a schedule, a one-use Floor Switch and impact drops. Its fifty challenges introduce Calm/Pull choices, planned floor schedules, the Floor Switch and impact drops.
+- **Accessible**: permanent colour symbols, keyboard and keypad control, an Animation setting that is on by default and a reduced-motion choice that is respected.
+- **Light and dark** that follow the device, in the demo's family look.
+- **English and Japanese** words for every lesson, challenge, button and line of the demo.
+- **Zero dependencies**, for the package and for the demo.
+
+### The games
+
+| Game | Entry | You | A match is | Challenges |
+| --- | --- | --- | --- | --- |
+| Falling Triplets | `falling-triplets` | cycle a falling vertical triplet and place it | a line of three, across, down or diagonal | 100 |
+| Stone Collapse | `stone-collapse` | select a connected group and confirm | two or more touching stones of one colour | 100 |
+| Colour Chains | `colour-chains` | rotate a falling pair | a group of four or more | 50 |
+| Gem Swap | `gem-swap` | swap two neighbours | a run of three or more, which can make special gems | 50 |
+| Magnetic Blocks | `magnetic-blocks` | rotate a falling 2×2 block | four connected gems, with Calm/Pull settling | 50 |
+| Shizen | `colour-chains` | anticipate marked stones and rebound | four connected gems after attraction | 50 |
+| Arashi | `colour-chains` | plan around earthquakes and lightning | four connected gems after weather | 50 |
+
+## Use it in your project
+
+Import a game directly from `@johnmorrisdotca/houseki/falling-triplets`, `@johnmorrisdotca/houseki/stone-collapse`, `@johnmorrisdotca/houseki/colour-chains`, `@johnmorrisdotca/houseki/gem-swap` or `@johnmorrisdotca/houseki/magnetic-blocks`, and the deterministic attraction, rebound and environment utilities from `@johnmorrisdotca/houseki/nature`. The main entry, `@johnmorrisdotca/houseki`, groups the same names as the namespaces `fallingTriplets`, `stoneCollapse`, `colourChains`, `gemSwap`, `nature` and `magneticBlocks`. The engines do not touch the DOM, storage or the network.
+
+Every engine works the same way:
+
+```ts
+import { createGame, createLevel, applyAction, advanceTicks, legalActions, encodeGame, decodeGame } from "@johnmorrisdotca/houseki/colour-chains";
+
+const level = createLevel(1);                       // a graded challenge; createGame({ seed }) is a free game
+const move = applyAction(level, { kind: "rotate-clockwise" });
+move.accepted;                                      // false when the action is not allowed
+move.events;                                        // what happened, in order, for a screen to animate
+const later = advanceTicks(move.state, 30).state;   // time is a count of ticks, never the clock
+const saved = encodeGame(later);                    // a string; decodeGame(saved) is the same game again
 ```
 
-The local demo instructions print its address. The first page plays Falling Triplets; `chains.html` plays Colour Chains; `tools.html` plays Gem Swap and Stone Collapse with optional stored-tool trays. The campaigns contain 100 Falling Triplets, 50 Colour Chains, 100 Stone Collapse and 50 Gem Swap challenges, ordered by measured difficulty. Finite goals show progress and remaining pieces or moves. All players share the persisted default-on Animation setting and respect reduced motion. See [CONTRIBUTING.md](https://github.com/johnmorrisdotca/houseki/blob/main/CONTRIBUTING.md) for contribution conventions and [the implementation plan](https://github.com/johnmorrisdotca/houseki/blob/main/docs/design/IMPLEMENTATION-PLAN.md) for bounded review milestones.
+Every function returns a new state and leaves the one it was given untouched. `legalActions(state)` lists what may be done now, so a bot or a test needs no knowledge of the rules. The two full-board games, Gem Swap and Stone Collapse, also have an undo and a hint (`undoGame` and `hintGame` in Gem Swap, `undo` and `requestHint` in Stone Collapse) and a restart; their stored tools are actions of their own.
+
+To run the whole demo, `pnpm install && pnpm site`, then serve `site/` with any static server. A page of the demo takes `?seed=anything` in its address to start the same board again, and `?lang=ja` for Japanese.
 
-## Engine example
+### Additional campaigns
 
-The currently reviewed Falling Triplets entry point is independent of DOM, storage and network access:
+![Magnetic Blocks campaign: fixed board settings, a marked-gem objective, progress bars and the shared cloth and piece appearance](docs/images/magnetic-blocks-campaign-desktop.png)
 
 ```ts
-import { createGame, applyAction, advanceTicks } from '@johnmorrisdotca/houseki/falling-triplets';
+import { createShizenLevel, createArashiLevel } from "@johnmorrisdotca/houseki/colour-chains";
+import { createLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
 
-let game = createGame({ mode: 'relaxed', seed: 'first-game' });
-game = applyAction(game, { kind: 'cycle-forward' }).state;
-game = applyAction(game, { kind: 'place' }).state;
-game = advanceTicks(game, 22).state;
+const magneticStones = createShizenLevel(1);
+const weather = createArashiLevel(1);
+const bondedSquares = createLevel(1);
 ```
 
-The package exposes an entry point for each game. The generated API reference lists every exported function, type and setting.
+Each campaign has fifty fixed puzzles ordered from easy to hard. Use its manifest for stable IDs, bilingual titles, objectives, difficulty marks and verified winning plans. Select Shizen or Arashi in the Colour Chains demo, or a challenge in Magnetic Blocks. A campaign uses a finite queue with no falling clock; the goal and progress appear beside the board. Fixed rules stay visible, and the result offers replay or the next challenge. See the [campaign contract](docs/design/CAMPAIGN-EXTENSIONS.md).
 
-## Licence
+## API
 
-[MIT](LICENSE), copyright John Morris. Original game content and presentation are maintained in this repository. Shared family files preserve their existing copyright notices. Report vulnerabilities through [SECURITY.md](https://github.com/johnmorrisdotca/houseki/blob/main/SECURITY.md).
+Every export of every entry point is in the [API reference](https://johnmorrisdotca.github.io/houseki/api.html), made from the source when the demo is built, with each signature and doc comment. A test fails when a public export has no doc comment.
 
-## Stored tools
+## Theming
 
-[Stored-tool rules](https://github.com/johnmorrisdotca/houseki/blob/main/docs/design/STORED-TOOLS.md) distinguish inventory from special gems on the board. Gem Swap offers Bomb, Row clear and Colour clear; Stone Collapse offers Bomb and Pick. Select a tool and an occupied square, inspect the highlighted effect, then confirm or cancel. Ordinary clears earn capped inventory; using tools marks the run assisted. Daily and existing authored challenges keep their declared tool-free rules. Gem Swap also offers an optional earned [Black Hole](https://github.com/johnmorrisdotca/houseki/blob/main/docs/design/BLACK-HOLE.md): consume nearby gems with a visibly shrinking capacity and bounded lifetime. Enable it before starting a casual board.
+The engines draw nothing. The demo's players take their colours from the family's stylesheet, `demo/family.css`: custom properties for the page, ink, accent and the felt the board sits on, which follow `prefers-color-scheme`, and five table cloths (green, blue, red, black and wood) chosen in the header. The boards add their own `--board`, `--frame` and `--gem-edge` in `demo/houseki.css`, and a Board material choice (ivory, slate or wood). Gems are told apart by their symbol as well as their colour, so no choice of cloth hides a colour.
 
-## Package entry points
+## Limits
 
-Import a game directly from `@johnmorrisdotca/houseki/falling-triplets`, `/stone-collapse`, `/colour-chains` or `/gem-swap`. The root entry groups the same APIs as `fallingTriplets`, `stoneCollapse`, `colourChains` and `gemSwap` namespaces. Engines do not depend on the DOM or external services.
+| What | Limit |
+| --- | --- |
+| Colours | 4 to 6 |
+| Colour Chains | 5 to 16 columns and 12 to 32 visible rows |
+| Magnetic Blocks | 4 to 16 columns and 4 to 32 rows; at most 200 pieces in the demo |
+| Stone Collapse | presets from 6×8 to 16×10 and 8×32 deep; shaped boards by mask |
+| Daily mode | the standard board and colour count only, from a date |
+| Saves | a replay of the actions taken, checked when it is decoded; a save that does not match its own record is refused |
+| Tools | capped inventory, earned by ordinary clears, and not offered in Daily or in authored challenges |
 
-```ts
-import { colourChains } from '@johnmorrisdotca/houseki';
-const firstChallenge = colourChains.createLevel(1);
-const objective = firstChallenge.settings.goal;
+## Browser support
+
+The engines run wherever JavaScript does: Node 22 or later, and current Chrome, Edge, Firefox and Safari. The demo's tests run in Chromium and WebKit, at a phone's width and a desk's.
+
+## Languages
+
+The demo is in English and Japanese: every lesson and challenge title, button, status line and the family's header and footer. The Japanese has not yet been read by a native reader: corrections are welcome as a *Fix a translation* issue.
+
+## Roadmap
+
+Physical-device feel testing, a fluent Japanese review and human difficulty review of the campaigns are next, and new techniques for later campaigns. [docs/COVERAGE.md](docs/COVERAGE.md) says what is verified by tests and what is not. Nothing here is promised for a date.
+
+## Architecture
+
+```text
+src/
+├── colour-chains/
+│   ├── challenge.ts
+│   ├── content-data.ts
+│   ├── content-types.ts
+│   ├── content.ts
+│   ├── engine.ts
+│   ├── input.ts
+│   ├── match.ts
+│   ├── persistence.ts
+│   ├── random.ts
+│   ├── types.ts
+│   └── validation.ts
+├── colour-chains.ts
+├── falling-triplets/
+│   ├── content-data.ts
+│   ├── content-types.ts
+│   ├── content.ts
+│   ├── engine.ts
+│   ├── input.ts
+│   ├── match.ts
+│   ├── random.ts
+│   └── types.ts
+├── falling-triplets.ts
+├── gem-swap/
+│   ├── black-hole.ts
+│   ├── board.ts
+│   ├── content.ts
+│   ├── engine.ts
+│   ├── persistence.ts
+│   ├── practice.ts
+│   ├── random.ts
+│   ├── specials.ts
+│   ├── tools.ts
+│   └── types.ts
+├── gem-swap.ts
+├── index.ts
+├── magnetic-blocks/
+│   ├── content-data.ts
+│   ├── content-types.ts
+│   ├── content.ts
+│   ├── engine.ts
+│   ├── persistence.ts
+│   ├── physics.ts
+│   ├── random.ts
+│   ├── types.ts
+│   └── validation.ts
+├── magnetic-blocks.ts
+├── nature/
+│   ├── attraction.ts
+│   ├── environment.ts
+│   ├── marking.ts
+│   ├── random.ts
+│   ├── rebound.ts
+│   ├── state.ts
+│   ├── types.ts
+│   └── validation.ts
+├── nature.ts
+├── stone-collapse/
+│   ├── content-data.ts
+│   ├── content-types.ts
+│   ├── content.ts
+│   ├── engine.ts
+│   ├── persistence.ts
+│   ├── types.ts
+│   └── validation.ts
+└── stone-collapse.ts
 ```
 
-Run `npm run check:package` to build, pack and install the actual tarball into a temporary consumer and check every game entry point. `npm run test:browser` verifies desktop and phone player controls, witnessed campaign wins, progress, tool use, persistence of animation preferences and reduced motion.
+The [design pack](docs/design/README.md) specifies the rules, controls, materials, accessibility, level generation, grading, persistence and acceptance checks of every game; [level generation](docs/design/LEVEL-GENERATION.md) follows a deliberate complete count: generate and prove original boards, remove duplicates, grade the decisions a player faces, then sort and number from easy to hard.
+
+## The name
+
+Houseki (宝石) is Japanese for a gem or precious stone: the pieces of these games are cut and polished, and the games are small.
+
+## Where it comes from
+
+Match games are an old family and their rules are common property. These five are original: the rules are written out in the design pack in our own words, every board is generated and checked by the repository's own scripts, and the pictures are drawn in code. No art, sound or level comes from another game.
+
+### The family
+
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Houseki 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/).
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+- [Narabe](https://github.com/johnmorrisdotca/narabe) (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. [Demo](https://johnmorrisdotca.github.io/narabe/).
+- [Tenka](https://github.com/johnmorrisdotca/tenka) (天下): world conquest for two to six, on a map of the real world. [Demo](https://johnmorrisdotca.github.io/tenka/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+- [Jarajara](https://github.com/johnmorrisdotca/jarajara) (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. [Demo](https://johnmorrisdotca.github.io/jarajara/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [Meikyuu](https://github.com/johnmorrisdotca/meikyuu) (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. [Demo](https://johnmorrisdotca.github.io/meikyuu/).
+- [Hikidashi](https://github.com/johnmorrisdotca/hikidashi) (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. [Demo](https://johnmorrisdotca.github.io/hikidashi/).
+- [Chizu](https://github.com/johnmorrisdotca/chizu) (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. [Demo](https://johnmorrisdotca.github.io/chizu/).
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
+- [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 Houseki.** The demos of all twenty-four share one header and footer, so each links the rest.
+<!-- family:end -->
+
+## Development
+
+```sh
+pnpm install
+pnpm check          # lint, types and tests: every game's rules, every campaign's recorded wins
+pnpm test:package   # pack it as npm does, install it in an empty project, import every entry
+pnpm test:demo      # build the demo and play it in a real browser, at a phone's width and a desk's
+pnpm site           # build the demo and the API reference into site/
+```
+
+## Contributing
+
+Ideas, bug reports and pull requests are welcome in the [issues](https://github.com/johnmorrisdotca/houseki/issues). See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Changes
+
+Every release is written up in [CHANGELOG.md](./CHANGELOG.md).
+
+## Licence
+
+[MIT](./LICENSE) © John Morris. The code, the boards and the words are all the package's own. Report vulnerabilities through [SECURITY.md](./SECURITY.md).

package/dist/colour-chains/challenge.js

@@ -61,7 +61,7 @@ function solveWitness(start, witness) {
 export function createChallenge(options) {
     if (!options || typeof options !== 'object' || Array.isArray(options))
         throw new StoneChainsOptionsError('invalid-challenge', 'Challenge options must be an object');
-    const allowed = ['id', 'width', 'height', 'colourCount', 'seed', 'board', 'queue', 'goal', 'witness'];
+    const allowed = ['id', 'width', 'height', 'colourCount', 'seed', 'board', 'queue', 'magneticQueue', 'nature', 'weather', 'goal', 'witness'];
     if (Object.keys(options).some(key => !allowed.includes(key)))
         throw new StoneChainsOptionsError('unknown-challenge-option', 'Challenge options contain unsupported fields');
     if (typeof options.id !== 'string' || !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(options.id))
@@ -75,6 +75,14 @@ export function createChallenge(options) {
     const seed = options.seed ?? `challenge:${options.id}`;
     if (typeof seed !== 'string' || seed.length < 1 || seed.length > 200)
         throw new StoneChainsOptionsError('invalid-seed', 'Seed must contain 1–200 characters');
+    if (options.nature !== undefined && typeof options.nature !== 'boolean')
+        throw new StoneChainsOptionsError('invalid-nature-option', 'nature must be a boolean');
+    if (options.weather !== undefined && options.weather !== 'frequent' && options.weather !== 'rare')
+        throw new StoneChainsOptionsError('invalid-weather-option', 'weather must be frequent or rare');
+    if (options.weather !== undefined && options.nature !== true)
+        throw new StoneChainsOptionsError('weather-requires-nature', 'Arashi weather requires nature:true');
+    if (options.magneticQueue !== undefined && options.nature !== true)
+        throw new StoneChainsOptionsError('magnetic-queue-requires-nature', 'Magnetic queue flags require nature:true');
     if (!Array.isArray(options.board) || options.board.length !== width * height)
         throw new StoneChainsOptionsError('invalid-challenge-board', 'Challenge board must contain width × height visible cells');
     if (!Array.isArray(options.queue) || options.queue.length < 2 || options.queue.length > 12)
@@ -84,10 +92,10 @@ export function createChallenge(options) {
     const board = options.board.map((gem, index) => {
         if (gem === null)
             return null;
-        if (!gem || typeof gem !== 'object' || Array.isArray(gem) || Object.keys(gem).some(key => key !== 'id' && key !== 'colour') || !Number.isSafeInteger(gem.id) || gem.id < 1 || gem.id > 0x7fff_ffff || ids.has(gem.id) || !allowedColours.includes(gem.colour))
+        if (!gem || typeof gem !== 'object' || Array.isArray(gem) || Object.keys(gem).some(key => key !== 'id' && key !== 'colour' && key !== 'magnetic') || !Number.isSafeInteger(gem.id) || gem.id < 1 || gem.id > 0x7fff_ffff || ids.has(gem.id) || !allowedColours.includes(gem.colour) || gem.magnetic !== undefined && (gem.magnetic !== true || options.nature !== true))
             throw new StoneChainsOptionsError('invalid-challenge-gem', `Invalid challenge gem at cell ${index}`);
         ids.add(gem.id);
-        return Object.freeze({ id: gem.id, colour: gem.colour });
+        return Object.freeze({ id: gem.id, colour: gem.colour, ...(gem.magnetic ? { magnetic: true } : {}) });
     });
     for (let x = 0; x < width; x++) {
         let gap = false;
@@ -103,6 +111,12 @@ export function createChallenge(options) {
             throw new StoneChainsOptionsError('invalid-challenge-pair', `Invalid queue pair ${index + 1}`);
         return Object.freeze([pair[0], pair[1]]);
     });
+    let magneticQueue;
+    if (options.magneticQueue !== undefined) {
+        if (!Array.isArray(options.magneticQueue) || options.magneticQueue.length !== queue.length || options.magneticQueue.some(pair => !Array.isArray(pair) || pair.length !== 2 || pair.some(flag => typeof flag !== 'boolean')))
+            throw new StoneChainsOptionsError('invalid-magnetic-queue', 'Magnetic queue must contain one pair of boolean flags per finite queue pair');
+        magneticQueue = Object.freeze(options.magneticQueue.map(pair => Object.freeze([pair[0], pair[1]])));
+    }
     const goal = validateChallengeGoal(options.goal, ids);
     if (!Array.isArray(options.witness) || options.witness.length < 1 || options.witness.length > queue.length)
         throw new StoneChainsOptionsError('invalid-witness', 'A challenge requires a complete witness of 1–12 pair placements');
@@ -111,7 +125,7 @@ export function createChallenge(options) {
             throw new StoneChainsOptionsError('invalid-witness-step', `Invalid witness placement ${index + 1}`);
         return Object.freeze({ pivotX: step.pivotX, orientation: step.orientation });
     });
-    const settings = Object.freeze({ mode: 'challenge', width, height, colourCount, seed, challengeId: options.id, goal, initialBoard: Object.freeze(board), queue: Object.freeze(queue), witness: Object.freeze(witness) });
+    const settings = Object.freeze({ mode: 'challenge', width, height, colourCount, seed, challengeId: options.id, goal, initialBoard: Object.freeze(board), queue: Object.freeze(queue), ...(magneticQueue ? { magneticQueue } : {}), ...(options.nature ? { nature: true } : {}), ...(options.weather ? { weather: options.weather } : {}), witness: Object.freeze(witness) });
     const state = initialChallengeState(settings, settings.initialBoard, settings.queue);
     const solved = solveWitness(state, witness);
     if (solved.phase !== 'won' || stable(solved.settings) !== stable(settings))