@djangocfg/layouts 2.1.619 → 2.1.622

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.619",
+  "version": "2.1.622",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -91,11 +91,11 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.619",
-    "@djangocfg/api": "^2.1.619",
-    "@djangocfg/devtools": "^2.1.619",
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/analytics": "^2.1.622",
+    "@djangocfg/api": "^2.1.622",
+    "@djangocfg/devtools": "^2.1.622",
+    "@djangocfg/i18n": "^2.1.622",
+    "@djangocfg/ui-core": "^2.1.622",
     "@hookform/resolvers": "^5.2.2 || ^7.0.2",
     "consola": "^3.4.2",
     "lucide-react": "^1.68.0",
@@ -123,12 +123,12 @@
     "qrcode.react": "^4.2.0"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.619",
-    "@djangocfg/api": "^2.1.619",
-    "@djangocfg/devtools": "^2.1.619",
-    "@djangocfg/i18n": "^2.1.619",
-    "@djangocfg/typescript-config": "^2.1.619",
-    "@djangocfg/ui-core": "^2.1.619",
+    "@djangocfg/analytics": "^2.1.622",
+    "@djangocfg/api": "^2.1.622",
+    "@djangocfg/devtools": "^2.1.622",
+    "@djangocfg/i18n": "^2.1.622",
+    "@djangocfg/typescript-config": "^2.1.622",
+    "@djangocfg/ui-core": "^2.1.622",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^25.9.5",
     "@types/react": "19.3.0",

package/src/layouts/AuthLayout/components/oauth/OAuthSection.tsx

@@ -52,7 +52,12 @@ function OAuthSectionRaw({ sourceUrl, disabled, onError, onFocusEmail }: OAuthSe
           <AuthDivider />
         </>
       )}
-      {!oauth.isReady && <div className="auth-oauth-reserve" aria-hidden="true" />}
+      {!oauth.isReady && (
+        <div className="auth-oauth-reserve" aria-hidden="true">
+          <span className="auth-oauth-skeleton" />
+          <span className="auth-oauth-skeleton" />
+        </div>
+      )}
     </>
   );
 }

package/src/layouts/AuthLayout/styles/oauth.css

@@ -20,7 +20,28 @@
 /* Holds the room of two buttons, the gap and the divider while the server's
    provider list loads, so the email field does not jump when it arrives. */
 .auth-oauth-reserve {
-  height: calc(2 * var(--auth-oauth-height) + var(--auth-oauth-gap) + var(--auth-gap) + 1rem);
+  display: flex;
+  flex-direction: column;
+  gap: var(--auth-oauth-gap);
+  /* Two buttons plus the divider's room below them. */
+  padding-bottom: calc(var(--auth-gap) + 1rem);
+}
+
+/* A quiet placeholder of one provider button, so the held room reads as "loading", not as a hole. */
+.auth-oauth-skeleton {
+  display: block;
+  height: var(--auth-oauth-height);
+  border-radius: var(--auth-radius, 0.75rem);
+  background: color-mix(in srgb, var(--auth-muted, currentColor) 12%, transparent);
+  animation: auth-oauth-pulse 1.4s ease-in-out infinite;
+}
+
+@keyframes auth-oauth-pulse {
+  50% { opacity: 0.5; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .auth-oauth-skeleton { animation: none; }
 }
 
 /* The line for whoever deploys the site, under a notice about configuration. */

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -102,12 +102,14 @@ export function PrivateLayout({
 
   if (isLoading) {
     return (
+      // The auth gate covers the whole viewport: solid, above the chat dock (z-100), sheets, dialogs and popovers.
+      // Nothing behind it may show or take a click while the session is still being decided.
       <Preloader
         variant="fullscreen"
         text={loadingText}
         size="lg"
-        backdrop={true}
-        backdropOpacity={80}
+        backdrop={false}
+        className="z-[9996] bg-background"
       />
     );
   }

package/src/layouts/PrivateLayout/hooks/useAuthGuard.test.ts

@@ -0,0 +1,20 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { redirectLoopDetected, resetRedirectLoop } from './useAuthGuard';
+
+describe('guard redirect circuit breaker', () => {
+  beforeEach(resetRedirectLoop);
+
+  it('allows a few redirects', () => {
+    for (let i = 0; i < 5; i++) expect(redirectLoopDetected(1000 + i * 400)).toBe(false);
+  });
+
+  it('trips on the sixth redirect inside the window', () => {
+    for (let i = 0; i < 5; i++) redirectLoopDetected(1000 + i * 400);
+    expect(redirectLoopDetected(3500)).toBe(true);
+  });
+
+  it('forgets redirects older than the window (a slow, legitimate sequence never trips)', () => {
+    for (let i = 0; i < 20; i++) expect(redirectLoopDetected(i * 6000)).toBe(false);
+  });
+});

package/src/layouts/PrivateLayout/hooks/useAuthGuard.ts

@@ -9,15 +9,36 @@
 import { useEffect, useState } from 'react';
 import { useRouter } from 'next/navigation';
 
-import { auth } from '@djangocfg/api';
 import {
   useAuth,
   resolveGuardIsLoading,
   resolveGuardIsAuthenticated,
   shouldRedirectToAuth,
   isForbidden,
+  authTrace,
 } from '@djangocfg/api/auth';
 
+/**
+ * Circuit breaker. A redirect that never lands (the sign-in page sends the user straight back) would otherwise
+ * run forever and hide the cause. After LOOP_MAX redirects within LOOP_WINDOW_MS the guard stops redirecting,
+ * writes `guard.loop` to the auth trace and shows a message that names the way to read it.
+ */
+const LOOP_MAX = 5;
+const LOOP_WINDOW_MS = 5000;
+const redirectTimes: number[] = [];
+
+/** @internal exported for tests */
+export function resetRedirectLoop(): void {
+  redirectTimes.length = 0;
+}
+
+/** @internal exported for tests */
+export function redirectLoopDetected(now: number): boolean {
+  redirectTimes.push(now);
+  while (redirectTimes.length && now - (redirectTimes[0] ?? now) > LOOP_WINDOW_MS) redirectTimes.shift();
+  return redirectTimes.length > LOOP_MAX;
+}
+
 interface UseAuthGuardOptions {
   requireAuth?: boolean;
   /**
@@ -28,10 +49,8 @@ interface UseAuthGuardOptions {
   /** Explicit override; defaults to the app's resolved `useAuth().routes.auth`. */
   authPath?: string;
   /**
-   * Safety net: if auth is still "loading" this many ms after mount, stop
-   * waiting and let the guard decide from whatever token state we have. Prevents
-   * an endless preloader if AuthContext initialization ever wedges (a hung
-   * request, a CSP-swallowed response, an unresolved promise). Default 8s.
+   * @deprecated No effect. The provider owns the single safety timer (8 s), so
+   * `status` always leaves 'resolving'. Kept so existing callers still compile.
    */
   loadingTimeoutMs?: number;
 }
@@ -51,12 +70,15 @@ export function useAuthGuard({
   requireAuth = true,
   requireStaff = false,
   authPath,
-  loadingTimeoutMs = 8000,
 }: UseAuthGuardOptions): UseAuthGuardResult {
-  const { isAuthenticated, isLoading: authLoading, isAdminUser, saveRedirectUrl, routes } = useAuth();
+  const { status, isAdminUser, saveRedirectUrl, routes } = useAuth();
+  // One linear state decides everything: 'resolving' → spinner, 'authenticated' → render, 'anonymous' → redirect.
+  const isAuthenticated = status === 'authenticated';
+  const authLoading = status === 'resolving';
   const resolvedAuthPath = authPath ?? routes.auth;
   const router = useRouter();
   const [isRedirecting, setIsRedirecting] = useState(false);
+  const [looping, setLooping] = useState(false);
 
   // Auth state lives in the browser (storage), so the server always renders
   // unauthenticated → the preloader. Keep the first client render identical to
@@ -66,26 +88,14 @@ export function useAuthGuard({
   const [mounted, setMounted] = useState(false);
   useEffect(() => setMounted(true), []);
 
-  // Safety-net timeout: force auth to be considered "resolved" if it hasn't
-  // settled within loadingTimeoutMs, so the guard can act (render or redirect)
-  // instead of spinning forever. Only armed while actually loading.
-  const [authTimedOut, setAuthTimedOut] = useState(false);
-  useEffect(() => {
-    if (!mounted || !authLoading || authTimedOut) return;
-    const t = setTimeout(() => setAuthTimedOut(true), loadingTimeoutMs);
-    return () => clearTimeout(t);
-  }, [mounted, authLoading, authTimedOut, loadingTimeoutMs]);
-
   // Guard state derives from a single pure resolver (see @djangocfg/api/auth
   // utils/guard) so the "spinner vs redirect vs render" decision is unit-tested
   // in isolation and can't silently regress into the "stuck on Authenticating…"
   // state where a resolved-but-unauthenticated session never redirects.
-  // `authLoading` is forced false once the safety-net timeout fires.
-  const effectiveAuthLoading = authLoading && !authTimedOut;
   const guardState = {
     mounted,
     requireAuth,
-    authLoading: effectiveAuthLoading,
+    authLoading,
     isRedirecting,
     isAuthenticated,
     requireStaff,
@@ -93,19 +103,28 @@ export function useAuthGuard({
   };
 
   useEffect(() => {
-    // The React snapshot can still be the server's 'anonymous' while the store holds a live session (hydration, or a
-    // full-page load right after sign-in). Never redirect on that: the snapshot catches up and the effect re-runs.
-    if (shouldRedirectToAuth(guardState) && !auth.isAuthenticated()) {
+    if (shouldRedirectToAuth(guardState)) {
       const currentUrl = window.location.pathname + window.location.search;
+      if (redirectLoopDetected(Date.now())) {
+        authTrace('guard.loop', { from: window.location.pathname, to: resolvedAuthPath, status });
+        setLooping(true);
+        setIsRedirecting(true);
+        return;
+      }
+      authTrace('guard.redirect', { from: window.location.pathname, to: resolvedAuthPath });
       saveRedirectUrl(currentUrl);
       setIsRedirecting(true);
       router.push(resolvedAuthPath);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [mounted, requireAuth, isAuthenticated, effectiveAuthLoading, isRedirecting, router, saveRedirectUrl, resolvedAuthPath]);
+  }, [mounted, requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, resolvedAuthPath]);
 
   const isLoading = resolveGuardIsLoading(guardState);
-  const loadingText = isRedirecting ? 'Redirecting to login...' : 'Authenticating...';
+  const loadingText = looping
+    ? 'Sign-in loop stopped. Open the console and run __cfgAuth.dump()'
+    : isRedirecting
+      ? 'Redirecting to login...'
+      : 'Authenticating...';
 
   return {
     isLoading,

package/src/testing/MockAuthProvider.tsx

@@ -63,6 +63,7 @@ export const MockAuthProvider: React.FC<MockAuthProviderProps> = ({
   const value = useMemo<AuthContextType>(() => ({
     user,
     isLoading,
+    status: isLoading ? 'resolving' : (isAuthenticated ?? Boolean(user)) ? 'authenticated' : 'anonymous',
     isAuthenticated: isAuthenticated ?? Boolean(user),
     isAdminUser,
     routes: { auth: '/auth', defaultCallback: '/', defaultAuthCallback: '/auth', ...routes },