@cosmicdrift/kumiko-samples 0.363.0 → 0.364.0

package/packages/bundled-features/src/template-resolver/handlers/layout-source.query.ts

@@ -4,13 +4,23 @@ import * as z from "zod";
 import { FALLBACK_LOCALE } from "../constants.js";
 import { type LayoutRegions, readLayoutRegions } from "../layout-regions.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import {
+  type ActiveInfo,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  toWorkingRow,
+  type WorkingRow,
+} from "../template-draft.js";
+import { type MailLayoutMeta, readMailLayoutMeta } from "../template-meta.js";
 import { localeSchema, templateSlugSchema } from "./shared.js";
+import { parseStoredJson } from "./template-gates.js";
 
 export type LayoutSourceRow = {
   readonly id: string;
   readonly version: number;
   readonly status: string;
   readonly locale: string;
+  readonly active: ActiveInfo | null;
 };
 
 export type LayoutSourceResponse = {
@@ -19,6 +29,8 @@ export type LayoutSourceResponse = {
   readonly regions: LayoutRegions;
   readonly effectiveFormat: "html" | "mjml" | null;
   readonly mjmlSource: string | null;
+  /** Appearance of the effective mail layout; invalid stored meta reads as defaults (empty). */
+  readonly meta: MailLayoutMeta;
   readonly locale: string;
 };
 
@@ -38,33 +50,82 @@ function pickByLocale(
   );
 }
 
-function toSourceRow(row: TemplateResourceRow): LayoutSourceRow {
-  return { id: String(row.id), version: row.version, status: row.status, locale: row.locale };
+function toSourceRow(row: WorkingRow): LayoutSourceRow {
+  return {
+    id: String(row.id),
+    version: row.version,
+    status: row.status,
+    locale: row.locale,
+    active: row.active,
+  };
 }
 
-function layoutFormat(row: TemplateResourceRow): "html" | "mjml" | null {
+function layoutFormat(row: WorkingRow): "html" | "mjml" | null {
   return row.contentFormat === "html" || row.contentFormat === "mjml" ? row.contentFormat : null;
 }
 
 function pickEditedRows(
   rows: readonly TemplateResourceRow[],
-  isSystemAdmin: boolean,
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
   locale: string | undefined,
 ): {
-  readonly tenantRow: TemplateResourceRow | null;
-  readonly systemRow: TemplateResourceRow | null;
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
 } {
-  const tenantRow = isSystemAdmin
+  const tenantRow = user.roles.includes("SystemAdmin")
     ? null
     : pickByLocale(
         rows.filter((row) => row.scope === "tenant"),
         locale,
       );
   const systemRow = pickByLocale(
-    rows.filter((row) => row.scope === "system"),
+    rows.filter((row) => row.scope === "system" && !isHiddenSystemDraft(user, row)),
     locale,
   );
-  return { tenantRow, systemRow };
+  return {
+    tenantRow: tenantRow && toWorkingRow(tenantRow, user.tenantId),
+    // Only a SystemAdmin works on the system draft; a tenant sees the served system version.
+    systemRow: systemRow && toWorkingRow(systemRow, draftViewerTenantId(user, systemRow)),
+  };
+}
+
+function readEffectiveRegions(
+  effective: WorkingRow | null,
+  effectiveFormat: "html" | "mjml" | null,
+): LayoutRegions {
+  return effective !== null && effectiveFormat === "html"
+    ? readLayoutRegions(effective.content ?? "")
+    : EMPTY_REGIONS;
+}
+
+function readMjmlSource(systemRow: WorkingRow | null, isSystemAdmin: boolean): string | null {
+  const exposesMjml = isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml";
+  return exposesMjml ? (systemRow.content ?? "") : null;
+}
+
+function buildLayoutSource(input: {
+  readonly kind: "mail-layout" | "pdf-layout";
+  readonly locale: string | undefined;
+  readonly isSystemAdmin: boolean;
+  readonly tenantRow: WorkingRow | null;
+  readonly systemRow: WorkingRow | null;
+}): LayoutSourceResponse {
+  const { kind, locale, isSystemAdmin, tenantRow, systemRow } = input;
+  const effective = tenantRow ?? systemRow;
+  const effectiveFormat = effective === null ? null : layoutFormat(effective);
+  return {
+    tenant: tenantRow === null ? null : toSourceRow(tenantRow),
+    system:
+      systemRow === null
+        ? null
+        : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
+    regions: readEffectiveRegions(effective, effectiveFormat),
+    effectiveFormat,
+    mjmlSource: readMjmlSource(systemRow, isSystemAdmin),
+    meta:
+      kind === "mail-layout" ? readMailLayoutMeta(parseStoredJson(effective?.meta ?? null)) : {},
+    locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
+  };
 }
 
 export const layoutSourceQuery = defineQueryHandler({
@@ -76,7 +137,7 @@ export const layoutSourceQuery = defineQueryHandler({
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug, the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
+    "Reads the layout the caller edits: the tenant's own version and the system version of one layout slug (each the open draft if there is one, else the stored version, with `active` naming the served version), the header, signature and footer regions of the effective html version, and the locale a save has to use; a SystemAdmin edits the system version and also receives its mjml source. Use it to load the layout editor.",
   handler: async (query, ctx): Promise<LayoutSourceResponse> => {
     const { kind, slug, locale } = query.payload;
     const isSystemAdmin = query.user.roles.includes("SystemAdmin");
@@ -84,25 +145,7 @@ export const layoutSourceQuery = defineQueryHandler({
       kind,
       slug,
     });
-    const { tenantRow, systemRow } = pickEditedRows(rows, isSystemAdmin, locale);
-    const effective = tenantRow ?? systemRow;
-    const effectiveFormat = effective === null ? null : layoutFormat(effective);
-    return {
-      tenant: tenantRow === null ? null : toSourceRow(tenantRow),
-      system:
-        systemRow === null
-          ? null
-          : { ...toSourceRow(systemRow), contentFormat: systemRow.contentFormat },
-      regions:
-        effective !== null && effectiveFormat === "html"
-          ? readLayoutRegions(effective.content ?? "")
-          : EMPTY_REGIONS,
-      effectiveFormat,
-      mjmlSource:
-        isSystemAdmin && systemRow !== null && layoutFormat(systemRow) === "mjml"
-          ? (systemRow.content ?? "")
-          : null,
-      locale: effective?.locale ?? locale ?? FALLBACK_LOCALE,
-    };
+    const { tenantRow, systemRow } = pickEditedRows(rows, query.user, locale);
+    return buildLayoutSource({ kind, locale, isSystemAdmin, tenantRow, systemRow });
   },
 });

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

@@ -3,6 +3,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { TEMPLATE_KINDS, TEMPLATE_STATUSES } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { isHiddenSystemDraft } from "../template-draft.js";
 
 // ctx.db is tenant-scoped even for SystemAdmin: every caller sees its own
 // tenant's rows plus the system defaults, never another tenant's rows.
@@ -43,16 +44,18 @@ export const listQuery = defineQueryHandler({
       limit: 500,
     })) as TemplateResourceRow[];
 
-    return rows.map((row) => ({
-      id: String(row.id),
-      tenantId: row.tenantId,
-      slug: row.slug,
-      kind: row.kind,
-      locale: row.locale,
-      scope: row.scope,
-      status: row.status,
-      contentFormat: row.contentFormat,
-      modifiedAt: row.modifiedAt,
-    }));
+    return rows
+      .filter((row) => !isHiddenSystemDraft(query.user, row))
+      .map((row) => ({
+        id: String(row.id),
+        tenantId: row.tenantId,
+        slug: row.slug,
+        kind: row.kind,
+        locale: row.locale,
+        scope: row.scope,
+        status: row.status,
+        contentFormat: row.contentFormat,
+        modifiedAt: row.modifiedAt,
+      }));
   },
 });

package/packages/bundled-features/src/template-resolver/handlers/override-diff.ts

@@ -0,0 +1,49 @@
+import type { TemplateResourceRow } from "../table.js";
+import { diffTemplateBlocks, splitTemplateBlocks } from "../template-diff.js";
+import { servedVersionOf } from "../template-draft.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] }));
+}
+
+// Shared by the tenant's own diff and the SystemAdmin's per-tenant diff in the overrides drawer.
+export function buildOverrideDiff(tenantRow: TemplateResourceRow, systemRow: TemplateResourceRow) {
+  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: servedVersionOf(tenantRow),
+      contentFormat: tenantRow.contentFormat,
+    },
+    system: {
+      templateId: String(systemRow.id),
+      templateVersion: servedVersionOf(systemRow),
+      contentFormat: systemRow.contentFormat,
+    },
+    identical: meta.length === 0 && blocks.every((block) => block.change === "same"),
+    blocks,
+    meta,
+  };
+}

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

@@ -3,7 +3,15 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { DEFAULT_MAIL_LAYOUT_SLUG, FALLBACK_LOCALE, type TemplateStatus } from "../constants.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
-import { collectTemplateUsage } from "../template-usage.js";
+import {
+  activeSinceOf,
+  activeVersionOf,
+  draftViewerTenantId,
+  isHiddenSystemDraft,
+  parseTemplateDraft,
+  servedVersionOf,
+} from "../template-draft.js";
+import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.js";
 import { storedRecord } from "./template-gates.js";
 
 const OVERVIEW_KINDS = ["mail", "document-pdf", "mail-layout", "pdf-layout"] as const;
@@ -31,6 +39,8 @@ export type OverviewRow = {
   readonly locales: readonly string[];
   readonly status: TemplateStatus;
   readonly version: number;
+  readonly draftVersion: number | null;
+  readonly activeSince: string | null;
   readonly systemVersion: number | null;
   readonly layoutSlug: string | null;
   readonly modifiedAt: string;
@@ -89,6 +99,27 @@ function effectiveRowsOf(rows: readonly TemplateResourceRow[]): EffectiveRows |
   return tenantRows.length > 0 ? { origin: "tenant", rows: tenantRows } : null;
 }
 
+export function effectiveMailLayoutSlugs(
+  rows: readonly TemplateResourceRow[],
+): EffectiveMailLayoutSlugs {
+  const byLocale = new Map<string, TemplateResourceRow[]>();
+  for (const row of rows) {
+    if (row.kind !== "mail") continue;
+    const key = `${row.slug}\u0000${row.locale}`;
+    byLocale.set(key, [...(byLocale.get(key) ?? []), row]);
+  }
+  const bySlug = new Map<string, Map<string, string>>();
+  for (const group of byLocale.values()) {
+    const effective = effectiveRowsOf(group)?.rows[0];
+    // All-archived: the renderer falls back to the code-registered template.
+    if (effective === undefined || effective.status === "archived") continue;
+    const locales = bySlug.get(effective.slug) ?? new Map<string, string>();
+    locales.set(effective.locale, layoutSlugOf(effective));
+    bySlug.set(effective.slug, locales);
+  }
+  return bySlug;
+}
+
 function modifiedAtOf(row: TemplateResourceRow): string {
   return (row.modifiedAt ?? row.insertedAt).toString();
 }
@@ -126,7 +157,37 @@ function groupBySlugAndKind(
   return groups;
 }
 
-function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>): {
+// Another tenant's draft, including a system draft seen by a tenant, is never announced.
+function draftVersionFor(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  row: TemplateResourceRow,
+): number | null {
+  const isOwnRow = row.tenantId === draftViewerTenantId(user, row);
+  return isOwnRow && parseTemplateDraft(row.draft) !== null ? row.version : null;
+}
+
+// Version columns of one overview row: the served version, a waiting draft and the system version it overrides.
+function versionFieldsOf(
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+  preferred: TemplateResourceRow,
+  groupRows: readonly TemplateResourceRow[],
+): Pick<OverviewDraft, "version" | "draftVersion" | "activeSince" | "systemVersion"> {
+  const isActive = preferred.status === "active";
+  const systemSameLocale = groupRows.find(
+    (row) => row.scope === "system" && row.locale === preferred.locale,
+  );
+  return {
+    version: servedVersionOf(preferred),
+    draftVersion: draftVersionFor(user, preferred),
+    activeSince: isActive ? activeSinceOf(preferred).toString() : null,
+    systemVersion: systemSameLocale === undefined ? null : activeVersionOf(systemSameLocale),
+  };
+}
+
+function buildDrafts(
+  groups: ReadonlyMap<string, readonly TemplateResourceRow[]>,
+  user: { readonly tenantId: string; readonly roles: readonly string[] },
+): {
   readonly drafts: OverviewDraft[];
   readonly layoutSlugByDocument: Map<string, string>;
 } {
@@ -137,9 +198,6 @@ function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>
     const preferred = effective === null ? undefined : preferredRow(effective.rows);
     if (effective === null || preferred === undefined) continue;
     if (!isOverviewKind(preferred.kind) || !isTemplateStatus(preferred.status)) continue;
-    const systemSameLocale = groupRows.find(
-      (row) => row.scope === "system" && row.locale === preferred.locale,
-    );
     const isDocument = preferred.kind === "mail" || preferred.kind === "document-pdf";
     const layoutSlug = isDocument ? layoutSlugOf(preferred) : null;
     if (layoutSlug !== null && preferred.kind === "document-pdf") {
@@ -154,8 +212,7 @@ function buildDrafts(groups: ReadonlyMap<string, readonly TemplateResourceRow[]>
       origin: effective.origin,
       locales: [...new Set(effective.rows.map((row) => row.locale))].sort(),
       status: preferred.status,
-      version: preferred.version,
-      systemVersion: systemSameLocale?.version ?? null,
+      ...versionFieldsOf(user, preferred, groupRows),
       layoutSlug,
       modifiedAt: modifiedAtOf(preferred),
     });
@@ -167,15 +224,18 @@ function withUsage(
   draft: OverviewDraft,
   layoutSlugByDocument: ReadonlyMap<string, string>,
   registry: Parameters<typeof collectTemplateUsage>[0],
+  effectiveLayouts: EffectiveMailLayoutSlugs,
 ): OverviewRow {
   let usedBy: OverviewUsage[] = [];
   if (draft.kind === "mail" || draft.kind === "mail-layout") {
-    usedBy = collectTemplateUsage(registry, draft.slug, draft.kind).map((entry) => ({
-      qualifiedName: entry.qualifiedName,
-      feature: entry.feature,
-      notification: entry.notification,
-      trigger: entry.trigger,
-    }));
+    usedBy = collectTemplateUsage(registry, draft.slug, draft.kind, effectiveLayouts).map(
+      (entry) => ({
+        qualifiedName: entry.qualifiedName,
+        feature: entry.feature,
+        notification: entry.notification,
+        trigger: entry.trigger,
+      }),
+    );
   } else if (draft.kind === "pdf-layout") {
     usedBy = [...layoutSlugByDocument]
       .filter(([, layoutSlug]) => layoutSlug === draft.slug)
@@ -192,9 +252,11 @@ function filterRows(
   rows: readonly OverviewRow[],
   search: string | undefined,
   filters: readonly OverviewFilter[],
+  layoutSlug: string | undefined,
 ): OverviewRow[] {
   const needle = search?.trim().toLowerCase() ?? "";
   return rows.filter((row) => {
+    if (layoutSlug !== undefined && row.layoutSlug !== layoutSlug) return false;
     if (needle !== "" && !`${row.title} ${row.slug}`.toLowerCase().includes(needle)) return false;
     return filters.every((filter) => filter.value.includes(String(row[filter.field])));
   });
@@ -211,6 +273,7 @@ export const overviewQuery = defineQueryHandler({
   schema: z.object({
     search: z.string().optional(),
     filters: z.array(filterSchema).optional(),
+    layoutSlug: z.string().optional(),
     sort: z.string().optional(),
     sortDirection: z.enum(["asc", "desc"]).optional(),
     limit: z.number().int().min(1).max(200).default(50),
@@ -219,7 +282,7 @@ export const overviewQuery = defineQueryHandler({
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   description:
-    "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant: where the effective version comes from (own override or system), its locales, status and version, the system version it overrides, the layout it uses and which notifications or templates use it; use it to browse and filter all templates at a glance.",
+    "Lists mail, PDF and layout templates as one row per slug and kind for the caller's tenant (optionally only the mails and PDFs using one layout slug): where the effective version comes from (own override or system), its locales, status and version (the served one; `draftVersion` is set when an unpublished draft waits beside it, `activeSince` says since when the served version applies), the system version it overrides, the layout it uses and which notifications or templates use it; use it to browse and filter all templates at a glance.",
   handler: async (query, ctx) => {
     const payload = query.payload;
     const rows = await selectMany<TemplateResourceRow>(
@@ -229,11 +292,21 @@ export const overviewQuery = defineQueryHandler({
       { limit: OVERVIEW_ROW_LIMIT },
     );
 
-    const { drafts, layoutSlugByDocument } = buildDrafts(groupBySlugAndKind(rows));
+    const visibleRows = rows.filter((row) => !isHiddenSystemDraft(query.user, row));
+    const { drafts, layoutSlugByDocument } = buildDrafts(
+      groupBySlugAndKind(visibleRows),
+      query.user,
+    );
+    const effectiveLayouts = effectiveMailLayoutSlugs(visibleRows);
     const overviewRows = drafts.map((draft) =>
-      withUsage(draft, layoutSlugByDocument, ctx.registry),
+      withUsage(draft, layoutSlugByDocument, ctx.registry, effectiveLayouts),
+    );
+    const filtered = filterRows(
+      overviewRows,
+      payload.search,
+      payload.filters ?? [],
+      payload.layoutSlug,
     );
-    const filtered = filterRows(overviewRows, payload.search, payload.filters ?? []);
 
     const sortField: SortField =
       payload.sort !== undefined && isSortField(payload.sort) ? payload.sort : "modifiedAt";

package/packages/bundled-features/src/template-resolver/handlers/resource-upload.write.ts

@@ -91,7 +91,7 @@ export const resourceUploadWrite = defineWriteHandler({
     try {
       source = await readFileRefContent({
         db: ctx.db,
-        filesForTenant: (tid) => fileContextForTenant(ctx, tid),
+        filesForTenant: (tid) => fileContextForTenant(ctx, ctx.user.tenantId, tid),
         fileRefId: sourceFileRefId,
         allowedTenantIds: [event.user.tenantId],
         unclaimedUploadOf: event.user.id,

package/packages/bundled-features/src/template-resolver/handlers/send-test.write.ts

@@ -28,6 +28,11 @@ function testMailFailed(code: "channel_error" | "not_sent") {
   );
 }
 
+function errorCodeOf(error: unknown): string | undefined {
+  const code = error instanceof Error ? Reflect.get(error, "code") : undefined;
+  return typeof code === "string" ? code : undefined;
+}
+
 // The only recipient is the caller's own address, resolved server-side, so the handler can never mail a third party.
 export const sendTestWrite = defineWriteHandler({
   name: "send-test",
@@ -37,18 +42,24 @@ export const sendTestWrite = defineWriteHandler({
     content: z.string().max(200_000).optional(),
     meta: z.unknown().optional(),
     variableSchema: z.record(z.string(), z.unknown()).default({}),
+    includeAttachments: z.boolean().default(true),
+    prefixSubject: z.boolean().default(true),
   }),
   access: { roles: ["TenantAdmin", "SystemAdmin"] },
   rateLimit: { per: "user+handler", ...TEST_MAIL_RATE_LIMIT },
   description:
-    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST], carrying the inline images and the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
+    "Sends the rendered preview of a mail template draft, or of the stored template when no content is given, to the calling user's own address with the subject prefixed by [TEST] unless prefixSubject is false, carrying the inline images and, unless includeAttachments is false, the files attached to the template; there is no recipient input, the sample values come from the declared variable examples, and a draft that fails the write rules is rejected without sending.",
   handler: async (event, ctx) => {
+    const { includeAttachments, prefixSubject, ...previewPayload } = event.payload;
     const outcome = await renderTemplatePreview(ctx, event.user, {
-      ...event.payload,
+      ...previewPayload,
       kind: "mail",
     });
     if (!outcome.ok) return writeFailure(outcome.error);
-    const { preview, mailAttachments } = outcome;
+    const { preview, sender } = outcome;
+    const mailAttachments = includeAttachments
+      ? outcome.mailAttachments
+      : outcome.mailAttachments.filter((ref) => ref.kind === "inline");
 
     const channel = emailChannelOf(ctx.registry);
     if (channel === undefined) {
@@ -69,7 +80,7 @@ export const sendTestWrite = defineWriteHandler({
         ctx.registry,
         event.user.tenantId,
         ctx.config,
-        (tenantId) => fileContextForTenant(ctx, tenantId),
+        (tenantId) => fileContextForTenant(ctx, ctx.user.tenantId, tenantId),
       ),
     };
     const address = (await channel.resolve?.(event.user.id, channelContext)) ?? null;
@@ -81,8 +92,8 @@ export const sendTestWrite = defineWriteHandler({
       );
     }
 
-    const subject = `${TEST_MAIL_SUBJECT_PREFIX}${preview.subject ?? ""}`;
-    let sent: boolean;
+    const subject = `${prefixSubject ? TEST_MAIL_SUBJECT_PREFIX : ""}${preview.subject ?? ""}`;
+    let sentStatus: string;
     try {
       const result = await channel.send(
         address,
@@ -94,13 +105,31 @@ export const sendTestWrite = defineWriteHandler({
           locale: event.payload.locale,
         },
         channelContext,
-        { subject, html: preview.html, text: preview.text ?? "", attachments: mailAttachments },
+        {
+          subject,
+          html: preview.html,
+          text: preview.text ?? "",
+          ...sender,
+          attachments: mailAttachments,
+        },
       );
-      sent = result.status === "sent";
-    } catch {
+      sentStatus = result.status;
+    } catch (error) {
+      // Class and code only: the message can carry the address or a provider response body.
+      ctx.log?.warn("template test mail: channel threw", {
+        tenantId: event.user.tenantId,
+        errorClass: error instanceof Error ? error.name : typeof error,
+        errorCode: errorCodeOf(error),
+      });
       return testMailFailed("channel_error");
     }
-    if (!sent) return testMailFailed("not_sent");
+    if (sentStatus !== "sent") {
+      ctx.log?.warn("template test mail: channel did not send", {
+        tenantId: event.user.tenantId,
+        status: sentStatus,
+      });
+      return testMailFailed("not_sent");
+    }
     return { isSuccess: true as const, data: { subject, checks: preview.checks } };
   },
 });

package/packages/bundled-features/src/template-resolver/handlers/template-gates.ts

@@ -24,12 +24,24 @@ const PLACEHOLDER_VALIDATED_KINDS: ReadonlySet<TemplateKind> = new Set([
   "pdf-layout",
 ]);
 
+// The parser's wording is English and meant for logs; the UI gets a key per setting instead.
+const META_FIELDS_WITH_MESSAGES: ReadonlySet<string> = new Set([
+  "subject",
+  "previewText",
+  "senderName",
+  "replyTo",
+  "layoutSlug",
+  "fileName",
+]);
+
 function metaIssueToFieldIssue(issue: TemplateMetaIssue): FieldIssue {
+  const hasMessage = META_FIELDS_WITH_MESSAGES.has(issue.field);
   return {
     path: issue.path,
     code: "invalid_meta",
-    i18nKey: "templateResolver.errors.template.invalidMeta",
-    params: { detail: issue.message },
+    i18nKey: hasMessage
+      ? `templateResolver.errors.template.meta.${issue.field}.${issue.missing ? "required" : "invalid"}`
+      : "templateResolver.errors.template.invalidMeta",
   };
 }
 

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

@@ -17,6 +17,7 @@ import { requireForTenant } from "../../shared/index.js";
 import type { ContentFormat, TemplateKind } from "../constants.js";
 import type { TemplateWriteScope } from "../layout-regions.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
+import { activationChanges, serializeTemplateDraft } from "../template-draft.js";
 import type { TemplateValidation } from "../template-validation.js";
 import { executor } from "./shared.js";
 import {
@@ -96,6 +97,42 @@ export function gateTemplateWrite(
   return { ok: true, evaluated };
 }
 
+type TemplateRowFields = {
+  readonly content: string | null;
+  readonly contentFormat: ContentFormat;
+  readonly variableSchema: string;
+  readonly meta: string | null;
+  readonly title: string | null;
+  readonly folder: string | null;
+  readonly parentTemplateId: string | null;
+};
+
+// A draft over an active row is stored beside it; every other write replaces the main fields.
+function updateChanges(
+  existing: TemplateResourceRow,
+  status: "draft" | "active",
+  fields: TemplateRowFields,
+): Record<string, unknown> {
+  if (status === "active") return { ...fields, ...activationChanges(existing) };
+  if (existing.status !== "active") return { ...fields, status, draft: null };
+  const draft = serializeTemplateDraft({
+    content: fields.content,
+    contentFormat: fields.contentFormat,
+    variableSchema: fields.variableSchema,
+    meta: fields.meta,
+    title: fields.title,
+    folder: fields.folder,
+    parentTemplateId: fields.parentTemplateId,
+  });
+  return existing.activeVersion === null
+    ? {
+        draft,
+        activeVersion: existing.version,
+        activeSince: existing.modifiedAt ?? existing.insertedAt,
+      }
+    : { draft };
+}
+
 // Shared by every template write: validate through the one pipeline, then
 // create or update the (tenant, slug, kind, locale) row via the event-store
 // executor. linkedResources is never part of an update; resources are attached
@@ -146,7 +183,11 @@ export async function writeTemplateRow(
 
   if (existing) {
     const result = await executor.update(
-      { id: existing.id, version: existing.version, changes: fields },
+      {
+        id: existing.id,
+        version: existing.version,
+        changes: updateChanges(existing, status, fields),
+      },
       user,
       db,
       { streamTenantId },
@@ -163,9 +204,18 @@ export async function writeTemplateRow(
     };
   }
 
-  const result = await executor.create({ ...fields, linkedResources: "{}", tenantId }, user, db, {
-    streamTenantId,
-  });
+  const result = await executor.create(
+    {
+      ...fields,
+      linkedResources: "{}",
+      tenantId,
+      draft: null,
+      ...(status === "active" ? activationChanges(null) : {}),
+    },
+    user,
+    db,
+    { streamTenantId },
+  );
   if (!result.isSuccess) return result;
   // @cast-boundary db-row — executor.create returnt Record-row aus
   // INSERT RETURNING; shape { id } ist garantiert weil PK in der