@bilkobibitkov/threewinds-engine 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@ Published under the owner's npm scope; every consumer imports it as `@threewinds
4
4
  alias, so moving to an `@threewinds` org later changes one line per consumer:
5
5
 
6
6
  ```json
7
- "@threewinds/engine": "npm:@bilkobibitkov/threewinds-engine@^0.1.0"
7
+ "@threewinds/engine": "npm:@bilkobibitkov/threewinds-engine@^0.1.1"
8
8
  ```
9
9
 
10
10
  In this monorepo the app uses `"@threewinds/engine": "workspace:@bilkobibitkov/threewinds-engine@*"`.
@@ -30,3 +30,4 @@ React or Node dependencies. Rules: `docs/RULES.md` in the source repo.
30
30
  | `isOver`, `settle` | `settle` returns integer per-seat points summing to 0, none below −400: the win payment plus every kong payment (or the kong payments alone after a draw game), after R9.6. |
31
31
  | `nextDealer(state)` | Extra: the dealer for the next hand under RULES.md R14.1. |
32
32
  | `timeoutAction(state, seat)` | Extra: play for a timed-out human (R4.6): takes a legal win, otherwise passes or discards the tutor's pick. |
33
+ | `deadlineMs(state, seat)` | Extra (added in 0.1.1; 0.1.2 sets the window to 10 s, `CLAIM_WINDOW_MS` 10000): `CLAIM_WINDOW_MS` for every seat while a claim window is open (R4.6), otherwise `undefined`, so the host's turn time applies (R3.5). It reads only the public phase, so a deadline never shows who holds a claim. |
package/dist/game.d.ts CHANGED
@@ -135,6 +135,11 @@ export interface ClaimWindow {
135
135
  /** Claims declared so far via apply(); the window closes once every other seat has declared. */
136
136
  declared: Partial<Record<Seat, Action>>;
137
137
  }
138
+ /**
139
+ * R4.6: the online claim window (Bilko's `deadlineMs`). Every seat that has not declared gets this many
140
+ * ms in any claim window, then auto-passes. The Practice Table has no claim timer: it waits for the player.
141
+ */
142
+ export declare const CLAIM_WINDOW_MS = 10000;
138
143
  export interface GameState {
139
144
  seed: number;
140
145
  dealer: Seat;
package/dist/game.js CHANGED
@@ -8,6 +8,11 @@ export const DEFAULT_RULES = {
8
8
  return { valid: score.valid, deltas: score.valid ? settle(ctx, score, coWinners) : [0, 0, 0], score };
9
9
  },
10
10
  };
11
+ /**
12
+ * R4.6: the online claim window (Bilko's `deadlineMs`). Every seat that has not declared gets this many
13
+ * ms in any claim window, then auto-passes. The Practice Table has no claim timer: it waits for the player.
14
+ */
15
+ export const CLAIM_WINDOW_MS = 10_000;
11
16
  export class IllegalActionError extends Error {
12
17
  seat;
13
18
  action;
package/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  * @threewinds/engine — platform-agnostic rules engine for Three Winds
3
3
  * (Malaysian 3-player mahjong). Must never import DOM, React or React Native.
4
4
  */
5
- export declare const ENGINE_VERSION = "0.1.0";
5
+ export declare const ENGINE_VERSION = "0.1.2";
6
6
  export * from './tiles.js';
7
7
  export * from './wall.js';
8
8
  export * from './seed.js';
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  * @threewinds/engine — platform-agnostic rules engine for Three Winds
3
3
  * (Malaysian 3-player mahjong). Must never import DOM, React or React Native.
4
4
  */
5
- export const ENGINE_VERSION = '0.1.0';
5
+ export const ENGINE_VERSION = '0.1.2';
6
6
  export * from './tiles.js';
7
7
  export * from './wall.js';
8
8
  export * from './seed.js';
package/dist/room.d.ts CHANGED
@@ -23,6 +23,12 @@ export interface RoomGameModule<S> {
23
23
  isOver(state: S): boolean;
24
24
  /** Per-seat points; must be integers summing to 0. */
25
25
  settle(state: S): number[];
26
+ /** Seat that deals the next hand; default (this hand's dealer + 1) % seats. */
27
+ nextDealer?(state: S): number;
28
+ /** Action for a timed-out human seat (connected or not); default aiAction. */
29
+ timeoutAction?(state: S, seat: number): unknown;
30
+ /** Ms a human seat has to act now (null/undefined = turnMs); must not depend on concealed data, since every seat sees when a seat is autoplayed. */
31
+ deadlineMs?(state: S, seat: number): number | null | undefined;
26
32
  }
27
33
  /** Room state: a GameState without its `rules` function, so it is plain JSON data. Server-only. */
28
34
  export type RoomState = Omit<GameState, 'rules'>;
@@ -102,5 +108,12 @@ export interface ThreeWindsRoomModule extends RoomGameModule<RoomState> {
102
108
  * claim window or discards the tutor's pick (R15.5). Never pongs, chows or kongs for them.
103
109
  */
104
110
  timeoutAction(state: RoomState, seat: number): Action;
111
+ /**
112
+ * R4.6: CLAIM_WINDOW_MS (10 s) for every seat while a claim window is open (on a discard or a
113
+ * robbable added kong), else undefined: the host's own turn time. It reads only the public phase,
114
+ * so a seat's deadline never shows whether it holds a claim. Own turns keep the host's time
115
+ * although R3.5 has no own-turn timer offline: a stalled seat would hold up a live table.
116
+ */
117
+ deadlineMs(state: RoomState, seat: number): number | undefined;
105
118
  }
106
119
  export declare const threeWindsRoomModule: ThreeWindsRoomModule;
package/dist/room.js CHANGED
@@ -4,7 +4,7 @@
4
4
  * every action here, plays AI seats with aiAction, and sends each seat only view(state, seat).
5
5
  */
6
6
  import { chooseAction, suggestDiscard } from './ai.js';
7
- import { apply as applyAction, DEFAULT_RULES, handFromDeal, IllegalActionError, legalActions, } from './game.js';
7
+ import { apply as applyAction, CLAIM_WINDOW_MS, DEFAULT_RULES, handFromDeal, IllegalActionError, legalActions, } from './game.js';
8
8
  import { HAND_LOSS_LIMIT } from './scoring.js';
9
9
  import { ALL_KINDS } from './tiles.js';
10
10
  import { dealFromSeed } from './wall.js';
@@ -192,4 +192,10 @@ export const threeWindsRoomModule = {
192
192
  { type: 'discard', tileId: suggestDiscard(g, seat).tileId };
193
193
  return cloneAction(pick);
194
194
  },
195
+ /** R4.6: CLAIM_WINDOW_MS (10 s) while a claim window is open, else undefined (the host's turn time). */
196
+ deadlineMs(state, seat) {
197
+ if (!isSeat(seat))
198
+ throw new RangeError(`seat must be 0, 1 or 2, got ${String(seat)}`);
199
+ return state.phase === 'claim' ? CLAIM_WINDOW_MS : undefined;
200
+ },
195
201
  };
package/dist/scoring.d.ts CHANGED
@@ -73,6 +73,21 @@ export interface FanRule {
73
73
  }
74
74
  /** The 20 rows of RULES.md §7, in design order. Each returns the fan it contributes (0 = not scored). */
75
75
  export declare const FAN_RULES: readonly FanRule[];
76
+ /** One display row of the RULES.md §7 fan table: what the rules drawer lists. */
77
+ export interface FanTableRow {
78
+ /** The FAN_RULES key (F1..F20). */
79
+ key: string;
80
+ /** Fan as printed in RULES.md §7 ("1", "+1", "2", "3"). */
81
+ fan: string;
82
+ /** The item name exactly as in RULES.md §7. */
83
+ item: string;
84
+ }
85
+ /**
86
+ * The fan table for display (rules drawer), one row per FAN_RULES entry in the same order, so a
87
+ * rule added to or removed from the scorer shows up here too. scoring.test.ts checks every row
88
+ * against docs/RULES.md §7.
89
+ */
90
+ export declare const FAN_TABLE: readonly FanTableRow[];
76
91
  export interface LimitRule {
77
92
  key: string;
78
93
  label: string;
package/dist/scoring.js CHANGED
@@ -75,6 +75,40 @@ export const FAN_RULES = [
75
75
  { key: 'F19', label: 'Seven pairs', fan: (v) => (v.sevenPairs ? 1 : 0) },
76
76
  { key: 'F20', label: 'Robbing a kong', fan: (v) => (v.ctx.robbedKong ? 1 : 0) },
77
77
  ];
78
+ /** RULES.md §7 "Fan" and "Item" columns, keyed by rule; FAN_TABLE pairs them with FAN_RULES. */
79
+ const FAN_DISPLAY = {
80
+ F1: ['1', 'Each face tile'],
81
+ F2: ['+1', 'All four faces'],
82
+ F3: ['1', 'Each animal tile'],
83
+ F4: ['+1', 'All four animals'],
84
+ F5: ['1', 'All four flowers'],
85
+ F6: ['1', 'All four seasons'],
86
+ F7: ['1', 'Your own flower or season (East 1, South 2, West 3)'],
87
+ F8: ['1', 'Number-four flower or season'],
88
+ F9: ['1', 'Pong of 東 East. Dealer gets +1'],
89
+ F10: ['1', 'Pong of 北 North'],
90
+ F11: ['1', 'Pong of your own wind'],
91
+ F12: ['1', 'Pong of a dragon'],
92
+ F13: ['3', 'Two dragon pongs and a dragon pair'],
93
+ F14: ['1', 'Mixed one suit (dots + honours)'],
94
+ F15: ['3', 'Pure dots'],
95
+ F16: ['1', 'All chows, with a pair of dots'],
96
+ F17: ['2', 'All pongs'],
97
+ F18: ['1', 'Win on a replacement tile'],
98
+ F19: ['1', 'Seven pairs'],
99
+ F20: ['1', 'Robbing a kong'],
100
+ };
101
+ /**
102
+ * The fan table for display (rules drawer), one row per FAN_RULES entry in the same order, so a
103
+ * rule added to or removed from the scorer shows up here too. scoring.test.ts checks every row
104
+ * against docs/RULES.md §7.
105
+ */
106
+ export const FAN_TABLE = FAN_RULES.map((r) => {
107
+ const d = FAN_DISPLAY[r.key];
108
+ if (!d)
109
+ throw new Error(`FAN_TABLE: no RULES.md §7 row for ${r.key}`);
110
+ return { key: r.key, fan: d[0], item: d[1] };
111
+ });
78
112
  function nineGates(v) {
79
113
  const { concealed, melds } = v.ctx;
80
114
  if (melds.length > 0 || v.flies > 0 || !concealed.every((t) => isDot(t.kind)))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bilkobibitkov/threewinds-engine",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Rules engine for Three Winds, Malaysian 3-player mahjong, plus its Bilko authoritative-room module (threeWindsRoomModule). Imported as @threewinds/engine via an alias.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",