feat(engagement): templates — the email block family, renderer and seeded set (engagement Phase 5a)

Every subject and body moves out of `mailer.js` into `engagement_templates` rows an
operator can edit. A relocation, not a regression: nothing that sends mail today
starts depending on an operator authoring something first.

- `email.*` block family in its own registry, sharing the page family's envelope
  walk and validate-then-sanitize order by binding rather than by copy.
- A server-side renderer producing both parts of a multipart message; the text
  part is byte-identical to the literals this commit deletes.
- Nine seeded templates, six of them wired now; the seeder's `customized = 0`
  guard lives in the UPDATE's own WHERE.
- `renderByKey` falls back to the shipped seed when a row is missing or unusable,
  so no failure of the table can stop a password reset.

Also fixes `check:hosts` reading the template key `auth.email-verify` as the
hostname `auth.email`.

Co-Authored-By: Claude <noreply@anthropic.com>

server/src/engagement/templateSeeds.js

@@ -0,0 +1,285 @@
+// ── The shipped template set (§4.6.1) ──────────────────────────────────────
+//
+// "A fresh deployment mails correctly before anyone opens the editor." Every body
+// that used to be a template literal inside `utils/mailer.js` is a row here, so
+// Phase 5 is a RELOCATION rather than a regression: nothing that sends mail today
+// starts depending on an operator authoring something first.
+//
+// **Nine seeds, six of them wired in this phase.** The five transactional bodies
+// plus `auth.email-verify` (which §4.6.1 lists as "new — Phase 9" and which Phase
+// 1b in fact already shipped) are rendered by `mailer` from this moment. The three
+// notification seeds are seeded but not yet rendered by anything: `notify.digest`
+// and `notify.team-post` belong to `teamNotify`/`teamDigestWorker`, which Phase 6
+// rewrites onto the engine, and `inapp.event` to the channel Phase 7 builds.
+// Settled with the org lead: seed all nine now so those phases open something
+// rather than shipping seeds of their own — a seeder bump is the mechanism of last
+// resort (property 3 below), not a per-phase routine.
+//
+// **`seedVersion` is the whole "improve a default without stealing an operator's
+// work" mechanism.** Bump it when a body changes; the seeder updates rows where
+// `customized = 0` and skips rows where it is 1. Do NOT bump it for a comment.
+//
+// ── Two conventions the bodies follow, both of which are visible to operators ──
+//
+// **1. Presentational fragments are variables, because templates have no logic.**
+// `mailer` used to build ` for the account “Darrow”` with a ternary. A template
+// cannot, by design (interpolate.js: no conditionals). So the ternary stays at the
+// call site and its RESULT arrives as a variable — `forWhom` — whose `example`
+// shows exactly what it produces, leading space and quotes included. That is the
+// price of a logic-free template language, and it is paid here rather than by
+// giving operator-authored data a conditional to get wrong.
+//
+// **2. Ambient brand variables are supplied by the renderer, not by the caller.**
+// `siteName`, `siteUrl`, `logoUrl` and `year` are available to every template and
+// cannot be overridden by whatever a caller passes (`engagement/templates.js`).
+// §4.6.1 property 2: "no template contains a literal hex code or a logo URL", so
+// one prebuilt image running as any shard mails in that shard's identity.
+
+// The ambient set, declared once so the editor's palette (Phase 5b) can offer them
+// on EVERY template rather than each seed having to list them.
+const AMBIENT_VARIABLES = Object.freeze([
+  { name: 'siteName', type: 'string', required: true, example: 'UOMysticmoon' },
+  { name: 'siteUrl', type: 'string', required: false, example: 'https://example.com' },
+  { name: 'logoUrl', type: 'string', required: false, example: 'https://example.com/brand/logo.png' },
+  { name: 'year', type: 'string', required: true, example: '2026' },
+])
+
+// A tiny helper so the block arrays below read as content rather than as JSON.
+const text = (id, body, opts = {}) => ({
+  id,
+  type: 'email.text',
+  props: opts.muted ? { text: body, muted: true } : { text: body },
+})
+const heading = (id, body, level = 'h1') => ({
+  id,
+  type: 'email.heading',
+  props: { level, text: body },
+})
+const button = (id, label, url, textLead) => ({
+  id,
+  type: 'email.button',
+  props: textLead ? { label, url, textLead } : { label, url },
+})
+const itemList = (id, variable, emptyText) => ({
+  id,
+  type: 'email.itemList',
+  props: emptyText ? { variable, emptyText } : { variable },
+})
+const divider = (id) => ({ id, type: 'email.divider', props: {} })
+
+const SEEDS = [
+  // ── Transactional: protected = 1, editable but not deletable ─────────────
+  {
+    key: 'auth.password-reset',
+    name: 'Password reset',
+    channel: 'email',
+    protected: true,
+    seedVersion: 1,
+    subject: 'Reset your {{siteName}} password',
+    variables: [
+      { name: 'username', type: 'string', required: false, example: 'Darrow' },
+      { name: 'forWhom', type: 'string', required: false, example: ' for the account “Darrow”' },
+      { name: 'resetUrl', type: 'string', required: true, example: 'https://example.com/reset/abc123' },
+    ],
+    blocks: [
+      text('p1', 'We received a request to reset the password{{forWhom}} at {{siteName}}.'),
+      button('cta', 'Choose a new password', '{{resetUrl}}', 'Choose a new password here:'),
+      text(
+        'p2',
+        'This link is single-use and expires in about an hour. If you didn\'t request this, ' +
+          'you can safely ignore this email — your password won\'t change.',
+      ),
+    ],
+  },
+  {
+    key: 'auth.invite',
+    name: 'Account invite',
+    channel: 'email',
+    protected: true,
+    seedVersion: 1,
+    subject: 'Your {{siteName}} invitation',
+    variables: [
+      { name: 'acceptUrl', type: 'string', required: true, example: 'https://example.com/invite/abc123' },
+      { name: 'roleLabel', type: 'string', required: false, example: ' as moderator' },
+      { name: 'invitedBy', type: 'string', required: false, example: ' by Aldric' },
+    ],
+    blocks: [
+      text('p1', 'You have been invited{{invitedBy}} to join {{siteName}}{{roleLabel}}.'),
+      button('cta', 'Accept your invitation', '{{acceptUrl}}', 'Accept your invitation and set up your account here:'),
+      text('p2', 'This link is single-use and will expire. If you weren\'t expecting this, you can ignore it.'),
+    ],
+  },
+  {
+    key: 'auth.email-verify',
+    name: 'Email address confirmation',
+    channel: 'email',
+    protected: true,
+    seedVersion: 1,
+    subject: 'Confirm your email address for {{siteName}}',
+    variables: [
+      { name: 'username', type: 'string', required: false, example: 'Darrow' },
+      { name: 'forWhom', type: 'string', required: false, example: ' “Darrow”' },
+      { name: 'verifyUrl', type: 'string', required: true, example: 'https://example.com/verify/abc123' },
+    ],
+    blocks: [
+      text('p1', 'The {{siteName}} account{{forWhom}} asked to use this address for contact and account recovery.'),
+      button('cta', 'Confirm this address', '{{verifyUrl}}', 'Confirm it here:'),
+      text(
+        'p2',
+        'This link is single-use and expires in about a day. Until it is used, nothing changes — ' +
+          'the account keeps whatever address it had.',
+      ),
+      text(
+        'p3',
+        'If you did not ask for this, you can ignore this email. Someone may have mistyped their ' +
+          'own address; no account of yours is affected and this link grants no access to anything.',
+      ),
+    ],
+  },
+  {
+    key: 'admin.contact-message',
+    name: 'Contact form message',
+    channel: 'email',
+    protected: true,
+    seedVersion: 1,
+    // `fromLabel` and `fromName` are the SAME missing name with two different
+    // fallbacks — 'a visitor' in the subject, 'unknown' in the body. That
+    // divergence is inherited from the literal this replaces, and the template is
+    // where it becomes visible and fixable: an operator who wants one word can now
+    // edit the subject line instead of a source file.
+    subject: '{{siteName}} contact from {{fromLabel}}',
+    variables: [
+      { name: 'fromLabel', type: 'string', required: true, example: 'a visitor' },
+      { name: 'fromName', type: 'string', required: true, example: 'unknown' },
+      { name: 'fromEmail', type: 'string', required: true, example: 'ann@example.com' },
+      { name: 'message', type: 'string', required: true, example: 'Is the shard open to new players?' },
+    ],
+    blocks: [
+      text('p1', 'From: {{fromName}} <{{fromEmail}}>'),
+      text('p2', '{{message}}'),
+    ],
+  },
+  {
+    key: 'admin.test',
+    name: 'Delivery test',
+    channel: 'email',
+    protected: true,
+    seedVersion: 1,
+    subject: '{{siteName}} email test',
+    variables: [
+      { name: 'transport', type: 'string', required: true, example: 'smtp' },
+      { name: 'sentAt', type: 'string', required: false, example: '2026-08-29 18:04 UTC' },
+    ],
+    blocks: [
+      text('p1', 'This is a test message confirming {{transport}} email delivery is working.'),
+    ],
+  },
+
+  // ── Notification: protected = 0, replaceable ─────────────────────────────
+  //
+  // **`notify.event` and `notify.digest` are generic on purpose** (§4.6.1 property
+  // 1): their variables are structural — `title`, `intro`, `items[]` — rather than
+  // domain-specific, so a trigger from core or from any module renders through
+  // them with NO authoring at all. This is what stops "add a trigger" from meaning
+  // "and now write a template".
+  {
+    key: 'notify.event',
+    name: 'Notification (single event)',
+    channel: 'email',
+    protected: false,
+    seedVersion: 1,
+    subject: '{{title}}',
+    variables: [
+      { name: 'title', type: 'string', required: true, example: 'Your house is close to collapsing' },
+      { name: 'intro', type: 'string', required: false, example: 'The Silver Anvil in Britain has entered its final decay stage.' },
+      { name: 'items', type: 'list', required: false, example: [{ heading: 'The Silver Anvil', excerpt: 'Britain, Trammel (1119, 1794)' }] },
+      { name: 'actionUrl', type: 'string', required: false, example: 'https://example.com/houses' },
+      { name: 'unsubscribeUrl', type: 'string', required: false, example: 'https://example.com/unsubscribe/abc123' },
+    ],
+    blocks: [
+      heading('h', '{{title}}'),
+      text('intro', '{{intro}}'),
+      itemList('items', 'items'),
+      button('cta', 'Open {{siteName}}', '{{actionUrl}}'),
+      divider('rule'),
+      button('unsub', 'Unsubscribe', '{{unsubscribeUrl}}', 'To stop these emails, use this link:'),
+    ],
+  },
+  {
+    key: 'notify.digest',
+    name: 'Notification digest',
+    channel: 'email',
+    protected: false,
+    seedVersion: 1,
+    subject: '{{siteName}}: {{periodLabel}}',
+    variables: [
+      { name: 'periodLabel', type: 'string', required: true, example: 'your daily summary' },
+      { name: 'intro', type: 'string', required: false, example: 'Here is what happened while you were away.' },
+      { name: 'items', type: 'list', required: false, example: [{ heading: 'New thread in Guild Hall', excerpt: 'Meeting moved to Friday', url: 'https://example.com/teams/1?thread=9' }] },
+      // Precomputed for the same reason `forWhom` is: "and 3 more" needs a
+      // conditional and a plural, and a template has neither.
+      { name: 'moreNote', type: 'string', required: false, example: 'and 3 more.' },
+      { name: 'scopeUrl', type: 'string', required: false, example: 'https://example.com/teams/1' },
+      { name: 'unsubscribeUrl', type: 'string', required: false, example: 'https://example.com/unsubscribe/abc123' },
+    ],
+    blocks: [
+      text('intro', '{{intro}}'),
+      itemList('items', 'items'),
+      text('more', '{{moreNote}}', { muted: true }),
+      button('cta', 'Open {{siteName}}', '{{scopeUrl}}'),
+      divider('rule'),
+      button('unsub', 'Unsubscribe', '{{unsubscribeUrl}}', 'To stop these emails, use this link:'),
+    ],
+  },
+  {
+    key: 'notify.team-post',
+    name: 'Team post notification',
+    channel: 'email',
+    protected: false,
+    seedVersion: 1,
+    subject: '{{teamName}}: {{threadTitle}}',
+    variables: [
+      { name: 'teamName', type: 'string', required: true, example: 'The Silver Anvil' },
+      { name: 'authorName', type: 'string', required: true, example: 'Aldric' },
+      { name: 'threadTitle', type: 'string', required: true, example: 'Meeting moved to Friday' },
+      { name: 'excerpt', type: 'string', required: false, example: 'We are pushing this week back a day so more people can make it.' },
+      { name: 'threadUrl', type: 'string', required: false, example: 'https://example.com/teams/1?thread=9' },
+      { name: 'unsubscribeUrl', type: 'string', required: false, example: 'https://example.com/unsubscribe/abc123' },
+    ],
+    blocks: [
+      text('p1', '{{authorName}} posted in {{teamName}}.'),
+      heading('h', '{{threadTitle}}', 'h2'),
+      text('excerpt', '{{excerpt}}', { muted: true }),
+      button('cta', 'Read the thread', '{{threadUrl}}'),
+      divider('rule'),
+      button('unsub', 'Unsubscribe', '{{unsubscribeUrl}}', 'To stop these emails for this team, use this link:'),
+    ],
+  },
+  {
+    key: 'inapp.event',
+    name: 'On-site notification',
+    channel: 'inapp',
+    protected: false,
+    seedVersion: 1,
+    // No subject: an inbox row has a title, and the title is a block. The column
+    // is email's, and leaving it NULL is how a non-email template says so.
+    subject: null,
+    variables: [
+      { name: 'title', type: 'string', required: true, example: 'Your house is close to collapsing' },
+      { name: 'body', type: 'string', required: false, example: 'The Silver Anvil in Britain has entered its final decay stage.' },
+      { name: 'url', type: 'string', required: false, example: 'https://example.com/houses' },
+    ],
+    blocks: [
+      heading('h', '{{title}}', 'h3'),
+      text('body', '{{body}}'),
+      button('cta', 'Open', '{{url}}'),
+    ],
+  },
+]
+
+/** @returns {object|null} the seed definition for `key`. */
+function seedByKey(key) {
+  return SEEDS.find((s) => s.key === key) || null
+}
+
+module.exports = { SEEDS, AMBIENT_VARIABLES, seedByKey }