@sjolystinnovation/app-kit 0.21.0 → 0.22.0

package/src/seo/environment.ts

@@ -1,9 +1,9 @@
-/** Values of `SITE_ENV` that name the live site. `prod` is what the deploy workflows pass. */
+/** The values of `SITE_ENV` that name the live site. The deploy workflows pass `prod`. */
 const PRODUCTION = new Set(["production", "prod", ""]);
 
 /**
- * Whether this deployment is the one search engines should index. An unset `SITE_ENV` counts as
- * production, so a missing variable is never what deindexes the live site.
+ * Checks whether this deployment is the one search engines should index. An unset `SITE_ENV` counts
+ * as production, so a missing variable is never what deindexes the live site.
  */
 export function isIndexableEnvironment(siteEnv: string | undefined = process.env.SITE_ENV): boolean {
   return PRODUCTION.has(siteEnv?.trim().toLowerCase() ?? "");

package/src/seo/index.ts

@@ -4,7 +4,6 @@ export { ref, serializeGraph, type OrganizationInfo, type SchemaNode, type Schem
 export {
   defineSite,
   LEGAL_PAGE_KEYS,
-  normalizePath,
   NOINDEX,
   SHARE_IMAGE_SIZE,
   type Crumb,

package/src/seo/og/index.tsx

@@ -3,20 +3,21 @@ import { SHARE_IMAGE_SIZE } from "../site";
 
 export { SHARE_IMAGE_SIZE };
 
+/** Options for `shareImage`. */
 export interface ShareImageInput {
   name: string;
   tagline: string;
   /**
-   * Colours as literals. The image renders outside the browser, so it cannot read CSS custom
+   * The colors as literals. The image renders outside the browser, so it cannot read CSS custom
    * properties. `primary` is the bar above the name.
    */
   colors: { background: string; foreground: string; primary: string };
 }
 
 /**
- * The default share preview: the name, a bar in the brand colour and the tagline. Return it from a
- * route such as `[locale]/og/route.tsx`, which `pageMetadata` points at. A route, not the
- * `opengraph-image` file convention, since a page's own `openGraph` block replaces that image.
+ * Renders the default share preview: the name, a bar in the brand color, and the tagline. Return it
+ * from a route such as `[locale]/og/route.tsx`, which `pageMetadata` points at. It is a route, not
+ * the `opengraph-image` file convention, since a page's own `openGraph` block replaces that image.
  */
 export function shareImage({ name, tagline, colors }: ShareImageInput): ImageResponse {
   return new ImageResponse(

package/src/seo/schema.ts

@@ -10,9 +10,10 @@ export interface SchemaRef {
   "@id": string;
 }
 
+/** Creates a reference to the node with this `@id`. */
 export const ref = (id: string): SchemaRef => ({ "@id": id });
 
-/** The JSON-LD document for one page. `<` is escaped, so the payload cannot close the script tag. */
+/** Serializes the JSON-LD document for one page. `<` is escaped, so the payload cannot close the script tag. */
 export function serializeGraph(nodes: SchemaNode[]): string {
   return JSON.stringify({
     "@context": "https://schema.org",
@@ -20,7 +21,10 @@ export function serializeGraph(nodes: SchemaNode[]): string {
   }).replace(/</g, "\\u003c");
 }
 
-/** The business as the API describes it. Blank fields are left out of the structured data. */
+/**
+ * The business as the API describes it. The structured data leaves out blank fields, except the
+ * street address, which falls back to the one-line address.
+ */
 export interface OrganizationInfo {
   name: string;
   legalName?: string | undefined;

package/src/seo/site.ts

@@ -9,12 +9,13 @@ export const SHARE_IMAGE_SIZE = { width: 1200, height: 630 } as const;
 /** The robots directive for pages that exist for signed-in users only. */
 export const NOINDEX: Metadata["robots"] = { index: false, follow: false };
 
+/** Options for `defineSite`. */
 export interface SiteConfig<L extends string> {
-  /** The site's name, as in titles, Open Graph and structured data. */
+  /** The site's name, as in titles, Open Graph, and structured data. */
   name: string;
   /** The canonical origin, such as `https://www.example.no`, without a trailing slash. */
   url: string;
-  /** Between a page title and the site name, such as `" | "`. */
+  /** The text between a page title and the site name, such as `" | "`. */
   titleSeparator: string;
   /** The locale segments every page is under, such as `["no", "en"]`. A site without them omits this. */
   locales?: readonly L[] | undefined;
@@ -28,6 +29,7 @@ export interface SiteConfig<L extends string> {
   shareImagePath?: string | undefined;
 }
 
+/** Options for `pageMetadata`. */
 export interface PageMetadataInput<L extends string> {
   locale: L;
   /** The path below the locale segment, such as `/builds/my-pc`. Omit for the front page. */
@@ -35,10 +37,11 @@ export interface PageMetadataInput<L extends string> {
   /** The page title, without the site name. The root layout's template adds it. */
   title?: string | undefined;
   description?: string | undefined;
-  /** Image URLs for the share preview. Defaults to the share image for the locale. */
+  /** The image URLs for the share preview. Defaults to the share image for the locale. */
   images?: string[] | undefined;
 }
 
+/** Options for `siteMetadata`. */
 export interface SiteMetadataInput<L extends string> {
   locale: L;
   description?: string | undefined;
@@ -46,54 +49,60 @@ export interface SiteMetadataInput<L extends string> {
   manifest?: string | undefined;
 }
 
+/** One step in a breadcrumb trail. */
 export interface Crumb {
   name: string;
   /** A site-relative path, such as `/no/builds`. The last crumb is the current page and has none. */
   path?: string | undefined;
 }
 
+/** Options for `localeEntries`. */
 export interface LocaleEntryOptions<L extends string> {
   /** The locales the page exists in. Defaults to all of them. A site without locales ignores it. */
   locales?: readonly L[] | undefined;
-  /** When the page last changed, per locale. Left out when unknown. A site without locales calls it once, with no locale. */
+  /** A function that returns when the page last changed in a locale. An unknown date is left out. A site without locales calls it once, with no locale. */
   lastModified?: ((locale: L) => Date | undefined) | undefined;
 }
 
 /** The legal pages every site has, as `createLegalService` names them. */
 export const LEGAL_PAGE_KEYS = ["terms", "privacy", "cookies"] as const;
 
+/** Options for `legalEntries`. */
 export interface LegalEntriesInput<K extends string, L extends string> {
   /** The legal pages, each at `/<key>` below the locale. Defaults to `LEGAL_PAGE_KEYS`. */
   keys?: readonly K[] | undefined;
-  /** When a page last changed, as the API's timestamp. A site without locales gets no locale. */
+  /** A function that returns when a page last changed, as the API's timestamp. A site without locales passes no locale. */
   updatedAt: (key: K, locale: L | undefined) => Promise<string | null | undefined>;
 }
 
+/** Options for `robots`. */
 export interface RobotsInput {
-  /** Paths below each locale segment that must not be crawled, such as `/admin`. */
+  /** The paths below each locale segment that must not be crawled, such as `/admin`. */
   privatePaths?: readonly string[] | undefined;
-  /** Paths outside the locale segments that must not be crawled, such as `/api/`. */
+  /** The paths outside the locale segments that must not be crawled, such as `/api/`. */
   privateRootPaths?: readonly string[] | undefined;
   /** Whether search engines may index this deployment. Defaults to `isIndexableEnvironment()`. */
   indexable?: boolean | undefined;
 }
 
+/** Options for `organizationNode`. */
 export interface OrganizationOptions {
   /** The schema.org type, such as `ComputerStore`, or several, such as `["Organization", "LocalBusiness"]`. Defaults to `Organization`. */
   type?: string | readonly string[] | undefined;
-  /** Pages about the same business elsewhere, such as its entry in Brønnøysundregistrene. */
+  /** The pages about the same business elsewhere, such as its entry in Brønnøysundregistrene. */
   sameAs?: readonly string[] | undefined;
   /** The ISO country code for the address and the area served. Defaults to `NO`. */
   country?: string | undefined;
-  /** Site-relative paths of the square image and the logo. Default to `/icon.png` and `/logo.png`. */
+  /** The site-relative path of the square image. Defaults to `/icon.png`. */
   image?: string | undefined;
+  /** The site-relative path of the logo. Defaults to `/logo.png`. */
   logo?: string | undefined;
 }
 
 /**
- * One leading slash, no trailing slash. `""` and `"/"` both mean the front page. Tabs and line
- * breaks are removed, as a URL parser removes them, and leading slashes and backslashes collapse
- * to one, so a path always stays on the site's own host.
+ * Normalizes a site path to one leading slash and no trailing slash. `""` and `"/"` both mean the
+ * front page. Tabs and line breaks are removed, as a URL parser removes them, and leading slashes
+ * and backslashes collapse to one, so a path always stays on the site's own host.
  */
 export function normalizePath(path: string): string {
   const clean = path.replace(/[\t\n\r]/g, "");
@@ -103,8 +112,8 @@ export function normalizePath(path: string): string {
 }
 
 /**
- * The URL, metadata, sitemap, robots and structured data helpers for one site, bound to its name,
- * canonical origin and locales.
+ * Creates the URL, metadata, sitemap, robots, and structured data helpers for one site, bound to its
+ * name, canonical origin, and locales.
  */
 export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   const locales = config.locales ?? [];
@@ -113,11 +122,11 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   const shareImagePath = config.shareImagePath ?? "/og";
   const origin = new URL(config.url).origin;
 
-  /** A site-relative URL for a page in one locale, such as `/no/builds`. A site without locales has no segment. */
+  /** Builds a site-relative URL for a page in one locale, such as `/no/builds`. A site without locales has no segment. */
   const localePath = (locale: L | undefined, path = ""): string =>
     locale === undefined || locales.length === 0 ? normalizePath(path) || "/" : `/${locale}${normalizePath(path)}`;
 
-  /** An absolute URL on the canonical origin, without a trailing slash. */
+  /** Builds an absolute URL on the canonical origin, without a trailing slash. */
   const absoluteUrl = (path = ""): string => {
     const url = new URL(normalizePath(path) || "/", config.url);
     // A path that would leave the site's origin gives the front page instead.
@@ -127,7 +136,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
 
   const absoluteLocaleUrl = (locale: L, path = ""): string => absoluteUrl(localePath(locale, path));
 
-  /** Language alternates by BCP 47 tag. `x-default` points at the default locale. */
+  /** Builds the language alternates by BCP 47 tag. `x-default` points at the default locale. */
   const languageAlternates = (path: string): Record<string, string> => ({
     ...Object.fromEntries(locales.map(l => [tag(l), localePath(l, path)])),
     ...(defaultLocale !== undefined ? { "x-default": localePath(defaultLocale, path) } : {}),
@@ -145,7 +154,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     alt: fullTitle(locale),
   });
 
-  /** The canonical URL, hreflang set and Open Graph for one public page. */
+  /** Builds the canonical URL, hreflang set, and Open Graph for one public page. */
   const pageMetadata = ({ locale, path = "", title, description, images }: PageMetadataInput<L>): Metadata => {
     const canonical = localePath(locale, path);
     return {
@@ -167,7 +176,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     };
   };
 
-  /** The metadata for the locale root layout: the title template, the index directive and the front page's canonical. */
+  /** Builds the metadata for the locale root layout: the title template, the index directive, and the front page's canonical. */
   const siteMetadata = ({ locale, description, manifest }: SiteMetadataInput<L>): Metadata => {
     const title = fullTitle(locale);
     return {
@@ -180,12 +189,13 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   };
 
   /**
-   * One sitemap entry per locale a page is served in, each listing the others as alternates. A site
-   * without locales has one URL per page, so it gets one entry with no alternates.
+   * Builds one sitemap entry per locale a page is served in, each listing the others as alternates.
+   * A site without locales has one URL per page, so it gets one entry with no alternates.
    */
   const localeEntries = (path: string, options: LocaleEntryOptions<L> = {}): MetadataRoute.Sitemap => {
     if (locales.length === 0) {
-      // There is no locale to pass, and the callback's type cannot say so without making every caller's simpler.
+      // There is no locale to pass. The callback's type cannot say so without making every caller
+      // handle undefined.
       const lastModified = options.lastModified?.(undefined as never);
       return [{ url: absoluteUrl(path), ...(lastModified ? { lastModified } : {}) }];
     }
@@ -202,14 +212,14 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     });
   };
 
-  /** Runs `load` for every locale at once and keys the results by locale. A site without locales gets `{}`. */
+  /** Runs `load` for every locale in parallel and keys the results by locale. A site without locales gets `{}`. */
   const forEachLocale = async <T>(load: (locale: L) => Promise<T>): Promise<Partial<Record<L, T>>> =>
     Object.fromEntries(await Promise.all(locales.map(async locale => [locale, await load(locale)] as const))) as Partial<Record<L, T>>;
 
   /**
-   * The legal pages' sitemap entries, each dated by when it last changed in that locale. The
-   * timestamps are fetched at once. An error from `updatedAt` fails the sitemap, so a stale one is
-   * served rather than one without dates.
+   * Builds the legal pages' sitemap entries, each dated by when it last changed in that locale. The
+   * timestamps are fetched in parallel. An error from `updatedAt` fails the sitemap, so a stale one
+   * is served rather than one without dates.
    */
   const legalEntries = async <K extends string = (typeof LEGAL_PAGE_KEYS)[number]>({
     keys,
@@ -224,8 +234,9 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   };
 
   /**
-   * robots.txt. A deployment that is not production disallows everything. Otherwise the private
-   * paths are disallowed under every locale segment, since a bare `/admin` matches nothing there.
+   * Builds robots.txt. A deployment that is not production disallows everything. Otherwise the
+   * private paths are disallowed under every locale segment, since a bare `/admin` matches nothing
+   * there.
    */
   const robots = ({ privatePaths = [], privateRootPaths = [], indexable = isIndexableEnvironment() }: RobotsInput = {}): MetadataRoute.Robots => {
     if (!indexable) return { rules: { userAgent: "*", disallow: "/" } };
@@ -238,11 +249,11 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     };
   };
 
-  /** An `@id` for an entity that is the same on every page. Page-scoped nodes use the page URL. */
+  /** Builds an `@id` for an entity that is the same on every page. Page-scoped nodes use the page URL. */
   const siteId = (fragment: string): string => `${config.url}/#${fragment}`;
   const ids = { organization: siteId("organization"), website: siteId("website") } as const;
 
-  /** The business, under a stable `@id` that page-scoped nodes point at. */
+  /** Builds the business node, under a stable `@id` that page-scoped nodes point at. */
   const organizationNode = (company: OrganizationInfo, options: OrganizationOptions = {}): SchemaNode => {
     const country = options.country ?? "NO";
     const type = typeof options.type === "string" ? options.type || undefined : options.type?.length ? [...options.type] : undefined;
@@ -273,7 +284,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     };
   };
 
-  /** The site as an entity, so search engines attribute its pages to it and to the business. */
+  /** Builds the site as an entity, so search engines attribute its pages to it and to the business. */
   const webSiteNode = (locale: L): SchemaNode => ({
     "@type": "WebSite",
     "@id": ids.website,
@@ -283,7 +294,7 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
     publisher: ref(ids.organization),
   });
 
-  /** The trail search results show in place of the raw URL. The last crumb has no `item`. */
+  /** Builds the trail that search results show in place of the raw URL. The last crumb has no `item`. */
   const breadcrumbNode = (crumbs: Crumb[], pageUrl: string): SchemaNode => ({
     "@type": "BreadcrumbList",
     "@id": `${pageUrl}#breadcrumb`,
@@ -326,4 +337,5 @@ export function defineSite<L extends string = string>(config: SiteConfig<L>) {
   };
 }
 
+/** The helpers `defineSite` returns. */
 export type Site<L extends string = string> = ReturnType<typeof defineSite<L>>;

package/src/seo/sitemap.ts

@@ -1,11 +1,11 @@
-/** The latest of a set of timestamps, or undefined when there are none. */
+/** Gets the latest of a set of timestamps, or undefined when there are none. */
 export function latest(dates: readonly (Date | undefined)[]): Date | undefined {
   const known = dates.filter((date): date is Date => date != null);
   if (known.length === 0) return undefined;
   return known.reduce((newest, date) => (date > newest ? date : newest));
 }
 
-/** Parses an API timestamp. A missing or malformed value gives undefined. */
+/** Parses an API timestamp. Returns undefined for a missing or malformed value. */
 export function parseTimestamp(value: string | null | undefined): Date | undefined {
   if (!value) return undefined;
   const date = new Date(value);

package/src/server/publicApi.ts

@@ -1,20 +1,23 @@
+/** A response from `publicGetWithMeta`, with its `Last-Modified` date. */
 export interface PublicResponse<T> {
   data: T;
-  /** From the `Last-Modified` header, when the endpoint reports one. */
+  /** The date from the `Last-Modified` header, when the endpoint reports one. */
   lastModified: Date | null;
 }
 
+/** Options for one public GET. */
 export interface PublicGetOptions {
-  /** Cache tags, so a revalidate route can purge this fetch by tag. */
+  /** The cache tags, so a revalidate route can purge this fetch by tag. */
   tags?: string[] | undefined;
 }
 
+/** Options for `createPublicApi`. */
 export interface PublicApiOptions {
-  /** Seconds a cached response stays fresh. Defaults to 60. */
+  /** The seconds a cached response stays fresh. Defaults to `60`. */
   revalidate?: number | undefined;
 }
 
-/** The API could not be reached, or answered with no usable content. */
+/** Thrown when the API could not be reached, or answered with no usable content. */
 export class PublicApiError extends Error {
   readonly path: string;
   readonly status: number | null;
@@ -36,9 +39,10 @@ function lastModifiedOf(response: Response): Date | null {
 }
 
 /**
- * Cached GETs against the API's anonymous endpoints, for server components and route handlers.
+ * Creates cached GETs against the API's anonymous endpoints, for server components and route
+ * handlers.
  *
- * A 404 gives null. An unreachable or failing API throws `PublicApiError`, so a failed fetch is
+ * A 404 returns null. An unreachable or failing API throws `PublicApiError`, so a failed fetch is
  * never cached as an empty page in place of a working one.
  */
 export function createPublicApi(baseUrl: string, options: PublicApiOptions = {}) {
@@ -51,7 +55,7 @@ export function createPublicApi(baseUrl: string, options: PublicApiOptions = {})
 
   // The path is joined onto the base URL. A path that does not start with a single "/" is a bug in
   // the caller, so it throws. A path with a dot segment, often a slug from the URL, names no resource,
-  // so it gives null, the same as a 404. A slug goes through encodeURIComponent first.
+  // so it gives null, the same as a 404. Pass a slug through encodeURIComponent first.
   function urlFor(path: string): string | null {
     if (!path.startsWith("/") || path.startsWith("//")) {
       throw new Error(`Public API path must start with a single "/" under the base URL: ${path}`);
@@ -85,12 +89,12 @@ export function createPublicApi(baseUrl: string, options: PublicApiOptions = {})
     }
   }
 
-  /** The data alone. Null when the resource does not exist. */
+  /** Gets the data alone. Returns null when the resource does not exist. */
   async function publicGet<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
     return (await publicGetWithMeta<T>(path, opts))?.data ?? null;
   }
 
-  /** For data a page can do without. Null on any failure, so the page still renders. */
+  /** Gets data a page can do without. Returns null when the API fails, so the page still renders. */
   async function publicGetOptional<T>(path: string, opts: PublicGetOptions = {}): Promise<T | null> {
     try {
       return await publicGet<T>(path, opts);

package/src/server/revalidateRoute.ts

@@ -4,11 +4,12 @@ import jwt from "jsonwebtoken";
 import { getToken, type JWT } from "next-auth/jwt";
 import { ABSOLUTE_SESSION_MAX_AGE, CLOCK_TOLERANCE_S, isTerminalSessionError } from "../session/expiry";
 
+/** Options for `createRevalidateRoute`. */
 export interface RevalidateRouteOptions {
   /**
-   * Each target the client may send, with the page paths it purges. A path with a dynamic segment,
-   * such as `/builds/[slug]`, purges every page of that route. The target name is also purged as a
-   * cache tag, so tag fetches with it.
+   * The targets the client may send, each with the page paths it purges. A path with a dynamic
+   * segment, such as `/builds/[slug]`, purges every page of that route. The route also purges the
+   * target name as a cache tag, so tag fetches with it.
    */
   targets: Record<string, readonly string[]>;
   /** The role allowed to purge, as it appears in the session user's roles. */
@@ -19,10 +20,10 @@ type Token = JWT | null;
 
 const rolesOf = (token: Token): string[] => (token?.user as { roles?: string[] } | undefined)?.roles ?? [];
 
-// getToken only decrypts the cookie, without the jwt callback. So the checks that callback makes are
-// made here: a refused refresh still carries its roles, and the cookie outlives the seven days. The
-// roles must also come from an access token that has not expired, so a copied cookie of a user who
-// lost the role stops working within the token's lifetime.
+// getToken only decrypts the cookie, without the jwt callback. So this file repeats the checks that
+// callback makes: a refused refresh still carries its roles, and the cookie outlives the seven
+// days. The roles must also come from an access token that has not expired, so a copied cookie of a
+// user who lost the role stops working within the token's lifetime.
 function isLive(token: Token): boolean {
   if (!token || isTerminalSessionError(token.error as string | undefined)) return false;
   const loginAt = token.loginAt;
@@ -40,7 +41,8 @@ function accessTokenValid(accessToken: unknown): boolean {
 }
 
 /**
- * A `POST` route handler that purges cached pages after an edit, for `app/api/revalidate/route.ts`.
+ * Creates a `POST` route handler that purges cached pages after an edit, for
+ * `app/api/revalidate/route.ts`.
  * It answers 403 unless the caller has a live session with `role`, 415 unless the body is JSON, and
  * 400 for a target it does not know.
  */

package/src/session/expiry.ts

@@ -1,11 +1,11 @@
-/** How long a session lasts after sign-in, however often it is refreshed. Seven days. */
+/** How long a session lasts after sign-in, in milliseconds, however often it is refreshed. Seven days. */
 export const ABSOLUTE_SESSION_MAX_AGE = 7 * 24 * 60 * 60 * 1000;
 
-/** How far this server's clock may differ from the API's when a token's times are checked. */
+/** How far this server's clock may differ from the API's, in seconds, when a token's times are checked. */
 export const CLOCK_TOLERANCE_S = 60;
 
 /**
- * Errors the jwt callback sets when the session cannot be recovered without a new sign-in. A
+ * The 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.
  */
@@ -31,7 +31,7 @@ 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. */
+/** Checks 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);
 }
@@ -58,19 +58,21 @@ function emit(): void {
   for (const listener of [...state.listeners]) listener();
 }
 
-/** Ask the user to sign in again without leaving the page. */
+/** Asks the user to sign in again without leaving the page. */
 export function openSessionPrompt(): void {
   if (state.open) return;
   state.open = true;
   emit();
 }
 
+/** Closes the re-sign-in prompt. */
 export function closeSessionPrompt(): void {
   if (!state.open) return;
   state.open = false;
   emit();
 }
 
+/** Subscribes to the prompt opening and closing. Returns a function that unsubscribes. */
 export function subscribeSessionPrompt(listener: () => void): () => void {
   state.listeners.add(listener);
   return () => {
@@ -78,6 +80,7 @@ export function subscribeSessionPrompt(listener: () => void): () => void {
   };
 }
 
+/** Checks whether the re-sign-in prompt is open. */
 export function getSessionPromptOpen(): boolean {
   return state.open;
 }

package/src/session/react/AppSessionProvider.tsx

@@ -6,14 +6,15 @@ import type { ReactNode } from "react";
 /** Four minutes, shorter than the five minutes before expiry when a refresh falls due. */
 const SESSION_POLL_SECONDS = 4 * 60;
 
+/** Props for `AppSessionProvider`. */
 export interface AppSessionProviderProps {
-  /** Seconds between session reads. Defaults to four minutes. */
+  /** The seconds between session reads. Defaults to four minutes. */
   refetchInterval?: number | undefined;
   children: ReactNode;
 }
 
 /**
- * next-auth's `SessionProvider`, reading the session again on a timer. Each read lets the jwt
+ * Wraps next-auth's `SessionProvider` and reads the session again on a timer. Each read lets the jwt
  * callback renew the access token ahead of expiry, so an open tab stays usable and does not find a
  * dead session on the next save. It also keeps what `useSession` reports in this tab up to date.
  * next-auth polls only once a session exists, so signed-out visitors cost nothing.

package/src/{ui → session/react}/CredentialsForm.tsx

@@ -2,26 +2,27 @@
 
 import { signIn } from "next-auth/react";
 import { useState, type FormEvent, type ReactNode } from "react";
-import { SIGN_IN_ERRORS } from "../session/expiry";
-import { Alert } from "./Alert";
-import { PasswordInput } from "./PasswordInput";
+import { SIGN_IN_ERRORS } from "../expiry";
+import { Alert } from "../../ui/Alert";
+import { PasswordInput } from "../../ui/PasswordInput";
 import {
   SignInRejected,
   defaultCredentialsFormStrings,
   type CredentialsFormStrings,
 } from "./credentialsFormStrings";
-import { TextInput } from "./TextInput";
-import { withDefaults, type TextOverrides } from "./withDefaults";
+import { TextInput } from "../../ui/TextInput";
+import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
 
 
+/** Props for `CredentialsForm`. */
 export interface CredentialsFormProps {
   initialEmail?: string | undefined;
-  /** Runs after next-auth accepts the credentials. Throw `SignInRejected` to refuse with a reason. */
+  /** A function that runs after next-auth accepts the credentials. Throw `SignInRejected` from it to refuse with a reason. */
   onSignedIn: () => void | Promise<void>;
-  /** Extra buttons next to the submit button, such as a close button. */
+  /** The extra buttons next to the submit button, such as a close button. */
   children?: ReactNode;
   strings?: TextOverrides<CredentialsFormStrings> | undefined;
-  /** Runs when a sign-in starts and when it ends, such as to stop a dialog closing mid-request. */
+  /** A function that runs when a sign-in starts and when it ends, such as to stop a dialog closing mid-request. */
   onPendingChange?: ((pending: boolean) => void) | undefined;
 }
 
@@ -32,7 +33,7 @@ function refusedForCsrf(url: string | null | undefined): boolean {
   return parsed.pathname.endsWith("/signin") && parsed.searchParams.get("csrf") === "true";
 }
 
-/** Email and password sign-in through next-auth's credentials provider. */
+/** Renders email and password sign-in through next-auth's credentials provider. */
 export function CredentialsForm({
   initialEmail = "",
   onSignedIn,

package/src/{ui → session/react}/LoginPage.tsx

@@ -2,23 +2,24 @@
 
 import Link from "next/link";
 import { useRouter } from "next/navigation";
-import { authLinkClassName, authPageClassName, authTitleClassName } from "./authClasses";
+import { authLinkClassName, authPageClassName, authTitleClassName } from "../../ui/authClasses";
 import { CredentialsForm } from "./CredentialsForm";
 import type { CredentialsFormStrings } from "./credentialsFormStrings";
 import { defaultLoginPageStrings, type LoginPageStrings } from "./loginPageStrings";
-import { withDefaults, type TextOverrides } from "./withDefaults";
+import { withDefaults, type TextOverrides } from "../../ui/withDefaults";
 
+/** Props for `LoginPage`. */
 export interface LoginPageProps {
-  /** Where a signed-in user goes. */
+  /** The path a signed-in user goes to. */
   redirectTo: string;
-  /** The password reset page. */
+  /** The password reset page's path. */
   resetHref: string;
-  /** The sign-up page. Without it the page has no register link. */
+  /** The sign-up page's path. Without it, the page has no register link. */
   registerHref?: string | undefined;
   strings?: TextOverrides<LoginPageStrings> | undefined;
   /** The form's own text, passed to `CredentialsForm`. */
   formStrings?: TextOverrides<CredentialsFormStrings> | undefined;
-  /** Replaces the page's outer spacing, such as when the page sits inside the app's own card. */
+  /** The classes that replace the page's outer spacing, such as when the page sits inside the app's own card. */
   className?: string | undefined;
 }
 

package/src/session/react/ProtectedGate.tsx

@@ -4,10 +4,11 @@ import { useRouter } from "next/navigation";
 import { useEffect, type ReactNode } from "react";
 import { useSessionGate } from "./useSessionGate";
 
+/** Props for `ProtectedGate`. */
 export interface ProtectedGateProps {
-  /** Where a signed-out visitor, or a session dead on arrival, is sent. */
+  /** The path a signed-out visitor, or a session dead on arrival, is sent to. */
   loginHref: string;
-  /** What shows while the page may not render yet. */
+  /** The content shown while the page may not render yet. */
   fallback?: ReactNode | undefined;
   children: ReactNode;
 }

package/src/session/react/RoleGate.tsx

@@ -7,23 +7,24 @@ import { useSessionGate } from "./useSessionGate";
 interface RoleGateBase {
   /** The role the page needs, as it appears in `session.user.roles`. */
   role: string;
-  /** What shows while the session or its roles are not known yet. */
+  /** The content shown while the session or its roles are not known yet. */
   fallback?: ReactNode | undefined;
   children: ReactNode;
 }
 
-/** Shows `denied` to a signed-in user without the role. */
+/** The props that show `denied` to a signed-in user without the role. */
 interface RoleGateWithDenied extends RoleGateBase {
   denied: ReactNode;
   deniedHref?: never;
 }
 
-/** Sends a signed-in user without the role to `deniedHref`. */
+/** The props that send a signed-in user without the role to `deniedHref`. */
 interface RoleGateWithDeniedHref extends RoleGateBase {
   deniedHref: string;
   denied?: never;
 }
 
+/** Props for `RoleGate`. Pass either `denied` or `deniedHref`. */
 export type RoleGateProps = RoleGateWithDenied | RoleGateWithDeniedHref;
 
 /**