@johnmorrisdotca/houseki 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this package are written here, newest first, in the form
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-14
+
+Nothing that was exported has changed. The package has an English and Japanese documentation site with a checked example for every export.
+
+### Added
+
+- Add the bilingual documentation site, checked public examples, paired guides, local search and machine-readable pages.
+
+### Changed
+
+- The API link in the header reads "API" in English, so that the header takes the same number of rows in English and in Japanese on a phone, as the demo's test of a language change asks.
+- Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
+- Keep complete resource catalogues on the documentation entry index and the active resource beside core navigation; render valid default imports in HTML and Markdown.
+- The demo's smoke test counts thirty-three links in the family footer, after the sports packages joined the list, and the family test counts thirty-two packages.
+- Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
+- Update the shared family description for addresses in all seven supported countries, including France and Germany.
+
+## [0.4.1] - 2026-10-07
+
+### Fixed
+
+- Gem Swap rejects excessively nested replay inputs with a bounded validation error.
+- Reshuffling preserves an active Black Hole portal and all remaining gem identities.
+- Black Hole design status now matches the optional shipped tray power. CI explicitly checks public metadata and machine-specific documentation paths.
+
 ## [0.4.0] - 2026-10-06
 
 ### Added
@@ -96,7 +121,8 @@ Nothing that was exported has changed. The README is the family's one layout, in
 - 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.4.0...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/houseki/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/johnmorrisdotca/houseki/compare/v0.4.1...v0.4.2
 [0.3.0]: https://github.com/johnmorrisdotca/houseki/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/johnmorrisdotca/houseki/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/johnmorrisdotca/houseki/compare/v0.1.1...v0.2.0
@@ -104,3 +130,5 @@ Nothing that was exported has changed. The README is the family's one layout, in
 [0.1.0]: https://github.com/johnmorrisdotca/houseki/releases/tag/v0.1.0
 
 [0.4.0]: https://github.com/johnmorrisdotca/houseki/compare/v0.3.0...v0.4.0
+
+[0.4.1]: https://github.com/johnmorrisdotca/houseki/compare/v0.4.0...v0.4.1

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Houseki <sub>宝石</sub></h1>
+<h1 align="center">Houseki <sub>宝石</sub> — Match-3 gem puzzles</h1>
 
 <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>
@@ -9,6 +9,8 @@ Falling Triplets, Colour Chains, Stone Collapse and Gem Swap: each an immutable,
   <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">
+  <a href="https://johnmorrisdotca.github.io/houseki/docs/api/main/index.html"><img alt="179.1 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-179.1%20kB-2f5d4a"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/houseki#provenance"><img alt="Published with npm provenance" src="https://img.shields.io/badge/npm-provenance-2f5d4a"></a>
 </p>
 
 <table align="center">
@@ -16,7 +18,7 @@ Falling Triplets, Colour Chains, Stone Collapse and Gem Swap: each an immutable,
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/hero-desk-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the page header with its language chooser, the API reference link, five cloth patches and the Help switch, the page chooser (Falling Triplets, Colour Chains, Gem Swap and Stone Collapse chosen, Magnetic Blocks), the settings column, and Gem Swap on green felt: an eight by eight board of red, blue, green, gold and purple gems with a permanent symbol on each, and the tool tray beside it with Bomb, Row clear and Colour clear" width="600">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the page header with its language chooser, the Docs and API reference links, five cloth patches and the Help switch, the page chooser (Falling Triplets, Colour Chains, Gem Swap and Stone Collapse chosen, Magnetic Blocks), the settings column, and Gem Swap on green felt: an eight by eight board of red, blue, green, gold and purple gems with a permanent symbol on each, and the tool tray beside it with Bomb, Row clear and Colour clear" width="600">
 </picture>
 <br><em>The demo on a desk: Gem Swap with its tool tray.</em>
 </td>
@@ -31,6 +33,8 @@ Falling Triplets, Colour Chains, Stone Collapse and Gem Swap: each an immutable,
 </table>
 
 
+<p align="center"><a href="https://johnmorrisdotca.github.io/houseki/docs/">Documentation</a> · <a href="https://johnmorrisdotca.github.io/houseki/docs/guides/getting-started.html">Getting started</a> · <a href="https://johnmorrisdotca.github.io/houseki/api.html">API reference</a></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.
 
 ## In 30 seconds
@@ -173,6 +177,17 @@ Each picture is the real game, drawn by the demo's player from the package's eng
 
 ## Use it in your project
 
+### Install under another name
+
+```sh
+npm install match-3@npm:@johnmorrisdotca/houseki
+```
+
+```ts no-check
+import { fallingTriplets } from "match-3";
+console.log(fallingTriplets.createGame({seed:"docs"}).phase);
+```
+
 ### Install
 
 ```sh
@@ -550,6 +565,8 @@ setInterval(() => {                                  // the page owns the clock;
 
 ## API
 
+The [documentation](https://johnmorrisdotca.github.io/houseki/docs/) has paired guides, local search and checked examples. The [API index](https://johnmorrisdotca.github.io/houseki/api.html) retains existing export anchors.
+
 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.
 
 ### Entry points
@@ -617,77 +634,7 @@ Physical-device feel testing, a fluent Japanese review and human difficulty revi
 
 ## 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
-```
-
-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 [architecture guide](docs/guides/architecture.md) preserves the complete source tree and design explanation. Each native engine keeps its own types, immutable transitions, content and replay boundary.
 
 ## The name
 
@@ -704,35 +651,67 @@ Using Houseki in something? Open an *Add my project* issue and we will add you.
 ### 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.
+Houseki is one of thirty-two packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca) or [github.com/spxis](https://github.com/spxis). 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/).
+**Games — board**
+
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
 - [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/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
 - [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/).
+
+**Games — cards & tiles**
+
+- [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/).
 - [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/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+
+**Games — puzzles**
+
+- [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/).
+- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
+- [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/).
 - [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [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/).
 - [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/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — dice & random**
+
+- [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/).
+- [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/).
+
+**Language**
+
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
 - [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/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+
+**Geography & data**
+
+- [address-plus](https://github.com/johnmorrisdotca/address-plus) (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. [Demo](https://johnmorrisdotca.github.io/address-plus/).
 - [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/).
+- [Hata](https://github.com/johnmorrisdotca/hata) (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. [Demo](https://johnmorrisdotca.github.io/hata/).
+- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): countries and their regions, with ISO codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+
+**Sports**
+
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
+- [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
+- [Senshu Jerseys](https://github.com/johnmorrisdotca/senshu-jerseys) (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. [Demo](https://johnmorrisdotca.github.io/senshu-jerseys/).
+- [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
+
+**Developer tools**
+
+- [REST in Pieces](https://github.com/spxis/rest-in-pieces) (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. [Demo](https://spxis.github.io/rest-in-pieces/).
+
 
-**This package is Houseki.** The demos of all twenty-four share one header and footer, so each links the rest.
+**This package is Houseki.** The demos of all thirty-two share one header and footer, so each links the rest.
 <!-- family:end -->
 
 ## Development
@@ -742,7 +721,10 @@ 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/
+pnpm site               # build the native demo into site/
+pnpm docs:site          # add guides, API pages, search and llms files
+pnpm docs:check         # check public documentation and run its examples
+pnpm size --write       # refresh the measured bundle size and README badge
 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
 ```
@@ -753,7 +735,7 @@ Ideas, bug reports and pull requests are welcome in the [issues](https://github.
 
 ## Changes
 
-Every release is written up in [CHANGELOG.md](./CHANGELOG.md). The latest release, 0.3.0, makes Magnetic Blocks show a level's fixed rules as soon as the level is chosen and give free play its own choices back, makes Space do what the ghost showed, lets a big board be scrolled from the keyboard on all three falling players, and adds `settledCells` to the Shizen hard-drop preview.
+Every release is written up in [CHANGELOG.md](./CHANGELOG.md). The latest release, 0.4.2, adds no code: it adds the documentation site, with a checked example for every export, in English and Japanese.
 
 ## Licence
 

package/dist/colour-chains/challenge.d.ts

@@ -1,3 +1,14 @@
 import type { ChallengeOptions, GameState } from './types.js';
-/** Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements. */
+/** Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements.
+ * @example
+ * ```ts
+ * import { createChallenge, levelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const level=levelManifest[0];
+ * console.log(createChallenge({id:level.id,seed:level.seed,width:level.width,height:level.height,colourCount:level.colourCount,board:level.board,queue:level.queue,goal:level.goal,witness:level.witness}).phase);
+ * ```
+ */
 export declare function createChallenge(options: ChallengeOptions): GameState;

package/dist/colour-chains/challenge.js

@@ -57,7 +57,18 @@ function solveWitness(start, witness) {
         throw new StoneChainsOptionsError('witness-does-not-win', 'Witness does not complete the challenge goal within its finite queue');
     return state;
 }
-/** Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements. */
+/** Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements.
+ * @example
+ * ```ts
+ * import { createChallenge, levelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const level=levelManifest[0];
+ * console.log(createChallenge({id:level.id,seed:level.seed,width:level.width,height:level.height,colourCount:level.colourCount,board:level.board,queue:level.queue,goal:level.goal,witness:level.witness}).phase);
+ * ```
+ */
 export function createChallenge(options) {
     if (!options || typeof options !== 'object' || Array.isArray(options))
         throw new StoneChainsOptionsError('invalid-challenge', 'Challenge options must be an object');

package/dist/colour-chains/content-types.d.ts

@@ -1,8 +1,30 @@
 import type { ChallengeGoal, Colour, Gem, Orientation, WitnessStep } from './types.js';
+/** One authored text in English and Japanese.
+ *
+ * @example
+ * ```ts
+ * import type { LocalizedText } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: LocalizedText = {en:"A small puzzle",ja:"小さいパズル"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface LocalizedText {
     readonly en: string;
     readonly ja: string;
 }
+/** The bounded engine measurements used to grade this campaign; they do not claim human difficulty.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { ChainDifficultyMetrics } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const level=levelManifest[0];
+ * const value: ChainDifficultyMetrics = level.rawMetrics;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainDifficultyMetrics {
     readonly placementProbes: number;
     readonly legalPlacements: number;
@@ -63,6 +85,18 @@ export interface ChainDifficultyMetrics {
     /** Number of committed pair placements in the supplied winning plan. */
     readonly planningLength: number;
 }
+/** One authored native challenge with its stable id, setup, winning witness, measurements and review status.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { ChainCampaignLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const level=levelManifest[0];
+ * const value: ChainCampaignLevel = level;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainCampaignLevel {
     readonly id: string;
     readonly number: number;
@@ -91,6 +125,17 @@ export interface ChainCampaignLevel {
     readonly rawDifficultyScore?: number;
     readonly normalizationCategory?: string;
 }
+/** One authored native challenge with its stable id, setup, winning witness, measurements and review status.
+ *
+ * @example
+ * ```ts
+ * import type { NatureChainCampaignLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ * import { shizenLevelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: NatureChainCampaignLevel = shizenLevelManifest[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface NatureChainCampaignLevel extends ChainCampaignLevel {
     readonly objective: LocalizedText;
     readonly nature: true;
@@ -98,6 +143,17 @@ export interface NatureChainCampaignLevel extends ChainCampaignLevel {
     readonly magneticQueue?: readonly (readonly [boolean, boolean])[];
     readonly weatherTrace?: readonly Readonly<Record<string, unknown>>[];
 }
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import type { ChainCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import { campaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: ChainCampaignManifest = campaignManifest;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainCampaignManifest {
     readonly count: number;
     readonly candidatePoolCount: number;
@@ -111,20 +167,65 @@ export interface ChainCampaignManifest {
     readonly checksum: string;
     readonly levels: readonly ChainCampaignLevel[];
 }
+/** An inclusive one-based range in a measured native nature-campaign difficulty band.
+ *
+ * @example
+ * ```ts
+ * import type { NatureCampaignBand } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: NatureCampaignBand = {id:"entry",count:1,first:1,last:1};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface NatureCampaignBand {
     readonly id: 'entry' | 'easy' | 'intermediate' | 'hard' | 'expert';
     readonly count: number;
     readonly first: number;
     readonly last: number;
 }
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import type { NatureChainCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import { shizenCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: NatureChainCampaignManifest = shizenCampaignManifest;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface NatureChainCampaignManifest extends Omit<ChainCampaignManifest, 'levels'> {
     readonly levels: readonly NatureChainCampaignLevel[];
     readonly bands?: readonly NatureCampaignBand[];
 }
+/** One bilingual native lesson instruction and the corresponding action or tick step.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { ChainTutorialStep } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const lesson=tutorialManifest[0];
+ * const value: ChainTutorialStep = lesson.steps[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainTutorialStep {
     readonly instruction: LocalizedText;
     readonly action: string;
 }
+/** One bilingual native lesson with its authored setup, teaching steps and winning witness.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { ChainTutorialDefinition } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const lesson=tutorialManifest[0];
+ * const value: ChainTutorialDefinition = lesson;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainTutorialDefinition {
     readonly id: string;
     readonly title: LocalizedText;
@@ -138,6 +239,17 @@ export interface ChainTutorialDefinition {
     readonly steps: readonly ChainTutorialStep[];
     readonly tags: readonly string[];
 }
+/** The stored native Colour Chains campaign, lessons and optional Shizen/Arashi campaigns.
+ *
+ * @example
+ * ```ts
+ * import type { ChainContentData } from "@johnmorrisdotca/houseki/colour-chains";
+ * import { campaignManifest, tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: ChainContentData = {campaign:campaignManifest,tutorials:tutorialManifest};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainContentData {
     readonly campaign: ChainCampaignManifest;
     readonly tutorials: readonly ChainTutorialDefinition[];