@cosmicdrift/kumiko-samples 0.366.0 → 0.367.0

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

@@ -3,6 +3,7 @@ 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";
+import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.js";
 
 // Admin-Lookup für UI-Edit-Flow. Returnt das raw Template inkl. draft/
 // archived Status. Tenant-Isolation: User sieht nur Templates des
@@ -19,7 +20,13 @@ export const findByIdQuery = defineQueryHandler({
     const stored = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
       id: query.payload.id,
     });
-    if (!stored || isHiddenSystemDraft(query.user, stored)) return null;
+    if (
+      !stored ||
+      isHiddenSystemDraft(query.user, stored) ||
+      isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, stored)
+    ) {
+      return null;
+    }
     const row = toWorkingRow(stored, draftViewerTenantId(query.user, stored));
     const isOwnTenant = row.tenantId === query.user.tenantId;
     const isSystemTemplate = row.scope === "system";

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

@@ -4,6 +4,7 @@ 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";
+import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.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.
@@ -45,7 +46,11 @@ export const listQuery = defineQueryHandler({
     })) as TemplateResourceRow[];
 
     return rows
-      .filter((row) => !isHiddenSystemDraft(query.user, row))
+      .filter(
+        (row) =>
+          !isHiddenSystemDraft(query.user, row) &&
+          !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row),
+      )
       .map((row) => ({
         id: String(row.id),
         tenantId: row.tenantId,

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

@@ -11,6 +11,7 @@ import {
   parseTemplateDraft,
   servedVersionOf,
 } from "../template-draft.js";
+import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.js";
 import { collectTemplateUsage, type EffectiveMailLayoutSlugs } from "../template-usage.js";
 import { storedRecord } from "./template-gates.js";
 
@@ -284,7 +285,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 (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.",
+    "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; templates of notifications registered with `systemOnly` are listed for SystemAdmins only; use it to browse and filter all templates at a glance.",
   handler: async (query, ctx) => {
     const payload = query.payload;
     const fetchedRows = await selectMany<TemplateResourceRow>(
@@ -301,7 +302,11 @@ export const overviewQuery = defineQueryHandler({
       });
     }
 
-    const visibleRows = rows.filter((row) => !isHiddenSystemDraft(query.user, row));
+    const visibleRows = rows.filter(
+      (row) =>
+        !isHiddenSystemDraft(query.user, row) &&
+        !isSystemOnlyTemplateHiddenFrom(query.user, ctx.registry, row),
+    );
     const { drafts, layoutSlugByDocument } = buildDrafts(
       groupBySlugAndKind(visibleRows),
       query.user,

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

@@ -1,6 +1,7 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
   type HandlerContext,
+  type Registry,
   type SessionUser,
   SYSTEM_TENANT_ID,
   type TemplateVariables,
@@ -16,8 +17,10 @@ import {
 import { requireForTenant } from "../../shared/index.js";
 import type { ContentFormat, TemplateKind } from "../constants.js";
 import type { TemplateWriteScope } from "../layout-regions.js";
+import { TemplateResolverErrors } from "../qualified-names.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 import { activationChanges, serializeTemplateDraft } from "../template-draft.js";
+import { isSystemOnlyTemplate } from "../template-system-only.js";
 import type { TemplateValidation } from "../template-validation.js";
 import { executor } from "./shared.js";
 import {
@@ -71,6 +74,21 @@ export function refuseTenantScopeUnderSystemTenant(
   );
 }
 
+export function refuseSystemOnlyTenantOverride(
+  registry: Registry,
+  scope: TemplateWriteScope,
+  slug: string,
+  kind: string,
+): WriteFailure | null {
+  if (scope !== "tenant" || !isSystemOnlyTemplate(registry, slug, kind)) return null;
+  return writeFailure(
+    new AccessDeniedError({
+      i18nKey: "templateResolver.errors.systemOnlyTemplate",
+      details: { reason: TemplateResolverErrors.systemOnlyTemplate },
+    }),
+  );
+}
+
 export type GatedTemplateWrite =
   | { readonly ok: true; readonly evaluated: Extract<TemplateWriteResult, { ok: true }> }
   | { readonly ok: false; readonly failure: WriteFailure };
@@ -141,7 +159,9 @@ export async function writeTemplateRow(
   args: TemplateRowWrite,
 ): Promise<WriteResult<WrittenTemplateRow>> {
   const { ctx, user, tenantId, scope, status, payload } = args;
-  const refused = refuseTenantScopeUnderSystemTenant(scope, tenantId);
+  const refused =
+    refuseTenantScopeUnderSystemTenant(scope, tenantId) ??
+    refuseSystemOnlyTenantOverride(ctx.registry, scope, payload.slug, payload.kind);
   if (refused !== null) return refused;
   const { db, streamTenantId } = requireForTenant(ctx, tenantId);
 

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

@@ -46,15 +46,18 @@ export {
   type DocumentViolation,
   type DocumentViolationCode,
   documentViolationsToFieldIssues,
+  flattenParagraphsToLineBreaks,
   type SanitizeBodyResult,
   type SanitizeHtmlResult,
   sanitizeDocumentHtml,
   sanitizeTemplateBody,
 } from "./document-sanitizer.js";
 export {
+  DOCUMENT_CONDITION_ATTRIBUTE,
   DOCUMENT_NODE_NAMES,
   DOCUMENT_TEXT_ALIGNMENTS,
   DocumentButton,
+  DocumentCondition,
   DocumentDivider,
   DocumentLink,
   DocumentPageBreak,
@@ -144,6 +147,7 @@ export {
 } from "./template-meta.js";
 export { type DocumentDraftOutcome, evaluateDocumentDraft } from "./template-preview.js";
 export { readTemplateResource, type TemplateResourceFile } from "./template-resources.js";
+export { isSystemOnlyTemplate } from "./template-system-only.js";
 export { collectTemplateUsage, type TemplateUsageEntry } from "./template-usage.js";
 export {
   hasPlaceholderProblems,

package/packages/bundled-features/src/template-resolver/qualified-names.ts

@@ -60,6 +60,7 @@ export const TemplateResolverErrors = {
   alreadyArchived: "template_already_archived",
   targetExists: "target_exists",
   systemResourcesNeedSystemTenant: "system_resources_need_system_tenant",
+  systemOnlyTemplate: "system_only_template",
   bundleLocalesDiffer: "bundle_locales_differ",
   resourceTooLarge: "template_resource_too_large",
   resourceUnsupportedImage: "template_resource_unsupported_image",

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

@@ -28,11 +28,13 @@ import {
   getStreamVersion,
   getUnscopedStreamMaxVersionForSeed,
 } from "@cosmicdrift/kumiko-framework/event-store";
+import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import { runEventStoreSeed, type SeedIfExists } from "@cosmicdrift/kumiko-framework/seeding";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { type ContentFormat, TEXT_BLOCK_KIND, type UpsertKind } from "./constants.js";
 import { executor } from "./handlers/shared.js";
 import { evaluateTemplateWrite } from "./handlers/template-gates.js";
-import { TEMPLATE_RESOLVER_FEATURE } from "./qualified-names.js";
+import { TEMPLATE_RESOLVER_FEATURE, TemplateResolverHandlers } from "./qualified-names.js";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
 import type { TemplateBundle } from "./template-bundle.js";
 import { activeStampChanges, servedStampChanges } from "./template-draft.js";
@@ -233,20 +235,21 @@ export async function seedSystemTemplate(
 export type SeedSystemTemplateBundleOptions = {
   readonly by?: SessionUser;
   readonly ifExists?: SeedIfExists;
+  /** Required for bundles with resources (e.g. a `logo`): the files go through the
+   *  import-bundle-system write, which needs the file provider of the system tenant. */
+  readonly dispatcher?: Dispatcher;
 };
 
-// Seeds one system row per bundle locale. Bundled resources need a file
-// provider and the system tenant's file space, which a boot seed does not
-// have, so those go through the import-bundle-system write instead.
+// Seeds one system row per bundle locale. Bundled resources need a file provider and
+// the system tenant's file space, so those bundles are written through the
+// import-bundle-system handler on the seed dispatcher instead of directly.
 export async function seedSystemTemplateBundle(
   db: DbConnection,
   bundle: TemplateBundle,
   opts: SeedSystemTemplateBundleOptions = {},
 ): Promise<{ ids: Record<string, string> }> {
   if (Object.keys(bundle.resources).length > 0) {
-    throw new Error(
-      `seedSystemTemplateBundle ${bundle.slug}/${bundle.kind}: bundles with resources cannot be seeded; use the import-bundle-system write`,
-    );
+    return seedSystemTemplateBundleWithResources(db, bundle, opts);
   }
   const ids: Record<string, string> = {};
   for (const [locale, entry] of Object.entries(bundle.locales)) {
@@ -266,6 +269,50 @@ export async function seedSystemTemplateBundle(
   return { ids };
 }
 
+async function seedSystemTemplateBundleWithResources(
+  db: DbConnection,
+  bundle: TemplateBundle,
+  opts: SeedSystemTemplateBundleOptions,
+): Promise<{ ids: Record<string, string> }> {
+  const label = `seedSystemTemplateBundle ${bundle.slug}/${bundle.kind}`;
+  const { dispatcher } = opts;
+  if (!dispatcher) {
+    throw new Error(
+      `${label}: bundles with resources need a file provider; pass opts.dispatcher (the dispatcher of the seed deps) so the files are stored through the import-bundle-system write`,
+    );
+  }
+  if ((opts.ifExists ?? "skip") === "skip") {
+    const existingIds: Record<string, string> = {};
+    for (const locale of Object.keys(bundle.locales)) {
+      const row = await fetchOne<TemplateResourceRow>(db, templateResourcesTable, {
+        tenantId: SYSTEM_TENANT_ID,
+        slug: bundle.slug,
+        kind: bundle.kind,
+        locale,
+      });
+      if (row) existingIds[locale] = String(row.id);
+    }
+    if (Object.keys(existingIds).length === Object.keys(bundle.locales).length) {
+      return { ids: existingIds };
+    }
+  }
+  const result = await dispatcher.write(
+    TemplateResolverHandlers.importBundleSystem,
+    { bundle },
+    opts.by ?? createSystemUser(SYSTEM_TENANT_ID, ["SystemAdmin"]),
+  );
+  if (!result.isSuccess) {
+    throw new Error(`${label} failed: ${result.error.code}: ${result.error.message}`);
+  }
+  return { ids: importedIds(result.data) };
+}
+
+function importedIds(data: unknown): Record<string, string> {
+  const ids = isPlainObject(data) ? data["ids"] : undefined;
+  if (!isPlainObject(ids)) throw new Error("seedSystemTemplateBundle: import returned no ids");
+  return Object.fromEntries(Object.entries(ids).map(([locale, id]) => [locale, String(id)]));
+}
+
 export function hasNotificationTemplates(registry: Registry): boolean {
   return Array.from(registry.getAllNotifications().values()).some(
     (notification) => notification.template !== undefined,

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

@@ -69,6 +69,8 @@ function sampleScalar(name: string, def: TemplateScalarVariableDef): unknown {
       return 0;
     case "date":
       return SAMPLE_DATE;
+    case "percent":
+      return 0;
   }
 }
 

package/packages/bundled-features/src/template-resolver/template-system-only.ts

@@ -0,0 +1,21 @@
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { isSystemAdmin } from "./template-draft.js";
+
+const NOTIFICATION_TEMPLATE_KIND = "mail";
+
+// A notification registered with systemOnly keeps its mail template as the system default:
+// tenants neither list nor override it, and overrides stored before the flag are ignored.
+export function isSystemOnlyTemplate(registry: Registry, slug: string, kind: string): boolean {
+  return (
+    kind === NOTIFICATION_TEMPLATE_KIND &&
+    registry.getAllNotifications().get(slug)?.systemOnly === true
+  );
+}
+
+export function isSystemOnlyTemplateHiddenFrom(
+  user: { readonly roles: readonly string[] },
+  registry: Registry,
+  row: { readonly slug: string; readonly kind: string },
+): boolean {
+  return !isSystemAdmin(user) && isSystemOnlyTemplate(registry, row.slug, row.kind);
+}

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

@@ -6,8 +6,12 @@ import type {
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { Element as ScanElement } from "happy-dom";
 import * as z from "zod";
-import { withParsedDocument } from "./document-sanitizer.js";
-import { isDocumentPlaceholderHref, isDocumentReferenceName } from "./document-schema.js";
+import { conditionScopeElement, withParsedDocument } from "./document-sanitizer.js";
+import {
+  DOCUMENT_CONDITION_ATTRIBUTE,
+  isDocumentPlaceholderHref,
+  isDocumentReferenceName,
+} from "./document-schema.js";
 import type { TemplateMeta } from "./template-meta.js";
 
 export const SYSTEM_PLACEHOLDERS: ReadonlySet<string> = new Set([
@@ -56,6 +60,7 @@ const scalarVariableSchema = z.discriminatedUnion("type", [
       .optional(),
   }),
   z.object({ ...variableCommon, type: z.literal("date"), example: textLikeExample }),
+  z.object({ ...variableCommon, type: z.literal("percent"), example: z.number().optional() }),
 ]);
 
 const variableDefSchema = z.union([
@@ -154,30 +159,49 @@ const NAME_ATTRIBUTE_BY_TAG: Readonly<Record<string, string>> = {
   div: "data-steps",
 };
 
+function scanRepeatRows(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+    const listName = element.getAttribute("data-each") ?? "";
+    const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
+    if (def?.type === "list") scope.used.add(listName);
+    else scope.unknown.add(listName);
+  }
+}
+
+function scanConditions(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(root.querySelectorAll(`[${DOCUMENT_CONDITION_ATTRIBUTE}]`))) {
+    const itemFields = listItemFields(
+      scope.variables,
+      enclosingEachName(conditionScopeElement(element)),
+    );
+    recordName(element.getAttribute(DOCUMENT_CONDITION_ATTRIBUTE) ?? "", itemFields, scope);
+  }
+}
+
+function scanReferences(root: ScanElement, scope: PlaceholderScope): void {
+  for (const element of Array.from(
+    root.querySelectorAll("span[data-variable], div[data-steps], a[href], img[data-resource]"),
+  )) {
+    const itemFields = listItemFields(scope.variables, enclosingEachName(element));
+    const tag = element.tagName.toLowerCase();
+    const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
+    if (nameAttribute !== undefined) {
+      recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
+    } else if (tag === "a") {
+      const href = element.getAttribute("href") ?? "";
+      if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
+    } else {
+      const key = element.getAttribute("data-resource") ?? "";
+      if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
+    }
+  }
+}
+
 function scanBodyPlaceholders(body: string, scope: PlaceholderScope): void {
   withParsedDocument(body, (root) => {
-    for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
-      const listName = element.getAttribute("data-each") ?? "";
-      const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
-      if (def?.type === "list") scope.used.add(listName);
-      else scope.unknown.add(listName);
-    }
-    for (const element of Array.from(
-      root.querySelectorAll("span[data-variable], div[data-steps], a[href], img[data-resource]"),
-    )) {
-      const itemFields = listItemFields(scope.variables, enclosingEachName(element));
-      const tag = element.tagName.toLowerCase();
-      const nameAttribute = NAME_ATTRIBUTE_BY_TAG[tag];
-      if (nameAttribute !== undefined) {
-        recordName(element.getAttribute(nameAttribute) ?? "", itemFields, scope);
-      } else if (tag === "a") {
-        const href = element.getAttribute("href") ?? "";
-        if (isDocumentPlaceholderHref(href)) recordName(href.slice(2, -2), itemFields, scope);
-      } else {
-        const key = element.getAttribute("data-resource") ?? "";
-        if (!scope.resourceKeys.has(key)) scope.unknownResources.add(key);
-      }
-    }
+    scanRepeatRows(root, scope);
+    scanConditions(root, scope);
+    scanReferences(root, scope);
   });
 }
 

package/packages/bundled-features/src/template-resolver/web/i18n.ts

@@ -96,6 +96,8 @@ export const defaultTranslations: TranslationsByLocale = {
       "“{detail}” templates are written through their own editor, not through a collection.",
     "templateResolver.errors.noSystemTemplate": "There is no active system template to reset to.",
     "templateResolver.errors.noDraft": "There is no draft to discard.",
+    "templateResolver.errors.systemOnlyTemplate":
+      "Only the platform maintains this template; it cannot be overridden per tenant.",
     "templateResolver.errors.template.invalidMeta": "The template settings are invalid.",
     "templateResolver.errors.template.meta.subject.required": "The subject is missing.",
     "templateResolver.errors.template.meta.subject.invalid":

package/packages/bundled-features/src/user-data-rights/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.367.0",
+    "type": "fix",
+    "title": "Tests seed tenant memberships and events through the framework",
+    "detail": "Test-only change. Integration tests create read_tenant_memberships from tenantMembershipEntity and seed rows with seedRow instead of hand-written DDL and raw INSERTs. Fake events go through the event-store append, and backdated audit events are written with runSeedWritesAt instead of an UPDATE on created_at. No runtime behavior changes."
+  },
   {
     "version": "0.365.0",
     "type": "improvement",

package/samples/apps/ui-walkthrough/src/app/seed-templates.ts

@@ -32,6 +32,7 @@ import {
   SYSTEM_INVOICE_ISSUED,
   SYSTEM_PDF_LAYOUT,
   SYSTEM_TENANCY_CERTIFICATE,
+  SYSTEM_TERMS_CHANGED,
   TENANT_INVOICE_OVERRIDES,
   TENANT_MAIL_LAYOUT_VERSIONS,
   TENANT_UTILITY_STATEMENT,
@@ -165,6 +166,7 @@ export const seedTemplates: SeedFn = async (stack) => {
   await upsertSystem(SYSTEM_PDF_LAYOUT);
   for (const mail of SYSTEM_AUTH_MAILS) await upsertSystem(mail);
   await upsertSystem(SYSTEM_INVOICE_ISSUED);
+  await upsertSystem(SYSTEM_TERMS_CHANGED);
   for (const document of SYSTEM_INVOICE_DOCUMENTS) await upsertSystem(document);
   const certificate = await upsertSystem(SYSTEM_TENANCY_CERTIFICATE);
   await stack.http.writeOk(

package/samples/apps/ui-walkthrough/src/app/template-seed-data.ts

@@ -276,6 +276,18 @@ export const INVOICE_CORRECTED_DRAFT: SeedTemplate = {
   meta: invoiceIssuedMeta("Ihre Rechnung {{invoiceNumber}} von {{tenantName}}"),
 };
 
+export const SYSTEM_TERMS_CHANGED: SeedTemplate = {
+  slug: "billing:notify:terms-changed",
+  kind: "mail",
+  locale: "de",
+  title: "AGB-Änderung",
+  content: [
+    `<p>Guten Tag ${v("customerName")},</p>`,
+    `<p>zum ${v("effectiveDate")} ändern sich die Allgemeinen Geschäftsbedingungen des Mieterportals.</p>`,
+  ].join(""),
+  meta: { subject: "Änderung der Geschäftsbedingungen" },
+};
+
 export const PAYMENT_REMINDER_TEMPLATES: readonly SeedTemplate[] = [
   {
     slug: "billing:notify:payment-reminder",

package/samples/apps/ui-walkthrough/src/features/billing/feature.ts

@@ -63,10 +63,17 @@ const PAYMENT_REMINDER_VARIABLES = {
   invoiceUrl: templateVariable.link({ required: true }),
 } as const;
 
+const TERMS_CHANGED_VARIABLES = {
+  customerName: templateVariable.text({ required: true, example: "Familie Yilmaz" }),
+  effectiveDate: templateVariable.date({ required: true, example: "2026-12-01" }),
+} as const;
+
 export const billingFeature = defineFeature("billing", (r) => {
   r.translations({ keys: toKeyFirst(billingTranslations) });
 
   r.notification("invoice-issued", { variables: INVOICE_ISSUED_VARIABLES });
   r.notification("invoice-corrected", { variables: INVOICE_ISSUED_VARIABLES });
   r.notification("payment-reminder", { variables: PAYMENT_REMINDER_VARIABLES });
+  // Legal wording the platform owns: tenant admins neither see nor override it.
+  r.notification("terms-changed", { variables: TERMS_CHANGED_VARIABLES, systemOnly: true });
 });

package/samples/apps/ui-walkthrough/src/features/billing/i18n.ts

@@ -8,11 +8,13 @@ export const billingTranslations: TranslationsByLocale = {
     "billing:notify.invoice-issued.label": "Rechnung gestellt",
     "billing:notify.invoice-corrected.label": "Rechnung korrigiert",
     "billing:notify.payment-reminder.label": "Mahnlauf",
+    "billing:notify.terms-changed.label": "AGB-Änderung",
   },
   en: {
     "billing:feature.label": "Invoices",
     "billing:notify.invoice-issued.label": "Invoice issued",
     "billing:notify.invoice-corrected.label": "Invoice corrected",
     "billing:notify.payment-reminder.label": "Dunning run",
+    "billing:notify.terms-changed.label": "Terms update",
   },
 };

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -407,7 +407,7 @@
     },
     {
       "name": "channel-email",
-      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.",
+      "description": "Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.",
       "toggleableDefault": null,
       "requires": [
         "delivery"
@@ -725,7 +725,7 @@
     },
     {
       "name": "delivery",
-      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.",
+      "description": "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: \"deferred\" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: \"dispatched\", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.",
       "toggleableDefault": null,
       "requires": [
         "tenant"
@@ -1507,7 +1507,7 @@
     },
     {
       "name": "mail-foundation",
-      "description": "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 — 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.",
+      "description": "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 — 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.",
       "toggleableDefault": null,
       "requires": [
         "config"
@@ -2122,7 +2122,7 @@
     },
     {
       "name": "renderer-mail-html",
-      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
+      "description": "A `renderer-foundation` plugin that handles `RenderRequest { kind: \"mail\" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: \"mail\"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: \"mail-layout\"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource=\"logo\"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.",
       "toggleableDefault": null,
       "requires": [
         "renderer-foundation",

package/samples/apps/use-all-bundled/package.json

@@ -21,6 +21,7 @@
     "@cosmicdrift/kumiko-document-designer": "workspace:*",
     "@cosmicdrift/kumiko-framework": "workspace:*",
     "@cosmicdrift/kumiko-headless": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*",
     "@cosmicdrift/kumiko-renderer-puppeteer-client": "workspace:*",
     "@cosmicdrift/kumiko-renderer-web": "workspace:*",
     "@cosmicdrift/kumiko-server-runtime": "workspace:*",