@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

package/packages/bundled-features/src/template-resolver/README.md

@@ -1,6 +1,6 @@
 # template-resolver
 
-Strukturierter Content-Storage mit Tenant-Override-Hierarchie, Locale-Fallback und Resource-Linking via `file-foundation`. Eine Entity (`template-resource`) für alle Content-Arten — Render-Templates (`mail-html`, `document-pdf`, `notification`, `image-snapshot`), Markdown-Textblöcke (`text-block`, ex `text-content`-Feature) und AI-Prompts (`ai-prompt`).
+Strukturierter Content-Storage mit Tenant-Override-Hierarchie, Locale-Fallback und Resource-Linking via `file-foundation`. Eine Entity (`template-resource`) für alle Content-Arten — Render-Templates (`mail`, `document-pdf`, `notification`, `image-snapshot`), Rahmen (`mail-layout`, `pdf-layout`), Markdown-Textblöcke (`text-block`, ex `text-content`-Feature) und AI-Prompts (`ai-prompt`).
 
 **Plan-Doc:** [`kumiko-platform/docs/plans/features/template-resolver.md`](../../../../../../kumiko-platform/docs/plans/features/template-resolver.md)
 
@@ -38,14 +38,51 @@ async function someHandler(ctx) {
   const template = await templateResolver.resolveTemplate({
     tenantId: ctx.user.tenantId,
     slug: "nka-versand",
-    kind: "mail-html",
+    kind: "mail",
     locale: "de",
   });
-  // template.content + template.variableSchema + template.linkedResources verwenden
+  // template.content + template.meta + template.variableSchema + template.linkedResources verwenden
   // ...
 }
 ```
 
+## Kinds, Format und Meta
+
+| kind | contentFormat | meta |
+|---|---|---|
+| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `sender` |
+| `mail-layout` | `mjml` | leer (`{}`) oder fehlend |
+| `pdf-layout` | `html` | leer (`{}`) oder fehlend |
+| `document-pdf` | `html` | fehlt |
+| übrige | frei | fehlt |
+
+`meta` liegt als JSON in der Spalte `meta` und wird beim Schreiben pro kind gegen
+`template-meta.ts` geprüft (Fehler als Field-Issues auf `meta.*`). Subject und
+Preview-Text erlauben nur einfache Platzhalter (`{{name}}`, `{{name.feld}}`), keine
+Zeilenumbrüche.
+
+Slugs sind kebab-Segmente, mit `:` verbunden (`templateSlugSchema`); Notification-Templates
+liegen unter ihrem qualifizierten Namen `feature:notify:name`.
+
+## Platzhalter-Validierung (kind `mail`)
+
+Die Variablen kommen aus der Notification mit gleichem qualifiziertem Namen
+(`r.notification({ variables })`), sonst aus `variableSchema` der Zeile. Systemplatzhalter
+(`tenantName`, `signature`, `imprint`, `unsubscribeUrl`) und der Resource-Key `logo` sind immer erlaubt.
+
+- `upsertSystem` und `upsertTenant` lehnen unbekannte Platzhalter ab (Field-Issue auf `content`).
+- `upsertSystem` und `upsertTenant` mit `status: "active"` verlangen zusätzlich, dass jede `required`-Variable benutzt wird. Ein Tenant-Draft darf unvollständig sein und liefert `validation` zurück.
+- `publish` prüft die gespeicherte Zeile erneut.
+- `seedSystemTemplate` wirft bei beiden Problemen.
+
+## Notification-Templates seeden
+
+`r.notification({ variables, template, meta })` bringt Text und Meta mit dem Code mit.
+`seedNotificationTemplates(db, registry)` (aus `.../template-resolver/seeding`) schreibt sie
+pro Locale als System-Template; `applyBootSeeds` ruft das beim Boot auf. Der Code ist
+maßgeblich: geänderte Texte aktualisieren die Zeile, unveränderte erzeugen kein Event.
+Tenant-Overrides bleiben unberührt.
+
 ## Resolver-Reihenfolge (4-Stufen-Fallback)
 
 1. `tenantId` + requested locale
@@ -63,10 +100,10 @@ import { seedSystemTemplate } from "@cosmicdrift/kumiko-bundled-features/templat
 // runProdApp seeds — idempotent, default skip if slug exists
 await seedSystemTemplate(db, {
   slug: "welcome-email",
-  kind: "notification",
+  kind: "mail",
   locale: "de",
-  content: JSON.stringify({ header: "Willkommen", sections: [{ text: "…" }] }),
-  contentFormat: "plain",
+  content: '<p>Willkommen, <span data-variable="name"></span></p>',
+  contentFormat: "html",
 });
 ```
 
@@ -80,8 +117,16 @@ await seedSystemTemplate(db, {
 | `TemplateResolverHandlers.upsertTenant` | `template-resolver:write:upsert-tenant` | TenantAdmin (eigener Tenant) + SystemAdmin via `tenantIdOverride` | Erstellt/Updated Tenant-Overrides (scope='tenant'), default-status='draft' |
 | `TemplateResolverHandlers.publish` | `template-resolver:write:publish` | TenantAdmin (eigener Tenant) | Setzt status='active' |
 | `TemplateResolverHandlers.archive` | `template-resolver:write:archive` | TenantAdmin (eigener Tenant) | Setzt status='archived' (Resolver ignoriert es danach) |
+| `TemplateResolverHandlers.publishSystem` | `template-resolver:write:publish-system` | SystemAdmin | Setzt status='active' auf einem System-Default (gleiche Mail-Prüfung wie `publish`) |
+| `TemplateResolverHandlers.archiveSystem` | `template-resolver:write:archive-system` | SystemAdmin | Setzt status='archived' auf einem System-Default; Tenants ohne Override fallen durch |
+| `TemplateResolverHandlers.resetToSystem` | `template-resolver:write:reset-to-system` | TenantAdmin (eigener Tenant) | Archiviert den eigenen Override, sodass wieder die aktive System-Vorlage greift; ohne aktive System-Vorlage `no_system_template` |
 | `TemplateResolverQueries.findById` | `template-resolver:query:find-by-id` | TenantAdmin + User (eigener Tenant + system-templates sichtbar) | Raw-Lookup für Edit-UI |
 | `TemplateResolverQueries.list` | `template-resolver:query:list` | gleich | Filter nach kind/locale/status, optional includeSystem |
+| `TemplateResolverQueries.usage` | `template-resolver:query:usage` | TenantAdmin | Welche Notifications eine Mail-Vorlage bzw. ein Mail-Layout verwenden (aus der Registry) |
+| `TemplateResolverQueries.overview` | `template-resolver:query:overview` | TenantAdmin + SystemAdmin | Eine Zeile je Slug und Art (Mail, PDF, Layouts) mit Herkunft, Sprachen, Status, Version, Layout und Verwendung; durchsuch-, filter-, sortier- und seitenweise lesbar |
+| `TemplateResolverQueries.layoutSource` | `template-resolver:query:layout-source` | TenantAdmin + SystemAdmin | Eigene und System-Fassung eines Layouts, Kopf/Signatur/Fuß-Bereiche der wirksamen html-Fassung, Speicher-Locale; MJML-Quelle nur für SystemAdmin |
+| `TemplateResolverQueries.tenantOverrides` | `template-resolver:query:tenant-overrides` | SystemAdmin | Anzahl aktiver/Entwurf-Overrides einer System-Vorlage und aktive Tenants gesamt, nur Zahlen |
+| `TemplateResolverQueries.diffToSystem` | `template-resolver:query:diff-to-system` | TenantAdmin (eigener Tenant) | Block- und Meta-Vergleich eines Tenant-Overrides mit der System-Vorlage |
 
 **SystemAdmin-Cross-Tenant für publish/archive/findById:** deferred (Task 8) — `upsertTenant` hat `tenantIdOverride` bereits; publish/archive brauchen das erst wenn ein Sysadmin-Panel fremde Tenant-Templates kuratiert. `ctx.db` ist tenant-scoped, fremde IDs → NotFound ohne Override.
 
@@ -162,7 +207,7 @@ createTemplateResolverFeature({
   collections: [
     {
       id: "reply-snippets",
-      kind: "mail-html",
+      kind: "mail",
       access: { roles: ["Agent", "TenantAdmin"] },
       nav: { label: "mail:nav.snippets", parent: "mail:nav:root" },
     },
@@ -245,6 +290,17 @@ nebeneinander und führt sie in der UI zusammen.
 Unter `tenantIdOverride` (SystemAdmin) bleibt die Zeile die **eigene** des
 Aufrufers im fremden Tenant — ein Admin editiert nie die Signatur eines anderen.
 
+## Validierung, Layouts, Bundles
+
+- `validate` (Query) trocken-läuft die Schreib-Pipeline: `canSave`, `canPublish`, verwendete/unbekannte/fehlende Platzhalter, verfügbare Variablen. `mail`, `document-pdf`, `pdf-layout` und `mail-layout` laufen durch dasselbe Platzhalter-Gate; `page`/`pages` gibt es nur in `document-pdf` und `pdf-layout`.
+- `preview` (Query, TenantAdmin/SystemAdmin) rendert einen Entwurf oder, ohne `content`, die gespeicherte Vorlage mit Beispielwerten aus dem `example` jeder deklarierten Variable (Listen: zwei Zeilen, ohne `example` feste Ersatzwerte). Der Entwurf läuft durch dieselben Gates wie ein Speichern, eine Mail durch den echten Mail-Renderer. Antwort: Betreff, HTML, `displayHtml` (nur Mail: `cid:`-Bilder als Data-URI für den Editor, 5 MiB Budget), Text, Anhänge (`kind: "inline"` mit `cid` oder `kind: "file"`, jeweils mit Größe) und `checks` (`resources_resolved`, `text_present`, `size_under_cap` mit 10 MiB, `required_placeholders`). `document-pdf` liefert den bereinigten Body und die Layout-Regionen, kein PDF.
+- `send-test` (Write, TenantAdmin/SystemAdmin) schickt die gerenderte Mail nur an die eigene Adresse des Aufrufers, Betreff mit `[TEST] `, höchstens 10 pro Nutzer und Stunde. Es gibt keine Empfänger-Eingabe. Braucht `delivery`, `channel-email` und `renderer-mail-html`.
+- Layouts: Tenant-`mail-layout` und `pdf-layout` sind strukturiertes HTML mit `data-content`-Slot und Regionen (Header, Signatur, Footer). Rohes MJML mit `{{{content}}}` genau einmal darf nur das System schreiben.
+- `export-bundle`, `import-bundle`, `import-bundle-system`: ein Template mit allen Locales und Ressourcen-Dateien (base64) als eigenständiges Bundle; bestehende Ziele nur mit `overwrite`. Systemimport mit Ressourcen braucht einen Caller im System-Tenant.
+- `copy-locale`: Startpunkt für Übersetzungen, kopiert als Tenant-Draft. Mit `scope: "system"` (nur SystemAdmin) wird eine Systemvorlage als System-Draft kopiert; andere Aufrufer bekommen 403.
+- Mail-Anhänge: `resource-upload` mit `purpose: "attachment"` und `fileName` legt eine PDF-, PNG- oder JPEG-Datei (geprüft am Inhalt, Originalbytes, höchstens 10 pro Mail-Vorlage) neben den Inline-Bildern ab. `resource-remove`, `copy-locale` und die Bundles tragen sie mit (Bundle-Eintrag `purpose: "attachment"`). Der Mail-Renderer hängt sie nach den Inline-Bildern an.
+- `r.notification(..., { record: { entity, map } })` mappt eine Entity-Zeile auf die deklarierten Variablen (`mapRecordToVariables`); Boot prüft Entity, Variablen und Feldpfade.
+
 ## Out-of-Scope
 
 - Rendering (Markdown/MJML → HTML/PDF) — siehe `renderer-foundation`

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

@@ -3,13 +3,22 @@
 // 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 { 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 +34,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 +56,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 +100,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 +139,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) => b.version - a.version || 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 +192,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,9 +199,7 @@ 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,
@@ -150,7 +212,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 +223,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,122 @@
 [
+  {
+    "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,214 @@
+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}}}`;
+  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 mail turns data-align into an inline style.
+  readonly alignmentAsInlineStyle?: boolean;
+};
+
+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"],
+): 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");
+}
+
+// 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) => {
+    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);
+    }
+    for (const element of Array.from(root.querySelectorAll("*"))) stripActiveContent(element);
+    if (options.alignmentAsInlineStyle === true) {
+      for (const element of Array.from(root.querySelectorAll("[data-align]"))) {
+        rewriteAlignment(element);
+      }
+    }
+    for (const element of Array.from(root.querySelectorAll("span[data-variable]"))) {
+      rewriteVariable(element, state);
+    }
+    for (const element of Array.from(root.querySelectorAll("a[href]"))) {
+      rewriteLink(element, state);
+    }
+    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)] ?? "",
+  );
+}