docs(code): document websocket flow

app/static/app.js

@@ -16,6 +16,7 @@ let socket = null;
 let currentUser = '';
 let currentRoom = '';
 
+// Persist the last used identity locally so refreshing the page is convenient.
 usernameInput.value = localStorage.getItem('chat_username') || '';
 roomInput.value = localStorage.getItem('chat_room') || 'عمومی';
 
@@ -48,6 +49,8 @@ function formatTime(timestamp) {
   if (!timestamp) return '';
   const date = new Date(timestamp);
   if (Number.isNaN(date.getTime())) return '';
+
+  // The server stores UTC timestamps; the browser formats them for the user.
   return date.toLocaleTimeString('fa-IR', { hour: '2-digit', minute: '2-digit' });
 }
 
@@ -108,6 +111,7 @@ function connect() {
   const wsProtocol = window.location.protocol === 'https:' ? 'wss' : 'ws';
   const wsUrl = `${wsProtocol}://${window.location.host}/ws/${encodeURIComponent(currentRoom)}/${encodeURIComponent(currentUser)}`;
 
+  // Opening this object starts the HTTP Upgrade handshake automatically.
   socket = new WebSocket(wsUrl);
 
   socket.addEventListener('open', () => {
@@ -120,6 +124,7 @@ function connect() {
   socket.addEventListener('message', (event) => {
     const payload = JSON.parse(event.data);
 
+    // Presence messages update the sidebar; chat/system messages go to the feed.
     if (payload.type === 'presence') {
       updateUsers(payload.users || []);
       return;
@@ -159,6 +164,7 @@ messageForm.addEventListener('submit', (event) => {
   const content = messageInput.value.trim();
   if (!content || !socket || socket.readyState !== WebSocket.OPEN) return;
 
+  // The server accepts JSON messages and broadcasts the content to the room.
   socket.send(JSON.stringify({ content }));
   messageInput.value = '';
   messageInput.focus();

app/static/style.css

@@ -29,6 +29,7 @@ body {
   color: var(--text);
   background: var(--bg);
   direction: rtl;
+  /* The app shell owns scrolling so the page does not exceed the viewport. */
   overflow: hidden;
 }
 
@@ -98,6 +99,7 @@ h1 {
 }
 
 .layout {
+  /* Allows the chat and users panels to shrink and scroll inside the viewport. */
   min-height: 0;
   flex: 1;
   display: grid;
@@ -216,6 +218,7 @@ ul {
 
 #usersList {
   min-height: 0;
+  /* Long user lists scroll here instead of making the page taller. */
   overflow-y: auto;
 }
 
@@ -252,6 +255,7 @@ li {
   min-height: 0;
   flex: 1;
   padding: 18px;
+  /* Chat history scrolls inside the chat panel. */
   overflow-y: auto;
   display: flex;
   flex-direction: column;