@johnmorrisdotca/domino 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-30
+
+### Added
+
+- Double-nine, double-twelve and double-fifteen sets of dominoes, a tile as a
+  number.
+- Mexican Train for two to eight players: the hub, a train for every player and
+  the Mexican Train, open trains, doubles to cover, blocked rounds and the score
+  over every round, with house rules as options.
+- A computer player, seeded deals that replay exactly, and a saved-game format
+  read back through the rules.
+- Brought from itsutsu.com, and held by its tests to sixty-four games dealt and
+  played out there before the move.

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

@@ -0,0 +1,117 @@
+<h1 align="center">Domino <sub>ドミノ</sub></h1>
+
+<p align="center"><strong>Dominoes and Mexican Train for JavaScript and TypeScript.</strong><br>
+Double-nine, double-twelve and double-fifteen sets; the full rules of Mexican Train for two to eight players; a computer player; seeded deals that replay exactly; and a saved game small enough to keep in a column. No dependencies.</p>
+
+<p align="center">
+  <a href="https://github.com/johnmorrisdotca/domino/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/domino/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/domino"><img alt="npm" src="https://img.shields.io/npm/v/@johnmorrisdotca/domino?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">
+</p>
+
+## In 30 seconds
+
+```sh
+npm install @johnmorrisdotca/domino
+```
+
+```ts
+import { computerMove, encodeTrain, legalPlays, playTrain, startTrain } from "@johnmorrisdotca/domino";
+
+// A double-twelve table for four, a computer in every seat but the first, dealt from seed 2026.
+let game = startTrain(12, ["You", "", "", ""], 2026, undefined, [false, true, true, true])!;
+
+legalPlays(game);                        // every tile you may lay, and on which train
+game = playTrain(game, computerMove(game))!;   // a move: a new game, or null for one the rules refuse
+encodeTrain(game);                       // the whole game as a short text, to keep and read back
+```
+
+## Who it is for
+
+- **Game sites and apps** that want a domino table with the rules already right,
+  a computer for any empty seat, and games that can be saved and resumed.
+- **Anyone writing a domino game of their own**, who wants the set, the tiles
+  and their ends as plain numbers and pure functions to build on.
+
+## Mexican Train
+
+A hub double in the middle, a train out of it for every player, and one more,
+the Mexican Train, that anybody may add to. Rounds count down from the set's
+highest double, the hub, to the blank; whoever goes out first ends the round, and
+the fewest pips over the whole game wins.
+
+- **Sets**: double-nine (55 tiles), double-twelve (91, the usual one) and
+  double-fifteen (136), with the hand size for each set and number of players.
+- **House rules**, as options: `length` (`full`, every round, or `short`),
+  `doubles` (`one`: a double laid must be covered next, or `chain`), and
+  `mexican` (`any`: anyone may start the Mexican Train, or `ownFirst`).
+- **Trains open and close**: a player who cannot lay draws, and if still stuck
+  marks their train open for everyone until they next lay on it.
+- **A blocked round** ends when nobody can lay and nothing is left to draw.
+- **A computer player** (`computerMove`) that lays its longest run on its own
+  train and plays doubles well, in a few milliseconds.
+- **Saved games**: `encodeTrain` and `decodeTrain` write and read a game as
+  text, and reading trusts nothing: every move is played again through the
+  rules, and a changed save is refused.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `startTrain(set, players, seed?, options?, computers?)` | A new game, or null for a table the rules do not allow |
+| `playTrain(game, move)` | The game after a move, or null for a move the rules refuse |
+| `trainMoves`, `legalPlays`, `mayLay`, `openEnd`, `mexicanOf` | What may be played, and where |
+| `computerMove(game)`, `longestRun(hand, end)` | The computer's move, and the run it plans |
+| `encodeTrain`, `decodeTrain`, `replayTrain`, `movesOf`, `moveCount` | Saving a game, reading it back, and replaying its moves |
+| `trainTotals`, `handPips`, `trainAgain`, `trainPlayerName`, `peopleAt`, `cleanTrainName` | Scores, a fresh deal at the same table, and the seats |
+| `tileOf`, `endsOf`, `isDouble`, `pipsOf`, `fits`, `laidAgainst`, `laidEnds`, `tileOfLaid`, `everyTile`, `tileWords` | Tiles as numbers: making, reading and laying them |
+| `TRAIN_SETS`, `TRAIN_SET_NAMES`, `trainSetName`, `handSizeFor`, `roundsFor`, `TRAIN_DEFAULT_OPTIONS`, `TRAIN_LENGTHS`, `TRAIN_DOUBLES`, `TRAIN_MEXICAN`, `TRAIN_PHASES`, `TRAIN_PIP_BASE`, `TRAIN_NAME_MOST` | The vocabulary and the limits |
+| `seededRandom(seed)`, `shuffled(items, random)` | The seeded stream every deal is made from |
+| `TrainGame`, `TrainMove`, `TrainOptions`, `Domino`, … | The types |
+| `VERSION` | This package's version |
+
+A tile is a number, `a × 16 + b` with `a ≤ b` (`TRAIN_PIP_BASE`), so a hand is
+an array of numbers and a game is plain data that can be stored or sent as it is.
+
+## The name
+
+*Domino* is ドミノ (domino), the word Japanese uses for dominoes, borrowed from
+the European game as English borrowed it.
+
+## Where it comes from, and where it is used
+
+Domino was written for [itsutsu.com](https://itsutsu.com), a site of games
+played with friends and family, where Mexican Train is played at one device or
+several. Every deal and every computer game there before the move is held by
+this package's tests, so a game kept on the site replays exactly.
+
+Using it somewhere? [Tell us](https://github.com/johnmorrisdotca/domino/issues/new?title=Add+my+project).
+
+### The family
+
+- [Korokoro](https://github.com/johnmorrisdotca/korokoro): dice, with exact odds and real sounds
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu): a turning cube, with a solve you can follow
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu): playing cards and ten card games, and three solitaires
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu): a colour-card game in the manner of UNO
+- [Tane](https://github.com/johnmorrisdotca/tane): seeded random numbers and daily seeds
+- [Narabe](https://github.com/johnmorrisdotca/narabe): a rules engine for board games of the five-in-a-row family and more
+- [Tenka](https://github.com/johnmorrisdotca/tenka): a game of world conquest
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji): a crossword tile race
+
+## Roadmap
+
+- A demo site, playable in the browser, in the family's look, with English and Japanese
+- The words for the table in English and Japanese, and a React hook
+- More domino games: Block, Draw, All Fives and Chicken Foot
+
+Left out on purpose: anything played for stakes, and play over a network, which
+needs a server. A game here is plain data, so your own server can carry it.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Licence
+
+MIT © John Morris

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/** Domino: double-nine, double-twelve and double-fifteen sets of dominoes, and Mexican Train with a computer player and a saved-game format. */
+export * from "./mexicanTrain/dominoes.ts";
+export * from "./mexicanTrain/mexicanTrain.constants.ts";
+export * from "./mexicanTrain/mexicanTrain.ts";
+export type * from "./mexicanTrain/mexicanTrain.types.ts";
+export * from "./mexicanTrain/trainComputer.ts";
+export * from "./mexicanTrain/trainCodec.ts";
+export { seededRandom, shuffled } from "./random.ts";
+export type { Random } from "./random.ts";
+export { VERSION } from "./version.ts";

package/dist/index.js

@@ -0,0 +1,8 @@
+/** Domino: double-nine, double-twelve and double-fifteen sets of dominoes, and Mexican Train with a computer player and a saved-game format. */
+export * from "./mexicanTrain/dominoes.js";
+export * from "./mexicanTrain/mexicanTrain.constants.js";
+export * from "./mexicanTrain/mexicanTrain.js";
+export * from "./mexicanTrain/trainComputer.js";
+export * from "./mexicanTrain/trainCodec.js";
+export { seededRandom, shuffled } from "./random.js";
+export { VERSION } from "./version.js";

package/dist/mexicanTrain/dominoes.d.ts

@@ -0,0 +1,27 @@
+import type { Domino, LaidDomino } from "./mexicanTrain.types.ts";
+/**
+ * DOMINOES AS NUMBERS: a tile is `low * 16 + high`, a tile laid in a train
+ * `from * 16 + to` (see `mexicanTrain.types.ts`). Small, pure helpers the
+ * rules, the computer player and the drawing all read, so that none of them
+ * pulls a number apart its own way.
+ */
+/** The tile with these two ends, whichever order they are given in. */
+export declare function tileOf(a: number, b: number): Domino;
+/** A tile's two ends, the smaller first. */
+export declare function endsOf(tile: Domino): [number, number];
+/** Both ends the same: a double, which is laid across a train and must be covered. */
+export declare function isDouble(tile: Domino): boolean;
+/** Every pip on a tile: what it counts against its holder when a round ends. */
+export declare function pipsOf(tile: Domino): number;
+/** Whether a tile has this number at either end, so it can be laid against it. */
+export declare function fits(tile: Domino, end: number): boolean;
+/** The tile laid against `end`: turned so that end touches, the other one left open. */
+export declare function laidAgainst(tile: Domino, end: number): LaidDomino;
+/** A laid tile's two ends in the order it lies: the one touching the train, then the open one. */
+export declare function laidEnds(laid: LaidDomino): [number, number];
+/** The tile a laid tile is, whichever way round it lies. */
+export declare function tileOfLaid(laid: LaidDomino): Domino;
+/** Every tile of a set, double-blank to its highest double, in order. */
+export declare function everyTile(set: number): Domino[];
+/** A tile as a person reads it: "6–4", the larger end first, as a tile is named at the table. */
+export declare function tileWords(tile: Domino): string;

package/dist/mexicanTrain/dominoes.js

@@ -0,0 +1,58 @@
+// Relative, like the rest of lib/party: the browser specs import this, and Playwright resolves no alias.
+import { TRAIN_PIP_BASE } from "./mexicanTrain.constants.js";
+/**
+ * DOMINOES AS NUMBERS: a tile is `low * 16 + high`, a tile laid in a train
+ * `from * 16 + to` (see `mexicanTrain.types.ts`). Small, pure helpers the
+ * rules, the computer player and the drawing all read, so that none of them
+ * pulls a number apart its own way.
+ */
+/** The tile with these two ends, whichever order they are given in. */
+export function tileOf(a, b) {
+    return a <= b ? a * TRAIN_PIP_BASE + b : b * TRAIN_PIP_BASE + a;
+}
+/** A tile's two ends, the smaller first. */
+export function endsOf(tile) {
+    return [Math.floor(tile / TRAIN_PIP_BASE), tile % TRAIN_PIP_BASE];
+}
+/** Both ends the same: a double, which is laid across a train and must be covered. */
+export function isDouble(tile) {
+    const [low, high] = endsOf(tile);
+    return low === high;
+}
+/** Every pip on a tile: what it counts against its holder when a round ends. */
+export function pipsOf(tile) {
+    const [low, high] = endsOf(tile);
+    return low + high;
+}
+/** Whether a tile has this number at either end, so it can be laid against it. */
+export function fits(tile, end) {
+    const [low, high] = endsOf(tile);
+    return low === end || high === end;
+}
+/** The tile laid against `end`: turned so that end touches, the other one left open. */
+export function laidAgainst(tile, end) {
+    const [low, high] = endsOf(tile);
+    return low === end ? low * TRAIN_PIP_BASE + high : high * TRAIN_PIP_BASE + low;
+}
+/** A laid tile's two ends in the order it lies: the one touching the train, then the open one. */
+export function laidEnds(laid) {
+    return [Math.floor(laid / TRAIN_PIP_BASE), laid % TRAIN_PIP_BASE];
+}
+/** The tile a laid tile is, whichever way round it lies. */
+export function tileOfLaid(laid) {
+    const [from, to] = laidEnds(laid);
+    return tileOf(from, to);
+}
+/** Every tile of a set, double-blank to its highest double, in order. */
+export function everyTile(set) {
+    const tiles = [];
+    for (let low = 0; low <= set; low += 1)
+        for (let high = low; high <= set; high += 1)
+            tiles.push(tileOf(low, high));
+    return tiles;
+}
+/** A tile as a person reads it: "6–4", the larger end first, as a tile is named at the table. */
+export function tileWords(tile) {
+    const [low, high] = endsOf(tile);
+    return `${high}–${low}`;
+}

package/dist/mexicanTrain/mexicanTrain.constants.d.ts

@@ -0,0 +1,42 @@
+import type { TrainLength, TrainOptions } from "./mexicanTrain.types.ts";
+/**
+ * THE SETS OFFERED, by their highest double. Double-twelve is the set Mexican
+ * Train is sold with and the one most published rules are written for, so it
+ * is the default; double-nine for a quicker game with fewer, larger pips, and
+ * double-fifteen for a long evening. These are the party game's "sizes"
+ * (`PARTY_SPECS`), since the set is what the table is played on.
+ */
+export declare const TRAIN_SETS: {
+    readonly nine: 9;
+    readonly twelve: 12;
+    readonly fifteen: 15;
+};
+/** The largest set's highest double, and so the base a tile's two ends are written in (`tileOf`). */
+export declare const TRAIN_PIP_BASE = 16;
+/**
+ * HOW MANY TILES EACH PLAYER IS DEALT, by the set and the number at the
+ * table. Double-twelve's are the figures most published rules give (fifteen
+ * each for two to four, twelve for five or six, ten for seven or eight); the
+ * other sets are scaled so that at every table some tiles are left to draw.
+ */
+export declare function handSizeFor(set: number, players: number): number;
+/** The options a table opens on: every round, one double at a time, and the Mexican Train open from the start. */
+export declare const TRAIN_DEFAULT_OPTIONS: TrainOptions;
+export declare const TRAIN_LENGTHS: {
+    readonly full: "full";
+    readonly short: "short";
+};
+export declare const TRAIN_DOUBLES: {
+    readonly one: "one";
+    readonly chain: "chain";
+};
+export declare const TRAIN_MEXICAN: {
+    readonly any: "any";
+    readonly ownFirst: "ownFirst";
+};
+/** How many rounds a game of this length plays with this set: one per double, top to blank, or the first half of them. */
+export declare function roundsFor(set: number, length: TrainLength): number;
+/** Each set by name, for the set-up's tiles and the card on My games. */
+export declare const TRAIN_SET_NAMES: Record<number, string>;
+/** The set's name, or null for a number that is no set offered. */
+export declare function trainSetName(set: number): string | null;

package/dist/mexicanTrain/mexicanTrain.constants.js

@@ -0,0 +1,40 @@
+/**
+ * THE SETS OFFERED, by their highest double. Double-twelve is the set Mexican
+ * Train is sold with and the one most published rules are written for, so it
+ * is the default; double-nine for a quicker game with fewer, larger pips, and
+ * double-fifteen for a long evening. These are the party game's "sizes"
+ * (`PARTY_SPECS`), since the set is what the table is played on.
+ */
+export const TRAIN_SETS = { nine: 9, twelve: 12, fifteen: 15 };
+/** The largest set's highest double, and so the base a tile's two ends are written in (`tileOf`). */
+export const TRAIN_PIP_BASE = 16;
+/**
+ * HOW MANY TILES EACH PLAYER IS DEALT, by the set and the number at the
+ * table. Double-twelve's are the figures most published rules give (fifteen
+ * each for two to four, twelve for five or six, ten for seven or eight); the
+ * other sets are scaled so that at every table some tiles are left to draw.
+ */
+export function handSizeFor(set, players) {
+    const few = players <= 4;
+    const some = players <= 6;
+    if (set === TRAIN_SETS.nine)
+        return few ? 10 : some ? 8 : 6;
+    if (set === TRAIN_SETS.fifteen)
+        return few ? 15 : some ? 13 : 12;
+    return few ? 15 : some ? 12 : 10;
+}
+/** The options a table opens on: every round, one double at a time, and the Mexican Train open from the start. */
+export const TRAIN_DEFAULT_OPTIONS = { length: "full", doubles: "one", mexican: "any" };
+export const TRAIN_LENGTHS = { full: "full", short: "short" };
+export const TRAIN_DOUBLES = { one: "one", chain: "chain" };
+export const TRAIN_MEXICAN = { any: "any", ownFirst: "ownFirst" };
+/** How many rounds a game of this length plays with this set: one per double, top to blank, or the first half of them. */
+export function roundsFor(set, length) {
+    return length === TRAIN_LENGTHS.full ? set + 1 : Math.ceil((set + 1) / 2);
+}
+/** Each set by name, for the set-up's tiles and the card on My games. */
+export const TRAIN_SET_NAMES = { 9: "Double-nine", 12: "Double-twelve", 15: "Double-fifteen" };
+/** The set's name, or null for a number that is no set offered. */
+export function trainSetName(set) {
+    return TRAIN_SET_NAMES[set] ?? null;
+}

package/dist/mexicanTrain/mexicanTrain.d.ts

@@ -0,0 +1,92 @@
+import type { Domino, TrainGame, TrainMove, TrainOptions, TrainSeat } from "./mexicanTrain.types.ts";
+/**
+ * MEXICAN TRAIN, THE DOMINO GAME: the rules, and nothing else.
+ *
+ * Pure, as the engine is: every function returns a new game and leaves the
+ * one it was given untouched. A game is its table (the set, the options, the
+ * seed, the seats) and its moves, in order; hands, trains, the boneyard and
+ * whose turn it is are always read again from those (`replayTrain`), so a game
+ * read back out of a browser's storage is exactly the game its moves make,
+ * or none. Every shuffle is drawn from the game's seed and the round's
+ * number, so a reload deals exactly what it dealt before.
+ *
+ * The rules as the site plays them, most published rules' own:
+ *
+ *  - a round is dealt round the engine double, the set's highest in the
+ *    first round and one fewer each round after, which sits in the hub;
+ *  - every player has a train of their own out of the hub, and there is one
+ *    more, the Mexican Train, anybody may play on;
+ *  - on your turn lay one tile against the open end of your own train, the
+ *    Mexican Train, or any player's train whose marker is out;
+ *  - nothing to lay: draw one tile; lay it if it goes, or put your marker out
+ *    and pass (with nothing to draw, just put it out); lay on your own train
+ *    and your marker comes in;
+ *  - a double must be covered before anything else is played anywhere, and
+ *    whoever lays one lays again to cover it (`DoublesRule` for the house
+ *    rule that lets doubles be chained);
+ *  - a round ends when somebody lays their last tile, or when nobody can lay
+ *    and there is nothing left to draw; every player scores the pips left in
+ *    their hand, and after the last round the lowest total wins.
+ */
+export declare const TRAIN_PHASES: {
+    readonly playing: "playing";
+    readonly roundOver: "roundOver";
+    readonly finished: "finished";
+};
+/** The longest name a seat keeps. */
+export declare const TRAIN_NAME_MOST = 20;
+/** A seat's name as given, its spaces tidied and cut to `TRAIN_NAME_MOST` characters. */
+export declare function cleanTrainName(name: string): string;
+/** The Mexican Train's number among a game's trains: after every seat's own. */
+export declare function mexicanOf(game: Pick<TrainGame, "players">): number;
+/** The number a train's next tile must match: its last tile's open end, or the engine double's when nothing is laid on it yet. */
+export declare function openEnd(game: TrainGame, train: number): number;
+/**
+ * A new game: the set (its highest double), the names at the table (one a
+ * seat), which seats a computer plays, the options, and the seed every
+ * shuffle is drawn from. Null for a table the game is not offered for — a set
+ * not in `PARTY_SPECS`, or too few or too many players — rather than a game
+ * nobody chose.
+ */
+export declare function startTrain(set: number, players: readonly string[], seed?: number, options?: TrainOptions, computers?: readonly boolean[]): TrainGame | null;
+/**
+ * Every tile the player to move may lay, and where: what `moves` offers, and
+ * what the table lights up. While a double is uncovered anywhere the only
+ * lay is to cover the last of them, on whoever's train it is — or, under the
+ * chained-doubles rule, another double laid by the player still laying them.
+ */
+export declare function legalPlays(game: TrainGame): {
+    tile: Domino;
+    train: number;
+}[];
+/**
+ * Whether the player to move may lay this tile on this train now: the same
+ * answer `legalPlays` gives, for one tile, without listing every other.
+ */
+export declare function mayLay(game: TrainGame, tile: Domino, train: number): boolean;
+/** Every move the player to move may make now; none once the game is over. */
+export declare function trainMoves(game: TrainGame): TrainMove[];
+/** Every move a game has made, first to last. */
+export declare function movesOf(game: Pick<TrainGame, "history">): TrainMove[];
+/** How many moves a game has made. */
+export declare function moveCount(game: Pick<TrainGame, "history">): number;
+/** Each seat's total over every round played: the lowest wins. */
+export declare function trainTotals(game: Pick<TrainGame, "players" | "results">): number[];
+/** The pips in a hand, which count against its holder when the round ends. */
+export declare function handPips(hand: readonly Domino[]): number;
+/**
+ * The game after that move, or null for a move that may not be made now.
+ * The game given is left untouched, and the move is added to its record.
+ */
+export declare function playTrain(game: TrainGame, move: TrainMove): TrainGame | null;
+/**
+ * A game played again from its table and its moves: what reading a kept game
+ * back does. Null if any move is one the rules would not have taken.
+ */
+export declare function replayTrain(set: number, players: readonly string[], seed: number, options: TrainOptions, computers: readonly boolean[], moves: readonly TrainMove[]): TrainGame | null;
+/** The same table again, the same seats and options, with a fresh shuffle. */
+export declare function trainAgain(game: TrainGame, seed: number): TrainGame;
+/** A seat's name as the table reads it: the one given, or "Computer 3" for a computer's seat left blank, "Player 3" for a person's. */
+export declare function trainPlayerName(game: Pick<TrainGame, "players" | "computers">, seat: TrainSeat): string;
+/** The seats a person plays: a table with two or more of them passes the device, and covers each hand between turns. */
+export declare function peopleAt(game: Pick<TrainGame, "computers">): TrainSeat[];