@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

package/samples/apps/use-all-bundled/src/app/seed.ts

@@ -37,6 +37,7 @@ import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { ADMIN_EMAIL, BETA_TENANT_ID, DEMO_NOTE_ID, DEV_TENANT_ID } from "./auth-constants";
 import { noteEntity } from "./notes-feature";
+import { seedPdfDocuments } from "./seed-documents";
 
 // Event-store executors mirror the real handlers (createEntityExecutor pairs the
 // projection table + executor), so seeded rows are proper event streams, not
@@ -392,6 +393,9 @@ export const seedScreenshotData: SeedFn = async (stack) => {
     await stack.http.writeOk("auth-email-password:write:invite-create", invitee, inviter);
   }
 
+  // PDF template editor — system invoice + letterhead, one live and one draft tenant override.
+  await seedPdfDocuments(stack, devAdminId);
+
   // reply-snippets — entries for the rich collection. Written through the
   // collection's own set-handler, the same path the editor uses, so the rows
   // carry whatever the handler derives instead of a hand-built projection.

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -39,7 +39,6 @@ import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-fea
 import { complianceProfilesOpsFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles-ops";
 import { customFieldsFeature } from "@cosmicdrift/kumiko-bundled-features/custom-fields";
 import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
-import type { NotificationRenderer } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { createDeliveryFeature } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { derivativesSharpFeature } from "@cosmicdrift/kumiko-bundled-features/derivatives-sharp";
 import { documentIngestFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/document-ingest-foundation";
@@ -77,7 +76,6 @@ import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/p
 import { readinessFeature } from "@cosmicdrift/kumiko-bundled-features/readiness";
 import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
 import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
-import { createRendererSimpleFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-simple";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
 import { createStepDispatcherFeature } from "@cosmicdrift/kumiko-bundled-features/step-dispatcher";
@@ -95,8 +93,10 @@ import { createUserDataRightsDefaultsFeature } from "@cosmicdrift/kumiko-bundled
 import { createUserProfileFeature } from "@cosmicdrift/kumiko-bundled-features/user-profile";
 import { createWaitlistFeature } from "@cosmicdrift/kumiko-bundled-features/waitlist";
 import { workflowRunnerFeature } from "@cosmicdrift/kumiko-bundled-features/workflow-runner";
+import { createDocumentDesignerFeature } from "@cosmicdrift/kumiko-document-designer";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { localeDe } from "@cosmicdrift/kumiko-locale-de";
+import { createRendererPuppeteerClientFeature } from "@cosmicdrift/kumiko-renderer-puppeteer-client";
 import { DEV_TENANT_ID } from "./app/auth-constants";
 import { CAP_OVERVIEW_CAPS } from "./app/cap-overview-caps";
 import { capOverviewLabelsFeature } from "./app/cap-overview-labels-feature";
@@ -114,10 +114,6 @@ const stubPushTransport: PushTransport = {
     /* smoke-only */
   },
 };
-const stubRenderer: NotificationRenderer = {
-  name: "smoke",
-  render: async () => "<smoke/>",
-};
 
 // Fixed dev-only signing key for the reset/verify/unlock magic-links (and,
 // below, tenant-handover's row-bound grant). The factory rejects anything
@@ -170,7 +166,6 @@ export const APP_FEATURES = [
   createChannelInAppFeature(),
   createChannelEmailFeature({
     transport: stubEmailTransport,
-    renderer: stubRenderer,
     resolveEmail: async () => "smoke@use-all-bundled.local",
   }),
   createChannelPushFeature({
@@ -297,7 +292,7 @@ export const APP_FEATURES = [
     collections: [
       {
         id: "reply-snippets",
-        kind: "mail-html",
+        kind: "snippet",
         access: { roles: ["TenantAdmin", "TenantMember", "SystemAdmin"] },
         // Without an explicit workspace the node lands in none of the three
         // shells and the collection is unreachable in the UI.
@@ -317,7 +312,7 @@ export const APP_FEATURES = [
       },
       {
         id: "signatures",
-        kind: "mail-html",
+        kind: "snippet",
         ownership: "user",
         access: { roles: ["TenantAdmin", "TenantMember", "SystemAdmin"] },
         nav: {
@@ -336,8 +331,10 @@ export const APP_FEATURES = [
   // collection-labels: the app-side nav labels for the two collections above.
   collectionLabelsFeature,
   createRendererFoundationFeature(),
-  createRendererSimpleFeature(),
   createRendererPdfFeature(),
+  // PDF printing for document templates; the print service is reached through
+  // PUPPETEER_SERVICE_URL + PUPPETEER_AUTH_TOKEN and only asked when a PDF is generated.
+  createRendererPuppeteerClientFeature(),
 
   // managed-pages: requires config (auto-bundled). Smoke resolver never serves
   // (boot-only). allowCustomCss:true boot-validates the CSS code path + emits
@@ -346,6 +343,9 @@ export const APP_FEATURES = [
   // covered — not standalone-mounted here (smoke = one mount per subpath-export).
   createManagedPagesFeature({ resolveApexTenant: () => null, allowCustomCss: true }),
 
+  // Template overview, layout editor and PDF template editor; needs template-resolver and managed-pages above.
+  createDocumentDesignerFeature(),
+
   // seo: requires config (auto-bundled). Smoke resolver never serves (boot-
   // only) — includeLegalPages:true gives the boot-check a real source
   // without needing real page data; managedPages reuses the same never-
@@ -363,7 +363,7 @@ export const APP_FEATURES = [
   // admin-shell: requires tenant (auto-mounted) + audit + jobs + tier-engine,
   // all mounted above. includeCapOverview:true exercises the my-caps /
   // tenant-caps nav entries end-to-end — cap-overview is mounted below.
-  createAdminShellFeature({ includeCapOverview: true }),
+  createAdminShellFeature({ includeCapOverview: true, includeDocumentDesigner: true }),
 
   // app-author-grade
   customFieldsFeature,

package/samples/recipes/delivery-notifications/README.md

@@ -1,48 +1,49 @@
 # Sample: Delivery Notifications
 
-Shows how a feature sends notifications to multiple channels (InApp + Email + Push) without knowing the channel internals.
+Shows how a feature sends notifications to multiple channels (InApp + Email + Push) without knowing the channel internals, and how the mail text lives in the template store where a tenant can override it.
 
 ## What you learn here
 
-**Declarative notifications:** `r.notification()` fires automatically after a CRUD handler — the feature author writes zero `ctx.notify()` calls.
+**Declarative notifications:** `r.notification()` declares the mail variables, the default mail text, the subject and the short inApp/push texts in one place.
 
-**Per-channel templates:** Each channel only receives the data it needs. InApp gets a short `title/body`, Email gets structured `sections` for the renderer, Push gets compact text.
+**Mail text is stored data:** The boot seed (`seedNotificationTemplates`) writes the declared `template` and `meta` into the template store as system templates. The email channel renders them with `renderer-mail-html`. A notification routed to email without `template` and `meta` fails its delivery.
+
+**Tenant override:** A tenant admin overrides the text through the template-resolver handlers (`upsertTenant`, then `publish`). The next mail for that tenant uses the override; the system text stays for everyone else.
+
+**Sending:** The write handler calls `ctx.notify(type, { to, data })`. The `data` keys are the template variables; sending fails loudly when a required variable is missing.
 
 **Swappable transports:** Email uses `InMemoryTransport` in tests; in a production setup it would be SMTP. Same interface, different implementation.
 
 ## Feature composition
 
-The test loads **7 features** together:
+The test loads these features together:
 
 ```
-config        → tenant/system config
-tenant        → memberships (delivery needs tenant:query:resolve-user-ids)
-delivery      → core: ctx.notify, DeliveryLog, Preferences, extension points
-channel-inApp → r.useExtension("deliveryChannel", "inApp", ...)
-channel-email → r.useExtension("deliveryChannel", "email", ...) + renderer + transport
-channel-push  → r.useExtension("deliveryChannel", "push", ...) + transport
-renderer-simple → r.useExtension("renderer", "simple", { kinds: ["notification"], render })
-support       → our business logic (tickets + notification definitions)
+config            → tenant/system config
+tenant            → memberships (delivery needs tenant:query:resolve-user-ids)
+template-resolver → template store, override handlers
+renderer-foundation + renderer-mail-html → renders kind "mail"
+delivery          → core: ctx.notify, DeliveryLog, Preferences, extension points
+channel-inApp / channel-email / channel-push
+support           → our business logic (tickets + the notification declaration)
 ```
 
-The `support` feature `r.requires("delivery")` — channels are features that attach to delivery, but `support` doesn't need to know them.
+The `support` feature `r.requires("delivery")`: channels are features that attach to delivery, but `support` doesn't need to know them.
 
 ## Flow
 
-1. Admin calls `support:write:ticket:create` over HTTP
-2. CrudExecutor inserts the ticket, returns the `SaveContext`
-3. Lifecycle pipeline: postSave hook fires `r.notification("ticket-assigned")`
-4. `recipient(result)` → assigneeId or `null` (skip)
-5. `data(result)` → raw data (title, description, ticketId, priority)
-6. For each registered channel:
-   - `templates[channelName](data)` transforms into channel-specific format
-   - InApp: DB insert + SSE push
-   - Email: renderer → HTML → transport
-   - Push: transport
-7. DeliveryLog entry per channel
+1. The boot seed stores the `ticket-assigned` mail template
+2. Admin calls `support:write:ticket:create` over HTTP
+3. The handler inserts the ticket and calls `ctx.notify` for the assignee (no assignee, no notification)
+4. For each registered channel:
+   - InApp: `templates.inApp(data)`, DB insert + SSE push
+   - Email: stored template rendered with `data` as variables, then transport
+   - Push: `templates.push(data)`, transport
+5. DeliveryLog entry per channel
 
 ## Tests
 
 - **E2E happy path:** Ticket with assignee → InApp + Email + Push + 3 DeliveryLog entries
-- **Recipient null skip:** Ticket without assignee → no notifications
+- **Tenant override:** a published tenant template replaces the system mail text
+- **Skip:** Ticket without assignee → no notifications
 - **Access control:** Non-Admin/Support can't create tickets

package/samples/recipes/delivery-notifications/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "dependencies": {
     "@cosmicdrift/kumiko-bundled-features": "workspace:*",
-    "@cosmicdrift/kumiko-framework": "workspace:*"
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-renderer-mail-html": "workspace:*"
   }
 }

package/samples/recipes/delivery-notifications/src/feature.ts

@@ -1,17 +1,21 @@
 // Delivery Notifications Sample
 //
-// Shows how a feature sends notifications via multiple channels (inApp + email + push).
-// Uses r.notification() for declarative notifications with per-channel templates.
-//
-// Flow: Admin assigns a support ticket to a user → the user gets notified
-//   - InApp: toast + badge in the app
-//   - Email: full HTML with rendered content
-//   - Push: native notification
+// A support ticket is created and its assignee is notified via inApp, email
+// and push. The mail is a stored template: `r.notification` declares the
+// variables, the default text and the subject, the boot seed writes the text
+// into the template store, and a tenant can override it there.
 //
 // The feature code only declares WHAT to notify. HOW is handled by Delivery.
 
 import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createTextField,
+  defineFeature,
+  QnTypes,
+  qn,
+  templateVariable,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 
 // --- Entity ---
@@ -40,69 +44,71 @@ function ticketExecutor() {
 
 // --- Feature ---
 
+export const TICKET_ASSIGNED = qn("support", QnTypes.notify, "ticket-assigned");
+
 export const supportFeature = defineFeature("support", (r) => {
   r.requires("delivery");
 
   r.entity("ticket", ticketEntity);
 
-  // Real CRUD handler (not stub) — returns SaveContext for lifecycle hooks
-  const createHandler = r.writeHandler(
-    "ticket:create",
-    z.object({
-      title: z.string().min(1),
-      description: z.string().optional(),
-      assigneeId: z.uuid().optional(),
-      priority: z.enum(["low", "normal", "critical"]),
-      status: z.string().default("open"),
-    }),
-    async (event, ctx) => ticketExecutor().create(event.payload, event.user, ctx.db),
-    { access: { roles: ["Admin", "Support"] } },
-  );
-
-  // Declarative notification: fires automatically after ticket.create postSave.
-  //
-  // - recipient: returns assignee ID, or null to skip (no assignee = no notification)
-  // - data: extracts raw fields from the save result
-  // - templates: per-channel transformations
-  //     inApp → short title/body for toast
-  //     email → structured template (header, sections, button) for renderer
-  //     push → short title/body for native notification
   r.notification("ticket-assigned", {
-    trigger: { on: createHandler },
-    recipient: (result) => {
-      const assigneeId = result.data["assigneeId"] as string | undefined;
-      return assigneeId ?? null;
+    variables: {
+      ticketId: templateVariable.text({ required: true }),
+      title: templateVariable.text({ required: true }),
+      description: templateVariable.text({ required: true }),
+      priority: templateVariable.text({ required: true }),
+      url: templateVariable.link({ required: true }),
     },
-    data: (result) => ({
-      ticketId: result.id,
-      title: result.data["title"] as string,
-      description: (result.data["description"] as string) ?? "",
-      priority: result.data["priority"] as string,
-    }),
+    template: {
+      en: {
+        body: '<h1>New ticket: <span data-variable="title"></span></h1><p><span data-variable="description"></span></p><p>Priority: <span data-variable="priority"></span></p><p><a data-button href="{{url}}">Open ticket</a></p>',
+      },
+    },
+    meta: { en: { subject: "Support ticket #{{ticketId}} ({{priority}})" } },
+    // inApp and push build their own short text; email renders the stored
+    // template with the notify data as variables.
     templates: {
       inApp: (data) => ({
-        title: `Neues Ticket: ${data["title"]}`,
-        body: (data["description"] as string) || "Dir wurde ein Ticket zugewiesen.",
-      }),
-      email: (data) => ({
-        subject: `Support-Ticket #${data["ticketId"]} (${data["priority"]})`,
-        header: `Neues Ticket: ${data["title"]}`,
-        sections: [
-          { text: (data["description"] as string) || "Kein Beschreibungstext." },
-          { text: `Prioritaet: ${data["priority"]}` },
-          {
-            button: {
-              label: "Ticket oeffnen",
-              url: `/support/tickets/${data["ticketId"]}`,
-            },
-          },
-        ],
-        footer: "Automatische Benachrichtigung — nicht antworten.",
+        title: `New ticket: ${data["title"]}`,
+        body: (data["description"] as string) || "A ticket was assigned to you.",
       }),
       push: (data) => ({
-        title: "Neues Ticket",
+        title: "New ticket",
         body: `${data["title"]} (${data["priority"]})`,
       }),
     },
   });
+
+  r.writeHandler(
+    "ticket:create",
+    z.object({
+      title: z.string().min(1),
+      description: z.string().optional(),
+      assigneeId: z.uuid().optional(),
+      priority: z.enum(["low", "normal", "critical"]),
+      status: z.string().default("open"),
+    }),
+    async (event, ctx) => {
+      const created = await ticketExecutor().create(event.payload, event.user, ctx.db);
+      const assigneeId = event.payload.assigneeId;
+      // No assignee, no notification.
+      if (!created.isSuccess || assigneeId === undefined) return created;
+      if (ctx.notify === undefined) {
+        throw new Error("ticket:create needs ctx.notify, mount the delivery feature");
+      }
+      const ticketId = created.data.id;
+      await ctx.notify(TICKET_ASSIGNED, {
+        to: assigneeId,
+        data: {
+          ticketId,
+          title: event.payload.title,
+          description: event.payload.description ?? "",
+          priority: event.payload.priority,
+          url: `https://app.example.com/support/tickets/${ticketId}`,
+        },
+      });
+      return created;
+    },
+    { access: { roles: ["Admin", "Support"] } },
+  );
 });

package/samples/recipes/seed-migration/README.md

@@ -40,7 +40,7 @@ Bei typo / drift fail-t mit klarer message + exit-code 1 — CI nutzt es als pr
 `findTemplateResources({ slug?, kind?, status?, locale?, tenantId? })` replaces a raw `SELECT … FROM read_template_resources`. It defaults to the system tenant and returns `[]` when template-resolver is not mounted:
 
 ```ts
-for (const t of await ctx.findTemplateResources({ kind: "notification", status: "active" })) {
+for (const t of await ctx.findTemplateResources({ kind: "mail", status: "active" })) {
   await ctx.systemWriteAs("template-resolver:write:archive", { id: t.id }, SYSTEM_TENANT_ID, [
     "SystemAdmin",
   ]);

package/packages/bundled-features/src/renderer-simple/changes.json

@@ -1,27 +0,0 @@
-[
-  {
-    "version": "0.352.0",
-    "type": "improvement",
-    "title": "Badge, stages track and chips for the simple mail renderer",
-    "detail": "Use badge, { stages } and { chips } in the template variables; the notification RenderResponse carries the matching plain text in text."
-  },
-  {
-    "version": "0.344.0",
-    "type": "improvement",
-    "title": "Heading and Markdown sections in the simple mail renderer",
-    "detail": "`createSimpleRenderer` accepts two more section kinds: `{ heading: string }` (rendered as an escaped `<h2>`) and `{ markdown: string }` (rendered with the hardened Markdown renderer; raw HTML is escaped and unsafe link targets are replaced by `#`). Existing section kinds render as before."
-  },
-  {
-    "version": "0.341.0",
-    "type": "improvement",
-    "title": "Localized mail branding, locale through delivery, logoPath",
-    "detail": "`ctx.notify` accepts `locale`, and the locale now travels through the delivery jobs (`delivery.render`, `delivery.send`) to `NotificationRenderer.render`, where `RendererInput.locale` is available. Jobs queued before this release have no locale and keep working. The email channel and `renderer-simple` pass it on; the auth mails and the consumer-protection mails set it to the language they already translate their content into. This lands in the same release as the `NotifyOptions` change from #3508.\n`MailBranding` for `renderer-simple` can now be localized: `footerText`, `footerLinks[].label` and `footerLinks[].url` take a plain string or a map of locale to string. The renderer picks the exact locale, then the language part (`de-AT` falls back to `de`), then the new optional `MailBranding.defaultLocale`, then the first entry. Every URL in a map must be an absolute http(s) URL, otherwise `createSimpleRenderer` throws at boot. Without a locale and with plain strings the HTML is unchanged.\n`MailBranding` also gets `logoPath` and `baseUrl`, so an app can point at a raster logo on its own origin (`logoPath: \"/logo.png\"`, `baseUrl` the same base as `auth.mail.baseUrl`). `logoPath` and `logoUrl` exclude each other, `logoPath` needs a valid `baseUrl`, must start with a single `/` and must stay on the base origin; violations throw at boot. Use PNG or JPEG, because mail clients block SVG."
-  },
-  {
-    "version": "0.339.0",
-    "type": "improvement",
-    "title": "createRendererSimpleFeature({ mailBranding }) brands every notification mail, including the auth mails, with product name or logo, primary color and footer text and links",
-    "detail": "renderer-simple accepts mailBranding for all framework notification mails",
-    "migration": "No code change needed."
-  }
-]

package/packages/bundled-features/src/renderer-simple/feature.ts

@@ -1,66 +0,0 @@
-import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
-import type { NotificationRenderer } from "../delivery/index.js";
-import {
-  RENDERER_EXTENSION,
-  type RendererContext,
-  RendererError,
-  type RenderRequest,
-  type RenderResponse,
-} from "../renderer-foundation/index.js";
-import { resolveNotificationVariables } from "./resolve-variables.js";
-import { createSimpleRenderer, type MailBranding, simpleRenderer } from "./simple-renderer.js";
-
-// Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
-// NotificationRenderer-Contract), renderer-foundation erwartet
-// `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
-// die simpleRenderer-Implementierung (Template-Strings → HTML mit
-// Inline-CSS) und packt sie in den RendererPlugin-Contract.
-//
-// Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
-export async function adaptToFoundation(
-  req: RenderRequest,
-  ctx: RendererContext,
-  renderer: NotificationRenderer = simpleRenderer,
-): Promise<RenderResponse> {
-  if (req.kind !== "notification") {
-    // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
-    // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
-    throw new RendererError(
-      `renderer-simple supports only kind="notification", got "${req.kind}"`,
-      "invalid_payload",
-    );
-  }
-  const variables = await resolveNotificationVariables(req, ctx);
-  const input = { template: req.payload.template ?? "", variables, locale: req.payload.locale };
-  const html = await renderer.render(input);
-  const text = renderer.renderText ? await renderer.renderText(input) : undefined;
-  return text === undefined ? { kind: "notification", html } : { kind: "notification", html, text };
-}
-
-export type RendererSimpleOptions = {
-  /** Branding applied to every notification mail, including the framework auth mails. */
-  readonly mailBranding?: MailBranding;
-};
-
-export function createRendererSimpleFeature(options?: RendererSimpleOptions): FeatureDefinition {
-  const renderer = options?.mailBranding
-    ? createSimpleRenderer(options.mailBranding)
-    : simpleRenderer;
-  return defineFeature("renderer-simple", (r) => {
-    r.describe(
-      'Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.',
-    );
-    r.uiHints({
-      displayLabel: "Renderer \u00b7 Simple",
-      category: "notifications",
-      recommended: false,
-    });
-    r.requires("renderer-foundation");
-    r.optionalRequires("template-resolver");
-
-    r.useExtension(RENDERER_EXTENSION, "simple", {
-      kinds: ["notification"] as const,
-      render: (req, ctx) => adaptToFoundation(req, ctx, renderer),
-    });
-  });
-}

package/packages/bundled-features/src/renderer-simple/index.ts

@@ -1,8 +0,0 @@
-export { createRendererSimpleFeature, type RendererSimpleOptions } from "./feature.js";
-export type { MailBadge, MailChip, MailStage, MailStageState, MailTone } from "./mail-blocks.js";
-export {
-  createSimpleRenderer,
-  type LocalizedText,
-  type MailBranding,
-  simpleRenderer,
-} from "./simple-renderer.js";

package/packages/bundled-features/src/renderer-simple/mail-blocks.ts

@@ -1,138 +0,0 @@
-import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
-
-export type MailTone = "neutral" | "info" | "success" | "warning" | "danger";
-export type MailStageState = "done" | "current" | "upcoming";
-
-export type MailBadge = { readonly label: string; readonly tone?: MailTone };
-export type MailStage = { readonly label: string; readonly state: MailStageState };
-export type MailChip = { readonly label: string; readonly tone?: MailTone };
-
-// Literal types (as const) keep the colors compile-time known, so they can go into style
-// attributes without escaping.
-const TONE_COLORS = {
-  neutral: { bg: "#f3f4f6", fg: "#374151" },
-  info: { bg: "#dbeafe", fg: "#1e40af" },
-  success: { bg: "#dcfce7", fg: "#166534" },
-  warning: { bg: "#fef3c7", fg: "#92400e" },
-  danger: { bg: "#fee2e2", fg: "#991b1b" },
-} as const satisfies Readonly<Record<MailTone, { readonly bg: string; readonly fg: string }>>;
-
-type ToneColors = (typeof TONE_COLORS)[MailTone];
-type PillMargin = "0" | "0 6px 6px 0";
-
-const STAGE_STATES: readonly MailStageState[] = ["done", "current", "upcoming"];
-const STAGE_DONE_COLOR = "#16a34a";
-const STAGE_UPCOMING_BG = "#e5e7eb";
-const STAGE_UPCOMING_FG = "#9ca3af";
-
-function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
-  return typeof value === "object" && value !== null;
-}
-
-function isMailTone(value: unknown): value is MailTone {
-  return typeof value === "string" && Object.hasOwn(TONE_COLORS, value);
-}
-
-function toneColors(tone: unknown): ToneColors {
-  return TONE_COLORS[isMailTone(tone) ? tone : "neutral"];
-}
-
-function isStageState(value: unknown): value is MailStageState {
-  return STAGE_STATES.some((state) => state === value);
-}
-
-// Template data is runtime data (variables of a stored template): entries that do not match are
-// skipped instead of failing the whole mail.
-function isStage(value: unknown): value is MailStage {
-  return isRecord(value) && typeof value["label"] === "string" && isStageState(value["state"]);
-}
-
-function isChip(value: unknown): value is MailChip {
-  return isRecord(value) && typeof value["label"] === "string";
-}
-
-export function parseBadge(value: unknown): MailBadge | undefined {
-  return isChip(value) && value.label !== "" ? value : undefined;
-}
-
-function validStages(value: unknown): readonly MailStage[] {
-  return Array.isArray(value) ? value.filter(isStage) : [];
-}
-
-function validChips(value: unknown): readonly MailChip[] {
-  return Array.isArray(value) ? value.filter(isChip) : [];
-}
-
-function pill(chip: MailChip, margin: PillMargin): string {
-  const { bg, fg } = toneColors(chip.tone);
-  return `<span style="display:inline-block;margin:${margin};padding:2px 10px;border-radius:999px;background:${bg};color:${fg};font-size:12px;font-weight:600;line-height:18px">${escapeHtml(chip.label)}</span>`;
-}
-
-export function renderBadge(badge: MailBadge): string {
-  return `<p style="margin:0 0 12px">${pill(badge, "0")}</p>`;
-}
-
-export function renderChips(chips: unknown): string {
-  const valid = validChips(chips);
-  if (valid.length === 0) return "";
-  return `<p style="margin:0 0 16px">${valid.map((chip) => pill(chip, "0 6px 6px 0")).join("")}</p>`;
-}
-
-function stageMarker(stage: MailStage, position: number, primaryColor: string): string {
-  const base =
-    "display:inline-block;width:24px;height:24px;line-height:24px;border-radius:12px;text-align:center;font-size:12px;font-weight:700";
-  const primary = escapeHtmlAttr(primaryColor);
-  if (stage.state === "done") {
-    return `<span style="${base};background:${STAGE_DONE_COLOR};color:#fff">&#10003;</span>`;
-  }
-  if (stage.state === "current") {
-    return `<span style="${base};background:#fff;border:2px solid ${primary};line-height:20px;width:20px;height:20px;color:${primary}">${position}</span>`;
-  }
-  return `<span style="${base};background:${STAGE_UPCOMING_BG};color:${STAGE_UPCOMING_FG}">${position}</span>`;
-}
-
-function stageCell(stage: MailStage, position: number, primaryColor: string): string {
-  const labelColor = stage.state === "upcoming" ? STAGE_UPCOMING_FG : "#111";
-  const weight = stage.state === "current" ? 700 : 400;
-  return `<td align="center" valign="top" style="padding:0 4px;font-family:sans-serif">${stageMarker(stage, position, primaryColor)}<div style="margin:4px 0 0;font-size:12px;font-weight:${weight};color:${labelColor}">${escapeHtml(stage.label)}</div></td>`;
-}
-
-function stageConnector(previous: MailStage): string {
-  const color = previous.state === "done" ? STAGE_DONE_COLOR : STAGE_UPCOMING_BG;
-  return `<td valign="top" style="padding:11px 0 0"><div style="width:24px;height:2px;line-height:2px;font-size:2px;background:${color}">&nbsp;</div></td>`;
-}
-
-export function renderStages(stages: unknown, primaryColor: string): string {
-  const valid = validStages(stages);
-  if (valid.length === 0) return "";
-  const cellsHtml = valid
-    .map((stage, index) => {
-      const previous = valid[index - 1];
-      const connector = previous ? stageConnector(previous) : "";
-      return `${connector}${stageCell(stage, index + 1, primaryColor)}`;
-    })
-    .join("");
-  return `<table role="presentation" cellpadding="0" cellspacing="0" border="0" style="margin:0 0 16px"><tr>${cellsHtml}</tr></table>`;
-}
-
-const STAGE_TEXT_MARKER: Readonly<Record<MailStageState, string>> = {
-  done: "✓",
-  current: "▶",
-  upcoming: "○",
-};
-
-export function badgeText(badge: MailBadge): string {
-  return `[${badge.label}]`;
-}
-
-export function stagesText(stages: unknown): string {
-  return validStages(stages)
-    .map((stage) => `${STAGE_TEXT_MARKER[stage.state]} ${stage.label}`)
-    .join(" → ");
-}
-
-export function chipsText(chips: unknown): string {
-  return validChips(chips)
-    .map((chip) => chip.label)
-    .join(" · ");
-}