@godxjp/ui 31.2.0 → 31.3.0

package/dist/components/query/data-state.js

@@ -2,6 +2,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { AlertQueryError } from "../feedback/alert.js";
+import { useAuthExpiry } from "../feedback/auth-expiry.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { classifyQueryError } from "../../lib/query-error.js";
 function defaultIsEmpty(data) {
@@ -34,10 +35,18 @@ function DataState({
     }
     void query.refetch();
   }, [onRetry, query]);
+  const showingAuthError = query.isError && !query.isFetching && classifyQueryError(query.error).category === "auth";
+  const authExpiry = useAuthExpiry(showingAuthError, query.error);
   if (query.isPending && query.fetchStatus === "idle") return /* @__PURE__ */ jsx(Fragment, { children: prerequisite });
   if (query.isPending) return /* @__PURE__ */ jsx(Fragment, { children: skeleton });
   if (query.isError) {
     if (query.isFetching) return /* @__PURE__ */ jsx(Fragment, { children: skeleton });
+    if (authExpiry?.status === "redirecting") {
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        skeleton,
+        /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: t("query.authExpiry.redirecting") })
+      ] });
+    }
     if (errorRenderer) return /* @__PURE__ */ jsx(Fragment, { children: errorRenderer(query.error, retry) });
     const info = classifyQueryError(query.error);
     const canRetry = (info.category === "transient" || info.category === "unknown") && (info.retryable || showRetry || Boolean(onRetry));

package/dist/components/query/index.d.ts

@@ -1,6 +1,8 @@
 export { DataState } from "./data-state.js";
 export type { DataStateProp, DataStateProps } from "./data-state.js";
 export { AlertMutationFeedback } from "./mutation-feedback.js";
+export { AuthExpiryProvider } from "../feedback/auth-expiry.js";
+export type { AuthExpiryProviderProp, AuthExpiryProviderProps } from "../feedback/auth-expiry.js";
 export type { AlertMutationFeedbackProp, AlertMutationFeedbackProps } from "./mutation-feedback.js";
 export { ButtonRefetch } from "./query-refetch-button.js";
 export type { ButtonRefetchProp, ButtonRefetchProps } from "./query-refetch-button.js";

package/dist/components/query/index.js

@@ -1,10 +1,12 @@
 import { DataState } from "./data-state.js";
 import { AlertMutationFeedback } from "./mutation-feedback.js";
+import { AuthExpiryProvider } from "../feedback/auth-expiry.js";
 import { ButtonRefetch } from "./query-refetch-button.js";
 import { InfiniteQueryState, flattenItemPages } from "./infinite-query-state.js";
 import { classifyQueryError, isRetryableQueryError } from "../../lib/query-error.js";
 export {
   AlertMutationFeedback,
+  AuthExpiryProvider,
   ButtonRefetch,
   DataState,
   InfiniteQueryState,

package/dist/components/query/infinite-query-state.js

@@ -2,6 +2,7 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { AlertQueryError } from "../feedback/alert.js";
+import { useAuthExpiry } from "../feedback/auth-expiry.js";
 import { Button } from "../general/button.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { classifyQueryError } from "../../lib/query-error.js";
@@ -36,9 +37,17 @@ function InfiniteQueryState({
     }
     void query.refetch();
   }, [onRetry, query]);
+  const showingAuthError = query.isError && !(query.isFetching && !query.isFetchingNextPage) && classifyQueryError(query.error).category === "auth";
+  const authExpiry = useAuthExpiry(showingAuthError, query.error);
   if (query.isPending) return /* @__PURE__ */ jsx(Fragment, { children: skeleton });
   if (query.isError) {
     if (query.isFetching && !query.isFetchingNextPage) return /* @__PURE__ */ jsx(Fragment, { children: skeleton });
+    if (authExpiry?.status === "redirecting") {
+      return /* @__PURE__ */ jsxs(Fragment, { children: [
+        skeleton,
+        /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: t("query.authExpiry.redirecting") })
+      ] });
+    }
     if (errorRenderer) return /* @__PURE__ */ jsx(Fragment, { children: errorRenderer(query.error, retry) });
     const info = classifyQueryError(query.error);
     const canRetry = (info.category === "transient" || info.category === "unknown") && (info.retryable || showRetry || Boolean(onRetry));

package/dist/contracts/measurement.json

@@ -1,6 +1,6 @@
 {
   "$comment": "AUTO-GENERATED by scripts/gen-measurement-contract.mjs — do not edit. Read this instead of guessing: docs/MEASUREMENT-CONTRACT.md.",
-  "version": "31.2.0",
+  "version": "31.3.0",
   "targetSize": {
     "standard": "WCAG 2.2 SC 2.5.8 Target Size (Minimum), level AA — 24×24 CSS px",
     "min": 24,

package/dist/i18n/messages/en.json

@@ -635,6 +635,9 @@
       "action": {
         "signIn": "Sign in again"
       }
+    },
+    "authExpiry": {
+      "redirecting": "Your session has ended. Redirecting to sign-in…"
     }
   },
   "chart": {

package/dist/i18n/messages/ja.json

@@ -622,6 +622,9 @@
       "action": {
         "signIn": "再度サインイン"
       }
+    },
+    "authExpiry": {
+      "redirecting": "セッションの有効期限が切れました。サインイン画面へ移動しています…"
     }
   },
   "chart": {

package/dist/i18n/messages/vi.json

@@ -623,6 +623,9 @@
       "action": {
         "signIn": "Đăng nhập lại"
       }
+    },
+    "authExpiry": {
+      "redirecting": "Phiên đăng nhập đã hết hạn. Đang chuyển đến trang đăng nhập…"
     }
   },
   "chart": {

package/dist/props/components/feedback.prop.d.ts

@@ -71,6 +71,19 @@ export type AlertQueryErrorProp = {
     onAuthAction?: HandlerProp;
     className?: ClassNameProp;
 };
+/** @see AuthExpiryProvider — central, deduplicated handling of an expired session (gh#1022). */
+export type AuthExpiryProviderProp = {
+    /**
+     * Called ONCE when a query/mutation surface under the provider meets an auth-class error (401 /
+     * invalid or expired token); simultaneous 401s share one call, re-armed after every auth-errored
+     * view has gone. Typically redirects to the IdP with the current URL as the return target.
+     * Return a promise for a silent refresh: a rejection brings back the sign-in alert.
+     */
+    onAuthExpired: (context: {
+        error: unknown;
+    }) => void | Promise<void>;
+    children?: ChildrenProp;
+};
 /** @see Alert */
 export type AlertProp = React.HTMLAttributes<HTMLDivElement> & {
     variant?: AlertVariantProp;

package/dist/props/components/index.d.ts

@@ -3,7 +3,7 @@ export type { ButtonProp } from "./general.prop.js";
 export type { CommandProp, InputProp, TextareaProp, FormFieldProp, SearchInputProp, CheckboxProp, CheckboxGroupProp, ChoiceOptionProp, RadioProp, RadioGroupProp, SwitchProp, SliderProp, CalendarProp, DatePickerProp, TimePickerProp, ColorPickerProp, UploadProp, UploadFileItemProp, UploadVariantProp, TreeOptionProp, TreeFieldNamesProp, CascaderProp, TreeSelectProp, ShowCheckedStrategyProp, TransferProp, TransferItemProp, } from "./data-entry.prop.js";
 export type { AvatarProp, EmptyStateProp, DescriptionsProp, DescriptionsItemProp, BadgeProp, DataTableProp, QrCodeProp, } from "./data-display.prop.js";
 export type { ChartDatum, ChartSeriesProp, LineChartProp, BarChartProp, AreaChartProp, PieChartProp, } from "./charts.prop.js";
-export type { AlertQueryErrorProp, AlertProp, DialogProp, DialogContentProp, AlertTitleProp, AlertContentProp, AlertDescriptionProp, AlertActionsProp, SheetResponsiveProp, SkeletonRowsProp, } from "./feedback.prop.js";
+export type { AlertQueryErrorProp, AuthExpiryProviderProp, AlertProp, DialogProp, DialogContentProp, AlertTitleProp, AlertContentProp, AlertDescriptionProp, AlertActionsProp, SheetResponsiveProp, SkeletonRowsProp, } from "./feedback.prop.js";
 export type { DataStateProp, InfiniteQueryStateProp, InfiniteQueryHelpers, PrefetchLinkProp, } from "./query.prop.js";
 export type { DropdownMenuPlacementProp, DropdownMenuTriggerActionProp, PaginationProp, PaginationSizeProp, PaginationAlignProp, StepsProp, StepItemProp, StepStatusProp, StepsTypeProp, TabsProp, TabItemProp, TabsVariantProp, TabsPlacementProp, TabsExtraProp, TabsOnEditProp, } from "./navigation.prop.js";
 export type { AppProviderProp, AppContextValue, AppSettingKind, AppSettingPickerProp, AppSettingToggleKind, AppSettingToggleProp, ThemeScopeProp, } from "./app.prop.js";

package/dist/props/registry.d.ts

@@ -848,7 +848,7 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly vocabulary: readonly ["OrientationProp", {
             readonly field: "vertical";
             readonly local: true;
-            readonly reason: "antd's boolean spelling of orientation=\"vertical\"; orientation wins over it.";
+            readonly reason: 'antd\'s boolean spelling of orientation="vertical"; orientation wins over it.';
         }, {
             readonly field: "fullWidth";
             readonly local: true;
@@ -2415,6 +2415,15 @@ export declare const COMPONENT_PROP_REGISTRY: {
         readonly file: "components/query.prop.ts";
         readonly vocabulary: readonly [];
     };
+    readonly AuthExpiryProviderProp: {
+        readonly group: "feedback";
+        readonly file: "components/feedback.prop.ts";
+        readonly vocabulary: readonly [{
+            readonly field: "onAuthExpired";
+            readonly local: true;
+            readonly reason: "App-wide session-expiry callback receiving the triggering error; fired once per expiry (gh#1022).";
+        }, "ChildrenProp"];
+    };
     readonly AlertQueryErrorProp: {
         readonly group: "feedback";
         readonly file: "components/feedback.prop.ts";

package/dist/props/registry.js

@@ -2833,6 +2833,18 @@ const COMPONENT_PROP_REGISTRY = {
     vocabulary: ["HandlerProp"]
   },
   PrefetchLinkProp: { group: "query", file: "components/query.prop.ts", vocabulary: [] },
+  AuthExpiryProviderProp: {
+    group: "feedback",
+    file: "components/feedback.prop.ts",
+    vocabulary: [
+      {
+        field: "onAuthExpired",
+        local: true,
+        reason: "App-wide session-expiry callback receiving the triggering error; fired once per expiry (gh#1022)."
+      },
+      "ChildrenProp"
+    ]
+  },
   AlertQueryErrorProp: {
     group: "feedback",
     file: "components/feedback.prop.ts",

package/dist/styles/alert-layout.css

@@ -50,6 +50,10 @@
     color: hsl(var(--foreground));
   }
 
+  [data-slot="alert"][data-query-category="auth"] {
+    max-inline-size: var(--query-auth-alert-max-inline-size);
+  }
+
   [data-slot="alert"][data-variant="banner"] {
     border-radius: var(--banner-radius);
     border-block-start-width: 0;

package/dist/styles/layers.json

@@ -1,5 +1,5 @@
 {
-  "version": "31.2.0",
+  "version": "31.3.0",
   "generatedBy": "scripts/gen-style-layers.mjs — do not edit by hand; run `pnpm gen:style-layers`",
   "base": "base.css",
   "fonts": "fonts.css",
@@ -67,6 +67,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -74,6 +76,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -83,6 +86,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -99,6 +103,7 @@
         "shell-layout.css",
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -157,6 +162,9 @@
         "layout.css"
       ]
     },
+    "AuthExpiryProvider": {
+      "layers": []
+    },
     "AuthFooter": {
       "layers": [
         "shell-layout.css"
@@ -195,6 +203,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -241,6 +251,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -357,6 +369,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -390,6 +403,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -397,6 +412,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "table-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
@@ -423,6 +439,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -490,6 +507,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
       ]
@@ -498,6 +517,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -505,6 +526,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
       ]
@@ -516,6 +539,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
       ]
@@ -524,6 +549,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
       ]
@@ -549,6 +576,8 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
+        "dialog-layout.css",
         "alert-layout.css"
       ]
     },
@@ -649,6 +678,7 @@
         "shell-layout.css",
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"
@@ -666,6 +696,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css",
@@ -1103,6 +1134,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "data-display-layout.css",
@@ -1150,6 +1182,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "data-display-layout.css",
@@ -1162,6 +1195,7 @@
       "layers": [
         "layout.css",
         "control.css",
+        "text-layout.css",
         "dialog-layout.css",
         "alert-layout.css",
         "form-layout.css"

package/dist/tokens/components/feedback.css

@@ -133,6 +133,8 @@
   --query-load-more-space-block-start: var(--space-stack-md);
   --query-loading-more-space-block-start: var(--space-stack-sm);
 
+  --query-auth-alert-max-inline-size: 36rem;
+
   --tooltip-max-width: 20rem;
   --tooltip-space-inline: var(--space-2);
   --tooltip-space-block: var(--space-1);

package/docs/FRAME-COVERAGE-REPORT.md

@@ -3,8 +3,8 @@
 > Generated by `scripts/frame-coverage.mjs` (issue #163). Do not edit by hand — run `pnpm check:frame-coverage`.
 > Standard: [FRAME-COVERAGE-STANDARD.md](./FRAME-COVERAGE-STANDARD.md). A missing dimension is **UNTESTED**, never a pass.
 
-- Public components: **175**
-- With ≥1 frame: **152** · zero-frame: **23**
+- Public components: **176**
+- With ≥1 frame: **152** · zero-frame: **24**
 - Fully covered (every contract axis declared): **0**
 
 ## UNTESTED — no `/frame/**` route
@@ -20,6 +20,7 @@
 - [ ] `Paragraph`
 - [ ] `Link`
 - [ ] `ServiceCatalogCta`
+- [ ] `AuthExpiryProvider`
 - [ ] `SkeletonRows`
 - [ ] `OverlayPortalProvider`
 - [ ] `SkeletonDetail`
@@ -101,6 +102,7 @@ Legend: ✓ covered · N/A reasoned skip · · UNTESTED (blank cell = UNTESTED).
 | TimelineGrid | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | Table | ✓ | N/A | N/A | N/A | · | · | · | · | · | · |
 | DataState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
+| AuthExpiryProvider | **✗** | N/A | N/A | N/A | · | · | · | · | · | · |
 | InfiniteQueryState | ✓ | N/A | · | N/A | · | · | · | · | · | · |
 | Form | ✓ | ✓ | · | N/A | · | · | · | · | · | · |
 | FormField | ✓ | N/A | · | N/A | · | · | · | · | · | · |

package/docs/feedback/auth-expiry.tsx

@@ -0,0 +1,104 @@
+import { useState } from "react";
+import { QueryClient, QueryClientProvider, useMutation, useQuery } from "@tanstack/react-query";
+
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  DataTable,
+  type ColumnDef,
+} from "@godxjp/ui/data-display";
+import { SkeletonTable } from "@godxjp/ui/feedback";
+import { Button, Text } from "@godxjp/ui/general";
+import { useTranslation } from "@godxjp/ui/i18n";
+import { Flex, PageContainer } from "@godxjp/ui/layout";
+import { AlertMutationFeedback, AuthExpiryProvider, DataState } from "@godxjp/ui/query";
+
+/**
+ * AuthExpiryProvider · the app root owns an expired session (gh#1022). Every DataState /
+ * InfiniteQueryState / AlertMutationFeedback / AlertQueryError underneath calls `onAuthExpired`
+ * automatically, once for any number of simultaneous 401s, and shows a neutral pending state
+ * instead of an error alert. A real app redirects to its IdP here:
+ *   window.location.assign(`/auth/login?return_to=${encodeURIComponent(location.href)}`)
+ */
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+});
+
+type Member = { id: string; name: string };
+
+const expired = () => Object.assign(new Error("Access token expired"), { status: 401 });
+
+function MembersCard() {
+  const { t } = useTranslation();
+  const columns: ColumnDef<Member>[] = [
+    { key: "id", header: "ID" },
+    { key: "name", header: t("authExpiryDocs.nameColumn") },
+  ];
+  const query = useQuery<Member[]>({
+    queryKey: ["auth-expiry-members"],
+    queryFn: async () => {
+      throw expired();
+    },
+  });
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle level={2}>{t("authExpiryDocs.membersTitle")}</CardTitle>
+        <CardDescription>A 401 keeps the skeleton and announces the redirect.</CardDescription>
+      </CardHeader>
+      <CardContent flush>
+        <DataState query={query} skeleton={<SkeletonTable rows={3} columns={2} />}>
+          {(d) => <DataTable data={d} columns={columns} getRowId={(r) => r.id} />}
+        </DataState>
+      </CardContent>
+    </Card>
+  );
+}
+
+function InviteCard() {
+  const { t } = useTranslation();
+  const mutation = useMutation({
+    mutationFn: async () => {
+      throw expired();
+    },
+  });
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle level={2}>{t("authExpiryDocs.inviteTitle")}</CardTitle>
+        <CardDescription>A 401 on submit shows a muted status line, not an alert.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Flex direction="col" gap="md" align="start">
+          <Button onClick={() => mutation.mutate()}>{t("authExpiryDocs.send")}</Button>
+          <AlertMutationFeedback mutation={mutation} />
+        </Flex>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function Demo() {
+  const [calls, setCalls] = useState(0);
+  return (
+    <QueryClientProvider client={queryClient}>
+      <AuthExpiryProvider onAuthExpired={() => setCalls((n) => n + 1)}>
+        <PageContainer
+          title="AuthExpiryProvider"
+          subtitle="Expired session handled once at the app root, never as a page error"
+        >
+          <Flex direction="col" gap="lg">
+            <Text size="sm" tone="muted">
+              onAuthExpired calls: {calls}
+            </Text>
+            <MembersCard />
+            <InviteCard />
+          </Flex>
+        </PageContainer>
+      </AuthExpiryProvider>
+    </QueryClientProvider>
+  );
+}

package/docs/i18n/messages/en.json

@@ -1444,5 +1444,11 @@
       "sample": "Sample",
       "date": "September 2026 · demo date"
     }
+  },
+  "authExpiryDocs": {
+    "membersTitle": "Members",
+    "nameColumn": "Name",
+    "inviteTitle": "Send invitation",
+    "send": "Send"
   }
 }

package/docs/i18n/messages/ja.json

@@ -1438,5 +1438,11 @@
       "sample": "サンプル",
       "date": "2026年9月 · 予定日はデモ用"
     }
+  },
+  "authExpiryDocs": {
+    "membersTitle": "メンバー",
+    "nameColumn": "氏名",
+    "inviteTitle": "招待を送信",
+    "send": "送信"
   }
 }

package/docs/i18n/messages/vi.json

@@ -1438,5 +1438,11 @@
       "sample": "Mẫu",
       "date": "Tháng 9/2026 · ngày dùng cho demo"
     }
+  },
+  "authExpiryDocs": {
+    "membersTitle": "Thành viên",
+    "nameColumn": "Họ tên",
+    "inviteTitle": "Gửi lời mời",
+    "send": "Gửi"
   }
 }

package/docs/query/data-state.tsx

@@ -1,3 +1,4 @@
+import { useState } from "react";
 import { QueryClient, QueryClientProvider, useQuery } from "@tanstack/react-query";
 
 import {
@@ -12,8 +13,9 @@ import {
   type ColumnDef,
 } from "@godxjp/ui/data-display";
 import { SkeletonTable } from "@godxjp/ui/feedback";
+import { Text } from "@godxjp/ui/general";
 import { Flex, PageContainer } from "@godxjp/ui/layout";
-import { DataState } from "@godxjp/ui/query";
+import { AuthExpiryProvider, DataState } from "@godxjp/ui/query";
 
 /**
  * DataState · drives skeleton / error / empty / success for ONE useQuery block.
@@ -99,8 +101,40 @@ function PrerequisiteBlock() {
   );
 }
 
+function ExpiredSessionQuery({ queryKey }: { queryKey: string }) {
+  const query = useQuery<Invoice[]>({
+    queryKey: [queryKey],
+    queryFn: async () => {
+      throw Object.assign(new Error("Access token expired"), { status: 401 });
+    },
+  });
+  return (
+    <DataState query={query} skeleton={<SkeletonTable rows={3} />}>
+      {(d) => <DataTable data={d} columns={columns} getRowId={(r) => r.id} />}
+    </DataState>
+  );
+}
+
+function AuthExpiryBlock() {
+  // The app root owns session expiry (gh#1022). A real app redirects to the IdP here:
+  //   window.location.assign(`/auth/login?return_to=${encodeURIComponent(location.href)}`)
+  // Two queries 401 at once — the handler still runs exactly once, and no alert is painted.
+  const [calls, setCalls] = useState(0);
+  return (
+    <AuthExpiryProvider onAuthExpired={() => setCalls((n) => n + 1)}>
+      <Flex direction="col" gap="md">
+        <Text size="sm" tone="muted">
+          onAuthExpired calls: {calls}
+        </Text>
+        <ExpiredSessionQuery queryKey="ds-auth-expiry-a" />
+        <ExpiredSessionQuery queryKey="ds-auth-expiry-b" />
+      </Flex>
+    </AuthExpiryProvider>
+  );
+}
+
 function AuthErrorBlock() {
-  // A 401 / expired token never resolves by retrying — DataState offers session renewal instead.
+  // Without an AuthExpiryProvider: the proportionate fallback — a neutral sign-in prompt.
   const query = useQuery<Invoice[]>({
     queryKey: ["ds-auth-error"],
     queryFn: async () => {
@@ -175,10 +209,24 @@ export default function Demo() {
 
           <Card>
             <CardHeader>
-              <CardTitle level={2}>Error · auth (session renewal)</CardTitle>
+              <CardTitle level={2}>Session expired · AuthExpiryProvider (recommended)</CardTitle>
+              <CardDescription>
+                Mount `AuthExpiryProvider` once at the app root. A 401 calls `onAuthExpired`
+                automatically, once for any number of simultaneous 401s, while each DataState keeps
+                its skeleton and announces the redirect to sign-in through a live region.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <AuthExpiryBlock />
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle level={2}>Session expired · fallback without a provider</CardTitle>
               <CardDescription>
-                A 401 / expired token routes to session renewal via `onAuthError`, never a blind
-                retry, and never surfaces the raw token message.
+                Without a provider a 401 renders a neutral, width-capped sign-in prompt whose button
+                calls `onAuthError`. It never offers a blind retry or shows the raw token message.
               </CardDescription>
             </CardHeader>
             <CardContent>