@cosmicdrift/kumiko-samples 0.366.0 → 0.367.0

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -6,6 +6,7 @@ import {
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
 import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as jose from "jose";
@@ -17,6 +18,14 @@ import {
   DeliveryErrors,
   DeliveryHandlers,
 } from "./constants.js";
+import "./unsubscribe-page-strings.js";
+
+// The mail's locale, so the pages behind the link speak the mail's language. Optional: links
+// signed before the claim existed keep verifying and fall back to English.
+const localeClaimSchema = z
+  .string()
+  .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
+  .optional();
 
 // Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
 // wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
@@ -32,6 +41,7 @@ const unsubscribeJwtPayloadSchema = z.object({
   tenantId: z.string().min(1),
   notificationType: z.string().min(1),
   channel: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 // Address-token payload. `sub` and `addressHash` are the same value (the
@@ -45,6 +55,7 @@ const addressUnsubscribeJwtPayloadSchema = z.object({
   notificationType: z.string().min(1),
   channel: z.string().min(1),
   addressHash: z.string().min(1),
+  locale: localeClaimSchema,
 });
 
 export type UnsubscribeTokenPayload = {
@@ -52,6 +63,7 @@ export type UnsubscribeTokenPayload = {
   readonly tenantId: TenantId;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 export type AddressUnsubscribeTokenPayload = {
@@ -59,6 +71,7 @@ export type AddressUnsubscribeTokenPayload = {
   readonly address: string;
   readonly notificationType: string;
   readonly channel: string;
+  readonly locale?: string | undefined;
 };
 
 /**
@@ -87,6 +100,11 @@ function assertUnsubscribeSecret(secret: string, caller: string): void {
   }
 }
 
+// An unusable locale is left out instead of failing the send; the pages then fall back to English.
+function localeClaim(locale: string | undefined): { locale?: string } {
+  return locale !== undefined && localeClaimSchema.safeParse(locale).success ? { locale } : {};
+}
+
 const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
   error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 } as const;
@@ -101,6 +119,7 @@ export async function signUnsubscribeToken(
     tenantId: payload.tenantId,
     notificationType: payload.notificationType,
     channel: payload.channel,
+    ...localeClaim(payload.locale),
   })
     .setProtectedHeader({ alg: "HS256" })
     .setSubject(String(payload.userId))
@@ -136,6 +155,7 @@ export async function signAddressUnsubscribeToken(
       channel: payload.channel,
       addressHash,
       kind: "address",
+      ...localeClaim(payload.locale),
     })
       .setProtectedHeader({ alg: "HS256" })
       .setSubject(addressHash)
@@ -154,6 +174,7 @@ type VerifiedUnsubscribe =
       readonly addressHash: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     }
   | {
       readonly kind: "user";
@@ -161,6 +182,7 @@ type VerifiedUnsubscribe =
       readonly userId: string;
       readonly notificationType: string;
       readonly channel: string;
+      readonly locale: string | undefined;
     };
 
 // RFC 8058 fixed value — both the List-Unsubscribe-Post header and the body a
@@ -183,6 +205,7 @@ async function signResubscribeToken(
     tenantId: verified.tenantId,
     notificationType: verified.notificationType,
     channel: verified.channel,
+    ...localeClaim(verified.locale),
   };
   const jwt =
     verified.kind === "address"
@@ -254,6 +277,7 @@ async function verifyUnsubscribeToken(
         addressHash: parsed.addressHash,
         notificationType: parsed.notificationType,
         channel: parsed.channel,
+        locale: parsed.locale,
       };
     }
 
@@ -274,6 +298,7 @@ async function verifyUnsubscribeToken(
       userId: parsed.sub,
       notificationType: parsed.notificationType,
       channel: parsed.channel,
+      locale: parsed.locale,
     };
   } catch (err) {
     if (err instanceof ExtraRouteRejection) throw err;
@@ -358,40 +383,68 @@ async function dispatchResubscribeWrite(
   return isResubscribeLimitReached(dispatched.error) ? "limit_reached" : "failed";
 }
 
-function confirmationPage(token: string): string {
+function pageLocale(locale: string | undefined): string {
+  return resolveMailLocale(locale ?? "en");
+}
+
+function htmlPage(locale: string, title: string, bodyHtml: string): string {
   return `<!doctype html>
-<html>
+<html lang="${escapeHtmlAttr(locale)}">
 <head>
 <meta charset="utf-8">
 <meta name="robots" content="noindex">
-<title>Unsubscribe</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtmlAttr(title)}</title>
 </head>
 <body>
-<p>Unsubscribe from these emails?</p>
-<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
-<button type="submit">Unsubscribe</button>
-</form>
+${bodyHtml}
 </body>
 </html>`;
 }
 
-function unsubscribedPage(resubscribeToken: string): string {
-  return `<!doctype html>
-<html>
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<title>Unsubscribed</title>
-</head>
-<body>
-<p>You have been unsubscribed.</p>
+function confirmationPage(token: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.confirmTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
+<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
+</form>`,
+  );
+}
+
+function unsubscribedPage(resubscribeToken: string, locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.doneTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>
 <form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
 <input type="hidden" name="token" value="${escapeHtmlAttr(resubscribeToken)}">
-<button type="submit">Undo</button>
-</form>
-</body>
-</html>`;
+<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
+</form>`,
+  );
+}
+
+function resubscribedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  return htmlPage(
+    lang,
+    mailT(lang, "mail.unsubscribe.resubscribedTitle"),
+    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`,
+  );
+}
+
+function failedPage(locale: string | undefined): string {
+  const lang = pageLocale(locale);
+  const message = mailT(lang, "mail.unsubscribe.failed");
+  return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+}
+
+function isFormRequest(contentType: string | undefined): boolean {
+  return contentType?.includes("application/x-www-form-urlencoded") === true;
 }
 
 // One-click clients put the token in the query string; only the
@@ -431,7 +484,7 @@ export function createUnsubscribeRoutes(
   assertUnsubscribeSecret(options.secret, "createUnsubscribeRoutes");
   const encodedSecret = new TextEncoder().encode(options.secret);
 
-  const confirmRoute = signatureRoute<{ token: string }>({
+  const confirmRoute = signatureRoute<{ token: string; locale: string | undefined }>({
     method: "GET",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
@@ -444,11 +497,11 @@ export function createUnsubscribeRoutes(
           "missing unsubscribe token",
         );
       }
-      await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-      return { token };
+      const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
+      return { token, locale: verified.locale };
     },
-    handler: async (c, { token }) =>
-      c.html(confirmationPage(token), 200, CONFIRMATION_PAGE_HEADERS),
+    handler: async (c, { token, locale }) =>
+      c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
   });
 
   const writeRoute = signatureRoute<VerifiedUnsubscribe>({
@@ -463,11 +516,13 @@ export function createUnsubscribeRoutes(
       // (e.g. events-table missing, DB down) behind a misleading 400.
       const succeeded = await dispatchUnsubscribeWrite(verified, deps);
       if (!succeeded) {
-        return c.html("Unsubscribe failed", 500, { "Cache-Control": "no-store" });
+        return c.html(failedPage(verified.locale), 500, { "Cache-Control": "no-store" });
       }
-      return c.html(unsubscribedPage(await signResubscribeToken(verified, encodedSecret)), 200, {
-        "Cache-Control": "no-store",
-      });
+      return c.html(
+        unsubscribedPage(await signResubscribeToken(verified, encodedSecret), verified.locale),
+        200,
+        { "Cache-Control": "no-store" },
+      );
     },
   });
 
@@ -482,6 +537,14 @@ export function createUnsubscribeRoutes(
       verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
     handler: async (c, verified, deps) => {
       const outcome = await dispatchResubscribeWrite(verified, deps);
+      // The undo button on the unsubscribed page posts a form; a browser should land on a page.
+      if (isFormRequest(c.req.header("content-type"))) {
+        return outcome === "success"
+          ? c.html(resubscribedPage(verified.locale), 200, { "Cache-Control": "no-store" })
+          : c.html(failedPage(verified.locale), outcome === "limit_reached" ? 409 : 500, {
+              "Cache-Control": "no-store",
+            });
+      }
       if (outcome === "limit_reached") {
         return c.json({ error: { code: DeliveryErrors.resubscribeLimitReached } }, 409, {
           "Cache-Control": "no-store",

package/packages/bundled-features/src/mail-foundation/feature.ts

@@ -39,9 +39,11 @@ import { requireDefined } from "@cosmicdrift/kumiko-bundled-features/foundation-
 import {
   access,
   type ConfigAccessor,
+  createSystemUser,
   createTenantConfig,
   defineFeature,
   type Registry,
+  type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
 
 const FEATURE_NAME = "mail-foundation";
@@ -121,7 +123,7 @@ declare module "@cosmicdrift/kumiko-framework/engine" {
 
 export const mailFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending \u2014 use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.",
+    "Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending \u2014 use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.",
   );
   r.uiHints({
     displayLabel: "Mail Transport Foundation",
@@ -187,6 +189,28 @@ export async function createTransportForTenant(
   tenantId: string,
   handlerName = "mail-foundation:transport-factory",
 ): Promise<EmailTransport> {
+  const transport = await createTransportForTenantIfConfigured(ctx, tenantId, handlerName);
+  if (transport === null) {
+    const usages = ctx.registry?.getExtensionUsages(MAIL_TRANSPORT_EXTENSION) ?? [];
+    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+    throw new Error(
+      `${FEATURE_NAME}: no provider selected — set the 'provider' config-key to one of: ${known}. ` +
+        `Mount a mail-transport-* feature first if no plugins are registered.`,
+    );
+  }
+  return transport;
+}
+
+/**
+ * Like createTransportForTenant, but an empty `provider` key means "this tenant has no
+ * mail provider" and yields null. Every other problem (unknown provider, plugin build
+ * failure) still throws, so a configured tenant never silently falls back.
+ */
+export async function createTransportForTenantIfConfigured(
+  ctx: MailTransportContext,
+  tenantId: string,
+  handlerName = "mail-foundation:transport-factory",
+): Promise<EmailTransport | null> {
   const ctxConfig = ctx.config;
   if (!ctxConfig) {
     throw new Error(
@@ -204,14 +228,7 @@ export async function createTransportForTenant(
     FEATURE_NAME,
     "provider",
   ) as string; // @cast-boundary engine-payload
-  if (provider.length === 0) {
-    const usages = ctx.registry.getExtensionUsages(MAIL_TRANSPORT_EXTENSION);
-    const known = usages.map((u) => u.entityName).join(", ") || "<none>";
-    throw new Error(
-      `${FEATURE_NAME}: no provider selected — set the 'provider' config-key to one of: ${known}. ` +
-        `Mount a mail-transport-* feature first if no plugins are registered.`,
-    );
-  }
+  if (provider.length === 0) return null;
 
   const usages = ctx.registry.getExtensionUsages(MAIL_TRANSPORT_EXTENSION);
   const usage = usages.find((u) => u.entityName === provider);
@@ -231,3 +248,27 @@ export async function createTransportForTenant(
   }
   return withPiiCiphertextGuard(await usage.options.build(ctx, tenantId));
 }
+
+export type TenantMailTransportScope = {
+  readonly tenantId: TenantId;
+  readonly config?: ConfigAccessor | undefined;
+  readonly registry: Registry;
+  readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext | undefined;
+};
+
+/** The `tenantTransport` resolver for `createChannelEmailFeature`: the tenant's configured
+ *  provider, or null so the channel falls back to its app transport. */
+export function tenantMailTransport(
+  scope: TenantMailTransportScope,
+): Promise<EmailTransport | null> {
+  return createTransportForTenantIfConfigured(
+    {
+      config: scope.config,
+      registry: scope.registry,
+      secrets: scope.secrets,
+      _userId: createSystemUser(scope.tenantId).id,
+    },
+    scope.tenantId,
+    "channel-email",
+  );
+}

package/packages/bundled-features/src/mail-foundation/index.ts

@@ -9,9 +9,12 @@
 
 export {
   createTransportForTenant,
+  createTransportForTenantIfConfigured,
   isMailTransportPlugin,
   MAIL_TRANSPORT_EXTENSION,
   type MailTransportContext,
   type MailTransportPlugin,
   mailFoundationFeature,
+  type TenantMailTransportScope,
+  tenantMailTransport,
 } from "./feature.js";

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

@@ -1,4 +1,29 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Notifications can keep their mail template system-only",
+    "detail": "r.notification(name, { systemOnly: true }) marks the stored mail template as a platform text. Tenant admins no longer see it in the template overview, list or detail, and creating a tenant version (upsert-tenant, copy-locale, import-bundle, also a SystemAdmin writing for a tenant) is refused with access_denied and templateResolver.errors.systemOnlyTemplate. SystemAdmins edit the system template as before, and the mail renderer always uses it, even if a tenant row exists from before."
+  },
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "Rich text placeholders no longer nest paragraphs",
+    "detail": "A richText placeholder alone in a paragraph compiles into a div that keeps the paragraph attributes, and one inside other text renders inline with line breaks instead of its own paragraphs. Mails and PDFs no longer contain <p><p>. richText and stepIs are now reserved template variable names, like the other renderer helpers.",
+    "migration": "A notification that declares a template variable called richText, stepIs or percent fails at boot; rename the variable."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Template bundles with a logo can be seeded",
+    "detail": "seedSystemTemplateBundle(db, bundle, { dispatcher }) now seeds bundles that carry resources such as a logo by running the import-bundle-system write on the given seed dispatcher. With ifExists \"skip\" (default) nothing is written when every locale row already exists; if only some exist, the whole bundle is imported again. Without a dispatcher such a bundle still fails with a message that names the missing option."
+  },
+  {
+    "version": "0.367.0",
+    "type": "improvement",
+    "title": "Template conditions with data-if and a percent variable type",
+    "detail": "A paragraph, heading or table row with data-if=\"name\" renders only when the variable has a value (0 counts as a value); inside a repeat row the name refers to the row field, on the repeat row itself to the root variable. The sanitizer keeps the attribute, and template validation reports a condition on an undeclared variable. New variable type percent (templateVariable.percent()) takes percentage points and renders locale-aware, 12 as \"12 %\" in German and \"12%\" in English; the preview uses its example value. The document designer has no toolbar control for conditions yet; the attribute survives editing."
+  },
   {
     "version": "0.365.0",
     "type": "breaking",

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

@@ -3,8 +3,9 @@ import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Element as ScanElement } from "happy-dom";
 import { isResourceImageContentType } from "../shared/index.js";
 import { rewriteStepsBlock } from "./compile-steps-block.js";
-import { withParsedDocument } from "./document-sanitizer.js";
+import { conditionScopeElement, withParsedDocument } from "./document-sanitizer.js";
 import {
+  DOCUMENT_CONDITION_ATTRIBUTE,
   DOCUMENT_TEXT_ALIGNMENTS,
   isAllowedDocumentLinkHref,
   isDocumentPlaceholderHref,
@@ -25,6 +26,8 @@ type RowScope = { readonly listName: string; readonly itemFields: TemplateVariab
 type CompileState = {
   readonly variables: TemplateVariables;
   readonly expressions: string[];
+  // richText spans that fill a whole block; their value brings its own paragraphs.
+  readonly blockRichTextSpans: Set<ScanElement>;
 };
 
 function marker(state: CompileState, expression: string): string {
@@ -59,10 +62,19 @@ function resolveReference(
   return { path: scope === null ? name : `@root.${name}`, def: ownVariable(variables, name) };
 }
 
-function valueExpression(path: string, def: TemplateVariableDef | undefined): string {
+// The sanitized rich text value always consists of blocks; inside a line of
+// other text it renders inline so no paragraph ends up inside a paragraph.
+function valueExpression(
+  path: string,
+  def: TemplateVariableDef | undefined,
+  isWholeBlock: boolean,
+): string {
   if (def?.type === "money") return `{{money ${path}}}`;
   if (def?.type === "date") return `{{date ${path}}}`;
-  if (def?.type === "richText") return `{{richText ${path}}}`;
+  if (def?.type === "percent") return `{{percent ${path}}}`;
+  if (def?.type === "richText") {
+    return isWholeBlock ? `{{richText ${path}}}` : `{{richText ${path} inline=true}}`;
+  }
   return `{{${path}}}`;
 }
 
@@ -70,7 +82,13 @@ 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)))
+      ? marker(
+          state,
+          valueExpression(
+            ...pathAndDef(name, element, state),
+            state.blockRichTextSpans.has(element),
+          ),
+        )
       : "",
   );
   element.replaceWith(replacement);
@@ -112,10 +130,27 @@ function wrapVariableOnlyBlock(block: ScanElement, state: CompileState): void {
   const name = soleVariableName(block);
   // skip: a line with static content or several placeholders stays as it is
   if (name === null) return;
-  const [path] = pathAndDef(name, block, state);
-  const document = block.ownerDocument;
-  block.before(document.createTextNode(marker(state, `{{#if ${path} includeZero=true}}`)));
-  block.after(document.createTextNode(marker(state, "{{/if}}")));
+  const [path, def] = pathAndDef(name, block, state);
+  const host =
+    def?.type === "richText" && block.tagName === "P" ? richTextBlockHost(block, state) : block;
+  const document = host.ownerDocument;
+  host.before(document.createTextNode(marker(state, `{{#if ${path} includeZero=true}}`)));
+  host.after(document.createTextNode(marker(state, "{{/if}}")));
+}
+
+// A paragraph cannot hold the paragraphs of a rich text value, a div can; it
+// keeps the paragraph's attributes so alignment and size still apply.
+function richTextBlockHost(paragraph: ScanElement, state: CompileState): ScanElement {
+  const host = paragraph.ownerDocument.createElement("div");
+  for (const attribute of Array.from(paragraph.attributes)) {
+    host.setAttribute(attribute.name, attribute.value ?? "");
+  }
+  for (const span of Array.from(paragraph.querySelectorAll("span[data-variable]"))) {
+    state.blockRichTextSpans.add(span);
+  }
+  host.append(...Array.from(paragraph.childNodes));
+  paragraph.replaceWith(host);
+  return host;
 }
 
 function rewriteLink(element: ScanElement, state: CompileState): void {
@@ -146,6 +181,20 @@ function rewriteRepeatRow(row: ScanElement, state: CompileState): void {
   }
 }
 
+function rewriteConditionalBlock(block: ScanElement, state: CompileState): void {
+  const name = block.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE) ?? "";
+  block.removeAttribute(DOCUMENT_CONDITION_ATTRIBUTE);
+  if (!isDocumentReferenceName(name)) {
+    block.remove();
+    // skip: a condition on a name that cannot be a variable never shows
+    return;
+  }
+  const [path] = pathAndDef(name, conditionScopeElement(block), state);
+  const document = block.ownerDocument;
+  block.before(document.createTextNode(marker(state, `{{#if ${path} includeZero=true}}`)));
+  block.after(document.createTextNode(marker(state, "{{/if}}")));
+}
+
 function stripActiveContent(element: ScanElement): void {
   for (const attribute of Array.from(element.attributes)) {
     if (/^on/i.test(attribute.name)) element.removeAttribute(attribute.name);
@@ -311,7 +360,7 @@ export function compileDocumentBodyToHandlebars(
   variables: TemplateVariables,
   options: CompileDocumentBodyOptions = {},
 ): string {
-  const state: CompileState = { variables, expressions: [] };
+  const state: CompileState = { variables, expressions: [], blockRichTextSpans: new Set() };
   const scrubbed = html.replaceAll(EXPRESSION_OPEN, "").replaceAll(EXPRESSION_CLOSE, "");
   const compiled = withParsedDocument(scrubbed, (root) => {
     stripScriptsAndActiveContent(root, options);
@@ -325,6 +374,9 @@ export function compileDocumentBodyToHandlebars(
         color: options.stepsColor,
       });
     }
+    for (const block of Array.from(root.querySelectorAll(`[${DOCUMENT_CONDITION_ATTRIBUTE}]`))) {
+      rewriteConditionalBlock(block, state);
+    }
     for (const block of Array.from(root.querySelectorAll(VARIABLE_ONLY_BLOCK_SELECTOR))) {
       wrapVariableOnlyBlock(block, state);
     }

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

@@ -7,6 +7,7 @@ import { type Element as ScanElement, Window } from "happy-dom";
 import type { ContentFormat } from "./constants.js";
 import { DOCUMENT_HTML_KINDS } from "./constants.js";
 import {
+  DOCUMENT_CONDITION_ATTRIBUTE,
   documentExtensions,
   isAllowedDocumentLinkHref,
   isDocumentPlaceholderHref,
@@ -138,6 +139,7 @@ function scanImage(element: ScanElement, out: DocumentViolation[]): void {
 const REFERENCE_ATTRIBUTES: ReadonlyArray<readonly [string, (value: string) => boolean]> = [
   ["data-variable", isDocumentReferenceName],
   ["data-each", isDocumentReferenceName],
+  [DOCUMENT_CONDITION_ATTRIBUTE, isDocumentReferenceName],
   ["data-resource", isDocumentResourceKey],
   ["data-steps", isDocumentReferenceName],
   ["data-step", isDocumentStepKey],
@@ -270,6 +272,17 @@ export function sanitizeDocumentHtml(html: string): SanitizeHtmlResult {
   };
 }
 
+// For a sanitized value placed inside a line of text: paragraphs become line
+// breaks. Other blocks (lists, headings) cannot be made inline and stay as they are.
+export function flattenParagraphsToLineBreaks(sanitizedHtml: string): string {
+  return withParsedDocument(sanitizedHtml, (body) => {
+    const blocks = Array.from(body.children);
+    const isParagraphsOnly =
+      blocks.length === body.childNodes.length && blocks.every((block) => block.tagName === "P");
+    return isParagraphsOnly ? blocks.map((block) => block.innerHTML).join("<br>") : sanitizedHtml;
+  });
+}
+
 // Snippets accept any format, but their html is as untrusted as a mail body.
 function isSanitizedHtmlKind(kind: string): boolean {
   return kind === "snippet" || isOneOf(DOCUMENT_HTML_KINDS, kind);
@@ -336,3 +349,9 @@ export function documentViolationsToFieldIssues(
     params: { detail: item.detail },
   }));
 }
+
+// A repeat row's own data-if is decided per list, outside the row's item scope,
+// because the compiled {{#if}} lands outside its {{#each}}.
+export function conditionScopeElement(block: ScanElement): ScanElement {
+  return block.matches("tr[data-each]") ? (block.parentElement ?? block) : block;
+}

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

@@ -314,6 +314,38 @@ export const DocumentTextSize = Extension.create({
   },
 });
 
+// A block shown only when the named variable has a value (data-if, the
+// conditional counterpart of data-each). Table rows qualify so an invoice can
+// drop a discount line; tiptap merges the attribute into paragraph, heading
+// and row markup only.
+export const DOCUMENT_CONDITION_ATTRIBUTE = "data-if";
+
+export const DocumentCondition = Extension.create({
+  name: "documentCondition",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["paragraph", "heading", "tableRow"],
+        attributes: {
+          showIf: {
+            default: null,
+            parseHTML: (element) => {
+              const name = element.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE);
+              return name !== null && isDocumentReferenceName(name) ? name : null;
+            },
+            renderHTML: (attributes) => {
+              const name: unknown = attributes["showIf"];
+              return typeof name === "string" && isDocumentReferenceName(name)
+                ? { [DOCUMENT_CONDITION_ATTRIBUTE]: name }
+                : {};
+            },
+          },
+        },
+      },
+    ];
+  },
+});
+
 export const documentExtensions: Extensions = [
   StarterKit.configure({
     blockquote: false,
@@ -348,4 +380,5 @@ export const documentExtensions: Extensions = [
   DocumentSteps,
   DocumentTextAlign,
   DocumentTextSize,
+  DocumentCondition,
 ];

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

@@ -32,6 +32,7 @@ import { resolveTemplateVariables } from "../template-validation.js";
 import { MAX_FILE_ATTACHMENTS_PER_TEMPLATE } from "./resource-shared.js";
 import { evaluateTemplateWrite } from "./template-gates.js";
 import {
+  refuseSystemOnlyTenantOverride,
   refuseTenantScopeUnderSystemTenant,
   type TemplateRowPayload,
   writeTemplateRow,
@@ -113,7 +114,14 @@ function checkBundleAttachments(bundle: TemplateBundle): WriteResult<null> {
 export async function prepareTemplateBundleBeforeTransaction(
   args: BundleImport & { readonly status: BundleImportStatus },
 ): Promise<BeforeTransactionResult<PreparedBundleResources>> {
-  const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
+  const refused =
+    refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId) ??
+    refuseSystemOnlyTenantOverride(
+      args.ctx.registry,
+      args.scope,
+      args.bundle.slug,
+      args.bundle.kind,
+    );
   if (refused !== null) return refused;
   const issues = await collectBundleIssues(args, args.status);
   if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));

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

@@ -30,7 +30,11 @@ import { resolveTemplateVariables } from "../template-validation.js";
 import { targetExistsIssue } from "./bundle-import.js";
 import { kindSchema, localeSchema, templateSlugSchema } from "./shared.js";
 import { parseStoredJson, storedRecord } from "./template-gates.js";
-import { refuseTenantScopeUnderSystemTenant, writeTemplateRow } from "./template-write.js";
+import {
+  refuseSystemOnlyTenantOverride,
+  refuseTenantScopeUnderSystemTenant,
+  writeTemplateRow,
+} from "./template-write.js";
 
 type CopyScope = "tenant" | "system";
 type WriteCtx = HandlerContext;
@@ -108,7 +112,9 @@ async function checkCopyRequest(
     );
   }
   const tenantId = scope === "system" ? SYSTEM_TENANT_ID : event.user.tenantId;
-  const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+  const refused =
+    refuseTenantScopeUnderSystemTenant(scope, tenantId) ??
+    refuseSystemOnlyTenantOverride(ctx.registry, scope, slug, kind);
   if (refused !== null) return refused;
 
   const readDb = readDbFor(ctx, scope);