@antelopejs/interface-dms 0.10.3 → 0.12.0

package/docs/5.html-render/1.introduction.md

@@ -1,19 +1,18 @@
 ---
 title: "Introduction"
-description: "Turn a named template and a props object into an HTML string, rendered by the frontend and delivered by your code — as an email, a file or a response."
+description: "Turn a named template and a props object into an HTML string. The frontend renders it, and your code delivers it as an email, a file or a response."
+mode: reference
 ---
 
-# Introduction
-
 ## Overview
 
-The `html-render` domain of `@antelopejs/interface-dms` turns a named template plus a props object into an HTML string. You declare a template once with `RegisterHtmlTemplate`, which records the name in a process-wide registry and hands back a typed reference; passing that reference to `GenerateHtml` produces the rendered HTML.
+The `html-render` domain of `@antelopejs/interface-dms` turns a named template and a props object into an HTML string. You declare a template once with `RegisterHtmlTemplate`. It records the name in a process-wide registry and returns a typed reference. Pass that reference to `GenerateHtml` to get the rendered HTML.
 
-Rendering itself does not happen in the backend process. `GenerateHtml` performs an HTTP `POST` to the render endpoint configured on the DMS (`htmlRender.renderEndpoint`), authenticated with a signed service token, and returns the HTML the endpoint sends back. The backend therefore owns the template *names* and the props *types*; the markup lives with the renderer behind that endpoint.
+The backend process does not render anything itself. `GenerateHtml` sends an HTTP `POST` to the render endpoint configured on the DMS (`htmlRender.renderEndpoint`), authenticated with a signed service token, and returns the HTML the endpoint sends back. The backend owns the template names and the props types. The markup lives with the renderer behind that endpoint.
 
-The interface produces HTML and nothing else. Delivering that HTML — as a transactional email, as a file, as a response body — is your code's job.
+The interface produces HTML and nothing else. Your code delivers that HTML, as a transactional email, a file or a response body.
 
-Everything below is exported from a single subpath:
+Everything below is exported from one subpath:
 
 ```typescript
 import {
@@ -29,23 +28,23 @@ import type {
 } from "@antelopejs/interface-dms/html-render";
 ```
 
-## Key Features
+## What the domain provides
 
-- **Named template registry** — `RegisterHtmlTemplate` records a template name at import time, so the whole process shares one catalogue of renderable templates.
-- **Documented props** — the type parameter on `RegisterHtmlTemplate` travels with the returned `HtmlTemplateRef`, recording on the reference itself which props the template expects.
-- **Remote rendering over HTTP** — `GenerateHtml` calls the configured render endpoint with a signed service token and resolves to the returned HTML string.
-- **Registry inspection** — `GetHtmlTemplate` and `GetAllHtmlTemplates` read back what has been registered, one name at a time or in bulk.
-- **Configurable endpoint and token** — `HtmlRenderConfig` types the `htmlRender` block of the DMS module configuration: endpoint URL, signing secret, token lifetime.
+- **A named template registry.** `RegisterHtmlTemplate` records a template name at import time, so the whole process shares one list of renderable templates.
+- **Documented props.** The type parameter of `RegisterHtmlTemplate` travels with the returned `HtmlTemplateRef`, so the reference records which props the template expects.
+- **Rendering over HTTP.** `GenerateHtml` calls the configured render endpoint with a signed service token and resolves to the returned HTML string.
+- **Registry lookups.** `GetHtmlTemplate` and `GetAllHtmlTemplates` read back what is registered, one name at a time or all at once.
+- **Endpoint and token settings.** `HtmlRenderConfig` types the `htmlRender` block of the DMS module configuration: the endpoint URL, the signing secret and the token lifetime.
 
 ## Dependencies
 
-This interface relies on the following AntelopeJS packages:
+This interface relies on one other AntelopeJS package:
 
-- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - `InterfaceFunction` and `RegisteringProxy`, the primitives the interface is built from.
+- [`@antelopejs/interface-core`](https://github.com/AntelopeJS/interface-core) provides `InterfaceFunction` and `RegisteringProxy`, the two helpers the interface is built from.
 
-## Quick Start
+## Quick start
 
-Register a template next to the code that uses it, then render it with props.
+Register a template next to the code that uses it, then render it with props. Registration runs when the module is imported, so keep the reference in module scope.
 
 ```typescript
 import {
@@ -58,7 +57,6 @@ interface WelcomeProps {
   activationLink: string;
 }
 
-// Registration happens at import time; keep the ref in module scope.
 const WelcomeTemplate = RegisterHtmlTemplate<WelcomeProps>("EmailWelcome");
 
 export async function buildWelcomeHtml(
@@ -69,13 +67,13 @@ export async function buildWelcomeHtml(
 }
 ```
 
-`GenerateHtml` needs the render endpoint to be reachable, so it belongs in request or job code — do not call it at import time.
+`GenerateHtml` needs a reachable render endpoint, so call it from request or job code, never at import time.
 
-## RegisterHtmlTemplate
+## `RegisterHtmlTemplate`
 
 Registers a template name and returns the reference you render with.
 
-```typescript
+```typescript fragment
 function RegisterHtmlTemplate<TProps = unknown>(
   name: string,
 ): HtmlTemplateRef<TProps>;
@@ -83,9 +81,9 @@ function RegisterHtmlTemplate<TProps = unknown>(
 
 | Parameter | Description |
 | --------- | ----------- |
-| `name` | The template identifier. It is the key the registry stores the template under, and the `templateName` sent to the render endpoint. |
+| `name` | The template identifier. The registry stores the template under this key, and `GenerateHtml` sends it to the render endpoint as `templateName`. |
 
-The type parameter `TProps` declares the props the template expects. It is carried by the returned [`HtmlTemplateRef`](#htmltemplateref) as a record of the template's shape; [`GenerateHtml`](#generatehtml) takes its `props` argument as `unknown`, so the compiler does not check the two against each other at the call site. Omitting `TProps` leaves the reference's props type as `unknown`.
+The type parameter `TProps` declares the props the template expects. The returned [`HtmlTemplateRef`](#htmltemplateref) carries it as a record of the template's shape. [`GenerateHtml`](#generatehtml) takes its `props` argument as `unknown`, so the compiler does not check the props against `TProps` at the call site. Without `TProps`, the reference's props type is `unknown`.
 
 ```typescript
 import { RegisterHtmlTemplate } from "@antelopejs/interface-dms/html-render";
@@ -100,51 +98,82 @@ export const InvoiceTemplate =
   RegisterHtmlTemplate<InvoiceProps>("EmailInvoice");
 ```
 
-The registry is keyed by name, so registering an existing name replaces the earlier entry. The DMS registers seven names for its own emails, listed in [Built-in Emails](/docs/interfaces/html-render/built-in-emails) — pick different names for your templates.
+The registry is keyed by name, so registering an existing name replaces the earlier entry. The DMS registers seven names for its own emails, listed in [Built-in emails](/docs/interfaces/html-render/built-in-emails). Give your templates other names.
 
-Call `RegisterHtmlTemplate` at module scope, in a file your module imports during startup. The returned reference is a plain object, so exporting it from that module is the usual way to share it.
+Call `RegisterHtmlTemplate` at module scope, in a file your module imports during startup. The returned reference is a plain object, so export it from that file to share it.
 
-The subpath also exports an `internal` namespace holding the registering proxy this function writes through. It is implementation detail — register through `RegisterHtmlTemplate`.
+The subpath also exports an `internal` namespace that holds the registering proxy this function writes through. It is marked `@internal`. Register through `RegisterHtmlTemplate` instead.
 
-## GenerateHtml
+## `GenerateHtml`
 
 Renders a registered template and resolves to the resulting HTML.
 
-```typescript
+```typescript fragment
 const GenerateHtml: (
   template: HtmlTemplateRef<unknown>,
   props: unknown,
+  language?: string,
 ) => Promise<string>;
 ```
 
 | Parameter | Description |
 | --------- | ----------- |
 | `template` | The reference returned by `RegisterHtmlTemplate`. Pass the reference, not the name string. |
-| `props` | The data the template renders with, serialised into the request body. The render endpoint expects a JSON object and rejects anything else with a `400`, so keep the props type an object shape. Typed `unknown` at this boundary, so the props type recorded on the reference is not enforced here — match it yourself. |
+| `props` | The data the template renders with, serialized into the request body. The DMS render endpoint expects a JSON object and answers `400` to anything else, so keep the props type an object shape. The parameter is typed `unknown`, so the compiler does not enforce the props type recorded on the reference. Match it yourself. |
+| `language` | Optional. The language to render in, sent in the `x-content-language` header. The DMS render endpoint renders in the language its first two letters name when a locale file exists for it, and in English otherwise. Without it, the template renders in English. |
 
 ```typescript
-import { GenerateHtml } from "@antelopejs/interface-dms/html-render";
-import { InvoiceTemplate } from "./templates";
-
-export async function renderInvoice(invoiceNumber: string): Promise<string> {
-  return GenerateHtml(InvoiceTemplate, {
-    invoiceNumber,
-    amount: "240.00 EUR",
-    dueDate: "2026-08-15",
-  });
+import {
+  GenerateHtml,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+
+interface InvoiceProps {
+  invoiceNumber: string;
+  amount: string;
+  dueDate: string;
+}
+
+const InvoiceTemplate = RegisterHtmlTemplate<InvoiceProps>("EmailInvoice");
+
+export async function renderInvoice(
+  invoiceNumber: string,
+  language: string,
+): Promise<string> {
+  return GenerateHtml(
+    InvoiceTemplate,
+    { invoiceNumber, amount: "240.00 EUR", dueDate: "2026-08-15" },
+    language,
+  );
 }
 ```
 
-The call `POST`s `{ templateName, props }` as JSON to `htmlRender.renderEndpoint`, with a service token signed from `htmlRender.serviceSecret` in the `x-dms-service-token` header, and reads the `html` field out of the JSON response.
+The call sends `{ templateName, props }` as JSON to `htmlRender.renderEndpoint`. It carries a service token signed with `htmlRender.serviceSecret` in the `x-dms-service-token` header, and it reads the `html` field of the JSON response.
+
+`GenerateHtml` does not look the name up in the registry before the call. It sends whatever name the reference carries. When the render endpoint does not know the name, the promise rejects. The backend runs no missing-template check of its own.
 
-`GenerateHtml` does not consult the registry before calling out: it sends whatever name the reference carries. A name the render endpoint does not know surfaces as a rejected promise, not as a missing-template check on the backend.
+The promise rejects in three cases:
 
-On a non-2xx response the promise rejects with an `Error` whose message starts with `Failed to render HTML template:`, followed by the response body's `error` string, its `statusMessage`, or `HTTP <status>`. When the endpoint is unreachable the underlying `fetch` failure propagates instead, without that prefix. Wrap the call when a failed render must not abort the surrounding operation:
+- On a non-2xx response, with an `Error` whose message starts with `Failed to render HTML template:`. The rest is the `message` string of the response body, else its `error` string, else its `statusMessage`, else `HTTP <status>`. The DMS render endpoint answers `401` with `Invalid service token`, `400` with `Invalid request body`, and `404` with `Template "<name>" not found or render failed`.
+- On a 2xx response without an `html` string, with the message `Failed to render HTML template: the render service answered no html`.
+- When the endpoint is unreachable, with the `fetch` error itself, without that prefix.
+
+To keep a failed render from stopping the surrounding operation, catch the rejection:
 
 ```typescript
 import { Logging } from "@antelopejs/interface-core/logging";
-import { GenerateHtml } from "@antelopejs/interface-dms/html-render";
-import { InvoiceTemplate } from "./templates";
+import {
+  GenerateHtml,
+  RegisterHtmlTemplate,
+} from "@antelopejs/interface-dms/html-render";
+
+interface InvoiceProps {
+  invoiceNumber: string;
+  amount: string;
+  dueDate: string;
+}
+
+const InvoiceTemplate = RegisterHtmlTemplate<InvoiceProps>("EmailInvoice");
 
 export async function renderInvoiceOrNull(
   invoiceNumber: string,
@@ -156,17 +185,18 @@ export async function renderInvoiceOrNull(
       dueDate: "2026-08-15",
     });
   } catch (error) {
-    Logging.Error(`Invoice render failed: ${(error as Error).message}`);
+    const reason = error instanceof Error ? error.message : String(error);
+    Logging.Error(`Invoice render failed: ${reason}`);
     return null;
   }
 }
 ```
 
-## GetHtmlTemplate
+## `GetHtmlTemplate`
 
-Looks a single template up in the registry.
+Looks one template up in the registry.
 
-```typescript
+```typescript fragment
 const GetHtmlTemplate: (key: string) => Promise<HtmlTemplateInfo | undefined>;
 ```
 
@@ -184,11 +214,11 @@ export async function isTemplateRegistered(name: string): Promise<boolean> {
 }
 ```
 
-## GetAllHtmlTemplates
+## `GetAllHtmlTemplates`
 
 Resolves to every registered template, keyed by name.
 
-```typescript
+```typescript fragment
 const GetAllHtmlTemplates: () => Promise<Record<string, HtmlTemplateInfo>>;
 ```
 
@@ -200,9 +230,9 @@ export async function listTemplateNames(): Promise<string[]> {
 }
 ```
 
-The result is a fresh object built from the registry, so mutating it does not change what is registered. Because registration happens as modules are imported, call this after startup rather than at import time if you want the complete set.
+The DMS builds a new object from the registry on each call, so changing the result does not change what is registered. Registration happens as modules are imported, so call this function after startup to get the complete set.
 
-## HtmlTemplateInfo
+## `HtmlTemplateInfo`
 
 What the registry stores for each template, and what `GetHtmlTemplate` and `GetAllHtmlTemplates` resolve to.
 
@@ -224,16 +254,16 @@ export async function describeTemplates(): Promise<string> {
 }
 ```
 
-## HtmlTemplateRef
+## `HtmlTemplateRef`
 
-The handle `RegisterHtmlTemplate` returns and `GenerateHtml` accepts.
+The reference `RegisterHtmlTemplate` returns and `GenerateHtml` accepts.
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
 | `name` | `string` | The template name sent to the render endpoint. |
-| `_propsType` | `TProps \| undefined` | Type-only carrier for the props type. It is never assigned a value; do not read it. |
+| `_propsType` | `TProps \| undefined` | Optional field that only carries the props type. `RegisterHtmlTemplate` never sets it. Do not read it. |
 
-Annotate the reference explicitly when you collect handles in a shared module and want the props type visible in that module's declarations:
+To keep the props type visible in the declarations of a module that collects references, annotate the reference:
 
 ```typescript
 import type { HtmlTemplateRef } from "@antelopejs/interface-dms/html-render";
@@ -248,24 +278,23 @@ export const AlertTemplate: HtmlTemplateRef<AlertProps> =
   RegisterHtmlTemplate<AlertProps>("EmailAlert");
 ```
 
-## HtmlRenderConfig
+## `HtmlRenderConfig`
 
 Types the `htmlRender` block of the DMS module configuration in `antelope.config.ts`.
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
-| `renderEndpoint` | `string` | Absolute URL `GenerateHtml` posts to. Default `http://localhost:3001/api/html/render`. |
-| `serviceSecret` | `string` | Secret used to sign the service token that authenticates the render call. Default `"dev"`, which the DMS refuses in production. |
-| `serviceTokenLifetime` | `number` | Lifetime of that service token, in milliseconds. The frontend render server rejects a token valid for more than five minutes. Default `300000` (5 minutes). |
+| `renderEndpoint` | `string` | The absolute URL `GenerateHtml` posts to. Default `http://localhost:3001/api/html/render`. |
+| `serviceSecret` | `string` | The secret that signs the service token of each render call. Default `"dev"`. The DMS refuses a production start when the value is empty or `"dev"`. |
+| `serviceTokenLifetime` | `number` | The lifetime of that service token, in milliseconds. The frontend render server rejects a token valid for more than five minutes. Default `300000` (five minutes). |
 
-The DMS merges the block you supply over those defaults, so a configuration only needs the keys it changes:
+The DMS merges the block you supply over those defaults, so a configuration needs only the keys it changes. In this example, `envOverrides` reads the secret from `DMS_HTML_RENDER_SECRET` at start:
 
 ```typescript
 import { defineConfig } from "@antelopejs/interface-core/config";
 
 export default defineConfig({
   name: "acme-admin",
-  // Read at start; a production start without it is refused by the DMS.
   envOverrides: {
     DMS_HTML_RENDER_SECRET: "modules.dms.config.htmlRender.serviceSecret",
   },
@@ -274,7 +303,7 @@ export default defineConfig({
       source: {
         type: "package",
         package: "@antelopejs/dms",
-        version: ">=0.4.3 <1.0.0",
+        version: "latest",
       },
       config: {
         htmlRender: {
@@ -286,11 +315,11 @@ export default defineConfig({
 });
 ```
 
-The Configuration chapter of the DMS guide covers where this block sits alongside the other DMS options.
+[Configuration](/docs/building/configuration#template-rendering-in-htmlrender) lists this block with the other DMS options.
 
-## Email Layout
+## Email layout
 
-The DMS ships the frame of its own emails as `EmailLayout`, which a module's email template (registered through `dms.email.ts`) may reuse: the branding logo, a card, an optional heading and a `footer` slot below a separator.
+The DMS ships the frame of its own emails as `EmailLayout`. A module's email template, registered through its `dms.email.ts`, can reuse it. The frame draws the branding logo and a white card that holds an optional heading, the content, and a `footer` slot below a separator.
 
 ```vue
 <script setup lang="ts">
@@ -319,34 +348,43 @@ defineProps<{ subject: string; preheader: string; locale: string }>();
 
 | Prop | Type | Description |
 | ---- | ---- | ----------- |
-| `title` | `string` (optional) | Drawn as the `h1` heading. Without it the email has no heading. |
+| `title` | `string` (optional) | Drawn as the `h1` heading. Without it, the email has no heading. |
 | `lang` | `string` (optional) | The `lang` of the document. Default `"en"`. |
-| `preheader` | `string` (optional) | Inbox preview text, hidden in the body. |
+| `preheader` | `string` (optional) | The inbox preview text, hidden in the body. |
 | `divider` | `boolean` (optional) | Draws the separator above the `footer` slot. Default `true`. |
-| `logoAlt` | `string` (optional) | Alternative text of the logo. Default `"Logo"`; pass `""` for a decorative logo. |
-| `publicLogoOnly` | `boolean` (optional) | Leaves the logo out unless a mail client can load it (see below). Default `false`. |
+| `logoAlt` | `string` (optional) | The alternative text of the logo. Default `"Logo"`. Pass `""` for a decorative logo. |
+| `publicLogoOnly` | `boolean` (optional) | Leaves the logo out unless a mail client can load it. The rules follow the table. Default `false`. |
 
-The `head` slot adds elements to the document head (a `<title>`, a viewport `<meta>`).
+The `head` slot adds elements to the document head, such as a `<title>` or a viewport `<meta>`.
 
-The logo is `branding.logo.email.light` from the app config, or `branding.logo.default.light` without an email logo, made absolute against `public.dms.clientBaseUrl` when it starts with `/`. A recipient's mail client fetches it from the internet, and Gmail and Outlook refuse SVG: with `publicLogoOnly`, the layout leaves the logo out when it is an SVG, is not an `http(s)` URL, or is served from a host a mail client cannot reach (`localhost`, `*.local`, `*.internal`, a loopback, private or link-local address), rather than drawing a broken image. Set a PNG logo and a public `clientBaseUrl` for it to show. A `branding.logo.email.dark` goes through the same rules and, when it differs from the light one, is offered to the mail clients in dark mode: the logo is then drawn as `<picture><source media="(prefers-color-scheme: dark)" srcset="…"><img …></picture>`, and a client that ignores the source draws the light image. The same check is exported as `emailLogoUrl(logoPath, clientBaseUrl)` from `#dms-layout/app/emails/components/index`, for a template that draws its own header.
+The logo is `branding.logo.email.light` from the app config, or `branding.logo.default.light` when no email logo is set. A logo path that starts with `/` is made absolute against `public.dms.clientBaseUrl`, or against the `DMS_CLIENT_BASE_URL` environment variable of the frontend server when it is set.
 
-### A rendered custom digest
+A recipient's mail client fetches the logo from the internet, and Gmail and Outlook refuse SVG. With `publicLogoOnly`, the layout leaves the logo out instead of drawing a broken image when the logo:
+
+- is an SVG,
+- does not resolve to an `http` or `https` URL, or
+- is served from a host a mail client cannot reach: `localhost`, a `*.localhost`, `*.local` or `*.internal` name, or a loopback, private or link-local address.
 
-The playground's `EmailPlaygroundDigest` reuses this layout with a preheader, `divider="false"` and `public-logo-only`. Here is its actual rendered HTML in English, with fictitious activity for Alex Morgan. With the default SVG logo, the header image is intentionally absent.
+Set a logo that is not an SVG, and a public `clientBaseUrl`, for the logo to show.
 
-![Rendered custom playground digest without a logo or footer divider](../images/emails-digest.png)
+A `branding.logo.email.dark` goes through the same rules. When it differs from the light logo, the layout offers it to mail clients in dark mode. The logo is then drawn as `<picture><source media="(prefers-color-scheme: dark)" srcset="…"><img …></picture>`, and a client that ignores the source draws the light image. The layout has no dark styles of its own. The card stays white on its pale grey background (`#f6f9fc`) in both modes, and only the logo changes.
 
-The same template below uses two demonstration PNG logos supplied through the app config. The light-mode capture selects the teal logo; the dark-mode capture selects the navy logo. The reserved demo hostname is mapped to a local image server for these captures, so they do not establish that a recipient can fetch the logo from the internet.
+`#dms-layout/app/emails/components/index` exports the same check as `emailLogoUrl(logoPath, clientBaseUrl)`, for a template that draws its own header. It returns the absolute URL, or `""` when the logo fails the rules.
+
+### A rendered custom digest
 
-![Custom digest with the light demonstration logo in browser light mode](../images/emails-digest-logo-light.png)
+The playground's `EmailPlaygroundDigest` template (`packages/dms/playground/frontend-vue/app/emails/EmailPlaygroundDigest.vue`) reuses this layout with a preheader, `:divider="false"` and `public-logo-only`. Rendered in English for a user named Alex Morgan, it contains:
 
-![Custom digest with the dark demonstration logo in browser dark mode](../images/emails-digest-logo-dark.png)
+- the heading **Your playground digest**,
+- the greeting `Hello Alex Morgan,`,
+- the line `<count> things happened in the playground since your last visit.`, with the same count in the hidden preheader,
+- the footer `Sent by the DMS playground's emails demo.`, with no separator above it.
 
-Dark mode changes the selected logo, not the card: `EmailLayout` keeps its white card and pale background in both browser modes. Without a dark logo source, the unbranded examples look identical in both modes. These captures use the real frontend render endpoint and show the returned HTML directly, not the playground's code viewer. No email is sent. Mail clients may strip `<picture>`, block remote images or transform colors; test delivery and appearance in your target clients separately.
+With the default SVG logo, the email has no logo at all. With a PNG light logo and a different PNG dark logo set in the app config, a mail client in light mode draws the light logo above the heading, and a client that follows dark mode draws the dark one. The card and the text keep the same colors in both modes. A local render does not show whether a recipient's mail client can fetch the logo from the internet.
 
-## Sending Rendered HTML as Email
+## Send rendered HTML as email
 
-Rendering and sending are separate steps. Render with `GenerateHtml`, then hand the string to the standard AntelopeJS email interface, which needs an implementing module (such as `@antelopejs/nodemailer`) loaded in your project configuration.
+Rendering and sending are separate steps. Render with `GenerateHtml`, then pass the string to the AntelopeJS email interface, `@antelopejs/interface-email`. That interface needs an implementing module, such as `@antelopejs/nodemailer`, loaded in your project configuration.
 
 ```typescript
 import { Send } from "@antelopejs/interface-email";
@@ -381,4 +419,4 @@ export async function sendReceipt(
 }
 ```
 
-This is the shape the DMS uses for its own account emails, and it keeps the two failure modes apart: a rejected `GenerateHtml` means the HTML was never produced, while a `success: false` response from `Send` means it was produced but not delivered.
+The DMS sends its own account emails the same way, and the two steps fail apart. A rejected `GenerateHtml` means the DMS never produced the HTML. A `success: false` response from `Send` means the HTML exists but the email was not delivered.

package/docs/5.html-render/2.built-in-emails.md

@@ -1,99 +1,119 @@
 ---
-title: "Built-in Emails"
-description: "The DMS sends seven emails of its own."
+title: "Built-in emails"
+description: "The seven emails the DMS sends: when each one goes out, its props, what it says, its language, its logo, and how to replace it."
+mode: reference
 ---
 
-# Built-in Emails
-
 ## Overview
 
-The DMS sends seven emails of its own. Each one is a template registered through [`RegisterHtmlTemplate`](/docs/interfaces/html-render/introduction#registerhtmltemplate), rendered by the frontend server from a Vue component in `frontend-vue/layers/dms-layout/app/emails/`, and delivered through `@antelopejs/interface-email`. They share one frame, `EmailLayout`: the branding logo, a white card, a heading, the body, a separator and a footer.
+The DMS sends seven emails of its own. Each one is a template registered through [`RegisterHtmlTemplate`](/docs/interfaces/html-render/introduction#registerhtmltemplate). The frontend server renders it from a Vue component in `frontend-vue/layers/dms-layout/app/emails/`, and the DMS delivers it through `Send` from `@antelopejs/interface-email`. The DMS sets no sender address, so every email goes out from the default sender of the email module your project loads.
 
 | Template | Sent when | Sent to | English subject |
 | -------- | --------- | ------- | ------- |
-| `EmailUserValidation` | A user signs up while `auth.mustValidateEmail` is on, or asks for a new code | The new account's address | `Verify Your Email` |
+| `EmailUserValidation` | With `auth.mustValidateEmail` on, a user who has not validated their email asks for a code, or an admin resends it from the Members page | The account's address | `Verify Your Email` |
 | `EmailResetPassword` | A user asks for a password reset | The account's address | `Reset Your Password` |
-| `EmailTwoFactor` | A user signs in with email as their second factor | The account's address | `Your verification code` |
-| `EmailAdminInvite` | A member is invited to the platform or to a workspace | The invited address | `You're invited to join <workspace> on <platform>`, shorter when a name is unknown |
+| `EmailTwoFactor` | A user signs in with email as their second factor, adds email as a second-factor method, or asks for a new code | The account's address | `Your verification code` |
+| `EmailAdminInvite` | A member is invited to the platform or to a workspace | The invited address | See [`EmailAdminInvite`](#emailadmininvite) |
 | `EmailChangeVerification` | A user asks to change their sign-in email | The new address | `Confirm your new sign-in email` |
 | `EmailChangeNotice` | The same request | The current address | `Your sign-in email is being changed` |
 | `EmailExportReady` | A data export delivered by email has finished | The user who asked for it | `Your data export is ready` |
 
-Each email, subject included, is written in the recipient's language, English or French (see [Language](#language)).
+An account created through an invitation link starts validated, so it receives no `EmailUserValidation`.
+
+Each email, subject included, is written in the recipient's language, English or French. See [Language](#language).
 
-These names are taken: pick other names for your own emails. To change what a built-in email looks like, see [Replacing a built-in email](#replacing-a-built-in-email).
+These names are taken. Give your own emails other names. To change what a built-in email looks like, see [Replacing a built-in email](#replacing-a-built-in-email).
 
 ## Props
 
-What the backend passes to each template. A template that replaces a built-in one receives the same props.
+The backend passes these props to each template. A template that replaces a built-in one receives the same props.
 
 | Template | Props |
 | -------- | ----- |
 | `EmailUserValidation` | `userName`, `validationCode`, `expiresInHours` (from `auth.emailValidationTokenLifetime`), `expiresIn` |
 | `EmailResetPassword` | `userName`, `resetCode`, `expiresInHours` (from `auth.passwordRecoverTokenLifetime`), `expiresIn` |
 | `EmailTwoFactor` | `userName`, `verificationCode` |
-| `EmailAdminInvite` | `email`, `signupLink`, `expiresInDays`, and when known `workspaceName`, `inviterName`, `platformName` (`meta.title`) |
+| `EmailAdminInvite` | `email`, `signupLink`, `expiresInDays`, and when known `workspaceName`, `inviterName` and `platformName` (`meta.title`) |
 | `EmailChangeVerification` | `userName`, `newEmail`, `code`, `expiresInHours` (from `auth.emailValidationTokenLifetime`), `expiresIn` |
 | `EmailChangeNotice` | `userName`, `newEmail` |
 | `EmailExportReady` | `userName`, `downloadLink`, `expiresInHours`, `expiresIn`, `partial`, `failedSources` (the export sources that could not be included) |
 
-`userName` is the user's name, or their email address when they have none. `expiresInHours` is the lifetime as a number, for the template to word in the recipient's language; `expiresIn` is the same lifetime already worded in English (`24 hours`), kept for templates written before `expiresInHours`.
-
-## Rendered examples
-
-These captures show HTML returned by the DMS frontend's real render endpoint, opened directly in Chromium, rather than the playground's HTML code viewer. All names, codes, addresses and links are fictitious; no email is sent. The default SVG logo is intentionally omitted by `publicLogoOnly`.
-
-### EmailUserValidation
-
-The signup email asks Alex to verify their address with a six-digit code, valid for 24 hours.
+`userName` is the user's name, or their email address when they have none. `expiresInHours` is the lifetime as a number, for the template to word in the recipient's language. `expiresIn` is the same lifetime already worded in English (`24 hours`). It stays for templates written before `expiresInHours` existed.
 
-![Rendered signup verification email with a six-digit code and a 24-hour expiry](../images/emails-user-validation.png)
+## What each email contains
 
-### EmailResetPassword
+Every built-in email uses the same frame, `EmailLayout`. A white card with rounded corners sits on a pale grey background. The card holds the logo when a mail client can load it (see [Logo](#logo)), a centered heading, the body text, a separator, and a footer in small, centered grey text. With the default SVG logo, the emails carry no logo.
 
-The password-reset email uses a separate code and the configured recovery lifetime: two hours in this example.
+A code sits in a grey box under the label `Your verification code is:`, in large monospaced characters. A link is a dark button with white text. An expiry line in small grey text follows the code or the button.
 
-![Rendered password-reset email with a two-hour code expiry](../images/emails-reset-password.png)
+The English text of each email follows, with the props in angle brackets. A lifetime in hours reads `1 hour` for one hour and `N hours` otherwise.
 
-### EmailTwoFactor
+### `EmailUserValidation`
 
-The second-factor email provides a sign-in code. Its footer tells the recipient to ignore the message if they did not attempt to sign in.
+- Heading: `Verify Your Email`.
+- Body: `Hello <userName>,`, then `Thank you for signing up! Enter the verification code below to verify your email address:`.
+- Code: `validationCode`, six uppercase letters and digits.
+- Expiry: `This code expires in <expiresInHours>.` The default `auth.emailValidationTokenLifetime` gives 24 hours.
+- Footer: `If you didn't create an account, you can safely ignore this email.`
 
-![Rendered email second-factor verification code](../images/emails-two-factor.png)
+### `EmailResetPassword`
 
-### EmailAdminInvite
+- Heading: `Reset Your Password`.
+- Body: `Hello <userName>,`, then `We received a request to reset your password. Enter the verification code below to reset your password:`.
+- Code: `resetCode`, six uppercase letters and digits, separate from the validation code.
+- Expiry: `This code expires in <expiresInHours>.` The default `auth.passwordRecoverTokenLifetime` gives 24 hours.
+- Footer: `If you didn't request a password reset, you can safely ignore this email. Your password will remain unchanged.`
 
-The invitation names the inviter, workspace and platform when they are known. Its button uses a fictitious destination here.
+### `EmailTwoFactor`
 
-![Rendered invitation from Jordan Lee to Northwind Studio on Acme Dashboard](../images/emails-admin-invite.png)
+- Heading: `Your verification code`.
+- Body: `Hello <userName>,`, then `Use this verification code to finish signing in:`.
+- Code: `verificationCode`, six digits. The email shows no expiry line.
+- Footer: `If you did not attempt to sign in, you can safely ignore this email.`
 
-### EmailChangeVerification
+### `EmailAdminInvite`
 
-The new address receives the code that confirms the sign-in email change.
+The invitation names the inviter, the workspace and the platform when the backend knows them.
 
-![Rendered confirmation email naming the new sign-in address and verification code](../images/emails-change-verification.png)
+- Subject: `<inviterName> invited you to join <target>` when the inviter is known, `You're invited to join <target>` otherwise, and `You're Invited to Join` when there is no target. The target is `<workspaceName> on <platformName>` when both are known, else whichever one is known.
+- Heading: `You're invited to <workspaceName>`, or `You're Invited!` without a workspace.
+- Body: `Hello,`, then the invitation line and `Click the button below to create your account:`. The invitation line is `<inviterName> invited you to join <target>.` when the inviter is known, `You've been invited to join <target>.` otherwise, and `You've been invited to join our platform.` when there is no target.
+- Button: `Create Account`, which opens `signupLink`.
+- Expiry: `This invitation expires in <expiresInDays> days.` The DMS sends 7 days.
+- Footer: `If you didn't expect this invitation, you can safely ignore this email.`
 
-### EmailChangeNotice
+### `EmailChangeVerification`
 
-The current address receives a notice, not the confirmation code. It tells the recipient what to do if they did not request the change.
+The new address receives the code that confirms the change.
 
-![Rendered security notice sent to the current sign-in address](../images/emails-change-notice.png)
+- Heading: `Confirm your new sign-in email`.
+- Body: `Hello <userName>,`, then `Enter the code below to make <newEmail> the sign-in email of your account:`.
+- Code: `code`, six digits.
+- Expiry: `This code expires in <expiresInHours>.`, from `auth.emailValidationTokenLifetime`.
+- Footer: `If you didn't ask for this change, you can safely ignore this email: your account keeps its current address.`
 
-### EmailExportReady
+### `EmailChangeNotice`
 
-A complete export provides a download button and an expiry. A partial export also names the sources that could not be included.
+The current address receives a notice, not the confirmation code.
 
-![Rendered complete data-export email with a download button and expiry](../images/emails-export-ready.png)
+- Heading: `Your sign-in email is being changed`.
+- Body: `Hello <userName>,`, then `Someone signed in to your account asked to change its sign-in email to <newEmail>. The change takes effect once that address is confirmed.`
+- Footer: `If this wasn't you, change your password now and sign out the other sessions in Security: your account keeps this address until the new one is confirmed.`
 
-![Rendered partial data-export email warning that Activity history is missing](../images/emails-export-partial.png)
+### `EmailExportReady`
 
-These are browser previews, not Gmail, Outlook or Apple Mail compatibility tests. See [Email Layout](/docs/interfaces/html-render/introduction#email-layout) for the custom digest, logo variants and the limits of dark-mode support.
+- Heading: `Your data export is ready`.
+- Body: `Hello <userName>,`, then `Your data export has been prepared. Use the button below to download the archive:`.
+- Button: `Download export`, which opens `downloadLink`.
+- Expiry: `This download link expires in <expiresInHours>.` An export link lasts 24 hours.
+- Partial export: when `partial` is true, a further paragraph says the export is **incomplete**, lists `failedSources` separated by commas, and asks the recipient to request a new export if they need those parts.
+- Footer: `If you didn't request this export, you can safely ignore this email.`
 
 ## Language
 
-Each email is written in the recipient's language: the account's `language`, or for an invitation the language it was sent in. English and French are supported; any other language falls back to English.
+Each email is written in the recipient's language. That is the account's `language`, or for an invitation the language the invitation was sent in. English and French are supported, and any other language falls back to English.
 
-The body text lives in the `dms-layout` locale files (`i18n/locales/layout-*.json`), under one key per email (`emails.user_validation`, `emails.reset_password`, `emails.two_factor`, `emails.admin_invite`, `emails.email_change_verification`, `emails.email_change_notice`, `emails.export_ready`) plus the shared `emails.common`. Locale files merge in module priority order, so a module registered with a priority above the DMS's (`0`) can reword any of these keys in its own `i18n/locales/*.json`:
+The body text lives in the `dms-layout` locale files (`i18n/locales/layout-*.json`). Each email has one key: `emails.user_validation`, `emails.reset_password`, `emails.two_factor`, `emails.admin_invite`, `emails.email_change_verification`, `emails.email_change_notice` and `emails.export_ready`. The shared texts sit under `emails.common`. Locale files merge in module priority order. A module registered with a priority above the DMS's (`0`) can reword any of these keys in its own `i18n/locales/*.json`:
 
 ```json [frontend-vue/i18n/locales/acme-en-GB.json]
 {
@@ -105,13 +125,13 @@ The body text lives in the `dms-layout` locale files (`i18n/locales/layout-*.jso
 }
 ```
 
-The subject is set by the backend, which sends it in the same language. It cannot be reworded from a module.
+The backend sets the subject, in the same language. A module cannot reword it.
 
 ## Logo
 
-Every built-in email draws `branding.logo.email.light` from the app config, or `branding.logo.default.light` when no email logo is set (see [Email Layout](/docs/interfaces/html-render/introduction#email-layout)), with `publicLogoOnly` on. The logo shows only when a mail client can load it: a PNG or JPEG served from a public `http(s)` address. The default DMS logo is an SVG, which Gmail and Outlook refuse, so out of the box the emails carry no logo. To show yours, set an `email` logo in your layer's `app/app.config.ts`, and serve the dashboard from a public `clientBaseUrl`:
+Every built-in email draws `branding.logo.email.light` from the app config, or `branding.logo.default.light` when no email logo is set, with `publicLogoOnly` on. See [Email layout](/docs/interfaces/html-render/introduction#email-layout) for the rules. The logo shows only when a mail client can load it, which means an image other than SVG served from a public `http` or `https` address. The default DMS logo is an SVG, which Gmail and Outlook refuse, so by default the emails carry no logo. To show yours, set an `email` logo in your layer's `app/app.config.ts`, and serve the dashboard from a public `clientBaseUrl`:
 
-```ts [frontend-vue/app/app.config.ts]
+```ts fragment [frontend-vue/app/app.config.ts]
 export default defineDmsAppConfig({
   branding: {
     logo: {
@@ -124,13 +144,13 @@ export default defineDmsAppConfig({
 });
 ```
 
-The loader hands every layer's `app/app.config.ts` to the email renderer too (`@antelopejs/dms-frontend` 0.6.0 or later), merged in module priority order, so a module registered with a priority above the DMS's (`0`) wins. `dark` is optional: when it passes the same check and differs from `light`, the header becomes a `<picture>` whose dark source the mail clients that follow the reader's dark mode pick, and the others draw `light`.
+The email renderer reads every layer's `app/app.config.ts`, merged in module priority order, so the config of a module registered with a priority above the DMS's (`0`) wins. `dark` is optional. When it passes the same rules and differs from `light`, the header becomes a `<picture>`. Mail clients that follow the reader's dark mode pick its dark source, and the others draw `light`.
 
 ## Replacing a built-in email
 
-The render server looks a template up by its file name, in module priority order, and renders the first match. A module registered with a `priority` above the DMS's (`0`, see [`AddFrontendModule`](/docs/interfaces/core/pages-and-modules#addfrontendmoduleoptions)) therefore replaces a built-in email by shipping a component of the same name in its `dms.email.ts`:
+The render server looks a template up by its file name, in module priority order, and renders the first match. A module registered with a `priority` above the DMS's (`0`, see [`AddFrontendModuleOptions`](/docs/interfaces/core/pages-and-modules#addfrontendmoduleoptions)) replaces a built-in email when its `dms.email.ts` ships a component of the same name:
 
-```ts [frontend-vue/dms.email.ts]
+```ts fragment [frontend-vue/dms.email.ts]
 export const serverEmailTemplates = import.meta.glob("./app/emails/**/*.vue");
 ```
 
@@ -154,4 +174,4 @@ const { t, locale } = useI18n();
 </template>
 ```
 
-The replacement receives the props listed in [Props](#props) and keeps the backend's subject. Do not register the name again with `RegisterHtmlTemplate`: the DMS already sends it. At equal priority the first module by id wins, so set the priority explicitly rather than relying on it.
+The replacement receives the props listed in [Props](#props) and keeps the backend's subject. Do not register the name again with `RegisterHtmlTemplate`, because the DMS already registers and sends it. At equal priority, the module whose id sorts first wins, so set the priority explicitly.