@johnmorrisdotca/houseki 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,10 +1,41 @@
 # 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]
+
+### Changed
+
+- 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 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.1.1...HEAD
+[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,273 @@
-# 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>Four 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, with bonded squares and a magnetic floor, is an experiment beside them. 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>
 
-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.
+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.
 
-![Falling Triplets demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/falling-triplets-desktop.png)
+## In 30 seconds
 
-![Colour Chains demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/colour-chains-desktop.png)
+```sh
+npm install @johnmorrisdotca/houseki
+```
 
-![Gem Swap demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/gem-swap-desktop.png)
+```ts
+import { createGame, applyAction, advanceTicks } from "@johnmorrisdotca/houseki/falling-triplets";
 
-![Stone Collapse demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/stone-collapse-desktop.png)
+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;
+```
 
-[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).
+Every engine is a path of its own, and the main entry groups them by game:
 
-## Design and progression
+```ts
+import { colourChains } from "@johnmorrisdotca/houseki";
 
-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.
+const firstChallenge = colourChains.createLevel(1);
+const goal = firstChallenge.settings.goal;
+```
 
-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.
+Or straight from a page, with nothing to build:
 
-## Local development
+```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>
+```
 
-Requires Node.js 22 or newer and pnpm.
+## Who it is for
 
-```sh
-pnpm install
-pnpm build
-pnpm test
-pnpm demo
-```
+- **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.
 
-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.
+## Features
 
-## Engine example
+- **Four 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) and [Gem Swap](docs/design/04-GEM-SWAP.md).
+- **Graded campaigns and lessons**: 100 Falling Triplets, 50 Colour Chains, 100 Stone Collapse and 50 Gem Swap challenges, 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, experimental**: bonded 2×2 squares, a floor that turns magnetic on a schedule, a one-use Floor Switch and impact drops. It has no graded campaign yet.
+- **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 currently reviewed Falling Triplets entry point is independent of DOM, storage and network access:
+### 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 (experimental) | `magnetic-blocks` | rotate a falling 2×2 block | bonded groups, on a floor that pulls | none yet |
+
+## 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, applyAction, advanceTicks } from '@johnmorrisdotca/houseki/falling-triplets';
+import { createGame, createLevel, applyAction, advanceTicks, legalActions, encodeGame, decodeGame } from "@johnmorrisdotca/houseki/colour-chains";
 
-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 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 package exposes an entry point for each game. The generated API reference lists every exported function, type and setting.
+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.
 
-## Licence
+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.
 
-[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).
+## API
 
-## Stored tools
+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-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.
+## Theming
 
-## Package entry points
+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.
 
-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.
+## Limits
 
-```ts
-import { colourChains } from '@johnmorrisdotca/houseki';
-const firstChallenge = colourChains.createLevel(1);
-const objective = firstChallenge.settings.goal;
+| 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 |
+
+## 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 a graded campaign for Magnetic Blocks. [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/
+│   ├── 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 four 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/input.js

@@ -14,6 +14,7 @@ export function setHeldInput(state, control, pressed) {
 /** Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick. */
 export function queueInputEdge(state, action) { return { ...state, queued: Object.freeze([...state.queued, action]) }; }
 /** Releases every held or queued control after focus loss, lock, resolution or pause. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the public signature takes the state a caller holds, though nothing of it is kept
 export function releaseAllInput(state) { return createInputScheduler(); }
 /** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order. */
 export function actionsForTick(game, input) {

package/dist/falling-triplets/engine.js

@@ -79,7 +79,7 @@ export function createGame(options = {}) {
     const settings = { mode, width, height, colourCount, seed, ...(pieceLimit === undefined ? {} : { pieceLimit }) };
     if (![4, 5, 6].includes(settings.colourCount))
         throw new RangeError('Colour count must be 4, 5, or 6');
-    let randomState = seedState(`falling-triplets|${RULES}|${seed}`);
+    const randomState = seedState(`falling-triplets|${RULES}|${seed}`);
     const initial = { game: 'falling-triplets', rules: RULES, settings, board: Array(width * (height + HIDDEN)).fill(null), phase: 'falling', active: null, next: [], bag: [], randomState, nextId: 1, score: 0, maxChain: 0, completedPieces: 0, elapsedTicks: 0, pieceTicks: 0, resolutionTick: 0, waves: [], assisted: false, hintsUsed: 0, witnessPathMatches: true, recording: [] };
     const first = drawTriplet(initial);
     let state = { ...initial, bag: first.bag, randomState: first.randomState, hintsUsed: 0 };

package/dist/falling-triplets/input.js

@@ -38,4 +38,5 @@ export function actionsForTick(state) {
     return [actions, { held, queued: [] }];
 }
 /** Releases every held action after blur, pause, or pointer cancellation. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- the public signature takes the state a caller holds, though nothing of it is kept
 export function releaseAllActions(state) { return { held: {}, queued: [] }; }

package/dist/gem-swap/engine.js

@@ -418,7 +418,7 @@ function awardTools(state, removed) {
         return { inventory: state.inventory, progress: state.toolProgress, cursor: state.toolAwardCursor, events: Object.freeze([]) };
     let progress = state.toolProgress + removed;
     let cursor = state.toolAwardCursor;
-    let inventory = { ...state.inventory };
+    const inventory = { ...state.inventory };
     const events = [];
     while (progress >= 12) {
         progress -= 12;

package/dist/gem-swap/specials.js

@@ -211,7 +211,7 @@ function comboPlan(state, p, q, protectedCells, pairIds) {
     return null;
 }
 function effectCells(state, cell, kind) {
-    const { width, height } = state.settings;
+    const { width } = state.settings;
     const x = cell % width;
     const y = Math.floor(cell / width);
     if (kind === 'row-beam')

package/dist/gem-swap/tools.js

@@ -1,7 +1,7 @@
 import { planWave } from './specials.js';
 /** Computes the occupied cells affected by a tool and all special activations it causes. */
 export function previewTool(state, tool, target) {
-    const { width, height, mask } = state.settings;
+    const { width, mask } = state.settings;
     if (!Number.isInteger(target) || target < 0 || target >= state.board.length || !mask[target] || !state.board[target])
         return Object.freeze([]);
     const x = target % width;

package/dist/nature/environment.js

@@ -73,9 +73,8 @@ function validateLightningOptions(options, width) {
 function faultPath(state) {
     if (state.width < 3)
         throw new NatureOptionsError('invalid-grid-size', 'A fault needs at least three columns to preserve playable space on both sides');
-    let randomState = state.randomState;
-    let draw;
-    [randomState, draw] = drawBelow(randomState, state.width - 2);
+    const [firstState, draw] = drawBelow(state.randomState, state.width - 2);
+    let randomState = firstState;
     let x = draw + 1;
     const path = [at(x, 0, state.width)];
     for (let y = 1; y < state.height; y++) {
@@ -146,8 +145,8 @@ export function previewJumble(state) {
     const candidates = candidatePatches(state);
     if (candidates.length === 0)
         return deepFreeze({ patchCells: [], moves: [], changed: false, reason: 'no-eligible-patch', cells: state.cells, randomStateAfter: state.randomState });
-    let randomState, selectedIndex;
-    [randomState, selectedIndex] = drawBelow(state.randomState, candidates.length);
+    const [firstState, selectedIndex] = drawBelow(state.randomState, candidates.length);
+    let randomState = firstState;
     const patch = candidates[selectedIndex];
     const shuffled = [...patch.stones];
     for (let index = shuffled.length - 1; index > 0; index--) {

package/dist/nature/rebound.js

@@ -57,7 +57,7 @@ export function previewPowerDrop(state, request) {
     }
     const eligible = request.power && state.rules.reboundEnabled;
     let randomStateAfter = state.randomState;
-    let attempts = [];
+    const attempts = [];
     let finalCells = normal;
     let selectedDirection;
     let selectedTurn = 0;

package/dist/stone-collapse/engine.js

@@ -74,7 +74,7 @@ function previewAt(state, tool, target) {
         }
     return cells;
 }
-function clearToolSelection(state) {
+function clearToolSelection(_state) {
     return { selectedTool: null, toolTarget: null, toolPreview: Object.freeze([]) };
 }
 function recordToolAction(state, action) {

package/dist/stone-collapse/validation.js

@@ -1,7 +1,6 @@
 const PRESETS = {
     compact: [6, 8], standard: [8, 10], wide: [10, 8], tall: [6, 12], extraWide: [16, 10], deep: [8, 32], large: [12, 32],
 };
-const COLOURS = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
 /** Typed public-settings validation error. */
 export class StoneCollapseOptionsError extends RangeError {
     code;
@@ -96,7 +95,7 @@ export function optionsFor(options) {
     const hasDimensions = options.width !== undefined || options.height !== undefined;
     let width;
     let height;
-    let shape = options.shape;
+    const shape = options.shape;
     let mask = options.mask;
     if (shape !== undefined) {
         if (options.preset !== undefined || hasDimensions || mask !== undefined || !['heart', 'star', 'hexagon'].includes(shape))

package/package.json

@@ -1,19 +1,53 @@
 {
   "name": "@johnmorrisdotca/houseki",
-  "version": "0.1.0",
-  "description": "Original immutable gem-matching game engines and accessible English/Japanese play.",
-  "type": "module",
-  "author": "John Morris",
-  "license": "MIT",
+  "version": "0.1.1",
+  "description": "Houseki \u5b9d\u77f3: four original gem and stone puzzle games, Falling Triplets, Colour Chains, Stone Collapse and Gem Swap, as immutable seeded engines with 300 graded levels, plus experimental Magnetic Blocks. English and Japanese. Zero dependencies.",
+  "keywords": [
+    "puzzle",
+    "puzzle-game",
+    "match-three",
+    "match-3",
+    "falling-triplets",
+    "colour-chains",
+    "stone-collapse",
+    "gem-swap",
+    "magnetic-blocks",
+    "gravity",
+    "cascade",
+    "game-engine",
+    "levels",
+    "immutable",
+    "deterministic",
+    "seeded-random",
+    "accessible",
+    "touch",
+    "keyboard",
+    "japanese",
+    "typescript",
+    "javascript",
+    "zero-dependencies",
+    "browser",
+    "node",
+    "itsutsu"
+  ],
+  "homepage": "https://johnmorrisdotca.github.io/houseki/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/johnmorrisdotca/houseki.git"
   },
-  "homepage": "https://johnmorrisdotca.github.io/houseki/",
   "bugs": {
     "url": "https://github.com/johnmorrisdotca/houseki/issues"
   },
+  "author": {
+    "name": "John Morris",
+    "email": "john@johnmorris.ca",
+    "url": "https://johnmorris.ca"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -63,36 +97,24 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test test/*.test.mjs",
-    "site": "npm run build && node scripts/site.mjs",
-    "demo": "npm run site && node scripts/serve.mjs",
-    "test:browser": "npm run site && node test/browser/tools.mjs",
-    "check:package": "npm run build && node scripts/check-package.mjs"
+    "test": "pnpm build && vitest run",
+    "test:package": "pnpm build && node scripts/check-package.mjs",
+    "family:readme": "node scripts/family-readme.mjs",
+    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "prepublishOnly": "pnpm check && pnpm build",
+    "site": "pnpm build && node scripts/site.mjs",
+    "test:demo": "pnpm site && playwright test && node --test --test-concurrency=2 e2e/review/appearance-api.test.mjs e2e/review/endings.test.mjs e2e/review/full-board-recovery.test.mjs e2e/review/nature-previews.test.mjs e2e/review/responsive.test.mjs",
+    "test:review": "pnpm site && node --test --test-concurrency=2 e2e/review/appearance-api.test.mjs e2e/review/endings.test.mjs e2e/review/full-board-recovery.test.mjs e2e/review/nature-previews.test.mjs e2e/review/responsive.test.mjs"
   },
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "@playwright/test": "^1.58.2"
+    "@eslint/js": "^9.0.0",
+    "@playwright/test": "^1.63.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^5.0.0"
   },
-  "packageManager": "pnpm@10.11.0",
-  "keywords": [
-    "falling-triplets",
-    "match-three",
-    "puzzle-game",
-    "immutable",
-    "typescript",
-    "zero-dependencies",
-    "accessible",
-    "touch",
-    "keyboard",
-    "japanese",
-    "stone-collapse",
-    "colour-chains",
-    "gem-swap",
-    "match-3",
-    "gravity",
-    "cascade",
-    "puzzle",
-    "game-engine"
-  ]
+  "packageManager": "pnpm@10.11.0"
 }