@cosmicdrift/kumiko-samples 0.363.0 → 0.364.0

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

@@ -1,4 +1,72 @@
 [
+  {
+    "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",

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

@@ -60,6 +60,7 @@ function resolveReference(
 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}}}`;
 }
 
@@ -123,10 +124,33 @@ function neutralizeBraces(html: string): string {
 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",
@@ -163,6 +187,7 @@ function rewriteAlignment(element: ScanElement): void {
 function rewriteResourceImage(
   element: ScanElement,
   resourceSrc: CompileDocumentBodyOptions["resourceSrc"],
+  maxWidthPx: number | undefined,
 ): void {
   const key = element.getAttribute("data-resource") ?? "";
   const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
@@ -173,6 +198,54 @@ function rewriteResourceImage(
   }
   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
@@ -186,22 +259,13 @@ export function compileDocumentBodyToHandlebars(
   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);
-      }
-    }
+    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);
     }
-    for (const element of Array.from(root.querySelectorAll("a[href]"))) {
-      rewriteLink(element, state);
-    }
+    rewriteLinks(root, state, options);
     for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
       rewriteRepeatRow(element, state);
     }

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

@@ -62,8 +62,18 @@ export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
 export const TEMPLATE_STATUSES = ["draft", "active", "archived"] as const;
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
 
-export const PDF_PAGE_FORMATS = ["A4", "Letter"] as const;
-export type PdfPageFormat = (typeof PDF_PAGE_FORMATS)[number];
+export {
+  PDF_DEFAULT_MARGIN_MM,
+  PDF_FOOTER_MARGIN_MM,
+  PDF_HEADER_MARGIN_MM,
+  PDF_ORIENTATIONS,
+  PDF_PAGE_FORMATS,
+  type PdfOrientation,
+  type PdfPageFormat,
+} from "./pdf-constants.js";
+
+// Colors end up inside MJML attributes, so only a strict hex is ever written there.
+export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
 
 export const DEFAULT_MAIL_LAYOUT_SLUG = "default";
 

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

@@ -9,13 +9,14 @@ import { Link } from "@tiptap/extension-link";
 import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
 import StarterKit from "@tiptap/starter-kit";
 
-const PLACEHOLDER_HREF = /^\{\{[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*\}\}$/;
+const PLACEHOLDER_HREF = /^\{\{(.+)\}\}$/;
 const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 const RESOURCE_KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const ALLOWED_LINK_SCHEMES = ["https://", "http://", "mailto:", "tel:"] as const;
 
 export function isDocumentPlaceholderHref(href: string): boolean {
-  return PLACEHOLDER_HREF.test(href);
+  const name = PLACEHOLDER_HREF.exec(href)?.[1];
+  return name !== undefined && isDocumentReferenceName(name);
 }
 
 const UNSAFE_URL_CHARACTERS = new Set(["<", ">", '"']);
@@ -204,8 +205,6 @@ export const DocumentTableRow = TableRow.extend({
   },
 });
 
-export const DocumentRepeatRow = DocumentTableRow;
-
 export const DocumentTable = Table.extend({
   renderHTML() {
     return ["table", ["tbody", 0]];
@@ -288,6 +287,28 @@ export const DocumentTextAlign = Extension.create({
   },
 });
 
+// Only "small" exists: the sender line above an address block. Serialized as data-size for the
+// same reason as data-align.
+export const DocumentTextSize = Extension.create({
+  name: "documentTextSize",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["paragraph"],
+        attributes: {
+          textSize: {
+            default: null,
+            parseHTML: (element) =>
+              element.getAttribute("data-size") === "small" ? "small" : null,
+            renderHTML: (attributes) =>
+              attributes["textSize"] === "small" ? { "data-size": "small" } : {},
+          },
+        },
+      },
+    ];
+  },
+});
+
 export const documentExtensions: Extensions = [
   StarterKit.configure({
     blockquote: false,
@@ -320,4 +341,5 @@ export const documentExtensions: Extensions = [
   DocumentDivider,
   DocumentPageBreak,
   DocumentTextAlign,
+  DocumentTextSize,
 ];

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

@@ -10,6 +10,7 @@ import { makeCollectionListQuery } from "./handlers/collection-list.query.js";
 import { makeCollectionSetWrite } from "./handlers/collection-set.write.js";
 import { copyLocaleWrite } from "./handlers/copy-locale.write.js";
 import { diffToSystemQuery } from "./handlers/diff-to-system.query.js";
+import { discardDraftSystemWrite, discardDraftWrite } from "./handlers/discard-draft.write.js";
 import { exportBundleQuery } from "./handlers/export-bundle.query.js";
 import { findByIdQuery } from "./handlers/find-by-id.query.js";
 import { importBundleWrite } from "./handlers/import-bundle.write.js";
@@ -66,7 +67,7 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
     r.describe(
       [
         "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).",
-        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`.",
+        "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.",
         "Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.",
         "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).",
         'A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.',
@@ -100,6 +101,8 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       archive: r.writeHandler(archiveWrite),
       publishSystem: r.writeHandler(publishSystemWrite),
       archiveSystem: r.writeHandler(archiveSystemWrite),
+      discardDraft: r.writeHandler(discardDraftWrite),
+      discardDraftSystem: r.writeHandler(discardDraftSystemWrite),
       resetToSystem: r.writeHandler(resetToSystemWrite),
       set: r.writeHandler(setWrite),
       importBundle: r.writeHandler(importBundleWrite),

package/packages/bundled-features/src/template-resolver/handlers/copy-locale.write.ts

@@ -17,7 +17,8 @@ import { CONTENT_FORMATS } from "../constants.js";
 import { parseLinkedResourceEntries } from "../linked-resources.js";
 import { TemplateResolverErrors } from "../qualified-names.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
-import { attachTemplateResources } from "../template-resources.js";
+import { toWorkingRow } from "../template-draft.js";
+import { attachTemplateResources, duplicateLinkedResourceFiles } from "../template-resources.js";
 import { resolveTemplateVariables } from "../template-validation.js";
 import { targetExistsIssue } from "./bundle-import.js";
 import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
@@ -50,7 +51,8 @@ async function findCopySource(
     kind,
     locale,
   });
-  if (own || scope === "system") return own;
+  // An archived tenant row is not an active source: the system default applies instead.
+  if (scope === "system" || (own && own.status !== "archived")) return own;
   return fetchOne<TemplateResourceRow>(readDb, templateResourcesTable, {
     tenantId: SYSTEM_TENANT_ID,
     slug,
@@ -89,7 +91,14 @@ export const copyLocaleWrite = defineWriteHandler({
     if (refused !== null) return refused;
 
     const readDb = readDbFor(ctx, scope);
-    const source = await findCopySource(ctx, { scope, tenantId, slug, kind, locale: fromLocale });
+    const storedSource = await findCopySource(ctx, {
+      scope,
+      tenantId,
+      slug,
+      kind,
+      locale: fromLocale,
+    });
+    const source = storedSource && toWorkingRow(storedSource, tenantId);
     if (!source || !isOneOf(CONTENT_FORMATS, source.contentFormat)) {
       return writeFailure(new NotFoundError("template-resource", `${slug}/${fromLocale}`));
     }
@@ -127,16 +136,25 @@ export const copyLocaleWrite = defineWriteHandler({
       },
     });
     if (!written.isSuccess) return written;
-    // A system source carries no files of its own: its resource keys are known to the tenant row anyway.
-    if (source.tenantId === tenantId) {
-      const attached = await attachTemplateResources(ctx, {
-        user: event.user,
-        tenantId,
-        templateId: written.data.id,
-        resources: parseLinkedResourceEntries(source.linkedResources),
-      });
-      if (!attached.isSuccess) return attached;
-    }
+    const sourceResources = parseLinkedResourceEntries(source.linkedResources);
+    // A system source's files belong to the system tenant: the tenant gets its own copies so
+    // previews, exports and the tenant's override keep working independent of the system row.
+    const resources =
+      source.tenantId === tenantId
+        ? { isSuccess: true as const, data: sourceResources }
+        : await duplicateLinkedResourceFiles(ctx, {
+            user: event.user,
+            tenantId,
+            resources: sourceResources,
+          });
+    if (!resources.isSuccess) return resources;
+    const attached = await attachTemplateResources(ctx, {
+      user: event.user,
+      tenantId,
+      templateId: written.data.id,
+      resources: resources.data,
+    });
+    if (!attached.isSuccess) return attached;
     return written;
   },
 });

package/packages/bundled-features/src/template-resolver/handlers/diff-to-system.query.ts

@@ -3,29 +3,8 @@ import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framew
 import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
-import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
-
-function parseStoredMeta(raw: string | null): Readonly<Record<string, unknown>> {
-  if (raw === null) return {};
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
-      ? Object.fromEntries(Object.entries(parsed))
-      : {};
-  } catch {
-    return {};
-  }
-}
-
-function diffMeta(
-  system: Readonly<Record<string, unknown>>,
-  tenant: Readonly<Record<string, unknown>>,
-) {
-  const keys = [...new Set([...Object.keys(system), ...Object.keys(tenant)])].sort();
-  return keys
-    .filter((key) => JSON.stringify(system[key]) !== JSON.stringify(tenant[key]))
-    .map((key) => ({ key, tenant: tenant[key], system: system[key] }));
-}
+import { isHiddenSystemDraft } from "../template-draft.js";
+import { buildOverrideDiff } from "./override-diff.js";
 
 export const diffToSystemQuery = defineQueryHandler({
   name: "diff-to-system",
@@ -46,27 +25,9 @@ export const diffToSystemQuery = defineQueryHandler({
       kind: tenantRow.kind,
       locale: tenantRow.locale,
     });
-    if (!systemRow) throw new NotFoundError("template-resource", tenantRow.slug);
+    if (!systemRow || isHiddenSystemDraft(query.user, systemRow))
+      throw new NotFoundError("template-resource", tenantRow.slug);
 
-    const blocks = diffTemplateBlocks(
-      splitTemplateBlocks(systemRow.content ?? "", systemRow.contentFormat),
-      splitTemplateBlocks(tenantRow.content ?? "", tenantRow.contentFormat),
-    );
-    const meta = diffMeta(parseStoredMeta(systemRow.meta), parseStoredMeta(tenantRow.meta));
-    return {
-      tenant: {
-        templateId: String(tenantRow.id),
-        templateVersion: tenantRow.version,
-        contentFormat: tenantRow.contentFormat,
-      },
-      system: {
-        templateId: String(systemRow.id),
-        templateVersion: systemRow.version,
-        contentFormat: systemRow.contentFormat,
-      },
-      identical: meta.length === 0 && blocks.every((block) => block.change === "same"),
-      blocks,
-      meta,
-    };
+    return buildOverrideDiff(tenantRow, systemRow);
   },
 });

package/packages/bundled-features/src/template-resolver/handlers/discard-draft.write.ts

@@ -0,0 +1,52 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { TemplateResolverErrors } from "../qualified-names.js";
+import { executor } from "./shared.js";
+import { loadTargetRow, type StatusTarget, writeAccessFor } from "./toggle-status.write.js";
+
+function createDiscardDraftHandler(name: string, target: StatusTarget, description: string) {
+  return defineWriteHandler({
+    name,
+    schema: z.object({ id: z.string().min(1) }),
+    access: writeAccessFor(target),
+    ...(target === "system" ? { agent: { risk: "high" as const } } : {}),
+    description,
+    handler: async (event, ctx) => {
+      const { db, scoped, row } = await loadTargetRow(ctx, target, event.user, event.payload.id);
+      if (!row) return writeFailure(new NotFoundError("template-resource", event.payload.id));
+      if (row.draft === null) {
+        return writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "id",
+                code: TemplateResolverErrors.noDraft,
+                i18nKey: "templateResolver.errors.noDraft",
+              },
+            ],
+          }),
+        );
+      }
+      const result = await executor.update(
+        { id: row.id, version: row.version, changes: { draft: null } },
+        event.user,
+        db,
+        scoped ? { streamTenantId: scoped.streamTenantId } : undefined,
+      );
+      if (!result.isSuccess) return result;
+      return { isSuccess: true as const, data: { id: String(row.id), discarded: true } };
+    },
+  });
+}
+
+export const discardDraftWrite = createDiscardDraftHandler(
+  "discard-draft",
+  "own",
+  "Throws away the open draft of one template resource of the caller's tenant so the editor shows the active version again; the served version is untouched. Refused with no_draft when there is no draft.",
+);
+export const discardDraftSystemWrite = createDiscardDraftHandler(
+  "discard-draft-system",
+  "system",
+  "Throws away the open draft of one system-default template; the served version stays. SystemAdmin only, refused with no_draft when there is no draft.",
+);

package/packages/bundled-features/src/template-resolver/handlers/export-bundle.query.ts

@@ -1,6 +1,7 @@
+import { isDeepStrictEqual } from "node:util";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
-import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { NotFoundError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import {
   isFileAttachmentEntry,
@@ -8,12 +9,63 @@ import {
   type LinkedResourceEntry,
   parseLinkedResourceEntries,
 } from "../linked-resources.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 import type { TemplateBundle } from "../template-bundle.js";
 import { readTemplateResource } from "../template-resources.js";
 import { kindSchema, templateSlugSchema } from "./shared.js";
 import { parseStoredJson, storedRecord } from "./template-gates.js";
 
+// The files live in the system tenant's key space; readTemplateResource only
+// serves the caller's own tenant, so anyone else would end in a misleading NotFound.
+function assertSystemFilesReadable(
+  scope: "tenant" | "system",
+  entries: Iterable<LinkedResourceEntry>,
+  callerTenantId: string,
+): void {
+  // skip: tenant exports read the caller's own files.
+  if (scope === "tenant") return;
+  // skip: the system tenant reads its own key space.
+  if (callerTenantId === SYSTEM_TENANT_ID) return;
+  const hasFileResources = [...entries].some((entry) => !isPdfAttachmentLink(entry));
+  // skip: PDF attachment links carry no file to read.
+  if (!hasFileResources) return;
+  throw new ValidationError({
+    fields: [
+      {
+        path: "scope",
+        code: "system_resources_need_system_tenant",
+        i18nKey: "templateResolver.errors.template.systemResourcesNeedSystemTenant",
+      },
+    ],
+  });
+}
+
+// A bundle carries one contentFormat and one variableSchema for all locales; importing it would
+// relabel the rows that differ from the first.
+function assertLocalesShareFormat(rows: readonly TemplateResourceRow[]): void {
+  const [first, ...rest] = rows;
+  // skip: a bundle without rows has nothing to compare
+  if (first === undefined) return;
+  const firstSchema = storedRecord(first.variableSchema);
+  const differing = rest.find(
+    (row) =>
+      row.contentFormat !== first.contentFormat ||
+      !isDeepStrictEqual(storedRecord(row.variableSchema), firstSchema),
+  );
+  // skip: all locales agree
+  if (differing === undefined) return;
+  throw new ValidationError({
+    fields: [
+      {
+        path: "slug",
+        code: TemplateResolverErrors.bundleLocalesDiffer,
+        i18nKey: "templateResolver.errors.template.bundleLocalesDiffer",
+      },
+    ],
+  });
+}
+
 export const exportBundleQuery = defineQueryHandler({
   name: "export-bundle",
   schema: z.object({
@@ -38,6 +90,7 @@ export const exportBundleQuery = defineQueryHandler({
       .sort((a, b) => a.locale.localeCompare(b.locale));
     const first = rows[0];
     if (!first) throw new NotFoundError("template-resource", slug);
+    assertLocalesShareFormat(rows);
 
     const locales: Record<string, { body: string; meta?: unknown }> = {};
     const entryByKey = new Map<string, LinkedResourceEntry>();
@@ -49,6 +102,8 @@ export const exportBundleQuery = defineQueryHandler({
       }
     }
 
+    assertSystemFilesReadable(scope, entryByKey.values(), query.user.tenantId);
+
     const resources: TemplateBundle["resources"] = {};
     const pdfAttachments: TemplateBundle["pdfAttachments"] = {};
     for (const [key, entry] of entryByKey) {

package/packages/bundled-features/src/template-resolver/handlers/find-by-id.query.ts

@@ -2,6 +2,7 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { draftViewerTenantId, isHiddenSystemDraft, toWorkingRow } from "../template-draft.js";
 
 // Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
 // archived Status. Tenant-Isolation: User sieht nur Templates des
@@ -13,12 +14,13 @@ export const findByIdQuery = defineQueryHandler({
   schema: z.object({ id: z.string().min(1) }),
   access: { roles: ["TenantAdmin", "SystemAdmin", "User"] },
   description:
-    "Reads one template resource by row id with its content, variable schema, scope and draft/archived status, but only when it belongs to the caller's tenant or is a system default; use it to load a template into the admin editor.",
+    "Reads the version of one template resource an editor works on, by row id: the open draft if there is one (status draft), else the stored version, with content, variable schema and scope, but only when it belongs to the caller's tenant or is a served system default (a never-served system draft is visible to a SystemAdmin only); `active` is the version number and since-time the resolver serves, null when none is served. Use it to load a template into the admin editor.",
   handler: async (query, ctx) => {
-    const row = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+    const stored = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
       id: query.payload.id,
     });
-    if (!row) return null;
+    if (!stored || isHiddenSystemDraft(query.user, stored)) return null;
+    const row = toWorkingRow(stored, draftViewerTenantId(query.user, stored));
     const isOwnTenant = row.tenantId === query.user.tenantId;
     const isSystemTemplate = row.scope === "system";
     if (!isOwnTenant && !isSystemTemplate) return null;
@@ -39,6 +41,7 @@ export const findByIdQuery = defineQueryHandler({
       parentTemplateId: row.parentTemplateId,
       status: row.status,
       modifiedAt: row.modifiedAt,
+      active: row.active,
     };
   },
 });