@johnmorrisdotca/houseki 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,273 @@
-# Temporary Holding Version
+<h1 align="center">Houseki <sub>宝石</sub></h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<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>
+
+<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>
+
+<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>
+
+<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.
+
+## In 30 seconds
+
+```sh
+npm install @johnmorrisdotca/houseki
+```
+
+```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;
+```
+
+Every engine is a path of its own, and the main entry groups them by game:
+
+```ts
+import { colourChains } from "@johnmorrisdotca/houseki";
+
+const firstChallenge = colourChains.createLevel(1);
+const goal = firstChallenge.settings.goal;
+```
+
+Or straight from a page, with nothing to build:
+
+```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>
+```
+
+## Who it is for
+
+- **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.
+
+## Features
+
+- **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 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, 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
+```
+
+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.
+
+## API
+
+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.
+
+## Theming
+
+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.
+
+## Limits
+
+| 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
+```
+
+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/challenge.d.ts

@@ -0,0 +1,3 @@
+import type { ChallengeOptions, GameState } from './types.js';
+/** Validates and creates a finite witnessed challenge. Hints use only the supplied verified pair placements. */
+export declare function createChallenge(options: ChallengeOptions): GameState;

package/dist/colour-chains/challenge.js

@@ -0,0 +1,120 @@
+import { applyAction, advanceTicks, initialChallengeState } from './engine.js';
+import { StoneChainsOptionsError, validateChallengeGoal, validateSize } from './validation.js';
+const COLOUR_NAMES = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
+const ORIENTATIONS = ['up', 'right', 'down', 'left'];
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+function solveWitness(start, witness) {
+    let state = start;
+    let work = 0;
+    const act = (kind) => {
+        const result = applyAction(state, { kind });
+        if (!result.accepted)
+            throw new StoneChainsOptionsError('invalid-witness', `Witness action ${kind} was rejected: ${result.reason}`);
+        state = result.state;
+        if (++work > 100_000)
+            throw new StoneChainsOptionsError('witness-work-limit', 'Challenge witness exceeds bounded verification work');
+    };
+    for (let stepIndex = 0; stepIndex < witness.length; stepIndex++) {
+        const step = witness[stepIndex];
+        if (state.phase !== 'falling' || !state.active)
+            break;
+        const rotateToward = (target) => {
+            for (let count = 0; state.active.orientation !== target && count < 4; count++)
+                act('rotate-clockwise');
+            if (state.active.orientation !== target)
+                throw new StoneChainsOptionsError('invalid-witness', `Witness step ${stepIndex + 1} cannot reach its orientation`);
+        };
+        for (let count = 0; state.active.pivot.x !== step.pivotX && count < 12; count++)
+            act(state.active.pivot.x < step.pivotX ? 'right' : 'left');
+        if (state.active.pivot.x !== step.pivotX)
+            throw new StoneChainsOptionsError('invalid-witness', `Witness step ${stepIndex + 1} cannot reach its pivot column`);
+        rotateToward(step.orientation);
+        for (let count = 0; state.active.pivot.x !== step.pivotX && count < 12; count++)
+            act(state.active.pivot.x < step.pivotX ? 'right' : 'left');
+        if (state.active.pivot.x !== step.pivotX)
+            throw new StoneChainsOptionsError('invalid-witness', `Witness step ${stepIndex + 1} cannot finish at its pivot column`);
+        act('hard-drop');
+        while (['clear-mark', 'clear-remove', 'gravity'].includes(state.phase) && work < 100_000) {
+            const result = advanceTicks(state, 3600);
+            state = result.state;
+            work += 3600;
+        }
+        if (state.phase === 'lost' || state.phase === 'finished')
+            throw new StoneChainsOptionsError('invalid-witness', `Witness ends before its goal after pair ${stepIndex + 1}`);
+        if (state.phase === 'won') {
+            if (stepIndex !== witness.length - 1)
+                throw new StoneChainsOptionsError('witness-after-goal', 'Witness must stop at the first completed goal');
+            return state;
+        }
+    }
+    if (state.phase !== 'won')
+        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. */
+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'];
+    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))
+        throw new StoneChainsOptionsError('invalid-challenge-id', 'Challenge ID must be stable lowercase text');
+    const width = options.width ?? 6;
+    const height = options.height ?? 12;
+    validateSize(width, height);
+    const colourCount = options.colourCount ?? 4;
+    if (colourCount !== 4 && colourCount !== 5 && colourCount !== 6)
+        throw new StoneChainsOptionsError('invalid-colour-count', 'Challenge colour count must be 4, 5 or 6');
+    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 (!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)
+        throw new StoneChainsOptionsError('invalid-challenge-queue', 'Challenge queue must contain 2–12 pairs');
+    const allowedColours = COLOUR_NAMES.slice(0, colourCount);
+    const ids = new Set();
+    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))
+            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 });
+    });
+    for (let x = 0; x < width; x++) {
+        let gap = false;
+        for (let y = height - 1; y >= 0; y--) {
+            if (board[y * width + x] === null)
+                gap = true;
+            else if (gap)
+                throw new StoneChainsOptionsError('unstable-challenge-board', `Starting column ${x} is not gravity-stable`);
+        }
+    }
+    const queue = options.queue.map((pair, index) => {
+        if (!Array.isArray(pair) || pair.length !== 2 || pair.some(colour => !allowedColours.includes(colour)))
+            throw new StoneChainsOptionsError('invalid-challenge-pair', `Invalid queue pair ${index + 1}`);
+        return 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');
+    const witness = options.witness.map((step, index) => {
+        if (!step || typeof step !== 'object' || Array.isArray(step) || Object.keys(step).some(key => key !== 'pivotX' && key !== 'orientation') || !Number.isInteger(step.pivotX) || step.pivotX < 0 || step.pivotX >= width || !ORIENTATIONS.includes(step.orientation))
+            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 state = initialChallengeState(settings, settings.initialBoard, settings.queue);
+    const solved = solveWitness(state, witness);
+    if (solved.phase !== 'won' || stable(solved.settings) !== stable(settings))
+        throw new StoneChainsOptionsError('invalid-witness', 'Challenge witness validation failed');
+    return state;
+}

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

@@ -0,0 +1,2 @@
+import type { ChainContentData } from './content-types.js';
+export declare const contentData: ChainContentData;