@cosmicdrift/kumiko-renderer-mail-html 0.0.0-stage → 0.363.0

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-renderer-mail-html
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# renderer-mail-html
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plugin für `renderer-foundation`. Rendert `RenderRequest { kind: "mail" }` zu Betreff + Email-safe HTML + plain-text: **Mail-Template (Dokument-HTML + `meta.subject`) -> isolierter Handlebars -> MJML-Layout -> html-to-text**.
+
+## Pipeline
+
+```
+RenderRequest { kind: "mail", payload: { slug, locale, variables, unsubscribeUrl? } }
+                            ↓
+   1. Template laden      resolveTemplate(slug, kind "mail", locale), nur contentFormat html,
+                          meta.subject Pflicht
+   2. Layout laden        meta.layoutSlug ?? "default", kind "mail-layout";
+                          tenant -> system -> in-code DEFAULT_MAIL_LAYOUT_MJML
+   3. Body kompilieren    compileDocumentBodyToHandlebars (template-resolver): span[data-variable],
+                          Links, Listenzeilen -> Handlebars-Quelle; Autoren-Klammern sind inert
+   4. Rendern             Handlebars.create() mit Helfern money/date/link, HTML-Escaping an;
+                          Betreff + Preview-Text ohne Escaping, CR/LF entfernt
+   5. Layout              Body als Datum (`{{{content}}}`), nie in die Layout-Quelle konkateniert;
+                          Layout-Kontext nur: content, subject, previewText, tenantName,
+                          signature, imprint, unsubscribeUrl
+   6. mjml + html-to-text
+                            ↓
+   RenderResponse { kind: "mail", subject, html, text, previewText? }
+```
+
+Datum und Zahlen formatiert der Renderer nach `payload.locale`, der Sprache der Vorlage, im langen Datumsformat („1. Oktober 2026“). `ctx.config` (optional) liefert die Währung (tenant-settings) und `tenantName` (Branding-Titel); ohne Config gelten `EUR` und `""`.
+
+## Mount
+
+```typescript
+import { createRendererMailHtmlFeature } from "@cosmicdrift/kumiko-renderer-mail-html";
+import { createTemplateResolverFeature } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+
+const features = [
+  createTemplateResolverFeature(),    // Vorausgesetzt
+  createRendererFoundationFeature(),  // Vorausgesetzt
+  createRendererMailHtmlFeature(),    // Dieses Plugin
+];
+```
+
+Mail-Texte kommen aus `r.notification({ variables, template, meta })`; `applyBootSeeds` legt sie als System-Templates an.
+
+## Caller-Pattern
+
+```typescript
+const foundation = requireRendererFoundation(ctx, "sendWelcomeMail");
+const renderer = foundation.createRendererForTenant({ tenantId, kind: "mail" });
+
+const result = await renderer.render(
+  {
+    kind: "mail",
+    payload: {
+      slug: "my-feature:notify:welcome",
+      locale: "de",
+      variables: { name: user.name, verifyUrl: "https://..." },
+    },
+  },
+  { db: ctx.db, registry: ctx.registry, tenantId, config: ctx.config },
+);
+
+await ctx.mailTransport.send({ to: user.email, subject: result.subject, html: result.html, text: result.text });
+```
+
+## Tenant-Branding
+
+Ein Tenant legt ein eigenes Layout als Template `kind: "mail-layout"`, `contentFormat: "mjml"`, Slug `default` (oder den Slug aus `meta.layoutSlug`) an. Es gewinnt gegen System-Layout und in-code Default. Das Layout sieht nur die oben genannten Variablen; den Body setzt es mit `{{{content}}}` ein.
+
+## Optionales Seeding
+
+```typescript
+import { seedSystemMailLayout } from "@cosmicdrift/kumiko-renderer-mail-html/seeding";
+
+await seedSystemMailLayout(db); // idempotent
+```
+
+Ohne Seeding läuft das Plugin trotzdem und fällt auf `DEFAULT_MAIL_LAYOUT_MJML` zurück.
+
+## Out-of-Scope
+
+- Visual-Editor für Layouts
+- Inline-Image-Embedding (CID-Attachments)
+- PDF/Image -> andere Plugins (`renderer-puppeteer-client`)
+- Mail-Versand -> `delivery` + `channel-email` + `mail-transport-*`

package/dist/default-layout.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_MAIL_LAYOUT_SLUG } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+export declare const DEFAULT_MAIL_LAYOUT_MJML = "<mjml>\n  <mj-head>\n    <mj-title>{{subject}}</mj-title>\n    <mj-preview>{{previewText}}</mj-preview>\n    <mj-attributes>\n      <mj-all font-family=\"Helvetica, Arial, sans-serif\" />\n      <mj-text font-size=\"14px\" color=\"#333\" line-height=\"1.6\" />\n    </mj-attributes>\n  </mj-head>\n  <mj-body background-color=\"#f5f5f5\">\n    <mj-section background-color=\"#ffffff\" padding=\"20px\">\n      <mj-column>\n        <mj-text font-size=\"22px\" font-weight=\"bold\" color=\"#111\">{{tenantName}}</mj-text>\n      </mj-column>\n    </mj-section>\n    <mj-section background-color=\"#ffffff\" padding=\"20px\">\n      <mj-column>\n        <mj-text>{{{content}}}</mj-text>\n      </mj-column>\n    </mj-section>\n    <mj-section background-color=\"#f5f5f5\" padding=\"20px\">\n      <mj-column>\n        <mj-text font-size=\"11px\" color=\"#888\" align=\"center\">\n          {{#if tenantName}}Sent by {{tenantName}}{{/if}}{{#if unsubscribeUrl}} \u00B7 <a href=\"{{link unsubscribeUrl}}\">Unsubscribe</a>{{/if}}\n        </mj-text>\n      </mj-column>\n    </mj-section>\n  </mj-body>\n</mjml>";

package/dist/default-layout.js

@@ -0,0 +1,48 @@
+// Default MJML layout that apps can use out of the box for mail templates. The
+// renderer falls back to it when neither tenant nor system has a "mail-layout"
+// template with the requested slug (default: "default").
+//
+// **Variables the layout receives (nothing else):**
+//   - {{tenantName}}      - header + footer
+//   - {{{content}}}       - the rendered mail body (escaped values), triple-stash.
+//                           It sits in mj-text: mj-raw would put block HTML straight into
+//                           the column tbody, where browsers move it out of the table into
+//                           the column div with font-size 0, so the body turns invisible.
+//   - {{subject}}         - mj-title
+//   - {{previewText}}     - inbox preview line
+//   - {{unsubscribeUrl}}  - optional footer link
+//
+// **Tenant override:** upsert a template of kind "mail-layout", contentFormat
+// "html" (structured: data-content slot plus header/signature/footer regions),
+// slug "default" (or the slug a mail names in meta.layoutSlug). Raw mjml is
+// system-only.
+export { DEFAULT_MAIL_LAYOUT_SLUG } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+export const DEFAULT_MAIL_LAYOUT_MJML = `<mjml>
+  <mj-head>
+    <mj-title>{{subject}}</mj-title>
+    <mj-preview>{{previewText}}</mj-preview>
+    <mj-attributes>
+      <mj-all font-family="Helvetica, Arial, sans-serif" />
+      <mj-text font-size="14px" color="#333" line-height="1.6" />
+    </mj-attributes>
+  </mj-head>
+  <mj-body background-color="#f5f5f5">
+    <mj-section background-color="#ffffff" padding="20px">
+      <mj-column>
+        <mj-text font-size="22px" font-weight="bold" color="#111">{{tenantName}}</mj-text>
+      </mj-column>
+    </mj-section>
+    <mj-section background-color="#ffffff" padding="20px">
+      <mj-column>
+        <mj-text>{{{content}}}</mj-text>
+      </mj-column>
+    </mj-section>
+    <mj-section background-color="#f5f5f5" padding="20px">
+      <mj-column>
+        <mj-text font-size="11px" color="#888" align="center">
+          {{#if tenantName}}Sent by {{tenantName}}{{/if}}{{#if unsubscribeUrl}} · <a href="{{link unsubscribeUrl}}">Unsubscribe</a>{{/if}}
+        </mj-text>
+      </mj-column>
+    </mj-section>
+  </mj-body>
+</mjml>`;

package/dist/document-kit.d.ts

@@ -0,0 +1,16 @@
+import type { RendererContext } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import { type LayoutRegions, type TemplateResolverApi, type TemplateResource } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import Handlebars from "handlebars";
+export type DocumentFormat = {
+    readonly locale: string;
+    readonly currency: string;
+};
+export declare function createDocumentHandlebars(format: DocumentFormat): typeof Handlebars;
+export declare function compileDocumentSource(hbs: typeof Handlebars, source: string, options?: {
+    readonly noEscape?: boolean;
+}): HandlebarsTemplateDelegate;
+export declare function readDocumentFormat(ctx: RendererContext, templateLocale: string): Promise<DocumentFormat>;
+export declare function readTenantName(ctx: RendererContext): Promise<string>;
+export declare function resolveResourceFileRefs(tplApi: TemplateResolverApi, ctx: RendererContext, template: TemplateResource, keys: readonly string[]): Promise<ReadonlyMap<string, string>>;
+export declare function collectRegionResourceKeys(regions: LayoutRegions): readonly string[];
+export declare function mergeResourceFileRefs(bodyRefs: ReadonlyMap<string, string>, layoutRefs: ReadonlyMap<string, string>): ReadonlyMap<string, string>;

package/dist/document-kit.js

@@ -0,0 +1,136 @@
+import { BRANDING_QN } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { collectDocumentResourceKeys, TemplateNotFoundError, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { isUuid, SYSTEM_TENANT_ID, TENANT_CURRENCY_CONFIG_KEY, } from "@cosmicdrift/kumiko-framework/engine";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { formatMoney, resolveSafeMoneyLocale } from "@cosmicdrift/kumiko-headless";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import Handlebars from "handlebars";
+// Handlebars instance, template resolution and resource lookup shared by the
+// mail and PDF renderers, so both format money/dates and find images the same way.
+const FALLBACK_CURRENCY = "EUR";
+const SAFE_LINK_PROTOCOL = /^(https?:|mailto:)/i;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function createDocumentHandlebars(format) {
+    const hbs = Handlebars.create();
+    hbs.registerHelper("money", (value) => {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return formatMoney(value, format.currency, format.locale);
+        }
+        if (isPlainRecord(value)) {
+            const { amount, currency } = value;
+            if (typeof amount === "number" && Number.isFinite(amount) && typeof currency === "string") {
+                return formatMoney(amount, currency, format.locale);
+            }
+        }
+        return value === undefined || value === null ? "" : String(value);
+    });
+    hbs.registerHelper("date", (value) => {
+        if (typeof value !== "string" && typeof value !== "number") {
+            return value === undefined || value === null ? "" : String(value);
+        }
+        const locale = resolveSafeMoneyLocale(format.locale);
+        try {
+            // A date-only string has no zone; going through an instant would show the
+            // previous day west of UTC.
+            if (typeof value === "string" && DATE_ONLY.test(value)) {
+                return Temporal.PlainDate.from(value).toLocaleString(locale, { dateStyle: "long" });
+            }
+            const instant = typeof value === "number"
+                ? Temporal.Instant.fromEpochMilliseconds(value)
+                : Temporal.Instant.from(value);
+            return instant.toLocaleString(locale, { dateStyle: "long", timeZone: "UTC" });
+        }
+        catch {
+            return String(value);
+        }
+    });
+    hbs.registerHelper("link", (value) => typeof value === "string" && SAFE_LINK_PROTOCOL.test(value.trim()) ? value : "#");
+    return hbs;
+}
+const KNOWN_HELPERS = { each: true, if: true, money: true, date: true, link: true };
+export function compileDocumentSource(hbs, source, options = {}) {
+    return hbs.compile(source, {
+        knownHelpers: KNOWN_HELPERS,
+        knownHelpersOnly: true,
+        strict: false,
+        ...options,
+    });
+}
+// A key only exists in the registry when its feature is mounted; reading an
+// unregistered key through the accessor would throw instead of falling back.
+async function readConfigText(ctx, key) {
+    if (ctx.config === undefined || ctx.registry.getConfigKey(key) === undefined)
+        return undefined;
+    const value = await ctx.config(key);
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+// Dates and numbers follow the template locale, the language the document is
+// read in; the tenant's locale setting must not turn a German invoice into
+// "Oct 1, 2026". The currency is a tenant fact and still comes from its settings.
+export async function readDocumentFormat(ctx, templateLocale) {
+    const currency = await readConfigText(ctx, TENANT_CURRENCY_CONFIG_KEY);
+    return { locale: templateLocale, currency: currency ?? FALLBACK_CURRENCY };
+}
+export async function readTenantName(ctx) {
+    return (await readConfigText(ctx, BRANDING_QN.title)) ?? "";
+}
+const LOGO_RESOURCE_KEY = "logo";
+// Lookup order: the template's own link, the system template it overrides, and for
+// "logo" the tenant's branding logo. The system lookup is skipped for system templates.
+export async function resolveResourceFileRefs(tplApi, ctx, template, keys) {
+    if (keys.length === 0)
+        return new Map();
+    let systemLinks = {};
+    if (template.scope === "tenant") {
+        try {
+            systemLinks = (await tplApi.resolveTemplate({
+                tenantId: SYSTEM_TENANT_ID,
+                slug: template.slug,
+                kind: template.kind,
+                locale: template.locale,
+            })).linkedResources;
+        }
+        catch (e) {
+            if (!(e instanceof TemplateNotFoundError))
+                throw e;
+        }
+    }
+    const brandingLogo = keys.includes(LOGO_RESOURCE_KEY) ? await readBrandingLogo(ctx) : undefined;
+    const fileRefIds = new Map();
+    for (const key of keys) {
+        const fileRefId = ownLink(template.linkedResources, key) ??
+            ownLink(systemLinks, key) ??
+            (key === LOGO_RESOURCE_KEY ? brandingLogo : undefined);
+        if (fileRefId !== undefined)
+            fileRefIds.set(key, fileRefId);
+    }
+    return fileRefIds;
+}
+// The token is a free field of the tenant admin and the send reader also reaches the system
+// tenant's files, so only a file of the rendering tenant itself counts.
+async function readBrandingLogo(ctx) {
+    const fileRefId = await readConfigText(ctx, BRANDING_QN.logoFile);
+    if (fileRefId === undefined || !isUuid(fileRefId))
+        return undefined;
+    const [row] = await selectMany(ctx.db, fileRefsTable, {
+        id: fileRefId,
+        tenantId: ctx.tenantId,
+        isDeleted: false,
+    });
+    return row === undefined ? undefined : fileRefId;
+}
+function ownLink(links, key) {
+    return Object.hasOwn(links, key) && links[key] !== "" ? links[key] : undefined;
+}
+export function collectRegionResourceKeys(regions) {
+    return collectDocumentResourceKeys([regions.header, regions.signature, regions.footer].join(""));
+}
+// A cid or data URI per key can point to one file only, so a key the body already
+// resolved keeps the body's file even when the layout links another one.
+export function mergeResourceFileRefs(bodyRefs, layoutRefs) {
+    return new Map([...layoutRefs, ...bodyRefs]);
+}

package/dist/feature.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-types/feature";
+export declare function createRendererMailHtmlFeature(): FeatureDefinition;

package/dist/feature.js

@@ -0,0 +1,25 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { mailHtmlRender } from "./render.js";
+// renderer-mail-html: plugin for renderer-foundation, renders `kind="mail"`
+// requests to subject + email-safe HTML + plain text.
+//
+// **Caller pattern:** the caller (e.g. delivery's email-channel) selects the plugin
+// via `createRendererForTenant({ tenantId, kind: "mail" })` and calls
+// `plugin.render({ kind: "mail", payload: { slug, locale, variables } }, ctx)`.
+// The plugin resolves the mail template and its layout itself through
+// template-resolver (tenant -> system), so ctx needs `db`, `registry`, `tenantId`
+// and optionally `config` for the tenant's currency and branding.
+//
+// **Layout:** meta.layoutSlug ?? "default", kind "mail-layout". Without a seeded
+// layout the in-code DEFAULT_MAIL_LAYOUT_MJML is used, so mail works from day 1.
+export function createRendererMailHtmlFeature() {
+    return defineFeature("renderer-mail-html", (r) => {
+        r.describe('A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`\'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, in-code `DEFAULT_MAIL_LAYOUT_MJML` as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.');
+        r.requires("renderer-foundation");
+        r.requires("template-resolver");
+        r.useExtension("renderer", "mail-html", {
+            kinds: ["mail"],
+            render: mailHtmlRender,
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.js";
+export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, type DocumentFormat, mergeResourceFileRefs, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+export { createRendererMailHtmlFeature } from "./feature.js";
+export { mailHtmlRender } from "./render.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.js";
+export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, mergeResourceFileRefs, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+export { createRendererMailHtmlFeature } from "./feature.js";
+export { mailHtmlRender } from "./render.js";

package/dist/mail-attachments.d.ts

@@ -0,0 +1,10 @@
+import { type FileAttachmentRef, type InlineAttachmentRef, type MailAttachmentRef, type RenderedPdfAttachmentRef } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import type { TemplatePdfAttachmentLink } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+export declare function buildRenderedPdfAttachments(args: {
+    readonly slug: string;
+    readonly links: readonly TemplatePdfAttachmentLink[];
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly locale: string;
+    readonly renderFileName: (pattern: string) => string;
+}): readonly RenderedPdfAttachmentRef[];
+export declare function combineMailAttachments(slug: string, inline: readonly InlineAttachmentRef[], files: readonly FileAttachmentRef[], renderedPdfs: readonly RenderedPdfAttachmentRef[]): readonly MailAttachmentRef[];

package/dist/mail-attachments.js

@@ -0,0 +1,26 @@
+import { MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, sanitizePdfAttachmentFileName, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { RendererError, } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+export function buildRenderedPdfAttachments(args) {
+    const { slug, links, variables, locale, renderFileName } = args;
+    if (links.length === 0)
+        return [];
+    if (Buffer.byteLength(JSON.stringify(variables)) > MAX_RENDERED_PDF_VARIABLES_BYTES) {
+        throw new RendererError(`renderer-mail-html: the variables of mail "${slug}" exceed ${MAX_RENDERED_PDF_VARIABLES_BYTES} bytes as JSON, too large to hand to the attached PDF`, "invalid_payload");
+    }
+    return links.map((link) => ({
+        kind: "rendered-pdf",
+        templateSlug: link.templateSlug,
+        variables,
+        locale,
+        fileName: sanitizePdfAttachmentFileName(renderFileName(link.fileName), link.templateSlug),
+    }));
+}
+// Inline images come first so their order in the mail matches the body; the delivery layer
+// rejects more than MAX_EMAIL_ATTACHMENTS, so the render fails here with the slug instead.
+export function combineMailAttachments(slug, inline, files, renderedPdfs) {
+    const attachments = [...inline, ...files, ...renderedPdfs];
+    if (attachments.length > MAX_EMAIL_ATTACHMENTS) {
+        throw new RendererError(`renderer-mail-html: mail "${slug}" would carry ${attachments.length} attachments (${inline.length} inline images, ${files.length} files, ${renderedPdfs.length} rendered PDFs), the limit is ${MAX_EMAIL_ATTACHMENTS}`, "other");
+    }
+    return attachments;
+}

package/dist/render.d.ts

@@ -0,0 +1,2 @@
+import { type RendererContext, type RenderRequest, type RenderResponse } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+export declare function mailHtmlRender(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;

package/dist/render.js

@@ -0,0 +1,307 @@
+// renderer-mail-html pipeline for kind "mail":
+//   1. Resolve the mail template (tenant -> system) and its layout
+//      (meta.layoutSlug ?? "default", kind mail-layout, fallback to the in-code
+//      DEFAULT_MAIL_LAYOUT_MJML).
+//   2. compileDocumentBodyToHandlebars turns the sanitized document body into
+//      Handlebars source; every author brace is neutralized there, so the only
+//      expressions are the ones template-resolver wrote.
+//   3. The body renders with HTML escaping on. The result is handed to the
+//      layout as data (`{{{content}}}`), never concatenated into layout source.
+//   4. mjml -> email HTML, html-to-text -> plain-text alternative.
+// Handlebars runs in an isolated instance with a fixed helper set.
+import { RendererError, } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import { collectDocumentResourceKeys, compileDocumentBodyToHandlebars, createTemplateResolverApi, fileAttachmentsOf, imageLinksOf, isMailTemplateMeta, parseTemplateMeta, pdfAttachmentLinksOf, readLayoutRegions, resolveTemplateVariables, sanitizeDocumentHtml, sanitizeLayoutHtml, TemplateNotFoundError, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
+import { convert as htmlToText } from "html-to-text";
+import mjml2html from "mjml";
+import { DEFAULT_MAIL_LAYOUT_MJML, DEFAULT_MAIL_LAYOUT_SLUG } from "./default-layout.js";
+import { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, mergeResourceFileRefs, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+import { buildRenderedPdfAttachments, combineMailAttachments } from "./mail-attachments.js";
+import { renderStructuredLayoutMjml } from "./structured-layout.js";
+const LINE_BREAKS = /[\r\n]+/g;
+function describe(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+const IN_CODE_LAYOUT = {
+    content: DEFAULT_MAIL_LAYOUT_MJML,
+    format: "mjml",
+    ref: null,
+    template: null,
+};
+// Only system layouts are trusted as written: a tenant mjml row left over from
+// before that rule, or a tenant html row failing the layout sanitizer, is
+// replaced by the system layout of the same slug.
+async function resolveLayout(tplApi, ctx, meta, locale) {
+    const slug = meta.layoutSlug ?? DEFAULT_MAIL_LAYOUT_SLUG;
+    try {
+        let layout = await tplApi.resolveLayout({
+            tenantId: ctx.tenantId,
+            slug,
+            kind: "mail-layout",
+            locale,
+        });
+        let content = layout.content;
+        let useSystemLayout = false;
+        if (layout.scope !== "system") {
+            if (layout.contentFormat === "html") {
+                // Re-checked on every render: rows written before the write gate existed
+                // or through another path must not reach the mail unsanitized.
+                const sanitized = sanitizeLayoutHtml(content);
+                if (sanitized.ok)
+                    content = sanitized.html;
+                else
+                    useSystemLayout = true;
+            }
+            else {
+                useSystemLayout = layout.contentFormat === "mjml";
+            }
+        }
+        if (useSystemLayout) {
+            layout = await tplApi.resolveLayout({
+                tenantId: SYSTEM_TENANT_ID,
+                slug,
+                kind: "mail-layout",
+                locale,
+            });
+            content = layout.content;
+        }
+        return {
+            content,
+            format: layout.contentFormat === "html" ? "html" : "mjml",
+            ref: { templateId: layout.id, templateVersion: layout.version, scope: layout.scope },
+            template: layout,
+        };
+    }
+    catch (e) {
+        // Only "no layout seeded" falls back to the in-code layout. Connection or
+        // schema errors must not be masked, or every mail silently loses its branding.
+        if (!(e instanceof TemplateNotFoundError)) {
+            throw new RendererError(`renderer-mail-html: layout resolution failed — ${describe(e)}`, "other");
+        }
+        return IN_CODE_LAYOUT;
+    }
+}
+async function findStoredMailTemplate(tplApi, ctx, slug, locale) {
+    try {
+        return await tplApi.resolveTemplate({ tenantId: ctx.tenantId, slug, kind: "mail", locale });
+    }
+    catch (e) {
+        if (e instanceof TemplateNotFoundError)
+            return null;
+        throw new RendererError(`renderer-mail-html: template resolution failed — ${describe(e)}`, "other");
+    }
+}
+async function resolveLayoutFileRefs(tplApi, ctx, layout) {
+    if (layout.format !== "html" || layout.template === null)
+        return new Map();
+    try {
+        return await resolveResourceFileRefs(tplApi, ctx, layout.template, collectRegionResourceKeys(readLayoutRegions(layout.content)));
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: resolving the layout images failed — ${describe(e)}`, "other");
+    }
+}
+// The draft comes from a caller outside the write pipeline, so it passes the document
+// sanitizer and the meta check again instead of being trusted as already gated.
+function applyMailDraft(stored, draft, slug, locale) {
+    const sanitized = sanitizeDocumentHtml(draft.content);
+    if (!sanitized.ok) {
+        throw new RendererError(`renderer-mail-html: draft of "${slug}" violates the document rules (${sanitized.violations.map((v) => v.code).join(", ")})`, "invalid_payload");
+    }
+    const parsedMeta = parseTemplateMeta("mail", draft.meta);
+    if (!parsedMeta.ok || !isMailTemplateMeta(parsedMeta.meta)) {
+        throw new RendererError(`renderer-mail-html: draft of "${slug}" has no valid mail meta`, "invalid_payload");
+    }
+    const base = stored ?? {
+        id: "",
+        version: 0,
+        tenantId: "",
+        slug,
+        kind: "mail",
+        locale,
+        title: null,
+        folder: null,
+        content: "",
+        contentFormat: "html",
+        variableSchema: {},
+        linkedResources: {},
+        meta: null,
+        scope: "tenant",
+        parentTemplateId: null,
+        status: "draft",
+        modifiedAt: null,
+    };
+    return {
+        ...base,
+        content: sanitized.html,
+        contentFormat: "html",
+        meta: parsedMeta.meta,
+        variableSchema: { ...(draft.variableSchema ?? base.variableSchema) },
+        ...(draft.linkedResources !== undefined && {
+            linkedResources: imageLinksOf(draft.linkedResources),
+            fileAttachments: fileAttachmentsOf(draft.linkedResources),
+            pdfAttachmentLinks: pdfAttachmentLinksOf(draft.linkedResources),
+        }),
+    };
+}
+async function resolveMailTemplate(tplApi, ctx, slug, locale, draft) {
+    const stored = await findStoredMailTemplate(tplApi, ctx, slug, locale);
+    const template = draft === undefined ? stored : applyMailDraft(stored, draft, slug, locale);
+    if (template === null) {
+        throw new RendererError(`renderer-mail-html: no mail template "${slug}" for locale "${locale}"`, "invalid_payload");
+    }
+    if (template.contentFormat !== "html") {
+        throw new RendererError(`renderer-mail-html: template "${slug}" has contentFormat "${template.contentFormat}", only html is supported`, "other");
+    }
+    if (!isMailTemplateMeta(template.meta)) {
+        throw new RendererError(`renderer-mail-html: template "${slug}" has no valid mail meta (subject is required)`, "other");
+    }
+    return { template, meta: template.meta };
+}
+// Each data-resource image is referenced by cid; the bytes are read at send time, so
+// the render result carries only file ref ids.
+async function renderMailBody(tplApi, ctx, template, hbs, context) {
+    try {
+        const resourceFileRefs = await resolveResourceFileRefs(tplApi, ctx, template, collectDocumentResourceKeys(template.content));
+        const handlebarsSource = compileDocumentBodyToHandlebars(template.content, resolveTemplateVariables(ctx.registry, template.slug, template.variableSchema), {
+            resourceSrc: (key) => (resourceFileRefs.has(key) ? `cid:${key}` : undefined),
+            alignmentAsInlineStyle: true,
+        });
+        return {
+            contentHtml: compileDocumentSource(hbs, handlebarsSource)(context),
+            resourceFileRefs,
+        };
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: rendering the body of "${template.slug}" failed — ${describe(e)}`, "other");
+    }
+}
+function renderSubjectLine(hbs, source, context) {
+    return compileDocumentSource(hbs, source, { noEscape: true })(context).replace(LINE_BREAKS, "");
+}
+function renderFileNamePattern(hbs, pattern, slug, context) {
+    try {
+        return renderSubjectLine(hbs, pattern, context);
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: rendering the attachment file name "${pattern}" of "${slug}" failed — ${describe(e)}`, "other");
+    }
+}
+function renderSubjectLines(hbs, meta, slug, context) {
+    try {
+        return {
+            subject: renderSubjectLine(hbs, meta.subject, context),
+            previewText: meta.previewText === undefined
+                ? undefined
+                : renderSubjectLine(hbs, meta.previewText, context),
+        };
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: rendering subject or preview text of "${slug}" failed — ${describe(e)}`, "other");
+    }
+}
+function assembleMailAttachments(args) {
+    const { slug, template, resourceFileRefs, variables, locale, renderFileName } = args;
+    const inlineAttachments = [...resourceFileRefs].map(([cid, fileRefId]) => ({ kind: "inline", cid, fileRefId }));
+    const renderedPdfs = buildRenderedPdfAttachments({
+        slug,
+        links: template.pdfAttachmentLinks ?? [],
+        variables,
+        locale,
+        renderFileName,
+    });
+    return combineMailAttachments(slug, inlineAttachments, template.fileAttachments ?? [], renderedPdfs);
+}
+export async function mailHtmlRender(req, ctx) {
+    if (req.kind !== "mail") {
+        // Foundation selects plugins only for matching kinds; defensive guard.
+        throw new RendererError(`renderer-mail-html supports only kind="mail", got "${req.kind}"`, "invalid_payload");
+    }
+    const { slug, locale, variables, unsubscribeUrl, draft } = req.payload;
+    const tplApi = createTemplateResolverApi(ctx.db);
+    const { template, meta } = await resolveMailTemplate(tplApi, ctx, slug, locale, draft);
+    const layout = await resolveLayout(tplApi, ctx, meta, locale);
+    const [format, tenantName] = await Promise.all([
+        readDocumentFormat(ctx, locale),
+        readTenantName(ctx),
+    ]);
+    const hbs = createDocumentHandlebars(format);
+    const context = {
+        ...variables,
+        tenantName,
+        signature: "",
+        imprint: "",
+        unsubscribeUrl: unsubscribeUrl ?? "",
+    };
+    const body = await renderMailBody(tplApi, ctx, template, hbs, context);
+    const { contentHtml } = body;
+    const layoutFileRefs = await resolveLayoutFileRefs(tplApi, ctx, layout);
+    const resourceFileRefs = mergeResourceFileRefs(body.resourceFileRefs, layoutFileRefs);
+    const attachments = assembleMailAttachments({
+        slug,
+        template,
+        resourceFileRefs,
+        variables,
+        locale,
+        renderFileName: (pattern) => renderFileNamePattern(hbs, pattern, slug, context),
+    });
+    const { subject, previewText } = renderSubjectLines(hbs, meta, slug, context);
+    let mjmlSource;
+    try {
+        const layoutContext = {
+            subject,
+            previewText: previewText ?? "",
+            tenantName,
+            signature: "",
+            imprint: "",
+            unsubscribeUrl: unsubscribeUrl ?? "",
+        };
+        mjmlSource =
+            layout.format === "html"
+                ? renderStructuredLayoutMjml({
+                    layoutHtml: layout.content,
+                    contentHtml,
+                    context: layoutContext,
+                    compile: (source) => compileDocumentSource(hbs, source),
+                    resourceSrc: (key) => (resourceFileRefs.has(key) ? `cid:${key}` : undefined),
+                })
+                : compileDocumentSource(hbs, layout.content)({ ...layoutContext, content: contentHtml });
+    }
+    catch (e) {
+        // "other": the caller's payload is fine, the layout template is broken.
+        throw new RendererError(`renderer-mail-html: Handlebars compile failed for layout — ${describe(e)}`, "other");
+    }
+    // mjml@5 is async
+    const mjmlResult = await mjml2html(mjmlSource, { validationLevel: "soft" });
+    const errors = mjmlResult.errors ?? [];
+    if (errors.length > 0) {
+        const firstErrors = errors
+            .slice(0, 3)
+            .map((e) => `line ${e.line}: ${e.message}`)
+            .join("; ");
+        throw new RendererError(`renderer-mail-html: MJML compile produced ${errors.length} error(s) — ${firstErrors}`, "other");
+    }
+    const text = htmlToText(mjmlResult.html, {
+        wordwrap: 80,
+        selectors: [
+            { selector: "a", options: { hideLinkHrefIfSameAsText: true } },
+            { selector: "img", format: "skip" },
+        ],
+    });
+    return {
+        kind: "mail",
+        subject,
+        html: mjmlResult.html,
+        text,
+        ...(previewText === undefined ? {} : { previewText }),
+        ...(attachments.length > 0 && { attachments }),
+        ...(draft === undefined && {
+            template: {
+                templateId: template.id,
+                templateVersion: template.version,
+                scope: template.scope,
+            },
+        }),
+        ...(layout.ref === null ? {} : { layout: layout.ref }),
+    };
+}

package/dist/seeding.d.ts

@@ -0,0 +1,10 @@
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+export type SeedSystemMailLayoutOptions = {
+    /** Override MJML — if omitted, DEFAULT_MAIL_LAYOUT_MJML is used. */
+    readonly mjml?: string;
+    /** Locale for the layout row — default "en". */
+    readonly locale?: string;
+    /** Layout slug — default "default". */
+    readonly slug?: string;
+};
+export declare function seedSystemMailLayout(db: DbConnection, options?: SeedSystemMailLayoutOptions): Promise<void>;

package/dist/seeding.js

@@ -0,0 +1,25 @@
+// Optional seeding helper for app authors. Writes DEFAULT_MAIL_LAYOUT_MJML as the
+// system layout (slug "default", kind "mail-layout", tenantId=SYSTEM_TENANT_ID)
+// into the template-resource table.
+//
+// **When to use?** When the app author wants the default layout editable in the
+// tenant admin UI. Without seeding the renderer falls back to the in-code
+// DEFAULT_MAIL_LAYOUT_MJML, which renders identically but is not editable.
+//
+// Idempotent: a second call with unchanged content writes no event, a changed
+// layout updates the existing row.
+import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/template-resolver/seeding";
+import { DEFAULT_MAIL_LAYOUT_MJML, DEFAULT_MAIL_LAYOUT_SLUG } from "./default-layout.js";
+const DEFAULT_LOCALE = "en";
+export async function seedSystemMailLayout(db, options = {}) {
+    const { mjml = DEFAULT_MAIL_LAYOUT_MJML, locale = DEFAULT_LOCALE, slug = DEFAULT_MAIL_LAYOUT_SLUG, } = options;
+    await seedSystemTemplate(db, {
+        slug,
+        kind: "mail-layout",
+        locale,
+        content: mjml,
+        contentFormat: "mjml",
+        meta: {},
+        ifExists: "update",
+    });
+}

package/dist/structured-layout.d.ts

@@ -0,0 +1,11 @@
+export type StructuredLayoutInput = {
+    readonly layoutHtml: string;
+    readonly contentHtml: string;
+    /** Layout context (tenantName, subject, previewText, signature, imprint, unsubscribeUrl). */
+    readonly context: Readonly<Record<string, unknown>>;
+    /** Compiles Handlebars source with the renderer's isolated instance and helper set. */
+    readonly compile: (source: string) => (context: Readonly<Record<string, unknown>>) => string;
+    /** src for `img[data-resource]` in the regions; without it layout images are dropped. */
+    readonly resourceSrc?: (key: string) => string | undefined;
+};
+export declare function renderStructuredLayoutMjml(input: StructuredLayoutInput): string;

package/dist/structured-layout.js

@@ -0,0 +1,54 @@
+// Renders a structured (html) mail layout: the tenant-editable regions go into
+// a fixed in-code MJML frame, so a tenant layout never contributes MJML source.
+import { compileDocumentBodyToHandlebars, readLayoutRegions, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+const STRUCTURED_LAYOUT_FRAME = `<mjml>
+  <mj-head>
+    <mj-title>{{subject}}</mj-title>
+    <mj-preview>{{previewText}}</mj-preview>
+    <mj-attributes>
+      <mj-all font-family="Helvetica, Arial, sans-serif" />
+      <mj-text font-size="14px" color="#333" line-height="1.6" />
+    </mj-attributes>
+  </mj-head>
+  <mj-body background-color="#f5f5f5">
+    {{#if regionHeader}}
+    <mj-section background-color="#ffffff" padding="20px">
+      <mj-column>
+        <mj-text>{{{regionHeader}}}</mj-text>
+      </mj-column>
+    </mj-section>
+    {{/if}}
+    <mj-section background-color="#ffffff" padding="20px">
+      <mj-column>
+        <mj-raw>{{{content}}}</mj-raw>
+      </mj-column>
+    </mj-section>
+    {{#if regionSignature}}
+    <mj-section background-color="#ffffff" padding="20px">
+      <mj-column>
+        <mj-text>{{{regionSignature}}}</mj-text>
+      </mj-column>
+    </mj-section>
+    {{/if}}
+    {{#if regionFooter}}
+    <mj-section background-color="#f5f5f5" padding="20px">
+      <mj-column>
+        <mj-text font-size="11px" color="#888" align="center">{{{regionFooter}}}</mj-text>
+      </mj-column>
+    </mj-section>
+    {{/if}}
+  </mj-body>
+</mjml>`;
+export function renderStructuredLayoutMjml(input) {
+    const regions = readLayoutRegions(input.layoutHtml);
+    const renderRegion = (region) => region.trim() === ""
+        ? ""
+        : input.compile(compileDocumentBodyToHandlebars(region, {}, input.resourceSrc && { resourceSrc: input.resourceSrc }))(input.context);
+    return input.compile(STRUCTURED_LAYOUT_FRAME)({
+        ...input.context,
+        content: input.contentHtml,
+        regionHeader: renderRegion(regions.header),
+        regionSignature: renderRegion(regions.signature),
+        regionFooter: renderRegion(regions.footer),
+    });
+}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-mail-html",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.363.0",
+  "description": "Renderer-Foundation plugin for branded HTML emails: mail-kind templates (document HTML + subject meta) rendered with isolated Handlebars into an MJML layout, plus plain text via html-to-text. Templates resolved from template-resolver.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "type": "module",
+  "kumiko": {
+    "runtime": "runtime"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./seeding": {
+      "types": "./dist/seeding.d.ts",
+      "default": "./dist/seeding.js"
+    }
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "0.363.0",
+    "@cosmicdrift/kumiko-framework": "0.363.0",
+    "@cosmicdrift/kumiko-headless": "0.363.0",
+    "@cosmicdrift/kumiko-types": "0.363.0",
+    "handlebars": "^4.7.8",
+    "html-to-text": "^9.0.5",
+    "mjml": "^5.2.2"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "0.363.0",
+    "@types/html-to-text": "^9.0.4",
+    "@types/mjml": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/renderer-mail-html"
+  },
+  "homepage": "https://kumiko.rocks",
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./seeding": {
+        "types": "./dist/seeding.d.ts",
+        "default": "./dist/seeding.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src/changes.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/changes.json

@@ -0,0 +1,59 @@
+[
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "Documents format dates and numbers by the template locale, dates in the long style",
+    "detail": "readDocumentFormat used the tenant setting tenant-settings:config:locale ahead of the template locale, so a German invoice of a tenant set to English printed \"Oct 1, 2026\" and \"€780.00\". Mails, mail previews and document PDFs now format by the locale of the template that is rendered; the tenant settings still supply the currency. The date helper prints the long style (\"1. Oktober 2026\", \"October 1, 2026\") instead of the medium style (\"01.10.2026\", \"Oct 1, 2026\").",
+    "migration": "Tests or snapshots that assert rendered dates change from \"05.03.2026\" to \"5. März 2026\" (de) and from \"Mar 5, 2026\" to \"March 5, 2026\" (en). A tenant that relied on tenant-settings:config:locale to change the number format of its documents now needs a template in that locale."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Images in layout regions, exported document-kit helpers",
+    "detail": "A mail layout region can contain images (data-resource) that are sent as inline attachments. The document helpers (createDocumentHandlebars, compileDocumentSource, readDocumentFormat, readTenantName, resolveResourceFileRefs, collectRegionResourceKeys, mergeResourceFileRefs) are exported, so other renderers format documents the same way."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Text alignment of paragraphs and headings is sent as an inline style",
+    "detail": "A paragraph or heading with data-align is rendered with an inline text-align, because mail clients ignore document CSS."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "renders kind mail from document templates, Markdown path removed",
+    "detail": "The plugin serves kind mail. It resolves the template by slug (contentFormat html, meta.subject required), compiles the document body to Handlebars through template-resolver, renders it in an isolated Handlebars instance (helpers money, date and link, HTML escaping on) and places the result into the mail-layout named by meta.layoutSlug (default slug default, in-code DEFAULT_MAIL_LAYOUT_MJML as fallback). The layout only sees content, subject, previewText, tenantName, signature, imprint and unsubscribeUrl. The response carries subject and previewText; the subject has line breaks removed. Markdown rendering and the content/contentFormat payload are gone; DEFAULT_MAIL_LAYOUT_MJML uses tenantName instead of appName. seedSystemMailLayout writes kind mail-layout slug default through seedSystemTemplate and is idempotent. New dependency on @cosmicdrift/kumiko-headless.",
+    "migration": "Send kind mail requests with { slug, locale, variables } and move mail texts into kind mail templates (html body plus meta.subject), for example through r.notification({ template, meta }). Custom mail layouts become kind mail-layout, contentFormat mjml, slug default and use {{tenantName}} instead of {{appName}}; the body is inserted with {{{content}}}."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "Package moved to the framework under the @cosmicdrift scope",
+    "detail": "Renamed from @cosmicdriftgamestudio/kumiko-renderer-mail-html (GitHub Packages, kumiko-enterprise) to @cosmicdrift/kumiko-renderer-mail-html on npmjs; the API is unchanged.",
+    "migration": "Replace @cosmicdriftgamestudio/kumiko-renderer-mail-html with @cosmicdrift/kumiko-renderer-mail-html in package.json and in every import; install from npmjs instead of GitHub Packages."
+  },
+  {
+    "version": "0.363.0",
+    "type": "fix",
+    "title": "The default mail layout shows the mail body",
+    "detail": "The in-code default mail layout wraps the body in mj-text instead of mj-raw. With mj-raw the body HTML sat directly in the column table, browsers moved it into the column wrapper with font-size 0, and every mail without a mail-layout row had an invisible body. seedSystemMailLayout updates a seeded row on its next run."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mail renderer attaches linked PDF templates as rendered-pdf attachments",
+    "detail": "The renderer builds a RenderedPdfAttachmentRef per linked PDF with the mail's render variables, the mail locale and the file name pattern rendered like the subject and cleaned by sanitizePdfAttachmentFileName, now exported from @cosmicdrift/kumiko-bundled-features/delivery (control characters and / \\ \" ; .. removed, at most 200 characters including .pdf, empty falls back to the last slug segment). Order is inline images, files, rendered PDFs, all within MAX_EMAIL_ATTACHMENTS; variables above MAX_RENDERED_PDF_VARIABLES_BYTES fail the render with the mail slug. RenderedPdfAttachmentRef now lives in renderer-foundation (still exported from delivery) and RenderResponse and RenderedMail allow it."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Renders a MailPayload.draft instead of the stored template body and subject",
+    "detail": "With a draft the stored template of the slug only supplies its linked images and variable schema; the body goes through the document sanitizer and the meta through the mail meta check, and a violation is an invalid_payload error. The response has no template reference because a draft is not a stored version."
+  },
+  {
+    "version": "0.363.0",
+    "type": "fix",
+    "title": "Mails use a tenant layout stored under another locale",
+    "detail": "The mail renderer resolves its layout with resolveLayout, so a tenant layout saved in en no longer leaves German mails without the tenant branding."
+  }
+]