Bump version to 3.1.6, update docs

Update version across pyproject.toml, FastAPI app, HTML footers,
and V3.17 doc. Mark kicked-ball bug as resolved in docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -20,6 +20,24 @@ DEBUG=false
 # Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
 LOG_LEVEL=INFO
 
+# Per-module log level overrides (optional)
+# These override LOG_LEVEL for specific modules.
+# LOG_LEVEL_GAME=DEBUG       # Core game logic
+# LOG_LEVEL_AI=DEBUG         # AI decisions (very verbose at DEBUG)
+# LOG_LEVEL_HANDLERS=DEBUG   # WebSocket message handlers
+# LOG_LEVEL_ROOM=DEBUG       # Room/lobby management
+# LOG_LEVEL_AUTH=DEBUG       # Auth stack (auth, routers.auth, services.auth_service)
+# LOG_LEVEL_STORES=DEBUG     # Database/Redis operations
+
+# --- Preset examples ---
+# Staging (debug game logic, quiet everything else):
+#   LOG_LEVEL=INFO
+#   LOG_LEVEL_GAME=DEBUG
+#   LOG_LEVEL_AI=DEBUG
+#
+# Production (minimal logging):
+#   LOG_LEVEL=WARNING
+
 # Environment name (development, staging, production)
 ENVIRONMENT=development
 

.gitignore

@@ -201,6 +201,9 @@ pyvenv.cfg
 # Personal notes
 lookfah.md
 
+# Internal docs (deployment info, credentials references, etc.)
+internal/
+
 # Ruff stuff:
 .ruff_cache/
 

client/app.js

@@ -379,7 +379,7 @@ class GolfGame {
         // Only show tooltips on your turn
         if (!this.isMyTurn() && !this.gameState?.waiting_for_initial_flip) return;
 
-        const value = this.getCardPointValue(cardData);
+        const value = this.getCardPointValueForTooltip(cardData);
         const special = this.getCardSpecialNote(cardData);
 
         let content = `<span class="tooltip-value ${value < 0 ? 'negative' : ''}">${value} pts</span>`;
@@ -409,14 +409,15 @@ class GolfGame {
         if (this.tooltip) this.tooltip.classList.add('hidden');
     }
 
-    getCardPointValue(cardData) {
+    getCardPointValueForTooltip(cardData) {
         const values = this.gameState?.card_values || this.getDefaultCardValues();
-        return values[cardData.rank] ?? 0;
+        const rules = this.gameState?.scoring_rules || {};
+        return this.getCardPointValue(cardData, values, rules);
     }
 
     getCardSpecialNote(cardData) {
         const rank = cardData.rank;
-        const value = this.getCardPointValue(cardData);
+        const value = this.getCardPointValueForTooltip(cardData);
         if (value < 0) return 'Negative - keep it!';
         if (rank === 'K' && value === 0) return 'Safe card';
         if (rank === 'K' && value === -2) return 'Super King!';
@@ -822,11 +823,29 @@ class GolfGame {
                                        newState.phase === 'round_over';
 
                 if (roundJustEnded && oldState) {
-                    // Save pre-reveal state for the reveal animation
+                    // Update state first so animations can read new card data
-                    this.preRevealState = JSON.parse(JSON.stringify(oldState));
-                    this.postRevealState = newState;
-                    // Update state but DON'T render yet - reveal animation will handle it
                     this.gameState = newState;
+
+                    // Fire animations for the last turn (swap/discard) before deferring
+                    try {
+                        this.triggerAnimationsForStateChange(oldState, newState);
+                    } catch (e) {
+                        console.error('Animation error on round end:', e);
+                    }
+
+                    // Build preRevealState from oldState, but mark swap position as
+                    // already handled so reveal animation doesn't double-flip it
+                    const preReveal = JSON.parse(JSON.stringify(oldState));
+                    if (this.opponentSwapAnimation) {
+                        const { playerId, position } = this.opponentSwapAnimation;
+                        const player = preReveal.players.find(p => p.id === playerId);
+                        if (player?.cards[position]) {
+                            player.cards[position].face_up = true;
+                        }
+                    }
+
+                    this.preRevealState = preReveal;
+                    this.postRevealState = newState;
                     break;
                 }
 
@@ -923,16 +942,16 @@ class GolfGame {
                     this.displayHeldCard(data.card, true);
                     this.renderGame();
                 }
-                this.showToast('Swap with a card or discard', '', 3000);
+                this.showToast('Swap with a card or discard', 'your-turn', 3000);
                 break;
 
             case 'can_flip':
                 this.waitingForFlip = true;
                 this.flipIsOptional = data.optional || false;
                 if (this.flipIsOptional) {
-                    this.showToast('Flip a card or skip', '', 3000);
+                    this.showToast('Flip a card or skip', 'your-turn', 3000);
                 } else {
-                    this.showToast('Flip a face-down card', '', 3000);
+                    this.showToast('Flip a face-down card', 'your-turn', 3000);
                 }
                 this.renderGame();
                 break;
@@ -950,7 +969,7 @@ class GolfGame {
                 // Host ended the game or player was kicked
                 this._intentionalClose = true;
                 if (this.ws) this.ws.close();
-                this.showScreen('lobby');
+                this.showLobby();
                 if (data.reason) {
                     this.showError(data.reason);
                 }
@@ -975,7 +994,7 @@ class GolfGame {
 
             case 'queue_left':
                 this.stopMatchmakingTimer();
-                this.showScreen('lobby');
+                this.showLobby();
                 break;
 
             case 'error':
@@ -995,7 +1014,7 @@ class GolfGame {
     cancelMatchmaking() {
         this.send({ type: 'queue_leave' });
         this.stopMatchmakingTimer();
-        this.showScreen('lobby');
+        this.showLobby();
     }
 
     startMatchmakingTimer() {
@@ -1431,8 +1450,9 @@ class GolfGame {
         this.swapAnimationCardEl = handCardEl;
         this.swapAnimationHandCardEl = handCardEl;
 
-        // Hide originals during animation
+        // Hide originals and UI during animation
         handCardEl.classList.add('swap-out');
+        this.discardBtn.classList.add('hidden');
         if (this.heldCardFloating) {
             this.heldCardFloating.style.visibility = 'hidden';
         }
@@ -1574,10 +1594,26 @@ class GolfGame {
 
         if (this.pendingGameState) {
             const oldState = this.gameState;
-            this.gameState = this.pendingGameState;
+            const newState = this.pendingGameState;
             this.pendingGameState = null;
-            this.checkForNewPairs(oldState, this.gameState);
+
-            this.renderGame();
+            // Check if the deferred state is a round_over transition
+            const roundJustEnded = oldState?.phase !== 'round_over' &&
+                                   newState.phase === 'round_over';
+
+            if (roundJustEnded && oldState) {
+                // Same intercept as the game_state handler: store pre/post
+                // reveal states so runRoundEndReveal can animate the reveal
+                this.gameState = newState;
+                const preReveal = JSON.parse(JSON.stringify(oldState));
+                this.preRevealState = preReveal;
+                this.postRevealState = newState;
+                // Don't renderGame - let the reveal sequence handle it
+            } else {
+                this.gameState = newState;
+                this.checkForNewPairs(oldState, newState);
+                this.renderGame();
+            }
         }
     }
 
@@ -2063,6 +2099,16 @@ class GolfGame {
 
     async runRoundEndReveal(scores, rankings) {
         const T = window.TIMING?.reveal || {};
+
+        // preRevealState may not be set yet if the game_state was deferred
+        // (e.g., local swap animation was in progress). Wait briefly for it.
+        if (!this.preRevealState) {
+            const waitStart = Date.now();
+            while (!this.preRevealState && Date.now() - waitStart < 3000) {
+                await this.delay(100);
+            }
+        }
+
         const oldState = this.preRevealState;
         const newState = this.postRevealState || this.gameState;
 
@@ -2072,22 +2118,35 @@ class GolfGame {
             return;
         }
 
-        // First, render the game with the OLD state (pre-reveal) so cards show face-down
+        // Compute what needs revealing (before renderGame changes the DOM)
-        this.gameState = newState;
-        // But render with pre-reveal card visuals
-        this.revealAnimationInProgress = true;
-
-        // Render game to show current layout (opponents, etc)
-        this.renderGame();
-
-        // Compute what needs revealing
         const revealsByPlayer = this.getCardsToReveal(oldState, newState);
 
         // Get reveal order: knocker first, then clockwise
         const knockerId = newState.finisher_id;
         const revealOrder = this.getRevealOrder(newState.players, knockerId);
 
-        // Initial pause
+        // Wait for the last player's animation (swap/discard/draw) to finish
+        // so the final play is visible before the reveal sequence starts
+        const maxWait = 3000;
+        const start = Date.now();
+        while (Date.now() - start < maxWait) {
+            if (!this.isDrawAnimating && !this.opponentSwapAnimation &&
+                !this.opponentDiscardAnimating && !this.localDiscardAnimating &&
+                !this.swapAnimationInProgress) {
+                break;
+            }
+            await this.delay(100);
+        }
+
+        // Extra pause so the final play registers visually before we
+        // re-render the board (renderGame below resets card positions)
+        await this.delay(T.lastPlayPause || 2500);
+
+        // Now render with pre-reveal state (face-down cards) for the reveal sequence
+        this.gameState = newState;
+        this.revealAnimationInProgress = true;
+        this.renderGame();
+
         this.setStatus('Revealing cards...', 'reveal');
         await this.delay(T.initialPause || 500);
 
@@ -2414,8 +2473,13 @@ class GolfGame {
                     this.opponentDiscardAnimating = false;
                     // Set isDrawAnimating to block renderGame from updating discard pile
                     this.isDrawAnimating = true;
+                    // Force discard DOM to show the card being drawn before animation starts
+                    // (previous animation may have blocked renderGame from updating it)
+                    if (oldDiscard) {
+                        this.updateDiscardPileDisplay(oldDiscard);
+                    }
                     console.log('[DEBUG] Opponent draw from discard - setting isDrawAnimating=true');
-                    window.drawAnimations.animateDrawDiscard(drawnCard, () => {
+                    window.drawAnimations.animateDrawDiscard(oldDiscard || drawnCard, () => {
                         console.log('[DEBUG] Opponent draw from discard complete - clearing isDrawAnimating');
                         this.isDrawAnimating = false;
                         onAnimComplete();
@@ -2425,7 +2489,7 @@ class GolfGame {
                     this.opponentSwapAnimation = null;
                     this.opponentDiscardAnimating = false;
                     this.isDrawAnimating = true;
-                    console.log('[DEBUG] Opponent draw from deck - setting isDrawAnimating=true');
+                    console.log('[DEBUG] Opponent draw from deck - setting isDrawAnimating=true, drawnCard:', drawnCard ? `${drawnCard.rank} of ${drawnCard.suit}` : 'NULL', 'discardTop:', newDiscard ? `${newDiscard.rank} of ${newDiscard.suit}` : 'EMPTY');
                     window.drawAnimations.animateDrawDeck(drawnCard, () => {
                         console.log('[DEBUG] Opponent draw from deck complete - clearing isDrawAnimating');
                         this.isDrawAnimating = false;
@@ -2506,6 +2570,7 @@ class GolfGame {
                 const cardsIdentical = wasOtherPlayer && JSON.stringify(oldPlayer.cards) === JSON.stringify(newPlayer.cards);
 
                 if (swappedPosition >= 0 && wasOtherPlayer) {
+                    console.log('[DEBUG] Swap detected:', { playerId: previousPlayerId, position: swappedPosition, wasFaceUp, newDiscard: newDiscard?.rank });
                     // Opponent swapped - animate from the actual position that changed
                     this.fireSwapAnimation(previousPlayerId, newDiscard, swappedPosition, wasFaceUp);
                     // Show CPU swap announcement
@@ -2807,16 +2872,7 @@ class GolfGame {
 
         // Use unified swap animation
         if (window.cardAnimations) {
-            // For opponent swaps, size the held card to match the opponent card
+            const heldRect = window.cardAnimations.getHoldingRect();
-            // rather than the deck size (default holding rect uses deck dimensions,
-            // which looks oversized next to small opponent cards on mobile)
-            const holdingRect = window.cardAnimations.getHoldingRect();
-            const heldRect = holdingRect ? {
-                left: holdingRect.left,
-                top: holdingRect.top,
-                width: sourceRect.width,
-                height: sourceRect.height
-            } : null;
 
             window.cardAnimations.animateUnifiedSwap(
                 discardCard,        // handCardData - card going to discard
@@ -2827,22 +2883,28 @@ class GolfGame {
                     rotation: sourceRotation,
                     wasHandFaceDown: !wasFaceUp,
                     onComplete: () => {
-                        sourceCardEl.classList.remove('swap-out');
+                        if (sourceCardEl) sourceCardEl.classList.remove('swap-out');
                         this.opponentSwapAnimation = null;
                         this.opponentDiscardAnimating = false;
                         console.log('[DEBUG] Swap animation complete - clearing opponentSwapAnimation and opponentDiscardAnimating');
-                        this.renderGame();
+                        // Don't re-render during reveal animation - it handles its own rendering
+                        if (!this.revealAnimationInProgress) {
+                            this.renderGame();
+                        }
                     }
                 }
             );
         } else {
             // Fallback
             setTimeout(() => {
-                sourceCardEl.classList.remove('swap-out');
+                if (sourceCardEl) sourceCardEl.classList.remove('swap-out');
                 this.opponentSwapAnimation = null;
                 this.opponentDiscardAnimating = false;
                 console.log('[DEBUG] Swap animation fallback complete - clearing flags');
-                this.renderGame();
+                // Don't re-render during reveal animation - it handles its own rendering
+                if (!this.revealAnimationInProgress) {
+                    this.renderGame();
+                }
             }, 500);
         }
     }
@@ -2864,6 +2926,11 @@ class GolfGame {
         if (window.cardAnimations) {
             window.cardAnimations.animateInitialFlip(cardEl, cardData, () => {
                 this.animatingPositions.delete(key);
+                // Unhide the current card element (may have been rebuilt by renderGame)
+                const currentCards = this.playerCards.querySelectorAll('.card');
+                if (currentCards[position]) {
+                    currentCards[position].style.visibility = '';
+                }
             });
         } else {
             // Fallback if card animations not available
@@ -2968,7 +3035,7 @@ class GolfGame {
                 this.hideToast();
             } else {
                 const remaining = requiredFlips - uniquePositions.length;
-                this.showToast(`Select ${remaining} more card${remaining > 1 ? 's' : ''} to flip`, '', 5000);
+                this.showToast(`Select ${remaining} more card${remaining > 1 ? 's' : ''} to flip`, 'your-turn', 5000);
             }
             return;
         }
@@ -3066,6 +3133,14 @@ class GolfGame {
     }
 
     showLobby() {
+        if (window.cardAnimations) {
+            window.cardAnimations.cancelAll();
+        }
+        this.dealAnimationInProgress = false;
+        this.isDrawAnimating = false;
+        this.localDiscardAnimating = false;
+        this.opponentDiscardAnimating = false;
+        this.opponentSwapAnimation = false;
         this.showScreen(this.lobbyScreen);
         this.lobbyError.textContent = '';
         this.roomCode = null;
@@ -3138,6 +3213,24 @@ class GolfGame {
                 `<span class="rule-tag rule-more" title="${tooltip}">+${moreCount} more</span>`;
         }
         this.activeRulesBar.classList.remove('hidden');
+
+        // Update mobile rules indicator
+        const mobileRulesBtn = document.getElementById('mobile-rules-btn');
+        const mobileRulesIcon = document.getElementById('mobile-rules-icon');
+        const mobileRulesContent = document.getElementById('mobile-rules-content');
+        if (mobileRulesBtn && mobileRulesIcon && mobileRulesContent) {
+            const isHouseRules = rules.length > 0;
+            mobileRulesIcon.textContent = isHouseRules ? '!' : 'RULES';
+            mobileRulesBtn.classList.toggle('house-rules', isHouseRules);
+
+            if (!isHouseRules) {
+                mobileRulesContent.innerHTML = '<div class="mobile-rules-content-list"><span class="rule-tag standard">Standard Rules</span></div>';
+            } else {
+                const tagHtml = (unrankedTag ? '<span class="rule-tag unranked">Unranked</span>' : '') +
+                    rules.map(renderTag).join('');
+                mobileRulesContent.innerHTML = `<div class="mobile-rules-content-list">${tagHtml}</div>`;
+            }
+        }
     }
 
     // V3_14: Map display names to rule keys
@@ -3544,7 +3637,9 @@ class GolfGame {
         const cardHeight = deckRect.height;
 
         // Position card centered, overlapping both piles (lower than before)
-        const overlapOffset = cardHeight * 0.35; // More overlap = lower position
+        // On mobile portrait, place held card fully above the deck/discard area
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
         const cardLeft = centerX - cardWidth / 2;
         const cardTop = deckRect.top - overlapOffset;
         this.heldCardFloating.style.left = `${cardLeft}px`;
@@ -3556,11 +3651,21 @@ class GolfGame {
             this.heldCardFloating.style.fontSize = `${cardWidth * 0.35}px`;
         }
 
-        // Position discard button attached to right side of held card
+        // Position discard button
-        const buttonLeft = cardLeft + cardWidth; // Right edge of card (no gap)
+        if (isMobilePortrait) {
-        const buttonTop = cardTop + cardHeight * 0.3; // Vertically centered on card
+            // Below the held card, centered
-        this.discardBtn.style.left = `${buttonLeft}px`;
+            const btnRect = this.discardBtn.getBoundingClientRect();
-        this.discardBtn.style.top = `${buttonTop}px`;
+            const buttonLeft = cardLeft + (cardWidth - (btnRect.width || 70)) / 2;
+            const buttonTop = cardTop + cardHeight + 4;
+            this.discardBtn.style.left = `${buttonLeft}px`;
+            this.discardBtn.style.top = `${buttonTop}px`;
+        } else {
+            // Right side of held card (desktop)
+            const buttonLeft = cardLeft + cardWidth;
+            const buttonTop = cardTop + cardHeight * 0.3;
+            this.discardBtn.style.left = `${buttonLeft}px`;
+            this.discardBtn.style.top = `${buttonTop}px`;
+        }
 
         if (card.rank === '★') {
             this.heldCardFloating.classList.add('joker');
@@ -3606,7 +3711,8 @@ class GolfGame {
         const centerX = (deckRect.left + deckRect.right + discardRect.left + discardRect.right) / 4;
         const cardWidth = deckRect.width;
         const cardHeight = deckRect.height;
-        const overlapOffset = cardHeight * 0.35;
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
         const cardLeft = centerX - cardWidth / 2;
         const cardTop = deckRect.top - overlapOffset;
 
@@ -3778,14 +3884,19 @@ class GolfGame {
         if (mobileTotal) mobileTotal.textContent = this.gameState.total_rounds;
 
         // Show/hide final turn badge with enhanced urgency
+        // Note: markKnocker() is deferred until after opponent areas are rebuilt below
         const isFinalTurn = this.gameState.phase === 'final_turn';
         if (isFinalTurn) {
-            this.updateFinalTurnDisplay();
+            this.gameScreen.classList.add('final-turn-active');
+            this.finalTurnBadge.classList.remove('hidden');
+            if (!this.finalTurnAnnounced) {
+                this.playSound('alert');
+                this.finalTurnAnnounced = true;
+            }
         } else {
             this.finalTurnBadge.classList.add('hidden');
             this.gameScreen.classList.remove('final-turn-active');
             this.finalTurnAnnounced = false;
-            this.clearKnockerMark();
         }
 
         // Toggle not-my-turn class to disable hover effects when it's not player's turn
@@ -3807,7 +3918,7 @@ class GolfGame {
             : this.gameState.current_player_id;
         const displayedPlayer = this.gameState.players.find(p => p.id === displayedPlayerId);
         if (displayedPlayer && displayedPlayerId !== this.playerId) {
-            this.setStatus(`${displayedPlayer.name}'s turn`);
+            this.setStatus(`${displayedPlayer.name}'s turn`, 'opponent-turn');
         }
 
         // Update player header (name + score like opponents)
@@ -4094,7 +4205,13 @@ class GolfGame {
                 cardEl.firstChild.addEventListener('click', () => this.handleCardClick(index));
                 // V3_13: Bind tooltip events for face-up cards
                 this.bindCardTooltipEvents(cardEl.firstChild, displayCard);
-                this.playerCards.appendChild(cardEl.firstChild);
+                const appendedCard = cardEl.firstChild;
+                this.playerCards.appendChild(appendedCard);
+
+                // Hide card if flip animation overlay is active on this position
+                if (this.animatingPositions.has(`local-${index}`)) {
+                    appendedCard.style.visibility = 'hidden';
+                }
             });
         }
 
@@ -4151,6 +4268,13 @@ class GolfGame {
         // Update scoreboard panel
         this.updateScorePanel();
 
+        // Mark knocker AFTER opponent areas are rebuilt (otherwise innerHTML='' wipes it)
+        if (this.gameState.phase === 'final_turn') {
+            this.markKnocker(this.gameState.finisher_id);
+        } else {
+            this.clearKnockerMark();
+        }
+
         // Initialize anime.js hover listeners on newly created cards
         if (window.cardAnimations) {
             window.cardAnimations.initHoverListeners(this.playerCards);

client/card-animations.js

@@ -46,7 +46,8 @@ class CardAnimations {
         const centerX = (deckRect.left + deckRect.right + discardRect.left + discardRect.right) / 4;
         const cardWidth = deckRect.width;
         const cardHeight = deckRect.height;
-        const overlapOffset = cardHeight * 0.35;
+        const isMobilePortrait = document.body.classList.contains('mobile-portrait');
+        const overlapOffset = cardHeight * (isMobilePortrait ? 0.48 : 0.35);
 
         return {
             left: centerX - cardWidth / 2,
@@ -155,12 +156,20 @@ class CardAnimations {
         }
         this.activeAnimations.clear();
 
-        // Remove all animation card elements (including those marked as animating)
+        // Remove all animation overlay elements
-        document.querySelectorAll('.draw-anim-card').forEach(el => {
+        document.querySelectorAll('.draw-anim-card, .traveling-card, .deal-anim-container').forEach(el => {
             delete el.dataset.animating;
             el.remove();
         });
 
+        // Restore visibility on any cards hidden during animations
+        document.querySelectorAll('.card[style*="opacity: 0"], .card[style*="opacity:0"]').forEach(el => {
+            el.style.opacity = '';
+        });
+        document.querySelectorAll('.card[style*="visibility: hidden"], .card[style*="visibility:hidden"]').forEach(el => {
+            el.style.visibility = '';
+        });
+
         // Restore discard pile visibility if it was hidden during animation
         const discardPile = document.getElementById('discard');
         if (discardPile && discardPile.style.opacity === '0') {
@@ -211,6 +220,7 @@ class CardAnimations {
     }
 
     _animateDrawDeckCard(cardData, deckRect, holdingRect, onComplete) {
+        console.log('[DEBUG] _animateDrawDeckCard called with cardData:', cardData ? `${cardData.rank} of ${cardData.suit}` : 'NULL');
         const deckColor = this.getDeckColor();
         const animCard = this.createAnimCard(deckRect, true, deckColor);
         animCard.dataset.animating = 'true'; // Mark as actively animating
@@ -219,6 +229,9 @@ class CardAnimations {
 
         if (cardData) {
             this.setCardContent(animCard, cardData);
+            // Debug: verify what was actually set on the front face
+            const front = animCard.querySelector('.draw-anim-front');
+            console.log('[DEBUG] Draw anim card front content:', front?.innerHTML);
         }
 
         this.playSound('draw-deck');
@@ -407,6 +420,7 @@ class CardAnimations {
     }
 
     // Animate initial flip at game start - smooth flip only, no lift
+    // Uses overlay sized to match the source card exactly
     animateInitialFlip(cardElement, cardData, onComplete) {
         if (!cardElement) {
             if (onComplete) onComplete();
@@ -420,8 +434,16 @@ class CardAnimations {
         const animCard = this.createAnimCard(rect, true, deckColor);
         this.setCardContent(animCard, cardData);
 
-        // Hide original card during animation
+        // Match the front face styling to player hand cards (not deck/discard cards)
-        cardElement.style.opacity = '0';
+        const front = animCard.querySelector('.draw-anim-front');
+        if (front) {
+            front.style.background = 'linear-gradient(145deg, #fff 0%, #f5f5f5 100%)';
+            front.style.border = '2px solid #ddd';
+            front.style.boxShadow = '0 2px 8px rgba(0, 0, 0, 0.3)';
+        }
+
+        // Hide original card during animation (overlay covers it)
+        cardElement.style.visibility = 'hidden';
 
         const inner = animCard.querySelector('.draw-anim-inner');
         const duration = window.TIMING?.card?.flip || 320;
@@ -436,7 +458,7 @@ class CardAnimations {
                 begin: () => this.playSound('flip'),
                 complete: () => {
                     animCard.remove();
-                    cardElement.style.opacity = '1';
+                    cardElement.style.visibility = '';
                     if (onComplete) onComplete();
                 }
             });
@@ -445,7 +467,7 @@ class CardAnimations {
         } catch (e) {
             console.error('Initial flip animation error:', e);
             animCard.remove();
-            cardElement.style.opacity = '1';
+            cardElement.style.visibility = '';
             if (onComplete) onComplete();
         }
     }
@@ -750,28 +772,36 @@ class CardAnimations {
         const id = 'turnPulse';
         this.stopTurnPulse(element);
 
-        // Quick shake animation
+        // Quick shake animation - target cards only, not labels
+        const T = window.TIMING?.turnPulse || {};
+        const cards = element.querySelectorAll(':scope > .pile-wrapper > .card, :scope > .pile-wrapper > .discard-stack > #discard');
         const doShake = () => {
             if (!this.activeAnimations.has(id)) return;
 
             anime({
-                targets: element,
+                targets: cards.length ? cards : element,
-                translateX: [0, -8, 8, -6, 4, 0],
+                translateX: [0, -6, 6, -4, 3, 0],
-                duration: 400,
+                duration: T.duration || 300,
                 easing: 'easeInOutQuad'
             });
         };
 
-        // Do initial shake, then repeat every 3 seconds
+        // Delay first shake, then repeat at interval
-        doShake();
+        const timeout = setTimeout(() => {
-        const interval = setInterval(doShake, 3000);
+            if (!this.activeAnimations.has(id)) return;
-        this.activeAnimations.set(id, { interval });
+            doShake();
+            const interval = setInterval(doShake, T.interval || 3000);
+            const entry = this.activeAnimations.get(id);
+            if (entry) entry.interval = interval;
+        }, T.initialDelay || 5000);
+        this.activeAnimations.set(id, { timeout });
     }
 
     stopTurnPulse(element) {
         const id = 'turnPulse';
         const existing = this.activeAnimations.get(id);
         if (existing) {
+            if (existing.timeout) clearTimeout(existing.timeout);
             if (existing.interval) clearInterval(existing.interval);
             if (existing.pause) existing.pause();
             this.activeAnimations.delete(id);
@@ -1097,7 +1127,7 @@ class CardAnimations {
                 });
                 // Now run the swap animation
                 this._runUnifiedSwap(handCardData, heldCardData, handRect, heldRect, discardRect, T, rotation, wasHandFaceDown, onComplete);
-            }, 100);
+            }, 350);
             return;
         }
 
@@ -1515,6 +1545,7 @@ class CardAnimations {
 
         // Create container for animation cards
         const container = document.createElement('div');
+        container.className = 'deal-anim-container';
         container.style.cssText = 'position:fixed;top:0;left:0;right:0;bottom:0;pointer-events:none;z-index:1000;';
         document.body.appendChild(container);
 

client/golfball-logo.svg

@@ -59,9 +59,9 @@
   <!-- Outer edge highlight -->
   <circle cx="50" cy="44" r="46" fill="none" stroke="#ffffff" stroke-width="0.5" opacity="0.5"/>
 
-  <!-- Card suits - single row, larger -->
+  <!-- Card suits - 2x2 grid -->
-  <text x="22" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9827;</text>
+  <text x="36" y="40" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9827;</text>
-  <text x="41" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9830;</text>
+  <text x="64" y="40" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9830;</text>
-  <text x="59" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9824;</text>
+  <text x="36" y="64" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9829;</text>
-  <text x="77" y="51" font-family="Arial, sans-serif" font-size="32" font-weight="bold" fill="#cc0000" text-anchor="middle">&#9829;</text>
+  <text x="64" y="64" font-family="Arial, sans-serif" font-size="28" font-weight="bold" fill="#1a1a1a" text-anchor="middle">&#9824;</text>
 </svg>

client/index.html

@@ -16,10 +16,10 @@
 
         <!-- Lobby Screen -->
         <div id="lobby-screen" class="screen active">
-            <h1><img src="golfball-logo.svg" alt="" class="golfball-logo"><span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span> <span class="golf-title">Golf</span></h1>
+            <h1><span class="logo-row"><img src="golfball-logo.svg" alt="" class="golfball-logo"><span class="golfer-container"><span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span></span></span> <span class="golf-title">GolfCards<span class="golf-title-tld">.club</span></span></h1>
             <p class="subtitle">6-Card Golf Card Game <button id="rules-btn" class="btn btn-small btn-rules">Rules</button> <button id="leaderboard-btn" class="btn btn-small leaderboard-btn">Leaderboard</button></p>
 
-            <div class="alpha-banner">Alpha &mdash; Things may break. Stats may be wiped.</div>
+            <div class="alpha-banner">Beta Testing - Bear with us while, stuff.</div>
 
             <!-- Auth prompt for unauthenticated users -->
             <div id="auth-prompt" class="auth-prompt">
@@ -53,6 +53,8 @@
             </div>
 
             <p id="lobby-error" class="error"></p>
+
+            <footer class="app-footer">v3.1.6 &copy; Aaron D. Lee</footer>
         </div>
 
         <!-- Matchmaking Screen -->
@@ -80,15 +82,15 @@
             <div class="waiting-layout">
                 <div class="waiting-left-col">
                     <div class="players-list">
-                        <h3>Players</h3>
+                        <div class="players-list-header">
-                        <ul id="players-list"></ul>
+                            <h3>Players</h3>
-                    </div>
+                            <div id="cpu-controls-section" class="cpu-controls hidden">
-                    <div id="cpu-controls-section" class="cpu-controls-section hidden">
+                                <span class="cpu-controls-label">CPU:</span>
-                        <h4>Add CPU Opponents</h4>
+                                <button id="remove-cpu-btn" class="cpu-ctrl-btn btn-danger" title="Remove CPU">−</button>
-                        <div class="cpu-controls">
+                                <button id="add-cpu-btn" class="cpu-ctrl-btn btn-success" title="Add CPU">+</button>
-                            <button id="remove-cpu-btn" class="btn btn-small btn-danger" title="Remove last CPU">−</button>
+                            </div>
-                            <button id="add-cpu-btn" class="btn btn-small btn-success" title="Add CPU player">+</button>
                         </div>
+                        <ul id="players-list"></ul>
                     </div>
                     <button id="leave-room-btn" class="btn btn-danger">Leave Room</button>
                 </div>
@@ -284,6 +286,8 @@
 
                 <p id="waiting-message" class="info">Waiting for host to start the game...</p>
             </div>
+
+            <footer class="app-footer">v3.1.6 &copy; Aaron D. Lee</footer>
         </div>
 
         <!-- Game Screen -->
@@ -328,18 +332,24 @@
                                         </div>
                                         <span class="held-label">Holding</span>
                                     </div>
-                                    <div id="deck" class="card card-back"></div>
+                                    <div class="pile-wrapper">
-                                    <div class="discard-stack">
+                                        <span class="pile-label">DRAW</span>
-                                        <div id="discard" class="card">
+                                        <div id="deck" class="card card-back"></div>
-                                            <span id="discard-content"></span>
+                                    </div>
+                                    <div class="pile-wrapper">
+                                        <span class="pile-label">DISCARD</span>
+                                        <div class="discard-stack">
+                                            <div id="discard" class="card">
+                                                <span id="discard-content"></span>
+                                            </div>
+                                            <!-- Floating held card (appears larger over discard when holding) -->
+                                            <div id="held-card-floating" class="card card-front held-card-floating hidden">
+                                                <span id="held-card-floating-content"></span>
+                                            </div>
+                                            <button id="discard-btn" class="btn btn-small hidden">Discard</button>
+                                            <button id="skip-flip-btn" class="btn btn-small btn-secondary hidden">Skip Flip</button>
+                                            <button id="knock-early-btn" class="btn btn-small btn-danger hidden">Knock!</button>
                                         </div>
-                                        <!-- Floating held card (appears larger over discard when holding) -->
-                                        <div id="held-card-floating" class="card card-front held-card-floating hidden">
-                                            <span id="held-card-floating-content"></span>
-                                        </div>
-                                        <button id="discard-btn" class="btn btn-small hidden">Discard</button>
-                                        <button id="skip-flip-btn" class="btn btn-small btn-secondary hidden">Skip Flip</button>
-                                        <button id="knock-early-btn" class="btn btn-small btn-danger hidden">Knock!</button>
                                     </div>
                                 </div>
                             </div>
@@ -398,16 +408,23 @@
                         <tbody></tbody>
                     </table>
                 </div>
+
             </div>
 
             <!-- Mobile bottom bar (hidden on desktop) -->
             <div id="mobile-bottom-bar">
                 <div class="mobile-round-info">Hole <span id="mobile-current-round">1</span>/<span id="mobile-total-rounds">9</span></div>
-                <button class="mobile-bar-btn" data-drawer="standings-panel">Standings</button>
+                <button class="mobile-bar-btn mobile-rules-btn" id="mobile-rules-btn" data-drawer="rules-drawer"><span id="mobile-rules-icon">RULES</span></button>
-                <button class="mobile-bar-btn" data-drawer="scoreboard">Scores</button>
+                <button class="mobile-bar-btn" data-drawer="standings-panel">Scorecard</button>
                 <button id="mobile-leave-btn" class="mobile-bar-btn mobile-leave-btn">End Game</button>
             </div>
 
+            <!-- Mobile rules drawer -->
+            <div id="rules-drawer" class="side-panel rules-drawer-panel">
+                <h4>Active Rules</h4>
+                <div id="mobile-rules-content"></div>
+            </div>
+
             <!-- Drawer backdrop for mobile -->
             <div id="drawer-backdrop" class="drawer-backdrop"></div>
         </div>
@@ -415,9 +432,8 @@
         <!-- Rules Screen -->
         <div id="rules-screen" class="screen">
             <div class="rules-container">
-                <button id="rules-back-btn" class="btn rules-back-btn">« Back</button>
-
                 <div class="rules-header">
+                    <button id="rules-back-btn" class="btn rules-back-btn">« Back</button>
                     <h1><span class="golfer-logo">🏌️</span> <span class="golf-title">Golf Rules</span></h1>
                     <p class="rules-subtitle">6-Card Golf Card Game - Complete Guide</p>
                 </div>
@@ -733,9 +749,8 @@ TOTAL: 0 + 8 + 16 = 24 points</pre>
         <!-- Leaderboard Screen -->
         <div id="leaderboard-screen" class="screen">
             <div class="leaderboard-container">
-                <button id="leaderboard-back-btn" class="btn leaderboard-back-btn">&laquo; Back</button>
-
                 <div class="leaderboard-header">
+                    <button id="leaderboard-back-btn" class="btn leaderboard-back-btn">&laquo; Back</button>
                     <h1>Leaderboard</h1>
                     <p class="leaderboard-subtitle">Top players ranked by performance</p>
                 </div>

client/style.css

@@ -42,15 +42,25 @@ body {
 
 /* Lobby Screen */
 #lobby-screen {
-    max-width: 400px;
+    max-width: 550px;
     margin: 0 auto;
     padding: 20px;
     text-align: center;
 }
 
+/* App footer (lobby & waiting room) */
+.app-footer {
+    margin-top: 2rem;
+    padding: 1rem 0;
+    font-size: 0.75rem;
+    color: rgba(255, 255, 255, 0.35);
+    text-align: center;
+}
+
 /* Golf title - golf ball with dimples and shine */
 .golf-title {
-    font-size: 1.3em;
+    display: block;
+    font-size: 1.05em;
     font-weight: 800;
     letter-spacing: 0.02em;
     /* Shiny gradient like a golf ball surface */
@@ -77,15 +87,72 @@ body {
     filter: drop-shadow(1px 1px 1px rgba(0,0,0,0.15));
 }
 
+.golf-title-tld {
+    font-size: 0.45em;
+    font-weight: 600;
+    letter-spacing: 0.15em;
+}
+
 /* Golf ball logo with card suits */
 .golfball-logo {
     width: 1.1em;
     height: 1.1em;
     vertical-align: middle;
-    margin-right: 18px;
+    margin-right: 8px;
     filter: drop-shadow(1px 2px 2px rgba(0,0,0,0.25));
 }
 
+#lobby-screen h1 {
+    display: inline-grid;
+    grid-template-columns: auto;
+    justify-items: start;
+    text-align: left;
+    row-gap: 0;
+}
+
+.logo-row {
+    margin-bottom: 0;
+}
+
+/* Golfer + ball container */
+.golfer-container {
+    position: relative;
+    display: inline-block;
+    margin-left: -2px;
+}
+
+#lobby-game-controls,
+#auth-prompt {
+    max-width: 400px;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+@media (max-width: 500px) {
+    #lobby-screen h1 {
+        display: block;
+        text-align: center;
+        text-indent: -18px;
+    }
+    .logo-row {
+        display: inline;
+        margin-bottom: 0;
+    }
+    .golf-title {
+        display: inline;
+    }
+    .golfball-logo {
+        margin-right: 6px;
+    }
+    .golfer-swing {
+        margin-left: 0;
+        margin-right: 10px;
+    }
+    .golfer-container {
+        margin-left: 15px;
+    }
+}
+
 /* Golfer swing animation */
 .golfer-swing {
     display: inline-block;
@@ -124,44 +191,46 @@ body {
 .kicked-ball {
     display: inline-block;
     font-size: 0.2em;
-    position: relative;
+    position: absolute;
+    right: -8px;
+    bottom: 30%;
     opacity: 0;
     animation: ball-kicked 0.7s linear forwards;
     animation-delay: 0.72s;
 }
 
-/* Trajectory: y = 0.0124x² - 1.42x (parabola with peak at x=57) */
+/* Trajectory: parabolic arc from golfer's front foot, up and to the right */
 @keyframes ball-kicked {
     0% {
-        transform: translate(-12px, 8px) scale(1);
+        transform: translate(0, 0) scale(1);
         opacity: 1;
     }
     15% {
-        transform: translate(8px, -16px) scale(1);
+        transform: translate(20px, -24px) scale(1);
         opacity: 1;
     }
     30% {
-        transform: translate(28px, -31px) scale(1);
+        transform: translate(40px, -39px) scale(1);
         opacity: 1;
     }
     45% {
-        transform: translate(48px, -38px) scale(0.95);
+        transform: translate(60px, -46px) scale(0.95);
         opacity: 1;
     }
     55% {
-        transform: translate(63px, -38px) scale(0.9);
+        transform: translate(75px, -46px) scale(0.9);
         opacity: 1;
     }
     70% {
-        transform: translate(83px, -27px) scale(0.85);
+        transform: translate(95px, -35px) scale(0.85);
         opacity: 0.9;
     }
     85% {
-        transform: translate(103px, -6px) scale(0.75);
+        transform: translate(115px, -14px) scale(0.75);
         opacity: 0.6;
     }
     100% {
-        transform: translate(118px, 25px) scale(0.65);
+        transform: translate(130px, 17px) scale(0.65);
         opacity: 0;
     }
 }
@@ -208,10 +277,11 @@ body {
     background: rgba(0,0,0,0.2);
     border-radius: 10px;
     padding: 15px;
+    margin-bottom: 0;
 }
 
 .waiting-left-col .players-list h3 {
-    margin: 0 0 10px 0;
+    margin: 0;
     font-size: 1rem;
 }
 
@@ -330,29 +400,36 @@ body {
 .deck-cyan { background: linear-gradient(135deg, #00bcd4 0%, #0097a7 100%); }
 .deck-brown { background: linear-gradient(135deg, #8b4513 0%, #5d2f0d 100%); }
 
-/* CPU Controls Section - below players list */
+/* Players List Header with inline CPU controls */
-.cpu-controls-section {
+.players-list-header {
-    background: rgba(0,0,0,0.2);
-    border-radius: 8px;
-    padding: 10px 12px;
-}
-
-.cpu-controls-section h4 {
-    margin: 0 0 6px 0;
-    font-size: 0.8rem;
-    color: #f4a460;
-}
-
-.cpu-controls-section .cpu-controls {
     display: flex;
-    gap: 6px;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 8px;
 }
 
-.cpu-controls-section .cpu-controls .btn {
+.cpu-ctrl-btn {
-    flex: 1;
+    width: 28px;
-    padding: 6px 0;
+    height: 28px;
-    font-size: 1rem;
+    border: none;
+    border-radius: 50%;
+    color: white;
+    font-size: 1.1rem;
     font-weight: bold;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: opacity 0.15s;
+    line-height: 1;
+}
+
+.cpu-ctrl-btn:hover {
+    opacity: 0.85;
+}
+
+.cpu-ctrl-btn:active {
+    opacity: 0.7;
 }
 
 #waiting-message {
@@ -363,12 +440,76 @@ body {
 
 /* Mobile: stack vertically */
 @media (max-width: 700px) {
+    #waiting-screen {
+        padding: 10px 15px;
+    }
+
     .waiting-layout {
         grid-template-columns: 1fr;
+        gap: 10px;
+        padding-top: 72px;
+    }
+
+    .waiting-left-col {
+        gap: 10px;
+    }
+
+    .waiting-left-col .players-list {
+        padding: 12px;
+    }
+
+    .players-list li {
+        padding: 8px 10px;
+        margin-bottom: 6px;
+    }
+
+    #waiting-screen .settings {
+        padding: 15px;
+    }
+
+    #waiting-screen .settings h3 {
+        margin-bottom: 10px;
+    }
+
+    #leave-room-btn {
+        padding: 10px 16px;
+        font-size: 0.9rem;
     }
 
     .basic-settings-row {
-        grid-template-columns: 1fr 1fr;
+        grid-template-columns: auto minmax(80px, auto) 1fr;
+        gap: 8px;
+    }
+
+    .basic-settings-row .form-group label {
+        font-size: 0.75rem;
+    }
+
+    .stepper-control {
+        gap: 4px;
+        padding: 4px 4px;
+    }
+
+    .stepper-btn {
+        width: 24px;
+        height: 24px;
+        font-size: 1rem;
+    }
+
+    .stepper-value {
+        min-width: 18px;
+        font-size: 0.95rem;
+    }
+
+    .basic-settings-row select {
+        padding: 6px 2px;
+        font-size: 0.85rem;
+        text-align: center;
+    }
+
+
+    .deck-color-selector select {
+        min-width: 0;
     }
 }
 
@@ -376,7 +517,7 @@ body {
 .room-code-banner {
     position: fixed;
     top: 0;
-    left: 20px;
+    left: 7px;
     z-index: 100;
     background: linear-gradient(180deg, #d4845a 0%, #c4723f 50%, #b8663a 100%);
     padding: 10px 14px 18px;
@@ -668,7 +809,15 @@ input::placeholder {
 
 .cpu-controls {
     display: flex;
-    gap: 10px;
+    align-items: center;
+    gap: 4px;
+}
+
+.cpu-controls-label {
+    font-size: 0.8rem;
+    color: #f4a460;
+    font-weight: 600;
+    margin-right: 2px;
 }
 
 .checkbox-group {
@@ -1124,6 +1273,20 @@ input::placeholder {
     align-items: flex-start;
 }
 
+.pile-wrapper {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+}
+
+.pile-label {
+    font-size: 0.55rem;
+    font-weight: 700;
+    letter-spacing: 0.1em;
+    color: rgba(255, 255, 255, 0.4);
+    margin-bottom: 3px;
+}
+
 /* Gentle pulse when it's your turn to draw - handled by anime.js */
 /* The .your-turn-to-draw class triggers anime.js startTurnPulse() */
 
@@ -1651,10 +1814,16 @@ input::placeholder {
     text-align: center;
     white-space: nowrap;
     color: #fff;
+    background: linear-gradient(135deg, #4a6741 0%, #3d5a35 100%);
+}
+
+/* Empty status - hide completely */
+.status-message:empty {
+    display: none;
 }
 
 .status-message.your-turn {
-    background: linear-gradient(135deg, #b5d484 0%, #9ab973 100%);
+    background: linear-gradient(135deg, #c8e6a0 0%, #8fbf5a 100%);
     color: #2d3436;
 }
 
@@ -1670,6 +1839,19 @@ input::placeholder {
     color: #fff;
 }
 
+/* Round/game over status */
+.status-message.round-over,
+.status-message.game-over {
+    background: linear-gradient(135deg, #f0c040 0%, #d4a017 100%);
+    color: #2d3436;
+}
+
+/* Reveal status */
+.status-message.reveal {
+    background: linear-gradient(135deg, #8b7eb8 0%, #6b5b95 100%);
+    color: #fff;
+}
+
 /* Final turn badge - enhanced V3 with countdown */
 .final-turn-badge {
     display: flex;
@@ -1677,8 +1859,8 @@ input::placeholder {
     gap: 6px;
     background: linear-gradient(135deg, #ff6b35 0%, #d63031 100%);
     color: #fff;
-    padding: 6px 14px;
+    padding: 6px 16px;
-    border-radius: 8px;
+    border-radius: 4px;
     font-weight: 700;
     letter-spacing: 0.05em;
     white-space: nowrap;
@@ -1687,7 +1869,7 @@ input::placeholder {
 }
 
 .final-turn-badge .final-turn-text {
-    font-size: 0.85rem;
+    font-size: 0.9rem;
 }
 
 .final-turn-badge.hidden {
@@ -2798,26 +2980,63 @@ input::placeholder {
 /* Mobile adjustments for final results modal */
 @media (max-width: 500px) {
     .final-results-content {
-        padding: 20px 25px;
+        padding: 15px 12px;
+        width: 95%;
     }
 
     .final-results-content h2 {
-        font-size: 1.5rem;
+        font-size: 1.3rem;
+        margin-bottom: 10px;
+    }
+
+    .double-victory-banner {
+        padding: 8px 12px;
+        font-size: 0.95rem;
+        margin-bottom: 12px;
     }
 
     .final-rankings {
-        flex-direction: column;
+        flex-direction: row;
-        gap: 15px;
+        gap: 8px;
+        margin-bottom: 15px;
+    }
+
+    .final-ranking-section {
+        padding: 8px;
+    }
+
+    .final-ranking-section h3 {
+        font-size: 0.7rem;
+        margin-bottom: 6px;
+        padding-bottom: 4px;
     }
 
     .final-rank-row {
+        font-size: 0.8rem;
+        padding: 4px 5px;
+        margin-bottom: 2px;
+    }
+
+    .final-rank-row .rank-pos {
+        width: 22px;
         font-size: 0.9rem;
-        padding: 6px 8px;
+    }
+
+    .final-rank-row .rank-val {
+        font-size: 0.8rem;
+    }
+
+    .final-actions {
+        flex-direction: row;
+        gap: 8px;
+        padding-bottom: 60px;
     }
 
     .final-actions .btn {
-        min-width: 120px;
+        min-width: 0;
-        padding: 12px 20px;
+        flex: 1;
+        padding: 10px 12px;
+        font-size: 0.9rem;
     }
 }
 
@@ -2854,12 +3073,15 @@ input::placeholder {
 
 /* Rules back button */
 .rules-back-btn {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: auto;
     padding: 4px 12px;
     font-size: 0.8rem;
     background: transparent;
     border: 1px solid rgba(255, 255, 255, 0.3);
     color: rgba(255, 255, 255, 0.7);
-    margin-bottom: 15px;
 }
 
 .rules-back-btn:hover {
@@ -2875,6 +3097,7 @@ input::placeholder {
 
 /* Rules header */
 .rules-header {
+    position: relative;
     text-align: center;
     margin-bottom: 25px;
     padding-bottom: 20px;
@@ -3274,7 +3497,7 @@ input::placeholder {
 .auth-bar {
     position: fixed;
     top: 10px;
-    right: 15px;
+    right: 7px;
     display: flex;
     align-items: center;
     gap: 10px;
@@ -3289,7 +3512,11 @@ input::placeholder {
     display: none;
 }
 
-/* Hide global auth-bar when game screen is active */
+/* Hide global auth-bar and remove top padding when game screen is active */
+#app:has(#game-screen.active) {
+    padding-top: 0;
+}
+
 #app:has(#game-screen.active) > .auth-bar {
     display: none !important;
 }
@@ -3511,11 +3738,15 @@ input::placeholder {
     border-radius: 12px;
     padding: 20px 25px;
     border: 1px solid rgba(255, 255, 255, 0.1);
+    margin-top: 0;
 }
 
 .leaderboard-header {
+    position: relative;
     text-align: center;
     margin-bottom: 20px;
+    padding-bottom: 20px;
+    border-bottom: 2px solid rgba(244, 164, 96, 0.3);
 }
 
 .leaderboard-header h1 {
@@ -3532,12 +3763,15 @@ input::placeholder {
 
 /* Leaderboard back button */
 .leaderboard-back-btn {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: auto;
     padding: 4px 12px;
     font-size: 0.8rem;
     background: transparent;
     border: 1px solid rgba(255, 255, 255, 0.3);
     color: rgba(255, 255, 255, 0.7);
-    margin-bottom: 15px;
 }
 
 .leaderboard-back-btn:hover {
@@ -4306,6 +4540,15 @@ input::placeholder {
     text-shadow: 0 1px 1px rgba(255, 255, 255, 0.3);
 }
 
+.player-area .dealer-chip {
+    width: 38px;
+    height: 38px;
+    font-size: 18px;
+    border-width: 2px;
+    bottom: -22px;
+    left: -22px;
+}
+
 /* --- V3_03: Round End Reveal --- */
 .reveal-prompt {
     position: fixed;
@@ -4387,6 +4630,13 @@ input::placeholder {
 .opponent-area.is-knocker {
     border: 2px solid #ff6b35;
     border-radius: 8px;
+    box-shadow: 0 0 12px 3px rgba(255, 107, 53, 0.4);
+    animation: knocker-glow 2s ease-in-out infinite;
+}
+
+@keyframes knocker-glow {
+    0%, 100% { box-shadow: 0 0 12px 3px rgba(255, 107, 53, 0.4); }
+    50% { box-shadow: 0 0 20px 6px rgba(255, 107, 53, 0.6); }
 }
 
 .knocker-badge {
@@ -4713,10 +4963,10 @@ body.screen-shake {
 .scoresheet-content {
     background: linear-gradient(145deg, #1a472a 0%, #0d3320 100%);
     border-radius: 16px;
-    padding: 24px 28px;
+    padding: 14px 18px;
     max-width: 520px;
     width: 92%;
-    max-height: 85vh;
+    max-height: 90vh;
     overflow-y: auto;
     box-shadow:
         0 16px 50px rgba(0, 0, 0, 0.6),
@@ -4728,23 +4978,23 @@ body.screen-shake {
 
 .ss-header {
     text-align: center;
-    font-size: 1.1rem;
+    font-size: 1rem;
     font-weight: 700;
     color: #f4a460;
-    margin-bottom: 18px;
+    margin-bottom: 10px;
     letter-spacing: 0.05em;
 }
 
 .ss-players {
     display: flex;
     flex-direction: column;
-    gap: 14px;
+    gap: 8px;
 }
 
 .ss-player-row {
     background: rgba(0, 0, 0, 0.2);
     border-radius: 10px;
-    padding: 12px 14px;
+    padding: 8px 10px;
     border: 1px solid rgba(255, 255, 255, 0.06);
 }
 
@@ -4752,7 +5002,7 @@ body.screen-shake {
     display: flex;
     align-items: center;
     gap: 8px;
-    margin-bottom: 8px;
+    margin-bottom: 4px;
 }
 
 .ss-player-name {
@@ -4816,10 +5066,10 @@ body.screen-shake {
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: 36px;
+    width: 32px;
-    height: 28px;
+    height: 24px;
     border-radius: 3px;
-    font-size: 0.72rem;
+    font-size: 0.68rem;
     font-weight: 700;
     line-height: 1;
     background: #f5f0e8;
@@ -4894,9 +5144,9 @@ body.screen-shake {
 .ss-next-btn {
     display: block;
     width: 100%;
-    margin-top: 18px;
+    margin-top: 10px;
-    padding: 10px;
+    padding: 8px;
-    font-size: 0.95rem;
+    font-size: 0.9rem;
 }
 
 /* --- V3_11: Swap Animation --- */
@@ -4920,14 +5170,21 @@ body.screen-shake {
 }
 
 body.mobile-portrait {
-    height: var(--app-height, 100vh);
-    overflow: hidden;
     overscroll-behavior: contain;
     touch-action: manipulation;
 }
 
 body.mobile-portrait #app {
     padding: 0;
+}
+
+/* Lock viewport only when game screen is active (allow scrolling on rules, lobby, etc.) */
+body.mobile-portrait:has(#game-screen.active) {
+    height: var(--app-height, 100vh);
+    overflow: hidden;
+}
+
+body.mobile-portrait:has(#game-screen.active) #app {
     height: var(--app-height, 100vh);
     overflow: hidden;
 }
@@ -5002,6 +5259,16 @@ body.mobile-portrait .game-header #leave-game-btn {
     display: none !important;
 }
 
+body.mobile-portrait .rules-container,
+body.mobile-portrait .leaderboard-container,
+body.mobile-portrait #matchmaking-screen {
+    margin-top: 50px;
+}
+
+body.mobile-portrait .header-col-center {
+    justify-content: flex-start;
+}
+
 body.mobile-portrait .status-message {
     font-size: 1.02rem;
     white-space: nowrap;
@@ -5026,11 +5293,14 @@ body.mobile-portrait .mute-btn {
 }
 
 body.mobile-portrait .final-turn-badge {
-    font-size: 0.6rem;
+    padding: 6px 16px;
-    padding: 2px 6px;
     white-space: nowrap;
 }
 
+body.mobile-portrait .final-turn-badge .final-turn-text {
+    font-size: 1.02rem;
+}
+
 /* --- Mobile: Game table — opponents pinned top, rest centered in remaining space --- */
 body.mobile-portrait .game-table {
     display: flex;
@@ -5052,9 +5322,9 @@ body.mobile-portrait .opponents-row {
     flex-wrap: wrap;
     justify-content: center;
     align-items: flex-start;
-    gap: 4px 10px;
+    gap: 9px 10px;
     min-height: 0 !important;
-    padding: 2px 4px 6px;
+    padding: 2px 4px 12px;
     overflow: visible;
     flex-shrink: 0;
 }
@@ -5120,6 +5390,11 @@ body.mobile-portrait .opponent-area .card {
     border-radius: 3px;
 }
 
+body.mobile-portrait .opponent-area .knocker-badge {
+    top: auto;
+    bottom: -10px;
+}
+
 body.mobile-portrait .opponent-showing {
     font-size: 0.85rem;
     padding: 0px 3px;
@@ -5128,7 +5403,7 @@ body.mobile-portrait .opponent-showing {
 
 /* --- Mobile: Deck/Discard area centered --- */
 body.mobile-portrait .table-center {
-    padding: 5px 10px;
+    padding: 20px 10px 5px;
     border-radius: 8px;
 }
 
@@ -5137,7 +5412,7 @@ body.mobile-portrait .deck-area {
     align-items: flex-start;
 }
 
-body.mobile-portrait .deck-area > .card,
+body.mobile-portrait .deck-area .card,
 body.mobile-portrait #deck,
 body.mobile-portrait #discard {
     width: 64px !important;
@@ -5160,7 +5435,8 @@ body.mobile-portrait #discard-btn {
     position: fixed;
     writing-mode: horizontal-tb;
     text-orientation: initial;
-    padding: 8px 16px;
+    width: auto;
+    padding: 6px 18px;
     font-size: 0.8rem;
     border-radius: 8px;
 }
@@ -5184,8 +5460,8 @@ body.mobile-portrait .player-area .dealer-chip {
     height: 22px;
     font-size: 11px;
     border-width: 2px;
-    bottom: auto;
+    top: auto;
-    top: -8px;
+    bottom: -8px;
     left: -8px;
 }
 
@@ -5307,8 +5583,9 @@ body.mobile-portrait .game-buttons {
 /* --- Mobile: Bottom bar --- */
 body.mobile-portrait #mobile-bottom-bar {
     display: flex;
-    justify-content: center;
+    justify-content: space-between;
     align-items: center;
+    align-self: stretch;
     gap: 8px;
     background: none;
     flex-shrink: 0;
@@ -5317,7 +5594,7 @@ body.mobile-portrait #mobile-bottom-bar {
     z-index: 900;
 }
 
-/* Hole indicator — pinned left with pill background */
+/* Hole indicator — pinned left */
 body.mobile-portrait #mobile-bottom-bar .mobile-round-info {
     margin-right: auto;
     color: rgba(255, 255, 255, 0.9);
@@ -5370,6 +5647,59 @@ body.mobile-portrait #mobile-bottom-bar .mobile-bar-btn.active {
     box-shadow: 0 2px 12px rgba(244, 164, 96, 0.4);
 }
 
+/* --- Mobile: Rules indicator button --- */
+body.mobile-portrait #mobile-bottom-bar .mobile-rules-btn {
+    padding: 4px 9px;
+    font-size: 0.77rem;
+    font-weight: 700;
+    min-width: unset;
+    background: rgba(255, 255, 255, 0.1);
+    border: 1px solid rgba(255, 255, 255, 0.15);
+    color: rgba(255, 255, 255, 0.7);
+}
+
+body.mobile-portrait #mobile-bottom-bar .mobile-rules-btn.house-rules {
+    background: rgba(244, 164, 96, 0.25);
+    border-color: rgba(244, 164, 96, 0.4);
+    color: #f4a460;
+}
+
+/* --- Mobile: Rules drawer content --- */
+#rules-drawer {
+    display: none;
+}
+
+body.mobile-portrait #rules-drawer {
+    display: block;
+}
+
+body.mobile-portrait .rules-drawer-panel .mobile-rules-content-list {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 6px;
+    margin-top: 8px;
+}
+
+body.mobile-portrait .rules-drawer-panel .rule-tag {
+    background: rgba(244, 164, 96, 0.3);
+    color: #f4a460;
+    padding: 4px 10px;
+    border-radius: 4px;
+    font-size: 0.8rem;
+    font-weight: 600;
+}
+
+body.mobile-portrait .rules-drawer-panel .rule-tag.standard {
+    background: rgba(255, 255, 255, 0.15);
+    color: rgba(255, 255, 255, 0.7);
+}
+
+body.mobile-portrait .rules-drawer-panel .rule-tag.unranked {
+    background: rgba(220, 80, 80, 0.3);
+    color: #f08080;
+    border: 1px solid rgba(220, 80, 80, 0.4);
+}
+
 /* --- Mobile: Non-game screens --- */
 body.mobile-portrait #lobby-screen {
     padding: 55px 12px 15px;
@@ -5378,11 +5708,12 @@ body.mobile-portrait #lobby-screen {
 }
 
 body.mobile-portrait #waiting-screen {
-    padding: 10px 12px;
+    padding: 10px 15px;
     overflow-y: auto;
     max-height: 100dvh;
 }
 
+
 /* --- Mobile: Compact scoresheet modal --- */
 body.mobile-portrait .scoresheet-content {
     padding: 14px 16px;
@@ -5443,6 +5774,7 @@ body.mobile-portrait .ss-next-btn {
     font-size: 0.85rem;
 }
 
+
 /* --- Mobile: Very short screens (e.g. iPhone SE) --- */
 @media (max-height: 600px) {
     body.mobile-portrait .opponents-row {
@@ -5465,7 +5797,7 @@ body.mobile-portrait .ss-next-btn {
         padding: 3px 8px;
     }
 
-    body.mobile-portrait .deck-area > .card,
+    body.mobile-portrait .deck-area .card,
     body.mobile-portrait #deck,
     body.mobile-portrait #discard {
         width: 60px !important;

client/timing-config.js

@@ -77,6 +77,7 @@ const TIMING = {
 
     // V3_03: Round end reveal timing
     reveal: {
+        lastPlayPause: 2000,      // Pause after last play animation before reveals
         voluntaryWindow: 2000,    // Time for players to flip their own cards
         initialPause: 250,        // Pause before auto-reveals start
         cardStagger: 50,          // Between cards in same hand
@@ -128,6 +129,13 @@ const TIMING = {
         pulseDelay: 200,        // Delay before card appears (pulse visible first)
     },
 
+    // Turn pulse (deck shake)
+    turnPulse: {
+        initialDelay: 5000,       // Delay before first shake
+        interval: 5400,           // Time between shakes
+        duration: 300,            // Shake animation duration
+    },
+
     // V3_17: Knock notification
     knock: {
         statusDuration: 2500,       // How long the knock status message persists

docker-compose.prod.yml

@@ -28,8 +28,14 @@ services:
       - RESEND_API_KEY=${RESEND_API_KEY:-}
       - EMAIL_FROM=${EMAIL_FROM:-Golf Cards <noreply@contact.golfcards.club>}
       - SENTRY_DSN=${SENTRY_DSN:-}
-      - ENVIRONMENT=production
+      - ENVIRONMENT=${ENVIRONMENT:-production}
-      - LOG_LEVEL=INFO
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - LOG_LEVEL_GAME=${LOG_LEVEL_GAME:-}
+      - LOG_LEVEL_AI=${LOG_LEVEL_AI:-}
+      - LOG_LEVEL_HANDLERS=${LOG_LEVEL_HANDLERS:-}
+      - LOG_LEVEL_ROOM=${LOG_LEVEL_ROOM:-}
+      - LOG_LEVEL_AUTH=${LOG_LEVEL_AUTH:-}
+      - LOG_LEVEL_STORES=${LOG_LEVEL_STORES:-}
       - BASE_URL=${BASE_URL:-https://golf.example.com}
       - RATE_LIMIT_ENABLED=true
       - INVITE_ONLY=true

docker-compose.staging.yml

@@ -0,0 +1,146 @@
+# Staging Docker Compose for Golf Card Game
+#
+# Mirrors production but with reduced memory limits for 512MB droplet.
+#
+# Usage:
+#   docker compose -f docker-compose.staging.yml up -d --build
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - POSTGRES_URL=postgresql://golf:${DB_PASSWORD}@postgres:5432/golf
+      - DATABASE_URL=postgresql://golf:${DB_PASSWORD}@postgres:5432/golf
+      - REDIS_URL=redis://redis:6379
+      - SECRET_KEY=${SECRET_KEY}
+      - RESEND_API_KEY=${RESEND_API_KEY:-}
+      - EMAIL_FROM=${EMAIL_FROM:-Golf Cards <noreply@contact.golfcards.club>}
+      - SENTRY_DSN=${SENTRY_DSN:-}
+      - ENVIRONMENT=${ENVIRONMENT:-staging}
+      - LOG_LEVEL=${LOG_LEVEL:-INFO}
+      - LOG_LEVEL_GAME=${LOG_LEVEL_GAME:-}
+      - LOG_LEVEL_AI=${LOG_LEVEL_AI:-}
+      - LOG_LEVEL_HANDLERS=${LOG_LEVEL_HANDLERS:-}
+      - LOG_LEVEL_ROOM=${LOG_LEVEL_ROOM:-}
+      - LOG_LEVEL_AUTH=${LOG_LEVEL_AUTH:-}
+      - LOG_LEVEL_STORES=${LOG_LEVEL_STORES:-}
+      - BASE_URL=${BASE_URL:-https://staging.golfcards.club}
+      - RATE_LIMIT_ENABLED=false
+      - INVITE_ONLY=true
+      - BOOTSTRAP_ADMIN_USERNAME=${BOOTSTRAP_ADMIN_USERNAME:-}
+      - BOOTSTRAP_ADMIN_PASSWORD=${BOOTSTRAP_ADMIN_PASSWORD:-}
+      - MATCHMAKING_ENABLED=true
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+        max_attempts: 3
+      resources:
+        limits:
+          memory: 128M
+        reservations:
+          memory: 48M
+    networks:
+      - internal
+      - web
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=golfgame_web"
+      - "traefik.http.routers.golf.rule=Host(`${DOMAIN:-staging.golfcards.club}`)"
+      - "traefik.http.routers.golf.entrypoints=websecure"
+      - "traefik.http.routers.golf.tls=true"
+      - "traefik.http.routers.golf.tls.certresolver=letsencrypt"
+      - "traefik.http.services.golf.loadbalancer.server.port=8000"
+      - "traefik.http.services.golf.loadbalancer.sticky.cookie=true"
+      - "traefik.http.services.golf.loadbalancer.sticky.cookie.name=golf_server"
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: golf
+      POSTGRES_USER: golf
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U golf -d golf"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - internal
+    deploy:
+      resources:
+        limits:
+          memory: 96M
+        reservations:
+          memory: 48M
+
+  redis:
+    image: redis:7-alpine
+    command: redis-server --appendonly yes --maxmemory 16mb --maxmemory-policy allkeys-lru
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - internal
+    deploy:
+      resources:
+        limits:
+          memory: 32M
+        reservations:
+          memory: 16M
+
+  traefik:
+    image: traefik:v3.6
+    environment:
+      - DOCKER_API_VERSION=1.44
+    command:
+      - "--api.dashboard=true"
+      - "--api.insecure=true"
+      - "--accesslog=true"
+      - "--log.level=WARN"
+      - "--providers.docker=true"
+      - "--providers.docker.exposedbydefault=false"
+      - "--entrypoints.web.address=:80"
+      - "--entrypoints.web.http.redirections.entryPoint.to=websecure"
+      - "--entrypoints.web.http.redirections.entryPoint.scheme=https"
+      - "--entrypoints.websecure.address=:443"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
+      - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
+      - "--certificatesresolvers.letsencrypt.acme.email=${ACME_EMAIL}"
+      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - letsencrypt:/letsencrypt
+    networks:
+      - web
+    deploy:
+      resources:
+        limits:
+          memory: 48M
+
+volumes:
+  postgres_data:
+  redis_data:
+  letsencrypt:
+
+networks:
+  internal:
+    driver: bridge
+  web:
+    driver: bridge

docs/BUG-kicked-ball-position.md

@@ -0,0 +1,77 @@
+# BUG: Kicked ball animation starts from golfer's back foot
+
+## Problem
+
+The `⚪` kicked ball animation (`.kicked-ball`) appears to launch from the golfer's **back foot** (left side) instead of the **front foot** (right side). The golfer faces right in both landscape (two-row) and mobile (single-line) views due to `scaleX(-1)`.
+
+## What we want
+
+The ball should appear at the golfer's front foot (right side) and arc up and to the right — matching the "good" landscape behavior seen at wide desktop widths (~1100px+).
+
+## Good reference
+
+- Video: `good.mp4` (landscape wide view)
+- Extracted frames: `/tmp/golf-frames-good/`
+- Frame 025: Ball clearly appears to the RIGHT of the golfer, arcing up-right
+
+## Bad behavior
+
+- Videos: `Screencast_20260224_005555.mp4`, `Screencast_20260224_013326.mp4`
+- The ball appears to the LEFT of the golfer (between the golf ball logo and golfer emoji)
+- Happens at the user's phone viewport width (two-row layout, inline-grid)
+
+## Root cause analysis
+
+### The scaleX(-1) offset problem
+
+The golfer emoji (`.golfer-swing`) has `transform: scaleX(-1)` which flips it visually. This means:
+- The golfer's **layout box** occupies the same inline flow position
+- But the **visual** left/right is flipped — the front foot (visually on the right) is at the LEFT edge of the layout box
+- The `.kicked-ball` span comes right after `.golfer-swing` in inline flow, so its natural position is at the **right edge** of the golfer's layout box
+- But due to `scaleX(-1)`, the right edge of the layout box is the golfer's **visual back** (left side)
+- So `translate(0, 0)` places the ball at the golfer's back, not front
+
+### CSS translate values tested
+
+| Start X | Result |
+|---------|--------|
+| `-30px` (original) | Ball appears way behind golfer (further left) |
+| `+20px` | Ball still appears to LEFT of golfer, but slightly closer |
+| `+80px` | Not confirmed (staging 404 during test) |
+
+### Key finding: The kicked-ball's natural position needs ~60-80px positive X offset to reach the golfer's visual front foot
+
+The golfer emoji is roughly 30-40px wide at this viewport. Since `scaleX(-1)` flips the visual, the ball needs to translate **past the entire emoji width** to reach the visual front.
+
+### Media query issues encountered
+
+1. First attempt: Added `ball-kicked-mobile` keyframes with `@media (max-width: 500px)` override
+2. **CSS source order bug**: The mobile override at line 144 was being overridden by the base `.kicked-ball` rule at line 216 (later = higher priority at equal specificity)
+3. Moved override after base rule — still didn't work
+4. Added `!important` — still didn't work
+5. Raised breakpoint from 500px to 768px, then 1200px — still no visible change
+6. **Breakthrough**: Added `outline: 3px solid red; background: yellow` debug styles to base `.kicked-ball` — these DID appear, confirming CSS was loading
+7. Changed base `ball-kicked` keyframes from `-30px` to `+20px` — ball DID move, confirming the base keyframes are what's being used
+8. The mobile override keyframes may never have been applied (unclear if `ball-kicked-mobile` was actually used)
+
+### What the Chrome extension Claude analysis said
+
+> "The breakpoint is 500px, but the viewport is above 500px. At 700px+, ball-kicked-mobile never kicks in — it still uses the desktop ball-kicked animation. But the layout at this width has already shifted to a more centered layout which changes where .kicked-ball is positioned relative to the golfer."
+
+## Suggested fix approach
+
+1. **Don't use separate mobile keyframes** — just fix the base `ball-kicked` to work at all viewport widths
+2. The starting X needs to be **much larger positive** (60-80px) to account for `scaleX(-1)` placing the natural position at the golfer's visual back
+3. Alternatively, restructure the HTML: move `.kicked-ball` BEFORE `.golfer-swing` in the DOM, so its natural inline position is at the golfer's visual front (since scaleX(-1) flips left/right)
+4. Or use `position: absolute` on `.kicked-ball` and position it relative to the golfer container explicitly
+
+## Files involved
+
+- `client/style.css` — `.kicked-ball`, `@keyframes ball-kicked`, `.golfer-swing`
+- `client/index.html` — line 19: `<span class="golfer-swing">🏌️</span><span class="kicked-ball">⚪</span>`
+
+## Resolution (v3.1.6)
+
+**Fixed** by wrapping `.golfer-swing` + `.kicked-ball` in a `.golfer-container` span with `position: relative`, and changing `.kicked-ball` from `position: relative` to `position: absolute; right: -8px; bottom: 30%`. This anchors the ball to the golfer's front foot regardless of viewport width or inline flow layout.
+
+Also fixed a **CSS source order bug** where the base `.golfer-container` rule was defined after the `@media (max-width: 500px)` override, clobbering the mobile margin-left value.

docs/v3/V3_17_MOBILE_PORTRAIT_LAYOUT.md

@@ -1,6 +1,6 @@
 # V3.17: Mobile Portrait Layout
 
-**Version:** 3.1.1
+**Version:** 3.1.6
 **Commits:** `4fcdf13`, `fb3bd53`
 
 ## Overview

docs/v3/V3_18_POSTGRES_STORAGE_EFFICIENCY.md

@@ -0,0 +1,57 @@
+# V3.18: PostgreSQL Game Data Storage Efficiency
+
+**Status:** Planning
+**Priority:** Medium
+**Category:** Infrastructure / Performance
+
+## Problem
+
+Per-move game logging stores full `hand_state` and `visible_opponents` JSONB on every move. For a typical 6-player, 9-hole game this generates significant redundant data since most of each player's hand doesn't change between moves.
+
+## Areas to Investigate
+
+### 1. Delta Encoding for Move Data
+
+Store only what changed from the previous move instead of full state snapshots.
+
+- First move of each round stores full state (baseline)
+- Subsequent moves store only changed positions (e.g., `{"player_0": {"pos_2": "5H"}}`)
+- Replay reconstruction applies deltas sequentially
+- Trade-off: simpler queries vs. storage savings
+
+### 2. PostgreSQL TOAST and Compression
+
+- TOAST already compresses large JSONB values automatically
+- Measure actual on-disk size vs. logical size for typical game data
+- Consider whether explicit compression (e.g., storing gzipped blobs) adds meaningful savings over TOAST
+
+### 3. Retention Policy
+
+- Archive completed games older than N days to a separate table or cold storage
+- Configurable retention period via env var (e.g., `GAME_LOG_RETENTION_DAYS`)
+- Keep aggregate stats even after pruning raw move data
+
+### 4. Move Logging Toggle
+
+- Env var `GAME_LOGGING_ENABLED=true|false` to disable move-level logging entirely
+- Useful for non-analysis environments (dev, load testing)
+- Game outcomes and stats would still be recorded
+
+### 5. Batch Inserts
+
+- Buffer moves in memory and flush periodically instead of per-move INSERT
+- Reduces database round-trips during active games
+- Risk: data loss if server crashes mid-game (acceptable for non-critical move logs)
+
+## Measurements Needed
+
+Before optimizing, measure current impact:
+
+- Average JSONB size per move (bytes)
+- Average moves per game
+- Total storage per game (moves + overhead)
+- Query patterns: how often is per-move data actually read?
+
+## Dependencies
+
+- None (independent infrastructure improvement)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "golfgame"
-version = "3.1.1"
+version = "3.1.6"
 description = "6-Card Golf card game with AI opponents"
 readme = "README.md"
 requires-python = ">=3.11"

scripts/deploy-staging.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -e
+
+DROPLET="root@129.212.150.189"
+REMOTE_DIR="/opt/golfgame"
+
+echo "Syncing to staging ($DROPLET)..."
+rsync -az --delete \
+    --exclude='.git' \
+    --exclude='__pycache__' \
+    --exclude='node_modules' \
+    --exclude='.env' \
+    --exclude='internal/' \
+    server/ "$DROPLET:$REMOTE_DIR/server/"
+rsync -az --delete \
+    --exclude='.git' \
+    --exclude='__pycache__' \
+    --exclude='node_modules' \
+    client/ "$DROPLET:$REMOTE_DIR/client/"
+
+echo "Rebuilding app container..."
+ssh $DROPLET "cd $REMOTE_DIR && docker compose -f docker-compose.staging.yml up -d --build app"
+echo "Staging deploy complete."

server/.env.example

@@ -7,6 +7,24 @@ PORT=8000
 DEBUG=true
 LOG_LEVEL=DEBUG
 
+# Per-module log level overrides (optional)
+# These override LOG_LEVEL for specific modules.
+# LOG_LEVEL_GAME=DEBUG       # Core game logic
+# LOG_LEVEL_AI=DEBUG         # AI decisions (very verbose at DEBUG)
+# LOG_LEVEL_HANDLERS=DEBUG   # WebSocket message handlers
+# LOG_LEVEL_ROOM=DEBUG       # Room/lobby management
+# LOG_LEVEL_AUTH=DEBUG       # Auth stack (auth, routers.auth, services.auth_service)
+# LOG_LEVEL_STORES=DEBUG     # Database/Redis operations
+
+# --- Preset examples ---
+# Staging (debug game logic, quiet everything else):
+#   LOG_LEVEL=INFO
+#   LOG_LEVEL_GAME=DEBUG
+#   LOG_LEVEL_AI=DEBUG
+#
+# Production (minimal logging):
+#   LOG_LEVEL=WARNING
+
 # Environment (development, staging, production)
 # Affects logging format, security headers (HSTS), etc.
 ENVIRONMENT=development

server/ai.py

@@ -43,8 +43,9 @@ CPU_TIMING = {
     # Delay before CPU "looks at" the discard pile
     "initial_look": (0.3, 0.5),
     # Brief pause after draw broadcast - let draw animation complete
-    # Must be >= client draw animation duration (~1s for deck, ~0.4s for discard)
+    # Must be >= client draw animation duration (~1.09s for deck, ~0.4s for discard)
-    "post_draw_settle": 1.1,
+    # Extra margin prevents swap message from arriving before draw flip completes
+    "post_draw_settle": 1.3,
     # Consideration time after drawing (before swap/discard decision)
     "post_draw_consider": (0.2, 0.4),
     # Variance multiplier range for chaotic personality players
@@ -1301,12 +1302,28 @@ class GolfAI:
 
         max_acceptable_go_out = 14 + int(profile.aggression * 4)
 
+        # Check opponent scores - don't go out if we'd lose badly
+        opponent_min = estimate_opponent_min_score(player, game, optimistic=False)
+        # Aggressive players tolerate a bigger gap; conservative ones less
+        opponent_margin = 4 + int(profile.aggression * 4)  # 4-8 points
+        opponent_cap = opponent_min + opponent_margin
+
+        # Use the more restrictive of the two thresholds
+        effective_max = min(max_acceptable_go_out, opponent_cap)
+
         ai_log(f"  Go-out safety check: visible_base={visible_score}, "
                f"score_if_swap={score_if_swap}, score_if_flip={score_if_flip}, "
-               f"max_acceptable={max_acceptable_go_out}")
+               f"max_acceptable={max_acceptable_go_out}, opponent_min={opponent_min}, "
+               f"opponent_cap={opponent_cap}, effective_max={effective_max}")
+
+        # High-card safety: don't swap 8+ into hidden position unless it makes a pair
+        creates_pair = (last_partner.face_up and last_partner.rank == drawn_card.rank)
+        if drawn_value >= HIGH_CARD_THRESHOLD and not creates_pair:
+            ai_log(f"  >> GO-OUT: high card ({drawn_value}) into hidden, preferring flip")
+            return None  # Fall through to normal scoring (will flip)
 
         # If BOTH options are bad, choose the better one
-        if score_if_swap > max_acceptable_go_out and score_if_flip > max_acceptable_go_out:
+        if score_if_swap > effective_max and score_if_flip > effective_max:
             if score_if_swap <= score_if_flip:
                 ai_log(f"  >> SAFETY: both options bad, but swap ({score_if_swap}) "
                        f"<= flip ({score_if_flip}), forcing swap")
@@ -1322,7 +1339,7 @@ class GolfAI:
             return None
 
         # If swap is good, prefer it (known outcome vs unknown flip)
-        elif score_if_swap <= max_acceptable_go_out and score_if_swap <= score_if_flip:
+        elif score_if_swap <= effective_max and score_if_swap <= score_if_flip:
             ai_log(f"  >> SAFETY: swap gives acceptable score {score_if_swap}")
             return last_pos
 
@@ -1739,9 +1756,23 @@ class GolfAI:
         expected_hidden_total = len(face_down) * EXPECTED_HIDDEN_VALUE
         projected_score = visible_score + expected_hidden_total
 
+        # Hard cap: never knock with projected score > 10
+        if projected_score > 10:
+            ai_log(f"  Knock rejected: projected score {projected_score:.1f} > 10 hard cap")
+            return False
+
         # Tighter threshold: range 5 to 9 based on aggression
         max_acceptable = 5 + int(profile.aggression * 4)
 
+        # Check opponent threat - don't knock if an opponent likely beats us
+        opponent_min = estimate_opponent_min_score(player, game, optimistic=False)
+        if opponent_min < projected_score:
+            # Opponent is likely beating us - penalize threshold
+            threat_margin = projected_score - opponent_min
+            max_acceptable -= int(threat_margin * 0.75)
+            ai_log(f"  Knock threat penalty: opponent est {opponent_min}, "
+                   f"margin {threat_margin:.1f}, threshold now {max_acceptable}")
+
         # Exception: if all opponents are showing terrible scores, relax threshold
         all_opponents_bad = all(
             sum(get_ai_card_value(c, game.options) for c in p.cards if c.face_up) >= 25
@@ -1752,12 +1783,14 @@ class GolfAI:
 
         if projected_score <= max_acceptable:
             # Scale knock chance by how good the projected score is
-            if projected_score <= 5:
+            if projected_score <= 4:
-                knock_chance = profile.aggression * 0.3  # Max 30%
+                knock_chance = profile.aggression * 0.35  # Max 35%
-            elif projected_score <= 7:
+            elif projected_score <= 6:
                 knock_chance = profile.aggression * 0.15  # Max 15%
-            else:
+            elif projected_score <= 8:
-                knock_chance = profile.aggression * 0.05  # Max 5% (very rare)
+                knock_chance = profile.aggression * 0.06  # Max 6%
+            else:  # 9-10
+                knock_chance = profile.aggression * 0.02  # Max 2% (very rare)
 
             if random.random() < knock_chance:
                 ai_log(f"  Knock early: taking the gamble! (projected {projected_score:.1f})")
@@ -1934,7 +1967,11 @@ def _log_cpu_action(logger, game_id: Optional[str], cpu_player: Player, game: Ga
 async def process_cpu_turn(
     game: Game, cpu_player: Player, broadcast_callback, game_id: Optional[str] = None
 ) -> None:
-    """Process a complete turn for a CPU player."""
+    """Process a complete turn for a CPU player.
+
+    May raise asyncio.CancelledError if the game is ended mid-turn.
+    The caller (check_and_run_cpu_turn) handles cancellation.
+    """
     import asyncio
     from services.game_logger import get_logger
 
@@ -1962,10 +1999,8 @@ async def process_cpu_turn(
     await asyncio.sleep(thinking_time)
     ai_log(f"{cpu_player.name} done thinking, making decision")
 
-    # Check if we should try to go out early
-    GolfAI.should_go_out_early(cpu_player, game, profile)
-
     # Check if we should knock early (flip all remaining cards at once)
+    # (Opponent threat logic consolidated into should_knock_early)
     if GolfAI.should_knock_early(game, cpu_player, profile):
         if game.knock_early(cpu_player.id):
             _log_cpu_action(logger, game_id, cpu_player, game,

server/handlers.py

@@ -229,7 +229,7 @@ async def handle_start_game(data: dict, ctx: ConnectionContext, *, broadcast_gam
                     "game_state": game_state,
                 })
 
-        await check_and_run_cpu_turn(ctx.current_room)
+        check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_flip_initial(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -240,7 +240,7 @@ async def handle_flip_initial(data: dict, ctx: ConnectionContext, *, broadcast_g
     async with ctx.current_room.game_lock:
         if ctx.current_room.game.flip_initial_cards(ctx.player_id, positions):
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 # ---------------------------------------------------------------------------
@@ -297,7 +297,7 @@ async def handle_swap(data: dict, ctx: ConnectionContext, *, broadcast_game_stat
 
             await broadcast_game_state(ctx.current_room)
             await asyncio.sleep(1.0)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_discard(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -329,12 +329,12 @@ async def handle_discard(data: dict, ctx: ConnectionContext, *, broadcast_game_s
                     })
                 else:
                     await asyncio.sleep(0.5)
-                    await check_and_run_cpu_turn(ctx.current_room)
+                    check_and_run_cpu_turn(ctx.current_room)
             else:
                 logger.debug("Player discarded, waiting 0.5s before CPU turn")
                 await asyncio.sleep(0.5)
                 logger.debug("Post-discard delay complete, checking for CPU turn")
-                await check_and_run_cpu_turn(ctx.current_room)
+                check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_cancel_draw(data: dict, ctx: ConnectionContext, *, broadcast_game_state, **kw) -> None:
@@ -364,7 +364,7 @@ async def handle_flip_card(data: dict, ctx: ConnectionContext, *, broadcast_game
             )
 
         await broadcast_game_state(ctx.current_room)
-        await check_and_run_cpu_turn(ctx.current_room)
+        check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_skip_flip(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -380,7 +380,7 @@ async def handle_skip_flip(data: dict, ctx: ConnectionContext, *, broadcast_game
             )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_flip_as_action(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -400,7 +400,7 @@ async def handle_flip_as_action(data: dict, ctx: ConnectionContext, *, broadcast
                 )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_knock_early(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -418,7 +418,7 @@ async def handle_knock_early(data: dict, ctx: ConnectionContext, *, broadcast_ga
                 )
 
             await broadcast_game_state(ctx.current_room)
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
 
 
 async def handle_next_round(data: dict, ctx: ConnectionContext, *, broadcast_game_state, check_and_run_cpu_turn, **kw) -> None:
@@ -443,7 +443,7 @@ async def handle_next_round(data: dict, ctx: ConnectionContext, *, broadcast_gam
                         "game_state": game_state,
                     })
 
-            await check_and_run_cpu_turn(ctx.current_room)
+            check_and_run_cpu_turn(ctx.current_room)
         else:
             await broadcast_game_state(ctx.current_room)
 
@@ -473,6 +473,15 @@ async def handle_end_game(data: dict, ctx: ConnectionContext, *, room_manager, c
         await ctx.websocket.send_json({"type": "error", "message": "Only the host can end the game"})
         return
 
+    # Cancel any running CPU turn task so the game ends immediately
+    if ctx.current_room.cpu_turn_task:
+        ctx.current_room.cpu_turn_task.cancel()
+        try:
+            await ctx.current_room.cpu_turn_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        ctx.current_room.cpu_turn_task = None
+
     await ctx.current_room.broadcast({
         "type": "game_ended",
         "reason": "Host ended the game",

server/logging_config.py

@@ -148,6 +148,39 @@ class DevelopmentFormatter(logging.Formatter):
         return output
 
 
+# Per-module log level overrides via env vars.
+# Key: env var suffix, Value: list of Python logger names to apply to.
+MODULE_LOGGER_MAP = {
+    "GAME": ["game"],
+    "AI": ["ai"],
+    "HANDLERS": ["handlers"],
+    "ROOM": ["room"],
+    "AUTH": ["auth", "routers.auth", "services.auth_service"],
+    "STORES": ["stores"],
+}
+
+
+def _apply_module_overrides() -> dict[str, str]:
+    """
+    Apply per-module log level overrides from LOG_LEVEL_{MODULE} env vars.
+
+    Returns:
+        Dict of module name -> level for any overrides that were applied.
+    """
+    active = {}
+    for module, logger_names in MODULE_LOGGER_MAP.items():
+        env_val = os.environ.get(f"LOG_LEVEL_{module}", "").upper()
+        if not env_val:
+            continue
+        level = getattr(logging, env_val, None)
+        if level is None:
+            continue
+        active[module] = env_val
+        for name in logger_names:
+            logging.getLogger(name).setLevel(level)
+    return active
+
+
 def setup_logging(
     level: str = "INFO",
     environment: str = "development",
@@ -182,12 +215,19 @@ def setup_logging(
     logging.getLogger("websockets").setLevel(logging.WARNING)
     logging.getLogger("asyncio").setLevel(logging.WARNING)
 
+    # Apply per-module overrides from env vars
+    overrides = _apply_module_overrides()
+
     # Log startup
     logger = logging.getLogger(__name__)
     logger.info(
         f"Logging configured: level={level}, environment={environment}",
         extra={"level": level, "environment": environment},
     )
+    if overrides:
+        logger.info(
+            f"Per-module log level overrides: {', '.join(f'{m}={l}' for m, l in overrides.items())}",
+        )
 
 
 class ContextLogger(logging.LoggerAdapter):

server/main.py

@@ -325,7 +325,7 @@ async def _close_all_websockets():
 app = FastAPI(
     title="Golf Card Game",
     debug=config.DEBUG,
-    version="3.1.1",
+    version="3.1.6",
     lifespan=lifespan,
 )
 
@@ -705,8 +705,13 @@ async def broadcast_game_state(room: Room):
                 })
 
 
-async def check_and_run_cpu_turn(room: Room):
+def check_and_run_cpu_turn(room: Room):
-    """Check if current player is CPU and run their turn."""
+    """Check if current player is CPU and start their turn as a background task.
+
+    The CPU turn chain runs as a fire-and-forget asyncio.Task stored on
+    room.cpu_turn_task. This allows the WebSocket message loop to remain
+    responsive so that end_game/leave messages can cancel the task immediately.
+    """
     if room.game.phase not in (GamePhase.PLAYING, GamePhase.FINAL_TURN):
         return
 
@@ -718,21 +723,54 @@ async def check_and_run_cpu_turn(room: Room):
     if not room_player or not room_player.is_cpu:
         return
 
-    # Brief pause before CPU starts - animations are faster now
+    task = asyncio.create_task(_run_cpu_chain(room))
-    await asyncio.sleep(0.25)
+    room.cpu_turn_task = task
 
-    # Run CPU turn
+    def _on_done(t: asyncio.Task):
-    async def broadcast_cb():
+        # Clear the reference when the task finishes (success, cancel, or error)
-        await broadcast_game_state(room)
+        if room.cpu_turn_task is t:
+            room.cpu_turn_task = None
+        if not t.cancelled() and t.exception():
+            logger.error(f"CPU turn task error in room {room.code}: {t.exception()}")
 
-    await process_cpu_turn(room.game, current, broadcast_cb, game_id=room.game_log_id)
+    task.add_done_callback(_on_done)
 
-    # Check if next player is also CPU (chain CPU turns)
+
-    await check_and_run_cpu_turn(room)
+async def _run_cpu_chain(room: Room):
+    """Run consecutive CPU turns until a human player's turn or game ends."""
+    while True:
+        if room.game.phase not in (GamePhase.PLAYING, GamePhase.FINAL_TURN):
+            return
+
+        current = room.game.current_player()
+        if not current:
+            return
+
+        room_player = room.get_player(current.id)
+        if not room_player or not room_player.is_cpu:
+            return
+
+        # Brief pause before CPU starts - animations are faster now
+        await asyncio.sleep(0.25)
+
+        # Run CPU turn
+        async def broadcast_cb():
+            await broadcast_game_state(room)
+
+        await process_cpu_turn(room.game, current, broadcast_cb, game_id=room.game_log_id)
 
 
 async def handle_player_leave(room: Room, player_id: str):
     """Handle a player leaving a room."""
+    # Cancel any running CPU turn task before cleanup
+    if room.cpu_turn_task:
+        room.cpu_turn_task.cancel()
+        try:
+            await room.cpu_turn_task
+        except (asyncio.CancelledError, Exception):
+            pass
+        room.cpu_turn_task = None
+
     room_code = room.code
     room_player = room.remove_player(player_id)
 

server/room.py

@@ -69,6 +69,7 @@ class Room:
     settings: dict = field(default_factory=lambda: {"decks": 1, "rounds": 1})
     game_log_id: Optional[str] = None
     game_lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    cpu_turn_task: Optional[asyncio.Task] = None
 
     def add_player(
         self,