feat(spa): keep player in sync across next-round and document issue-180 flow

frontend/angular/src/app/features/player/player-shell.component.ts

@@ -107,6 +107,7 @@ export class PlayerShellComponent implements OnInit, OnDestroy {
   private readonly sessionContextStore = createSessionContextStore(resolveLocalStorage());
   private readonly controller = createVerticalSliceController(createApiClient(), this.sessionContextStore);
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private stateSyncTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor() {
     if (typeof navigator !== 'undefined' && !navigator.onLine) {
@@ -145,6 +146,7 @@ export class PlayerShellComponent implements OnInit, OnDestroy {
       window.removeEventListener('offline', this.handleOffline);
     }
     this.clearReconnectTimer();
+    this.clearStateSyncTimer();
   }
 
   private readonly handleOnline = (): void => {
@@ -155,6 +157,7 @@ export class PlayerShellComponent implements OnInit, OnDestroy {
   private readonly handleOffline = (): void => {
     this.connectionState = 'offline';
     this.clearReconnectTimer();
+    this.clearStateSyncTimer();
   };
 
   private clearReconnectTimer(): void {
@@ -164,6 +167,34 @@ export class PlayerShellComponent implements OnInit, OnDestroy {
     }
   }
 
+  private clearStateSyncTimer(): void {
+    if (this.stateSyncTimer) {
+      clearTimeout(this.stateSyncTimer);
+      this.stateSyncTimer = null;
+    }
+  }
+
+  private scheduleStateSync(): void {
+    this.clearStateSyncTimer();
+
+    if (!this.sessionCode.trim() || this.connectionState !== 'online' || !this.session) {
+      return;
+    }
+
+    if (this.session.session.status === 'finished') {
+      return;
+    }
+
+    this.stateSyncTimer = setTimeout(() => {
+      this.stateSyncTimer = null;
+      if (this.loading || this.connectionState !== 'online') {
+        this.scheduleStateSync();
+        return;
+      }
+      void this.refreshSession();
+    }, 3000);
+  }
+
   get loadingMessage(): string {
     switch (this.loadingTransition) {
       case 'join':
@@ -192,9 +223,12 @@ export class PlayerShellComponent implements OnInit, OnDestroy {
   private markOnline(): void {
     this.connectionState = 'online';
     this.clearReconnectTimer();
+    this.scheduleStateSync();
   }
 
   private markConnectionIssue(error: unknown): void {
+    this.clearStateSyncTimer();
+
     if (typeof navigator !== 'undefined' && !navigator.onLine) {
       this.connectionState = 'offline';
       return;