@cosmicdrift/kumiko-samples 0.363.0 → 0.365.0

package/packages/bundled-features/src/shared/sharp-input-limits.ts

@@ -5,22 +5,21 @@
 // to be an OOM primitive for a single request.
 export const MAX_INPUT_PIXELS = 100_000_000;
 // sequentialRead trades random pixel access for lower peak memory on
-// streamed formats — applied at every decode entry point below since none
-// of them need non-sequential access to the *original* bytes (extract runs
-// against a single already-buffered region per call).
+// streamed formats. Shared by every sharp caller since none of them need
+// non-sequential access to the original bytes.
 export const SHARP_INPUT_OPTIONS = {
   limitInputPixels: MAX_INPUT_PIXELS,
   sequentialRead: true,
 } as const;
 
-// Shared trust boundary for every image byte source this renderer decodes —
-// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
-// alike: a base64 string in a field declaration isn't more trustworthy than
-// an upload just because it came from app code.
+// Shared trust boundary for every image byte source decoded through sharp:
+// uploads, overlay layers and template resources alike. A base64 string in a
+// field declaration isn't more trustworthy than an upload just because it
+// came from app code.
 export function assertNotSvg(format: string | undefined): void {
   if (format === "svg") {
     throw new Error(
-      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+      "SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this code doesn't need to cross.",
     );
   }
 }

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -118,8 +118,8 @@ export type WebhookDispatchDeps = {
   readonly requestTimeoutMs?: number;
 };
 
-// One hanging tenant-controlled receiver must not stall the shared
-// step-dispatcher consumer for every tenant.
+// Bounds a single hanging tenant-controlled receiver to this long. The consumer
+// is sequential and shared, so N hanging requests still delay other tenants by N times this.
 export const WEBHOOK_REQUEST_TIMEOUT_MS = 10_000;
 
 // Never includes the secret name or value — spec.auth.secret is a

package/packages/bundled-features/src/subscription-stripe/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "A stale Stripe customer id no longer turns the customer portal into a 500",
+    "detail": "createPortalSession now maps Stripe's \"No such customer\" rejection (account switch, customer deleted in the dashboard) to an UnprocessableError with the i18n key billing-foundation.errors.providerCustomerUnknown, translated in German and Spanish, instead of letting the raw Stripe error surface as a server error."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",

package/packages/bundled-features/src/subscription-stripe/plugin-methods.ts

@@ -109,12 +109,10 @@ export function mapAppLocaleToStripeLocale(
   return knownLocales.find((known) => known === language) ?? "auto";
 }
 
-function isUnknownCustomerStripeError(error: unknown): boolean {
-  return (
-    isResourceMissingStripeError(error) &&
-    error instanceof Stripe.errors.StripeInvalidRequestError &&
-    error.param === "customer"
-  );
+function isUnknownCustomerStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
+  return isResourceMissingStripeError(error) && error.param === "customer";
 }
 
 export function createStripeCheckoutSession(
@@ -203,11 +201,21 @@ export type StripePortalOptions = Parameters<
 export function createStripePortalSession(runtime: StripeCtxRuntime) {
   return async (ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
     const stripe = await runtime.clientForCtx(ctx);
-    const session = await stripe.billingPortal.sessions.create({
-      customer: options.providerCustomerId,
-      return_url: options.returnUrl,
-    });
-    return { url: session.url };
+    try {
+      const session = await stripe.billingPortal.sessions.create({
+        customer: options.providerCustomerId,
+        return_url: options.returnUrl,
+      });
+      return { url: session.url };
+    } catch (error) {
+      // A portal needs an existing customer, so unlike checkout there is no retry without one.
+      if (!isUnknownCustomerStripeError(error)) throw error;
+      throw new UnprocessableError("provider_customer_unknown", {
+        i18nKey: "billing-foundation.errors.providerCustomerUnknown",
+        message: `subscription-stripe: Stripe does not know customer "${options.providerCustomerId}" (account switch or customer deleted).`,
+        cause: error,
+      });
+    }
   };
 }
 

package/packages/bundled-features/src/subscription-stripe/verify-webhook.ts

@@ -54,7 +54,9 @@ import type { StripeWebhookRuntime } from "./runtime.js";
 
 const log = createFallbackLogger("subscription-stripe");
 
-export function isResourceMissingStripeError(error: unknown): boolean {
+export function isResourceMissingStripeError(
+  error: unknown,
+): error is Stripe.errors.StripeInvalidRequestError {
   return (
     error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing"
   );

package/packages/bundled-features/src/template-resolver/README.md

@@ -50,7 +50,7 @@ async function someHandler(ctx) {
 
 | kind | contentFormat | meta |
 |---|---|---|
-| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `sender` |
+| `mail` | `html` (Dokument-Schema, wird serverseitig neu aufgebaut) | Pflicht: `subject`; optional `previewText`, `layoutSlug`, `category` (`transactional`/`marketing`), `senderName`, `replyTo` |
 | `mail-layout` | `mjml` | leer (`{}`) oder fehlend |
 | `pdf-layout` | `html` | leer (`{}`) oder fehlend |
 | `document-pdf` | `html` | fehlt |
@@ -137,10 +137,12 @@ upsertSystem  ──┐
                 ├──► status: "active" (System-Default sofort aktiv)
 upsertTenant  ──┴──► status: "draft" (Default) | "active" (explizit)
 
-publish ───────► status: "active"
+publish ───────► status: "active" (übernimmt einen offenen Entwurf)
 archive ───────► status: "archived"
+discardDraft ──► verwirft den Entwurf neben der aktiven Fassung
 ```
 
+Ein Entwurf über einer aktiven Zeile (`upsertTenant` ohne `status`, `copy-locale`, `import-bundle`) liegt als JSON in `draft` neben der Zeile; die Hauptfelder bleiben die ausgelieferte Fassung. `find-by-id` und `layout-source` liefern die Arbeitsfassung (Entwurf, sonst gespeichert) mit `active { version, since }`.
 Resolver returnt **nur** Templates mit `status: "active"`. draft/archived werden ignoriert.
 
 ## Consumer Conformance

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

@@ -18,6 +18,7 @@ import {
   type TemplatePdfAttachmentLink,
 } from "./linked-resources.js";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.js";
+import { activeVersionOf, servedVersionOf } from "./template-draft.js";
 import { parseTemplateMeta, type TemplateMeta } from "./template-meta.js";
 
 // Public TemplateResource: what consumers see. Hides DB-internal columns
@@ -161,7 +162,7 @@ function pickActiveLayoutRow(
 ): TemplateResourceRow | null {
   const active = rows
     .filter((row) => row.status === "active")
-    .sort((a, b) => b.version - a.version || a.locale.localeCompare(b.locale));
+    .sort((a, b) => activeVersionOf(b) - activeVersionOf(a) || a.locale.localeCompare(b.locale));
   return (
     active.find((row) => row.locale === locale) ??
     active.find((row) => row.locale === FALLBACK_LOCALE) ??
@@ -202,7 +203,7 @@ function toPublic(row: TemplateResourceRow): TemplateResource {
   const linkedEntries = parseLinkedResourceEntries(row.linkedResources);
   return {
     id: String(row.id),
-    version: row.version,
+    version: servedVersionOf(row),
     tenantId: row.tenantId,
     slug: row.slug,
     kind,

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

@@ -1,4 +1,153 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "copy-locale copies the system default's files in a beforeTransaction phase and can no longer run as a nested write",
+    "detail": "When a tenant copies a locale from the system default, the image and attachment files are now read and written to the tenant's storage in a beforeTransaction phase. The transaction only creates the fileRef rows, and the uploaded binaries are released when it does not commit. Before, the storage I/O held the database transaction open.",
+    "migration": "Dispatch copy-locale as a top-level command, or from a perCommand handler via ctx.write. A handler that called it nested moves that call into a client or job, or becomes a perCommand handler."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Opening a document or mail editor with an empty body no longer marks the form as changed",
+    "detail": "Switching the editor's editable state on mount emitted an update, so DocumentTiptapEditor called onChange(\"<p></p>\") before the user typed anything and the surrounding form counted as dirty."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "onEditorReady receives null when the editor is destroyed",
+    "detail": "DocumentTiptapEditor and PlaceholderLineEditor call onEditorReady(null) on destroy, so a held handle no longer points at a destroyed editor. The callback type is (handle: DocumentEditorHandle | null) => void. The document designer drops the handle of an unmounted field, so placeholder insertion no longer targets a destroyed editor.",
+    "migration": "A custom onEditorReady callback must accept null and drop its stored handle when it receives it."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Document editor no longer blanks the app when late placeholders rebuild it",
+    "detail": "When the system placeholders or resource previews arrived in the same render as a new value (layout editor after opening or saving), the editor rebuilt itself and the value sync then read the destroyed editor. The TypeError unmounted the whole app and left a blank page. Both sync effects now skip a destroyed editor; the replacement editor picks up the value on its next render."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Steps block in mail and PDF templates",
+    "detail": "The document editor offers a steps block in the toolbar block menu. It stores a fixed list of stages (value=label, at most 8) and the variable that names the current stage. Mail and PDF render it as a row of bars and labels; stages up to the current one are coloured, the current label is bold. Invalid blocks are dropped by the sanitizer and render nothing. Layout regions do not offer the block."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A paragraph or heading that only holds an empty placeholder is left out of the rendered document",
+    "detail": "compileDocumentBodyToHandlebars wraps a p or h1 to h4 whose only content is one placeholder in an if block, so an empty optional value no longer leaves a blank line in mails and PDFs. Zero numbers and money values still render. Blocks with static text, images or several placeholders are unchanged."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Mail layout buttons follow the branding accent colour",
+    "detail": "mailLayoutAppearance takes the tenant branding accent colour. When the layout uses the branding accent line, buttons in the mail body use that colour instead of the fixed dark teal. Invalid colours fall back to the previous default."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A placeholder inside a button label is kept",
+    "detail": "The document schema allows placeholder chips inside a button label. Before, saving or seeding a body such as a button reading \"View {{pageName}}\" split the button: the label stopped at the placeholder and the rest landed in a new paragraph outside the button."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "compileDocumentBodyToHandlebars takes a height cap for resource images",
+    "detail": "The new resourceImageMaxHeightPx option adds max-height and width:auto to resource images. The mail renderer caps images in a layout header at 64 px, so a square logo stays small while a wide wordmark keeps its 180 px width cap."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "resource-upload refuses key collisions between images and attachments and linking a non-active PDF template",
+    "detail": "Uploading an attachment under a key that holds an inline image, or an image under a key that holds an attachment or linked PDF, fails with template_attachment_invalid (code key_in_use) instead of silently replacing the entry. resource-link-pdf only accepts an active document-pdf template, so draft or archived templates no longer produce mails that fail at send time. When the link write fails after the file was stored, the orphaned storage object is deleted."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "collection kinds fail at boot; validate, diff-to-system, overview, seeding, bundle import and placeholder checks follow the write rules",
+    "detail": "createTemplateResolverFeature throws for a collection whose kind is mail, mail-layout or pdf-layout instead of failing on every save. The validate query ignores scope system for non-SystemAdmins. diff-to-system compares only against an active system template like reset-to-system. The overview reads rows in a stable order and reports truncated when its row limit is hit. Re-seeding notification templates reactivates an archived system row and applies a changed parentTemplateId. A bundle holds at most 50 locales. Dotted placeholders under a declared variable or list item field are reported as unknown because they never render a value. The document editor fallbacks are read-only and the placeholder line editor recolors chips when systemVariables change."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Resource image formats come from one list",
+    "detail": "PNG, JPEG, GIF and WebP content types and extensions are defined once in the shared module and reused by the resource upload, the document body compiler and the email channel."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "resource-upload, import-bundle and import-bundle-system upload in a beforeTransaction phase and can no longer run as nested writes",
+    "detail": "The three handlers now validate and upload their files before the write transaction opens and only create the fileRef and template rows inside it, so no database connection sits idle in a transaction during storage I/O. A rolled-back transaction releases the uploaded bytes. Because they now have a pre-transaction phase, the dispatcher rejects a nested ctx.write, ctx.writeAs or handler-to-handler call of them (\"has a pre-transaction phase\"). The exported storeTemplateResource is replaced by prepareTemplateResourceBeforeTransaction (beforeTransaction half) and storePreparedTemplateResource (in-transaction half).",
+    "migration": "Dispatch resource-upload, import-bundle and import-bundle-system as top-level commands, or from a perCommand handler via ctx.write. A handler that called them nested moves that call into a client or job, or becomes a perCommand handler. Code that called storeTemplateResource calls prepareTemplateResourceBeforeTransaction in a beforeTransaction phase and passes the result to storePreparedTemplateResource in the handler."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "PDF collections show Page break instead of Button, and placeholder links no longer insert {{name}} text",
+    "detail": "The content editor for a `document-pdf` collection now offers the PDF block set (including Page break) instead of the mail set, chosen from the collection's kind. A link to a placeholder href such as `{{invoice.url}}` without a selection now links a variable node instead of inserting the placeholder as plain text."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Document sanitizer rejects prototype-style placeholder hrefs",
+    "detail": "`{{__proto__}}` and `{{constructor.prototype}}` are no longer accepted as link or button placeholder hrefs; only valid reference names pass."
+  },
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "DocumentRepeatRow is removed, use DocumentTableRow",
+    "detail": "Removed the DocumentRepeatRow alias",
+    "migration": "Replace `DocumentRepeatRow` with `DocumentTableRow` (identical shape)."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "export-bundle for a system template with resources returns a validation error outside the system tenant",
+    "detail": "A TenantAdmin, or a SystemAdmin outside the system tenant, exporting a system template that links resource files now gets the `system_resources_need_system_tenant` validation error, the same code import-bundle-system uses, instead of a NotFound for the resource file."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "send-test logs failed test mails with error class and tenant",
+    "detail": "A transport that throws or reports not sent is logged with the error class/code and tenant id (no address, no provider body) and still answers `template_test_mail_failed`."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "copy-locale ignores archived tenant sources and duplicates linked files of system sources; export-bundle refuses locales with differing format",
+    "detail": "copy-locale no longer copies from an archived tenant template, and copying a system template duplicates its linked resource files into the target tenant. export-bundle rejects a bundle whose locales differ in content format or variable schema with `bundleLocalesDiffer`."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Template preview counts encoding overhead and reports missing attachments",
+    "detail": "The mail size estimate counts base64 size plus a fixed per-part overhead, an attachment whose file reference is missing fails the resources_resolved check, and the document draft scope is derived once per request."
+  },
+  {
+    "version": "0.364.0",
+    "type": "breaking",
+    "title": "A draft no longer replaces the active template",
+    "detail": "Saving a draft (upsert-tenant default, copy-locale, import-bundle with status draft) over an active template stores it beside the active version in the new column draft instead of overwriting content, meta and status; resolveTemplate, resolveLayout, preview without content and sends keep using the active version. publish and publish-system promote an open draft (the publish gate checks the draft) and record activeVersion and activeSince; the new handlers discard-draft and discard-draft-system drop it and refuse with no_draft when none is open. find-by-id and layout-source return the working version (the open draft with status draft, else the stored one) plus active { version, since }, null when nothing is served. overview keeps status and version of the served version and adds draftVersion and activeSince. A draft over a row that is not active (new, draft or archived) behaves as before. A tenant never sees system draft content: find-by-id, layout-source, overview, copy-locale and diff-to-system apply a system draft only for a SystemAdmin and hide system rows that were never served; list leaves those rows out too. Version numbers shown for an active row are the served version (activeVersion): resolveTemplate / resolveLayout results, tenant-overrides rows and the override diff no longer show the save counter that drafts raise.",
+    "migration": "Run kumiko schema generate and apply the migration before deploying: it adds the nullable columns draft, active_version and active_since to read_template_resources. No rebuild needed."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "template-resolver:query:overview accepts layoutSlug to list only the mails and PDFs using that layout",
+    "detail": "The optional layoutSlug payload field keeps only documents whose layout slug matches; total counts the filtered rows. Without it the response is unchanged."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "Layout usage follows the effective template per notification and locale",
+    "detail": "Mail layout usage counts a notification only when it declares a template and resolves the effective row per notification and locale, so tenant overrides are reflected."
+  },
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "templateVariable.richText for notification variables that carry formatted HTML",
+    "detail": "Notification variables are escaped, so a value holding HTML (for example a document written in a rich text editor) showed up as literal tags in the mail. A variable declared with templateVariable.richText({ required }) is run through the document sanitizer at render time and inserted as HTML; bold, italic, lists and safe links stay, script, event handlers and javascript links are not emitted as markup. If the sanitizer rejects a value, it is rendered as escaped text and a warning with the violation codes is logged. All other variable types stay escaped."
+  },
   {
     "version": "0.363.0",
     "type": "improvement",

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

@@ -1,6 +1,8 @@
 import type { TemplateVariableDef, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
 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 {
   DOCUMENT_TEXT_ALIGNMENTS,
@@ -60,6 +62,7 @@ function resolveReference(
 function valueExpression(path: string, def: TemplateVariableDef | undefined): string {
   if (def?.type === "money") return `{{money ${path}}}`;
   if (def?.type === "date") return `{{date ${path}}}`;
+  if (def?.type === "richText") return `{{richText ${path}}}`;
   return `{{${path}}}`;
 }
 
@@ -82,6 +85,39 @@ function pathAndDef(
   return [path, def];
 }
 
+const VARIABLE_ONLY_BLOCK_SELECTOR = "p, h1, h2, h3, h4";
+
+function soleVariableName(block: ScanElement): string | null {
+  const names = new Set(
+    Array.from(block.querySelectorAll("span[data-variable]")).map(
+      (span) => span.getAttribute("data-variable") ?? "",
+    ),
+  );
+  const [name] = [...names];
+  if (names.size !== 1 || name === undefined || !isDocumentReferenceName(name)) return null;
+  const withoutVariables = block.cloneNode(true);
+  for (const span of Array.from(withoutVariables.querySelectorAll("span[data-variable]"))) {
+    span.remove();
+  }
+  const hasStaticContent =
+    (withoutVariables.textContent ?? "").trim() !== "" ||
+    withoutVariables.querySelector("img") !== null;
+  return hasStaticContent ? null : name;
+}
+
+// A line that holds nothing but one optional placeholder would otherwise leave
+// an empty paragraph (a visible gap) when the value is missing. includeZero
+// keeps an amount of 0.
+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}}")));
+}
+
 function rewriteLink(element: ScanElement, state: CompileState): void {
   const href = element.getAttribute("href") ?? "";
   if (isDocumentPlaceholderHref(href)) {
@@ -123,16 +159,43 @@ function neutralizeBraces(html: string): string {
 export type CompileDocumentBodyOptions = {
   // Returns the src for an `img[data-resource]` key; undefined drops the image.
   readonly resourceSrc?: (key: string) => string | undefined;
+  // Mail clients ignore document CSS, so a full-width logo needs an inline width cap.
+  readonly resourceImageMaxWidthPx?: number;
+  // Keeps a square logo in a mail header from growing to the full width cap.
+  readonly resourceImageMaxHeightPx?: number;
   // Mail clients ignore document CSS, so mail turns data-align into an inline style.
   readonly alignmentAsInlineStyle?: boolean;
+  // Same reason: a[data-button] only looks like a button through editor/print CSS.
+  readonly buttonAsInlineStyle?: boolean;
+  // Same reason: cell padding and table width only exist in editor/print CSS, so without
+  // inline styles a mail table renders its cells flush against each other.
+  readonly tableAsInlineStyle?: boolean;
+  // Replaces the default button look; only values from the layout appearance belong here.
+  readonly buttonInlineStyle?: string;
+  // Mail clients ignore document CSS, so headings get their size and weight inline.
+  readonly headingAsInlineStyle?: boolean;
+  // Bar color of reached stages in a steps block; ignored unless it is a #rrggbb hex.
+  readonly stepsColor?: string;
+};
+
+const MAIL_BUTTON_STYLE =
+  "display:inline-block;padding:10px 20px;border-radius:6px;background-color:#1f5468;color:#ffffff;font-weight:600;text-decoration:none";
+
+const MAIL_TABLE_STYLE = "width:100%;border-collapse:collapse";
+const MAIL_TABLE_CELL_STYLE = "padding:6px 12px;vertical-align:top;border-bottom:1px solid #e5e5e5";
+const MAIL_TABLE_HEAD_STYLE = "font-size:12px;font-weight:600;color:#6b7280;text-align:left";
+const MAIL_SMALL_STYLE = "font-size:13px;color:#4A515E";
+const MAIL_HEADING_STYLES: Readonly<Record<string, string>> = {
+  h1: "margin:0 0 12px 0;font-size:30px;line-height:1.15;font-weight:700;letter-spacing:-0.035em;color:#0B0D12",
+  h2: "margin:0 0 12px 0;font-size:24px;line-height:1.2;font-weight:700;letter-spacing:-0.02em;color:#0B0D12",
+  h3: "margin:20px 0 8px 0;font-size:17px;line-height:1.3;font-weight:600;color:#0B0D12",
 };
 
-const RESOURCE_IMAGE_CONTENT_TYPES: ReadonlySet<string> = new Set([
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp",
-]);
+// Appended after an existing style (data-align) so the alignment survives.
+function appendStyle(element: ScanElement, style: string): void {
+  const existing = element.getAttribute("style");
+  element.setAttribute("style", existing === null ? style : `${existing};${style}`);
+}
 
 // Unique valid resource keys in document order.
 export function collectDocumentResourceKeys(html: string): readonly string[] {
@@ -147,7 +210,7 @@ export function collectDocumentResourceKeys(html: string): readonly string[] {
 }
 
 export function toResourceDataUri(contentType: string, bytes: Uint8Array): string {
-  if (!RESOURCE_IMAGE_CONTENT_TYPES.has(contentType)) {
+  if (!isResourceImageContentType(contentType)) {
     throw new Error(`resource content type "${contentType}" cannot be embedded as an image`);
   }
   return `data:${contentType};base64,${Buffer.from(bytes).toString("base64")}`;
@@ -163,6 +226,8 @@ function rewriteAlignment(element: ScanElement): void {
 function rewriteResourceImage(
   element: ScanElement,
   resourceSrc: CompileDocumentBodyOptions["resourceSrc"],
+  maxWidthPx: number | undefined,
+  maxHeightPx: number | undefined,
 ): void {
   const key = element.getAttribute("data-resource") ?? "";
   const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
@@ -173,6 +238,69 @@ function rewriteResourceImage(
   }
   element.setAttribute("src", src);
   element.removeAttribute("data-resource");
+  const caps = [
+    ...(maxWidthPx === undefined ? [] : [`max-width:${maxWidthPx}px`]),
+    ...(maxHeightPx === undefined ? [] : [`max-height:${maxHeightPx}px;width:auto`]),
+  ];
+  if (caps.length > 0) element.setAttribute("style", `${caps.join(";")};height:auto`);
+}
+
+function stripScriptsAndActiveContent(
+  root: ScanElement,
+  options: CompileDocumentBodyOptions,
+): void {
+  for (const element of Array.from(root.querySelectorAll("script"))) element.remove();
+  for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
+    rewriteResourceImage(
+      element,
+      options.resourceSrc,
+      options.resourceImageMaxWidthPx,
+      options.resourceImageMaxHeightPx,
+    );
+  }
+  for (const element of Array.from(root.querySelectorAll("*"))) stripActiveContent(element);
+}
+
+function applyAlignmentInlineStyles(root: ScanElement): void {
+  for (const element of Array.from(root.querySelectorAll("[data-align]"))) {
+    rewriteAlignment(element);
+  }
+  for (const element of Array.from(root.querySelectorAll("[data-size]"))) {
+    element.removeAttribute("data-size");
+    appendStyle(element, MAIL_SMALL_STYLE);
+  }
+}
+
+function applyHeadingInlineStyles(root: ScanElement): void {
+  for (const heading of Array.from(root.querySelectorAll("h1, h2, h3"))) {
+    const style = MAIL_HEADING_STYLES[heading.tagName.toLowerCase()];
+    if (style !== undefined) appendStyle(heading, style);
+  }
+}
+
+function applyTableInlineStyles(root: ScanElement): void {
+  for (const table of Array.from(root.querySelectorAll("table"))) {
+    appendStyle(table, MAIL_TABLE_STYLE);
+  }
+  for (const cell of Array.from(root.querySelectorAll("td, th"))) {
+    appendStyle(cell, MAIL_TABLE_CELL_STYLE);
+  }
+  for (const head of Array.from(root.querySelectorAll("th"))) {
+    appendStyle(head, MAIL_TABLE_HEAD_STYLE);
+  }
+}
+
+function rewriteLinks(
+  root: ScanElement,
+  state: CompileState,
+  options: CompileDocumentBodyOptions,
+): void {
+  for (const element of Array.from(root.querySelectorAll("a[href]"))) {
+    rewriteLink(element, state);
+    if (options.buttonAsInlineStyle === true && element.hasAttribute("data-button")) {
+      element.setAttribute("style", options.buttonInlineStyle ?? MAIL_BUTTON_STYLE);
+    }
+  }
 }
 
 // Turns a sanitized document body into Handlebars source. Rows and links are
@@ -186,22 +314,24 @@ export function compileDocumentBodyToHandlebars(
   const state: CompileState = { variables, expressions: [] };
   const scrubbed = html.replaceAll(EXPRESSION_OPEN, "").replaceAll(EXPRESSION_CLOSE, "");
   const compiled = withParsedDocument(scrubbed, (root) => {
-    for (const element of Array.from(root.querySelectorAll("script"))) element.remove();
-    for (const element of Array.from(root.querySelectorAll("img[data-resource]"))) {
-      rewriteResourceImage(element, options.resourceSrc);
+    stripScriptsAndActiveContent(root, options);
+    if (options.alignmentAsInlineStyle === true) applyAlignmentInlineStyles(root);
+    if (options.headingAsInlineStyle === true) applyHeadingInlineStyles(root);
+    if (options.tableAsInlineStyle === true) applyTableInlineStyles(root);
+    for (const element of Array.from(root.querySelectorAll("div[data-steps]"))) {
+      rewriteStepsBlock(element, {
+        expression: (source) => marker(state, source),
+        pathOf: (name, at) => pathAndDef(name, at, state)[0],
+        color: options.stepsColor,
+      });
     }
-    for (const element of Array.from(root.querySelectorAll("*"))) stripActiveContent(element);
-    if (options.alignmentAsInlineStyle === true) {
-      for (const element of Array.from(root.querySelectorAll("[data-align]"))) {
-        rewriteAlignment(element);
-      }
+    for (const block of Array.from(root.querySelectorAll(VARIABLE_ONLY_BLOCK_SELECTOR))) {
+      wrapVariableOnlyBlock(block, state);
     }
     for (const element of Array.from(root.querySelectorAll("span[data-variable]"))) {
       rewriteVariable(element, state);
     }
-    for (const element of Array.from(root.querySelectorAll("a[href]"))) {
-      rewriteLink(element, state);
-    }
+    rewriteLinks(root, state, options);
     for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
       rewriteRepeatRow(element, state);
     }

package/packages/bundled-features/src/template-resolver/compile-steps-block.ts

@@ -0,0 +1,68 @@
+import type { Element as ScanElement } from "happy-dom";
+import { isDocumentReferenceName } from "./document-schema.js";
+import { readDocumentSteps } from "./document-steps.js";
+import { isHexColor } from "./layout-appearance.js";
+
+export const DEFAULT_STEPS_COLOR = "#1f5468";
+const TODO_BAR_COLOR = "#ECEDEA";
+const REACHED_LABEL_COLOR = "#0B0D12";
+const TODO_LABEL_COLOR = "#5A6170";
+
+export type StepsCompileHooks = {
+  /** Registers a Handlebars expression and returns the marker that stands for it. */
+  readonly expression: (source: string) => string;
+  /** Resolves a variable name to its Handlebars path at the element's position. */
+  readonly pathOf: (name: string, element: ScanElement) => string;
+  readonly color: string | undefined;
+};
+
+// Inline-styled table in every output (mail, PDF, preview): mail clients ignore
+// document CSS, and one rendering keeps the three outputs identical. The labels
+// stay static text; only the reached/current switch is a Handlebars block, and
+// its arguments are a validated path and validated keys.
+export function rewriteStepsBlock(element: ScanElement, hooks: StepsCompileHooks): void {
+  const name = element.getAttribute("data-steps") ?? "";
+  const steps = readDocumentSteps(element);
+  if (!isDocumentReferenceName(name) || steps === null) {
+    element.remove();
+    // skip: an invalid steps block renders nothing
+    return;
+  }
+  const path = hooks.pathOf(name, element);
+  const keys = steps.map((step) => step.key).join(",");
+  const color =
+    hooks.color !== undefined && isHexColor(hooks.color) ? hooks.color : DEFAULT_STEPS_COLOR;
+  const when = (index: number, state: "reached" | "current", yes: string, no: string): string =>
+    `${hooks.expression(`{{#stepIs ${path} ${index} "${keys}" "${state}"}}`)}${yes}${hooks.expression("{{else}}")}${no}${hooks.expression("{{/stepIs}}")}`;
+
+  const document = element.ownerDocument;
+  const table = document.createElement("table");
+  table.setAttribute("role", "presentation");
+  table.setAttribute("width", "100%");
+  table.setAttribute("cellpadding", "0");
+  table.setAttribute("cellspacing", "0");
+  table.setAttribute("style", "table-layout:fixed;border-collapse:collapse;margin:4px 0 24px 0");
+  const row = document.createElement("tr");
+  steps.forEach((step, index) => {
+    const cell = document.createElement("td");
+    cell.setAttribute(
+      "style",
+      `padding:0 ${index === steps.length - 1 ? 0 : 4}px 0 0;vertical-align:top`,
+    );
+    const bar = document.createElement("div");
+    bar.setAttribute(
+      "style",
+      `height:4px;line-height:4px;font-size:0;border-radius:2px;background-color:${when(index, "reached", color, TODO_BAR_COLOR)}`,
+    );
+    const label = document.createElement("div");
+    label.setAttribute(
+      "style",
+      `padding-top:8px;font-size:12px;line-height:1.3;color:${when(index, "reached", REACHED_LABEL_COLOR, TODO_LABEL_COLOR)};font-weight:${when(index, "current", "600", "400")}`,
+    );
+    label.textContent = step.label;
+    cell.append(bar, label);
+    row.append(cell);
+  });
+  table.append(row);
+  element.replaceWith(table);
+}