@sjolystinnovation/app-kit 0.3.0 → 0.5.0

package/README.md

@@ -5,9 +5,13 @@
 
 > Building blocks for Next.js apps that sign in against a JWT API through next-auth
 
-Several apps sharing one API also share the code around it: the session plumbing, how a failed
-request becomes a message a user can read, and the form controls on the sign in page. This package
-holds that code once, so the apps install it instead of each keeping a copy.
+Several apps sharing one API also share the code around it:
+
+- the session plumbing
+- how a failed request becomes a message a user can read
+- the form controls on the sign in page
+
+This package holds that code once, and each app installs it.
 
 ## Install
 
@@ -64,21 +68,29 @@ const secret = resolveJwtSecret(sessionConfig, process.env);
 | --- | --- | --- |
 | `jwtSecretEnvVar` | `string` | Name of the environment variable holding the API JWT secret, such as `API_JWT_SECRET`. |
 | `loginRoute` | `string` | Where an expired session sends the browser, such as `/en/login` or `/login`. |
-| `draftStoragePrefix` | `string` | Prefix for the `localStorage` keys holding form drafts. |
+| `draftStoragePrefix` | `string` | Bare name for the `localStorage` keys holding form drafts, such as `example`. Drafts are stored under `example:draft:<owner>:<scope>`. |
 
 ### `defineSessionConfig(config)`
 
 `(config: SessionConfig) => SessionConfig`
 
-Returns the config unchanged, so TypeScript checks its shape where it is declared rather than at
-every call site.
+Returns the config unchanged, so TypeScript checks its shape once, where it is declared. Throws
+when `draftStoragePrefix` is empty or contains a colon.
+
+### `requireEnv(name, value)`
+
+`(name: string, value: string | undefined) => string`
+
+Returns `value`, or throws `Missing <name>.` when it is unset or empty. Pass the value read in
+place, such as `process.env.NEXT_PUBLIC_API_URL`, so Next.js can inline a public variable at build
+time.
 
 ### `resolveJwtSecret(config, env)`
 
 `(config: SessionConfig, env: Record<string, string | undefined>) => string`
 
-Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty, so a
-missing secret fails at startup instead of at the first token verification.
+Reads the secret named by `config.jwtSecretEnvVar`. Throws when that variable is unset or empty,
+with the variable's name in the message.
 
 ```ts
 resolveJwtSecret(sessionConfig, { API_JWT_SECRET: "s3cret" });
@@ -88,8 +100,8 @@ resolveJwtSecret(sessionConfig, {});
 // Error: Missing API_JWT_SECRET. The app verifies API session tokens with it.
 ```
 
-The environment is a parameter rather than a read of `process.env`, which keeps Node types out of a
-package that also runs in the browser.
+The environment is a parameter, so the root entry point needs no Node types and works in browser
+code. `@sjolystinnovation/app-kit/auth` is server only and does load Node types.
 
 ### `formatApiError(error, fallback, statusMessages?)`
 
@@ -110,11 +122,16 @@ body can come from a proxy, such as "Bad Gateway", so the caller's own words win
 A problem details `title` is never shown. ASP.NET Core fills it with generic text, such as "Bad
 Request" or "An error occurred while processing your request.", which says less than `fallback`.
 
-Key `0` in `statusMessages` covers a request that got no response, because of a dropped connection
-or a timeout. Only text on a single line counts as a message. Axios's own message, such as "Request
-failed with status code 500", is never shown, and a cancelled request gives `fallback`. Any other
-`Error` gives its own message. A body requested as an `arraybuffer` or a `blob`, as for a file
-download, is not read, so a failed download gets `statusMessages` or `fallback`.
+A few more rules:
+
+- Key `0` in `statusMessages` covers a request that got no response, because of a dropped
+  connection or a timeout.
+- Only text on a single line counts as a message.
+- Axios's own message, such as "Request failed with status code 500", is never shown.
+- A cancelled request gives `fallback`.
+- Any other `Error` gives its own message.
+- A body requested as an `arraybuffer` or a `blob`, as for a file download, is not read. A failed
+  download gets `statusMessages` or `fallback`.
 
 ```ts
 try {
@@ -124,6 +141,280 @@ try {
 }
 ```
 
+### `createAuthOptions(config, settings)`
+
+From `@sjolystinnovation/app-kit/auth`. Server only. Builds the next-auth options for an app that
+signs in against the API with email and password:
+
+```ts
+// src/lib/authOptions.ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createAuthOptions } from "@sjolystinnovation/app-kit/auth";
+import { sessionConfig } from "@/lib/session";
+
+export const authOptions = createAuthOptions(sessionConfig, {
+  apiUrl: requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL),
+  env: process.env,
+});
+```
+
+```ts
+// src/app/api/auth/[...nextauth]/route.ts
+import NextAuth from "next-auth/next";
+import { authOptions } from "@/lib/authOptions";
+
+const handler = NextAuth(authOptions);
+
+export { handler as GET, handler as POST };
+```
+
+| Setting | Type | Description |
+| --- | --- | --- |
+| `apiUrl` | `string` | Base URL of the API. Sign-in posts to `/auth/login` and refresh to `/auth/refresh-token` under it. An empty value throws. |
+| `env` | `Record<string, string \| undefined>` | The server environment, usually `process.env`. It supplies the secret named by `jwtSecretEnvVar`. |
+| `http` | `AxiosInstance` | In place of `apiUrl`, for tests. The client for sign-in and refresh, with its own base URL. |
+
+next-auth reads `NEXTAUTH_SECRET` itself and refuses to run in production without it.
+
+What the options do:
+
+- **Sign-in** posts `{ email, password }` and expects `{ token, refreshToken }`. The access token is
+  verified with the API JWT secret, allowing 60 seconds of clock difference between the server and
+  the API. Its `sub`, `unique_name` and `role` claims become the user's `id`, `name` and `roles`.
+  The log gets the status, error code and message, never the request. A failed sign-in reports one
+  of these in next-auth's `error`:
+  - `SIGN_IN_ERRORS.unavailable` when the API does not answer, or a gateway returns 502, 503 or 504.
+  - `SIGN_IN_ERRORS.invalidCredentials` for every other failure, including an unreadable token and
+    an answer without both tokens.
+- **Refresh** runs ahead of expiry: five minutes before it, or a quarter of the token's lifetime
+  before it when that is shorter. It is never scheduled sooner than 30 seconds out, so a token that
+  lives under 30 seconds is refreshed after it expires. Parallel reads of one session in one server
+  process share a single refresh. Its answer is kept for a minute, because the API rotates the
+  refresh token on every call.
+- **Failures:** a 400 or 401 from the refresh ends the session with `RefreshTokenRejected`. Any
+  other failure keeps it and tries again a minute later. A session without a refresh token ends with
+  `NoRefreshToken` when its refresh falls due.
+- **Cap:** the session ends seven days after sign-in with `AbsoluteSessionExpired`, however recently
+  it was refreshed.
+- **Session:** it carries `user`, `accessToken`, `error`, and `absoluteExpiresAt`, the end of the
+  seven days in milliseconds.
+- **Sign-in page:** `pages.signIn` is `config.loginRoute`.
+
+Two rules keep a refresh from being lost:
+
+- Read the session on the client, through `useSession` or `getSession`. In the App Router,
+  `getServerSession(authOptions)` cannot store a cookie, in server components, route handlers and
+  server actions alike. A refresh there replaces the tokens at the API and loses the new ones. The
+  next refresh then reuses the old token, and the API revokes every session the user has. On the
+  server, read the token with `getToken` from `next-auth/jwt`, which never refreshes.
+- Run the app as one server process. Parallel session reads share one refresh only within a process.
+  Two replicas can refresh the same token at once, with the same result.
+
+The package does not declare these fields on next-auth's types. The app declares them, so its own
+code can read them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    user: { id: string; name: string; email: string; roles: string[] };
+    accessToken: string;
+    error?: string | undefined;
+    absoluteExpiresAt?: number;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    accessToken?: string;
+    refreshToken?: string;
+    refreshAt?: number;
+    loginAt?: number;
+    user?: { id: string; name: string; email: string; roles: string[] };
+    error?: string | undefined;
+  }
+}
+```
+
+### `@sjolystinnovation/app-kit/api`
+
+`createApiClient(baseURL)` returns an axios instance for the signed-in API, for code that runs in
+the browser. It reads the session through next-auth's `getSession`, which has no cookies to read on
+the server. An empty `baseURL` throws. Each request carries the session's access token. A 401
+opens the re-sign-in prompt when the session is gone or has a terminal error. It does not sign
+the user out, so the page keeps its state. The error still rejects as usual.
+
+`request(call, fallback, statusMessages?)` runs a call and returns its `data`. A failure becomes an
+`Error` with the message `formatApiError` gives it. A cancelled call rethrows the cancel unchanged:
+
+```ts
+import { requireEnv } from "@sjolystinnovation/app-kit";
+import { createApiClient, request } from "@sjolystinnovation/app-kit/api";
+
+const api = createApiClient(requireEnv("NEXT_PUBLIC_API_URL", process.env.NEXT_PUBLIC_API_URL));
+
+export const getRecipe = (id: number) =>
+  request(() => api.get<Recipe>(`/recipes/${id}`), "Could not load the recipe.");
+```
+
+### `@sjolystinnovation/app-kit/session`
+
+Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
+callbacks.
+
+The gate reads `session.error`. `createAuthOptions` sets it already. An app with its own next-auth
+options sets `token.error` in its `jwt` callback and copies it across in its `session` callback:
+
+```ts
+callbacks: {
+  session({ session, token }) {
+    session.error = token.error;
+    return session;
+  },
+},
+```
+
+For that to compile, `error` has to be on next-auth's `Session` and `JWT` types. Add it to
+the app's existing next-auth type declarations, or create them:
+
+```ts
+// src/types/next-auth.d.ts
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth" {
+  interface Session {
+    error?: string | undefined;
+  }
+}
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    error?: string | undefined;
+  }
+}
+```
+
+`SIGN_IN_ERRORS` holds the two codes a failed sign-in reports: `InvalidCredentials` and
+`SignInUnavailable`. Map them to the app's own messages.
+
+`SESSION_ERRORS` holds the values the jwt callback puts in `token.error` when the session cannot be
+recovered: `AbsoluteSessionExpired`, `RefreshTokenRejected` and `NoRefreshToken`. `SessionError`
+is their union type. `isTerminalSessionError(error)` is true for those three only, so a transient
+refresh failure keeps the session.
+
+The re-sign-in prompt is a flag outside React, so an axios interceptor can raise it:
+
+| Function | Description |
+| --- | --- |
+| `openSessionPrompt()` | Asks the user to sign in again without leaving the page. |
+| `closeSessionPrompt()` | Hides the prompt. Call it when the component showing the prompt unmounts, or the flag stays open and the gate never redirects. |
+| `subscribeSessionPrompt(listener)` | Calls `listener` when the prompt opens or closes. Returns an unsubscribe function. |
+| `getSessionPromptOpen()` | Whether the prompt is showing. |
+
+Copies of the package installed side by side share the one flag, as long as their releases use the
+same prompt state format. A release that changes the format says so in its changelog. An app's own
+copy of these functions does not share the flag. So the interceptor, the prompt and every gate all
+import them from this package.
+
+### `useSessionGate()`
+
+From `@sjolystinnovation/app-kit/session/react`. Tells a protected page whether it may render. It
+reads `useSession`, so it needs a `SessionProvider` above it.
+
+A page that rendered on a healthy session stays rendered, so an open form keeps its values:
+
+- when the session gets a terminal error
+- while the session is re-read
+- while the prompt recovers it
+
+A session that turns signed out with no prompt open blanks the page. A page the user opens on a
+dead session does not render. Use `mayRender` in every gate and layout on the way down, so none of
+them blanks a page that another one kept.
+
+The hook does not navigate. The gate sends the user to the login page itself, and never while the
+prompt is open. The app passes the login URL in, so an app with a locale in the path can build it
+for the current locale:
+
+```tsx
+"use client";
+
+import { useSessionGate } from "@sjolystinnovation/app-kit/session/react";
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+
+export function ProtectedGate({
+  loginHref,
+  children,
+}: {
+  loginHref: string;
+  children: React.ReactNode;
+}) {
+  const router = useRouter();
+  const { status, promptOpen, usable, wasUsable, mayRender } = useSessionGate();
+
+  useEffect(() => {
+    if (promptOpen) return;
+    if (status === "unauthenticated" || (status === "authenticated" && !usable && !wasUsable)) {
+      router.push(loginHref);
+    }
+  }, [status, usable, wasUsable, promptOpen, router, loginHref]);
+
+  return mayRender ? children : <p>Loading…</p>;
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `mayRender` | Whether the page may render. |
+| `session`, `status` | As `useSession` returns them. |
+| `usable` | The session is signed in and has no terminal error. |
+| `wasUsable` | This page has rendered on a usable session. |
+| `promptOpen` | The re-sign-in prompt is showing. |
+| `recovering` | The prompt is showing over a page that was usable. |
+
+`SessionGate` is the type of the result.
+
+### `useFormDraft(config, options)`
+
+From `@sjolystinnovation/app-kit/forms`. Keeps a form's values in `localStorage`, so a sign-out,
+reload or closed tab does not lose them. Values are written half a second after the last change, so
+only that last half second is at risk.
+
+```tsx
+// userId is the signed-in user's id, from wherever the app's session keeps it.
+const draft = useFormDraft(sessionConfig, {
+  owner: userId,
+  scope: recipe ? `recipe:${recipe.id}` : "recipe:new",
+  value: form,
+});
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `owner` | `string \| undefined` | The signed-in user's id. Drafts are stored per user, and nothing is stored until it is known. The last known owner is kept when the session stops reporting one. |
+| `scope` | `string` | The form and the entity it edits, such as `recipe:42`. |
+| `value` | `T` | The form's current values. They must survive `JSON.stringify`. |
+
+Mount an edit form once the entity has loaded, with its values already in `value`. The hook treats
+the values it first sees under a key as the untouched form, so values that arrive later count as an
+edit and are written over the draft being offered.
+
+It returns:
+
+- `pending`, the stored draft. The page offers it to the user and does not apply it. It is read
+  when the owner is first known and again whenever the owner or `scope` changes, so it can appear
+  after the form mounts.
+- `dismiss()`, to stop offering it.
+- `clear()`, to drop the stored draft after a successful save.
+
+Drafts are stored under `<draftStoragePrefix>:draft:<owner>:<scope>`. The hook throws when
+`draftStoragePrefix` is empty or contains a colon. A draft older than 7 days is not offered, and is
+removed when its form next reads it.
+
 ### `Alert`
 
 ```tsx
@@ -136,7 +427,7 @@ import { Alert } from "@sjolystinnovation/app-kit/ui";
 | --- | --- | --- | --- |
 | `variant` | `"error" \| "success" \| "info" \| "warning"` | `"info"` | Colour of the box. |
 | `role` | `"alert" \| "status"` | `"alert"` | Use `status` for text that keeps changing, such as a countdown, so a screen reader does not announce every change. |
-| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables instead, since whether a clashing class wins depends on the order Tailwind emits them in. |
+| `className` | `string` | | Classes for placing the alert, such as a margin. Restyle it through the theme variables. A clashing class wins or loses by the order Tailwind emits them in. |
 | `children` | `ReactNode` | | Content. |
 
 ### `PasswordInput`
@@ -157,7 +448,7 @@ import { PasswordInput } from "@sjolystinnovation/app-kit/ui";
 | `error` | `string` | | Message shown under the field. It turns the border red, marks the input invalid and is read out with it by screen readers. |
 | `showPasswordLabel` | `string` | `"Show password"` | Accessible name of the toggle while the value is hidden. |
 | `hidePasswordLabel` | `string` | `"Hide password"` | Accessible name of the toggle while the value is visible. |
-| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables instead. |
+| `className` | `string` | | Classes for placing the field, such as a margin. They go on the outer element around the label, input and error. Restyle the field through the theme variables. |
 
 Pass the two toggle labels in the app's language. The defaults are English.
 
@@ -214,15 +505,17 @@ with it and has to set the ones it uses itself.
 
 ## Requirements
 
-- Next.js 16, React 19, next-auth 4 and axios 1, as peer dependencies the app installs itself.
+- Next.js 16, React 19, next-auth 4.24 or later and axios 1.20 or later, as peer dependencies the
+  app installs itself.
+- `jsonwebtoken` comes with the package. `@sjolystinnovation/app-kit/auth` uses it on the server.
 - For `@sjolystinnovation/app-kit/ui`: Tailwind CSS 4 and `@heroicons/react` 2. The focus ring uses
   the theme's `primary` colour unless `--color-input-focus-ring` is set.
 - TypeScript with `"moduleResolution": "bundler"`. Relative imports here are extensionless, which
   `node16` and `nodenext` reject.
 
-There is no build output. Shipping source is what keeps the `"use client"` directives intact, since
-bundlers strip or relocate them. The consumer therefore compiles this source with its own
-`compilerOptions`, and `skipLibCheck` does not exempt it.
+There is no build output. Bundlers strip or relocate `"use client"` directives, and shipping source
+keeps them intact. The consumer compiles this source with its own `compilerOptions`, and
+`skipLibCheck` does not exempt it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -16,6 +16,11 @@
   ],
   "exports": {
     ".": "./src/index.ts",
+    "./session": "./src/session/index.ts",
+    "./session/react": "./src/session/react/index.ts",
+    "./forms": "./src/forms/index.ts",
+    "./auth": "./src/auth/index.ts",
+    "./api": "./src/api/index.ts",
     "./ui": "./src/ui/index.ts",
     "./styles.css": "./src/styles.css"
   },
@@ -32,7 +37,7 @@
   },
   "peerDependencies": {
     "@heroicons/react": "^2",
-    "axios": "^1",
+    "axios": "^1.20.0",
     "next": "^16",
     "next-auth": "^4.24",
     "react": "^19",
@@ -46,7 +51,7 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "@vitejs/plugin-react": "^6.1.2",
-    "axios": "^1.19.0",
+    "axios": "^1.20.0",
     "jsdom": "^30.1.1",
     "next": "^16.3.6",
     "next-auth": "^4.24.15",
@@ -62,5 +67,9 @@
     "jwt",
     "react",
     "tailwindcss"
-  ]
+  ],
+  "dependencies": {
+    "@types/jsonwebtoken": "^9.0.8",
+    "jsonwebtoken": "^9.0.2"
+  }
 }

package/src/api/createApiClient.ts

@@ -0,0 +1,43 @@
+import axios, { type AxiosInstance } from "axios";
+import { getSession } from "next-auth/react";
+import { isTerminalSessionError, openSessionPrompt } from "../session/expiry";
+
+/**
+ * An axios instance for the signed-in API, for browser code. Each request carries the session's
+ * access token. A 401 on a dead session opens the re-sign-in prompt, so the page keeps its state.
+ */
+export function createApiClient(baseURL: string): AxiosInstance {
+  if (!baseURL) {
+    throw new Error("createApiClient needs the API base URL, and baseURL is empty.");
+  }
+  // allowAbsoluteUrls: false joins every URL onto baseURL, so the token only goes to the API.
+  const client = axios.create({ baseURL, allowAbsoluteUrls: false });
+
+  // broadcast: false, so a request does not make every other open tab refetch its session.
+  client.interceptors.request.use(async (request) => {
+    const session = await getSession({ broadcast: false });
+    const accessToken = (session as { accessToken?: string } | null)?.accessToken;
+    if (accessToken) {
+      request.headers.Authorization = `Bearer ${accessToken}`;
+    }
+    return request;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      if (axios.isAxiosError(error) && error.response?.status === 401) {
+        const session = await getSession({ broadcast: false });
+        // No session also opens the prompt. The cookie is gone, or the session fetch failed. Either
+        // way there is no error field to read, and signing in again recovers both.
+        const sessionError = (session as { error?: string } | null)?.error;
+        if (!session || isTerminalSessionError(sessionError)) {
+          openSessionPrompt();
+        }
+      }
+      return Promise.reject(error);
+    },
+  );
+
+  return client;
+}

package/src/api/index.ts

@@ -0,0 +1,2 @@
+export { createApiClient } from "./createApiClient";
+export { request } from "./request";

package/src/api/request.ts

@@ -0,0 +1,22 @@
+import axios from "axios";
+import { formatApiError, type StatusMessages } from "../errors";
+
+/**
+ * Runs an API call and returns its data. A failure throws an `Error` with a message for the user,
+ * from `formatApiError`. A cancelled call rethrows the cancel as it is, so the caller can ignore it.
+ */
+export async function request<T>(
+  call: () => Promise<{ data: T }>,
+  fallback: string,
+  statusMessages?: StatusMessages,
+): Promise<T> {
+  try {
+    const response = await call();
+    return response.data;
+  } catch (error: unknown) {
+    if (axios.isCancel(error)) throw error;
+    // No cause. Errors get logged, and the axios error carries the access token and request body.
+    // eslint-disable-next-line preserve-caught-error
+    throw new Error(formatApiError(error, fallback, statusMessages));
+  }
+}

package/src/auth/createAuthOptions.ts

@@ -0,0 +1,313 @@
+import axios, { type AxiosInstance } from "axios";
+import jwt from "jsonwebtoken";
+import type { NextAuthOptions, Session, User } from "next-auth";
+import CredentialsProvider from "next-auth/providers/credentials";
+import type { JWT } from "next-auth/jwt";
+import { resolveJwtSecret, type SessionConfig } from "../config";
+import { SESSION_ERRORS, SIGN_IN_ERRORS, isTerminalSessionError } from "../session/expiry";
+
+/** The signed-in user, as the session carries it. */
+export interface SessionUser {
+  id: string;
+  name: string;
+  email: string;
+  roles: string[];
+}
+
+interface TokenPair {
+  token: string;
+  refreshToken: string;
+}
+
+interface ApiClaims {
+  sub: string;
+  unique_name: string;
+  role?: string | string[];
+  exp: number;
+  iat: number;
+}
+
+// The fields this module stores in next-auth's JWT. An intersection still compiles when the app
+// declares the same fields itself.
+type AppToken = JWT & {
+  accessToken?: string;
+  refreshToken?: string;
+  refreshAt?: number;
+  loginAt?: number;
+  user?: SessionUser;
+  error?: string;
+};
+
+interface AuthorizedUser extends User {
+  roles: string[];
+  accessToken: string;
+  refreshToken: string;
+}
+
+export type AuthOptionsSettings = {
+  /** The server environment, usually `process.env`. It holds the API JWT secret. */
+  env: Record<string, string | undefined>;
+} & (
+  | {
+      /** Base URL of the API, such as `https://api.example.com/api`. */
+      apiUrl: string;
+      http?: never;
+    }
+  | {
+      /** An HTTP client with its own base URL, for tests. */
+      http: AxiosInstance;
+      apiUrl?: never;
+    }
+);
+
+const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// Refresh ahead of expiry, so the token is still fresh when the user saves.
+const MAX_REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+// The soonest a refresh can be due. The floor stops a short-lived token from refreshing on every
+// session read.
+const MIN_REFRESH_GAP_MS = 30 * 1000;
+
+// How long a refresh result is remembered. It is also the wait before a failed refresh is retried.
+const REMEMBER_ROTATION_MS = 60 * 1000;
+
+// How far this server's clock may differ from the API's when a token's times are checked.
+const CLOCK_TOLERANCE_S = 60;
+
+// Sign-in and session reads wait for the API, so a hung connection must not hold them forever.
+const API_TIMEOUT_MS = 10_000;
+
+function rolesOf(claims: ApiClaims): string[] {
+  const raw = claims.role;
+  return Array.isArray(raw) ? raw : raw ? [raw] : [];
+}
+
+// The skew is capped at a quarter of the token's lifetime, so a short-lived token is not refreshed
+// on every read. A token without a lifetime gets the floor.
+function nextRefreshAt(claims: ApiClaims): number {
+  const expiresAt = claims.exp * 1000;
+  const lifetimeMs = Math.max(0, (claims.exp - claims.iat) * 1000);
+  const refreshAt = expiresAt - Math.min(MAX_REFRESH_SKEW_MS, lifetimeMs / 4);
+  if (!Number.isFinite(refreshAt)) return Date.now() + MIN_REFRESH_GAP_MS;
+  return Math.max(Date.now() + MIN_REFRESH_GAP_MS, refreshAt);
+}
+
+// No answer, or a gateway that could not reach the API. A plain 500 is left out, because the API
+// may fail after it has checked the password.
+function apiUnavailable(error: unknown): boolean {
+  if (!axios.isAxiosError(error)) return false;
+  const status = error.response?.status;
+  return status === undefined || status === 502 || status === 503 || status === 504;
+}
+
+// What a log line may contain. The error itself carries the request, which holds the password or
+// tokens.
+function failureShape(error: unknown) {
+  return {
+    status: axios.isAxiosError(error) ? error.response?.status : undefined,
+    code: axios.isAxiosError(error) ? error.code : undefined,
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/**
+ * next-auth options for email and password sign-in against the API. The API issues a short-lived
+ * access token and a refresh token that changes on every refresh. The session refreshes ahead of
+ * expiry, rides out temporary API failures, and ends seven days after sign-in.
+ */
+export function createAuthOptions(config: SessionConfig, settings: AuthOptionsSettings): NextAuthOptions {
+  const { env } = settings;
+  if (settings.http === undefined && !settings.apiUrl) {
+    throw new Error("createAuthOptions needs the API base URL, and apiUrl is empty.");
+  }
+  const http = settings.http ?? axios.create({ baseURL: settings.apiUrl, allowAbsoluteUrls: false });
+
+  const readClaims = (token: string) =>
+    jwt.verify(token, resolveJwtSecret(config, env), {
+      clockTolerance: CLOCK_TOLERANCE_S,
+    }) as unknown as ApiClaims;
+
+  async function postTokens(path: string, body: object): Promise<TokenPair> {
+    const response = await http.post<TokenPair>(path, body, { timeout: API_TIMEOUT_MS });
+    return response.data;
+  }
+
+  // Parallel session reads carry the same refresh token. The API accepts each refresh token once.
+  // It treats a second use as replay and revokes every session the user has. So all reads of one
+  // token share one refresh. The result is kept for a while, because a slow read can arrive with
+  // the old token after the refresh is done.
+  //
+  // The map lives in one server process. Replicas do not share it.
+  const inFlight = new Map<string, Promise<AppToken>>();
+
+  function refreshOnce(token: AppToken): Promise<AppToken> {
+    const key = token.refreshToken as string;
+    const existing = inFlight.get(key);
+    if (existing) return existing;
+
+    const pending = rotate(token);
+    inFlight.set(key, pending);
+    // The minute counts from the answer, so a slow refresh is remembered as long as a fast one.
+    void pending.then(() => {
+      // unref, so the timer cannot keep a serverless invocation alive.
+      const expiry = setTimeout(() => inFlight.delete(key), REMEMBER_ROTATION_MS) as unknown as {
+        unref?: () => void;
+      };
+      expiry.unref?.();
+    });
+    return pending;
+  }
+
+  async function rotate(token: AppToken): Promise<AppToken> {
+    let refreshed: TokenPair;
+    try {
+      refreshed = await postTokens(
+        "/auth/refresh-token",
+        { token: token.accessToken, refreshToken: token.refreshToken },
+      );
+    } catch (error) {
+      // The API refused the token pair: a bad access token, or a refresh token that is unknown,
+      // expired or already used. Only this ends the session.
+      const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+      if (status === 400 || status === 401) {
+        return { ...token, error: SESSION_ERRORS.refreshRejected };
+      }
+      // A network error or an API restart keeps the session. A later read tries again.
+      console.error("Refresh token request failed, keeping the session", failureShape(error));
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // A success without tokens is treated as a temporary failure, and the session keeps its own.
+    if (!refreshed?.token || !refreshed.refreshToken) {
+      console.error("Refresh token response had no tokens, keeping the session");
+      return { ...token, refreshAt: Date.now() + REMEMBER_ROTATION_MS };
+    }
+
+    // The API has already replaced the old tokens. Keep the new ones whatever happens below,
+    // because the old refresh token now counts as replay.
+    const next: AppToken = {
+      ...token,
+      accessToken: refreshed.token,
+      refreshToken: refreshed.refreshToken,
+    };
+    delete next.error;
+
+    try {
+      const claims = readClaims(refreshed.token);
+      next.refreshAt = nextRefreshAt(claims);
+      next.user = { ...(token.user as SessionUser), roles: rolesOf(claims) };
+    } catch (error) {
+      // The token is unreadable, for example after a secret change. Retry soon with the new
+      // refresh token.
+      console.error("Could not read the refreshed access token, retrying shortly", failureShape(error));
+      next.refreshAt = Date.now() + REMEMBER_ROTATION_MS;
+    }
+
+    return next;
+  }
+
+  return {
+    providers: [
+      CredentialsProvider({
+        name: "Credentials",
+        credentials: {
+          email: { label: "Email", type: "email" },
+          password: { label: "Password", type: "password" },
+        },
+        async authorize(credentials) {
+          if (!credentials) {
+            throw new Error("Credentials are missing");
+          }
+          try {
+            const tokens = await postTokens(
+              "/auth/login",
+              { email: credentials.email, password: credentials.password },
+            );
+            if (!tokens?.token || !tokens.refreshToken) {
+              throw new Error("Login response had no tokens");
+            }
+            const claims = readClaims(tokens.token);
+            const user: AuthorizedUser = {
+              id: claims.sub,
+              name: claims.unique_name,
+              email: credentials.email,
+              roles: rolesOf(claims),
+              accessToken: tokens.token,
+              refreshToken: tokens.refreshToken,
+            };
+            return user;
+          } catch (error) {
+            console.error("Sign-in failed", failureShape(error));
+            // No cause: next-auth logs this error, and the cause carries the password.
+            // eslint-disable-next-line preserve-caught-error
+            throw new Error(
+              apiUnavailable(error) ? SIGN_IN_ERRORS.unavailable : SIGN_IN_ERRORS.invalidCredentials,
+            );
+          }
+        },
+      }),
+    ],
+    pages: {
+      signIn: config.loginRoute,
+    },
+    session: {
+      maxAge: ABSOLUTE_SESSION_MAX_AGE / 1000,
+    },
+    callbacks: {
+      async jwt({ token: current, user }) {
+        let token = current as AppToken;
+        if (user) {
+          const signedIn = user as AuthorizedUser;
+          const claims = readClaims(signedIn.accessToken);
+          token = {
+            ...token,
+            accessToken: signedIn.accessToken,
+            refreshToken: signedIn.refreshToken,
+            refreshAt: nextRefreshAt(claims),
+            loginAt: Date.now(),
+            user: {
+              id: signedIn.id,
+              name: signedIn.name ?? "",
+              email: signedIn.email ?? "",
+              roles: signedIn.roles,
+            },
+          };
+          delete token.error;
+        }
+
+        // A session without a sign-in time counts as expired.
+        if (token.loginAt === undefined || Date.now() - token.loginAt > ABSOLUTE_SESSION_MAX_AGE) {
+          return { ...token, error: SESSION_ERRORS.absoluteExpiry };
+        }
+
+        // Only a new sign-in recovers a terminal session, so the API is not asked again.
+        if (isTerminalSessionError(token.error)) {
+          return token;
+        }
+
+        if (token.refreshAt && Date.now() < token.refreshAt) {
+          return token;
+        }
+
+        if (!token.refreshToken) {
+          return { ...token, error: SESSION_ERRORS.noRefreshToken };
+        }
+
+        return refreshOnce(token);
+      },
+      async session({ session, token: current }) {
+        const token = current as AppToken;
+        // Cast, so it compiles against the app's own Session declaration.
+        return {
+          ...session,
+          user: token.user,
+          accessToken: token.accessToken,
+          error: token.error,
+          // Lets the UI warn before the seven days run out.
+          absoluteExpiresAt: token.loginAt ? token.loginAt + ABSOLUTE_SESSION_MAX_AGE : undefined,
+        } as Session;
+      },
+    },
+  };
+}

package/src/auth/index.ts

@@ -0,0 +1,2 @@
+export { createAuthOptions } from "./createAuthOptions";
+export type { AuthOptionsSettings, SessionUser } from "./createAuthOptions";

package/src/config.ts

@@ -1,6 +1,6 @@
 /**
  * The values that differ between the apps using this package. Everything else in the session layer
- * is identical across them, so it stays hardcoded rather than becoming an option.
+ * is the same in every app, so it is hardcoded.
  */
 export interface SessionConfig {
   /**
@@ -10,24 +10,55 @@ export interface SessionConfig {
   jwtSecretEnvVar: string;
   /**
    * Where an expired or rejected session sends the browser. An app with a locale prefix uses
-   * something like "/en/login", one without uses "/login".
+   * something like "/en/login". An app without one uses "/login".
    */
   loginRoute: string;
-  /** Prefix for the localStorage keys holding form drafts. */
+  /**
+   * Prefix for the localStorage keys holding form drafts, usually the app's name, such as
+   * "example". Drafts are stored under `<prefix>:draft:<owner>:<scope>`, so the prefix itself
+   * has no trailing colon.
+   */
   draftStoragePrefix: string;
 }
 
-/** Identity helper, so an app can declare its config as a typed constant. */
+/**
+ * Declares an app's config as a typed constant. Throws when `draftStoragePrefix` is not a bare name,
+ * so a bad value fails at app start, before any form opens.
+ */
 export function defineSessionConfig(config: SessionConfig): SessionConfig {
+  draftPrefix(config);
   return config;
 }
 
 /**
- * Reads the API JWT secret named by the config. Throws rather than returning undefined, because a
- * missing secret silently breaks token verification at runtime instead of at boot.
+ * The key prefix for form drafts. Throws on a colon or an empty name. Those build keys such as
+ * "app:draft::draft:", which match no draft saved under "app:draft:".
+ */
+export function draftPrefix(config: Pick<SessionConfig, "draftStoragePrefix">): string {
+  const name = config.draftStoragePrefix;
+  if (!name || name.includes(":")) {
+    throw new Error(`draftStoragePrefix must be a bare name such as "example", not "${name}".`);
+  }
+  return `${name}:draft:`;
+}
+
+/**
+ * Returns `value`, or throws when it is unset or empty. Pass `process.env.NAME` directly, so Next.js
+ * can inline public variables at build time.
+ */
+export function requireEnv(name: string, value: string | undefined): string {
+  if (!value) {
+    throw new Error(`Missing ${name}.`);
+  }
+  return value;
+}
+
+/**
+ * Reads the API JWT secret named by the config. Throws when it is missing, with a message that names
+ * the variable.
  *
- * The caller passes the environment, usually `process.env`. Reading it here would put
- * `@types/node` in the type surface of a package that ends up in a browser bundle.
+ * The caller passes the environment, usually `process.env`, so this entry point needs no Node
+ * types and stays safe to import in browser code.
  */
 export function resolveJwtSecret(
   config: SessionConfig,

package/src/errors.ts

@@ -9,7 +9,7 @@ export type StatusMessages = Partial<Record<number, string>>;
 
 /**
  * Axios codes for a request that never got a response from the network. A browser reports every
- * network failure as ERR_NETWORK. On the server, Node reports the cause instead.
+ * network failure as ERR_NETWORK. On the server, Node reports the specific cause.
  */
 const NO_RESPONSE_CODES = new Set([
   "ERR_NETWORK",
@@ -26,15 +26,19 @@ const NO_RESPONSE_CODES = new Set([
 /**
  * Turns a failed request into one line a user can read.
  *
- * On a 4xx response the body's own message comes first: a text body, then `message`, the first
- * validation error and `detail` from a JSON body. After that come `statusMessages` for the status
- * and `fallback`. On a 5xx the caller's status message comes first, because the body may be a
- * proxy's "Bad Gateway" rather than the API's own words. A problem details `title` is never used:
- * ASP.NET Core fills it with generic text such as "Bad Request", which says less than `fallback`.
+ * On a 4xx response the order is:
+ * 1. The body's own message: a text body, or `message`, the first validation error or `detail` from
+ *    a JSON body.
+ * 2. `statusMessages` for the status.
+ * 3. `fallback`.
+ *
+ * On a 5xx the caller's status message comes first, because the body may come from a proxy, such
+ * as "Bad Gateway". A problem details `title` is never used. ASP.NET Core fills it with generic text
+ * such as "Bad Request", which says less than `fallback`.
  *
  * Only single line text counts as a message. Axios's own message, such as "Request failed with
- * status code 500", is never shown, and a cancelled request gives `fallback`. Any other `Error`
- * gives its message.
+ * status code 500", is never shown. A cancelled request gives `fallback`. Any other `Error` gives
+ * its message.
  */
 export function formatApiError(
   error: unknown,

package/src/forms/index.ts

@@ -0,0 +1,2 @@
+export { useFormDraft } from "./useFormDraft";
+export type { FormDraft, FormDraftOptions } from "./useFormDraft";

package/src/forms/useFormDraft.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { draftPrefix, type SessionConfig } from "../config";
+
+const WRITE_DELAY_MS = 500;
+
+// How long a draft is offered. Long enough to outlive an expired session or a closed tab. Short
+// enough that stale work is not offered as current. A form removes its expired draft on next read.
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+interface Envelope<T> {
+  savedAt: number;
+  value: T;
+}
+
+function read<T>(storageKey: string): T | null {
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw == null) return null;
+
+    const envelope = JSON.parse(raw) as Envelope<T> | null;
+    const fresh =
+      typeof envelope?.savedAt === "number" && Date.now() - envelope.savedAt <= MAX_AGE_MS;
+    if (!fresh || envelope?.value === undefined) {
+      window.localStorage.removeItem(storageKey);
+      return null;
+    }
+    return envelope.value;
+  } catch {
+    return null;
+  }
+}
+
+export interface FormDraftOptions<T> {
+  /**
+   * The signed-in user's id. A browser profile can be shared, so drafts are stored per user. That
+   * way nobody is offered another user's work. The hook keeps the last known owner. A lost cookie
+   * reports nobody, and that is when the draft matters most. Nothing is stored until an owner is
+   * known.
+   */
+  owner: string | undefined;
+  /** Identifies the form and the entity it edits, for example `recipe:new` or `recipe:42`. */
+  scope: string;
+  /** The form's current values. They must survive `JSON.stringify`. */
+  value: T;
+}
+
+export interface FormDraft<T> {
+  /**
+   * The stored draft, while it is still waiting to be restored or dismissed. Read once the owner is
+   * known and again whenever the owner or scope changes, so it can appear after mount.
+   */
+  pending: T | null;
+  /** Stop offering the draft. The caller applies the values it wants. */
+  dismiss: () => void;
+  /** Drop the stored draft after a successful save. */
+  clear: () => void;
+}
+
+/**
+ * Keeps a form's values in localStorage so a sign-out, reload or closed tab does not lose them.
+ * Values are written half a second after the last change, so only that last half second is at risk.
+ *
+ * A draft found at mount is offered for restore, not applied. So an edit form never silently
+ * overwrites what the API returned. Saving starts at once, whether or not the offer is answered.
+ * The offer is held in memory, so storage always holds the newest work.
+ */
+export function useFormDraft<T>(
+  config: Pick<SessionConfig, "draftStoragePrefix">,
+  { owner, scope, value }: FormDraftOptions<T>,
+): FormDraft<T> {
+  // Set during render, which is React's supported way to derive state from changing inputs.
+  const [lastOwner, setLastOwner] = useState<string | undefined>(undefined);
+  if (owner && owner !== lastOwner) setLastOwner(owner);
+
+  // Checked before the owner is known, so a bad prefix fails on the first render, signed in or not.
+  const prefix = draftPrefix(config);
+  const key = lastOwner ? `${prefix}${lastOwner}:${scope}` : null;
+
+  const [pending, setPending] = useState<T | null>(null);
+  const json = JSON.stringify(value);
+  const untouched = useRef(json);
+  const writeTimer = useRef<number | null>(null);
+
+  useEffect(() => {
+    // Re-base on a key change too. The values on screen belong to the old key and must not land
+    // in the new key's draft.
+    untouched.current = json;
+    // Reading storage is an external-system read, which belongs in an effect.
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    setPending(key == null ? null : read<T>(key));
+    // Runs on a key change only. Re-reading on every value change would re-offer a draft the user
+    // has already answered.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  useEffect(() => {
+    if (key == null) return;
+    // Write only once the form differs from how it opened, so the pristine form never overwrites
+    // a draft that is still on offer.
+    if (json === untouched.current) return;
+    const timer = window.setTimeout(() => {
+      try {
+        window.localStorage.setItem(key, JSON.stringify({ savedAt: Date.now(), value }));
+      } catch {
+        // A full or blocked store must not break the form.
+      }
+    }, WRITE_DELAY_MS);
+    writeTimer.current = timer;
+    return () => window.clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, json]);
+
+  const clear = useCallback(() => {
+    if (key == null) return;
+    // Cancel any scheduled write and make the current values the baseline, so a save is never
+    // followed by a fresh draft write.
+    if (writeTimer.current != null) window.clearTimeout(writeTimer.current);
+    untouched.current = json;
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+      // The draft is a convenience. Nothing depends on it.
+    }
+  }, [key, json]);
+
+  const dismiss = useCallback(() => setPending(null), []);
+
+  return { pending, dismiss, clear };
+}

package/src/index.ts

@@ -1,4 +1,4 @@
-export { defineSessionConfig, resolveJwtSecret } from "./config";
+export { defineSessionConfig, requireEnv, resolveJwtSecret } from "./config";
 export type { SessionConfig } from "./config";
 export { formatApiError } from "./errors";
 export type { StatusMessages } from "./errors";

package/src/session/expiry.ts

@@ -0,0 +1,77 @@
+/**
+ * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
+ * transient refresh failure, such as a network error or an API restart, sets no error, so the
+ * session keeps working and a later session read retries the refresh.
+ */
+export const SESSION_ERRORS = {
+  absoluteExpiry: "AbsoluteSessionExpired",
+  refreshRejected: "RefreshTokenRejected",
+  noRefreshToken: "NoRefreshToken",
+} as const;
+
+/**
+ * The codes a failed sign-in reports in next-auth's `error`. Wrong credentials and every API answer
+ * look the same, so the message never hints that a password was right. Only an API that does not
+ * answer, or a gateway error, reports `unavailable`. That depends on the server, never on the
+ * password.
+ */
+export const SIGN_IN_ERRORS = {
+  invalidCredentials: "InvalidCredentials",
+  unavailable: "SignInUnavailable",
+} as const;
+
+/** One of the values in `SESSION_ERRORS`. */
+export type SessionError = (typeof SESSION_ERRORS)[keyof typeof SESSION_ERRORS];
+
+const TERMINAL: ReadonlySet<string> = new Set(Object.values(SESSION_ERRORS));
+
+/** Whether a session error means the user has to sign in again. */
+export function isTerminalSessionError(error: string | undefined): boolean {
+  return error != null && TERMINAL.has(error);
+}
+
+// Whether the re-sign-in prompt is showing. It lives outside React for two reasons:
+// 1. The axios interceptor that raises it is a plain module.
+// 2. The page gate reads it, so it never redirects to login while the prompt recovers the session.
+//
+// It sits on globalThis under a registered symbol, so two copies of this module share one prompt.
+// Two installed versions of the package are one example. A gate reading one copy then sees a
+// prompt raised through the other and keeps the form on screen.
+interface PromptState {
+  open: boolean;
+  listeners: Set<() => void>;
+}
+
+// The shape of PromptState is a contract between releases. A release that changes it must also
+// change this key, so it never reads state in a shape it does not expect.
+const STATE_KEY = Symbol.for("@sjolystinnovation/app-kit/session-prompt/v1");
+const shared = globalThis as typeof globalThis & { [STATE_KEY]?: PromptState };
+const state: PromptState = (shared[STATE_KEY] ??= { open: false, listeners: new Set() });
+
+function emit(): void {
+  for (const listener of [...state.listeners]) listener();
+}
+
+/** Ask the user to sign in again without leaving the page. */
+export function openSessionPrompt(): void {
+  if (state.open) return;
+  state.open = true;
+  emit();
+}
+
+export function closeSessionPrompt(): void {
+  if (!state.open) return;
+  state.open = false;
+  emit();
+}
+
+export function subscribeSessionPrompt(listener: () => void): () => void {
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function getSessionPromptOpen(): boolean {
+  return state.open;
+}

package/src/session/index.ts

@@ -0,0 +1,10 @@
+export {
+  SESSION_ERRORS,
+  SIGN_IN_ERRORS,
+  closeSessionPrompt,
+  getSessionPromptOpen,
+  isTerminalSessionError,
+  openSessionPrompt,
+  subscribeSessionPrompt,
+} from "./expiry";
+export type { SessionError } from "./expiry";

package/src/session/react/index.ts

@@ -0,0 +1,2 @@
+export { useSessionGate } from "./useSessionGate";
+export type { SessionGate } from "./useSessionGate";

package/src/session/react/useSessionGate.ts

@@ -0,0 +1,61 @@
+"use client";
+
+import { useSession } from "next-auth/react";
+import { usePathname } from "next/navigation";
+import { useState, useSyncExternalStore } from "react";
+import { getSessionPromptOpen, isTerminalSessionError, subscribeSessionPrompt } from "../expiry";
+
+/**
+ * Whether a protected page may render, and whether it must stay rendered.
+ *
+ * Every gate on the way down should use this, so they all agree. A nested layout that decides on
+ * its own can blank the page. That undoes the in-place recovery the re-sign-in prompt exists for.
+ */
+export function useSessionGate() {
+  const { data: session, status } = useSession();
+  const pathname = usePathname();
+  const promptOpen = useSyncExternalStore(
+    subscribeSessionPrompt,
+    getSessionPromptOpen,
+    () => false,
+  );
+
+  // The jwt callback copies its error onto the session. Read it without requiring the app to have
+  // added `error` to next-auth's Session type.
+  const error = (session as { error?: string } | null)?.error;
+  const usable = status === "authenticated" && !isTerminalSessionError(error);
+
+  // The path that last rendered on a healthy session. Keyed by path, so each page checks again. A
+  // session that died on the previous page cannot pass a fresh form.
+  // Set during render, which is React's supported way to derive state from changing inputs.
+  // It starts as undefined, not null, because usePathname can return null.
+  const [usableAt, setUsableAt] = useState<string | null | undefined>(undefined);
+  if (usable && usableAt !== pathname) setUsableAt(pathname);
+  const wasUsable = usableAt === pathname;
+
+  // The page is already open and the prompt is recovering the session in place.
+  const recovering = promptOpen && wasUsable;
+
+  return {
+    session,
+    status,
+    promptOpen,
+    usable,
+    wasUsable,
+    recovering,
+    /**
+     * The one answer every gate on the way down uses. A layout that decides this again can blank
+     * the page that the gate above it chose to keep.
+     */
+    mayRender:
+      recovering ||
+      !(
+        (status === "loading" && !wasUsable) ||
+        status === "unauthenticated" ||
+        (!usable && !wasUsable)
+      ),
+  };
+}
+
+/** What `useSessionGate` returns. */
+export type SessionGate = ReturnType<typeof useSessionGate>;

package/src/styles.css

@@ -2,9 +2,9 @@
 @source ".";
 
 /*
- * Design tokens for the components. Each default matches a stock Tailwind value, so an app that
- * sets none of them gets the look below. Set any of them in the app's own @theme to restyle, or in
- * a selector such as .dark for a scoped theme.
+ * Design tokens for the components. The defaults are stock Tailwind values, except the focus ring,
+ * which uses the theme's --color-primary. Set a token in the app's own @theme to restyle, or in a
+ * selector such as .dark for a scoped theme.
  */
 @theme default {
   --radius-alert: var(--radius-lg);

package/src/ui/Alert.tsx

@@ -9,9 +9,8 @@ export interface AlertProps {
    */
   role?: "alert" | "status";
   /**
-   * Classes for placing the alert, such as a margin. Restyle it through the theme variables
-   * instead: whether a class that clashes with the alert's own wins depends on the order Tailwind
-   * emits them in.
+   * Classes for placing the alert, such as a margin. Restyle it through the theme variables. A
+   * class that clashes with the alert's own wins or loses by the order Tailwind emits them in.
    */
   className?: string;
   children: ReactNode;

package/src/ui/PasswordInput.tsx

@@ -14,7 +14,7 @@ export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputEl
   hidePasswordLabel?: string;
   /**
    * Classes for placing the field, such as a margin. They go on the outer element, which holds the
-   * label, the input and the error. Restyle the field through the theme variables instead.
+   * label, the input and the error. Restyle the field through the theme variables.
    */
   className?: string;
 }
@@ -30,11 +30,10 @@ export function PasswordInput({
   ...props
 }: PasswordInputProps) {
   const [visible, setVisible] = useState(false);
-  // Fall back to a generated id so the label is always tied to its own control. Not the name: two
-  // fields named "password" on one page, such as sign in next to sign up, would share an id.
+  // A generated id ties the label to its own control, even when two fields on a page share a name.
   const generated = useId();
   const inputId = id ?? generated;
-  // Built from useId rather than the name, since an id list in aria-describedby splits on spaces.
+  // From useId, which has no spaces. aria-describedby splits its ids on spaces.
   const errorId = `${generated}-error`;
 
   return (