@cosmicdrift/kumiko-renderer-mail-html 0.0.0-stage → 0.364.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,17 @@
+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 readBrandingAccentColor(ctx: RendererContext): Promise<string | undefined>;
+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,169 @@
+import { BRANDING_QN } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
+import { collectDocumentResourceKeys, isHexColor, sanitizeDocumentHtml, 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 { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+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 documentKitLogger = createFallbackLogger("renderer-mail-html");
+const FALLBACK_CURRENCY = "EUR";
+const SAFE_LINK_PROTOCOL = /^(https?:|mailto:)/i;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T.*[+-]\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" });
+            }
+            // An explicit offset names the sender's zone: the calendar date is the wall-clock
+            // date of the string, not the date at UTC.
+            if (typeof value === "string" && DATE_TIME_WITH_OFFSET.test(value)) {
+                return Temporal.PlainDateTime.from(value)
+                    .toPlainDate()
+                    .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("richText", (value) => {
+        if (typeof value !== "string")
+            return "";
+        const sanitized = sanitizeDocumentHtml(value);
+        if (sanitized.ok)
+            return new hbs.SafeString(sanitized.html);
+        // Rejected markup renders as visible text (escaped by Handlebars) instead of vanishing.
+        documentKitLogger.warn("richText value rejected by sanitizer, rendered as escaped text", {
+            violations: sanitized.violations.map((item) => item.code),
+        });
+        return 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,
+    richText: 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)) ?? "";
+}
+export async function readBrandingAccentColor(ctx) {
+    const value = await readConfigText(ctx, BRANDING_QN.accentColor);
+    return value !== undefined && isHexColor(value) ? value : undefined;
+}
+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,11 @@
+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[];
+export declare function mergeInheritedAttachments<T>(own: readonly T[], inherited: readonly T[], fileNameOf: (attachment: T) => string): readonly T[];

package/dist/mail-attachments.js

@@ -0,0 +1,37 @@
+import { MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, sanitizePdfAttachmentFileName, withoutDeliveryEnvelopeKeys, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { RendererError, } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+export function buildRenderedPdfAttachments(args) {
+    const { slug, links, locale, renderFileName } = args;
+    if (links.length === 0)
+        return [];
+    const variables = withoutDeliveryEnvelopeKeys(args.variables);
+    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;
+}
+// A tenant override carries its own links only; what the overridden system mail attaches
+// must not silently vanish. Attachments are slot-less here, so an own attachment with the
+// same file name replaces the inherited one.
+export function mergeInheritedAttachments(own, inherited, fileNameOf) {
+    const ownNames = new Set(own.map((attachment) => fileNameOf(attachment).toLowerCase()));
+    return [
+        ...inherited.filter((attachment) => !ownNames.has(fileNameOf(attachment).toLowerCase())),
+        ...own,
+    ];
+}

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,372 @@
+// 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, mailLayoutAppearance, 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, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+import { buildRenderedPdfAttachments, combineMailAttachments, mergeInheritedAttachments, } from "./mail-attachments.js";
+import { MAIL_IMAGE_MAX_WIDTH_PX, 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 = true;
+            }
+        }
+        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, buttonInlineStyle) {
+    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),
+            resourceImageMaxWidthPx: MAIL_IMAGE_MAX_WIDTH_PX,
+            alignmentAsInlineStyle: true,
+            buttonAsInlineStyle: true,
+            tableAsInlineStyle: true,
+            ...(buttonInlineStyle !== undefined && { buttonInlineStyle }),
+        });
+        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");
+    }
+}
+// Same fallback as for images (resolveResourceFileRefs): a tenant override of a system mail
+// keeps the attachments the system mail carries.
+async function resolveSystemAttachments(tplApi, template) {
+    if (template.scope !== "tenant")
+        return {};
+    try {
+        const system = await tplApi.resolveTemplate({
+            tenantId: SYSTEM_TENANT_ID,
+            slug: template.slug,
+            kind: template.kind,
+            locale: template.locale,
+        });
+        return {
+            fileAttachments: system.fileAttachments ?? [],
+            pdfAttachmentLinks: system.pdfAttachmentLinks ?? [],
+        };
+    }
+    catch (e) {
+        if (e instanceof TemplateNotFoundError)
+            return {};
+        throw new RendererError(`renderer-mail-html: resolving the system attachments of "${template.slug}" failed — ${describe(e)}`, "other");
+    }
+}
+async function assembleMailAttachments(args) {
+    const { tplApi, slug, template, resourceFileRefs, variables, locale, renderFileName } = args;
+    const inherited = await resolveSystemAttachments(tplApi, template);
+    const inlineAttachments = [...resourceFileRefs].map(([cid, fileRefId]) => ({ kind: "inline", cid, fileRefId }));
+    const renderedPdfs = buildRenderedPdfAttachments({
+        slug,
+        links: mergeInheritedAttachments(template.pdfAttachmentLinks ?? [], inherited.pdfAttachmentLinks ?? [], (link) => link.fileName),
+        variables,
+        locale,
+        renderFileName,
+    });
+    return combineMailAttachments(slug, inlineAttachments, mergeInheritedAttachments(template.fileAttachments ?? [], inherited.fileAttachments ?? [], (file) => file.fileName), renderedPdfs);
+}
+function compileLayoutMjml(args) {
+    const { layout, hbs, contentHtml, appearance, accentColor, resourceFileRefs, layoutContext } = args;
+    try {
+        return layout.format === "html"
+            ? renderStructuredLayoutMjml({
+                layoutHtml: layout.content,
+                contentHtml,
+                context: layoutContext,
+                compile: (source) => compileDocumentSource(hbs, source),
+                resourceSrc: (key) => (resourceFileRefs.has(key) ? `cid:${key}` : undefined),
+                ...(appearance !== undefined && { appearance }),
+                ...(accentColor !== undefined && { accentColor }),
+            })
+            : 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");
+    }
+}
+async function compileMjmlToHtml(mjmlSource) {
+    // 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");
+    }
+    return mjmlResult.html;
+}
+function htmlToPlainText(html) {
+    return htmlToText(html, {
+        wordwrap: 80,
+        selectors: [
+            { selector: "a", options: { hideLinkHrefIfSameAsText: true } },
+            { selector: "img", format: "skip" },
+        ],
+    });
+}
+function buildMailRenderResponse(args) {
+    const { subject, previewText, html, text, meta, attachments, template, layout, isDraft } = args;
+    return {
+        kind: "mail",
+        subject,
+        html,
+        text,
+        ...(previewText === undefined ? {} : { previewText }),
+        ...(meta.senderName !== undefined && { fromName: meta.senderName }),
+        ...(meta.replyTo !== undefined && { replyTo: meta.replyTo }),
+        ...(attachments.length > 0 && { attachments }),
+        ...(!isDraft && {
+            template: {
+                templateId: template.id,
+                templateVersion: template.version,
+                scope: template.scope,
+            },
+        }),
+        ...(layout.ref === null ? {} : { layout: layout.ref }),
+    };
+}
+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 ?? "",
+    };
+    // Only a structured (html) layout carries appearance; an mjml layout keeps its own look.
+    const appearance = layout.format === "html" ? mailLayoutAppearance(layout.template?.meta) : undefined;
+    const body = await renderMailBody(tplApi, ctx, template, hbs, context, appearance?.buttonStyle);
+    const { contentHtml } = body;
+    const layoutFileRefs = await resolveLayoutFileRefs(tplApi, ctx, layout);
+    const resourceFileRefs = mergeResourceFileRefs(body.resourceFileRefs, layoutFileRefs);
+    const attachments = await assembleMailAttachments({
+        tplApi,
+        slug,
+        template,
+        resourceFileRefs,
+        variables,
+        locale,
+        renderFileName: (pattern) => renderFileNamePattern(hbs, pattern, slug, context),
+    });
+    const { subject, previewText } = renderSubjectLines(hbs, meta, slug, context);
+    const accentColor = appearance?.accentLine === true ? await readBrandingAccentColor(ctx) : undefined;
+    const mjmlSource = compileLayoutMjml({
+        layout,
+        hbs,
+        contentHtml,
+        appearance,
+        accentColor,
+        resourceFileRefs,
+        layoutContext: {
+            subject,
+            previewText: previewText ?? "",
+            tenantName,
+            signature: "",
+            imprint: "",
+            unsubscribeUrl: unsubscribeUrl ?? "",
+        },
+    });
+    const html = await compileMjmlToHtml(mjmlSource);
+    return buildMailRenderResponse({
+        subject,
+        previewText,
+        html,
+        text: htmlToPlainText(html),
+        meta,
+        attachments,
+        template,
+        layout,
+        isDraft: draft !== undefined,
+    });
+}

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,17 @@
+import { type MailLayoutAppearance } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+export declare const MAIL_IMAGE_MAX_WIDTH_PX = 180;
+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;
+    /** Parsed layout appearance; defaults apply when missing. */
+    readonly appearance?: MailLayoutAppearance;
+    /** Tenant branding accent color for the accent line; ignored unless it is a #rrggbb hex. */
+    readonly accentColor?: string;
+};
+export declare function renderStructuredLayoutMjml(input: StructuredLayoutInput): string;

package/dist/structured-layout.js

@@ -0,0 +1,73 @@
+// 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, isHexColor, mailLayoutAppearance, readLayoutRegions, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+// The logo of a mail layout and of a mail body is capped here; the editors show the same width.
+export const MAIL_IMAGE_MAX_WIDTH_PX = 180;
+// Appearance values are enum members or a strict hex (see mailLayoutAppearance / isHexColor),
+// so interpolating them into the frame cannot inject MJML; the escaping keeps that if the schema widens.
+function structuredLayoutFrame(appearance, accentColor) {
+    const accentLine = appearance.accentLine && accentColor !== undefined && isHexColor(accentColor)
+        ? `<mj-section background-color="${escapeHtmlAttr(accentColor)}" padding="0">
+      <mj-column padding="0">
+        <mj-spacer height="4px" padding="0" />
+      </mj-column>
+    </mj-section>`
+        : "";
+    return `<mjml>
+  <mj-head>
+    <mj-title>{{subject}}</mj-title>
+    <mj-preview>{{previewText}}</mj-preview>
+    <mj-attributes>
+      <mj-all font-family="${escapeHtmlAttr(appearance.fontFamily)}" />
+      <mj-text font-size="14px" color="#333" line-height="1.6" />
+    </mj-attributes>
+  </mj-head>
+  <mj-body width="${appearance.width}px" background-color="${escapeHtmlAttr(appearance.outerBackground)}">
+    ${accentLine}
+    {{#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-text>{{{content}}}</mj-text>
+      </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="${escapeHtmlAttr(appearance.outerBackground)}" 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 }),
+            resourceImageMaxWidthPx: MAIL_IMAGE_MAX_WIDTH_PX,
+        }))(input.context);
+    const frame = structuredLayoutFrame(input.appearance ?? mailLayoutAppearance({}), input.accentColor);
+    return input.compile(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.364.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.364.0",
+    "@cosmicdrift/kumiko-framework": "0.364.0",
+    "@cosmicdrift/kumiko-headless": "0.364.0",
+    "@cosmicdrift/kumiko-types": "0.364.0",
+    "handlebars": "^4.7.8",
+    "html-to-text": "^9.0.5",
+    "mjml": "^5.2.2"
+  },
+  "devDependencies": {
+    "@cosmicdrift/kumiko-testing": "0.364.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,71 @@
+[
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Structured mail layouts show the mail body",
+    "detail": "The structured layout frame 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 on a tenant layout had an invisible body."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Mail renderer keeps wall-clock dates and system attachments",
+    "detail": "The date helper keeps the calendar date of offset datetimes, tenant overrides of system mails keep inherited attachments, markdown templates use the system layout and delivery envelope keys are not exposed as variables."
+  },
+  {
+    "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."
+  }
+]