From a1fb777dd39afdbff064ea60a4df2cee5c67685c Mon Sep 17 00:00:00 2001
From: timofeykafanov <tim.kafanov@gmail.com>
Date: Wed, 11 Mar 2026 21:42:23 +0100
Subject: [PATCH 1/8] feat: add light theme

---
 client/app/app.css                          | 115 +++++++++++++++++++-
 client/app/components/GameModeSelector.tsx  |  18 +--
 client/app/components/LoadingOverlay.tsx    |   6 +-
 client/app/components/ThemeToggle.tsx       |  47 ++++++++
 client/app/components/auth/LoginForm.tsx    |  26 ++---
 client/app/components/auth/RegisterForm.tsx |  34 +++---
 client/app/components/game/GameBoard.tsx    |  40 +++----
 client/app/components/game/GamePage.tsx     |  28 ++---
 client/app/components/game/OpponentCard.tsx |  18 +--
 client/app/components/game/PiecePreview.tsx |   8 +-
 client/app/components/game/RoomControls.tsx |  56 +++++-----
 client/app/hooks/useTheme.ts                |  30 +++++
 client/app/root.tsx                         |  15 ++-
 client/app/welcome/welcome.tsx              |  80 +++++++-------
 14 files changed, 356 insertions(+), 165 deletions(-)
 create mode 100644 client/app/components/ThemeToggle.tsx
 create mode 100644 client/app/hooks/useTheme.ts

diff --git a/client/app/app.css b/client/app/app.css
index d6d62ca..111d7f4 100644
--- a/client/app/app.css
+++ b/client/app/app.css
@@ -3,14 +3,119 @@
 @theme {
   --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif,
     "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+
+  /* ── Semantic surface colors ── */
+  --color-page: var(--page);
+  --color-surface: var(--surface);
+  --color-surface-alt: var(--surface-alt);
+  --color-surface-hover: var(--surface-hover);
+
+  /* ── Semantic foreground (text) colors ── */
+  --color-on-surface: var(--on-surface);
+  --color-on-surface-variant: var(--on-surface-variant);
+  --color-on-surface-muted: var(--on-surface-muted);
+  --color-on-surface-faint: var(--on-surface-faint);
+
+  /* ── Borders ── */
+  --color-outline: var(--outline);
+  --color-outline-variant: var(--outline-variant);
+
+  /* ── Overlay ── */
+  --color-scrim: var(--scrim);
+
+  /* ── Status colors ── */
+  --color-status-success-bg: var(--status-success-bg);
+  --color-status-success-border: var(--status-success-border);
+  --color-status-success-text: var(--status-success-text);
+  --color-status-error-bg: var(--status-error-bg);
+  --color-status-error-border: var(--status-error-border);
+  --color-status-error-text: var(--status-error-text);
+}
+
+/* ── Light theme (default) ── */
+:root {
+  --page: #f1f5f9;
+  --surface: #ffffff;
+  --surface-alt: #f1f5f9;
+  --surface-hover: #e2e8f0;
+  --on-surface: #0f172a;
+  --on-surface-variant: #475569;
+  --on-surface-muted: #64748b;
+  --on-surface-faint: #94a3b8;
+  --outline: #cbd5e1;
+  --outline-variant: #e2e8f0;
+  --scrim: rgba(0, 0, 0, 0.15);
+
+  --status-success-bg: #f0fdf4;
+  --status-success-border: #bbf7d0;
+  --status-success-text: #15803d;
+  --status-error-bg: #fef2f2;
+  --status-error-border: #fecaca;
+  --status-error-text: #dc2626;
+
+  /* Game-board cell tokens */
+  --cell-grid: rgba(0, 0, 0, 0.08);
+  --cell-ghost-bg: rgba(0, 0, 0, 0.05);
+  --cell-ghost-border-light: rgba(0, 0, 0, 0.06);
+  --cell-ghost-border-dark: rgba(0, 0, 0, 0.1);
+  --cell-penalty-bg: #cbd5e1;
+  --cell-penalty-border-light: rgba(255, 255, 255, 0.4);
+  --cell-penalty-border-dark: rgba(0, 0, 0, 0.15);
+  --piece-border-light: rgba(255, 255, 255, 0.25);
+  --piece-border-dark: rgba(0, 0, 0, 0.2);
+  --mini-board-bg: #e2e8f0;
+  --opponent-ghost-alive: rgba(0, 0, 0, 0.04);
+  --opponent-ghost-dead: rgba(0, 0, 0, 0.02);
+  --opponent-penalty-alive: #cbd5e1;
+  --opponent-penalty-dead: #94a3b8;
+  --opponent-dead-piece: #9ca3af;
+
+  color-scheme: light;
+}
+
+/* ── Dark theme ── */
+.dark {
+  --page: #0f172a;
+  --surface: #111827;
+  --surface-alt: #1f2937;
+  --surface-hover: #374151;
+  --on-surface: #ffffff;
+  --on-surface-variant: #d1d5db;
+  --on-surface-muted: #9ca3af;
+  --on-surface-faint: #6b7280;
+  --outline: #4b5563;
+  --outline-variant: rgba(255, 255, 255, 0.1);
+  --scrim: rgba(0, 0, 0, 0.4);
+
+  --status-success-bg: rgba(34, 197, 94, 0.15);
+  --status-success-border: #166534;
+  --status-success-text: #4ade80;
+  --status-error-bg: rgba(239, 68, 68, 0.15);
+  --status-error-border: #991b1b;
+  --status-error-text: #fca5a5;
+
+  --cell-grid: rgba(255, 255, 255, 0.12);
+  --cell-ghost-bg: rgba(255, 255, 255, 0.12);
+  --cell-ghost-border-light: rgba(255, 255, 255, 0.15);
+  --cell-ghost-border-dark: rgba(0, 0, 0, 0.3);
+  --cell-penalty-bg: #374151;
+  --cell-penalty-border-light: rgba(255, 255, 255, 0.08);
+  --cell-penalty-border-dark: rgba(0, 0, 0, 0.3);
+  --piece-border-light: rgba(255, 255, 255, 0.15);
+  --piece-border-dark: rgba(0, 0, 0, 0.3);
+  --mini-board-bg: #000000;
+  --opponent-ghost-alive: rgba(255, 255, 255, 0.06);
+  --opponent-ghost-dead: rgba(255, 255, 255, 0.03);
+  --opponent-penalty-alive: #111111;
+  --opponent-penalty-dead: #444444;
+  --opponent-dead-piece: #777777;
+
+  color-scheme: dark;
 }
 
 html,
 body {
-  background: #0f172a;
+  background: var(--page);
+  color: var(--on-surface);
   min-height: 100vh;
-
-  @media (prefers-color-scheme: dark) {
-    color-scheme: dark;
-  }
 }
diff --git a/client/app/components/GameModeSelector.tsx b/client/app/components/GameModeSelector.tsx
index f494c74..dff4732 100644
--- a/client/app/components/GameModeSelector.tsx
+++ b/client/app/components/GameModeSelector.tsx
@@ -25,16 +25,16 @@ export function GameModeSelector({ selected, onChange, disabled, compact }: Game
               className={`relative rounded-lg p-2.5 text-left transition-all border ${
                 isActive
                   ? `${info.accentBg} ${info.accentBorder} ring-1 ring-offset-0 ring-current ${info.accentColor}`
-                  : 'bg-gray-800 border-gray-600 hover:border-gray-500'
+                  : 'bg-surface-alt border-outline hover:border-on-surface-faint'
               } ${disabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}`}
             >
               <div className='flex items-center gap-2 mb-1'>
                 <span className='text-base'>{info.icon}</span>
-                <span className={`text-sm font-semibold ${isActive ? info.accentColor : 'text-white'}`}>
+                <span className={`text-sm font-semibold ${isActive ? info.accentColor : 'text-on-surface'}`}>
                   {info.label}
                 </span>
               </div>
-              <div className='text-[10px] text-gray-400'>{info.boardLabel}</div>
+              <div className='text-[10px] text-on-surface-muted'>{info.boardLabel}</div>
             </button>
           );
         })}
@@ -59,22 +59,22 @@ export function GameModeSelector({ selected, onChange, disabled, compact }: Game
             className={`relative rounded-lg p-3 text-left transition-all border ${
               isActive
                 ? `${info.accentBg} ${info.accentBorder} ring-1 ring-offset-0 ring-current ${info.accentColor}`
-                : 'bg-gray-800 border-gray-600 hover:border-gray-500 hover:bg-gray-800/80'
+                : 'bg-surface-alt border-outline hover:border-on-surface-faint hover:bg-surface-alt/80'
             } ${disabled ? 'opacity-50 cursor-not-allowed' : 'cursor-pointer'}`}
           >
             <div className='flex items-start gap-3'>
               <span className='text-2xl mt-0.5'>{info.icon}</span>
               <div className='flex-1 min-w-0'>
                 <div className='flex items-center justify-between mb-1'>
-                  <span className={`text-sm font-bold ${isActive ? info.accentColor : 'text-white'}`}>
+                  <span className={`text-sm font-bold ${isActive ? info.accentColor : 'text-on-surface'}`}>
                     {info.label}
                   </span>
-                  <div className='flex items-center gap-2 text-[10px] text-gray-500'>
-                    <span className='bg-gray-700/60 px-1.5 py-0.5 rounded'>{info.boardLabel}</span>
-                    <span className='bg-gray-700/60 px-1.5 py-0.5 rounded'>{pieceCount} pcs</span>
+                  <div className='flex items-center gap-2 text-[10px] text-on-surface-faint'>
+                    <span className='bg-surface-hover/60 px-1.5 py-0.5 rounded'>{info.boardLabel}</span>
+                    <span className='bg-surface-hover/60 px-1.5 py-0.5 rounded'>{pieceCount} pcs</span>
                   </div>
                 </div>
-                <p className='text-xs text-gray-400 leading-relaxed'>{info.description}</p>
+                <p className='text-xs text-on-surface-muted leading-relaxed'>{info.description}</p>
               </div>
             </div>
           </button>
diff --git a/client/app/components/LoadingOverlay.tsx b/client/app/components/LoadingOverlay.tsx
index 776469b..2075db4 100644
--- a/client/app/components/LoadingOverlay.tsx
+++ b/client/app/components/LoadingOverlay.tsx
@@ -1,10 +1,10 @@
 export function LoadingOverlay() {
   return (
-    <div className='fixed inset-0 bg-black/40 flex items-center justify-center z-50'>
-      <div className='bg-gray-900 rounded-xl p-6 border border-gray-600'>
+    <div className='fixed inset-0 bg-scrim flex items-center justify-center z-50'>
+      <div className='bg-surface rounded-xl p-6 border border-outline shadow-lg'>
         <div className='text-center'>
           <div className='w-8 h-8 border-2 border-red-500 border-t-transparent rounded-full animate-spin mx-auto mb-4'></div>
-          <p className='text-gray-300 font-medium'>Loading...</p>
+          <p className='text-on-surface-variant font-medium'>Loading...</p>
         </div>
       </div>
     </div>
diff --git a/client/app/components/ThemeToggle.tsx b/client/app/components/ThemeToggle.tsx
new file mode 100644
index 0000000..f2c1903
--- /dev/null
+++ b/client/app/components/ThemeToggle.tsx
@@ -0,0 +1,47 @@
+interface ThemeToggleProps {
+  theme: 'light' | 'dark';
+  toggle: () => void;
+}
+
+export function ThemeToggle({ theme, toggle }: ThemeToggleProps) {
+  return (
+    <button
+      onClick={toggle}
+      className='fixed top-4 right-4 z-50 p-2.5 rounded-xl bg-surface border border-outline hover:bg-surface-alt transition-colors shadow-sm'
+      aria-label={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+      title={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
+    >
+      {theme === 'dark' ? (
+        <svg
+          xmlns='http://www.w3.org/2000/svg'
+          className='w-5 h-5 text-yellow-400'
+          fill='none'
+          viewBox='0 0 24 24'
+          stroke='currentColor'
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap='round'
+            strokeLinejoin='round'
+            d='M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z'
+          />
+        </svg>
+      ) : (
+        <svg
+          xmlns='http://www.w3.org/2000/svg'
+          className='w-5 h-5 text-slate-600'
+          fill='none'
+          viewBox='0 0 24 24'
+          stroke='currentColor'
+          strokeWidth={2}
+        >
+          <path
+            strokeLinecap='round'
+            strokeLinejoin='round'
+            d='M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z'
+          />
+        </svg>
+      )}
+    </button>
+  );
+}
diff --git a/client/app/components/auth/LoginForm.tsx b/client/app/components/auth/LoginForm.tsx
index b24b9de..50f8412 100644
--- a/client/app/components/auth/LoginForm.tsx
+++ b/client/app/components/auth/LoginForm.tsx
@@ -28,17 +28,17 @@ export function LoginForm() {
   };
 
   return (
-    <main className='min-h-screen bg-slate-900 flex items-center justify-center px-4 py-12'>
+    <main className='min-h-screen bg-page flex items-center justify-center px-4 py-12'>
       <div className='w-full max-w-md'>
         {/* Header */}
         <div className='text-center mb-8'>
           <h1 className='text-5xl font-bold text-red-500 mb-4'>RED TETRIS</h1>
-          <p className='text-xl text-gray-300'>Welcome Back!</p>
-          <p className='text-gray-400 mt-2'>Sign in to continue your game</p>
+          <p className='text-xl text-on-surface-variant'>Welcome Back!</p>
+          <p className='text-on-surface-muted mt-2'>Sign in to continue your game</p>
         </div>
 
         {/* Login Form */}
-        <div className='bg-gray-900 rounded-xl p-8 border border-gray-600'>
+        <div className='bg-surface rounded-xl p-8 border border-outline shadow-sm'>
           <form
             className='space-y-6'
             onSubmit={(e) => {
@@ -46,8 +46,8 @@ export function LoginForm() {
             }}
           >
             {error && (
-              <div className='bg-red-500/20 backdrop-blur-sm border border-red-400/30 rounded-lg p-4'>
-                <div className='text-red-200 text-sm text-center'>{error}</div>
+              <div className='bg-status-error-bg border border-status-error-border rounded-lg p-4'>
+                <div className='text-status-error-text text-sm text-center'>{error}</div>
               </div>
             )}
 
@@ -55,7 +55,7 @@ export function LoginForm() {
               <div>
                 <label
                   htmlFor='username'
-                  className='block text-sm font-medium text-gray-300 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Username
                 </label>
@@ -64,7 +64,7 @@ export function LoginForm() {
                   name='username'
                   type='text'
                   required
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Enter your username'
                   disabled={isLoading}
                 />
@@ -72,7 +72,7 @@ export function LoginForm() {
               <div>
                 <label
                   htmlFor='password'
-                  className='block text-sm font-medium text-gray-400 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Password
                 </label>
@@ -81,7 +81,7 @@ export function LoginForm() {
                   name='password'
                   type='password'
                   required
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Enter your password'
                   disabled={isLoading}
                 />
@@ -91,7 +91,7 @@ export function LoginForm() {
             <button
               type='submit'
               disabled={isLoading}
-              className='w-full bg-red-600 hover:bg-red-500 disabled:bg-gray-700 disabled:opacity-70 text-white font-bold py-4 px-6 rounded-lg transition-colors'
+              className='w-full bg-red-600 hover:bg-red-500 disabled:bg-surface-hover disabled:opacity-70 text-white font-bold py-4 px-6 rounded-lg transition-colors'
             >
               {isLoading ? (
                 <span className='flex items-center justify-center'>
@@ -122,8 +122,8 @@ export function LoginForm() {
               )}
             </button>
 
-            <div className='text-center pt-4 border-t border-white/10'>
-              <p className='text-gray-400 text-sm'>
+            <div className='text-center pt-4 border-t border-outline-variant'>
+              <p className='text-on-surface-muted text-sm'>
                 Don't have an account?{' '}
                 <Link
                   to='/register'
diff --git a/client/app/components/auth/RegisterForm.tsx b/client/app/components/auth/RegisterForm.tsx
index 837d46b..c2ec52d 100644
--- a/client/app/components/auth/RegisterForm.tsx
+++ b/client/app/components/auth/RegisterForm.tsx
@@ -40,17 +40,17 @@ export function RegisterForm() {
   };
 
   return (
-    <main className='min-h-screen bg-slate-900 flex items-center justify-center px-4 py-12'>
+    <main className='min-h-screen bg-page flex items-center justify-center px-4 py-12'>
       <div className='w-full max-w-md'>
         {/* Header */}
         <div className='text-center mb-8'>
           <h1 className='text-5xl font-bold text-red-500 mb-4'>RED TETRIS</h1>
-          <p className='text-xl text-gray-300'>Join the Game!</p>
-          <p className='text-gray-400 mt-2'>Create your account to start playing</p>
+          <p className='text-xl text-on-surface-variant'>Join the Game!</p>
+          <p className='text-on-surface-muted mt-2'>Create your account to start playing</p>
         </div>
 
         {/* Register Form */}
-        <div className='bg-gray-900 rounded-xl p-8 border border-gray-600'>
+        <div className='bg-surface rounded-xl p-8 border border-outline shadow-sm'>
           <form
             className='space-y-6'
             onSubmit={(e) => {
@@ -58,8 +58,8 @@ export function RegisterForm() {
             }}
           >
             {error && (
-              <div className='bg-red-500/20 backdrop-blur-sm border border-red-400/30 rounded-lg p-4'>
-                <div className='text-red-200 text-sm text-center'>{error}</div>
+              <div className='bg-status-error-bg border border-status-error-border rounded-lg p-4'>
+                <div className='text-status-error-text text-sm text-center'>{error}</div>
               </div>
             )}
 
@@ -67,7 +67,7 @@ export function RegisterForm() {
               <div>
                 <label
                   htmlFor='username'
-                  className='block text-sm font-medium text-gray-400 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Username
                 </label>
@@ -79,7 +79,7 @@ export function RegisterForm() {
                   minLength={3}
                   maxLength={50}
                   pattern='[a-zA-Z0-9_-]+'
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Choose a unique username (3-50 chars)'
                   disabled={isLoading}
                 />
@@ -87,7 +87,7 @@ export function RegisterForm() {
               <div>
                 <label
                   htmlFor='email'
-                  className='block text-sm font-medium text-gray-400 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Email Address
                 </label>
@@ -96,7 +96,7 @@ export function RegisterForm() {
                   name='email'
                   type='email'
                   required
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Enter your email address'
                   disabled={isLoading}
                 />
@@ -104,7 +104,7 @@ export function RegisterForm() {
               <div>
                 <label
                   htmlFor='password'
-                  className='block text-sm font-medium text-gray-400 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Password
                 </label>
@@ -114,7 +114,7 @@ export function RegisterForm() {
                   type='password'
                   required
                   minLength={6}
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Create a strong password (6+ chars)'
                   disabled={isLoading}
                 />
@@ -122,7 +122,7 @@ export function RegisterForm() {
               <div>
                 <label
                   htmlFor='confirmPassword'
-                  className='block text-sm font-medium text-gray-400 mb-2'
+                  className='block text-sm font-medium text-on-surface-muted mb-2'
                 >
                   Confirm Password
                 </label>
@@ -132,7 +132,7 @@ export function RegisterForm() {
                   type='password'
                   required
                   minLength={6}
-                  className='w-full bg-gray-800 border border-gray-600 rounded-lg px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
+                  className='w-full bg-surface-alt border border-outline rounded-lg px-4 py-3 text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 transition-colors'
                   placeholder='Confirm your password'
                   disabled={isLoading}
                 />
@@ -142,7 +142,7 @@ export function RegisterForm() {
             <button
               type='submit'
               disabled={isLoading}
-              className='w-full bg-red-600 hover:bg-red-500 disabled:bg-gray-700 disabled:opacity-70 text-white font-bold py-4 px-6 rounded-lg transition-colors'
+              className='w-full bg-red-600 hover:bg-red-500 disabled:bg-surface-hover disabled:opacity-70 text-white font-bold py-4 px-6 rounded-lg transition-colors'
             >
               {isLoading ? (
                 <span className='flex items-center justify-center'>
@@ -173,8 +173,8 @@ export function RegisterForm() {
               )}
             </button>
 
-            <div className='text-center pt-4 border-t border-white/10'>
-              <p className='text-gray-400 text-sm'>
+            <div className='text-center pt-4 border-t border-outline-variant'>
+              <p className='text-on-surface-muted text-sm'>
                 Already have an account?{' '}
                 <Link
                   to='/login'
diff --git a/client/app/components/game/GameBoard.tsx b/client/app/components/game/GameBoard.tsx
index 241ba26..3f83653 100644
--- a/client/app/components/game/GameBoard.tsx
+++ b/client/app/components/game/GameBoard.tsx
@@ -28,7 +28,7 @@ export function GameBoard({ board, idColors, width, height, cellSize, maxWidth,
   return (
     <div className='flex flex-col items-center'>
       <div
-        className='bg-gray-900 rounded-lg p-3 border border-gray-600 flex items-center justify-center'
+        className='bg-surface rounded-lg p-3 border border-outline flex items-center justify-center'
         style={{ width: maxWidth * cellSize + 24, height: maxHeight * cellSize + 24 }}
       >
         <div
@@ -43,10 +43,10 @@ export function GameBoard({ board, idColors, width, height, cellSize, maxWidth,
         </div>
       </div>
 
-      <div className='mt-4 bg-gray-800 rounded-lg p-3 border border-gray-600'>
-        <div className='text-center text-white'>
-          <span className='text-lg font-bold text-white'>{score}</span>
-          <div className='text-sm text-gray-400'>Score</div>
+      <div className='mt-4 bg-surface-alt rounded-lg p-3 border border-outline'>
+        <div className='text-center text-on-surface'>
+          <span className='text-lg font-bold text-on-surface'>{score}</span>
+          <div className='text-sm text-on-surface-muted'>Score</div>
         </div>
       </div>
     </div>
@@ -70,7 +70,7 @@ function renderCell(
           width: cellSize,
           height: cellSize,
           boxSizing: 'border-box',
-          outline: '1px solid rgba(255,255,255,0.12)',
+          outline: '1px solid var(--cell-grid)',
         }}
       />
     );
@@ -85,11 +85,11 @@ function renderCell(
           height: cellSize,
           boxSizing: 'border-box',
           borderRadius: 2,
-          background: 'rgba(255,255,255,0.12)',
-          borderTop: '1px solid rgba(255,255,255,0.15)',
-          borderLeft: '1px solid rgba(255,255,255,0.1)',
-          borderBottom: '1px solid rgba(0,0,0,0.3)',
-          borderRight: '1px solid rgba(0,0,0,0.2)',
+          background: 'var(--cell-ghost-bg)',
+          borderTop: '1px solid var(--cell-ghost-border-light)',
+          borderLeft: '1px solid var(--cell-ghost-border-light)',
+          borderBottom: '1px solid var(--cell-ghost-border-dark)',
+          borderRight: '1px solid var(--cell-ghost-border-dark)',
         }}
       />
     );
@@ -104,11 +104,11 @@ function renderCell(
           height: cellSize,
           boxSizing: 'border-box',
           borderRadius: 2,
-          background: '#374151',
-          borderTop: '1px solid rgba(255,255,255,0.08)',
-          borderLeft: '1px solid rgba(255,255,255,0.05)',
-          borderBottom: '1px solid rgba(0,0,0,0.3)',
-          borderRight: '1px solid rgba(0,0,0,0.2)',
+          background: 'var(--cell-penalty-bg)',
+          borderTop: '1px solid var(--cell-penalty-border-light)',
+          borderLeft: '1px solid var(--cell-penalty-border-light)',
+          borderBottom: '1px solid var(--cell-penalty-border-dark)',
+          borderRight: '1px solid var(--cell-penalty-border-dark)',
         }}
       />
     );
@@ -124,10 +124,10 @@ function renderCell(
         boxSizing: 'border-box',
         borderRadius: 2,
         background: color,
-        borderTop: '1px solid rgba(255,255,255,0.15)',
-        borderLeft: '1px solid rgba(255,255,255,0.1)',
-        borderBottom: '1px solid rgba(0,0,0,0.3)',
-        borderRight: '1px solid rgba(0,0,0,0.2)',
+        borderTop: '1px solid var(--piece-border-light)',
+        borderLeft: '1px solid var(--piece-border-light)',
+        borderBottom: '1px solid var(--piece-border-dark)',
+        borderRight: '1px solid var(--piece-border-dark)',
       }}
     />
   );
diff --git a/client/app/components/game/GamePage.tsx b/client/app/components/game/GamePage.tsx
index 9b5407a..465f631 100644
--- a/client/app/components/game/GamePage.tsx
+++ b/client/app/components/game/GamePage.tsx
@@ -51,20 +51,20 @@ export function GamePage() {
 
   return (
     <main
-      className='min-h-screen bg-slate-900 p-6'
+      className='min-h-screen bg-page p-6'
       style={{ pointerEvents: 'auto' }}
     >
       <div className='container mx-auto max-w-[1600px]'>
         <header className='flex items-center justify-center mb-8 relative'>
           <Link
             to='/'
-            className='absolute left-0 z-10 px-4 py-2 bg-gray-800 hover:bg-gray-700 border border-gray-600 text-gray-300 hover:text-white font-medium rounded-lg transition-colors text-sm flex items-center gap-2'
+            className='absolute left-0 z-10 px-4 py-2 bg-surface-alt hover:bg-surface-hover border border-outline text-on-surface-variant hover:text-on-surface font-medium rounded-lg transition-colors text-sm flex items-center gap-2'
           >
             Back
           </Link>
           <div className='text-center'>
             <h1 className='text-4xl font-bold text-red-500 mb-2'>RED TETRIS</h1>
-            <p className='text-gray-400'>Play Mode</p>
+            <p className='text-on-surface-muted'>Play Mode</p>
           </div>
         </header>
 
@@ -82,10 +82,10 @@ export function GamePage() {
           {/* Center: Game Area */}
           <div className='flex flex-wrap sm:flex-nowrap items-start gap-4 sm:gap-6 justify-center'>
             {/* Hold Piece */}
-            <div className='bg-gray-900 rounded-xl p-4 border border-gray-600'>
-              <h3 className='text-sm font-semibold text-white mb-3 text-center'>Hold</h3>
+            <div className='bg-surface rounded-xl p-4 border border-outline shadow-sm'>
+              <h3 className='text-sm font-semibold text-on-surface mb-3 text-center'>Hold</h3>
               <div
-                className='bg-gray-900 rounded-lg p-3 border border-gray-600 flex justify-center items-center'
+                className='bg-surface rounded-lg p-3 border border-outline flex justify-center items-center'
                 style={{ width: 4 * CELL + 24, height: 4 * CELL + 24 }}
               >
                 <PiecePreview
@@ -98,12 +98,12 @@ export function GamePage() {
             </div>
 
             {/* Main Game Board */}
-            <div className='bg-gray-900 rounded-xl p-6 border border-gray-600'>
-              <h3 className='text-xl font-semibold text-white mb-4 text-center'>Your Board</h3>
+            <div className='bg-surface rounded-xl p-6 border border-outline shadow-sm'>
+              <h3 className='text-xl font-semibold text-on-surface mb-4 text-center'>Your Board</h3>
               <div className='flex items-center justify-center gap-2 mb-3'>
                 <span className='text-base'>{modeInfo.icon}</span>
                 <span className={`text-sm font-medium ${modeInfo.accentColor}`}>{modeInfo.label}</span>
-                <span className='text-[10px] text-gray-500'>({modeInfo.boardLabel})</span>
+                <span className='text-[10px] text-on-surface-faint'>({modeInfo.boardLabel})</span>
               </div>
 
               <GameBoard
@@ -119,10 +119,10 @@ export function GamePage() {
             </div>
 
             {/* Next Piece */}
-            <div className='bg-gray-900 rounded-xl p-4 border border-gray-600'>
-              <h3 className='text-sm font-semibold text-white mb-3 text-center'>Next</h3>
+            <div className='bg-surface rounded-xl p-4 border border-outline shadow-sm'>
+              <h3 className='text-sm font-semibold text-on-surface mb-3 text-center'>Next</h3>
               <div
-                className='bg-gray-900 rounded-lg p-3 border border-gray-600 flex justify-center items-center'
+                className='bg-surface rounded-lg p-3 border border-outline flex justify-center items-center'
                 style={{ width: 4 * CELL + 24, height: 4 * CELL + 24 }}
               >
                 <PiecePreview
@@ -138,8 +138,8 @@ export function GamePage() {
           {/* Right Side: Opponents */}
           {game.opponents.length > 0 && (
             <div className='w-full sm:w-72 xl:w-80 shrink-0 space-y-4'>
-              <div className='bg-gray-900 rounded-xl p-4 border border-gray-600'>
-                <h3 className='text-lg font-semibold text-white mb-4 text-center'>Opponents</h3>
+              <div className='bg-surface rounded-xl p-4 border border-outline shadow-sm'>
+                <h3 className='text-lg font-semibold text-on-surface mb-4 text-center'>Opponents</h3>
                 <div className='space-y-3'>
                   {game.opponents.map((op) => (
                     <OpponentCard
diff --git a/client/app/components/game/OpponentCard.tsx b/client/app/components/game/OpponentCard.tsx
index f899a21..634df86 100644
--- a/client/app/components/game/OpponentCard.tsx
+++ b/client/app/components/game/OpponentCard.tsx
@@ -25,9 +25,9 @@ export function OpponentCard({ name, board, isAlive, score, isHost, idColors, wi
         const val = board?.[y]?.[x] ?? 0;
         let bg = 'transparent';
         if (val === 0) bg = 'transparent';
-        else if (val === -2) bg = isAlive ? 'rgba(255,255,255,0.06)' : 'rgba(255,255,255,0.03)';
-        else if (val === -1) bg = isAlive ? '#111' : '#444';
-        else bg = isAlive ? (idColors[val] ?? '#999') : '#777';
+        else if (val === -2) bg = isAlive ? 'var(--opponent-ghost-alive)' : 'var(--opponent-ghost-dead)';
+        else if (val === -1) bg = isAlive ? 'var(--opponent-penalty-alive)' : 'var(--opponent-penalty-dead)';
+        else bg = isAlive ? (idColors[val] ?? '#999') : 'var(--opponent-dead-piece)';
 
         const isPiece = val > 0;
         cells.push(
@@ -53,18 +53,18 @@ export function OpponentCard({ name, board, isAlive, score, isHost, idColors, wi
   };
 
   return (
-    <div className='bg-gray-800 rounded-lg p-3 border border-gray-600 flex gap-3 items-center justify-between'>
+    <div className='bg-surface-alt rounded-lg p-3 border border-outline flex gap-3 items-center justify-between'>
       {/* Left: Info */}
       <div className='flex-1 min-w-0 flex flex-col items-start justify-center'>
         <div className='flex items-center gap-1.5 mb-1'>
           <div
             className={`w-2 h-2 rounded-full ${isAlive ? 'bg-green-400 shadow-[0_0_6px_rgba(74,222,128,0.6)]' : 'bg-red-400 shadow-[0_0_6px_rgba(248,113,113,0.6)]'}`}
           />
-          <span className='text-sm font-semibold text-white truncate'>{name}</span>
+          <span className='text-sm font-semibold text-on-surface truncate'>{name}</span>
         </div>
-        {isHost && <span className='text-[10px] text-yellow-400 font-medium mb-1'>Host</span>}
-        <div className='text-xs text-gray-400 mb-2'>
-          Score: <span className='text-white font-semibold'>{score}</span>
+        {isHost && <span className='text-[10px] text-yellow-500 font-medium mb-1'>Host</span>}
+        <div className='text-xs text-on-surface-muted mb-2'>
+          Score: <span className='text-on-surface font-semibold'>{score}</span>
         </div>
         <div
           className={`text-[10px] px-2 py-0.5 rounded-full font-medium ${
@@ -77,7 +77,7 @@ export function OpponentCard({ name, board, isAlive, score, isHost, idColors, wi
         </div>
       </div>
       {/* Right: Board */}
-      <div className='shrink-0 bg-black rounded-lg p-1.5 border border-gray-600 flex justify-center'>
+      <div className='shrink-0 rounded-lg p-1.5 border border-outline flex justify-center' style={{ background: 'var(--mini-board-bg)' }}>
         {renderOpponentBoard()}
       </div>
     </div>
diff --git a/client/app/components/game/PiecePreview.tsx b/client/app/components/game/PiecePreview.tsx
index 4c1c287..95830c1 100644
--- a/client/app/components/game/PiecePreview.tsx
+++ b/client/app/components/game/PiecePreview.tsx
@@ -37,10 +37,10 @@ export function PiecePreview({ type, shapes, colors, cellSize }: PiecePreviewPro
               boxSizing: 'border-box',
               borderRadius: 2,
               background: color,
-              borderTop: '1px solid rgba(255,255,255,0.15)',
-              borderLeft: '1px solid rgba(255,255,255,0.1)',
-              borderBottom: '1px solid rgba(0,0,0,0.3)',
-              borderRight: '1px solid rgba(0,0,0,0.2)',
+              borderTop: '1px solid var(--piece-border-light)',
+              borderLeft: '1px solid var(--piece-border-light)',
+              borderBottom: '1px solid var(--piece-border-dark)',
+              borderRight: '1px solid var(--piece-border-dark)',
             }}
           />
         ) : (
diff --git a/client/app/components/game/RoomControls.tsx b/client/app/components/game/RoomControls.tsx
index b6e6847..1e621fc 100644
--- a/client/app/components/game/RoomControls.tsx
+++ b/client/app/components/game/RoomControls.tsx
@@ -47,23 +47,23 @@ export function RoomControls({
 
   if (compact) {
     return (
-      <div className='bg-gray-900 rounded-xl p-4 border border-gray-600 mb-6 max-w-xl mx-auto xl:hidden'>
-        <h2 className='text-lg font-semibold text-white mb-3 text-center'>Room Settings</h2>
+      <div className='bg-surface rounded-xl p-4 border border-outline shadow-sm mb-6 max-w-xl mx-auto xl:hidden'>
+        <h2 className='text-lg font-semibold text-on-surface mb-3 text-center'>Room Settings</h2>
 
         <div className='space-y-3'>
           <div>
-            <label className='block text-xs font-medium text-gray-400 mb-1'>Room Code</label>
+            <label className='block text-xs font-medium text-on-surface-muted mb-1'>Room Code</label>
             <input
               value={room}
               onChange={(e) => setRoom(e.target.value)}
               disabled={!!playerId}
-              className='w-full px-3 py-2 text-sm bg-gray-800 border border-gray-600 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 disabled:opacity-50 disabled:cursor-not-allowed'
+              className='w-full px-3 py-2 text-sm bg-surface-alt border border-outline rounded-lg text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 disabled:opacity-50 disabled:cursor-not-allowed'
               placeholder='Room code'
             />
           </div>
 
           <div>
-            <label className='block text-xs font-medium text-gray-400 mb-1'>Game Mode</label>
+            <label className='block text-xs font-medium text-on-surface-muted mb-1'>Game Mode</label>
             <GameModeSelector
               selected={selectedMode}
               onChange={setSelectedMode}
@@ -76,21 +76,21 @@ export function RoomControls({
             <button
               onClick={create}
               disabled={!!playerId}
-              className='px-4 py-2 text-sm bg-green-600 hover:bg-green-500 disabled:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
+              className='px-4 py-2 text-sm bg-green-600 hover:bg-green-500 disabled:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
             >
               Create
             </button>
             <button
               onClick={join}
               disabled={!!playerId || !room}
-              className='px-4 py-2 text-sm bg-blue-600 hover:bg-blue-500 disabled:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
+              className='px-4 py-2 text-sm bg-blue-600 hover:bg-blue-500 disabled:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
             >
               Join
             </button>
             <button
               onClick={start}
               disabled={!playerId || (hostId ? playerId !== hostId : false)}
-              className='px-4 py-2 text-sm bg-red-600 hover:bg-red-500 disabled:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
+              className='px-4 py-2 text-sm bg-red-600 hover:bg-red-500 disabled:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
             >
               Start
             </button>
@@ -105,7 +105,7 @@ export function RoomControls({
             {playerId && (
               <button
                 onClick={leave}
-                className='px-4 py-2 text-sm bg-gray-700 hover:bg-gray-600 text-gray-300 hover:text-white font-semibold rounded-lg transition-colors'
+                className='px-4 py-2 text-sm bg-surface-hover hover:bg-surface-alt text-on-surface-variant hover:text-on-surface font-semibold rounded-lg transition-colors'
               >
                 Leave
               </button>
@@ -130,23 +130,23 @@ export function RoomControls({
   /* Desktop variant */
   return (
     <div className='hidden xl:block w-80 shrink-0 space-y-4'>
-      <div className='bg-gray-900 rounded-xl p-4 border border-gray-600'>
-        <h2 className='text-lg font-semibold text-white mb-4 text-center'>Room Settings</h2>
+      <div className='bg-surface rounded-xl p-4 border border-outline shadow-sm'>
+        <h2 className='text-lg font-semibold text-on-surface mb-4 text-center'>Room Settings</h2>
 
         <div className='space-y-4'>
           <div>
-            <label className='block text-sm font-medium text-gray-400 mb-2'>Room Code</label>
+            <label className='block text-sm font-medium text-on-surface-muted mb-2'>Room Code</label>
             <input
               value={room}
               onChange={(e) => setRoom(e.target.value)}
               disabled={!!playerId}
-              className='w-full px-3 py-2 bg-gray-800 border border-gray-600 rounded-lg text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 disabled:opacity-50 disabled:cursor-not-allowed'
+              className='w-full px-3 py-2 bg-surface-alt border border-outline rounded-lg text-on-surface placeholder-on-surface-faint focus:outline-none focus:ring-2 focus:ring-red-500/50 focus:border-red-500/50 disabled:opacity-50 disabled:cursor-not-allowed'
               placeholder='Enter room code'
             />
           </div>
 
           <div>
-            <label className='block text-sm font-medium text-gray-400 mb-2'>Game Mode</label>
+            <label className='block text-sm font-medium text-on-surface-muted mb-2'>Game Mode</label>
             <GameModeSelector
               selected={selectedMode}
               onChange={setSelectedMode}
@@ -167,7 +167,7 @@ export function RoomControls({
               <button
                 onClick={join}
                 disabled={!room}
-                className='w-full px-4 py-2 bg-blue-600 hover:bg-blue-500 disabled:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
+                className='w-full px-4 py-2 bg-blue-600 hover:bg-blue-500 disabled:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
               >
                 Join Room
               </button>
@@ -175,7 +175,7 @@ export function RoomControls({
             <button
               onClick={start}
               disabled={!playerId || (hostId ? playerId !== hostId : false)}
-              className='w-full px-4 py-2 bg-red-600 hover:bg-red-500 disabled:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
+              className='w-full px-4 py-2 bg-red-600 hover:bg-red-500 disabled:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-white font-semibold rounded-lg transition-colors'
             >
               Start Game
             </button>
@@ -190,7 +190,7 @@ export function RoomControls({
             {playerId && (
               <button
                 onClick={leave}
-                className='w-full px-4 py-2 bg-gray-700 hover:bg-gray-600 text-gray-300 hover:text-white font-semibold rounded-lg transition-colors'
+                className='w-full px-4 py-2 bg-surface-hover hover:bg-surface-alt text-on-surface-variant hover:text-on-surface font-semibold rounded-lg transition-colors'
               >
                 Leave Room
               </button>
@@ -233,26 +233,26 @@ function StatusMessages({
   return (
     <div className='space-y-2'>
       {hostId && playerId === hostId && (
-        <div className='bg-green-900/30 border border-green-800 rounded-lg p-2 text-center'>
-          <span className='text-green-400 text-sm font-medium'>Room: </span>
-          <span className='text-white text-sm font-bold'>{room}</span>
+        <div className='bg-status-success-bg border border-status-success-border rounded-lg p-2 text-center'>
+          <span className='text-status-success-text text-sm font-medium'>Room: </span>
+          <span className='text-on-surface text-sm font-bold'>{room}</span>
         </div>
       )}
       {hostName && (
-        <div className='bg-gray-800 border border-gray-600 rounded-lg p-2 text-center'>
-          <span className='text-gray-400 text-sm font-medium'>Host: </span>
-          <span className='text-white text-sm font-semibold'>{hostName}</span>
-          {isHost ? <span className='text-gray-400 text-sm font-medium'> (you)</span> : null}
+        <div className='bg-surface-alt border border-outline rounded-lg p-2 text-center'>
+          <span className='text-on-surface-muted text-sm font-medium'>Host: </span>
+          <span className='text-on-surface text-sm font-semibold'>{hostName}</span>
+          {isHost ? <span className='text-on-surface-muted text-sm font-medium'> (you)</span> : null}
         </div>
       )}
       {error && (
-        <div className='bg-red-900/30 border border-red-800 rounded-lg p-2 text-center'>
-          <span className='text-red-300 text-sm'>{error}</span>
+        <div className='bg-status-error-bg border border-status-error-border rounded-lg p-2 text-center'>
+          <span className='text-status-error-text text-sm'>{error}</span>
         </div>
       )}
       {message && (
-        <div className='bg-green-900/30 border border-green-800 rounded-lg p-2 text-center'>
-          <span className='text-green-300 text-sm'>{message}</span>
+        <div className='bg-status-success-bg border border-status-success-border rounded-lg p-2 text-center'>
+          <span className='text-status-success-text text-sm'>{message}</span>
         </div>
       )}
     </div>
diff --git a/client/app/hooks/useTheme.ts b/client/app/hooks/useTheme.ts
new file mode 100644
index 0000000..3cd7dee
--- /dev/null
+++ b/client/app/hooks/useTheme.ts
@@ -0,0 +1,30 @@
+import { useEffect, useState } from 'react';
+
+type Theme = 'light' | 'dark';
+
+const STORAGE_KEY = 'red-tetris-theme';
+
+function getInitialTheme(): Theme {
+  if (typeof window === 'undefined') return 'dark';
+  const stored = localStorage.getItem(STORAGE_KEY);
+  if (stored === 'light' || stored === 'dark') return stored;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+export function useTheme() {
+  const [theme, setTheme] = useState<Theme>(getInitialTheme);
+
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === 'dark') {
+      root.classList.add('dark');
+    } else {
+      root.classList.remove('dark');
+    }
+    localStorage.setItem(STORAGE_KEY, theme);
+  }, [theme]);
+
+  const toggle = () => setTheme((prev) => (prev === 'dark' ? 'light' : 'dark'));
+
+  return { theme, toggle } as const;
+}
diff --git a/client/app/root.tsx b/client/app/root.tsx
index 4eadcc5..86a9ddd 100644
--- a/client/app/root.tsx
+++ b/client/app/root.tsx
@@ -5,6 +5,8 @@ import type { Route } from './+types/routes';
 import './app.css';
 import { store } from './store/store';
 import { LoadingOverlay } from './components/LoadingOverlay';
+import { ThemeToggle } from './components/ThemeToggle';
+import { useTheme } from './hooks/useTheme';
 
 export const links: Route.LinksFunction = () => [
   { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
@@ -26,6 +28,11 @@ export function Layout({ children }: { children: React.ReactNode }) {
         />
         <Meta />
         <Links />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `(function(){try{var t=localStorage.getItem('red-tetris-theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}})()`
+          }}
+        />
       </head>
       <body>
         {children}
@@ -39,9 +46,11 @@ export function Layout({ children }: { children: React.ReactNode }) {
 export default function App() {
   const navigation = useNavigation();
   const isNavigating = navigation.state === 'loading';
+  const { theme, toggle } = useTheme();
 
   return (
     <Provider store={store}>
+      <ThemeToggle theme={theme} toggle={toggle} />
       <Outlet />
       {isNavigating && <LoadingOverlay />}
     </Provider>
@@ -62,12 +71,12 @@ export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
   }
 
   return (
-    <main className='min-h-screen bg-slate-900 flex items-center justify-center p-6'>
+    <main className='min-h-screen bg-page flex items-center justify-center p-6'>
       <div className='text-center max-w-md'>
         <h1 className='text-8xl font-bold text-red-500 mb-4'>{message}</h1>
-        <p className='text-xl text-gray-300 mb-8'>{details}</p>
+        <p className='text-xl text-on-surface-variant mb-8'>{details}</p>
         {stack && (
-          <pre className='w-full p-4 overflow-x-auto bg-gray-800 border border-gray-600 rounded-lg text-left text-sm text-gray-400 mb-8'>
+          <pre className='w-full p-4 overflow-x-auto bg-surface-alt border border-outline rounded-lg text-left text-sm text-on-surface-muted mb-8'>
             <code>{stack}</code>
           </pre>
         )}
diff --git a/client/app/welcome/welcome.tsx b/client/app/welcome/welcome.tsx
index dd35de1..22a18b0 100644
--- a/client/app/welcome/welcome.tsx
+++ b/client/app/welcome/welcome.tsx
@@ -42,33 +42,33 @@ export function Welcome() {
   };
 
   return (
-    <main className='min-h-screen bg-slate-900'>
+    <main className='min-h-screen bg-page'>
       <div className='container mx-auto px-4 py-8'>
         {/* Header */}
         <header className='text-center mb-12'>
           <h1 className='text-6xl font-bold text-red-500 mb-4'>RED TETRIS</h1>
-          <p className='text-lg text-gray-400'>Multiplayer Tetris</p>
+          <p className='text-lg text-on-surface-muted'>Multiplayer Tetris</p>
         </header>
 
         {user && (
           <div className='max-w-6xl mx-auto space-y-8'>
             {/* Profile Section */}
             <div className='max-w-md mx-auto'>
-              <div className='bg-gray-900 rounded-xl p-6 border border-gray-600'>
+              <div className='bg-surface rounded-xl p-6 border border-outline shadow-sm'>
                 <div className='text-center mb-6'>
                   <div className='w-20 h-20 bg-red-500/20 border border-red-500/30 rounded-full mx-auto mb-4 flex items-center justify-center'>
                     <span className='text-2xl font-bold text-red-400'>{user.username.charAt(0).toUpperCase()}</span>
                   </div>
-                  <h2 className='text-2xl font-bold text-white mb-2'>{user.username}</h2>
-                  <p className='text-gray-300 text-sm'>{user.email}</p>
-                  <p className='text-gray-400 text-xs mt-1'>
+                  <h2 className='text-2xl font-bold text-on-surface mb-2'>{user.username}</h2>
+                  <p className='text-on-surface-variant text-sm'>{user.email}</p>
+                  <p className='text-on-surface-muted text-xs mt-1'>
                     Member since {new Date(user.created_at).toLocaleDateString()}
                   </p>
                 </div>
 
                 <button
                   onClick={handleLogout}
-                  className='w-full bg-gray-800 hover:bg-gray-700 text-gray-300 hover:text-white border border-gray-600 rounded-lg px-4 py-2 text-sm font-medium transition-colors'
+                  className='w-full bg-surface-alt hover:bg-surface-hover text-on-surface-variant hover:text-on-surface border border-outline rounded-lg px-4 py-2 text-sm font-medium transition-colors'
                 >
                   Logout
                 </button>
@@ -83,79 +83,79 @@ export function Welcome() {
               >
                 PLAY NOW
               </Link>
-              <p className='text-gray-300 mt-4 text-lg'>Ready to drop some blocks?</p>
+              <p className='text-on-surface-variant mt-4 text-lg'>Ready to drop some blocks?</p>
             </div>
 
             {/* Stats Grid */}
-            <div className='bg-gray-900 rounded-xl p-6 border border-gray-600'>
-              <h3 className='text-2xl font-bold text-white mb-6 text-center'>Your Stats</h3>
+            <div className='bg-surface rounded-xl p-6 border border-outline shadow-sm'>
+              <h3 className='text-2xl font-bold text-on-surface mb-6 text-center'>Your Stats</h3>
               {statsLoading ? (
                 <div className='text-center py-8'>
                   <div className='w-8 h-8 border-2 border-red-500 border-t-transparent rounded-full animate-spin mx-auto mb-3'></div>
-                  <p className='text-gray-500 text-sm'>Loading stats...</p>
+                  <p className='text-on-surface-faint text-sm'>Loading stats...</p>
                 </div>
               ) : stats && stats.gamesPlayed > 0 ? (
                 <div className='grid grid-cols-2 md:grid-cols-3 gap-4'>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-white'>{stats.gamesPlayed}</div>
-                    <div className='text-gray-400 text-sm'>Games Played</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>{stats.gamesPlayed}</div>
+                    <div className='text-on-surface-muted text-sm'>Games Played</div>
                   </div>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-white'>{stats.highScore.toLocaleString()}</div>
-                    <div className='text-gray-400 text-sm'>High Score</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>{stats.highScore.toLocaleString()}</div>
+                    <div className='text-on-surface-muted text-sm'>High Score</div>
                   </div>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-green-400'>{stats.wins}</div>
-                    <div className='text-gray-400 text-sm'>Wins</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>{stats.wins}</div>
+                    <div className='text-on-surface-muted text-sm'>Wins</div>
                   </div>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-white'>{stats.averageScore.toLocaleString()}</div>
-                    <div className='text-gray-400 text-sm'>Avg Score</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>{stats.averageScore.toLocaleString()}</div>
+                    <div className='text-on-surface-muted text-sm'>Avg Score</div>
                   </div>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-white'>{stats.winRate}%</div>
-                    <div className='text-gray-400 text-sm'>Win Rate</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>{stats.winRate}%</div>
+                    <div className='text-on-surface-muted text-sm'>Win Rate</div>
                   </div>
-                  <div className='bg-gray-800 rounded-lg p-4 text-center border border-gray-600'>
-                    <div className='text-2xl font-bold text-white'>#{stats.bestPlace}</div>
-                    <div className='text-gray-400 text-sm'>Best Place</div>
+                  <div className='bg-surface-alt rounded-lg p-4 text-center border border-outline'>
+                    <div className='text-2xl font-bold text-on-surface'>#{stats.bestPlace}</div>
+                    <div className='text-on-surface-muted text-sm'>Best Place</div>
                   </div>
                 </div>
               ) : (
                 <div className='text-center py-8'>
-                  <p className='text-gray-400 text-lg'>No games played yet</p>
-                  <p className='text-gray-500 text-sm mt-1'>Play your first game to see your stats!</p>
+                  <p className='text-on-surface-muted text-lg'>No games played yet</p>
+                  <p className='text-on-surface-faint text-sm mt-1'>Play your first game to see your stats!</p>
                 </div>
               )}
             </div>
 
             {/* Recent Games */}
             {recentGames.length > 0 && (
-              <div className='bg-gray-900 rounded-xl p-6 border border-gray-600'>
-                <h3 className='text-2xl font-bold text-white mb-6 text-center'>Recent Games</h3>
+              <div className='bg-surface rounded-xl p-6 border border-outline shadow-sm'>
+                <h3 className='text-2xl font-bold text-on-surface mb-6 text-center'>Recent Games</h3>
                 <div className='space-y-3'>
                   {recentGames.map((game) => {
                     const myRecord = game.players.find((p) => p.player.id === user.id);
                     return (
                       <div
                         key={game.game_id}
-                        className='bg-gray-800 rounded-lg p-4 border border-gray-600 flex items-center justify-between'
+                        className='bg-surface-alt rounded-lg p-4 border border-outline flex items-center justify-between'
                       >
                         <div className='flex items-center gap-4'>
                           <div
                             className={`w-10 h-10 rounded-full flex items-center justify-center text-sm font-bold ${
                               myRecord?.place === 1
-                                ? 'bg-yellow-500/20 text-yellow-300 border border-yellow-500/30'
-                                : 'bg-gray-700 text-gray-300 border border-gray-600'
+                                ? 'bg-amber-500 text-white border border-amber-600 dark:bg-amber-500 dark:text-white dark:border-amber-400'
+                                : 'bg-surface-hover text-on-surface-variant border border-outline'
                             }`}
                           >
                             #{myRecord?.place ?? '?'}
                           </div>
                           <div>
-                            <div className='text-white font-medium'>
+                            <div className='text-on-surface font-medium'>
                               {game.players.length} player{game.players.length !== 1 ? 's' : ''}
                             </div>
-                            <div className='text-gray-400 text-xs'>
+                            <div className='text-on-surface-muted text-xs'>
                               {new Date(game.finished_at).toLocaleDateString()} at{' '}
                               {new Date(game.finished_at).toLocaleTimeString([], {
                                 hour: '2-digit',
@@ -165,8 +165,8 @@ export function Welcome() {
                           </div>
                         </div>
                         <div className='text-right'>
-                          <div className='text-white font-bold'>{myRecord?.score.toLocaleString() ?? 0}</div>
-                          <div className='text-gray-500 text-xs'>points</div>
+                          <div className='text-on-surface font-bold'>{myRecord?.score.toLocaleString() ?? 0}</div>
+                          <div className='text-on-surface-faint text-xs'>points</div>
                         </div>
                       </div>
                     );

From 5cee51c581a5bfdc319b49b0823ba7d146659efe Mon Sep 17 00:00:00 2001
From: timofeykafanov <tim.kafanov@gmail.com>
Date: Thu, 12 Mar 2026 22:10:25 +0100
Subject: [PATCH 2/8] feat: enhance game routing and player management with
 initial room support

---
 client/app/components/game/GamePage.tsx     |  9 +++-
 client/app/components/game/RoomControls.tsx | 52 +++++++++++++++++++++
 client/app/hooks/useGameSocket.ts           | 22 ++++++++-
 client/app/root.tsx                         |  2 +-
 client/app/routes.ts                        |  1 +
 client/app/routes/+types/home.d.ts          |  5 --
 client/app/routes/join.tsx                  | 16 +++++++
 client/app/services/games.ts                | 13 ++++--
 8 files changed, 107 insertions(+), 13 deletions(-)
 delete mode 100644 client/app/routes/+types/home.d.ts
 create mode 100644 client/app/routes/join.tsx

diff --git a/client/app/components/game/GamePage.tsx b/client/app/components/game/GamePage.tsx
index 465f631..a6aff53 100644
--- a/client/app/components/game/GamePage.tsx
+++ b/client/app/components/game/GamePage.tsx
@@ -16,11 +16,15 @@ const CELL = 28;
 const MAX_WIDTH = Math.max(...Object.values(GAME_SETUP).map((s) => s.width));
 const MAX_HEIGHT = Math.max(...Object.values(GAME_SETUP).map((s) => s.height));
 
+interface GamePageProps {
+  initialRoom?: string;
+}
+
 /**
  * Main game page component — composes all game sub-components and wires up hooks.
  */
-export function GamePage() {
-  const game = useGameSocket();
+export function GamePage({ initialRoom }: GamePageProps) {
+  const game = useGameSocket(initialRoom);
   useKeyboardControls(game.socketRef, game.room, game.playerId);
 
   const setup = GAME_SETUP[game.selectedMode];
@@ -42,6 +46,7 @@ export function GamePage() {
     error: game.error,
     message: game.message,
     hostName: game.hostName,
+    playerName: game.playerName,
     create: game.create,
     join: game.join,
     start: game.start,
diff --git a/client/app/components/game/RoomControls.tsx b/client/app/components/game/RoomControls.tsx
index 1e621fc..3941adf 100644
--- a/client/app/components/game/RoomControls.tsx
+++ b/client/app/components/game/RoomControls.tsx
@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { GameModeSelector } from '../GameModeSelector';
 import type { GameMode } from '../../constants';
 import type { GameState } from '../../types/socket';
@@ -13,6 +14,7 @@ interface RoomControlsProps {
   error: string | null;
   message: string | null;
   hostName: string | null;
+  playerName: string | null;
   create: () => void;
   join: () => void;
   start: () => void;
@@ -35,6 +37,7 @@ export function RoomControls({
   error,
   message,
   hostName,
+  playerName,
   create,
   join,
   start,
@@ -44,6 +47,39 @@ export function RoomControls({
 }: RoomControlsProps) {
   const isHost = hostId === playerId || state?.hostId === playerId;
   const canRestart = state?.status === 'finished' && playerId && hostId && playerId === hostId;
+  const [linkCopied, setLinkCopied] = useState(false);
+
+  const copyRoomLink = () => {
+    const name = playerName ?? 'player';
+    const url = `${window.location.origin}/${encodeURIComponent(room)}/${encodeURIComponent(name)}`;
+
+    const onSuccess = () => {
+      setLinkCopied(true);
+      setTimeout(() => setLinkCopied(false), 2000);
+    };
+
+    if (navigator.clipboard?.writeText) {
+      navigator.clipboard.writeText(url).then(onSuccess).catch(() => fallbackCopy(url, onSuccess));
+    } else {
+      fallbackCopy(url, onSuccess);
+    }
+  };
+
+  const fallbackCopy = (text: string, onSuccess: () => void) => {
+    const textarea = document.createElement('textarea');
+    textarea.value = text;
+    textarea.style.position = 'fixed';
+    textarea.style.opacity = '0';
+    document.body.appendChild(textarea);
+    textarea.select();
+    try {
+      document.execCommand('copy');
+      onSuccess();
+    } catch {
+      /* silent fail */
+    }
+    document.body.removeChild(textarea);
+  };
 
   if (compact) {
     return (
@@ -110,6 +146,14 @@ export function RoomControls({
                 Leave
               </button>
             )}
+            {playerId && room && (
+              <button
+                onClick={copyRoomLink}
+                className='px-4 py-2 text-sm bg-purple-600 hover:bg-purple-500 text-white font-semibold rounded-lg transition-colors'
+              >
+                {linkCopied ? 'Copied!' : 'Copy Link'}
+              </button>
+            )}
           </div>
 
           {/* Status Messages */}
@@ -195,6 +239,14 @@ export function RoomControls({
                 Leave Room
               </button>
             )}
+            {playerId && room && (
+              <button
+                onClick={copyRoomLink}
+                className='w-full px-4 py-2 bg-purple-600 hover:bg-purple-500 text-white font-semibold rounded-lg transition-colors'
+              >
+                {linkCopied ? 'Copied!' : 'Copy Link'}
+              </button>
+            )}
           </div>
 
           {/* Status Messages */}
diff --git a/client/app/hooks/useGameSocket.ts b/client/app/hooks/useGameSocket.ts
index 6eea76d..24a9a63 100644
--- a/client/app/hooks/useGameSocket.ts
+++ b/client/app/hooks/useGameSocket.ts
@@ -18,6 +18,7 @@ export interface UseGameSocketReturn {
   actionLoading: boolean;
   myView: PlayerState | null;
   hostName: string | null;
+  playerName: string | null;
   opponents: OpponentInfo[];
   join: () => void;
   create: () => void;
@@ -37,8 +38,9 @@ export interface OpponentInfo {
   isHost: boolean;
 }
 
-export function useGameSocket(): UseGameSocketReturn {
-  const [room, setRoom] = useState('');
+export function useGameSocket(initialRoom?: string): UseGameSocketReturn {
+  const [room, setRoom] = useState(initialRoom ?? '');
+  const initialRoomRef = useRef(initialRoom);
   const [playerId, setPlayerId] = useState<string | null>(null);
   const [selectedMode, setSelectedMode] = useState<GameMode>('classic');
   const [state, setState] = useState<GameState | null>(null);
@@ -142,6 +144,16 @@ export function useGameSocket(): UseGameSocketReturn {
       else setError(err?.message ?? String(err));
     });
 
+    /* auto-join if initialRoom was provided (from /:room/:playerName URL) */
+    if (initialRoomRef.current) {
+      const joinRoom = initialRoomRef.current;
+      setActionLoading(true);
+      s.once('connect', () => {
+        s.emit('join', { roomId: joinRoom });
+      });
+      s.connect();
+    }
+
     return () => {
       s.off();
       s.disconnect();
@@ -218,6 +230,11 @@ export function useGameSocket(): UseGameSocketReturn {
     return hid ? (state.players?.[hid]?.name ?? hid) : null;
   }, [state, hostId]);
 
+  const playerName = useMemo(() => {
+    if (!state || !playerId) return null;
+    return state.players?.[playerId]?.name ?? null;
+  }, [state, playerId]);
+
   const computeSpectrumFromBoard = (board: number[][]): number[] => {
     const cols = Array.from({ length: WIDTH }, () => 0);
     for (let x = 0; x < WIDTH; x++) {
@@ -271,6 +288,7 @@ export function useGameSocket(): UseGameSocketReturn {
     actionLoading,
     myView,
     hostName,
+    playerName,
     opponents,
     join,
     create,
diff --git a/client/app/root.tsx b/client/app/root.tsx
index 86a9ddd..fca5754 100644
--- a/client/app/root.tsx
+++ b/client/app/root.tsx
@@ -19,7 +19,7 @@ export const links: Route.LinksFunction = () => [
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang='en'>
+    <html lang='en' suppressHydrationWarning>
       <head>
         <meta charSet='utf-8' />
         <meta
diff --git a/client/app/routes.ts b/client/app/routes.ts
index 0318af5..7226c83 100644
--- a/client/app/routes.ts
+++ b/client/app/routes.ts
@@ -5,4 +5,5 @@ export default [
   route('login', 'routes/login.tsx'),
   route('register', 'routes/register.tsx'),
   route('game', 'routes/game.tsx'),
+  route(':room/:playerName', 'routes/join.tsx'),
 ] satisfies RouteConfig;
diff --git a/client/app/routes/+types/home.d.ts b/client/app/routes/+types/home.d.ts
deleted file mode 100644
index 1f0e4fb..0000000
--- a/client/app/routes/+types/home.d.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export namespace Route {
-  export type MetaArgs = Record<string, any>;
-}
-
-export {};
diff --git a/client/app/routes/join.tsx b/client/app/routes/join.tsx
new file mode 100644
index 0000000..7652dd4
--- /dev/null
+++ b/client/app/routes/join.tsx
@@ -0,0 +1,16 @@
+import { useParams } from 'react-router';
+import { ProtectedRoute } from '../components/auth/ProtectedRoute';
+import { GamePage } from '../components/game/GamePage';
+
+/**
+ * Handles the subject-required URL format: /:room/:playerName
+ * Renders the game page directly and auto-joins the room.
+ */
+export default function JoinRoute() {
+  const { room } = useParams<{ room: string; playerName: string }>();
+  return (
+    <ProtectedRoute>
+      <GamePage initialRoom={room} />
+    </ProtectedRoute>
+  );
+}
diff --git a/client/app/services/games.ts b/client/app/services/games.ts
index 3917940..68d801d 100644
--- a/client/app/services/games.ts
+++ b/client/app/services/games.ts
@@ -69,6 +69,7 @@ const createGamesService = () => {
     let highScore = 0;
     let totalScore = 0;
     let bestPlace = Infinity;
+    let multiplayerGames = 0;
 
     for (const game of games) {
       const myRecord = game.players.find((p) => p.player.id === userId);
@@ -76,14 +77,20 @@ const createGamesService = () => {
 
       totalScore += myRecord.score;
       if (myRecord.score > highScore) highScore = myRecord.score;
-      if (myRecord.place < bestPlace) bestPlace = myRecord.place;
-      if (myRecord.place === 1) wins++;
+
+      // Only count wins, win rate and best place for multiplayer games
+      const isMultiplayer = game.players.length > 1;
+      if (isMultiplayer) {
+        multiplayerGames++;
+        if (myRecord.place < bestPlace) bestPlace = myRecord.place;
+        if (myRecord.place === 1) wins++;
+      }
     }
 
     return {
       gamesPlayed: games.length,
       wins,
-      winRate: games.length > 0 ? Math.round((wins / games.length) * 100) : 0,
+      winRate: multiplayerGames > 0 ? Math.round((wins / multiplayerGames) * 100) : 0,
       highScore,
       averageScore: games.length > 0 ? Math.round(totalScore / games.length) : 0,
       bestPlace: bestPlace === Infinity ? 0 : bestPlace,

From 9f68bf2ce197567a4ef65a0b3cc778dc315814fd Mon Sep 17 00:00:00 2001
From: timofeykafanov <tim.kafanov@gmail.com>
Date: Thu, 12 Mar 2026 22:27:25 +0100
Subject: [PATCH 3/8] feat: improve code readability and maintainability by
 refactoring styles and adding tests for RoomControls and ThemeToggle
 components

---
 client/app/components/game/GameBoard.tsx    |   7 +-
 client/app/components/game/OpponentCard.tsx |   5 +-
 client/app/components/game/RoomControls.tsx |   5 +-
 client/app/root.tsx                         |  13 +-
 client/app/routes/join.tsx                  |   4 -
 client/tests/GameModeSelector.test.tsx      |   2 +-
 client/tests/OpponentCard.test.tsx          |  12 +-
 client/tests/RoomControls.test.tsx          | 586 ++++++++++++++++++++
 client/tests/ThemeToggle.test.tsx           |  94 ++++
 client/tests/gamesService.test.ts           |  52 ++
 client/tests/routes.test.tsx                |  60 +-
 11 files changed, 817 insertions(+), 23 deletions(-)
 create mode 100644 client/tests/RoomControls.test.tsx
 create mode 100644 client/tests/ThemeToggle.test.tsx

diff --git a/client/app/components/game/GameBoard.tsx b/client/app/components/game/GameBoard.tsx
index 3f83653..721c381 100644
--- a/client/app/components/game/GameBoard.tsx
+++ b/client/app/components/game/GameBoard.tsx
@@ -66,12 +66,7 @@ function renderCell(
     return (
       <div
         key={`${x}-${y}`}
-        style={{
-          width: cellSize,
-          height: cellSize,
-          boxSizing: 'border-box',
-          outline: '1px solid var(--cell-grid)',
-        }}
+        style={{ width: cellSize, height: cellSize, boxSizing: 'border-box', outline: '1px solid var(--cell-grid)' }}
       />
     );
   }
diff --git a/client/app/components/game/OpponentCard.tsx b/client/app/components/game/OpponentCard.tsx
index 634df86..1859baf 100644
--- a/client/app/components/game/OpponentCard.tsx
+++ b/client/app/components/game/OpponentCard.tsx
@@ -77,7 +77,10 @@ export function OpponentCard({ name, board, isAlive, score, isHost, idColors, wi
         </div>
       </div>
       {/* Right: Board */}
-      <div className='shrink-0 rounded-lg p-1.5 border border-outline flex justify-center' style={{ background: 'var(--mini-board-bg)' }}>
+      <div
+        className='shrink-0 rounded-lg p-1.5 border border-outline flex justify-center'
+        style={{ background: 'var(--mini-board-bg)' }}
+      >
         {renderOpponentBoard()}
       </div>
     </div>
diff --git a/client/app/components/game/RoomControls.tsx b/client/app/components/game/RoomControls.tsx
index 3941adf..bb5479b 100644
--- a/client/app/components/game/RoomControls.tsx
+++ b/client/app/components/game/RoomControls.tsx
@@ -59,7 +59,10 @@ export function RoomControls({
     };
 
     if (navigator.clipboard?.writeText) {
-      navigator.clipboard.writeText(url).then(onSuccess).catch(() => fallbackCopy(url, onSuccess));
+      navigator.clipboard
+        .writeText(url)
+        .then(onSuccess)
+        .catch(() => fallbackCopy(url, onSuccess));
     } else {
       fallbackCopy(url, onSuccess);
     }
diff --git a/client/app/root.tsx b/client/app/root.tsx
index fca5754..937bc4d 100644
--- a/client/app/root.tsx
+++ b/client/app/root.tsx
@@ -19,7 +19,10 @@ export const links: Route.LinksFunction = () => [
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <html lang='en' suppressHydrationWarning>
+    <html
+      lang='en'
+      suppressHydrationWarning
+    >
       <head>
         <meta charSet='utf-8' />
         <meta
@@ -30,7 +33,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
         <Links />
         <script
           dangerouslySetInnerHTML={{
-            __html: `(function(){try{var t=localStorage.getItem('red-tetris-theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}})()`
+            __html:
+              "(function(){try{var t=localStorage.getItem('red-tetris-theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}})()",
           }}
         />
       </head>
@@ -50,7 +54,10 @@ export default function App() {
 
   return (
     <Provider store={store}>
-      <ThemeToggle theme={theme} toggle={toggle} />
+      <ThemeToggle
+        theme={theme}
+        toggle={toggle}
+      />
       <Outlet />
       {isNavigating && <LoadingOverlay />}
     </Provider>
diff --git a/client/app/routes/join.tsx b/client/app/routes/join.tsx
index 7652dd4..0ec6382 100644
--- a/client/app/routes/join.tsx
+++ b/client/app/routes/join.tsx
@@ -2,10 +2,6 @@ import { useParams } from 'react-router';
 import { ProtectedRoute } from '../components/auth/ProtectedRoute';
 import { GamePage } from '../components/game/GamePage';
 
-/**
- * Handles the subject-required URL format: /:room/:playerName
- * Renders the game page directly and auto-joins the room.
- */
 export default function JoinRoute() {
   const { room } = useParams<{ room: string; playerName: string }>();
   return (
diff --git a/client/tests/GameModeSelector.test.tsx b/client/tests/GameModeSelector.test.tsx
index e6cef52..3046364 100644
--- a/client/tests/GameModeSelector.test.tsx
+++ b/client/tests/GameModeSelector.test.tsx
@@ -149,7 +149,7 @@ describe('GameModeSelector', () => {
     it('does not highlight non-selected modes', () => {
       render(<GameModeSelector {...defaultProps} />);
       const narrowBtn = screen.getByText('Narrow').closest('button');
-      expect(narrowBtn?.className).toContain('bg-gray-800');
+      expect(narrowBtn?.className).toContain('bg-surface-alt');
       expect(narrowBtn?.className).not.toContain('ring-1');
     });
   });
diff --git a/client/tests/OpponentCard.test.tsx b/client/tests/OpponentCard.test.tsx
index 5766bf1..7136fd5 100644
--- a/client/tests/OpponentCard.test.tsx
+++ b/client/tests/OpponentCard.test.tsx
@@ -150,7 +150,7 @@ describe('OpponentCard', () => {
         />
       );
       const cell = container.querySelector<HTMLElement>('[style*="box-sizing"]');
-      expect(cell?.style.background).toBe('rgba(255, 255, 255, 0.06)');
+      expect(cell?.style.background).toBe('var(--opponent-ghost-alive)');
     });
 
     it('renders penalty cells (val=-2) with dead color', () => {
@@ -165,7 +165,7 @@ describe('OpponentCard', () => {
         />
       );
       const cell = container.querySelector<HTMLElement>('[style*="box-sizing"]');
-      expect(cell?.style.background).toBe('rgba(255, 255, 255, 0.03)');
+      expect(cell?.style.background).toBe('var(--opponent-ghost-dead)');
     });
 
     it('renders locked cells (val=-1) with alive color', () => {
@@ -180,7 +180,7 @@ describe('OpponentCard', () => {
         />
       );
       const cell = container.querySelector<HTMLElement>('[style*="box-sizing"]');
-      expect(cell?.style.background).toBe('rgb(17, 17, 17)');
+      expect(cell?.style.background).toBe('var(--opponent-penalty-alive)');
     });
 
     it('renders locked cells (val=-1) with dead color', () => {
@@ -195,7 +195,7 @@ describe('OpponentCard', () => {
         />
       );
       const cell = container.querySelector<HTMLElement>('[style*="box-sizing"]');
-      expect(cell?.style.background).toBe('rgb(68, 68, 68)');
+      expect(cell?.style.background).toBe('var(--opponent-penalty-dead)');
     });
 
     it('renders piece cells (val>0) with idColors when alive', () => {
@@ -213,7 +213,7 @@ describe('OpponentCard', () => {
       expect(cell?.style.background).toBe('rgb(255, 0, 0)'); // idColors[1]
     });
 
-    it('renders piece cells (val>0) as #777 when dead', () => {
+    it('renders piece cells (val>0) as dead-piece color when dead', () => {
       const board = [[1]];
       const { container } = render(
         <OpponentCard
@@ -225,7 +225,7 @@ describe('OpponentCard', () => {
         />
       );
       const cell = container.querySelector<HTMLElement>('[style*="box-sizing"]');
-      expect(cell?.style.background).toBe('rgb(119, 119, 119)');
+      expect(cell?.style.background).toBe('var(--opponent-dead-piece)');
     });
 
     it('falls back to #999 when idColors does not have the piece index', () => {
diff --git a/client/tests/RoomControls.test.tsx b/client/tests/RoomControls.test.tsx
new file mode 100644
index 0000000..1adbd89
--- /dev/null
+++ b/client/tests/RoomControls.test.tsx
@@ -0,0 +1,586 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { RoomControls } from '~/components/game/RoomControls';
+
+// Mock GameModeSelector to keep tests focused on RoomControls logic
+vi.mock('~/components/GameModeSelector', () => ({
+  GameModeSelector: ({ selected, disabled }: { selected: string; disabled?: boolean }) => (
+    <div data-testid='game-mode-selector'>
+      mode={selected} disabled={String(!!disabled)}
+    </div>
+  ),
+}));
+
+const defaultProps = {
+  room: 'test-room',
+  setRoom: vi.fn(),
+  selectedMode: 'classic' as const,
+  setSelectedMode: vi.fn(),
+  playerId: null as string | null,
+  hostId: null as string | null,
+  state: null,
+  error: null as string | null,
+  message: null as string | null,
+  hostName: null as string | null,
+  playerName: null as string | null,
+  create: vi.fn(),
+  join: vi.fn(),
+  start: vi.fn(),
+  leave: vi.fn(),
+  restart: vi.fn(),
+};
+
+describe('RoomControls', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('desktop variant (default)', () => {
+    it('renders Room Settings heading', () => {
+      render(<RoomControls {...defaultProps} />);
+      expect(screen.getByText('Room Settings')).toBeInTheDocument();
+    });
+
+    it('renders room code input with current value', () => {
+      render(<RoomControls {...defaultProps} />);
+      const input = screen.getByPlaceholderText('Enter room code');
+      expect(input).toBeInTheDocument();
+      expect(input).toHaveValue('test-room');
+    });
+
+    it('calls setRoom when input changes', () => {
+      const setRoom = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          setRoom={setRoom}
+        />
+      );
+      fireEvent.change(screen.getByPlaceholderText('Enter room code'), { target: { value: 'new-room' } });
+      expect(setRoom).toHaveBeenCalledWith('new-room');
+    });
+
+    it('disables room input when player is in a room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+        />
+      );
+      expect(screen.getByPlaceholderText('Enter room code')).toBeDisabled();
+    });
+
+    it('renders Create Room button when not in a room', () => {
+      render(<RoomControls {...defaultProps} />);
+      expect(screen.getByText('Create Room')).toBeInTheDocument();
+    });
+
+    it('renders Join Room button when not in a room', () => {
+      render(<RoomControls {...defaultProps} />);
+      expect(screen.getByText('Join Room')).toBeInTheDocument();
+    });
+
+    it('hides Create/Join when in a room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+        />
+      );
+      expect(screen.queryByText('Create Room')).not.toBeInTheDocument();
+      expect(screen.queryByText('Join Room')).not.toBeInTheDocument();
+    });
+
+    it('calls create when Create Room is clicked', () => {
+      const create = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          create={create}
+        />
+      );
+      fireEvent.click(screen.getByText('Create Room'));
+      expect(create).toHaveBeenCalledOnce();
+    });
+
+    it('calls join when Join Room is clicked', () => {
+      const join = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          join={join}
+        />
+      );
+      fireEvent.click(screen.getByText('Join Room'));
+      expect(join).toHaveBeenCalledOnce();
+    });
+
+    it('disables Join Room when room is empty', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          room=''
+        />
+      );
+      expect(screen.getByText('Join Room')).toBeDisabled();
+    });
+
+    it('disables Start Game when no playerId', () => {
+      render(<RoomControls {...defaultProps} />);
+      expect(screen.getByText('Start Game')).toBeDisabled();
+    });
+
+    it('disables Start Game when player is not host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p2'
+          hostId='p1'
+        />
+      );
+      expect(screen.getByText('Start Game')).toBeDisabled();
+    });
+
+    it('enables Start Game when player is the host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+        />
+      );
+      expect(screen.getByText('Start Game')).not.toBeDisabled();
+    });
+
+    it('calls start when Start Game is clicked', () => {
+      const start = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          start={start}
+        />
+      );
+      fireEvent.click(screen.getByText('Start Game'));
+      expect(start).toHaveBeenCalledOnce();
+    });
+
+    it('shows Leave Room button only when in a room', () => {
+      const { rerender } = render(<RoomControls {...defaultProps} />);
+      expect(screen.queryByText('Leave Room')).not.toBeInTheDocument();
+
+      rerender(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+        />
+      );
+      expect(screen.getByText('Leave Room')).toBeInTheDocument();
+    });
+
+    it('calls leave when Leave Room is clicked', () => {
+      const leave = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          leave={leave}
+        />
+      );
+      fireEvent.click(screen.getByText('Leave Room'));
+      expect(leave).toHaveBeenCalledOnce();
+    });
+
+    it('shows Restart button only when game is finished and player is host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          state={{ status: 'finished', tick: 0, speed: 1, players: {} }}
+        />
+      );
+      expect(screen.getByText('Restart')).toBeInTheDocument();
+    });
+
+    it('hides Restart when game is not finished', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          state={{ status: 'running', tick: 0, speed: 1, players: {} }}
+        />
+      );
+      expect(screen.queryByText('Restart')).not.toBeInTheDocument();
+    });
+
+    it('hides Restart when player is not host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p2'
+          hostId='p1'
+          state={{ status: 'finished', tick: 0, speed: 1, players: {} }}
+        />
+      );
+      expect(screen.queryByText('Restart')).not.toBeInTheDocument();
+    });
+
+    it('calls restart when Restart is clicked', () => {
+      const restart = vi.fn();
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          state={{ status: 'finished', tick: 0, speed: 1, players: {} }}
+          restart={restart}
+        />
+      );
+      fireEvent.click(screen.getByText('Restart'));
+      expect(restart).toHaveBeenCalledOnce();
+    });
+
+    it('renders GameModeSelector', () => {
+      render(<RoomControls {...defaultProps} />);
+      expect(screen.getByTestId('game-mode-selector')).toBeInTheDocument();
+    });
+  });
+
+  describe('compact variant', () => {
+    it('renders compact heading', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          compact
+        />
+      );
+      expect(screen.getByText('Room Settings')).toBeInTheDocument();
+    });
+
+    it('renders room code input in compact mode', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          compact
+        />
+      );
+      expect(screen.getByPlaceholderText('Room code')).toBeInTheDocument();
+    });
+
+    it('renders Create/Join/Start buttons in compact mode', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          compact
+        />
+      );
+      expect(screen.getByText('Create')).toBeInTheDocument();
+      expect(screen.getByText('Join')).toBeInTheDocument();
+      expect(screen.getByText('Start')).toBeInTheDocument();
+    });
+
+    it('disables Create in compact when already in a room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          compact
+        />
+      );
+      expect(screen.getByText('Create')).toBeDisabled();
+    });
+
+    it('disables Join in compact when no room or already in room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          room=''
+          compact
+        />
+      );
+      expect(screen.getByText('Join')).toBeDisabled();
+    });
+
+    it('shows Leave button in compact when in a room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          compact
+        />
+      );
+      expect(screen.getByText('Leave')).toBeInTheDocument();
+    });
+
+    it('shows Restart in compact when game finished and host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          state={{ status: 'finished', tick: 0, speed: 1, players: {} }}
+          compact
+        />
+      );
+      expect(screen.getByText('Restart')).toBeInTheDocument();
+    });
+  });
+
+  describe('Copy Link button', () => {
+    it('shows Copy Link when in a room with a room code', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+        />
+      );
+      expect(screen.getByText('Copy Link')).toBeInTheDocument();
+    });
+
+    it('hides Copy Link when not in a room', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          room='my-room'
+        />
+      );
+      expect(screen.queryByText('Copy Link')).not.toBeInTheDocument();
+    });
+
+    it('hides Copy Link when room is empty', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room=''
+        />
+      );
+      expect(screen.queryByText('Copy Link')).not.toBeInTheDocument();
+    });
+
+    it('copies link via navigator.clipboard and shows Copied!', async () => {
+      const writeText = vi.fn().mockResolvedValue(undefined);
+      Object.assign(navigator, { clipboard: { writeText } });
+
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+          playerName='alice'
+        />
+      );
+      fireEvent.click(screen.getByText('Copy Link'));
+
+      await waitFor(() => {
+        expect(screen.getByText('Copied!')).toBeInTheDocument();
+      });
+      expect(writeText).toHaveBeenCalledWith(expect.stringContaining('/my-room/alice'));
+    });
+
+    it('uses fallback copy when clipboard API is unavailable', () => {
+      // Remove clipboard API
+      Object.assign(navigator, { clipboard: undefined });
+
+      const execCommand = vi.fn().mockReturnValue(true);
+      document.execCommand = execCommand;
+
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+          playerName='bob'
+          compact
+        />
+      );
+      fireEvent.click(screen.getByText('Copy Link'));
+
+      expect(execCommand).toHaveBeenCalledWith('copy');
+    });
+
+    it('uses fallback when clipboard.writeText rejects', async () => {
+      const writeText = vi.fn().mockRejectedValue(new Error('denied'));
+      Object.assign(navigator, { clipboard: { writeText } });
+
+      const execCommand = vi.fn().mockReturnValue(true);
+      document.execCommand = execCommand;
+
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+          playerName='carol'
+        />
+      );
+      fireEvent.click(screen.getByText('Copy Link'));
+
+      await waitFor(() => {
+        expect(execCommand).toHaveBeenCalledWith('copy');
+      });
+    });
+
+    it('uses "player" as default name when playerName is null', async () => {
+      const writeText = vi.fn().mockResolvedValue(undefined);
+      Object.assign(navigator, { clipboard: { writeText } });
+
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+          playerName={null}
+        />
+      );
+      fireEvent.click(screen.getByText('Copy Link'));
+
+      await waitFor(() => {
+        expect(writeText).toHaveBeenCalledWith(expect.stringContaining('/my-room/player'));
+      });
+    });
+
+    it('shows Copy Link in compact mode', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          room='my-room'
+          compact
+        />
+      );
+      expect(screen.getByText('Copy Link')).toBeInTheDocument();
+    });
+  });
+
+  describe('StatusMessages', () => {
+    it('shows room code when player is host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          room='ABC123'
+        />
+      );
+      expect(screen.getByText('Room:')).toBeInTheDocument();
+      expect(screen.getByText('ABC123')).toBeInTheDocument();
+    });
+
+    it('does not show room code when player is not host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p2'
+          hostId='p1'
+          room='ABC123'
+        />
+      );
+      // The "Room:" label should not be present for non-host
+      expect(screen.queryByText('Room:')).not.toBeInTheDocument();
+    });
+
+    it('shows host name', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          hostName='Alice'
+        />
+      );
+      expect(screen.getByText('Host:')).toBeInTheDocument();
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    it('shows (you) indicator when current player is host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId='p1'
+          hostName='Alice'
+        />
+      );
+      expect(screen.getByText('(you)')).toBeInTheDocument();
+    });
+
+    it('does not show (you) when not the host', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p2'
+          hostId='p1'
+          hostName='Alice'
+        />
+      );
+      expect(screen.queryByText('(you)')).not.toBeInTheDocument();
+    });
+
+    it('shows error message', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          error='Room not found'
+        />
+      );
+      expect(screen.getByText('Room not found')).toBeInTheDocument();
+    });
+
+    it('shows success message', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          message='Player joined!'
+        />
+      );
+      expect(screen.getByText('Player joined!')).toBeInTheDocument();
+    });
+
+    it('does not show error when null', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          error={null}
+        />
+      );
+      // No error container
+      const errorEls = document.querySelectorAll('.text-status-error-text');
+      expect(errorEls.length).toBe(0);
+    });
+
+    it('shows status messages in compact mode', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          error='Some error'
+          message='Some message'
+          hostName='Host1'
+          compact
+        />
+      );
+      expect(screen.getByText('Some error')).toBeInTheDocument();
+      expect(screen.getByText('Some message')).toBeInTheDocument();
+      expect(screen.getByText('Host1')).toBeInTheDocument();
+    });
+  });
+
+  describe('isHost via state.hostId fallback', () => {
+    it('uses state.hostId when hostId prop is null', () => {
+      render(
+        <RoomControls
+          {...defaultProps}
+          playerId='p1'
+          hostId={null}
+          state={{ status: 'finished', tick: 0, speed: 1, players: {}, hostId: 'p1' }}
+        />
+      );
+      // canRestart should be false because hostId prop is null (used for canRestart check)
+      // but isHost uses state.hostId fallback
+      // hostName not set so no "(you)" check; but at least shouldn't crash
+      expect(screen.getByText('Start Game')).toBeInTheDocument();
+    });
+  });
+});
diff --git a/client/tests/ThemeToggle.test.tsx b/client/tests/ThemeToggle.test.tsx
new file mode 100644
index 0000000..49e1092
--- /dev/null
+++ b/client/tests/ThemeToggle.test.tsx
@@ -0,0 +1,94 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ThemeToggle } from '~/components/ThemeToggle';
+
+describe('ThemeToggle', () => {
+  it('renders sun icon in dark mode', () => {
+    const { container } = render(
+      <ThemeToggle
+        theme='dark'
+        toggle={vi.fn()}
+      />
+    );
+    // Sun icon has a circle-based path (d includes "M12 3v1")
+    const svg = container.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+    expect(svg?.classList.contains('text-yellow-400')).toBe(true);
+  });
+
+  it('renders moon icon in light mode', () => {
+    const { container } = render(
+      <ThemeToggle
+        theme='light'
+        toggle={vi.fn()}
+      />
+    );
+    const svg = container.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+    expect(svg?.classList.contains('text-slate-600')).toBe(true);
+  });
+
+  it('has correct aria-label for dark mode (switch to light)', () => {
+    render(
+      <ThemeToggle
+        theme='dark'
+        toggle={vi.fn()}
+      />
+    );
+    expect(screen.getByLabelText('Switch to light mode')).toBeInTheDocument();
+  });
+
+  it('has correct aria-label for light mode (switch to dark)', () => {
+    render(
+      <ThemeToggle
+        theme='light'
+        toggle={vi.fn()}
+      />
+    );
+    expect(screen.getByLabelText('Switch to dark mode')).toBeInTheDocument();
+  });
+
+  it('has correct title for dark mode', () => {
+    render(
+      <ThemeToggle
+        theme='dark'
+        toggle={vi.fn()}
+      />
+    );
+    expect(screen.getByTitle('Switch to light mode')).toBeInTheDocument();
+  });
+
+  it('has correct title for light mode', () => {
+    render(
+      <ThemeToggle
+        theme='light'
+        toggle={vi.fn()}
+      />
+    );
+    expect(screen.getByTitle('Switch to dark mode')).toBeInTheDocument();
+  });
+
+  it('calls toggle when clicked', () => {
+    const toggle = vi.fn();
+    render(
+      <ThemeToggle
+        theme='dark'
+        toggle={toggle}
+      />
+    );
+    fireEvent.click(screen.getByRole('button'));
+    expect(toggle).toHaveBeenCalledOnce();
+  });
+
+  it('renders as a button element', () => {
+    render(
+      <ThemeToggle
+        theme='dark'
+        toggle={vi.fn()}
+      />
+    );
+    const button = screen.getByRole('button');
+    expect(button).toBeInTheDocument();
+    expect(button.tagName).toBe('BUTTON');
+  });
+});
diff --git a/client/tests/gamesService.test.ts b/client/tests/gamesService.test.ts
index 9d76436..f6f0251 100644
--- a/client/tests/gamesService.test.ts
+++ b/client/tests/gamesService.test.ts
@@ -181,5 +181,57 @@ describe('gamesService', () => {
       expect(stats.highScore).toBe(0);
       expect(stats.bestPlace).toBe(0); // Infinity becomes 0
     });
+
+    it('excludes solo games from wins, winRate and bestPlace', () => {
+      const games = [
+        {
+          game_id: 1,
+          finished_at: '2025-01-01',
+          players: [{ player: { id: 1, username: 'me' }, score: 800, place: 1 }],
+        },
+      ];
+
+      const stats = gamesService.computeStats(games, 1);
+      expect(stats.gamesPlayed).toBe(1);
+      expect(stats.wins).toBe(0); // solo game, not counted
+      expect(stats.winRate).toBe(0); // no multiplayer games
+      expect(stats.highScore).toBe(800); // still counted for score
+      expect(stats.averageScore).toBe(800);
+      expect(stats.bestPlace).toBe(0); // solo excluded
+    });
+
+    it('counts multiplayer wins but not solo wins', () => {
+      const games = [
+        {
+          game_id: 1,
+          finished_at: '2025-01-01',
+          players: [{ player: { id: 1, username: 'me' }, score: 500, place: 1 }],
+        },
+        {
+          game_id: 2,
+          finished_at: '2025-01-02',
+          players: [
+            { player: { id: 1, username: 'me' }, score: 300, place: 1 },
+            { player: { id: 2, username: 'other' }, score: 100, place: 2 },
+          ],
+        },
+        {
+          game_id: 3,
+          finished_at: '2025-01-03',
+          players: [
+            { player: { id: 1, username: 'me' }, score: 200, place: 2 },
+            { player: { id: 3, username: 'third' }, score: 400, place: 1 },
+          ],
+        },
+      ];
+
+      const stats = gamesService.computeStats(games, 1);
+      expect(stats.gamesPlayed).toBe(3);
+      expect(stats.wins).toBe(1); // only game 2 (multiplayer win)
+      expect(stats.winRate).toBe(50); // 1 win / 2 multiplayer games
+      expect(stats.highScore).toBe(500); // solo game score still counts
+      expect(stats.averageScore).toBe(333); // Math.round((500+300+200)/3)
+      expect(stats.bestPlace).toBe(1); // from multiplayer game 2
+    });
   });
 });
diff --git a/client/tests/routes.test.tsx b/client/tests/routes.test.tsx
index 81780a0..4be6e05 100644
--- a/client/tests/routes.test.tsx
+++ b/client/tests/routes.test.tsx
@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import { Provider } from 'react-redux';
 import { configureStore } from '@reduxjs/toolkit';
-import { MemoryRouter } from 'react-router';
+import { MemoryRouter, Route, Routes } from 'react-router';
 import authReducer from '~/store/authSlice';
 
 // Mock services
@@ -27,6 +27,12 @@ vi.mock('~/services/games', () => ({
   },
 }));
 
+vi.mock('~/components/game/GamePage', () => ({
+  GamePage: ({ initialRoom }: { initialRoom?: string }) => (
+    <div data-testid='game-page'>GamePage: {initialRoom ?? 'no-room'}</div>
+  ),
+}));
+
 const createStore = (authState = {}) =>
   configureStore({
     reducer: { auth: authReducer },
@@ -118,3 +124,55 @@ describe('Route meta functions', () => {
     expect(result).toEqual(expect.arrayContaining([expect.objectContaining({ title: 'Red Tetris - Home' })]));
   });
 });
+
+describe('Route: Join', () => {
+  it('renders GamePage with initialRoom from URL params when authenticated', async () => {
+    const { default: JoinRoute } = await import('~/routes/join');
+    const store = createStore({
+      hydrated: true,
+      isAuthenticated: true,
+      user: { id: 1, username: 'testuser', email: 'test@test.com', created_at: '', updated_at: '' },
+    });
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter initialEntries={['/my-room/host-player']}>
+          <Routes>
+            <Route
+              path='/:room/:playerName'
+              element={<JoinRoute />}
+            />
+          </Routes>
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(screen.getByTestId('game-page')).toBeInTheDocument();
+    expect(screen.getByText('GamePage: my-room')).toBeInTheDocument();
+  });
+
+  it('redirects to login when not authenticated', async () => {
+    const { default: JoinRoute } = await import('~/routes/join');
+    const store = createStore({ hydrated: true, isAuthenticated: false });
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter initialEntries={['/my-room/host-player']}>
+          <Routes>
+            <Route
+              path='/:room/:playerName'
+              element={<JoinRoute />}
+            />
+            <Route
+              path='/login'
+              element={<div>Login Page</div>}
+            />
+          </Routes>
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(screen.queryByTestId('game-page')).not.toBeInTheDocument();
+    expect(screen.getByText('Login Page')).toBeInTheDocument();
+  });
+});

From dfe0c13ecfcfc7f31a94a1439371fc96e6e63317 Mon Sep 17 00:00:00 2001
From: timofeykafanov <tim.kafanov@gmail.com>
Date: Thu, 12 Mar 2026 22:27:38 +0100
Subject: [PATCH 4/8] feat: add unit tests for useTheme hook to validate theme
 management and persistence

---
 client/tests/useTheme.test.ts | 115 ++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 client/tests/useTheme.test.ts

diff --git a/client/tests/useTheme.test.ts b/client/tests/useTheme.test.ts
new file mode 100644
index 0000000..c193ac9
--- /dev/null
+++ b/client/tests/useTheme.test.ts
@@ -0,0 +1,115 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useTheme } from '~/hooks/useTheme';
+
+describe('useTheme', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    document.documentElement.classList.remove('dark');
+    vi.mocked(localStorage.getItem).mockClear();
+    vi.mocked(localStorage.setItem).mockClear();
+  });
+
+  it('defaults to dark theme when localStorage is empty and prefers-color-scheme is dark', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue(null);
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: vi
+        .fn()
+        .mockImplementation((query: string) => ({ matches: query === '(prefers-color-scheme: dark)', media: query })),
+    });
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('dark');
+  });
+
+  it('defaults to light theme when prefers-color-scheme is light', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue(null);
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({ matches: false, media: query })),
+    });
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('light');
+  });
+
+  it('reads theme from localStorage when stored', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('light');
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('light');
+  });
+
+  it('reads dark theme from localStorage', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('dark');
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('dark');
+  });
+
+  it('adds dark class to documentElement when theme is dark', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('dark');
+
+    renderHook(() => useTheme());
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+  });
+
+  it('removes dark class from documentElement when theme is light', () => {
+    document.documentElement.classList.add('dark');
+    vi.mocked(localStorage.getItem).mockReturnValue('light');
+
+    renderHook(() => useTheme());
+    expect(document.documentElement.classList.contains('dark')).toBe(false);
+  });
+
+  it('persists theme to localStorage', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('dark');
+
+    renderHook(() => useTheme());
+    expect(localStorage.setItem).toHaveBeenCalledWith('red-tetris-theme', 'dark');
+  });
+
+  it('toggles from dark to light', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('dark');
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('dark');
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.theme).toBe('light');
+    expect(document.documentElement.classList.contains('dark')).toBe(false);
+    expect(localStorage.setItem).toHaveBeenCalledWith('red-tetris-theme', 'light');
+  });
+
+  it('toggles from light to dark', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('light');
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('light');
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.theme).toBe('dark');
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+    expect(localStorage.setItem).toHaveBeenCalledWith('red-tetris-theme', 'dark');
+  });
+
+  it('ignores invalid localStorage values and falls back to matchMedia', () => {
+    vi.mocked(localStorage.getItem).mockReturnValue('invalid-value');
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: vi
+        .fn()
+        .mockImplementation((query: string) => ({ matches: query === '(prefers-color-scheme: dark)', media: query })),
+    });
+
+    const { result } = renderHook(() => useTheme());
+    expect(result.current.theme).toBe('dark');
+  });
+});

From 3c94c8834127d220eddc545b5c8b1e8ae1feb3f1 Mon Sep 17 00:00:00 2001
From: timofeykafanov <tim.kafanov@gmail.com>
Date: Thu, 12 Mar 2026 22:33:54 +0100
Subject: [PATCH 5/8] feat: replace SVG icons with text-based icons in
 ThemeToggle component and update tests accordingly

---
 client/app/components/ThemeToggle.tsx       | 36 ++++++---------------
 client/app/components/auth/LoginForm.tsx    | 21 +-----------
 client/app/components/auth/RegisterForm.tsx | 21 +-----------
 client/tests/ThemeToggle.test.tsx           | 15 +++++----
 4 files changed, 20 insertions(+), 73 deletions(-)

diff --git a/client/app/components/ThemeToggle.tsx b/client/app/components/ThemeToggle.tsx
index f2c1903..f03f8ec 100644
--- a/client/app/components/ThemeToggle.tsx
+++ b/client/app/components/ThemeToggle.tsx
@@ -12,35 +12,19 @@ export function ThemeToggle({ theme, toggle }: ThemeToggleProps) {
       title={`Switch to ${theme === 'dark' ? 'light' : 'dark'} mode`}
     >
       {theme === 'dark' ? (
-        <svg
-          xmlns='http://www.w3.org/2000/svg'
-          className='w-5 h-5 text-yellow-400'
-          fill='none'
-          viewBox='0 0 24 24'
-          stroke='currentColor'
-          strokeWidth={2}
+        <span
+          className='w-5 h-5 text-yellow-400 flex items-center justify-center text-lg leading-none'
+          aria-hidden='true'
         >
-          <path
-            strokeLinecap='round'
-            strokeLinejoin='round'
-            d='M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z'
-          />
-        </svg>
+          ☀
+        </span>
       ) : (
-        <svg
-          xmlns='http://www.w3.org/2000/svg'
-          className='w-5 h-5 text-slate-600'
-          fill='none'
-          viewBox='0 0 24 24'
-          stroke='currentColor'
-          strokeWidth={2}
+        <span
+          className='w-5 h-5 text-slate-600 flex items-center justify-center text-lg leading-none'
+          aria-hidden='true'
         >
-          <path
-            strokeLinecap='round'
-            strokeLinejoin='round'
-            d='M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z'
-          />
-        </svg>
+          ☾
+        </span>
       )}
     </button>
   );
diff --git a/client/app/components/auth/LoginForm.tsx b/client/app/components/auth/LoginForm.tsx
index 50f8412..8b19923 100644
--- a/client/app/components/auth/LoginForm.tsx
+++ b/client/app/components/auth/LoginForm.tsx
@@ -95,26 +95,7 @@ export function LoginForm() {
             >
               {isLoading ? (
                 <span className='flex items-center justify-center'>
-                  <svg
-                    className='animate-spin -ml-1 mr-3 h-5 w-5 text-white'
-                    xmlns='http://www.w3.org/2000/svg'
-                    fill='none'
-                    viewBox='0 0 24 24'
-                  >
-                    <circle
-                      className='opacity-25'
-                      cx='12'
-                      cy='12'
-                      r='10'
-                      stroke='currentColor'
-                      strokeWidth='4'
-                    ></circle>
-                    <path
-                      className='opacity-75'
-                      fill='currentColor'
-                      d='m4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z'
-                    ></path>
-                  </svg>
+                  <span className='animate-spin -ml-1 mr-3 h-5 w-5 border-2 border-white border-t-transparent rounded-full inline-block'></span>
                   Signing in...
                 </span>
               ) : (
diff --git a/client/app/components/auth/RegisterForm.tsx b/client/app/components/auth/RegisterForm.tsx
index c2ec52d..eda99ea 100644
--- a/client/app/components/auth/RegisterForm.tsx
+++ b/client/app/components/auth/RegisterForm.tsx
@@ -146,26 +146,7 @@ export function RegisterForm() {
             >
               {isLoading ? (
                 <span className='flex items-center justify-center'>
-                  <svg
-                    className='animate-spin -ml-1 mr-3 h-5 w-5 text-white'
-                    xmlns='http://www.w3.org/2000/svg'
-                    fill='none'
-                    viewBox='0 0 24 24'
-                  >
-                    <circle
-                      className='opacity-25'
-                      cx='12'
-                      cy='12'
-                      r='10'
-                      stroke='currentColor'
-                      strokeWidth='4'
-                    ></circle>
-                    <path
-                      className='opacity-75'
-                      fill='currentColor'
-                      d='m4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z'
-                    ></path>
-                  </svg>
+                  <span className='animate-spin -ml-1 mr-3 h-5 w-5 border-2 border-white border-t-transparent rounded-full inline-block'></span>
                   Creating account...
                 </span>
               ) : (
diff --git a/client/tests/ThemeToggle.test.tsx b/client/tests/ThemeToggle.test.tsx
index 49e1092..2f96fd7 100644
--- a/client/tests/ThemeToggle.test.tsx
+++ b/client/tests/ThemeToggle.test.tsx
@@ -10,10 +10,10 @@ describe('ThemeToggle', () => {
         toggle={vi.fn()}
       />
     );
-    // Sun icon has a circle-based path (d includes "M12 3v1")
-    const svg = container.querySelector('svg');
-    expect(svg).toBeInTheDocument();
-    expect(svg?.classList.contains('text-yellow-400')).toBe(true);
+    const icon = container.querySelector('span[aria-hidden="true"]');
+    expect(icon).toBeInTheDocument();
+    expect(icon?.classList.contains('text-yellow-400')).toBe(true);
+    expect(icon?.textContent).toBe('☀');
   });
 
   it('renders moon icon in light mode', () => {
@@ -23,9 +23,10 @@ describe('ThemeToggle', () => {
         toggle={vi.fn()}
       />
     );
-    const svg = container.querySelector('svg');
-    expect(svg).toBeInTheDocument();
-    expect(svg?.classList.contains('text-slate-600')).toBe(true);
+    const icon = container.querySelector('span[aria-hidden="true"]');
+    expect(icon).toBeInTheDocument();
+    expect(icon?.classList.contains('text-slate-600')).toBe(true);
+    expect(icon?.textContent).toBe('☾');
   });
 
   it('has correct aria-label for dark mode (switch to light)', () => {

From aacebea26b0651f42270f9abe198cfe62105dee1 Mon Sep 17 00:00:00 2001
From: Timofey Kafanov <tim.kafanov@gmail.com>
Date: Fri, 13 Mar 2026 08:48:47 +0000
Subject: [PATCH 6/8] feat: update ThemeToggle component styles, enhance
 useTheme hook for hydration, and add Chrome Devtools route

---
 client/app/components/ThemeToggle.tsx     |  2 +-
 client/app/hooks/useTheme.ts              | 20 +++++++++++++++-----
 client/app/root.tsx                       | 20 ++++++++------------
 client/app/routes.ts                      |  1 +
 client/app/routes/chrome-devtools.tsx     |  7 +++++++
 client/tests/chromeDevtoolsRoute.test.tsx | 19 +++++++++++++++++++
 6 files changed, 51 insertions(+), 18 deletions(-)
 create mode 100644 client/app/routes/chrome-devtools.tsx
 create mode 100644 client/tests/chromeDevtoolsRoute.test.tsx

diff --git a/client/app/components/ThemeToggle.tsx b/client/app/components/ThemeToggle.tsx
index f03f8ec..6148f86 100644
--- a/client/app/components/ThemeToggle.tsx
+++ b/client/app/components/ThemeToggle.tsx
@@ -20,7 +20,7 @@ export function ThemeToggle({ theme, toggle }: ThemeToggleProps) {
         </span>
       ) : (
         <span
-          className='w-5 h-5 text-slate-600 flex items-center justify-center text-lg leading-none'
+          className='w-5 h-5 text-slate-600 flex items-center justify-center text-2xl leading-none -mt-px'
           aria-hidden='true'
         >
           ☾
diff --git a/client/app/hooks/useTheme.ts b/client/app/hooks/useTheme.ts
index 3cd7dee..3552723 100644
--- a/client/app/hooks/useTheme.ts
+++ b/client/app/hooks/useTheme.ts
@@ -4,17 +4,27 @@ type Theme = 'light' | 'dark';
 
 const STORAGE_KEY = 'red-tetris-theme';
 
-function getInitialTheme(): Theme {
-  if (typeof window === 'undefined') return 'dark';
+function resolveClientTheme(): Theme {
   const stored = localStorage.getItem(STORAGE_KEY);
   if (stored === 'light' || stored === 'dark') return stored;
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 }
 
 export function useTheme() {
-  const [theme, setTheme] = useState<Theme>(getInitialTheme);
+  const [theme, setTheme] = useState<Theme>('dark');
+  const [isHydrated, setIsHydrated] = useState(false);
 
   useEffect(() => {
+    try {
+      setTheme(resolveClientTheme());
+    } finally {
+      setIsHydrated(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!isHydrated) return;
+
     const root = document.documentElement;
     if (theme === 'dark') {
       root.classList.add('dark');
@@ -22,9 +32,9 @@ export function useTheme() {
       root.classList.remove('dark');
     }
     localStorage.setItem(STORAGE_KEY, theme);
-  }, [theme]);
+  }, [theme, isHydrated]);
 
   const toggle = () => setTheme((prev) => (prev === 'dark' ? 'light' : 'dark'));
 
-  return { theme, toggle } as const;
+  return { theme, toggle, isHydrated } as const;
 }
diff --git a/client/app/root.tsx b/client/app/root.tsx
index 3a65103..2f91d60 100644
--- a/client/app/root.tsx
+++ b/client/app/root.tsx
@@ -32,14 +32,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
         />
         <Meta />
         <Links />
-        <script
-          dangerouslySetInnerHTML={{
-            __html:
-              "(function(){try{var t=localStorage.getItem('red-tetris-theme');if(t==='dark'||(!t&&window.matchMedia('(prefers-color-scheme:dark)').matches)){document.documentElement.classList.add('dark')}}catch(e){}})()",
-          }}
-        />
       </head>
-      <body>
+      <body suppressHydrationWarning>
         {children}
         <ScrollRestoration />
         <Scripts />
@@ -51,14 +45,16 @@ export function Layout({ children }: { children: React.ReactNode }) {
 export default function App() {
   const navigation = useNavigation();
   const isNavigating = navigation.state === 'loading';
-  const { theme, toggle } = useTheme();
+  const { theme, toggle, isHydrated } = useTheme();
 
   return (
     <Provider store={store}>
-      <ThemeToggle
-        theme={theme}
-        toggle={toggle}
-      />
+      {isHydrated && (
+        <ThemeToggle
+          theme={theme}
+          toggle={toggle}
+        />
+      )}
       <Outlet />
       {isNavigating && <LoadingOverlay />}
     </Provider>
diff --git a/client/app/routes.ts b/client/app/routes.ts
index 7226c83..1c361b1 100644
--- a/client/app/routes.ts
+++ b/client/app/routes.ts
@@ -1,6 +1,7 @@
 import { type RouteConfig, index, route } from '@react-router/dev/routes';
 
 export default [
+  route('.well-known/appspecific/com.chrome.devtools.json', 'routes/chrome-devtools.tsx'),
   index('routes/home.tsx'),
   route('login', 'routes/login.tsx'),
   route('register', 'routes/register.tsx'),
diff --git a/client/app/routes/chrome-devtools.tsx b/client/app/routes/chrome-devtools.tsx
new file mode 100644
index 0000000..8444757
--- /dev/null
+++ b/client/app/routes/chrome-devtools.tsx
@@ -0,0 +1,7 @@
+export function loader() {
+  return new Response(null, { status: 204 });
+}
+
+export default function ChromeDevtoolsProbe() {
+  return null;
+}
diff --git a/client/tests/chromeDevtoolsRoute.test.tsx b/client/tests/chromeDevtoolsRoute.test.tsx
new file mode 100644
index 0000000..112204c
--- /dev/null
+++ b/client/tests/chromeDevtoolsRoute.test.tsx
@@ -0,0 +1,19 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import ChromeDevtoolsProbe, { loader } from '~/routes/chrome-devtools';
+
+describe('chrome-devtools route', () => {
+  it('returns 204 from loader', () => {
+    const response = loader();
+
+    expect(response).toBeInstanceOf(Response);
+    expect(response.status).toBe(204);
+  });
+
+  it('renders null component', () => {
+    const { container } = render(<ChromeDevtoolsProbe />);
+
+    expect(container.firstChild).toBeNull();
+  });
+});

From 7cb909fa9ba082870bed21dfc2d2ad6eec255976 Mon Sep 17 00:00:00 2001
From: Timofey Kafanov <tim.kafanov@gmail.com>
Date: Fri, 13 Mar 2026 09:35:59 +0000
Subject: [PATCH 7/8] feat: update CLIENT_URL and Docker run port to 3001 for
 consistency across configurations

---
 .env.example          |  2 +-
 client/README.md      |  2 +-
 client/package.json   |  2 +-
 client/vite.config.ts | 22 ++--------------------
 server/app.ts         | 28 +++-------------------------
 5 files changed, 8 insertions(+), 48 deletions(-)

diff --git a/.env.example b/.env.example
index 5ea5f59..7f11e18 100644
--- a/.env.example
+++ b/.env.example
@@ -7,7 +7,7 @@ DB_PORT=3306
 DB_PASSWORD_TEST=app_pw_change_me
 DB_NAME_TEST=red_tetris_test
 
-CLIENT_URL=http://localhost:3000,http://127.0.0.1:3000
+CLIENT_URL=http://localhost:3001,http://127.0.0.1:3001
 CLIENT_PORT=3001
 
 # Client Configuration
diff --git a/client/README.md b/client/README.md
index 5c4780a..eb5b276 100644
--- a/client/README.md
+++ b/client/README.md
@@ -52,7 +52,7 @@ To build and run using Docker:
 docker build -t my-app .
 
 # Run the container
-docker run -p 3000:3000 my-app
+docker run -p 3001:3001 my-app
 ```
 
 The containerized application can be deployed to any platform that supports Docker, including:
diff --git a/client/package.json b/client/package.json
index 073af9d..7beb510 100644
--- a/client/package.json
+++ b/client/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "dev": "sh -c 'react-router dev --port ${CLIENT_PORT:-3001} --host 0.0.0.0'",
     "build": "react-router build",
-    "start": "react-router-serve build/server/index.js",
+    "start": "sh -c 'PORT=${CLIENT_PORT:-3001} HOST=0.0.0.0 react-router-serve build/server/index.js'",
     "lint": "eslint . --ext js,jsx,ts,tsx --ignore-pattern .react-router --ignore-pattern build --ignore-pattern node_modules --ignore-pattern coverage --fix",
     "lint:check": "eslint . --ext js,jsx,ts,tsx --ignore-pattern .react-router --ignore-pattern build --ignore-pattern node_modules --ignore-pattern coverage",
     "prettier": "prettier \"**/*.{js,jsx,ts,tsx,json,css,md}\" --ignore-path ../.prettierignore --write",
diff --git a/client/vite.config.ts b/client/vite.config.ts
index 9c7fa94..5fee987 100644
--- a/client/vite.config.ts
+++ b/client/vite.config.ts
@@ -1,30 +1,15 @@
 import { reactRouter } from '@react-router/dev/vite';
 import { sentryVitePlugin } from '@sentry/vite-plugin';
 import tailwindcss from '@tailwindcss/vite';
-import os from 'os';
 import { defineConfig } from 'vite';
 import tsconfigPaths from 'vite-tsconfig-paths';
 
-// Helper function to get the first network IP
-function getNetworkIP() {
-  const interfaces = os.networkInterfaces();
-
-  for (const name of Object.keys(interfaces)) {
-    for (const networkInterface of interfaces[name]) {
-      if (networkInterface.family === 'IPv4' && !networkInterface.internal) {
-        return networkInterface.address;
-      }
-    }
-  }
-  return 'localhost';
-}
-
 // Dynamic server URL based on environment
 const serverPort = process.env.SERVER_PORT ?? '3002';
 const clientPort = parseInt(process.env.CLIENT_PORT ?? '3001', 10);
 const serverUrl =
   process.env.VITE_SERVER_URL === 'auto'
-    ? `http://${getNetworkIP()}:${serverPort}`
+    ? `http://localhost:${serverPort}`
     : (process.env.VITE_SERVER_URL ?? `http://localhost:${serverPort}`);
 
 export default defineConfig({
@@ -37,10 +22,7 @@ export default defineConfig({
 
   envDir: '..',
 
-  server: {
-    host: '0.0.0.0', // Allow external connections
-    port: clientPort,
-  },
+  server: { host: '0.0.0.0', port: clientPort },
 
   define: { 'import.meta.env.VITE_SERVER_URL': JSON.stringify(serverUrl) },
 
diff --git a/server/app.ts b/server/app.ts
index cf947de..e7b91ea 100644
--- a/server/app.ts
+++ b/server/app.ts
@@ -19,39 +19,17 @@ import { logDbError, logger } from './utils/logger';
 
 dotenv.config({ path: path.resolve(process.cwd(), '..', '.env') });
 
-import os from 'os';
-
 const app = express();
 const server = http.createServer(app);
 
-// Helper function to get network IPs
-function getNetworkIPs(): string[] {
-  const interfaces = os.networkInterfaces();
-  const ips: string[] = [];
-
-  for (const name of Object.keys(interfaces)) {
-    for (const networkInterface of interfaces[name] ?? []) {
-      if (networkInterface.family === 'IPv4' && !networkInterface.internal) {
-        ips.push(networkInterface.address);
-      }
-    }
-  }
-  return ips;
-}
-
-// Dynamic CORS origins - include current network IPs
+// Localhost-only CORS origins
 const clientPort = process.env.CLIENT_PORT ?? '3001';
-const clientUrlsRaw = process.env.CLIENT_URL ?? `http://localhost:${clientPort}`;
-const baseOrigins = clientUrlsRaw
+const clientUrlsRaw = process.env.CLIENT_URL ?? `http://localhost:${clientPort},http://127.0.0.1:${clientPort}`;
+const allowedOrigins = clientUrlsRaw
   .split(',')
   .map((s) => s.trim())
   .filter(Boolean);
 
-// Add current network IPs dynamically
-const networkIPs = getNetworkIPs();
-const dynamicOrigins = networkIPs.map((ip) => `http://${ip}:${clientPort}`);
-const allowedOrigins = [...baseOrigins, ...dynamicOrigins];
-
 const io = new IOServer<ClientToServerEvents, ServerToClientEvents, ServerToClientEvents, SocketData>(server, {
   cors: { origin: allowedOrigins, credentials: true },
 });

From 3462ccc3104a72dbe39440b882511c63d9503906 Mon Sep 17 00:00:00 2001
From: Timofey Kafanov <tim.kafanov@gmail.com>
Date: Fri, 13 Mar 2026 09:49:02 +0000
Subject: [PATCH 8/8] test: add unit tests for ErrorButton component to
 validate rendering and error handling

---
 client/tests/ErrorButton.test.tsx | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 client/tests/ErrorButton.test.tsx

diff --git a/client/tests/ErrorButton.test.tsx b/client/tests/ErrorButton.test.tsx
new file mode 100644
index 0000000..c14eff8
--- /dev/null
+++ b/client/tests/ErrorButton.test.tsx
@@ -0,0 +1,31 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import ErrorButton from '~/components/ErrorButton';
+
+describe('ErrorButton', () => {
+  it('renders button text', () => {
+    render(<ErrorButton />);
+    expect(screen.getByRole('button', { name: 'Break the world' })).toBeInTheDocument();
+  });
+
+  it('includes the red button styling classes', () => {
+    render(<ErrorButton />);
+    const button = screen.getByRole('button', { name: 'Break the world' });
+
+    expect(button.className).toContain('bg-red-600');
+    expect(button.className).toContain('hover:bg-red-500');
+  });
+
+  it('throws the expected error when clicked', () => {
+    const element = ErrorButton();
+    const { onClick } = element.props as { onClick?: () => void };
+
+    expect(onClick).toBeTypeOf('function');
+
+    if (!onClick) {
+      throw new Error('Expected onClick handler to be defined');
+    }
+
+    expect(() => onClick()).toThrowError('This is a test error from the ErrorButton component');
+  });
+});