collin/mahjong

f55b8ad0e3652a507739502125725eeed521af0a / README.md

1	# 台灣麻將 — four-player mahjong, on one touchscreen or over the wire
2
3	Sixteen-tile Taiwanese mahjong for four people sitting around a single laptop.
4	All four hands are on screen at once, each rotated to face its own edge — put a
5	piece of card or plastic over your strip so the others can't see your tiles.
6	Every label is Chinese with English underneath; the tiles themselves stay
7	Chinese, because that is what the tiles say.
8
9	Nobody else around? 單人對局 Single player on the lobby gives you the
10	bottom seat and hands the other three to the computer — same rules, same
11	table, same scoring. See [computer players](#computer-players).
12
13	Friends elsewhere? 線上對戰 Online game puts everyone at the same table
14	from their own devices, and 手機派對 Party mode keeps the laptop as the
15	table while phones scan a QR to hold their own tiles — see
16	[playing online](#playing-online).
17
18	```
19	npm install
20	npm run dev # then open the browser full-screen (F11)
21	npm test # rules engine, the bots, and 200 randomly-played hands
22	```
23
24	## Screen layout
25
26	```
27	┌──── 對家 (rotated 180°) ────┐
28	上家 (rotated 90°) │ wall, and the discard pool │ 下家 (rotated −90°)
29	└──── 自家 (upright, near you) ┘
30	```
31
32	Seat 0 is the bottom edge, and play runs 0 → 1 (right) → 2 (top) → 3 (left),
33	which is the normal counter-clockwise 東南西北 order.
34
35	Each strip shows, from the player's edge inwards: nameplate (seat wind, 莊
36	marker, 聽 badge, chip count) → concealed hand → action buttons → melds and
37	flowers. Discards are not in the strips: they are thrown into the middle and
38	stay there for the hand, the way they would be on a table. (A phone has no
39	middle to throw into, so the compact layout keeps a discard row per seat — see
40	[on a phone](#on-a-phone).)
41
42	## Playing
43
44	- The tile you just drew is held apart from the sorted hand with a gold ring
45	and a 摸 label, instead of being sorted invisibly into it. It merges into the
46	hand once you discard. 補花 replacements and kong replacements are marked the
47	same way.
48	- The wall is drawn in the centre as a square of four staggered sides, laid
49	out like a `#` with the corners open, the way it's built on a real table. The
50	gold stack is the break point you draw from, stacks shrink to a single tile and
51	then vanish as they're used, and the dimmed tail is the 16-tile 底牌 that ends
52	the hand — which is also the end kong and flower replacements are taken from,
53	so the square is eaten from both directions at once. Only what is still
54	standing is drawn, and it is evened up over the four sides as it goes, which
55	is what lets every tile left in it be the size of a tile in your hand — see
56	[what is left of the wall](#what-is-left-of-the-wall).
57	- Discard — drag a tile out of your row and it comes up out of your hand and
58	follows your finger anywhere on the table; let go and it goes in, from where
59	you let go and at the speed you let go at. Dragging along the row is still
60	arranging your hand — which of the two you meant is decided once, from whether
61	the movement is mostly along the row or out of it, and then it sticks. Let go
62	back over your own hand and the tile goes back. Tapping a tile twice, or the
63	打出 button, still works and lobs it in for you.
64	- The discard pool — every tile thrown lands in the middle and stays there
65	until the hand ends, with real weight: it skids, turns, knocks the tiles
66	already there out of its way, and comes to rest against them. Nothing is ever
67	stacked on anything — tiles are solved as rectangles, so two lying at an angle
68	lean on each other rather than overlapping. The tile still to be claimed is
69	the lit one.
70	- Over the wall or across the table — which of the two ways a tile goes in is
71	not a setting, it is whatever the wall allows. At the start of a hand the
72	square is a solid barrier and a discard has to be lobbed over it, so the
73	flick's speed decides how far across the pool it lands. As the wall is eaten
74	away, gaps open in front of one seat and then another, and from then on that
75	seat can slide a tile in instead — flat across the cloth at exactly the speed
76	it was flicked. Which it will be is a ray cast at the stacks actually standing
77	there, so a gap off to one side counts, and a stack worn down to a single tile
78	is low enough to go over. A seat whose wall is still up says 牆未開 on its
79	nameplate, so a lob is never a mystery.
80	- Throw it badly and it ends up in somebody's tiles — the middle stops
81	exactly where their hand starts, so a tile that comes off the pool arrives in
82	their lap, and one that falls short lands out by their seat. Either way their
83	row takes the knock and rocks back, and with 報牌 on they tell you about it —
84	喂，小心點 if you are lucky, 是在哈囉 or 你牌品很差欸 if you are not, and
85	never the same line twice running. How hard it got there only decides how
86	loudly. Never your own edge: you cannot be barged by your own discard.
87	- Arranging — drag any tile in your hand to reorder it; 理牌 sorts it back
88	into suit order. Hands are never auto-sorted after the deal, so an arrangement
89	you set up survives draws, claims and kongs.
90	- Rules — the `?` on your nameplate opens a bilingual rules panel anchored to
91	your own edge of the table and rotated to face you.
92	- Claiming — after a discard, every seat that can claim gets 胡 / 槓 / 碰 /
93	吃 / 過 buttons on their own strip, and they resolve by priority (胡 > 槓/碰 >
94	吃; ties go to the player nearest the discarder in turn order).
95	The table never blocks on a claim. The next player gets a 摸牌 button and
96	may draw whenever they like, which shuts the window on anyone who hasn't
97	called — exactly like shouting 碰 before the next player picks up. A claim
98	already declared still stands, so calling in time always wins the tile. If
99	everyone answers first, play advances on its own without the extra tap.
100	The seat that draws next gets no separate 過 button, because for them the two
101	are the same move: picking up is how you decline. Their draw button reads
102	過．摸牌 while they have something they could have called instead. Wanting to
103	decline but leave the window open for everyone else is just waiting, which is
104	what not pressing anything already does.
105	- On your turn — 自摸, 暗槓 and 加槓 appear automatically when legal.
106	加槓 offers everyone else a 搶槓 chance.
107	- Where the buttons go — the strip is built from its edge inwards, so the
108	action bar holds a fixed height whether or not anything is in it. Otherwise
109	the melds above it shuffled along every time you lifted a tile
110	and 打出五萬 appeared, since a button naming a tile stands taller than a bare
111	過. Every button on the bar is given that one height for the same reason.
112	- When a hand ends — a big arrow drops onto the winner's edge of the table.
113	It lives inside their strip, so it turns with the seat and lands on the right
114	person wherever they are sitting, and 一炮多響 lights up every seat that
115	called. A 流局 has no winner to point at, so it turns the hands over instead:
116	who was 聽牌 and the tiles they were waiting on, the same reveal as at a real
117	table.
118	- Undo — a 復原 button in the middle of the table takes back the last
119	action, naming what it will undo (`復原玩家 2 打五萬`). It sits in the
120	centre rather than on a seat because whoever spots the mis-tap should be
121	able to reach it. Twenty actions deep, cleared when the next hand is dealt.
122	Snapshots live outside the saved state, so an undo does not survive a
123	refresh: what you can take back is what happened while everyone was still
124	watching it happen.
125	- Sound — on by default, muted from the 🔊 button in the middle of the
126	table or from settings. A dry clack as a tile goes down, and a distinct
127	two-note chime when a claim window opens, which is how a slow player notices
128	their 碰 is available before the next player draws it shut. Everything is
129	synthesised with a few oscillators (`src/game/sound.ts`) rather than sampled,
130	so there is nothing to load and the cue lands on the same frame as the tile.
131	Browsers refuse to start audio before the page has been clicked, so the first
132	sound anyone hears is the deal — triggered by the button that starts it.
133	- 報牌 (voice) — a second switch under sound calls the game out loud: 碰,
134	吃, 槓, 胡了, 自摸, and the name of every tile as it is discarded — 三條,
135	五萬, 東風. A flower says 補花 and then which one. A new call cuts off one
136	still being spoken; at table pace the newest is the only one that matters.
137	See [the voice pack](#the-voice-pack) for where the audio comes from.
138	- Settings — 設定 from the lobby, or from the game-over panel: player names,
139	底 / 台 / starting chips, the house-rule switches below, and sound. Kept in
140	`localStorage` separately from the save, so they carry over to the next game.
141	Stakes are locked once a game is under way — they'd otherwise rewrite chips
142	already won.
143
144	## Playing online
145
146	Two networked modes, both built on a room relay of our own — `server/rooms.ts`,
147	a couple hundred lines of Node on `ws`. The relay knows nothing about mahjong:
148	rooms with codes, host election by join order, one bag of shared state only the
149	host may write, and events fanned out to everyone else. One client — the
150	host — runs the engine, publishes the whole `GameState` as room state after
151	every move, and plays intents the other devices send as events. The engine was
152	already a pure JSON state machine, so nothing in `src/game/` knows the network
153	exists — the same trick `autoplay.ts` plays, stretched over a wire. The client
154	end of the wire is `src/net/room.ts`; the rest of `src/net/` is the game
155	riding it.
156
157	- 線上對戰 Online game — everyone on their own device. Whoever opens the
158	room picks 線上對戰 and gets a seat lobby; friends who open the same link
159	land in it, sit down, and the host deals. Empty seats go to the computer,
160	which runs on the host client — that is what stands in for a server on the
161	classic (free) tier. Each screen draws the same full table, turned so your
162	own seat is the bottom edge; other people's tiles are face down. Joining
163	mid-game takes over a vacant or computer seat, so a dropped friend can
164	reload and carry on.
165	- 手機派對 Party mode — the laptop stays the table, exactly like hotseat,
166	and each seat's corner of the felt wears a QR. Scanning one loads a
167	controller on the phone: just that hand, face up, with the claim buttons —
168	and the throw. Flick a tile up off the top of the phone and it sails in from
169	your edge of the common screen, at the speed and angle you let go of it
170	(`NetThrow`, mapped into table coordinates by `TablePool.throwFromNet`). The
171	seat's tiles go face down on the shared screen and its QR hides; hold the 📱
172	tag on the nameplate to show it again for a player who lost theirs. A phone
173	that leaves hands the seat back to the laptop. Seats never lock: a second
174	phone scanning the same QR joins the same hand — two people playing one
175	hand, whoever acts first acts.
176
177	Design notes, in the order they bit:
178
179	- Seats are claims on a shared map, `seats: {ids, name}[]` in room state,
180	arbitrated by the host. Your own hand's arrangement never goes over the wire
181	— the state carries a multiset and each device keeps its own order
182	(`src/net/handOrder.ts`), because a round-trip inside a drag gesture is lag
183	you can feel.
184	- The host can change. The relay re-elects — the earliest joiner still
185	connected — when the host leaves; every other client already mirrors the
186	full state, so the new host starts its engine from what it was just watching
187	and the game carries on.
188	- A hidden host must keep hosting. Browsers suspend requestAnimationFrame
189	and throttle timers in background tabs, so nothing in `src/net/` runs on a
190	loop: state writes flush on a microtask, everything inbound arrives over the
191	WebSocket (whose delivery is not throttled), and dead connections are the
192	server's ping loop's problem. A party screen somebody tabbed away from
193	keeps answering.
194	- Identity is a UUID in sessionStorage, chosen by the device and taken at
195	its word by the relay. The seat map is keyed on it, so a reload or a wifi
196	blip walks back into its own seat. No auth — this is a home server for one
197	table of friends.
198	- Fairness is social, not cryptographic. Room state carries the whole
199	game, wall and hands included — a friend with devtools open can cheat.
200	Moving the engine into the relay would fix that; the server is ours now, so
201	only the work stands in the way (TODO).
202
203	### Running it
204
205	```
206	npm run dev # vite, with the relay on /ws of the same origin
207	npm run build && npm run serve # production: dist/ + relay, one process
208	```
209
210	The relay always lives at `/ws` on the page's own origin. In development
211	`vite.config.ts` attaches it to vite's server, so `npm run dev` is the whole
212	stack; in production `server/index.ts` serves the built `dist/` and the relay
213	from one port (`PORT`, default 8080), listening on the LAN by default so
214	phones on the same wifi can scan straight in. Anything further away wants TLS
215	in front — a reverse proxy with a certificate — since phones only get camera
216	and fullscreen on https.
217
218	Rooms live in memory. A restart drops them; the next visitor on an old link
219	recreates the room empty, and a host mid-game republishes its state on the
220	next move. Joining a room writes `?room=` back into the address bar, so the
221	page URL — the host's included — is the invite link.
222
223	## On a phone
224
225	The table assumes four people sitting around a screen lying flat, and about
226	770px in both directions before the middle is worth looking at. A phone has
227	neither, so under `(max-height: 620px), (max-width: 820px)` it switches to the
228	compact layout: nothing is rotated, everything reads upright for the one person
229	holding it, the other three seats shrink to cards showing what is public about
230	them, and the depth that frees up goes to your hand, which is allowed to wrap.
231
232	There is no centre square there — the middle collapses to a one-line bar showing
233	what the wall square was telling you anyway — so there is nowhere to throw a tile
234	to. The compact layout therefore keeps a discard row per seat, and discarding
235	is tap-twice or 打出, exactly as it was. The pool and the throw are a full-size
236	feature.
237
238	The breakpoint is written down once, in `COMPACT_QUERY` in `src/ui/compact.ts`,
239	which sets a `compact` class on `<html>` for the CSS to key off.
240
241	## Computer players
242
243	Single player seats you at the bottom and gives seats 1-3 to the computer.
244	Their tiles go face down and their 聽 / 過水 badges come off, since both would
245	give the hand away; everything public — the pool, melds, flowers, chips — stays
246	exactly as it is, and everyone turns their hand over when the hand ends. They
247	throw their tiles in like anyone else, and under the same rule: a computer seat
248	whose wall is open slides them across, and one still walled in lobs them over.
249
250	The engine does not know the bots exist. `AutoPlay` (`src/game/autoplay.ts`)
251	watches the same state the screen does, and when the seat being waited on
252	belongs to the computer it calls the identical method the button would have
253	called — `discard`, `respond`, `declareConcealedKong`. So scoring, sound,
254	saving, 過水 and 包牌 all work without a special case, and a bot cannot make a
255	move a person could not. It never acts for you and never closes your claim
256	window: if the table is waiting on you, it waits.
257
258	How they play (`src/game/bot.ts`) is one idea applied everywhere. A hand is
259	judged at its resting size — the (5 − melds) × 3 + 1 tiles you hold between a
260	discard and your next draw — by its 向聽 first and by its 進張 count second.
261
262	- Discard — try every distinct tile, keep the one that leaves the best
263	resting hand. Ties go to whatever is hardest to build on: a lone honour with
264	most of its copies already gone, before a lone 五萬 that still has neighbours
265	to meet.
266	- 碰 / 吃 — only when the hand that comes out the other side is strictly
267	closer to home. Melding costs concealment and flexibility, so a claim that
268	merely holds the 向聽 steady is declined — which is why the bots pass on
269	pungs that would narrow a two-sided wait to a single tile.
270	- 槓 — judged more kindly: it pays 台 and fetches a replacement, so standing
271	still is good enough.
272	- 胡 — always taken.
273
274	What they watch you do (`src/game/danger.ts`) is the other half. Efficiency
275	alone throws whatever is fastest and pays for it; these bots read the table
276	first, off the face-up table only — discard rows, exposed melds, the 過水 locks
277	the nameplates already show. Two separate questions:
278
279	- How close does each seat look? Turns taken (a hand is usually settled
280	inside ten goes each, long before the wall looks finished, so counting the
281	wall is the wrong clock), melds exposed, and what they have been throwing
282	lately. Nobody discards 五條 out of a hand that still needs shaping — it comes
283	out once the shape is done, so late middle tiles are the tell. A 過水 lock is
284	a confession: to be locked out of a tile you had to have been able to win on
285	it.
286	- How likely is this tile the one they want? An honour can only be caught by
287	a pair or a triplet; a 五萬 sits in the middle of every run through it. A tile
288	they discarded themselves was not their tile when it went down — not proof
289	now, but the best evidence there is. A tile with no copies left unseen cannot
290	be a pair or triplet wait at all. Two melds in one suit means stay out of that
291	suit. And two dragon pungs down means the third dragon is not going anywhere
292	near the table, because 包牌 bills the feeder for the entire hand.
293
294	Whether any of that changes the discard depends on the bot's own hand. At 聽牌
295	it pushes — nothing short of 包牌 is worth breaking a ready hand for. Two or
296	three away with somebody live across the table and it will give up a whole 向聽
297	step to throw something safe, which is what folding is.
298
299	The estimate is checked against ground truth in the tests rather than assumed:
300	over the tiles bots actually considered, the ones the model rated below 0.2 deal
301	in 0% of the time and the ones above 0.8 deal in 10.5%, cleanly monotonic in
302	between. Switching the read on cuts deal-ins by about 13% over a few hundred
303	hands, takes hands from ~30 discards to ~38, and moves the draw rate from
304	almost nothing to about one hand in ten — which is what a table where people
305	stop feeding each other actually looks like.
306
307	What they know is still only what they can see. `unseenFor` counts the four
308	copies of each tile and subtracts the bot's own hand plus every discard and
309	exposed meld on the table. Neither module ever reads an opponent's concealed
310	tiles or looks at the wall.
311
312	There is no difficulty setting, and the reading stops at the discard: claims are
313	still judged purely on speed, and a bot will take a 碰 that walks it into
314	trouble.
315
316	向聽 lives in `src/game/shanten.ts`, apart from `hu.ts`, because the two want
317	different things: the win check has to be exact, and this one has to be fast —
318	it runs a few hundred times for every discard a bot considers. The tests hold
319	them against each other over random hands, since they work in completely
320	different ways and any disagreement is a bug in the fast one.
321
322	Undo behaves differently against the computer: rewinding into the middle of its
323	turn would only hand the move straight back to it, so one press goes back to
324	the last point you had a decision to make, computer replies and all.
325
326	## Saving
327
328	The game state is plain data, so a save is just its JSON in `localStorage`,
329	rewritten after every move. Close the lid, refresh, or run the battery flat and
330	nothing is lost — the lobby offers 繼續對局 Resume above the two ways to
331	start a fresh one, showing whether it was a solo or a hotseat game, the round,
332	hand number, chip counts and when it was saved. Which seats the computer holds
333	is part of the state, so a save resumes as the kind of game it was. A
334	save is validated before it is offered (four players, 144 tiles accounted for),
335	so a truncated or hand-edited one is ignored rather than loaded into a broken
336	table. `VERSION` in `save.ts` retires old saves if the state shape changes.
337
338	## Rules implemented
339
340	- 144 tiles (four of each suit/honour, eight flowers), 16-tile hands, dealer
341	draws the 17th.
342	- 補花 at the deal and on every drawn flower, replacements from the back of the
343	wall.
344	- 吃 only from 上家; 碰/槓/胡 from anyone. 明槓, 暗槓, 加槓, 搶槓, 槓上開花.
345	- 流局 when 16 tiles remain (`Rules.wallReserve`); the dealer keeps the deal on a
346	draw or on a dealer win (連莊), otherwise the deal passes and the round wind
347	advances every four passes. A full 四圈 game is 16 dealer passes.
348
349	### House rules (switches in `Rules`, all on the settings screen)
350
351	- 過水 `sacredDiscard` (on) — pass on a tile you could have won with and it
352	is dead to you until your own next draw; the seat shows a 過水 badge listing
353	what it is locked out of, so the missing 胡 button is never a mystery. A draw
354	from either end of the wall lifts it. `sacredClearedByClaim` (off) decides
355	whether taking a 吃 / 碰 / 槓 lifts it too — tables genuinely differ.
356	- 一炮多響 `multipleWinners` (off) — one discard pays out to every seat that
357	calls on it, each settled separately against the discarder. With it off the
358	tile goes to the caller nearest the discarder. Either way the table now waits
359	for other seats that can win before settling, so the nearest seat wins the
360	tile rather than the quickest hand — and the 摸牌 button still closes the
361	window on anyone dithering.
362	- 包牌 `liability` (on) — feeding the pung that completes a visible 大三元
363	or 大四喜 makes the feeder answer for the whole hand, in place of all three
364	payers. Only the seat that fed the last of those sets is on the hook, and
365	only if it came off a discard: a hand that assembled them itself, or closed
366	the set with a 暗槓, has nobody to blame.
367
368	### 台 scoring (`src/game/tai.ts`)
369
370	自摸 1 · 門清 1 · 門清自摸 +1 · 全求人 2 · 平胡 2 · 五門齊 2 · 正花 1 each ·
371	花槓 2 · 八仙過海 8 · 圈風 / 門風 1 each · 三元牌 1 each · 小三元 4 · 大三元 8 ·
372	小四喜 8 · 大四喜 16 · 碰碰胡 4 · 混一色 4 · 清一色 8 · 字一色 16 ·
373	三暗刻 2 / 四暗刻 5 / 五暗刻 8 · 獨聽 · 單釣 1 · 搶槓 1 · 槓上開花 1 ·
374	海底撈月 1 · 河底撈魚 1 · 天胡 16 · 地胡 16 · 人胡 8 · 莊家 1 (連N拉N → 2N+1)
375
376	Ambiguous hands are decomposed every legal way and scored at the best reading.
377
378	Payment (`Game.settle`): one unit is `底 + 台 × 台值`
379	(`DEFAULT_RULES` = 底 3, 台 1, 100 chips each).
380	放槍一家付 — the discarder alone pays one unit; on 自摸 all three pay one unit
381	each. 拉莊 is billed to the dealer alone when the dealer is a payer, and added
382	to the whole hand when the dealer wins.
383
384	House rules vary a lot; the tai table and payments are plain data/functions in
385	`tai.ts` and `types.ts` if yours differ.
386
387	## The voice pack
388
389	A mahjong table only ever says about fifty things — 42 tile names and a handful
390	of calls — so the whole vocabulary is rendered ahead of time into
391	`public/voice/` (~330 kB of mp3) rather than left to whatever speech synthesis
392	the browser happens to have. On Linux that is usually espeak-ng, which is
393	intelligible but sounds like a modem; and on a machine with no Chinese voice at
394	all the feature would silently do nothing. Shipping the audio makes playback
395	instant, identical everywhere, and lets a call be cut off mid-word when the
396	next one lands, all through the same Web Audio graph as the chimes.
397
398	`scripts/voice.mjs` is the authoring step, not part of `npm run build`. It needs
399	[piper](https://github.com/OHF-Voice/piper1-gpl) and ffmpeg on PATH:
400
401	```
402	node scripts/voice.mjs # → public/voice/*.mp3 + manifest.json
403	PIPER_MODEL=/path/to/voice.onnx node scripts/voice.mjs # a different voice
404	```
405
406	The wording lives in that script, and some of it is deliberately not the bare
407	tile character: 東 alone is a direction where 東風 is the tile, and the dragons
408	are 紅中 / 發財 / 白板 the way they are actually called — which also gives the
409	phonemiser enough context to get the tone right, since 中 on its own is as
410	likely to come out zhòng.
411
412	The clips here were rendered with piper's `zh_CN-huayan-medium`. If you
413	redistribute this app, check that voice's model card in
414	[piper-voices](https://huggingface.co/rhasspy/piper-voices) for the terms
415	attached to it, the same way you would the tile art below — or re-render the
416	pack with a voice whose terms suit you, which is a single command.
417
418	## Tile art
419
420	`public/tiles/tiles.svg` is the postmodern tileset from
421	[gnome-mahjongg](https://gitlab.gnome.org/GNOME/gnome-mahjongg), extracted from
422	the installed binary's GResource — a 43×2 sprite sheet (second row is the
423	highlighted variant, used for a lifted tile). `public/tiles/back.png` is the
424	blank tile from its smooth theme, tinted jade, since a solitaire game has no
425	face-down art of its own.
426
427	That art is GPL-2.0-or-later. Fine for playing at home; if you ever
428	distribute this app, either honour the GPL or swap the two files for art of your
429	own — `SPRITE_COL` in `tiles.ts` is the only mapping that would need updating.
430
431	Known gaps and house rules that aren't implemented yet are listed in
432	[TODO.md](TODO.md).
433
434	## Layout
435
436	```
437	public/tiles/ sprite sheet + tile back
438	src/game/tiles.ts tile codes, wall, shuffle, sprite mapping
439	src/game/hu.ts hand decomposition, 聽 detection, wait shapes
440	src/game/shanten.ts 向聽 / 進張 counting, for the computer players
441	src/game/bot.ts what a computer player discards and claims (pure)
442	src/game/danger.ts reading the table: who looks ready, which tiles are hot
443	src/game/autoplay.ts when it does it, and how long it appears to think
444	src/game/tai.ts 台 scoring
445	src/game/engine.ts state machine: deal, turns, claim resolution, settlement
446	src/game/ctl.ts TableCtl — the surface the UI drives, local or networked
447	src/game/wall.ts what is left of the square, and what still blocks a throw
448	src/net/room.ts the wire itself: join, reconnect, state, events
449	src/net/session.ts the room: host duties, seats, intents, migration
450	src/net/table.ts TableCtl over the wire: mirror + intents + hand overlay
451	src/net/protocol.ts what crosses the wire, in one place
452	src/net/handOrder.ts your own arrangement, kept on your own device
453	src/ui/Controller.tsx the phone at the party table: your tiles and the throw
454	src/ui/OnlineLobby.tsx seats and the deal button, before an online game
455	server/rooms.ts the relay: rooms, host election, state fan-out
456	server/index.ts production: dist/ and the relay from one port
457	src/table/physics.ts the discard pool: rectangles with weight, pure and testable
458	src/table/geometry.ts the table measured — colliders, launch points, throw gate
459	src/table/pool.ts game state ⇄ tiles in the middle, by diffing the discards
460	src/ui/ TileView, Hand (drag and throw), Seat, Center, Pool, Help
461	```
462
463	## The tiles in the middle
464
465	The pool is a small rigid-body solver (`src/table/physics.ts`) that knows nothing
466	about mahjong, the DOM, or the clock: fixed 1/120s steps, no randomness of its
467	own, and everything in table pixels. Given the same throws it produces the same
468	pile every time, which is what lets a refresh mid-hand come back to the pile you
469	had rather than a freshly scattered one — positions are derived from the hand
470	number and each tile's place in its thrower's discards, never saved.
471
472	It is drawn on a canvas that spans the whole table, not just the centre.
473	That is deliberate: `.slot` and `.seat` both clip their own contents, which is
474	why a tile can't be animated out of a strip as an element. On the canvas there is
475	nothing to clip it, so a tile lifted out of a hand crosses the table in one
476	piece.
477
478	Nothing about the square is calculated twice. Its size lives entirely in CSS
479	(`--ws`, `--wd`), so `geometry.ts` measures it instead of restating that
480	arithmetic: `WallRing` already renders every stack as a real element tagged with
481	its index, and the colliders are those elements' bounding rects. That one
482	mapping is what makes the wall a physical object — the thing a thrown tile
483	bounces off, and the thing the throw gate casts its ray at.
484
485	## What is left of the wall
486
487	Four walls of eighteen full-size stacks want about 560px a side. No ordinary
488	window has that between the top and bottom strips, and the tile is not allowed
489	to shrink to make it fit — a tile in the wall is the same tile you play with, so
490	drawing it smaller was a visible lie.
491
492	What saves it is that nobody ever sees a whole wall: four hands come off the
493	front before the table is on screen, so barely half of it is left by then. So
494	only the stacks still standing are drawn, and they are laid out around a ring
495	cut to the middle rather than to eighteen — `ringLayout` in `game/wall.ts`
496	measures how many stacks a side can take (`WallRing` renders one hidden cell and
497	asks CSS how big it came out) and shares what is left over the four sides in
498	proportion. Every seat keeps a wall in front of it instead of the remainder
499	piling into one corner, and the order runs all the way round, so the break point
500	is still at the head of it and the 底牌 tail still at the end.
501
502	Shuffling the wall along as it is eaten costs nothing to look at, because every
503	stack shows the same green back — and it is what people do to a half-eaten wall
504	anyway.
505
506	`pool.ts` never listens for events. It diffs the discards against what it is
507	already drawing, keyed by `seat:index` — and those keys never shift, because
508	discards are only ever pushed and a claim only ever pops the one on top. So a
509	key that appeared is a tile to throw in and a key that went is a tile to take
510	off, which makes undo, 下一局, a claim and resuming a saved game all the same
511	code path. The engine has no idea any of it exists, and the save format did not
512	change.