@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# 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.

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,80 @@
-# Temporary Holding Version
+# Houseki · 宝石
 
-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.
+[![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)
+
+Original gem and stone puzzle games with immutable TypeScript rules and a shared English/Japanese player.
+
+**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.
+
+| 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 |
+
+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.
+
+![Falling Triplets demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/falling-triplets-desktop.png)
+
+![Colour Chains demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/colour-chains-desktop.png)
+
+![Gem Swap demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/gem-swap-desktop.png)
+
+![Stone Collapse demo](https://raw.githubusercontent.com/johnmorrisdotca/houseki/main/docs/images/stone-collapse-desktop.png)
+
+[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).
+
+## Design and progression
+
+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.
+
+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.
+
+## Local development
+
+Requires Node.js 22 or newer and pnpm.
+
+```sh
+pnpm install
+pnpm build
+pnpm test
+pnpm demo
+```
+
+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.
+
+## Engine example
+
+The currently reviewed Falling Triplets entry point is independent of DOM, storage and network access:
+
+```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;
+```
+
+The package exposes an entry point for each game. The generated API reference lists every exported function, type and setting.
+
+## Licence
+
+[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).
+
+## Stored tools
+
+[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.
+
+## Package entry points
+
+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.
+
+```ts
+import { colourChains } from '@johnmorrisdotca/houseki';
+const firstChallenge = colourChains.createLevel(1);
+const objective = firstChallenge.settings.goal;
+```
+
+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.

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;