@djangocfg/layouts 2.1.601 → 2.1.603

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.601",
+  "version": "2.1.603",
   "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.601",
-    "@djangocfg/api": "^2.1.601",
-    "@djangocfg/devtools": "^2.1.601",
-    "@djangocfg/i18n": "^2.1.601",
-    "@djangocfg/ui-core": "^2.1.601",
+    "@djangocfg/analytics": "^2.1.603",
+    "@djangocfg/api": "^2.1.603",
+    "@djangocfg/devtools": "^2.1.603",
+    "@djangocfg/i18n": "^2.1.603",
+    "@djangocfg/ui-core": "^2.1.603",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.601",
-    "@djangocfg/api": "^2.1.601",
-    "@djangocfg/devtools": "^2.1.601",
-    "@djangocfg/i18n": "^2.1.601",
-    "@djangocfg/typescript-config": "^2.1.601",
-    "@djangocfg/ui-core": "^2.1.601",
+    "@djangocfg/analytics": "^2.1.603",
+    "@djangocfg/api": "^2.1.603",
+    "@djangocfg/devtools": "^2.1.603",
+    "@djangocfg/i18n": "^2.1.603",
+    "@djangocfg/typescript-config": "^2.1.603",
+    "@djangocfg/ui-core": "^2.1.603",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/components/errors/ErrorsTracker/components/ErrorButtons.tsx

@@ -81,7 +81,7 @@ export function ErrorButtons({ detail }: ErrorButtonsProps) {
         size="sm"
         variant="secondary"
         onClick={handleCopyError}
-        className="h-8 text-xs bg-background hover:bg-background/80 text-foreground border border-border gap-1.5"
+        className="text-xs bg-background hover:bg-background/80 text-foreground border border-border gap-1.5"
       >
         <Copy className="h-3.5 w-3.5" />
         Copy Error
@@ -92,7 +92,7 @@ export function ErrorButtons({ detail }: ErrorButtonsProps) {
           size="sm"
           variant="secondary"
           onClick={handleCopyCurl}
-          className="h-8 text-xs bg-background hover:bg-background/80 text-foreground border border-border gap-1.5"
+          className="text-xs bg-background hover:bg-background/80 text-foreground border border-border gap-1.5"
         >
           <Terminal className="h-3.5 w-3.5" />
           Copy cURL

package/src/layouts/AuthLayout/README.md

@@ -278,6 +278,28 @@ calls and navigations for `play` assertions. Pair it with
 parameters in the address bar and the stored state in `sessionStorage`
 (`seedOAuthBrowser`), as a real return leaves them.
 
+## A failed provider sign-in
+
+A provider round trip that does not finish never blocks the page. `OAuthCallback`
+strips `?provider=&code=&state=` from the address bar, puts the failure in
+`AuthFormContext.oauthNotice`, and the visitor lands on the normal sign-in form
+with a calm inline notice (`OAuthNotice`, `role="status"`) above the buttons. Only
+the wait for the code exchange covers the page.
+
+| Failure | The form says | One next step |
+|---|---|---|
+| Cancelled on the provider's page | nothing | the form itself |
+| `link_not_allowed` (staff account) | "Use the email code for this address" + one sentence | **Continue with email**: closes the notice, focuses the email field |
+| Expired or foreign state, exchange or token failure, provider down, unknown | one short sentence | **Try {provider} again** (email when the provider has no button here) |
+| Email missing or unverified, domain refused | one sentence | **Continue with email** |
+| Account disabled, rate limited | one sentence | none |
+
+The notice closes with its button or Escape. The code-to-copy table
+(`OAUTH_CODE_TO_KEY`) and the code-to-next-step table live together in
+`components/oauth/oauthNoticeCopy.ts`; copy is `layouts.auth.oauth.error.*` and
+`layouts.auth.oauth.notice.*` in `@djangocfg/i18n`. The strict-mode guard is
+unchanged: one attempt per page load.
+
 ## Errors
 
 The form never shows a raw transport string. `@djangocfg/api`'s

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

@@ -1,21 +1,19 @@
 'use client';
 
-import { AlertCircle, Loader2 } from 'lucide-react';
+import { Loader2 } from 'lucide-react';
 import { useSearchParams } from 'next/navigation';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 
 import {
-    beginTwoFactorChallenge, clearOAuthAttempt, isOAuthProviderId, type OAuthFailureCode, useAuth,
-    useOAuthLogin
+    beginTwoFactorChallenge, clearOAuthAttempt, isOAuthProviderId, type OAuthFailureCode, useOAuthLogin
 } from '@djangocfg/api/auth';
 import { useAppT } from '@djangocfg/i18n';
-import {
-    Card, CardContent, CardDescription, CardHeader, CardTitle
-} from '@djangocfg/ui-core/components';
+import { Card, CardDescription, CardHeader, CardTitle } from '@djangocfg/ui-core/components';
 
 import { useAuthFormContext } from '../../context';
 import { readOAuthCallback, stripOAuthCallbackParams } from './oauthCallbackParams';
 import { useOAuthErrorText } from './oauthErrors';
+import { describeOAuthFailure } from './oauthNoticeCopy';
 
 export interface OAuthCallbackProps {
   /** `user` is the provider callback's user payload, untyped upstream — narrow it before reading fields. */
@@ -24,13 +22,7 @@ export interface OAuthCallbackProps {
   redirectUrl?: string;
 }
 
-type CallbackStatus = 'idle' | 'processing' | 'error' | 'challenge';
-
-interface Failure {
-  message: string;
-  /** Google refused to open on its own page, which we never see; point at the likely cause. */
-  browserHint: boolean;
-}
+type CallbackStatus = 'idle' | 'processing' | 'challenge';
 
 /**
  * Finishes a provider sign-in on the page the provider returned to.
@@ -38,8 +30,9 @@ interface Failure {
  * Mounted by `AuthLayout`; it renders nothing unless the URL carries
  * `?provider=<id>`. It reads the URL once, strips the single-use parameters
  * from the address bar, then either exchanges the code (the stored `state`
- * must match, see `useOAuthLogin`) or shows why there is no code (Cancel,
- * a provider error, an unknown provider).
+ * must match, see `useOAuthLogin`) or hands the failure (Cancel, a provider
+ * error, an unknown provider) to the sign-in form as a dismissible notice.
+ * The page is never blocked by a failure: the visitor lands on the form.
  *
  * Success hands over to the layout's success screen, which consumes the saved
  * return URL; this component never navigates itself.
@@ -49,14 +42,12 @@ interface Failure {
  */
 function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProps) {
   const searchParams = useSearchParams();
-  const { routes } = useAuth();
-  const { setStep } = useAuthFormContext();
+  const { setStep, setOAuthNotice } = useAuthFormContext();
   const t = useAppT();
   const errorText = useOAuthErrorText();
 
   const [status, setStatus] = useState<CallbackStatus>('idle');
   const [provider, setProvider] = useState<string | null>(null);
-  const [failure, setFailure] = useState<Failure | null>(null);
 
   // One attempt per page load: strict mode runs effects twice, and the
   // stripped URL re-renders this component with no provider left to read.
@@ -64,15 +55,12 @@ function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProp
 
   const fail = useCallback(
     (providerId: string, code: OAuthFailureCode | undefined, message?: string) => {
-      const text = errorText(code, message);
-      setFailure({
-        message: text,
-        browserHint: providerId === 'google' && (code === undefined || code === 'server_error'),
-      });
-      setStatus('error');
-      onError?.(text);
+      // Cancel is not an error: the visitor is simply back at the form.
+      if (describeOAuthFailure(code)) setOAuthNotice({ provider: providerId, code });
+      setStatus('idle');
+      onError?.(errorText(code, message));
     },
-    [errorText, onError],
+    [errorText, setOAuthNotice, onError],
   );
 
   const failRef = useRef(fail);
@@ -115,47 +103,24 @@ function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProp
     void complete(intent.provider, intent.code, intent.state);
   }, [searchParams, complete, fail]);
 
-  if (status === 'idle' || status === 'challenge') return null;
+  if (status !== 'processing') return null;
 
-  // Success is the layout's success screen (setStep('success')); this overlay
-  // only covers waiting and failing.
+  // Success is the layout's success screen (setStep('success')), a failure is
+  // the notice on the form; this overlay covers only the wait for the exchange.
   return (
     <div className="fixed inset-0 bg-background/80 backdrop-blur-sm z-50 flex items-center justify-center">
       <Card className="w-full max-w-md mx-4 shadow-lg">
         <CardHeader className="text-center">
-          {status === 'processing' && (
-            <div role="status" aria-live="polite">
-              <div className="mx-auto w-12 h-12 bg-primary/10 rounded-full flex items-center justify-center mb-4">
-                <Loader2 className="w-6 h-6 text-primary animate-spin" aria-hidden="true" />
-              </div>
-              <CardTitle>{t('layouts.auth.oauth.signingIn')}</CardTitle>
-              <CardDescription>
-                {t('layouts.auth.oauth.signingInBody', { provider: providerLabel(provider) })}
-              </CardDescription>
+          <div role="status" aria-live="polite">
+            <div className="mx-auto w-12 h-12 bg-primary/10 rounded-full flex items-center justify-center mb-4">
+              <Loader2 className="w-6 h-6 text-primary animate-spin" aria-hidden="true" />
             </div>
-          )}
-
-          {status === 'error' && (
-            <div role="alert">
-              <div className="mx-auto w-12 h-12 bg-destructive/10 rounded-full flex items-center justify-center mb-4">
-                <AlertCircle className="w-6 h-6 text-destructive" aria-hidden="true" />
-              </div>
-              <CardTitle>{t('layouts.auth.oauth.failedTitle')}</CardTitle>
-              <CardDescription className="text-destructive">{failure?.message}</CardDescription>
-              {failure?.browserHint && (
-                <CardDescription className="mt-2">{t('layouts.auth.oauth.browserHint')}</CardDescription>
-              )}
-            </div>
-          )}
+            <CardTitle>{t('layouts.auth.oauth.signingIn')}</CardTitle>
+            <CardDescription>
+              {t('layouts.auth.oauth.signingInBody', { provider: providerLabel(provider) })}
+            </CardDescription>
+          </div>
         </CardHeader>
-
-        {status === 'error' && (
-          <CardContent className="text-center">
-            <a href={routes.auth} className="text-primary hover:underline text-sm" autoFocus>
-              {t('layouts.auth.oauth.tryAgain')}
-            </a>
-          </CardContent>
-        )}
       </Card>
     </div>
   );

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

@@ -0,0 +1,94 @@
+'use client';
+
+import { Info, X } from 'lucide-react';
+import React, { memo, useCallback, useEffect } from 'react';
+
+import { isOAuthProviderId, useOAuthLogin } from '@djangocfg/api/auth';
+import { useAppT } from '@djangocfg/i18n';
+import { Alert, AlertDescription, AlertTitle, Button } from '@djangocfg/ui-core/components';
+
+import type { OAuthFailure } from '../../types';
+import { describeOAuthFailure } from './oauthNoticeCopy';
+
+export interface OAuthNoticeProps {
+  failure: OAuthFailure;
+  sourceUrl?: string;
+  /** Closes the notice (button or Escape). */
+  onDismiss: () => void;
+  /** Takes the visitor to the email field; the notice closes with it. */
+  onUseEmail: () => void;
+}
+
+/** Brand names are not translated; an id we do not know is shown as it came. */
+const providerLabel = (id: string): string => {
+  if (id === 'github') return 'GitHub';
+  if (id === 'google') return 'Google';
+  return id;
+};
+
+/**
+ * What the sign-in form says after a provider round trip failed: one calm
+ * sentence, at most one next step, and a way to close it. Not a dialog: the
+ * form underneath stays usable and focus stays where it was.
+ *
+ * `role="status"` (polite): the visitor did nothing wrong, so it informs
+ * without interrupting. Renders nothing for a cancelled sign-in.
+ */
+function OAuthNoticeRaw({ failure, sourceUrl, onDismiss, onUseEmail }: OAuthNoticeProps) {
+  const t = useAppT();
+  const copy = describeOAuthFailure(failure.code);
+  const provider = providerLabel(failure.provider);
+  const canRetry = isOAuthProviderId(failure.provider);
+
+  const { start, isLoading } = useOAuthLogin({ sourceUrl });
+  const handleRetry = useCallback(() => {
+    if (isOAuthProviderId(failure.provider)) void start(failure.provider);
+  }, [start, failure.provider]);
+
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') onDismiss();
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [onDismiss]);
+
+  if (!copy) return null;
+
+  // A retry for a provider this client has no button for would go nowhere: send the visitor to email instead.
+  const action = copy.action === 'retry' && !canRetry ? 'email' : copy.action;
+  const title = copy.titleKey ? t(copy.titleKey) : null;
+  const body = t(copy.bodyKey, { provider });
+
+  return (
+    <Alert role="status" className="auth-oauth-notice relative pr-10">
+      <Info className="h-4 w-4 text-muted-foreground" aria-hidden="true" />
+      <div>
+        {title && <AlertTitle>{title}</AlertTitle>}
+        <AlertDescription className="text-muted-foreground">{body}</AlertDescription>
+        {action === 'email' && (
+          <Button type="button" size="sm" className="mt-3" onClick={onUseEmail}>
+            {t('layouts.auth.oauth.notice.useEmail')}
+          </Button>
+        )}
+        {action === 'retry' && (
+          <Button type="button" size="sm" className="mt-3" disabled={isLoading} onClick={handleRetry}>
+            {t('layouts.auth.oauth.notice.retry', { provider })}
+          </Button>
+        )}
+      </div>
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon"
+        className="absolute right-1 top-1 h-8 w-8"
+        aria-label={t('layouts.auth.oauth.notice.dismiss')}
+        onClick={onDismiss}
+      >
+        <X className="h-4 w-4" aria-hidden="true" />
+      </Button>
+    </Alert>
+  );
+}
+
+export const OAuthNotice = memo(OAuthNoticeRaw);

package/src/layouts/AuthLayout/components/oauth/index.ts

@@ -1,3 +1,4 @@
 export { OAuthCallback, type OAuthCallbackProps } from './OAuthCallback';
 export { OAuthButtons, type OAuthButtonsProps } from './OAuthButtons';
 export { resolveOAuthProviders } from './oauthProviders';
+export { OAuthNotice, type OAuthNoticeProps } from './OAuthNotice';

package/src/layouts/AuthLayout/components/oauth/oauthErrors.ts

@@ -5,48 +5,7 @@ import { useCallback } from 'react';
 import type { OAuthFailureCode } from '@djangocfg/api/auth';
 import { useAppT } from '@djangocfg/i18n';
 
-/**
- * Copy for each failure code. Exhaustive on purpose: a code the backend adds
- * fails typecheck here until someone decides what to tell the visitor.
- */
-export const OAUTH_ERROR_KEYS = {
-  invalid_state: 'layouts.auth.oauth.error.invalid_state',
-  oauth_exchange_failed: 'layouts.auth.oauth.error.oauth_exchange_failed',
-  invalid_id_token: 'layouts.auth.oauth.error.invalid_id_token',
-  email_missing: 'layouts.auth.oauth.error.email_missing',
-  email_not_verified: 'layouts.auth.oauth.error.email_not_verified',
-  hosted_domain_not_allowed: 'layouts.auth.oauth.error.hosted_domain_not_allowed',
-  account_inactive: 'layouts.auth.oauth.error.account_inactive',
-  link_not_allowed: 'layouts.auth.oauth.error.link_not_allowed',
-  rate_limited: 'layouts.auth.oauth.error.rate_limited',
-  provider_unavailable: 'layouts.auth.oauth.error.provider_unavailable',
-  cancelled: 'layouts.auth.oauth.error.cancelled',
-  generic: 'layouts.auth.oauth.error.generic',
-} as const;
-
-type OAuthErrorKey = (typeof OAUTH_ERROR_KEYS)[keyof typeof OAUTH_ERROR_KEYS];
-
-/** Maps every failure code to one of the keys above. Configuration faults the visitor cannot fix read as "unavailable" or generic. */
-export const OAUTH_CODE_TO_KEY: Record<OAuthFailureCode, OAuthErrorKey> = {
-  invalid_state: OAUTH_ERROR_KEYS.invalid_state,
-  oauth_exchange_failed: OAUTH_ERROR_KEYS.oauth_exchange_failed,
-  invalid_id_token: OAUTH_ERROR_KEYS.invalid_id_token,
-  email_missing: OAUTH_ERROR_KEYS.email_missing,
-  email_not_verified: OAUTH_ERROR_KEYS.email_not_verified,
-  hosted_domain_not_allowed: OAUTH_ERROR_KEYS.hosted_domain_not_allowed,
-  account_inactive: OAUTH_ERROR_KEYS.account_inactive,
-  link_not_allowed: OAUTH_ERROR_KEYS.link_not_allowed,
-  rate_limited: OAUTH_ERROR_KEYS.rate_limited,
-  provider_unavailable: OAUTH_ERROR_KEYS.provider_unavailable,
-  cancelled: OAUTH_ERROR_KEYS.cancelled,
-  oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
-  github_oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
-  origin_not_allowed: OAUTH_ERROR_KEYS.generic,
-  missing_redirect_uri: OAUTH_ERROR_KEYS.generic,
-  server_error: OAUTH_ERROR_KEYS.generic,
-  not_found: OAUTH_ERROR_KEYS.generic,
-  unknown_provider: OAUTH_ERROR_KEYS.generic,
-};
+import { OAUTH_CODE_TO_KEY, OAUTH_ERROR_KEYS } from './oauthNoticeCopy';
 
 /**
  * The visitor-facing sentence for a failure: the translated copy of its code,

package/src/layouts/AuthLayout/components/oauth/oauthNoticeCopy.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { describeOAuthFailure } from './oauthNoticeCopy';
+
+describe('describeOAuthFailure', () => {
+  it('says nothing when the visitor cancelled', () => {
+    expect(describeOAuthFailure('cancelled')).toBeNull();
+  });
+
+  it('points a staff account at the email code, with a heading', () => {
+    expect(describeOAuthFailure('link_not_allowed')).toEqual({
+      titleKey: 'layouts.auth.oauth.notice.linkNotAllowedTitle',
+      bodyKey: 'layouts.auth.oauth.error.link_not_allowed',
+      action: 'email',
+    });
+  });
+
+  it('offers a retry where trying again can help', () => {
+    for (const code of ['invalid_state', 'oauth_exchange_failed', 'provider_unavailable', 'server_error'] as const) {
+      expect(describeOAuthFailure(code)?.action).toBe('retry');
+    }
+  });
+
+  it('offers nothing the visitor cannot act on', () => {
+    expect(describeOAuthFailure('account_inactive')?.action).toBe('none');
+    expect(describeOAuthFailure('rate_limited')?.action).toBe('none');
+  });
+
+  it('treats a missing code as the generic failure', () => {
+    expect(describeOAuthFailure(undefined)).toEqual({
+      titleKey: undefined,
+      bodyKey: 'layouts.auth.oauth.error.generic',
+      action: 'retry',
+    });
+  });
+});

package/src/layouts/AuthLayout/components/oauth/oauthNoticeCopy.ts

@@ -0,0 +1,86 @@
+import type { OAuthFailureCode } from '@djangocfg/api/auth';
+
+/**
+ * Copy for each failure code. Exhaustive on purpose: a code the backend adds
+ * fails typecheck here until someone decides what to tell the visitor.
+ */
+export const OAUTH_ERROR_KEYS = {
+  invalid_state: 'layouts.auth.oauth.error.invalid_state',
+  oauth_exchange_failed: 'layouts.auth.oauth.error.oauth_exchange_failed',
+  invalid_id_token: 'layouts.auth.oauth.error.invalid_id_token',
+  email_missing: 'layouts.auth.oauth.error.email_missing',
+  email_not_verified: 'layouts.auth.oauth.error.email_not_verified',
+  hosted_domain_not_allowed: 'layouts.auth.oauth.error.hosted_domain_not_allowed',
+  account_inactive: 'layouts.auth.oauth.error.account_inactive',
+  link_not_allowed: 'layouts.auth.oauth.error.link_not_allowed',
+  rate_limited: 'layouts.auth.oauth.error.rate_limited',
+  provider_unavailable: 'layouts.auth.oauth.error.provider_unavailable',
+  cancelled: 'layouts.auth.oauth.error.cancelled',
+  generic: 'layouts.auth.oauth.error.generic',
+} as const;
+
+export type OAuthErrorKey = (typeof OAUTH_ERROR_KEYS)[keyof typeof OAUTH_ERROR_KEYS];
+
+/** Maps every failure code to one of the keys above. Configuration faults the visitor cannot fix read as "unavailable" or generic. */
+export const OAUTH_CODE_TO_KEY: Record<OAuthFailureCode, OAuthErrorKey> = {
+  invalid_state: OAUTH_ERROR_KEYS.invalid_state,
+  oauth_exchange_failed: OAUTH_ERROR_KEYS.oauth_exchange_failed,
+  invalid_id_token: OAUTH_ERROR_KEYS.invalid_id_token,
+  email_missing: OAUTH_ERROR_KEYS.email_missing,
+  email_not_verified: OAUTH_ERROR_KEYS.email_not_verified,
+  hosted_domain_not_allowed: OAUTH_ERROR_KEYS.hosted_domain_not_allowed,
+  account_inactive: OAUTH_ERROR_KEYS.account_inactive,
+  link_not_allowed: OAUTH_ERROR_KEYS.link_not_allowed,
+  rate_limited: OAUTH_ERROR_KEYS.rate_limited,
+  provider_unavailable: OAUTH_ERROR_KEYS.provider_unavailable,
+  cancelled: OAUTH_ERROR_KEYS.cancelled,
+  oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
+  github_oauth_disabled: OAUTH_ERROR_KEYS.provider_unavailable,
+  origin_not_allowed: OAUTH_ERROR_KEYS.generic,
+  missing_redirect_uri: OAUTH_ERROR_KEYS.generic,
+  server_error: OAUTH_ERROR_KEYS.generic,
+  not_found: OAUTH_ERROR_KEYS.generic,
+  unknown_provider: OAUTH_ERROR_KEYS.generic,
+};
+
+/** The one next step a notice offers: reveal the email field, run the provider again, or nothing the visitor can do. */
+export type OAuthNoticeAction = 'email' | 'retry' | 'none';
+
+/** What the visitor does next, per copy key. A retry is only offered where trying again can change the outcome. */
+const ACTION_BY_KEY: Record<OAuthErrorKey, OAuthNoticeAction> = {
+  [OAUTH_ERROR_KEYS.invalid_state]: 'retry',
+  [OAUTH_ERROR_KEYS.oauth_exchange_failed]: 'retry',
+  [OAUTH_ERROR_KEYS.invalid_id_token]: 'retry',
+  [OAUTH_ERROR_KEYS.email_missing]: 'email',
+  [OAUTH_ERROR_KEYS.email_not_verified]: 'email',
+  [OAUTH_ERROR_KEYS.hosted_domain_not_allowed]: 'email',
+  [OAUTH_ERROR_KEYS.account_inactive]: 'none',
+  [OAUTH_ERROR_KEYS.link_not_allowed]: 'email',
+  [OAUTH_ERROR_KEYS.rate_limited]: 'none',
+  [OAUTH_ERROR_KEYS.provider_unavailable]: 'retry',
+  [OAUTH_ERROR_KEYS.cancelled]: 'none',
+  [OAUTH_ERROR_KEYS.generic]: 'retry',
+};
+
+export interface OAuthNoticeCopy {
+  /** Only the code that needs a heading has one; the rest are a single sentence. */
+  titleKey?: 'layouts.auth.oauth.notice.linkNotAllowedTitle';
+  bodyKey: OAuthErrorKey;
+  action: OAuthNoticeAction;
+}
+
+/**
+ * What the sign-in form tells a visitor whose provider round trip failed.
+ *
+ * `null` means "say nothing": the visitor cancelled on the provider's page and
+ * is back at the form they started from. An absent code is the unknown case.
+ */
+export const describeOAuthFailure = (code?: OAuthFailureCode | null): OAuthNoticeCopy | null => {
+  const bodyKey = code ? OAUTH_CODE_TO_KEY[code] : OAUTH_ERROR_KEYS.generic;
+  if (bodyKey === OAUTH_ERROR_KEYS.cancelled) return null;
+  return {
+    titleKey: bodyKey === OAUTH_ERROR_KEYS.link_not_allowed ? 'layouts.auth.oauth.notice.linkNotAllowedTitle' : undefined,
+    bodyKey,
+    action: ACTION_BY_KEY[bodyKey],
+  };
+};

package/src/layouts/AuthLayout/components/steps/IdentifierStep.tsx

@@ -1,13 +1,13 @@
 'use client';
 
-import React, { memo, useEffect, useMemo, useRef } from 'react';
+import React, { memo, useCallback, useEffect, useMemo, useRef } from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
 import { Checkbox, Input } from '@djangocfg/ui-core/components';
 
 import { useAuthLayoutContext } from '../../layoutContext';
 import { useAuthFormContext } from '../../context';
-import { OAuthButtons } from '../oauth';
+import { OAuthButtons, OAuthNotice } from '../oauth';
 import {
   AuthButton,
   AuthConsent,
@@ -46,6 +46,8 @@ function IdentifierStepRaw() {
     termsUrl,
     privacyUrl,
     oauth,
+    oauthNotice,
+    setOAuthNotice,
     sourceUrl,
     marketingConsent,
     marketingConsentConfig,
@@ -106,6 +108,13 @@ function IdentifierStepRaw() {
     }
   }, [oauth.isReady, hasOAuth]);
 
+  // The notice's one next step: close it and put the cursor in the email field.
+  const dismissNotice = useCallback(() => setOAuthNotice(null), [setOAuthNotice]);
+  const useEmail = useCallback(() => {
+    setOAuthNotice(null);
+    emailRef.current?.focus();
+  }, [setOAuthNotice]);
+
   return (
     <AuthContainer step="identifier">
       {!hideHeader && (
@@ -117,6 +126,10 @@ function IdentifierStepRaw() {
         />
       )}
 
+      {oauthNotice && (
+        <OAuthNotice failure={oauthNotice} sourceUrl={sourceUrl} onDismiss={dismissNotice} onUseEmail={useEmail} />
+      )}
+
       {hasOAuth && (
         <>
           <OAuthButtons

package/src/layouts/AuthLayout/context.tsx

@@ -1,11 +1,11 @@
 'use client';
 
-import React, { createContext, useContext, useMemo } from 'react';
+import React, { createContext, useContext, useMemo, useState } from 'react';
 
 import { useAuthForm, useOAuthProviders } from '@djangocfg/api/auth';
 
 import { resolveOAuthProviders } from './components/oauth/oauthProviders';
-import type { AuthFormContextType, AuthLayoutProps } from './types';
+import type { AuthFormContextType, AuthLayoutProps, OAuthFailure } from './types';
 
 // Exported so test/mock providers (storybook) can supply their own value
 // without re-implementing AuthFormProvider end-to-end.
@@ -48,6 +48,8 @@ export const AuthFormProvider: React.FC<AuthLayoutProps> = ({
     [serverProviders, oauthProviders, oauthReady],
   );
 
+  const [oauthNotice, setOAuthNotice] = useState<OAuthFailure | null>(null);
+
   // Use the auth form hook
 
   const authForm = useAuthForm({
@@ -72,6 +74,8 @@ export const AuthFormProvider: React.FC<AuthLayoutProps> = ({
       termsUrl,
       privacyUrl,
       oauth,
+      oauthNotice,
+      setOAuthNotice,
       logo,
       redirectUrl,
       // Renamed: `marketingConsent` (the name) is the checkbox STATE from the form hook.
@@ -84,6 +88,7 @@ export const AuthFormProvider: React.FC<AuthLayoutProps> = ({
       termsUrl,
       privacyUrl,
       oauth,
+      oauthNotice,
       logo,
       redirectUrl,
       marketingConsent,

package/src/layouts/AuthLayout/index.ts

@@ -38,6 +38,7 @@ export type {
   // Layout UI types (owned by this package)
   AuthLayoutConfig,
   AuthFormContextType,
+  OAuthFailure,
   AuthLayoutProps,
   AuthHelpProps,
   // Shell types

package/src/layouts/AuthLayout/types.ts

@@ -18,7 +18,7 @@ export type {
   UseAuthFormOptions,
 } from '@djangocfg/api/auth';
 
-import type { AuthFormReturn, OAuthProviderId } from '@djangocfg/api/auth';
+import type { AuthFormReturn, OAuthFailureCode, OAuthProviderId } from '@djangocfg/api/auth';
 
 import type { AuthBackgroundConfig, AuthShellVariant } from './shells';
 
@@ -93,6 +93,15 @@ export interface AuthFormContextType
     /** False only while the server's list is first loading. */
     isReady: boolean;
   };
+  /** The failed provider round trip the form should explain, until the visitor dismisses it. */
+  oauthNotice: OAuthFailure | null;
+  setOAuthNotice: (failure: OAuthFailure | null) => void;
+}
+
+/** A provider sign-in that did not finish. `code` is absent when the cause is unknown. */
+export interface OAuthFailure {
+  provider: string;
+  code?: OAuthFailureCode;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -31,6 +31,8 @@ import type { PrivateLayoutProps } from './types';
 
 export type {
   SidebarItem,
+  SidebarLinkItem,
+  SidebarSettingsItem,
   SidebarGroupConfig,
   SidebarConfig,
   HeaderConfig,