@masonf539/egyptian-war 1.0.0 → 1.0.1-beta.0

package/LICENSE

@@ -1,27 +1,27 @@
-Egyptian War License
-
-Copyright (c) 2026 Mason Fong
-
-Required Notice: Copyright (c) 2026 Mason Fong
-Required Notice: Egyptian War source code is licensed under the PolyForm Noncommercial License 1.0.0.
-
-The Egyptian War software, including its source code, browser code, styles,
-templates, tests, documentation, rules engine, and networking implementation,
-is licensed under the PolyForm Noncommercial License 1.0.0.
-
-You may use, copy, modify, and distribute the Egyptian War software only for
-purposes permitted by that license. Commercial use requires a separate written
-license from the copyright holder.
-
-The complete PolyForm Noncommercial License 1.0.0 is available at:
-
-https://polyformproject.org/licenses/noncommercial/1.0.0
-
-The creative assets located in public/assets are part of the Egyptian War software 
-and are licensed under the PolyForm Noncommercial License 1.0.0, like the rest of this package.
-
-Third-party dependencies and separately identified third-party materials remain
-governed by their respective licenses.
-
-THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OR CONDITION, TO THE EXTENT
+Egyptian War License
+
+Copyright (c) 2026 Mason Fong
+
+Required Notice: Copyright (c) 2026 Mason Fong
+Required Notice: Egyptian War source code is licensed under the PolyForm Noncommercial License 1.0.0.
+
+The Egyptian War software, including its source code, browser code, styles,
+templates, tests, documentation, rules engine, and networking implementation,
+is licensed under the PolyForm Noncommercial License 1.0.0.
+
+You may use, copy, modify, and distribute the Egyptian War software only for
+purposes permitted by that license. Commercial use requires a separate written
+license from the copyright holder.
+
+The complete PolyForm Noncommercial License 1.0.0 is available at:
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+The creative assets located in public/assets are part of the Egyptian War software 
+and are licensed under the PolyForm Noncommercial License 1.0.0, like the rest of this package.
+
+Third-party dependencies and separately identified third-party materials remain
+governed by their respective licenses.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OR CONDITION, TO THE EXTENT
 PERMITTED BY LAW.

package/README.md

@@ -1,66 +1,68 @@
-# Egyptian War for GameHub
-
-This directory contains the server-authoritative Egyptian War game plugin for
-GameHub and is exported to the `egyptian-war-standalone` branch for release.
-
-Egyptian War is designed to be installed and run by GameHub through the
-`@masonf539/game-sdk` contracts. It is independently versioned, but it is not a
-standalone web application and depends on GameHub for rooms, networking, the
-lobby, shared settings, and browser hosting.
-
-The package owns its rules, state engine, slap arbitration, tests, browser
-presentation, game-specific audio, preview media, and design documentation.
-GameHub supplies rooms, members, spectators, transport, and shared services.
-
-`src/session.ts` owns the authoritative runtime lifecycle, including turn
-timers, slap collection, pause/disconnect recovery, animations, member
-removal, and completion. `public/client.js` owns the browser controller and
-registers it with GameHub's generic client host.
-
-Game-specific music, effects, and picker previews live under `public/assets`
-and are served by GameHub from `/games/egyptian-war`.
-The package-owned `public/register.js` registers those sounds with GameHub's
-shared audio service.
-The game board lives in `public/template.html`, and its presentation lives in
-`public/style.css`. GameHub injects the fragment into a package-specific root;
-the browser controller scopes its element lookups to that root.
-During active play, the stylesheet fixes the board to the available viewport,
-accounts for mobile safe areas, and keeps its compact Pause/connection row
-below GameHub's Settings shortcut. Full Screen and confirmed Exit/Leave
-actions remain platform-owned controls in GameHub's reusable Game tab. The
-shortcut is mounted inside the active game viewport, while the Settings tabs
-move into one horizontal row at medium and small widths.
-Egyptian War declares `play-card` and `slap` input actions for GameHub's
-package-aware Keybinds tab. Their defaults are E and Space respectively, and
-the game subscribes through the shared input service so remapping remains a
-personal GameHub preference.
-The package's public state also states whether the current player may legally
-play a card, keeping the action disabled during the final slap window after a
-failed challenge. Its numeric countdown stays fixed at the right edge inside
-the full-width timer track while the yellow fill passes beneath it, and the
-complete timer scales with the action controls on narrow screens.
-
-The package consumes an exact `@masonf539/game-sdk` release. Once both packages
-are published, GameHub installs an exact Egyptian War version and enables it
-through `gamehub.config.json`. GameHub's `npm run verify:packages` command
-currently verifies that both packed artifacts work without monorepo source.
-
-## Slap rules and penalties
-
-Slap patterns are validated by the server and configured in the lobby. The
-"Three in a Row" pattern checks the latest three cards for an ascending or
-descending rank sequence, including Ace-low and Ace-high sequences. The
-"Tens" pattern checks only two directly adjacent number cards that total ten;
-an Ace counts as one. An active player who false-slaps forfeits the configured
-number of cards, up to the number they hold. An eliminated player has no cards
-to forfeit, so a false slap instead makes them miss the next card's slap
-opportunity. A valid slap can still let an eliminated player re-enter when
-their cooldown is clear.
-
-## Independent repository preparation
-
-The package directory includes its own README, license, TypeScript settings,
-tests, public assets, and package metadata. Its only GameHub code dependency is
-the exact `@masonf539/game-sdk` version declared in `package.json`. A standalone
-lockfile will be generated after that SDK version is published so it records
-the registry artifact rather than the monorepo workspace link.
+# Egyptian War for GameHub
+
+This repository contains the server-authoritative Egyptian War game plugin
+for GameHub.
+
+Egyptian War is designed to be installed and run by GameHub through the
+`@masonf539/game-sdk` contracts. It is independently versioned, but it is not a
+standalone web application and depends on GameHub for rooms, networking, the
+lobby, shared settings, and browser hosting.
+
+The package owns its rules, state engine, slap arbitration, tests, browser
+presentation, game-specific audio, preview media, and design documentation.
+GameHub supplies rooms, members, spectators, transport, and shared services.
+
+`src/session.ts` owns the authoritative runtime lifecycle, including turn
+timers, slap collection, pause/disconnect recovery, animations, member
+removal, and completion. `public/client.js` owns the browser controller and
+registers it with GameHub's generic client host.
+
+Game-specific music, effects, and picker previews live under `public/assets`
+and are served by GameHub from `/games/egyptian-war`.
+The package-owned `public/register.js` registers those sounds with GameHub's
+shared audio service.
+The game board lives in `public/template.html`, and its presentation lives in
+`public/style.css`. GameHub injects the fragment into a package-specific root;
+the browser controller scopes its element lookups to that root.
+During active play, the stylesheet fixes the board to the available viewport,
+accounts for mobile safe areas, and keeps its compact Pause/connection row
+below GameHub's Settings shortcut. Full Screen and confirmed Exit/Leave
+actions remain platform-owned controls in GameHub's reusable Game tab. The
+shortcut is mounted inside the active game viewport, while the Settings tabs
+move into one horizontal row at medium and small widths.
+Egyptian War declares `play-card` and `slap` input actions for GameHub's
+package-aware Keybinds tab. Their defaults are E and Space respectively, and
+the game subscribes through the shared input service so remapping remains a
+personal GameHub preference.
+The package's public state also states whether the current player may legally
+play a card, keeping the action disabled during the final slap window after a
+failed challenge. Its numeric countdown stays fixed at the right edge inside
+the full-width timer track while the yellow fill passes beneath it, and the
+complete timer scales with the action controls on narrow screens.
+
+The package consumes an exact `@masonf539/game-sdk` release. Once both packages
+are published, GameHub installs an exact Egyptian War version and enables it
+through `gamehub.config.json`. GameHub's `npm run verify:packages` command
+currently verifies that both packed artifacts work without monorepo source.
+
+## Slap rules and penalties
+
+Slap patterns are validated by the server and configured in the lobby. The
+"Three in a Row" pattern checks the latest three cards for an ascending or
+descending rank sequence, including Ace-low and Ace-high sequences. The
+"Tens" pattern checks only two directly adjacent number cards that total ten;
+an Ace counts as one. An active player who false-slaps forfeits the configured
+number of cards, up to the number they hold. An eliminated player has no cards
+to forfeit, so a false slap prevents them from slapping the unchanged pile
+again. The cooldown clears when the next card is played, allowing that card to
+be slapped and the eliminated player to re-enter immediately.
+Invalid reentry attempts use the same visible one-hand slap animation as other
+false slaps; additional attempts during the cooldown do not create extra hands.
+
+## Installation preparation
+
+The repository includes its own README, license, TypeScript settings, tests,
+public assets, package metadata, and ignore rules. Its only GameHub code
+dependency is the exact `@masonf539/game-sdk` version declared in `package.json`.
+A lockfile will be generated after that SDK version is published so it records
+the registry artifact rather than the former monorepo workspace link.

package/dist/definition.js

@@ -5,7 +5,7 @@ const game_sdk_1 = require("@masonf539/game-sdk");
 exports.egyptianWar = {
     id: "egyptian-war",
     name: "Egyptian War",
-    description: "Play cards into a central pile, survive face-card challenges, and race to slap enabled patterns. False slaps carry penalties, and eliminated players must skip the next card's slap opportunity after a false slap. The last player holding all the cards wins.",
+    description: "Play cards into a central pile, survive face-card challenges, and race to slap enabled patterns. False slaps carry penalties, and eliminated players must wait for another card before slapping again. The last player holding all the cards wins.",
     isPlayable: true,
     chatEnabled: true,
     minPlayers: 2,
@@ -39,10 +39,10 @@ exports.egyptianWar = {
         "If the challenged player uses every attempt without revealing a face card, Ace, or Joker, the player who most recently played a challenge card wins the pile unless the final card creates a valid slap combination.",
         "When the final failed challenge card creates a valid slap combination, players get a short window of about four seconds to slap; if nobody slaps, the most recent challenge card player wins the pile.",
         "If the challenged player runs out of cards before completing their attempts, the next player with cards inherits the challenge with the remaining attempts.",
-        "A player who runs out of cards is skipped until they reenter by winning a valid slap. An eliminated player who false-slaps must miss the next card's slap opportunity before trying again.",
+        "A player who runs out of cards is skipped until they reenter by winning a valid slap. An eliminated player who false-slaps cannot slap the unchanged pile again, but may slap as soon as the next card is played.",
         "A player who wins the pile places all of its cards at the bottom of their deck without shuffling and begins the next pile.",
         "When a valid slap combination appears, the first player to slap wins the central pile.",
-        "Slapping without a valid combination forfeits the configured number of cards face down to the bottom of the pile, or all remaining cards if fewer remain. Penalty cards do not create slap combinations. A player with no cards forfeits no cards for a false slap, but will miss the next card's slap opportunity before being able to try again.",
+        "Slapping without a valid combination forfeits the configured number of cards face down to the bottom of the pile, or all remaining cards if fewer remain. Penalty cards do not create slap combinations. A player with no cards forfeits no cards for a false slap and must wait for another card before trying again.",
         "When only one player still has cards, that player wins unless the current face-up pile has a valid slap that allows an eliminated player to reenter.",
         "If several players slap at nearly the same moment, the pile goes to one of them by weighted chance that favors the earlier slap. The others forfeit nothing.",
         "The winner is the player who collects every card."
@@ -103,7 +103,7 @@ exports.egyptianWar = {
             type: "number",
             key: "falseSlapPenaltyCards",
             label: "False Slap Penalty",
-            description: "Cards forfeited to the bottom of the pile for an invalid slap. An eliminated player forfeits no cards, but must miss the next card's slap opportunity.",
+            description: "Cards forfeited to the bottom of the pile for an invalid slap. An eliminated player forfeits no cards and must wait for another card before slapping again.",
             defaultValue: 2,
             options: [1, 2, 3],
             unit: "card"

package/dist/engine.d.ts

@@ -81,12 +81,12 @@ export type EgyptianWarDeparture = "removed" | "left";
 export declare function removeEgyptianWarPlayer(state: EgyptianWarState, playerId: string, departure?: EgyptianWarDeparture): string;
 export declare function isEgyptianWarPileSlappable(pile: readonly Card[], settings: EgyptianWarSettings): boolean;
 export declare function isEgyptianWarStateSlappable(state: Pick<EgyptianWarState, "pile" | "penaltyPileCardCount" | "settings">): boolean;
-export type EgyptianWarSlapCooldownStatus = "none" | "waiting" | "blocked";
-/** Start a cooldown that lasts until one more card has been played. */
+export type EgyptianWarSlapCooldownStatus = "none" | "waiting";
+/** Prevent repeated free slaps until one more card has been played. */
 export declare function startEgyptianWarSlapCooldown(state: EgyptianWarState, playerId: string): void;
 /**
- * Returns the status of an eliminated player's one-card slap cooldown.
- * The next card's opportunity is consumed the first time they try to slap on it.
+ * Returns the status of an eliminated player's slap cooldown. Once another
+ * card has been played, the cooldown clears and that new card may be slapped.
  */
 export declare function checkEgyptianWarSlapCooldown(state: EgyptianWarState, playerId: string): EgyptianWarSlapCooldownStatus;
 export declare function applyEgyptianWarAction(state: EgyptianWarState, playerId: string, action: EgyptianWarAction): string;

package/dist/engine.js

@@ -471,7 +471,7 @@ function trackPileVersion(state, run) {
         }
     }
 }
-/** Start a cooldown that lasts until one more card has been played. */
+/** Prevent repeated free slaps until one more card has been played. */
 function startEgyptianWarSlapCooldown(state, playerId) {
     const player = state.players.find((candidate) => candidate.id === playerId);
     if (!player)
@@ -479,8 +479,8 @@ function startEgyptianWarSlapCooldown(state, playerId) {
     player.slapCooldownUntilCardPlayCount = (state.cardsPlayedCount ?? 0) + 1;
 }
 /**
- * Returns the status of an eliminated player's one-card slap cooldown.
- * The next card's opportunity is consumed the first time they try to slap on it.
+ * Returns the status of an eliminated player's slap cooldown. Once another
+ * card has been played, the cooldown clears and that new card may be slapped.
  */
 function checkEgyptianWarSlapCooldown(state, playerId) {
     const player = state.players.find((candidate) => candidate.id === playerId);
@@ -491,7 +491,7 @@ function checkEgyptianWarSlapCooldown(state, playerId) {
     if (cardsPlayedCount < cooldownTarget)
         return "waiting";
     player.slapCooldownUntilCardPlayCount = null;
-    return cardsPlayedCount === cooldownTarget ? "blocked" : "none";
+    return "none";
 }
 function applyEgyptianWarAction(state, playerId, action) {
     return trackPileVersion(state, () => applyAction(state, playerId, action));
@@ -513,9 +513,6 @@ function applyAction(state, playerId, action) {
         if (slapCooldown === "waiting") {
             throw new EgyptianWarRuleError("You must wait until the next card is played before slapping again.");
         }
-        if (slapCooldown === "blocked") {
-            throw new EgyptianWarRuleError("Your one-card slap cooldown blocked that slap.");
-        }
         const faceUpPile = state.pile.slice(state.penaltyPileCardCount);
         if (faceUpPile.length === 0) {
             throw new EgyptianWarRuleError("There are no face-up cards to slap.");

package/dist/session.js

@@ -396,6 +396,14 @@ class EgyptianWarSession {
             return;
         }
         const isLiveSlap = action === "slap" && !isTurnTimeout && !isResolvedSlap;
+        if (isLiveSlap &&
+            (0, engine_js_1.checkEgyptianWarSlapCooldown)(this.state, memberId) === "waiting") {
+            respond({
+                success: false,
+                message: "You must wait until the next card is played before slapping again."
+            });
+            return;
+        }
         if (this.isAnimating &&
             !isResolvedSlap &&
             !(isLiveSlap && this.animationAllowsSlaps)) {
@@ -403,22 +411,6 @@ class EgyptianWarSession {
             return;
         }
         if (isLiveSlap) {
-            const slapCooldown = (0, engine_js_1.checkEgyptianWarSlapCooldown)(this.state, memberId);
-            if (slapCooldown === "waiting") {
-                respond({
-                    success: false,
-                    message: "You must wait until the next card is played before slapping again."
-                });
-                return;
-            }
-            if (slapCooldown === "blocked") {
-                respond({
-                    success: false,
-                    message: "Your one-card slap cooldown blocked that slap."
-                });
-                this.context.broadcastState();
-                return;
-            }
             if ((0, engine_js_1.isEgyptianWarStateSlappable)(this.state)) {
                 this.collectSlap(memberId, respond);
                 return;
@@ -436,16 +428,6 @@ class EgyptianWarSession {
                 respond({ success: false, message: "Wait for the current action to finish." });
                 return;
             }
-            const eliminatedPlayer = this.state.players.find((player) => player.id === memberId);
-            const faceUpCardCount = this.state.pile.length - this.state.penaltyPileCardCount;
-            if (faceUpCardCount > 0 && eliminatedPlayer?.cards.length === 0) {
-                (0, engine_js_1.startEgyptianWarSlapCooldown)(this.state, memberId);
-                respond({
-                    success: false,
-                    message: "You are out of cards and must wait until the next card is played before slapping again."
-                });
-                return;
-            }
         }
         if (this.pendingSlaps !== null && !isResolvedSlap) {
             respond({ success: false, message: "A slap is being resolved. Please wait." });

package/docs/design.md

@@ -1,126 +1,126 @@
-# Egyptian War Design
-
-Egyptian War is a versioned game plugin made for GameHub. The package owns the
-game-specific server and browser behavior, while GameHub provides the room,
-transport, lobby, spectator, and hosting services required to run it.
-
-## Implementation status
-
-This document distinguishes implemented behavior from planned gameplay. A checked item means the behavior exists in the application, not merely that its design has been selected.
-Checked implementation items do not imply that every multiplayer interaction has completed manual gameplay testing; automated engine, arbitration, Socket.IO integration, and browser-animation tests run during the Docker build.
-
-### Game availability
-
-- [x] Keep Egyptian War visible so players can read its rules and configure its settings.
-- [x] Represent playability in the shared game definition.
-- [x] Disable the Start Game button and show a coming-soon status when the selected game is not playable.
-- [x] Reject attempts to start an unplayable game on the server.
-- [x] Mark Egyptian War playable after its server-authoritative game loop and client interface are implemented.
-
-### Existing configuration
-
-- [x] Support 2–6 players in the game definition.
-- [x] Define standard cards and optional Jokers.
-- [x] Configure one, two, or three complete decks, defaulting to one; include two Jokers per deck when Jokers are enabled.
-- [x] Configure Jokers, doubles, sandwiches, three in a row, top-bottom, adjacent-card tens, and marriage as lobby settings.
-- [x] Apply the saved settings to server-side slap validation.
-- [x] Configure the false-slap penalty to 1, 2, or 3 cards, defaulting to 2.
-- [x] Configure a 5–120 second player timer with a default of 15 seconds using synchronized slider and number controls.
-- [x] Reset the active player's timer after they win a valid slap on their own turn.
-
-### Server-authoritative gameplay
-
-- [x] Implement server-side deck creation and cryptographic shuffling.
-- [x] Implement face-down dealing and public state without hidden decks.
-- [x] Implement random first-player selection.
-- [x] Initialize the engine when a live room starts Egyptian War.
-- [x] Enforce clockwise turns.
-- [x] Implement Jack, Queen, King, Ace, and Joker challenge attempts (Jokers allow 5 attempts).
-- [x] Award the pile to the most recent challenge-card player when a challenge fails, except while a valid final-attempt slap window is active.
-- [x] Validate slaps on the server and resolve competing slaps fairly.
-- [x] Use server receipt time for slap candidates so clients cannot improve their position by delaying timing acknowledgements. Collect requests for 200 ms, assign a fixed server-controlled 25 ms uncertainty to each candidate, compare candidates within the resulting 50 ms window, and select eligible candidates with smooth exponential weighting driven by Node's cryptographically secure random source.
-- [x] Finish accepted slap arbitration before honoring a host pause, and allow candidates accepted before a disconnect-triggered pause to resolve instead of silently discarding them.
-- [x] Skip players who run out of cards; continue the turn with the next eligible player.
-- [x] Pass an unfinished challenge to the next eligible player with the remaining attempts unchanged when its responder runs out of cards.
-- [x] Allow eliminated players to reenter through a valid slap.
-- [x] Detect when one player owns every card and end the game.
-- [x] Return the room to the lobby after the game ends.
-- [x] Pause the active game when a player disconnects; allow the host to resume while the player is away, and restore the saved pause preference after they reconnect. Lobby-only disconnects still expire after two minutes.
-- [x] Gray out disconnected players' table seats and show a yellow disconnected alert beneath each seat.
-- [x] Provide a host-only Close Lobby control in the lobby and expose confirmed Exit Game or Leave Game actions through GameHub's reusable Game settings tab.
-- [x] Hide the room code by default for non-host players while showing it by default to the host.
-- [x] Preserve a reconnecting active player's remaining turn time and allow one short grace period per turn, capped at the configured turn duration, then continue normal automatic turn play if the timer expires.
-- [x] Send recent face-up cards in reconnect snapshots so the board restores the visible pile after reconnecting.
-- [x] Reject slap actions when there are no face-up cards available to slap, including immediately after a pile transfer or reconnect.
-- [x] Let the host kick a disconnected player during a game; hold their cards face-down until the current pile is awarded, then add them to the next pile.
-- [x] Tell a kicked player they were removed after disconnecting if they later try to reconnect, and notify the table when their cards are deferred.
-- [x] Play the game-winner animation when kicking opponents leaves the host as the last player.
-- [x] Keep slap actions available throughout active play, including for players out of cards, while rejecting actions during pile-transfer, penalty, and win animations and during pauses. Slaps are still collected during the short card-play animation, because the card is already on the pile.
-- [x] Penalize an invalid slap by moving the configured number of the player's cards to the bottom of the pile; forfeit any remaining cards if fewer than the configured penalty remain.
-- [x] Keep face-down false-slap penalty cards out of slap-pattern validation so repeated penalties cannot manufacture a valid slap.
-- [x] End the game when only one player has cards and the face-up pile offers no valid slap for an eliminated player to reenter.
-- [x] Never let a challenger answer their own challenge: when nobody but the challenger can continue, the challenger wins the pile (or the slap window opens).
-- [x] Give an eliminated player who false-slaps a one-card cooldown: they cannot win on the next card's slap opportunity, and they forfeit no cards, since they have none.
-- [x] Keep slap-pattern information off the wire: the public state carries a `pileVersion` but no slappable flag, and messages about a pending pile are neutral.
-- [x] Have slaps carry the `pileVersion` the player last saw. A slap that lost a short race with a card play (previous version, previous pile slappable, under 350 ms) is ignored without a penalty.
-- [x] Allow a player to leave voluntarily; their cards are held face-down and added to the next pile, just like a host removal. If removing a player leaves nobody holding cards, the remaining cards go to the next player in turn order immediately.
-- [x] Allow only the host to pause and resume the game; enforce pause state on the server.
-- [x] Support per-game chat capability; validate room membership, message length, and send rate on the server.
-- [x] Preserve a final played card and winner state long enough for the win animation before returning to the lobby.
-- [x] Enforce the player timer on the server and pause it during host pauses and action animations; add a short reconnect grace period, then auto-play on timeout.
-- [x] When the final failed challenge card creates a valid slap, allow slaps for a short fixed window (four seconds, not a whole turn) before awarding the pile to the challenge owner.
-- [x] Let the host end an active game and return everyone to the lobby after confirming in the browser.
-
-### Client gameplay
-
-- [x] Keep active gameplay fixed to the usable mobile viewport so browser chrome and the on-screen keyboard cannot push the board off-screen.
-- [x] Reserve space for GameHub's compact Settings shortcut above the package-owned Pause and connection-latency row on narrow screens.
-- [x] Render each player's public state without revealing hidden cards.
-- [x] Render the central pile and the most recently played card.
-- [x] Provide server-validated play-card and slap actions.
-- [x] Show turn, challenge, elimination, pile-winner, and game-winner updates.
-- [x] Replace the separate player list with a responsive table arena showing each player's avatar, name, and card count around the table.
-- [x] Render physical-looking cards and animate played cards into the central pile.
-- [x] Place play-card and slap controls immediately below the arena.
-- [x] Display action and challenge messages on the table rather than below it.
-- [x] Show late joiners in a dedicated in-game spectator list, including connection status and host removal controls.
-- [x] Preserve spectator-list updates that arrive while the game client mounts so each spectator sees themselves, allow spectators to return to the lobby through a dedicated confirmation, and offer lobby waiters a Spectate Game action while play remains active.
-- [x] Lay out each player avatar beside their name and card count, with an underline beneath the player details.
-- [x] Highlight the entire current player's seat.
-- [x] Animate cards moving from the pile into the pile winner's area and outline the winner in gold.
-- [x] Animate a hand moving from the slapper's seat to the pile for valid and invalid slap attempts.
-- [x] Animate and retain the final played card while highlighting the game winner in gold.
-- [x] Place a host-only pause/resume button at the upper-right of the gameplay panel.
-- [x] Place a host-only Close Lobby control in the lobby and route the Game settings tab's Exit/Leave action through the appropriate in-app confirmation modal.
-- [x] Put a host-only Kick button beside a disconnected player's table alert.
-- [x] Make the slap-rules list collapsible.
-- [x] On narrow screens, place the collapsed rules Show control directly beside the Slap Rules label without changing the expanded panel or Hide control.
-- [x] Show enabled slap patterns and the false-slap penalty in the upper-left of the gameplay panel.
-- [x] Keep turn-state messages neutral; do not announce when the current pile matches a slap pattern.
-- [x] Show a chat panel only for games whose definitions enable chat.
-- [x] Show the synchronized turn countdown below the table while reserving its layout space when hidden.
-- [x] Keep the current whole seconds stationary at the right inside the timer track above its moving fill, align the timer to both action-button edges, and scale the complete control group together on narrow screens.
-- [x] Decorate the countdown's uncovered track with a blue gradient and progressively revealed sleep marks, ending with a sleeping bear, without changing authoritative timer behavior.
-- [x] Show each browser its latest display-only network round-trip time in the upper-right; never use that client-acknowledged measurement for slap arbitration.
-- [x] Show server connection state as a colored dot with status text on the main menu, in the lobby, and beside the gameplay controls.
-- [x] Fit active gameplay into the browser viewport without page scrolling; overlay Chat and Spectators in one wide bottom-left tab panel with an explicit viewport-relative Expand/Collapse control; place the timer and same-level action buttons in the open bottom-right area; and show turn text directly above the central pile count.
-- [x] Let the Chat/Spectators panel collapse into a small round chat button: it opens at medium size by default, the arrow switches between medium and large, and a small diagonal-arrow button on the panel's corner collapses it to the circle. Reopening restores the size it had before it was collapsed, a new game starts at medium again, and the circle shows an unread count (capped at 9+) for messages from other players that arrived while it was collapsed.
-- [x] Give the side-panel expand and minimize controls separate, lighter utility-button surfaces so they remain visually distinct from the Chat and Spectators tabs.
-- [x] Keep the collapsed Slap Rules Show button in the top-right while shrinking the surrounding box around its title at every viewport size, then restore the full rules width when expanded.
-- [x] Style "Play a Card" and "Slap" buttons as prominent game-action controls, with a secondary "Bring the pain" label and fire accents on Slap.
-- [x] Keep slaps available during active play even when no pattern matches; disable them only when no face-up cards are present, the game is paused or finished, or a non-card-play animation is in progress.
-- [x] Disable Play a Card for every player while a completed challenge is waiting through its final slap window, even though the next player remains identified in public state.
-- [x] Restore active players from a complete reconnect snapshot.
-- [x] Reuse the limited public game-state projection for spectators so they receive the visible pile, public player state, timers, and live animations without hidden decks.
-- [x] Use game-specific background music and synchronize card, slap, pile-win, and game-win sounds with their corresponding presentation animations.
-- [x] Expose persistent, independently adjustable music, lobby alert, and gameplay volume controls through the personal GameHub Settings Audio tab (0% disables a category), and wait for browser-approved user interaction before starting music.
-
-### Table presentation
-
-- [x] Draw the table with CSS until a project-owned table image is available.
-- [x] Give the CSS table a layered casino-felt, wooden-rail, depth, and drop-shadow treatment while retaining its original oval shape.
-- [x] Draw cards as accessible HTML/CSS playing-card faces; do not depend on external card image assets.
-- [x] Render mirrored card corners, distinct face-card styling, and a Joker with vertical JOKER labels and a decorative center that is distinguishable from a Jack.
-- [x] Scale slap hands and their stopping distance with the rendered card size, keep their shadows visually below the hand at every seat rotation, and layer later collected attempts above the official winner.
-- [x] Keep the table, player seats, card motion, spectator area, and controls usable on narrow screens and with reduced-motion preferences.
-- Offer chat per game rather than requiring it in every game; games that rely on secrecy or fast rounds can opt out, while social multiplayer games can enable it.
+# Egyptian War Design
+
+Egyptian War is a versioned game plugin made for GameHub. The package owns the
+game-specific server and browser behavior, while GameHub provides the room,
+transport, lobby, spectator, and hosting services required to run it.
+
+## Implementation status
+
+This document distinguishes implemented behavior from planned gameplay. A checked item means the behavior exists in the application, not merely that its design has been selected.
+Checked implementation items do not imply that every multiplayer interaction has completed manual gameplay testing; automated engine, arbitration, Socket.IO integration, and browser-animation tests run during the Docker build.
+
+### Game availability
+
+- [x] Keep Egyptian War visible so players can read its rules and configure its settings.
+- [x] Represent playability in the shared game definition.
+- [x] Disable the Start Game button and show a coming-soon status when the selected game is not playable.
+- [x] Reject attempts to start an unplayable game on the server.
+- [x] Mark Egyptian War playable after its server-authoritative game loop and client interface are implemented.
+
+### Existing configuration
+
+- [x] Support 2–6 players in the game definition.
+- [x] Define standard cards and optional Jokers.
+- [x] Configure one, two, or three complete decks, defaulting to one; include two Jokers per deck when Jokers are enabled.
+- [x] Configure Jokers, doubles, sandwiches, three in a row, top-bottom, adjacent-card tens, and marriage as lobby settings.
+- [x] Apply the saved settings to server-side slap validation.
+- [x] Configure the false-slap penalty to 1, 2, or 3 cards, defaulting to 2.
+- [x] Configure a 5–120 second player timer with a default of 15 seconds using synchronized slider and number controls.
+- [x] Reset the active player's timer after they win a valid slap on their own turn.
+
+### Server-authoritative gameplay
+
+- [x] Implement server-side deck creation and cryptographic shuffling.
+- [x] Implement face-down dealing and public state without hidden decks.
+- [x] Implement random first-player selection.
+- [x] Initialize the engine when a live room starts Egyptian War.
+- [x] Enforce clockwise turns.
+- [x] Implement Jack, Queen, King, Ace, and Joker challenge attempts (Jokers allow 5 attempts).
+- [x] Award the pile to the most recent challenge-card player when a challenge fails, except while a valid final-attempt slap window is active.
+- [x] Validate slaps on the server and resolve competing slaps fairly.
+- [x] Use server receipt time for slap candidates so clients cannot improve their position by delaying timing acknowledgements. Collect requests for 300 ms, assign a fixed server-controlled 25 ms uncertainty to each candidate, compare candidates within the resulting 50 ms window, and select eligible candidates with smooth exponential weighting driven by Node's cryptographically secure random source.
+- [x] Finish accepted slap arbitration before honoring a host pause, and allow candidates accepted before a disconnect-triggered pause to resolve instead of silently discarding them.
+- [x] Skip players who run out of cards; continue the turn with the next eligible player.
+- [x] Pass an unfinished challenge to the next eligible player with the remaining attempts unchanged when its responder runs out of cards.
+- [x] Allow eliminated players to reenter through a valid slap.
+- [x] Detect when one player owns every card and end the game.
+- [x] Return the room to the lobby after the game ends.
+- [x] Pause the active game when a player disconnects; allow the host to resume while the player is away, and restore the saved pause preference after they reconnect. Lobby-only disconnects still expire after two minutes.
+- [x] Gray out disconnected players' table seats and show a yellow disconnected alert beneath each seat.
+- [x] Provide a host-only Close Lobby control in the lobby and expose confirmed Exit Game or Leave Game actions through GameHub's reusable Game settings tab.
+- [x] Hide the room code by default for non-host players while showing it by default to the host.
+- [x] Preserve a reconnecting active player's remaining turn time and allow one short grace period per turn, capped at the configured turn duration, then continue normal automatic turn play if the timer expires.
+- [x] Send recent face-up cards in reconnect snapshots so the board restores the visible pile after reconnecting.
+- [x] Reject slap actions when there are no face-up cards available to slap, including immediately after a pile transfer or reconnect.
+- [x] Let the host kick a disconnected player during a game; hold their cards face-down until the current pile is awarded, then add them to the next pile.
+- [x] Tell a kicked player they were removed after disconnecting if they later try to reconnect, and notify the table when their cards are deferred.
+- [x] Play the game-winner animation when kicking opponents leaves the host as the last player.
+- [x] Keep slap actions available throughout active play, including for players out of cards, while rejecting actions during pile-transfer, penalty, and win animations and during pauses. Slaps are still collected during the short card-play animation, because the card is already on the pile.
+- [x] Penalize an invalid slap by moving the configured number of the player's cards to the bottom of the pile; forfeit any remaining cards if fewer than the configured penalty remain.
+- [x] Keep face-down false-slap penalty cards out of slap-pattern validation so repeated penalties cannot manufacture a valid slap.
+- [x] End the game when only one player has cards and the face-up pile offers no valid slap for an eliminated player to reenter.
+- [x] Never let a challenger answer their own challenge: when nobody but the challenger can continue, the challenger wins the pile (or the slap window opens).
+- [x] Prevent an eliminated player who false-slaps from repeatedly slapping the unchanged pile; clear that cooldown when the next card is played so they can immediately slap back in.
+- [x] Keep slap-pattern information off the wire: the public state carries a `pileVersion` but no slappable flag, and messages about a pending pile are neutral.
+- [x] Have slaps carry the `pileVersion` the player last saw. A slap that lost a short race with a card play (previous version, previous pile slappable, under 350 ms) is ignored without a penalty.
+- [x] Allow a player to leave voluntarily; their cards are held face-down and added to the next pile, just like a host removal. If removing a player leaves nobody holding cards, the remaining cards go to the next player in turn order immediately.
+- [x] Allow only the host to pause and resume the game; enforce pause state on the server.
+- [x] Support per-game chat capability; validate room membership, message length, and send rate on the server.
+- [x] Preserve a final played card and winner state long enough for the win animation before returning to the lobby.
+- [x] Enforce the player timer on the server and pause it during host pauses and action animations; add a short reconnect grace period, then auto-play on timeout.
+- [x] When the final failed challenge card creates a valid slap, allow slaps for a short fixed window (four seconds, not a whole turn) before awarding the pile to the challenge owner.
+- [x] Let the host end an active game and return everyone to the lobby after confirming in the browser.
+
+### Client gameplay
+
+- [x] Keep active gameplay fixed to the usable mobile viewport so browser chrome and the on-screen keyboard cannot push the board off-screen.
+- [x] Reserve space for GameHub's compact Settings shortcut above the package-owned Pause and connection-latency row on narrow screens.
+- [x] Render each player's public state without revealing hidden cards.
+- [x] Render the central pile and the most recently played card.
+- [x] Provide server-validated play-card and slap actions.
+- [x] Show turn, challenge, elimination, pile-winner, and game-winner updates.
+- [x] Replace the separate player list with a responsive table arena showing each player's avatar, name, and card count around the table.
+- [x] Render physical-looking cards and animate played cards into the central pile.
+- [x] Place play-card and slap controls immediately below the arena.
+- [x] Display action and challenge messages on the table rather than below it.
+- [x] Show late joiners in a dedicated in-game spectator list, including connection status and host removal controls.
+- [x] Preserve spectator-list updates that arrive while the game client mounts so each spectator sees themselves, allow spectators to return to the lobby through a dedicated confirmation, and offer lobby waiters a Spectate Game action while play remains active.
+- [x] Lay out each player avatar beside their name and card count, with an underline beneath the player details.
+- [x] Highlight the entire current player's seat.
+- [x] Animate cards moving from the pile into the pile winner's area and outline the winner in gold.
+- [x] Animate one hand moving from the slapper's seat to the pile for valid and invalid slap attempts, including invalid reentry attempts by eliminated players; suppress extra hands while their cooldown is active.
+- [x] Animate and retain the final played card while highlighting the game winner in gold.
+- [x] Place a host-only pause/resume button at the upper-right of the gameplay panel.
+- [x] Place a host-only Close Lobby control in the lobby and route the Game settings tab's Exit/Leave action through the appropriate in-app confirmation modal.
+- [x] Put a host-only Kick button beside a disconnected player's table alert.
+- [x] Make the slap-rules list collapsible.
+- [x] On narrow screens, place the collapsed rules Show control directly beside the Slap Rules label without changing the expanded panel or Hide control.
+- [x] Show enabled slap patterns and the false-slap penalty in the upper-left of the gameplay panel.
+- [x] Keep turn-state messages neutral; do not announce when the current pile matches a slap pattern.
+- [x] Show a chat panel only for games whose definitions enable chat.
+- [x] Show the synchronized turn countdown below the table while reserving its layout space when hidden.
+- [x] Keep the current whole seconds stationary at the right inside the timer track above its moving fill, align the timer to both action-button edges, and scale the complete control group together on narrow screens.
+- [x] Decorate the countdown's uncovered track with a blue gradient and progressively revealed sleep marks, ending with a sleeping bear, without changing authoritative timer behavior.
+- [x] Show each browser its latest display-only network round-trip time in the upper-right; never use that client-acknowledged measurement for slap arbitration.
+- [x] Show server connection state as a colored dot with status text on the main menu, in the lobby, and beside the gameplay controls.
+- [x] Fit active gameplay into the browser viewport without page scrolling; overlay Chat and Spectators in one wide bottom-left tab panel with an explicit viewport-relative Expand/Collapse control; place the timer and same-level action buttons in the open bottom-right area; and show turn text directly above the central pile count.
+- [x] Let the Chat/Spectators panel collapse into a small round chat button: it opens at medium size by default, the arrow switches between medium and large, and a small diagonal-arrow button on the panel's corner collapses it to the circle. Reopening restores the size it had before it was collapsed, a new game starts at medium again, and the circle shows an unread count (capped at 9+) for messages from other players that arrived while it was collapsed.
+- [x] Give the side-panel expand and minimize controls separate, lighter utility-button surfaces so they remain visually distinct from the Chat and Spectators tabs.
+- [x] Keep the collapsed Slap Rules Show button in the top-right while shrinking the surrounding box around its title at every viewport size, then restore the full rules width when expanded.
+- [x] Style "Play a Card" and "Slap" buttons as prominent game-action controls, with a secondary "Bring the pain" label and fire accents on Slap.
+- [x] Keep slaps available during active play even when no pattern matches; disable them only when no face-up cards are present, the game is paused or finished, or a non-card-play animation is in progress.
+- [x] Disable Play a Card for every player while a completed challenge is waiting through its final slap window, even though the next player remains identified in public state.
+- [x] Restore active players from a complete reconnect snapshot.
+- [x] Reuse the limited public game-state projection for spectators so they receive the visible pile, public player state, timers, and live animations without hidden decks.
+- [x] Use game-specific background music and synchronize card, slap, pile-win, and game-win sounds with their corresponding presentation animations.
+- [x] Expose persistent, independently adjustable music, lobby alert, and gameplay volume controls through the personal GameHub Settings Audio tab (0% disables a category), and wait for browser-approved user interaction before starting music.
+
+### Table presentation
+
+- [x] Draw the table with CSS until a project-owned table image is available.
+- [x] Give the CSS table a layered casino-felt, wooden-rail, depth, and drop-shadow treatment while retaining its original oval shape.
+- [x] Draw cards as accessible HTML/CSS playing-card faces; do not depend on external card image assets.
+- [x] Render mirrored card corners, distinct face-card styling, and a Joker with vertical JOKER labels and a decorative center that is distinguishable from a Jack.
+- [x] Render slap hands with a package-owned palm graphic for consistent mobile orientation, scale them and their stopping distance with the rendered card size, keep their shadows visually below the hand at every seat rotation, and layer later collected attempts above the official winner.
+- [x] Keep the table, player seats, card motion, spectator area, and controls usable on narrow screens and with reduced-motion preferences.
+- Offer chat per game rather than requiring it in every game; games that rely on secrecy or fast rounds can opt out, while social multiplayer games can enable it.