@cosmicdrift/kumiko-renderer-mail-html 0.363.0 → 0.365.0

package/dist/default-layout.d.ts

@@ -1,2 +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>";
+export declare const DEFAULT_MAIL_LAYOUT_MJML = "<mjml lang=\"{{lang}}\">\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}}<p>Sent by {{tenantName}}</p>{{/if}}{{#if mailFooterHtml}}<p>{{{mailFooterHtml}}}</p>{{/if}}\n        </mj-text>\n      </mj-column>\n    </mj-section>\n  </mj-body>\n</mjml>";

package/dist/default-layout.js

@@ -1,6 +1,6 @@
-// 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").
+// Default MJML layout that apps can seed as their editable system layout
+// (seedSystemMailLayout). Without any layout row the renderer uses an in-code
+// structured layout instead, which also shows the branding logo and accent.
 //
 // **Variables the layout receives (nothing else):**
 //   - {{tenantName}}      - header + footer
@@ -11,13 +11,17 @@
 //   - {{subject}}         - mj-title
 //   - {{previewText}}     - inbox preview line
 //   - {{unsubscribeUrl}}  - optional footer link
+//   - {{lang}}            - the mail locale for <mjml lang>
+//   - {{imprint}}         - imprint URL from the app's footer resolver
+//   - {{{mailFooterHtml}}} - escaped footer line (resolver text, imprint, privacy,
+//                           unsubscribe link), built in code
 //
 // **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>
+export const DEFAULT_MAIL_LAYOUT_MJML = `<mjml lang="{{lang}}">
   <mj-head>
     <mj-title>{{subject}}</mj-title>
     <mj-preview>{{previewText}}</mj-preview>
@@ -40,7 +44,7 @@ export const DEFAULT_MAIL_LAYOUT_MJML = `<mjml>
     <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}}
+          {{#if tenantName}}<p>Sent by {{tenantName}}</p>{{/if}}{{#if mailFooterHtml}}<p>{{{mailFooterHtml}}}</p>{{/if}}
         </mj-text>
       </mj-column>
     </mj-section>

package/dist/document-kit.d.ts

@@ -11,6 +11,10 @@ export declare function compileDocumentSource(hbs: typeof Handlebars, source: st
 }): 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 readBrandingSiteUrl(ctx: RendererContext): Promise<string | undefined>;
+export declare const LOGO_RESOURCE_KEY = "logo";
 export declare function resolveResourceFileRefs(tplApi: TemplateResolverApi, ctx: RendererContext, template: TemplateResource, keys: readonly string[]): Promise<ReadonlyMap<string, string>>;
+export declare function readBrandingLogo(ctx: RendererContext): Promise<string | undefined>;
 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

@@ -1,16 +1,19 @@
 import { BRANDING_QN } from "@cosmicdrift/kumiko-bundled-features/managed-pages";
-import { collectDocumentResourceKeys, TemplateNotFoundError, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+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);
 }
@@ -39,6 +42,13 @@ export function createDocumentHandlebars(format) {
             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);
@@ -48,10 +58,44 @@ export function createDocumentHandlebars(format) {
             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 : "#");
+    hbs.registerHelper("stepIs", function stepIs(value, index, keys, state, options) {
+        return isStepInState(value, index, keys, state) ? options.fn(this) : options.inverse(this);
+    });
     return hbs;
 }
-const KNOWN_HELPERS = { each: true, if: true, money: true, date: true, link: true };
+// An unknown stage value reaches no stage: the row shows all stages as open.
+function isStepInState(value, index, keys, state) {
+    if (typeof index !== "number" || typeof keys !== "string")
+        return false;
+    const current = typeof value === "string" || typeof value === "number"
+        ? keys.split(",").indexOf(String(value).trim())
+        : -1;
+    if (current < 0)
+        return false;
+    return state === "current" ? index === current : index <= current;
+}
+const KNOWN_HELPERS = {
+    each: true,
+    if: true,
+    money: true,
+    date: true,
+    link: true,
+    richText: true,
+    stepIs: true,
+};
 export function compileDocumentSource(hbs, source, options = {}) {
     return hbs.compile(source, {
         knownHelpers: KNOWN_HELPERS,
@@ -78,7 +122,14 @@ export async function readDocumentFormat(ctx, templateLocale) {
 export async function readTenantName(ctx) {
     return (await readConfigText(ctx, BRANDING_QN.title)) ?? "";
 }
-const LOGO_RESOURCE_KEY = "logo";
+export async function readBrandingAccentColor(ctx) {
+    const value = await readConfigText(ctx, BRANDING_QN.accentColor);
+    return value !== undefined && isHexColor(value) ? value : undefined;
+}
+export async function readBrandingSiteUrl(ctx) {
+    return readConfigText(ctx, BRANDING_QN.siteUrl);
+}
+export 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) {
@@ -112,7 +163,7 @@ export async function resolveResourceFileRefs(tplApi, ctx, template, keys) {
 }
 // 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) {
+export async function readBrandingLogo(ctx) {
     const fileRefId = await readConfigText(ctx, BRANDING_QN.logoFile);
     if (fileRefId === undefined || !isUuid(fileRefId))
         return undefined;

package/dist/feature.d.ts

@@ -1,2 +1,3 @@
 import type { FeatureDefinition } from "@cosmicdrift/kumiko-types/feature";
-export declare function createRendererMailHtmlFeature(): FeatureDefinition;
+import { type MailHtmlRenderOptions } from "./render.js";
+export declare function createRendererMailHtmlFeature(options?: MailHtmlRenderOptions): FeatureDefinition;

package/dist/feature.js

@@ -11,15 +11,20 @@ import { mailHtmlRender } from "./render.js";
 // 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() {
+// layout an in-code structured layout with the tenant branding is used, so mail
+// works from day 1.
+//
+// **Footer:** options.footer returns the platform's imprint, privacy link and
+// footer text per tenant and locale. Structured layouts always render it below
+// the tenant-editable footer region, so a tenant cannot remove it.
+export function createRendererMailHtmlFeature(options = {}) {
     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.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, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. 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,
+            render: (req, ctx) => mailHtmlRender(req, ctx, options),
         });
     });
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { DEFAULT_MAIL_LAYOUT_MJML } from "./default-layout.js";
-export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, type DocumentFormat, mergeResourceFileRefs, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+export { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, type DocumentFormat, mergeResourceFileRefs, readBrandingAccentColor, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
 export { createRendererMailHtmlFeature } from "./feature.js";
-export { mailHtmlRender } from "./render.js";
+export type { MailFooter, MailFooterLink, MailFooterResolver } from "./mail-footer.js";
+export { type MailBrandSuffixResolver, type MailHtmlRenderOptions, mailHtmlRender, } from "./render.js";

package/dist/index.js

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

package/dist/mail-attachments.d.ts

@@ -8,3 +8,4 @@ export declare function buildRenderedPdfAttachments(args: {
     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

@@ -1,9 +1,10 @@
-import { MAX_EMAIL_ATTACHMENTS, MAX_RENDERED_PDF_VARIABLES_BYTES, sanitizePdfAttachmentFileName, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+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, variables, locale, renderFileName } = 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");
     }
@@ -24,3 +25,13 @@ export function combineMailAttachments(slug, inline, files, renderedPdfs) {
     }
     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/mail-chrome.d.ts

@@ -0,0 +1,16 @@
+import { type MailTone } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+export type ToneColors = {
+    readonly bar: string;
+    readonly fg: string;
+    readonly soft: string;
+};
+export declare const DEFAULT_ACCENT_COLOR = "#1f5468";
+export declare function readMailTone(rendered: string | undefined): MailTone | undefined;
+export declare function toneColors(tone: MailTone, accentColor: string | undefined): ToneColors;
+export declare function brandHeaderHtml(input: {
+    readonly tenantName: string;
+    readonly suffix: string;
+    readonly logoSrc: string | undefined;
+    readonly accentColor: string;
+}): string;
+export declare function headerRowHtml(leftHtml: string, chipLabel: string, colors: ToneColors): string;

package/dist/mail-chrome.js

@@ -0,0 +1,63 @@
+import { isHexColor, MAIL_TONES, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+const FIXED_TONES = {
+    info: { bar: "#7C8DB5", fg: "#3E4C70", soft: "#EEF1F7" },
+    success: { bar: "#22B35E", fg: "#0E7A3E", soft: "#E8F7EE" },
+    warning: { bar: "#F2B53A", fg: "#8A4B00", soft: "#FEF4E2" },
+    danger: { bar: "#E5484D", fg: "#A1161B", soft: "#FDECEC" },
+    neutral: { bar: "#8B919C", fg: "#4A515E", soft: "#F1F2F0" },
+};
+export const DEFAULT_ACCENT_COLOR = "#1f5468";
+const INK = "#0B0D12";
+const MUTED = "#5A6170";
+const LOGO_HEIGHT_PX = 28;
+// The rendered meta value is author input: only a known tone name selects colors.
+export function readMailTone(rendered) {
+    const value = rendered?.trim().toLowerCase();
+    return isOneOf(MAIL_TONES, value) ? value : undefined;
+}
+function tintTowardsWhite(hex, whiteShare) {
+    const channel = (offset) => {
+        const value = Number.parseInt(hex.slice(offset, offset + 2), 16);
+        const mixed = Math.round(value + (255 - value) * whiteShare);
+        return mixed.toString(16).padStart(2, "0");
+    };
+    return `#${channel(1)}${channel(3)}${channel(5)}`;
+}
+export function toneColors(tone, accentColor) {
+    if (tone !== "accent")
+        return FIXED_TONES[tone];
+    const accent = accentColor !== undefined && isHexColor(accentColor) ? accentColor : DEFAULT_ACCENT_COLOR;
+    return { bar: accent, fg: accent, soft: tintTowardsWhite(accent, 0.9) };
+}
+function tenantInitial(tenantName) {
+    const first = Array.from(tenantName.trim())[0];
+    return first === undefined ? "" : first.toLocaleUpperCase();
+}
+// Logo (or an initial tile in the accent color), tenant name and an optional suffix in one row.
+export function brandHeaderHtml(input) {
+    const initial = tenantInitial(input.tenantName);
+    const tileColor = isHexColor(input.accentColor) ? input.accentColor : DEFAULT_ACCENT_COLOR;
+    const mark = input.logoSrc !== undefined
+        ? `<img src="${escapeHtmlAttr(input.logoSrc)}" alt="" height="${LOGO_HEIGHT_PX}" style="height:${LOGO_HEIGHT_PX}px;width:auto;max-width:140px;border:0;vertical-align:middle;margin:0 10px 0 0">`
+        : initial === ""
+            ? ""
+            : `<span style="display:inline-block;width:${LOGO_HEIGHT_PX}px;height:${LOGO_HEIGHT_PX}px;line-height:${LOGO_HEIGHT_PX}px;text-align:center;border-radius:8px;background:${escapeHtmlAttr(tileColor)};color:#ffffff;font-weight:700;font-size:14px;vertical-align:middle;margin:0 10px 0 0">${escapeHtml(initial)}</span>`;
+    const name = input.tenantName.trim() === ""
+        ? ""
+        : `<span style="vertical-align:middle;font-size:15px;font-weight:600;color:${INK}">${escapeHtml(input.tenantName)}</span>`;
+    const suffix = input.suffix.trim() === ""
+        ? ""
+        : ` <span style="vertical-align:middle;font-size:13px;color:${MUTED}">${escapeHtml(input.suffix)}</span>`;
+    return `${mark}${name}${suffix}`;
+}
+function chipHtml(label, colors) {
+    return `<span style="display:inline-block;font-size:12px;font-weight:600;line-height:1.4;color:${escapeHtmlAttr(colors.fg)};background:${escapeHtmlAttr(colors.soft)};padding:4px 10px;border-radius:999px;white-space:nowrap"><span style="display:inline-block;width:6px;height:6px;border-radius:999px;background:${escapeHtmlAttr(colors.bar)};margin:0 6px 1px 0;vertical-align:middle"></span>${escapeHtml(label)}</span>`;
+}
+// A table instead of two mj-columns: columns stack on narrow screens, the chip belongs beside the brand.
+export function headerRowHtml(leftHtml, chipLabel, colors) {
+    if (chipLabel.trim() === "")
+        return leftHtml;
+    return `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0"><tr><td align="left" style="vertical-align:middle">${leftHtml}</td><td align="right" style="vertical-align:middle">${chipHtml(chipLabel, colors)}</td></tr></table>`;
+}

package/dist/mail-footer.d.ts

@@ -0,0 +1,29 @@
+import type { RendererContext } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+export type MailFooterLink = {
+    readonly label: string;
+    readonly url: string;
+};
+export type MailFooter = {
+    readonly text?: string;
+    readonly imprint?: MailFooterLink;
+    readonly privacy?: MailFooterLink;
+};
+export type MailFooterResolver = (input: {
+    readonly locale: string;
+    readonly ctx: RendererContext;
+}) => MailFooter | null | Promise<MailFooter | null>;
+export declare function buildMailBandLinksHtml(input: {
+    readonly siteUrl: string | undefined;
+    readonly unsubscribeUrl: string;
+    readonly locale: string;
+    readonly layoutLinksUnsubscribe: boolean;
+}): string;
+export declare function safeFooterUrl(link: MailFooterLink | undefined): string;
+export declare function buildMailFooterHtml(input: {
+    readonly footer: MailFooter | null;
+    readonly unsubscribeUrl: string;
+    readonly locale: string;
+    readonly layoutLinksImprint: boolean;
+    readonly layoutLinksUnsubscribe: boolean;
+}): string;
+export declare function layoutLinksToPlaceholder(layoutHtml: string, name: string): boolean;

package/dist/mail-footer.js

@@ -0,0 +1,73 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+const SAFE_FOOTER_URL = /^(https?:|mailto:)/i;
+const BAND_LINK_COLOR = "#4A515E";
+const UNSUBSCRIBE_LABEL_BY_LANGUAGE = {
+    de: "Abmelden",
+    en: "Unsubscribe",
+    es: "Darse de baja",
+};
+function unsubscribeLabel(locale) {
+    const language = (locale.split("-")[0] ?? locale).toLowerCase();
+    return UNSUBSCRIBE_LABEL_BY_LANGUAGE[language] ?? "Unsubscribe";
+}
+function linkHtml(link, color = "#888") {
+    const url = link.url.trim();
+    if (!SAFE_FOOTER_URL.test(url) || link.label.trim() === "")
+        return null;
+    return `<a href="${escapeHtmlAttr(url)}" style="color:${escapeHtmlAttr(color)}">${escapeHtml(link.label)}</a>`;
+}
+function webHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.host : null;
+    }
+    catch {
+        return null;
+    }
+}
+// The card's own footer line: the tenant's site and the unsubscribe link.
+export function buildMailBandLinksHtml(input) {
+    const host = input.siteUrl === undefined ? null : webHost(input.siteUrl);
+    const links = [
+        host === null || input.siteUrl === undefined
+            ? null
+            : linkHtml({ label: host, url: input.siteUrl }, BAND_LINK_COLOR),
+        input.unsubscribeUrl === "" || input.layoutLinksUnsubscribe
+            ? null
+            : linkHtml({ label: unsubscribeLabel(input.locale), url: input.unsubscribeUrl }, BAND_LINK_COLOR),
+    ];
+    return links.filter((link) => link !== null).join(" · ");
+}
+export function safeFooterUrl(link) {
+    return link !== undefined && SAFE_FOOTER_URL.test(link.url.trim()) ? link.url.trim() : "";
+}
+// Built in code with every value escaped, so it can go into the layout as raw
+// HTML. Links the layout regions already carry are left out to avoid doubling them.
+export function buildMailFooterHtml(input) {
+    const { footer, unsubscribeUrl, locale } = input;
+    const links = [];
+    if (footer?.imprint !== undefined && !input.layoutLinksImprint) {
+        const html = linkHtml(footer.imprint);
+        if (html !== null)
+            links.push(html);
+    }
+    if (footer?.privacy !== undefined) {
+        const html = linkHtml(footer.privacy);
+        if (html !== null)
+            links.push(html);
+    }
+    if (unsubscribeUrl !== "" && !input.layoutLinksUnsubscribe) {
+        const html = linkHtml({ label: unsubscribeLabel(locale), url: unsubscribeUrl });
+        if (html !== null)
+            links.push(html);
+    }
+    const text = footer?.text?.trim() ?? "";
+    const lines = [
+        ...(text === "" ? [] : [escapeHtml(text)]),
+        ...(links.length === 0 ? [] : [links.join(" · ")]),
+    ];
+    return lines.join("<br>");
+}
+export function layoutLinksToPlaceholder(layoutHtml, name) {
+    return new RegExp(`href="\\{\\{\\s*${name}\\s*\\}\\}"`).test(layoutHtml);
+}

package/dist/render.d.ts

@@ -1,2 +1,12 @@
 import { type RendererContext, type RenderRequest, type RenderResponse } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
-export declare function mailHtmlRender(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+import { type MailFooterResolver } from "./mail-footer.js";
+export type MailBrandSuffixResolver = (input: {
+    readonly locale: string;
+    readonly ctx: RendererContext;
+}) => string | null | Promise<string | null>;
+export type MailHtmlRenderOptions = {
+    readonly footer?: MailFooterResolver;
+    /** Text after the tenant name in the in-code layout's brand row, e.g. "Status". */
+    readonly brandSuffix?: MailBrandSuffixResolver;
+};
+export declare function mailHtmlRender(req: RenderRequest, ctx: RendererContext, options?: MailHtmlRenderOptions): Promise<RenderResponse>;

package/dist/render.js

@@ -1,7 +1,7 @@
 // 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).
+//      (meta.layoutSlug ?? "default", kind mail-layout, fallback to an in-code
+//      structured layout with the branding logo or tenant name as header).
 //   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.
@@ -10,24 +10,39 @@
 //   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 { 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, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
-import { buildRenderedPdfAttachments, combineMailAttachments } from "./mail-attachments.js";
-import { renderStructuredLayoutMjml } from "./structured-layout.js";
+import { DEFAULT_MAIL_LAYOUT_SLUG } from "./default-layout.js";
+import { collectRegionResourceKeys, compileDocumentSource, createDocumentHandlebars, LOGO_RESOURCE_KEY, mergeResourceFileRefs, readBrandingAccentColor, readBrandingLogo, readBrandingSiteUrl, readDocumentFormat, readTenantName, resolveResourceFileRefs, } from "./document-kit.js";
+import { buildRenderedPdfAttachments, combineMailAttachments, mergeInheritedAttachments, } from "./mail-attachments.js";
+import { brandHeaderHtml, DEFAULT_ACCENT_COLOR, readMailTone, toneColors, } from "./mail-chrome.js";
+import { buildMailBandLinksHtml, buildMailFooterHtml, layoutLinksToPlaceholder, safeFooterUrl, } from "./mail-footer.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,
+// Without a seeded layout every mail still carries the tenant's branding: accent
+// line and button color, and a brand row with the logo (or an initial tile) and the name.
+const IN_CODE_LAYOUT_META = {
+    accentLine: "branding",
+    width: 640,
+    outerBackground: "#ecedea",
 };
+async function inCodeLayout(ctx) {
+    const logoFileRefId = await readBrandingLogo(ctx);
+    return {
+        content: "<div data-content></div>",
+        format: "html",
+        ref: null,
+        template: null,
+        appearanceMeta: IN_CODE_LAYOUT_META,
+        brandHeader: { hasLogo: logoFileRefId !== undefined },
+        fileRefs: logoFileRefId === undefined ? new Map() : new Map([[LOGO_RESOURCE_KEY, logoFileRefId]]),
+    };
+}
 // 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.
@@ -53,7 +68,7 @@ async function resolveLayout(tplApi, ctx, meta, locale) {
                     useSystemLayout = true;
             }
             else {
-                useSystemLayout = layout.contentFormat === "mjml";
+                useSystemLayout = true;
             }
         }
         if (useSystemLayout) {
@@ -70,6 +85,7 @@ async function resolveLayout(tplApi, ctx, meta, locale) {
             format: layout.contentFormat === "html" ? "html" : "mjml",
             ref: { templateId: layout.id, templateVersion: layout.version, scope: layout.scope },
             template: layout,
+            appearanceMeta: layout.meta,
         };
     }
     catch (e) {
@@ -78,7 +94,7 @@ async function resolveLayout(tplApi, ctx, meta, locale) {
         if (!(e instanceof TemplateNotFoundError)) {
             throw new RendererError(`renderer-mail-html: layout resolution failed — ${describe(e)}`, "other");
         }
-        return IN_CODE_LAYOUT;
+        return null;
     }
 }
 async function findStoredMailTemplate(tplApi, ctx, slug, locale) {
@@ -92,6 +108,8 @@ async function findStoredMailTemplate(tplApi, ctx, slug, locale) {
     }
 }
 async function resolveLayoutFileRefs(tplApi, ctx, layout) {
+    if (layout.fileRefs !== undefined)
+        return layout.fileRefs;
     if (layout.format !== "html" || layout.template === null)
         return new Map();
     try {
@@ -160,12 +178,18 @@ async function resolveMailTemplate(tplApi, ctx, slug, locale, draft) {
 }
 // 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) {
+async function renderMailBody(tplApi, ctx, template, hbs, context, buttonInlineStyle, stepsColor) {
     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,
+            headingAsInlineStyle: true,
+            stepsColor,
+            ...(buttonInlineStyle !== undefined && { buttonInlineStyle }),
         });
         return {
             contentHtml: compileDocumentSource(hbs, handlebarsSource)(context),
@@ -200,77 +224,91 @@ function renderSubjectLines(hbs, meta, slug, context) {
         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;
+// Chip and tone are author-chosen per mail; a chip without a known tone takes the accent tone.
+function renderMailChrome(hbs, meta, slug, context, brandColor) {
+    const render = (source) => source === undefined ? "" : renderSubjectLine(hbs, source, context).trim();
+    try {
+        const headerChip = render(meta.headerChip);
+        const tone = readMailTone(render(meta.tone));
+        return {
+            tone: tone === undefined && headerChip === ""
+                ? undefined
+                : toneColors(tone ?? "accent", brandColor),
+            headerChip,
+            footerNote: render(meta.footerNote),
+        };
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: rendering chip, tone or footer note 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: template.pdfAttachmentLinks ?? [],
+        links: mergeInheritedAttachments(template.pdfAttachmentLinks ?? [], inherited.pdfAttachmentLinks ?? [], (link) => link.fileName),
         variables,
         locale,
         renderFileName,
     });
-    return combineMailAttachments(slug, inlineAttachments, template.fileAttachments ?? [], renderedPdfs);
+    return combineMailAttachments(slug, inlineAttachments, mergeInheritedAttachments(template.fileAttachments ?? [], inherited.fileAttachments ?? [], (file) => file.fileName), 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;
+function compileLayoutMjml(args) {
+    const { layout, hbs, contentHtml, appearance, accentColor, resourceFileRefs, layoutContext } = args;
     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 });
+        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 }),
+                ...(args.chrome.tone !== undefined && { tone: args.chrome.tone }),
+                ...(args.brandHeaderHtml !== undefined && { brandHeaderHtml: args.brandHeaderHtml }),
+                headerChip: args.chrome.headerChip,
+                footerNote: args.chrome.footerNote,
+                bandLinksHtml: args.bandLinksHtml,
+                footerHtml: args.footerHtml,
+            })
+            : compileDocumentSource(hbs, layout.content)({
+                ...layoutContext,
+                content: contentHtml,
+                mailFooterHtml: args.footerHtml,
+            });
     }
     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 ?? [];
@@ -281,21 +319,29 @@ export async function mailHtmlRender(req, ctx) {
             .join("; ");
         throw new RendererError(`renderer-mail-html: MJML compile produced ${errors.length} error(s) — ${firstErrors}`, "other");
     }
-    const text = htmlToText(mjmlResult.html, {
+    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: mjmlResult.html,
+        html,
         text,
         ...(previewText === undefined ? {} : { previewText }),
+        ...(meta.senderName !== undefined && { fromName: meta.senderName }),
+        ...(meta.replyTo !== undefined && { replyTo: meta.replyTo }),
         ...(attachments.length > 0 && { attachments }),
-        ...(draft === undefined && {
+        ...(!isDraft && {
             template: {
                 templateId: template.id,
                 templateVersion: template.version,
@@ -305,3 +351,146 @@ export async function mailHtmlRender(req, ctx) {
         ...(layout.ref === null ? {} : { layout: layout.ref }),
     };
 }
+async function resolveMailFooter(options, ctx, locale) {
+    if (options.footer === undefined)
+        return null;
+    try {
+        return await options.footer({ locale, ctx });
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: the mail footer resolver failed — ${describe(e)}`, "other");
+    }
+}
+// Only a structured (html) layout carries appearance; an mjml layout keeps its own look.
+async function resolveMailBranding(ctx, layout) {
+    const brandColor = await readBrandingAccentColor(ctx);
+    if (layout.format !== "html") {
+        return { appearance: undefined, accentColor: undefined, brandColor };
+    }
+    const accentColor = mailLayoutAppearance(layout.appearanceMeta).accentLine
+        ? brandColor
+        : undefined;
+    return {
+        appearance: mailLayoutAppearance(layout.appearanceMeta, accentColor),
+        accentColor,
+        brandColor,
+    };
+}
+async function resolveBrandSuffix(options, ctx, locale) {
+    if (options.brandSuffix === undefined)
+        return "";
+    try {
+        return (await options.brandSuffix({ locale, ctx })) ?? "";
+    }
+    catch (e) {
+        throw new RendererError(`renderer-mail-html: the brand suffix resolver failed — ${describe(e)}`, "other");
+    }
+}
+// A structured layout shows the site and unsubscribe links inside the card and only the
+// platform line below it; an mjml layout gets everything in one line.
+function renderFooterParts(args) {
+    const { layout, footer, unsubscribeUrl, locale } = args;
+    const structured = layout.format === "html";
+    const layoutLinksUnsubscribe = structured && layoutLinksToPlaceholder(layout.content, "unsubscribeUrl");
+    const footerHtml = buildMailFooterHtml({
+        footer,
+        unsubscribeUrl: structured ? "" : unsubscribeUrl,
+        locale,
+        layoutLinksImprint: structured && layoutLinksToPlaceholder(layout.content, "imprint"),
+        layoutLinksUnsubscribe,
+    });
+    return {
+        footerHtml,
+        bandLinksHtml: structured
+            ? buildMailBandLinksHtml({
+                siteUrl: args.siteUrl,
+                unsubscribeUrl,
+                locale,
+                layoutLinksUnsubscribe,
+            })
+            : "",
+    };
+}
+export async function mailHtmlRender(req, ctx, options = {}) {
+    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 [format, tenantName, footer, siteUrl, brandSuffix] = await Promise.all([
+        readDocumentFormat(ctx, locale),
+        readTenantName(ctx),
+        resolveMailFooter(options, ctx, locale),
+        readBrandingSiteUrl(ctx),
+        resolveBrandSuffix(options, ctx, locale),
+    ]);
+    const layout = (await resolveLayout(tplApi, ctx, meta, locale)) ?? (await inCodeLayout(ctx));
+    const hbs = createDocumentHandlebars(format);
+    const systemPlaceholders = {
+        tenantName,
+        signature: "",
+        imprint: safeFooterUrl(footer?.imprint),
+        unsubscribeUrl: unsubscribeUrl ?? "",
+    };
+    const context = { ...variables, ...systemPlaceholders };
+    const { appearance, accentColor, brandColor } = await resolveMailBranding(ctx, layout);
+    const chrome = renderMailChrome(hbs, meta, slug, context, brandColor);
+    const body = await renderMailBody(tplApi, ctx, template, hbs, context, appearance?.buttonStyle, chrome.tone?.bar ?? brandColor ?? DEFAULT_ACCENT_COLOR);
+    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 mjmlSource = compileLayoutMjml({
+        layout,
+        hbs,
+        contentHtml,
+        appearance,
+        accentColor,
+        resourceFileRefs,
+        layoutContext: {
+            ...systemPlaceholders,
+            lang: locale,
+            subject,
+            previewText: previewText ?? "",
+        },
+        chrome,
+        brandHeaderHtml: layout.brandHeader === undefined
+            ? undefined
+            : brandHeaderHtml({
+                tenantName,
+                suffix: brandSuffix,
+                logoSrc: layout.brandHeader.hasLogo ? `cid:${LOGO_RESOURCE_KEY}` : undefined,
+                accentColor: brandColor ?? DEFAULT_ACCENT_COLOR,
+            }),
+        ...renderFooterParts({
+            layout,
+            footer,
+            unsubscribeUrl: systemPlaceholders.unsubscribeUrl,
+            siteUrl,
+            locale,
+        }),
+    });
+    const html = await compileMjmlToHtml(mjmlSource);
+    return buildMailRenderResponse({
+        subject,
+        previewText,
+        html,
+        text: htmlToPlainText(html),
+        meta,
+        attachments,
+        template,
+        layout,
+        isDraft: draft !== undefined,
+    });
+}

package/dist/structured-layout.d.ts

@@ -1,11 +1,30 @@
+import { type MailLayoutAppearance } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { type ToneColors } from "./mail-chrome.js";
+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). */
+    /** Layout context (lang, 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;
+    /** Colors of the mail's tone; when set, the top line and the header chip use them. */
+    readonly tone?: ToneColors;
+    /** Escaped brand row built in code; replaces the header region (in-code layout only). */
+    readonly brandHeaderHtml?: string;
+    /** Plain text of the header chip, escaped here. */
+    readonly headerChip?: string;
+    /** Plain text above the card's footer links, escaped here. */
+    readonly footerNote?: string;
+    /** Escaped site and unsubscribe links from buildMailBandLinksHtml. */
+    readonly bandLinksHtml?: string;
+    /** Escaped platform line from buildMailFooterHtml; rendered below the card, never editable. */
+    readonly footerHtml?: string;
 };
 export declare function renderStructuredLayoutMjml(input: StructuredLayoutInput): string;

package/dist/structured-layout.js

@@ -1,54 +1,108 @@
 // 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>
+import { compileDocumentBodyToHandlebars, isHexColor, mailLayoutAppearance, readLayoutRegions, } from "@cosmicdrift/kumiko-bundled-features/template-resolver";
+import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { headerRowHtml } from "./mail-chrome.js";
+// 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;
+const MAIL_HEADER_IMAGE_MAX_HEIGHT_PX = 64;
+const CARD_BORDER = "#DCDFDA";
+const BAND_BACKGROUND = "#FBFBFA";
+const BAND_BORDER = "#ECEDEA";
+// 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, lineColor) {
+    const accentLine = lineColor !== undefined && isHexColor(lineColor)
+        ? `<mj-section background-color="${escapeHtmlAttr(lineColor)}" border-radius="14px 14px 0 0" padding="0">
+      <mj-column padding="0">
+        <mj-spacer height="4px" padding="0" />
+      </mj-column>
+    </mj-section>`
+        : "";
+    return `<mjml lang="{{lang}}">
   <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-all font-family="${escapeHtmlAttr(appearance.fontFamily)}" />
+      <mj-text font-size="16px" color="#2A2F3A" line-height="1.65" padding="0" />
     </mj-attributes>
   </mj-head>
-  <mj-body background-color="#f5f5f5">
-    {{#if regionHeader}}
-    <mj-section background-color="#ffffff" padding="20px">
+  <mj-body width="${appearance.width}px" background-color="${escapeHtmlAttr(appearance.outerBackground)}">
+    <mj-section padding="0">
       <mj-column>
-        <mj-text>{{{regionHeader}}}</mj-text>
+        <mj-spacer height="48px" padding="0" />
+      </mj-column>
+    </mj-section>
+    <mj-wrapper padding="0" border="1px solid ${CARD_BORDER}" border-radius="14px" background-color="#ffffff">
+    ${accentLine}
+    {{#if headerRowHtml}}
+    <mj-section padding="36px 40px 0 40px">
+      <mj-column>
+        <mj-text>{{{headerRowHtml}}}</mj-text>
       </mj-column>
     </mj-section>
     {{/if}}
-    <mj-section background-color="#ffffff" padding="20px">
+    <mj-section padding="24px 40px 32px 40px">
       <mj-column>
-        <mj-raw>{{{content}}}</mj-raw>
+        <mj-text>{{{content}}}</mj-text>
       </mj-column>
     </mj-section>
     {{#if regionSignature}}
-    <mj-section background-color="#ffffff" padding="20px">
+    <mj-section padding="0 40px 32px 40px">
       <mj-column>
         <mj-text>{{{regionSignature}}}</mj-text>
       </mj-column>
     </mj-section>
     {{/if}}
-    {{#if regionFooter}}
-    <mj-section background-color="#f5f5f5" padding="20px">
+    {{#if hasBand}}
+    <mj-section background-color="${BAND_BACKGROUND}" border-top="1px solid ${BAND_BORDER}" border-radius="0 0 14px 14px" padding="20px 40px 24px 40px">
       <mj-column>
-        <mj-text font-size="11px" color="#888" align="center">{{{regionFooter}}}</mj-text>
+        <mj-text font-size="13px" color="#5A6170">{{#if footerNote}}<p style="margin:0">{{footerNote}}</p>{{/if}}{{#if bandLinksHtml}}<p style="margin:0">{{{bandLinksHtml}}}</p>{{/if}}{{{regionFooter}}}</mj-text>
       </mj-column>
     </mj-section>
     {{/if}}
+    </mj-wrapper>
+    <mj-section padding="20px 24px 48px 24px">
+      <mj-column>
+        <mj-text font-size="12px" color="#5A6170" align="center">{{{mailFooterHtml}}}</mj-text>
+      </mj-column>
+    </mj-section>
   </mj-body>
 </mjml>`;
+}
+function topLineColor(input, appearance) {
+    if (input.tone !== undefined)
+        return input.tone.bar;
+    return appearance.accentLine ? input.accentColor : undefined;
+}
 export function renderStructuredLayoutMjml(input) {
     const regions = readLayoutRegions(input.layoutHtml);
-    const renderRegion = (region) => region.trim() === ""
+    const renderRegion = (region, maxHeightPx) => region.trim() === ""
         ? ""
-        : input.compile(compileDocumentBodyToHandlebars(region, {}, input.resourceSrc && { resourceSrc: input.resourceSrc }))(input.context);
-    return input.compile(STRUCTURED_LAYOUT_FRAME)({
+        : input.compile(compileDocumentBodyToHandlebars(region, {}, {
+            ...(input.resourceSrc && { resourceSrc: input.resourceSrc }),
+            resourceImageMaxWidthPx: MAIL_IMAGE_MAX_WIDTH_PX,
+            ...(maxHeightPx !== undefined && { resourceImageMaxHeightPx: maxHeightPx }),
+        }))(input.context);
+    const appearance = input.appearance ?? mailLayoutAppearance({});
+    const frame = structuredLayoutFrame(appearance, topLineColor(input, appearance));
+    const headerLeft = input.brandHeaderHtml ?? renderRegion(regions.header, MAIL_HEADER_IMAGE_MAX_HEIGHT_PX);
+    const chip = input.headerChip ?? "";
+    const regionFooter = renderRegion(regions.footer);
+    const footerNote = input.footerNote?.trim() ?? "";
+    const bandLinksHtml = input.bandLinksHtml ?? "";
+    return input.compile(frame)({
         ...input.context,
         content: input.contentHtml,
-        regionHeader: renderRegion(regions.header),
+        headerRowHtml: input.tone === undefined || chip.trim() === ""
+            ? headerLeft
+            : headerRowHtml(headerLeft, chip, input.tone),
         regionSignature: renderRegion(regions.signature),
-        regionFooter: renderRegion(regions.footer),
+        regionFooter,
+        footerNote,
+        bandLinksHtml,
+        mailFooterHtml: input.footerHtml ?? "",
+        hasBand: regionFooter !== "" || footerNote !== "" || bandLinksHtml !== "",
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-mail-html",
-  "version": "0.363.0",
+  "version": "0.365.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>",
@@ -19,16 +19,16 @@
     }
   },
   "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",
+    "@cosmicdrift/kumiko-bundled-features": "0.365.0",
+    "@cosmicdrift/kumiko-framework": "0.365.0",
+    "@cosmicdrift/kumiko-headless": "0.365.0",
+    "@cosmicdrift/kumiko-types": "0.365.0",
     "handlebars": "^4.7.8",
     "html-to-text": "^9.0.5",
     "mjml": "^5.2.2"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.363.0",
+    "@cosmicdrift/kumiko-testing": "0.365.0",
     "@types/html-to-text": "^9.0.4",
     "@types/mjml": "^5.0.0"
   },

package/src/changes.json

@@ -1,4 +1,40 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Structured mail layouts render as a card with a footer band",
+    "detail": "The structured frame now draws a rounded white card with a border on the outer background. The top line sits inside the card, the footer region goes into a grey band at the bottom of the card, and the platform line from the footer resolver sits below the card. The in-code layout uses 640 px width and #ecedea as outer background and shows the tenant logo at 28 px height beside the tenant name, or an initial tile in the accent colour when no logo is set. Mail headings carry inline sizes (h1 30 px bold) and small text renders at 13 px. Existing structured layouts change their look accordingly; mjml layouts are unchanged."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Mail meta headerChip, tone and footerNote",
+    "detail": "A mail template can set meta.headerChip (a chip right of the brand row), meta.tone (accent, info, success, warning, danger or neutral; colours the chip, the top line of the card and the steps block) and meta.footerNote (a line above the site and unsubscribe links in the card band). All three accept placeholders and are rendered escaped; an unknown tone falls back to the accent colour. The band links the tenant site from the branding siteUrl next to the unsubscribe link. createRendererMailHtmlFeature({ brandSuffix }) adds a word after the tenant name in the brand row."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "createRendererMailHtmlFeature takes a footer resolver for imprint, privacy and platform line",
+    "detail": "createRendererMailHtmlFeature({ footer }) resolves a footer per mail from locale and renderer context: an optional text line plus imprint and privacy links. The renderer appends it below every layout, the in-code one, mjml layouts and structured tenant layouts, so a tenant cannot edit or delete it. Values are escaped and only http(s) and mailto links are kept. The imprint URL also fills the {{imprint}} system placeholder, and a layout region that already links {{imprint}} or {{unsubscribeUrl}} is not doubled. The unsubscribe link is labelled in the mail language (de, en, es, English otherwise). Without a resolver only the unsubscribe link is added, as before."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Without a stored layout mails use the tenant branding logo and accent colour",
+    "detail": "When no tenant or system layout exists, the renderer no longer falls back to a bare MJML frame. It renders the structured frame with the branding logo in the header (or the tenant name when no logo is set), the accent line and buttons in the branding accent colour, and the platform footer. Layout HTML now carries lang from the mail locale instead of lang=\"und\"."
+  },
+  {
+    "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",