fix(#770): Stabilize user.roles reference in AuthProvider to prevent unnecessary router recreation (#771)

Author: paulushcgcj

frontend/src/context/auth/AuthProvider.tsx

@@ -10,6 +10,28 @@ import { signOutUrl } from '@/config/fam/config';
 import { env } from '@/env';
 import { navigateTo } from '@/utils/navigation';
 
+/**
+ * Preserves the existing roles array reference when the next auth user has the
+ * same effective role assignments, avoiding unnecessary downstream recomputation.
+ *
+ * @param previousUser The previously cached authenticated user.
+ * @param nextUser The next authenticated user produced from token refresh.
+ * @returns The next user, reusing the previous roles reference when safe.
+ */
+export const preserveRolesReference = (
+  previousUser: FamLoginUser | undefined,
+  nextUser: FamLoginUser | undefined,
+): FamLoginUser | undefined => {
+  if (!previousUser || !nextUser) return nextUser;
+  if (previousUser.roles === nextUser.roles) return nextUser;
+  if (!isEqual(previousUser.roles, nextUser.roles)) return nextUser;
+
+  return {
+    ...nextUser,
+    roles: previousUser.roles,
+  };
+};
+
 /**
  * Provides authenticated user state and auth actions to the application tree.
  *
@@ -47,7 +69,10 @@ export const AuthProvider = ({ children }: { children: ReactNode }) => {
       try {
         const idToken = await loadUserToken();
         const newUser = idToken ? parseToken(idToken) : undefined;
-        setUser((prev) => (isEqual(prev, newUser) ? prev : newUser));
+        setUser((prev) => {
+          if (isEqual(prev, newUser)) return prev;
+          return preserveRolesReference(prev, newUser);
+        });
       } catch {
         setUser(undefined);
         if (!silent) await signOut();

frontend/src/context/auth/AuthProvider.unit.test.tsx

@@ -3,7 +3,8 @@ import { render, waitFor, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeAll } from 'vitest';
 
 import { AuthContext } from './AuthContext';
-import { AuthProvider } from './AuthProvider';
+import { AuthProvider, preserveRolesReference } from './AuthProvider';
+import { Role, type FamLoginUser, type FamRole } from './types';
 
 import { jwtfy } from '@/config/tests/auth.helper';
 import { navigateTo } from '@/utils/navigation';
@@ -113,6 +114,7 @@ describe('AuthProvider (extra coverage)', () => {
       await waitFor(() => expect(context).toBeDefined());
       expect(context.userToken()).toBe('sometoken');
     });
+
   });
 
   describe('when VITE_MOCK_AUTH is true', () => {
@@ -165,3 +167,82 @@ describe('AuthProvider (extra coverage)', () => {
     });
   });
 });
+
+describe('preserveRolesReference', () => {
+  const mockRoles: FamRole[] = [{ role: Role.VIEWER, clients: ['100'] }];
+  const mockRoles2: FamRole[] = [{ role: Role.ADMIN, clients: ['200'] }];
+  const mockUser: FamLoginUser = {
+    userName: 'testuser',
+    displayName: 'Test User',
+    email: 'test@example.com',
+    roles: mockRoles,
+    privileges: {},
+  };
+
+  it('returns nextUser when previousUser is undefined', () => {
+    const nextUser = { ...mockUser, roles: mockRoles };
+    const result = preserveRolesReference(undefined, nextUser);
+    expect(result).toBe(nextUser);
+  });
+
+  it('returns nextUser when nextUser is undefined', () => {
+    const result = preserveRolesReference(mockUser, undefined);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns nextUser when both are undefined', () => {
+    const result = preserveRolesReference(undefined, undefined);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns nextUser when role content differs', () => {
+    const previousUser = { ...mockUser, roles: mockRoles };
+    const nextUser = { ...mockUser, roles: mockRoles2 };
+    const result = preserveRolesReference(previousUser, nextUser);
+    expect(result).toBe(nextUser);
+    expect(result?.roles).toBe(mockRoles2);
+  });
+
+  it('preserves previous roles reference when role content is equal but reference differs', () => {
+    const previousRoles: FamRole[] = [{ role: Role.VIEWER, clients: ['100'] }];
+    const nextRoles: FamRole[] = [{ role: Role.VIEWER, clients: ['100'] }];
+    const previousUser = { ...mockUser, roles: previousRoles };
+    const nextUser = { ...mockUser, roles: nextRoles };
+
+    const result = preserveRolesReference(previousUser, nextUser);
+
+    expect(result).toBeDefined();
+    expect(result?.roles).toBe(previousRoles);
+    expect(result?.roles).not.toBe(nextRoles);
+    expect(result?.userName).toBe(nextUser.userName);
+  });
+
+  it('returns nextUser unchanged when roles reference is already the same', () => {
+    const sharedRoles = mockRoles;
+    const previousUser = { ...mockUser, roles: sharedRoles };
+    const nextUser = { ...mockUser, roles: sharedRoles };
+
+    const result = preserveRolesReference(previousUser, nextUser);
+
+    expect(result).toBe(nextUser);
+  });
+
+  it('preserves roles while updating other user fields', () => {
+    const sharedRoles: FamRole[] = [{ role: Role.SUBMITTER, clients: ['300'] }];
+    const previousUser = {
+      ...mockUser,
+      roles: sharedRoles,
+      email: 'old@example.com',
+    };
+    const nextUser = {
+      ...mockUser,
+      roles: sharedRoles,
+      email: 'new@example.com',
+    };
+
+    const result = preserveRolesReference(previousUser, nextUser);
+
+    expect(result?.roles).toBe(sharedRoles);
+    expect(result?.email).toBe('new@example.com');
+  });
+});