@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/api.ts

@@ -3,13 +3,23 @@
 // ctx.templateResolver at runtime.
 
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { FileAttachmentRef } from "../renderer-foundation/index.js";
 import type { ContentFormat, TemplateKind } from "./constants.js";
 import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./constants.js";
+import {
+  fileAttachmentsOf,
+  imageLinksOf,
+  parseLinkedResourceEntries,
+  pdfAttachmentLinksOf,
+  type TemplatePdfAttachmentLink,
+} from "./linked-resources.js";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+import { activeVersionOf, servedVersionOf } from "./template-draft.js";
+import { parseTemplateMeta, type TemplateMeta } from "./template-meta.js";
 
 // Public TemplateResource: what consumers see. Hides DB-internal columns
 // (insertedById, internal id-type) but keeps the fields needed for rendering.
@@ -25,7 +35,15 @@ export type TemplateResource = {
   readonly content: string;
   readonly contentFormat: ContentFormat;
   readonly variableSchema: Record<string, unknown>;
+  /** Embeddable images: resource key -> fileRef id. */
   readonly linkedResources: Record<string, string>;
+  /** Files attached to every mail rendered from this template, ordered by key. */
+  readonly fileAttachments?: readonly FileAttachmentRef[];
+  /** PDFs rendered from document templates and attached at send time, ordered by key. */
+  readonly pdfAttachmentLinks?: readonly TemplatePdfAttachmentLink[];
+  /** Parsed per kind; null when absent or when the stored JSON no longer
+   *  matches the kind's schema (the renderer then fails with a clear error). */
+  readonly meta: TemplateMeta | null;
   readonly scope: "system" | "tenant";
   readonly parentTemplateId: string | null;
   readonly status: "draft" | "active" | "archived";
@@ -39,6 +57,15 @@ export type ResolveRequest = {
   readonly locale: string;
 };
 
+export type LayoutKind = "mail-layout" | "pdf-layout";
+
+export type ResolveLayoutRequest = {
+  readonly tenantId: TenantId;
+  readonly slug: string;
+  readonly kind: LayoutKind;
+  readonly locale: string;
+};
+
 export type TemplateResolverApi = {
   /**
    * Findet ein konkretes Template by (tenantId, slug, kind, locale).
@@ -74,9 +101,20 @@ export type TemplateResolverApi = {
    * User cross-tenant Templates abfragen (Tenant-Isolation gebrochen).
    */
   readonly resolveTemplate: (args: ResolveRequest) => Promise<TemplateResource>;
+
+  /**
+   * Layouts are locale-neutral in the product (the layout editor saves under the locale of the
+   * row it loaded), so the locale chain is wider than resolveTemplate: tenant (requested,
+   * FALLBACK_LOCALE, any active locale), then system (same). Only active rows count; among
+   * "any" the highest version wins, then the alphabetically first locale, so the pick is stable.
+   * Throws TemplateNotFoundError when neither scope has an active row.
+   *
+   * **Caller invariant:** `tenantId` must come from the server, as for `resolveTemplate`.
+   */
+  readonly resolveLayout: (args: ResolveLayoutRequest) => Promise<TemplateResource>;
 };
 
-export function createTemplateResolverApi(db: DbRunner): TemplateResolverApi {
+export function createTemplateResolverApi(db: DbRunner | TenantDb): TemplateResolverApi {
   return {
     findExact: async ({ tenantId, slug, kind, locale, scope }) => {
       const effectiveTenantId = scope === "system" ? SYSTEM_TENANT_ID : tenantId;
@@ -102,11 +140,39 @@ export function createTemplateResolverApi(db: DbRunner): TemplateResolverApi {
       }
       throw new TemplateNotFoundError({ slug, kind, locale });
     },
+
+    resolveLayout: async ({ tenantId, slug, kind, locale }) => {
+      for (const tid of [tenantId, SYSTEM_TENANT_ID]) {
+        const rows = await selectMany<TemplateResourceRow>(db, templateResourcesTable, {
+          tenantId: tid,
+          slug,
+          kind,
+        });
+        const row = pickActiveLayoutRow(rows, locale);
+        if (row !== null) return toPublic(row);
+      }
+      throw new TemplateNotFoundError({ slug, kind, locale });
+    },
   };
 }
 
+function pickActiveLayoutRow(
+  rows: readonly TemplateResourceRow[],
+  locale: string,
+): TemplateResourceRow | null {
+  const active = rows
+    .filter((row) => row.status === "active")
+    .sort((a, b) => activeVersionOf(b) - activeVersionOf(a) || a.locale.localeCompare(b.locale));
+  return (
+    active.find((row) => row.locale === locale) ??
+    active.find((row) => row.locale === FALLBACK_LOCALE) ??
+    active[0] ??
+    null
+  );
+}
+
 async function fetchTemplate(
-  db: DbRunner,
+  db: DbRunner | TenantDb,
   tenantId: string,
   slug: string,
   kind: TemplateKind,
@@ -127,7 +193,6 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
   // @cast-boundary db-row — Drizzle-Schema typisiert kind/contentFormat/
   // scope/status als generic text. CHECK-Constraints in der DB schränken
   // sie auf die Union-Types ein; Cast assertet das Schema-Wissen.
-  // linkedResources ist ein text-column mit JSON-payload (string→string map).
   const kind = row.kind as TemplateKind;
   // @cast-boundary db-row — siehe kind.
   const contentFormat = row.contentFormat as ContentFormat;
@@ -135,12 +200,10 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
   const scope = row.scope as "system" | "tenant";
   // @cast-boundary db-row — siehe kind.
   const status = row.status as "draft" | "active" | "archived";
-  // @cast-boundary db-row — parseJson returnt Record<string, unknown>;
-  // linkedResources-Spalte enthält per Schema {key: signedUrl}-Map.
-  const linkedResources = parseJson(row.linkedResources) as Record<string, string>;
+  const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
   return {
     id: String(row.id),
-    version: row.version,
+    version: servedVersionOf(row),
     tenantId: row.tenantId,
     slug: row.slug,
     kind,
@@ -150,7 +213,10 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
     content: row.content ?? "",
     contentFormat,
     variableSchema: parseJson(row.variableSchema),
-    linkedResources,
+    linkedResources: imageLinksOf(linkedEntries),
+    fileAttachments: fileAttachmentsOf(linkedEntries),
+    pdfAttachmentLinks: pdfAttachmentLinksOf(linkedEntries),
+    meta: parseStoredMeta(kind, row.meta),
     scope,
     parentTemplateId: row.parentTemplateId,
     status,
@@ -158,6 +224,16 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
   };
 }
 
+function parseStoredMeta(kind: TemplateKind, raw: string | null): TemplateMeta | null {
+  if (!raw) return null;
+  try {
+    const result = parseTemplateMeta(kind, JSON.parse(raw));
+    return result.ok ? result.meta : null;
+  } catch {
+    return null;
+  }
+}
+
 function parseJson(raw: string | null): Record<string, unknown> {
   if (!raw) return {};
   try {

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,190 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "PDF collections show Page break instead of Button, and placeholder links no longer insert {{name}} text",
+    "detail": "The content editor for a `document-pdf` collection now offers the PDF block set (including Page break) instead of the mail set, chosen from the collection's kind. A link to a placeholder href such as `{{invoice.url}}` without a selection now links a variable node instead of inserting the placeholder as plain text."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Document sanitizer rejects prototype-style placeholder hrefs",
+    "detail": "`{{__proto__}}` and `{{constructor.prototype}}` are no longer accepted as link or button placeholder hrefs; only valid reference names pass."
+  },
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "DocumentRepeatRow is removed, use DocumentTableRow",
+    "detail": "Removed the DocumentRepeatRow alias",
+    "migration": "Replace `DocumentRepeatRow` with `DocumentTableRow` (identical shape)."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "export-bundle for a system template with resources returns a validation error outside the system tenant",
+    "detail": "A TenantAdmin, or a SystemAdmin outside the system tenant, exporting a system template that links resource files now gets the `system_resources_need_system_tenant` validation error, the same code import-bundle-system uses, instead of a NotFound for the resource file."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "send-test logs failed test mails with error class and tenant",
+    "detail": "A transport that throws or reports not sent is logged with the error class/code and tenant id (no address, no provider body) and still answers `template_test_mail_failed`."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "copy-locale ignores archived tenant sources and duplicates linked files of system sources; export-bundle refuses locales with differing format",
+    "detail": "copy-locale no longer copies from an archived tenant template, and copying a system template duplicates its linked resource files into the target tenant. export-bundle rejects a bundle whose locales differ in content format or variable schema with `bundleLocalesDiffer`."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Template preview counts encoding overhead and reports missing attachments",
+    "detail": "The mail size estimate counts base64 size plus a fixed per-part overhead, an attachment whose file reference is missing fails the resources_resolved check, and the document draft scope is derived once per request."
+  },
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "A draft no longer replaces the active template",
+    "detail": "Saving a draft (upsert-tenant default, copy-locale, import-bundle with status draft) over an active template stores it beside the active version in the new column draft instead of overwriting content, meta and status; resolveTemplate, resolveLayout, preview without content and sends keep using the active version. publish and publish-system promote an open draft (the publish gate checks the draft) and record activeVersion and activeSince; the new handlers discard-draft and discard-draft-system drop it and refuse with no_draft when none is open. find-by-id and layout-source return the working version (the open draft with status draft, else the stored one) plus active { version, since }, null when nothing is served. overview keeps status and version of the served version and adds draftVersion and activeSince. A draft over a row that is not active (new, draft or archived) behaves as before. A tenant never sees system draft content: find-by-id, layout-source, overview, copy-locale and diff-to-system apply a system draft only for a SystemAdmin and hide system rows that were never served; list leaves those rows out too. Version numbers shown for an active row are the served version (activeVersion): resolveTemplate / resolveLayout results, tenant-overrides rows and the override diff no longer show the save counter that drafts raise.",
+    "migration": "Run kumiko schema generate and apply the migration before deploying: it adds the nullable columns draft, active_version and active_since to read_template_resources. No rebuild needed."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "template-resolver:query:overview accepts layoutSlug to list only the mails and PDFs using that layout",
+    "detail": "The optional layoutSlug payload field keeps only documents whose layout slug matches; total counts the filtered rows. Without it the response is unchanged."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Layout usage follows the effective template per notification and locale",
+    "detail": "Mail layout usage counts a notification only when it declares a template and resolves the effective row per notification and locale, so tenant overrides are reflected."
+  },
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "templateVariable.richText for notification variables that carry formatted HTML",
+    "detail": "Notification variables are escaped, so a value holding HTML (for example a document written in a rich text editor) showed up as literal tags in the mail. A variable declared with templateVariable.richText({ required }) is run through the document sanitizer at render time and inserted as HTML; bold, italic, lists and safe links stay, script, event handlers and javascript links are not emitted as markup. If the sanitizer rejects a value, it is rendered as escaped text and a warning with the violation codes is logged. All other variable types stay escaped."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Overview and layout-source queries for the template designer",
+    "detail": "template-resolver:query:overview lists the mail, PDF and layout templates of the caller's tenant grouped by slug and kind (effective origin, locales, status, versions, layout slug, last change and the notifications that use it) and template-resolver:query:layout-source returns the header, signature and footer regions of a mail or PDF layout plus the locale a save has to use; a SystemAdmin also receives the MJML source of the system layout. The usage lookup is the exported collectTemplateUsage."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "contentFormat \"document\" with a toolbar editor for mail and PDF templates",
+    "detail": "ContentEditorFormat gains \"document\". template-resolver registers DocumentContentEditor for it (tiptap, lazy-loaded) and stores the body as html. The toolbar offers paragraph style, bold, italic, lists, links, placeholders and the blocks image, table, button, divider, repeat and page break; the blocks prop picks them (MAIL_DOCUMENT_BLOCKS, PDF_DOCUMENT_BLOCKS). Placeholders are inserted only as variable nodes (data-variable), never as {{name}} text. ContentPreview does not substitute example values for \"document\" content, because substituting a button or link href would make the schema drop that node. New exports from template-resolver/web: DocumentContentEditor, DocumentEditorProps, DocumentToolbarBlock, MAIL_DOCUMENT_BLOCKS, PDF_DOCUMENT_BLOCKS."
+  },
+  {
+    "version": "0.363.0",
+    "type": "fix",
+    "title": "Preview uses the examples of a stored or draft variable schema",
+    "detail": "A template's variableSchema kept only type and required, label and example were dropped, so the preview showed [name] instead of the declared example. The schema now keeps label and example, for mail and document previews."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "PDF meta gets orientation, printBackground and layoutHeaderFooter; paragraphs and headings get data-align",
+    "detail": "The document-pdf meta accepts orientation (portrait or landscape), printBackground (default true) and layoutHeaderFooter (false prints without the layout header and footer). Paragraphs and headings carry textAlign (left, center, right, justify), serialized as data-align and kept by the sanitizer only with these four values. New exports are evaluateDocumentDraft, localeSchema, DOCUMENT_TEXT_ALIGNMENTS and DocumentTextAlign; compileDocumentBodyToHandlebars accepts alignmentAsInlineStyle."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "document-pdf templates require contentFormat html, and html bodies are sanitized on write",
+    "detail": "upsertSystem, upsertTenant, the collection-set handlers and seedSystemTemplate rebuild html bodies of kind mail-html and document-pdf through the new document schema (template-resolver/document-schema). Script elements, inline event handlers, embedded content (iframe, frame, object, embed, applet, portal), links and url attributes (svg href, xlink:href, form action, base) outside https/http/mailto/tel/{{placeholder}}, external image sources, alt text containing < or >, and invalid or prototype-chain variable names are rejected with a validation_error (or a thrown Error in seedSystemTemplate); anything the schema cannot express is dropped silently, and links keep only href (no target, rel, class or title). New exports: documentExtensions, DocumentLink and the other Document* nodes, isAllowedDocumentLinkHref, isDocumentReferenceName, isDocumentResourceKey, isDocumentPlaceholderHref, sanitizeDocumentHtml, sanitizeTemplateBody. kind document-pdf with another contentFormat is rejected with document_requires_html_format.",
+    "migration": "Store document-pdf bodies as html and reference images via data-resource instead of src. mail-html with markdown or mjml is unchanged."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mail templates carry file attachments (PDF, PNG, JPEG)",
+    "detail": "linkedResources stays image only; file attachments of a mail template are listed in the optional TemplateResource.fileAttachments (kind file, fileRefId, fileName), sorted by key. template-resolver:write:resource-upload takes purpose \"attachment\" with a fileName; it checks the file by content (PDF, PNG, JPEG), keeps the original bytes, allows at most 10 per mail template and stores the entry next to the inline images. resource-remove, copy-locale and the bundle export/import carry attachments (bundle resource entries get purpose \"attachment\"). The preview lists attachments with kind \"inline\" or \"file\" (PreviewAttachment is now a union), send-test sends them, and the mail renderer attaches them after the inline images within the delivery attachment limit."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "copy-locale can copy system templates (scope \"system\", system admins only)",
+    "detail": "template-resolver:write:copy-locale takes scope \"tenant\" (default) or \"system\". With \"system\" a system admin copies a system template to another locale as a draft; other callers get access denied."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mail preview returns displayHtml for the editor",
+    "detail": "The preview of a mail template carries displayHtml, the body with cid images replaced by data URIs (png, jpeg, gif, webp, 5 MiB budget in total) so an editor can show it without cid support. The sent mail is unchanged."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Document editor gets variable labels, a handle, resource previews, canvas chrome, underline and PlaceholderLineEditor",
+    "detail": "DocumentContentEditor accepts variableLabels, systemVariables, resourcePreviews, chrome (\"default\" or \"canvas\") and onEditorReady (handle with insertPlaceholder, insertResource, focus). The new PlaceholderLineEditor edits plain text with {{name}} placeholders as chips on one line. Underline (u) is part of the document schema and survives the sanitizer."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Mail templates link a PDF rendered from a document template (resource-link-pdf)",
+    "detail": "New write template-resolver:write:resource-link-pdf takes templateId, key, templateSlug and fileName and stores a linkedResources entry { kind \"rendered-pdf\", templateSlug, fileName } in a mail template; nothing is uploaded. fileName is a one-line pattern that may use the mail's {{placeholders}} and must end with .pdf (no / \\ \" ; or ..). The document-pdf template must exist for the tenant or the system, otherwise the write fails with template_attachment_pdf_template_missing; an invalid pattern or slug fails with template_attachment_invalid. Uploaded files and linked PDFs share the limit of 10 attachments per template. resource-remove, copy-locale and the bundle export/import carry the entry (the bundle gets an optional pdfAttachments map of key to { templateSlug, fileName }; import does not check that the document template exists). TemplateResource gains pdfAttachmentLinks, LinkedResourceEntry gains the TemplatePdfAttachmentLink variant."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Preview and test mail use the images and attachments of the edited row, also while it is a draft",
+    "detail": "When preview or send-test get content and the caller has a row for (slug, kind, locale), that row supplies linkedResources whatever its status (also when it has none, so nothing is borrowed from the system template), so a tenant whose customization is saved as a draft sees its logo and attachments. MailDraft has an optional linkedResources; without it the stored active template's resources are used as before. PreviewAttachment gains the variant { kind \"rendered-pdf\", name, templateSlug } without sizeBytes, because the PDF is not rendered in the preview; size_under_cap does not count it."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Preview query and send-test write for mail and PDF templates",
+    "detail": "template-resolver:query:preview renders a draft, or the stored template when no content is given, with sample values from the declared variable examples (list variables get two rows). The draft passes the same write gates as a save and a mail goes through the real mail renderer, so subject, html, plain text and inline images match a real send. The response carries checks (images resolved, plain text present, size under 10 MiB, required placeholders used); a PDF template returns its sanitized body and the layout regions. template-resolver:write:send-test mails the rendered mail to the calling user's own address only, subject prefixed with [TEST], limited to 10 per user and hour. It needs delivery, channel-email and renderer-mail-html."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "DocumentEditorProps toolbar option for an icon-only toolbar",
+    "detail": "DocumentEditorProps gains toolbar (\"full\" or \"compact\", default \"full\"). Compact renders the placeholder and block buttons icon-only with a tooltip and a narrower paragraph select, for narrow columns such as the layout editor regions. The formatting buttons now carry a tooltip with their label in every mode."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "kind mail-html is replaced by mail, mail-layout and pdf-layout; templates carry meta",
+    "detail": "The kind mail-html is removed; the new non-render kind snippet holds collection content (reply snippets, signatures; any contentFormat, html is sanitized like a mail body). Mail bodies are kind mail (contentFormat html only, rebuilt through the document schema, meta.subject required), mail frames are kind mail-layout (contentFormat mjml), and pdf-layout (html) is new. The table gains a nullable meta column (JSON per kind, validated by parseTemplateMeta: mail takes subject, previewText, layoutSlug, category, sender; layouts take none; other kinds take no meta) and the template-resource entity moves to eventVersion 2 with an upcaster that reads stored mail-html events as mail. upsertSystem, upsertTenant (active), publish and seedSystemTemplate reject unknown placeholders and, for the same writes, bodies that miss a required variable of the notification with the same qualified name; a tenant draft may be incomplete and returns validation. Slugs must be kebab segments joined by a colon. seedSystemTemplate now validates the slug (templateSlugSchema) and the per-kind meta for every kind. A content collection of kind mail, mail-layout or pdf-layout is refused on collection-set (field issue on kind, templateResolver.errors.collection.kindNotAllowed), because such a tenant row would shadow the system template without the meta and placeholder gates. TemplateResource gains meta. New exports: parseTemplateMeta, isMailTemplateMeta, templateSlugSchema, validateTemplatePlaceholders, resolveTemplateVariables, compileDocumentBodyToHandlebars, MAIL_CATEGORIES and their types; seedNotificationTemplates and hasNotificationTemplates on template-resolver/seeding, which applyBootSeeds now calls. RENDER_KINDS contains mail instead of mail-html.",
+    "migration": "Rename kind mail-html to mail in app code, collections and seeds; mail bodies must be contentFormat html (markdown or mjml mail bodies are rejected) and carry meta.subject, mail layouts use kind mail-layout with contentFormat mjml and slug default. Slugs of every kind must now be kebab segments joined by a colon (upsert handlers and seedSystemTemplate reject dotted, underscored or camelCase slugs). Collections that used kind mail-html move to the new kind snippet (stored mail-html rows are upcast to mail, which collections refuse, so re-create those entries under snippet); collection-set refuses mail, mail-layout and pdf-layout collections. seedSystemTemplate callers must pass a kebab slug and valid meta for every kind, not only mail. Generate and apply the migration that adds the nullable meta column to read_template_resources; it ships a rebuild marker for read_template_resources so existing mail-html rows are read as mail after the rebuild."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "resolveLayout finds a layout in any locale",
+    "detail": "TemplateResolverApi gains resolveLayout({ tenantId, slug, kind, locale }) for mail-layout and pdf-layout. It looks at the tenant first (requested locale, then the fallback locale, then any active locale) and then at the system layouts the same way, ignoring draft and archived rows. A layout saved by the layout editor under one locale is therefore found for every locale. The template preview uses it for the PDF layout."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "PDF template meta, render provenance, system template lifecycle and override queries",
+    "detail": "kind document-pdf takes a strict meta (layoutSlug, pageFormat A4/Letter, margins in mm, fileName without / \\ \" ; or .., metadata title/author); new exports PDF_PAGE_FORMATS, PdfPageFormat, PdfTemplateMeta, readPdfTemplateMeta, DEFAULT_MAIL_LAYOUT_SLUG. RenderResponse (renderer-foundation) gains optional template and layout refs ({ templateId, templateVersion, scope }, new types RenderedTemplateRef and RenderProvenance); renderer-mail-html fills them. New handlers template-resolver:write:publish-system and archive-system (SystemAdmin), reset-to-system (TenantAdmin, SystemAdmin), queries usage, tenant-overrides (SystemAdmin, counts only) and diff-to-system. publish and archive answer not_found for rows outside the caller's tenant instead of a version_conflict; find-by-id also returns meta."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "linkedResources is no longer a payload field of upsertSystem/upsertTenant; resourceUpload and resourceRemove manage it",
+    "detail": "Two steps - upload the image with POST /api/files (multipart, no entityType), then call template-resolver:write:resource-upload with { sourceFileRefId, templateId?, key? }. The handler re-encodes the caller's own unclaimed upload into a new file ref (width at most 1200 px) and links it into the template; resource-remove unlinks a key. upsertSystem and upsertTenant no longer accept linkedResources and leave the stored value untouched on update. The size cap is the system config key resource-max-bytes (default 2 MiB); a cap above the files route's maxUploadSize has no effect because the upload is rejected first. The source upload stays as an unclaimed file.",
+    "migration": "Whoever sent linkedResources with upsertSystem or upsertTenant now uploads the image via POST /api/files (multipart, no entityType) and links it with template-resolver:write:resource-upload { sourceFileRefId, templateId, key }. Server-side seeding (seedSystemTemplate linkedResources) stays."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "Bundle import re-encodes its images like resource-upload; re-seeding keeps uploaded system resources",
+    "detail": "importBundle and importBundleSystem store each bundle resource through the same normalization as resource-upload (decoded format decides the content type, SVG and non-images are rejected, width at most 1200 px, resource-max-bytes applies), so an exported bundle carries the re-encoded bytes. seedSystemTemplate without linkedResources no longer resets the links of an existing row, so images a system admin uploaded survive the next boot. storeTemplateResource from the template-resolver barrel is the normalizing store; the raw byte variant is gone."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "Tenant mail-layouts are structured html, pdf-layout and document-pdf are placeholder-validated",
+    "detail": "A new validate query dry-runs the write pipeline (used, unknown and missing placeholders, canSave, canPublish). document-pdf, pdf-layout and mail-layout now go through the same placeholder gate as mail; document-pdf and pdf-layout know the system placeholders page and pages. A tenant mail-layout is html with a data-content slot plus header, signature and footer regions that renderer-mail-html wraps in a fixed MJML frame; raw mjml (with {{{content}}} exactly once) is system-only. New handlers export-bundle, import-bundle, import-bundle-system and copy-locale move a template with its resource files between tenants and locales. r.notification accepts a record mapping from an entity row to the declared variables, validated at boot. publish and archive no longer touch system rows through a tenant-scoped SystemAdmin.",
+    "migration": "Tenant mail-layout rows stored as mjml are ignored by the renderer, which falls back to the system layout; re-create them as html with a data-content slot. upsert-system answers with an extra validation field. seedSystemTemplate errors now read `<label> rejected: <code> (<detail>); ...`. Layout bodies without the content slot are rejected on write. `set` now runs the same gate for mail, document-pdf, pdf-layout and mail-layout rows and rejects unsanitized markup or publish issues, since saving publishes; the mail renderer also re-sanitizes stored tenant html layouts and falls back to the system layout when they fail. upsert-system and upsert-tenant no longer accept linkedResources (resources go through the resource upload; bundle import and copy-locale attach them). Unknown data-resource keys are a validate warning (resource_not_uploaded), not a write error."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/template-resolver/compile-document-body.ts

@@ -0,0 +1,278 @@
+import type { TemplateVariableDef, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import type { Element as ScanElement } from "happy-dom";
+import { withParsedDocument } from "./document-sanitizer.js";
+import {
+  DOCUMENT_TEXT_ALIGNMENTS,
+  isAllowedDocumentLinkHref,
+  isDocumentPlaceholderHref,
+  isDocumentReferenceName,
+  isDocumentResourceKey,
+} from "./document-schema.js";
+
+// Private-use characters mark where a Handlebars expression goes. Author text
+// is scrubbed of them first and every `{`/`}` is entity-encoded before the
+// markers are swapped for real expressions, so the only Handlebars syntax in
+// the output is the syntax this module wrote.
+const EXPRESSION_OPEN = "\uE000";
+const EXPRESSION_CLOSE = "\uE001";
+const MARKER_PATTERN = /\uE000(\d+)\uE001/g;
+
+type RowScope = { readonly listName: string; readonly itemFields: TemplateVariables } | null;
+
+type CompileState = {
+  readonly variables: TemplateVariables;
+  readonly expressions: string[];
+};
+
+function marker(state: CompileState, expression: string): string {
+  state.expressions.push(expression);
+  return `${EXPRESSION_OPEN}${state.expressions.length - 1}${EXPRESSION_CLOSE}`;
+}
+
+function ownVariable(variables: TemplateVariables, name: string): TemplateVariableDef | undefined {
+  return Object.hasOwn(variables, name) ? variables[name] : undefined;
+}
+
+function itemFieldsOf(variables: TemplateVariables, listName: string): TemplateVariables | null {
+  const def = ownVariable(variables, listName);
+  return def?.type === "list" ? def.item : null;
+}
+
+function rowScopeOf(element: ScanElement, state: CompileState): RowScope {
+  const listName = element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
+  if (listName === null) return null;
+  const itemFields = itemFieldsOf(state.variables, listName);
+  return itemFields === null ? null : { listName, itemFields };
+}
+
+function resolveReference(
+  name: string,
+  scope: RowScope,
+  variables: TemplateVariables,
+): { readonly path: string; readonly def: TemplateVariableDef | undefined } {
+  if (scope !== null && ownVariable(scope.itemFields, name) !== undefined) {
+    return { path: name, def: ownVariable(scope.itemFields, name) };
+  }
+  return { path: scope === null ? name : `@root.${name}`, def: ownVariable(variables, name) };
+}
+
+function valueExpression(path: string, def: TemplateVariableDef | undefined): string {
+  if (def?.type === "money") return `{{money ${path}}}`;
+  if (def?.type === "date") return `{{date ${path}}}`;
+  if (def?.type === "richText") return `{{richText ${path}}}`;
+  return `{{${path}}}`;
+}
+
+function rewriteVariable(element: ScanElement, state: CompileState): void {
+  const name = element.getAttribute("data-variable") ?? "";
+  const replacement = element.ownerDocument.createTextNode(
+    isDocumentReferenceName(name)
+      ? marker(state, valueExpression(...pathAndDef(name, element, state)))
+      : "",
+  );
+  element.replaceWith(replacement);
+}
+
+function pathAndDef(
+  name: string,
+  element: ScanElement,
+  state: CompileState,
+): [string, TemplateVariableDef | undefined] {
+  const { path, def } = resolveReference(name, rowScopeOf(element, state), state.variables);
+  return [path, def];
+}
+
+function rewriteLink(element: ScanElement, state: CompileState): void {
+  const href = element.getAttribute("href") ?? "";
+  if (isDocumentPlaceholderHref(href)) {
+    const name = href.slice(2, -2);
+    if (isDocumentReferenceName(name)) {
+      const [path] = pathAndDef(name, element, state);
+      element.setAttribute("href", marker(state, `{{link ${path}}}`));
+    } else {
+      element.setAttribute("href", "#");
+    }
+  } else if (!isAllowedDocumentLinkHref(href)) {
+    element.setAttribute("href", "#");
+  }
+}
+
+function rewriteRepeatRow(row: ScanElement, state: CompileState): void {
+  const listName = row.getAttribute("data-each") ?? "";
+  const document = row.ownerDocument;
+  if (itemFieldsOf(state.variables, listName) === null || !isDocumentReferenceName(listName)) {
+    row.remove();
+  } else {
+    row.before(document.createTextNode(marker(state, `{{#each ${listName}}}`)));
+    row.after(document.createTextNode(marker(state, "{{/each}}")));
+    row.removeAttribute("data-each");
+    row.removeAttribute("data-repeat-header");
+  }
+}
+
+function stripActiveContent(element: ScanElement): void {
+  for (const attribute of Array.from(element.attributes)) {
+    if (/^on/i.test(attribute.name)) element.removeAttribute(attribute.name);
+  }
+}
+
+function neutralizeBraces(html: string): string {
+  return html.replace(/[{}]/g, (brace) => (brace === "{" ? "{" : "}"));
+}
+
+export type CompileDocumentBodyOptions = {
+  // Returns the src for an `img[data-resource]` key; undefined drops the image.
+  readonly resourceSrc?: (key: string) => string | undefined;
+  // Mail clients ignore document CSS, so a full-width logo needs an inline width cap.
+  readonly resourceImageMaxWidthPx?: number;
+  // Mail clients ignore document CSS, so mail turns data-align into an inline style.
+  readonly alignmentAsInlineStyle?: boolean;
+  // Same reason: a[data-button] only looks like a button through editor/print CSS.
+  readonly buttonAsInlineStyle?: boolean;
+  // Same reason: cell padding and table width only exist in editor/print CSS, so without
+  // inline styles a mail table renders its cells flush against each other.
+  readonly tableAsInlineStyle?: boolean;
+  // Replaces the default button look; only values from the layout appearance belong here.
+  readonly buttonInlineStyle?: string;
+};
+
+const MAIL_BUTTON_STYLE =
+  "display:inline-block;padding:10px 20px;border-radius:6px;background-color:#1f5468;color:#ffffff;font-weight:600;text-decoration:none";
+
+const MAIL_TABLE_STYLE = "width:100%;border-collapse:collapse";
+const MAIL_TABLE_CELL_STYLE = "padding:6px 12px;vertical-align:top;border-bottom:1px solid #e5e5e5";
+const MAIL_TABLE_HEAD_STYLE = "font-size:12px;font-weight:600;color:#6b7280;text-align:left";
+const MAIL_SMALL_STYLE = "font-size:12px;color:#6b7280";
+
+// Appended after an existing style (data-align) so the alignment survives.
+function appendStyle(element: ScanElement, style: string): void {
+  const existing = element.getAttribute("style");
+  element.setAttribute("style", existing === null ? style : `${existing};${style}`);
+}
+
+const RESOURCE_IMAGE_CONTENT_TYPES: ReadonlySet<string> = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+]);
+
+// Unique valid resource keys in document order.
+export function collectDocumentResourceKeys(html: string): readonly string[] {
+  return withParsedDocument(html, (root) => {
+    const keys = new Set<string>();
+    for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
+      const key = element.getAttribute("data-resource") ?? "";
+      if (isDocumentResourceKey(key)) keys.add(key);
+    }
+    return [...keys];
+  });
+}
+
+export function toResourceDataUri(contentType: string, bytes: Uint8Array): string {
+  if (!RESOURCE_IMAGE_CONTENT_TYPES.has(contentType)) {
+    throw new Error(`resource content type "${contentType}" cannot be embedded as an image`);
+  }
+  return `data:${contentType};base64,${Buffer.from(bytes).toString("base64")}`;
+}
+
+function rewriteAlignment(element: ScanElement): void {
+  const align = element.getAttribute("data-align");
+  element.removeAttribute("data-align");
+  if (isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align))
+    element.setAttribute("style", `text-align:${align}`);
+}
+
+function rewriteResourceImage(
+  element: ScanElement,
+  resourceSrc: CompileDocumentBodyOptions["resourceSrc"],
+  maxWidthPx: number | undefined,
+): void {
+  const key = element.getAttribute("data-resource") ?? "";
+  const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
+  if (src === undefined) {
+    element.remove();
+    // skip: an unresolved resource key drops the image
+    return;
+  }
+  element.setAttribute("src", src);
+  element.removeAttribute("data-resource");
+  if (maxWidthPx !== undefined)
+    element.setAttribute("style", `max-width:${maxWidthPx}px;height:auto`);
+}
+
+function stripScriptsAndActiveContent(
+  root: ScanElement,
+  options: CompileDocumentBodyOptions,
+): void {
+  for (const element of Array.from(root.querySelectorAll("script"))) element.remove();
+  for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
+    rewriteResourceImage(element, options.resourceSrc, options.resourceImageMaxWidthPx);
+  }
+  for (const element of Array.from(root.querySelectorAll("*"))) stripActiveContent(element);
+}
+
+function applyAlignmentInlineStyles(root: ScanElement): void {
+  for (const element of Array.from(root.querySelectorAll("[data-align]"))) {
+    rewriteAlignment(element);
+  }
+  for (const element of Array.from(root.querySelectorAll("[data-size]"))) {
+    element.removeAttribute("data-size");
+    appendStyle(element, MAIL_SMALL_STYLE);
+  }
+}
+
+function applyTableInlineStyles(root: ScanElement): void {
+  for (const table of Array.from(root.querySelectorAll("table"))) {
+    appendStyle(table, MAIL_TABLE_STYLE);
+  }
+  for (const cell of Array.from(root.querySelectorAll("td, th"))) {
+    appendStyle(cell, MAIL_TABLE_CELL_STYLE);
+  }
+  for (const head of Array.from(root.querySelectorAll("th"))) {
+    appendStyle(head, MAIL_TABLE_HEAD_STYLE);
+  }
+}
+
+function rewriteLinks(
+  root: ScanElement,
+  state: CompileState,
+  options: CompileDocumentBodyOptions,
+): void {
+  for (const element of Array.from(root.querySelectorAll("a[href]"))) {
+    rewriteLink(element, state);
+    if (options.buttonAsInlineStyle === true && element.hasAttribute("data-button")) {
+      element.setAttribute("style", options.buttonInlineStyle ?? MAIL_BUTTON_STYLE);
+    }
+  }
+}
+
+// Turns a sanitized document body into Handlebars source. Rows and links are
+// rewritten in document order; list rows last so their placeholders still see
+// the `tr[data-each]` ancestor.
+export function compileDocumentBodyToHandlebars(
+  html: string,
+  variables: TemplateVariables,
+  options: CompileDocumentBodyOptions = {},
+): string {
+  const state: CompileState = { variables, expressions: [] };
+  const scrubbed = html.replaceAll(EXPRESSION_OPEN, "").replaceAll(EXPRESSION_CLOSE, "");
+  const compiled = withParsedDocument(scrubbed, (root) => {
+    stripScriptsAndActiveContent(root, options);
+    if (options.alignmentAsInlineStyle === true) applyAlignmentInlineStyles(root);
+    if (options.tableAsInlineStyle === true) applyTableInlineStyles(root);
+    for (const element of Array.from(root.querySelectorAll("span[data-variable]"))) {
+      rewriteVariable(element, state);
+    }
+    rewriteLinks(root, state, options);
+    for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+      rewriteRepeatRow(element, state);
+    }
+    return root.innerHTML;
+  });
+  return neutralizeBraces(compiled).replace(
+    MARKER_PATTERN,
+    (_match, index: string) => state.expressions[Number(index)] ?? "",
+  );
+}