@cosmicdrift/kumiko-samples 0.364.0 → 0.365.0

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,
@@ -83,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)) {
@@ -126,6 +161,8 @@ export type CompileDocumentBodyOptions = {
   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.
@@ -135,6 +172,10 @@ export type CompileDocumentBodyOptions = {
   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 =
@@ -143,7 +184,12 @@ const MAIL_BUTTON_STYLE =
 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:12px;color:#6b7280";
+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",
+};
 
 // Appended after an existing style (data-align) so the alignment survives.
 function appendStyle(element: ScanElement, style: string): void {
@@ -151,13 +197,6 @@ function appendStyle(element: ScanElement, style: string): void {
   element.setAttribute("style", existing === null ? style : `${existing};${style}`);
 }
 
-const RESOURCE_IMAGE_CONTENT_TYPES: ReadonlySet<string> = new Set([
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp",
-]);
-
 // Unique valid resource keys in document order.
 export function collectDocumentResourceKeys(html: string): readonly string[] {
   return withParsedDocument(html, (root) => {
@@ -171,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")}`;
@@ -188,6 +227,7 @@ 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;
@@ -198,8 +238,11 @@ function rewriteResourceImage(
   }
   element.setAttribute("src", src);
   element.removeAttribute("data-resource");
-  if (maxWidthPx !== undefined)
-    element.setAttribute("style", `max-width:${maxWidthPx}px;height:auto`);
+  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(
@@ -208,7 +251,12 @@ function stripScriptsAndActiveContent(
 ): 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);
+    rewriteResourceImage(
+      element,
+      options.resourceSrc,
+      options.resourceImageMaxWidthPx,
+      options.resourceImageMaxHeightPx,
+    );
   }
   for (const element of Array.from(root.querySelectorAll("*"))) stripActiveContent(element);
 }
@@ -223,6 +271,13 @@ function applyAlignmentInlineStyles(root: ScanElement): void {
   }
 }
 
+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);
@@ -261,7 +316,18 @@ export function compileDocumentBodyToHandlebars(
   const compiled = withParsedDocument(scrubbed, (root) => {
     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 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);
     }

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);
+}

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

@@ -51,7 +51,15 @@ export const TEXT_BLOCK_KIND = "text-block" as const;
 // Kinds a content collection must not write: a tenant row of these kinds would
 // shadow the system notification template or layout without the meta and
 // placeholder gates that upsertTenant applies.
-export const COLLECTION_REFUSED_KINDS: readonly string[] = ["mail", "mail-layout", "pdf-layout"];
+export const COLLECTION_REFUSED_KINDS = [
+  "mail",
+  "mail-layout",
+  "pdf-layout",
+] as const satisfies readonly TemplateKind[];
+
+export function isCollectionRefusedKind(kind: string): boolean {
+  return COLLECTION_REFUSED_KINDS.some((refused) => refused === kind);
+}
 
 export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"] as const;
 export type ContentFormat = (typeof CONTENT_FORMATS)[number];
@@ -61,6 +69,7 @@ export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
 
 export const TEMPLATE_STATUSES = ["draft", "active", "archived"] as const;
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
+export const ACTIVE_TEMPLATE_STATUS = "active" satisfies TemplateStatus;
 
 export {
   PDF_DEFAULT_MARGIN_MM,
@@ -76,6 +85,7 @@ export {
 export const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
 
 export const DEFAULT_MAIL_LAYOUT_SLUG = "default";
+export const DEFAULT_PDF_LAYOUT_SLUG = "default";
 
 // The mail transport enforces no size limit of its own; 10 MiB is a common provider ceiling.
 export const MAIL_PREVIEW_MAX_BYTES = 10 * 1024 * 1024;

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

@@ -13,6 +13,7 @@ import {
   isDocumentReferenceName,
   isDocumentResourceKey,
 } from "./document-schema.js";
+import { isDocumentStepKey } from "./document-steps.js";
 
 export type DocumentViolationCode =
   | "script_element"
@@ -138,6 +139,8 @@ const REFERENCE_ATTRIBUTES: ReadonlyArray<readonly [string, (value: string) => b
   ["data-variable", isDocumentReferenceName],
   ["data-each", isDocumentReferenceName],
   ["data-resource", isDocumentResourceKey],
+  ["data-steps", isDocumentReferenceName],
+  ["data-step", isDocumentStepKey],
 ];
 
 function scanReferences(tag: string, element: ScanElement, out: DocumentViolation[]): void {

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

@@ -8,6 +8,7 @@ import { Extension, type Extensions, Node } from "@tiptap/core";
 import { Link } from "@tiptap/extension-link";
 import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
 import StarterKit from "@tiptap/starter-kit";
+import { createDocumentStepsNode } from "./document-steps.js";
 
 const PLACEHOLDER_HREF = /^\{\{(.+)\}\}$/;
 const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
@@ -71,6 +72,7 @@ export const DOCUMENT_NODE_NAMES = [
   "button",
   "divider",
   "pageBreak",
+  "steps",
 ] as const;
 
 export const DocumentVariable = Node.create({
@@ -131,7 +133,8 @@ export const DocumentResource = Node.create({
 export const DocumentButton = Node.create({
   name: "button",
   group: "block",
-  content: "text*",
+  // A placeholder in the label ("View {{pageName}}") must survive the round trip.
+  content: "(text | variable)*",
   marks: "",
   defining: true,
   addAttributes() {
@@ -179,6 +182,8 @@ export const DocumentPageBreak = Node.create({
   },
 });
 
+export const DocumentSteps = createDocumentStepsNode(isDocumentReferenceName);
+
 // A repeat row is a table row carrying `each`: prosemirror-tables requires
 // the tableRow node type, so a separate node type is not an option.
 export const DocumentTableRow = TableRow.extend({
@@ -340,6 +345,7 @@ export const documentExtensions: Extensions = [
   DocumentButton,
   DocumentDivider,
   DocumentPageBreak,
+  DocumentSteps,
   DocumentTextAlign,
   DocumentTextSize,
 ];

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

@@ -0,0 +1,114 @@
+// @runtime client
+// A progress row: fixed stages stored in the template, the reached stage read
+// from a variable at render time. Universal like document-schema.ts.
+import { Node } from "@tiptap/core";
+
+// Keys end up as Handlebars string literals in the compiled body, so they are
+// restricted to characters that cannot close or escape a literal.
+const STEP_KEY = /^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$/;
+export const DOCUMENT_STEPS_MAX = 8;
+const STEP_LABEL_MAX_LENGTH = 40;
+
+export type DocumentStep = { readonly key: string; readonly label: string };
+
+export function isDocumentStepKey(value: string): boolean {
+  return STEP_KEY.test(value);
+}
+
+export function documentStepKeyOf(label: string): string {
+  return label
+    .normalize("NFKD")
+    .replace(/\p{M}/gu, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+// Editor input: "value=Label" entries separated by commas; a bare label derives its value.
+export function parseDocumentStepsInput(text: string): readonly DocumentStep[] | null {
+  const steps = text
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "")
+    .map((entry): DocumentStep => {
+      const separator = entry.indexOf("=");
+      const label = (separator < 0 ? entry : entry.slice(separator + 1)).trim();
+      const key = separator < 0 ? documentStepKeyOf(entry) : entry.slice(0, separator).trim();
+      return { key, label: label.slice(0, STEP_LABEL_MAX_LENGTH) };
+    });
+  return areValidSteps(steps) ? steps : null;
+}
+
+function areValidSteps(steps: readonly DocumentStep[]): boolean {
+  return (
+    steps.length > 0 &&
+    steps.length <= DOCUMENT_STEPS_MAX &&
+    new Set(steps.map((step) => step.key)).size === steps.length &&
+    steps.every((step) => isDocumentStepKey(step.key) && step.label !== "")
+  );
+}
+
+// Duplicate or invalid keys would make the reached stage ambiguous, so the whole
+// list is refused rather than repaired.
+export function readDocumentSteps(element: {
+  querySelectorAll(selector: string): ArrayLike<{
+    getAttribute(name: string): string | null;
+    textContent: string | null;
+  }>;
+}): readonly DocumentStep[] | null {
+  const steps = Array.from(element.querySelectorAll("span[data-step]")).map((span) => ({
+    key: span.getAttribute("data-step") ?? "",
+    label: (span.textContent ?? "").trim().slice(0, STEP_LABEL_MAX_LENGTH),
+  }));
+  return areValidSteps(steps) ? steps : null;
+}
+
+function isDocumentStep(step: unknown): step is DocumentStep {
+  return (
+    typeof step === "object" &&
+    step !== null &&
+    "key" in step &&
+    "label" in step &&
+    typeof step.key === "string" &&
+    typeof step.label === "string"
+  );
+}
+
+// Node attrs are untyped JSON; anything that is not a step entry is dropped.
+export function readDocumentStepsAttribute(value: unknown): readonly DocumentStep[] {
+  return Array.isArray(value) ? value.filter(isDocumentStep) : [];
+}
+
+export function createDocumentStepsNode(isReferenceName: (value: string) => boolean) {
+  return Node.create({
+    name: "steps",
+    group: "block",
+    atom: true,
+    addAttributes() {
+      return { variable: { default: null }, steps: { default: [] } };
+    },
+    parseHTML() {
+      return [
+        {
+          tag: "div[data-steps]",
+          getAttrs: (element) => {
+            const variable = element.getAttribute("data-steps");
+            const steps = readDocumentSteps(element);
+            if (variable === null || !isReferenceName(variable) || steps === null) return false;
+            return { variable, steps };
+          },
+        },
+      ];
+    },
+    renderHTML({ node }) {
+      return [
+        "div",
+        { "data-steps": node.attrs["variable"] },
+        ...readDocumentStepsAttribute(node.attrs["steps"]).map(
+          (step) => ["span", { "data-step": step.key }, step.label] as const,
+        ),
+      ];
+    },
+  });
+}

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

@@ -3,6 +3,7 @@ import {
   createSystemConfig,
   defineFeature,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { isCollectionRefusedKind } from "./constants.js";
 import { bySlugQuery } from "./handlers/by-slug.query.js";
 import { byTenantQuery } from "./handlers/by-tenant.query.js";
 import { makeCollectionItemQuery } from "./handlers/collection-item.query.js";
@@ -60,8 +61,19 @@ export type TemplateResolverOptions = {
   readonly collections?: readonly ContentCollectionDefinition[];
 };
 
+function assertCollectionKindsAllowed(collections: readonly ContentCollectionDefinition[]): void {
+  for (const collection of collections) {
+    if (isCollectionRefusedKind(collection.kind)) {
+      throw new Error(
+        `template-resolver: collection "${collection.id}" uses kind "${collection.kind}", which collections may not write`,
+      );
+    }
+  }
+}
+
 export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}) {
   const collections = opts.collections ?? [];
+  assertCollectionKindsAllowed(collections);
   const hasUserOwned = collections.some((c) => c.ownership === "user");
   return defineFeature("template-resolver", (r) => {
     r.describe(

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

@@ -1,5 +1,6 @@
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type {
+  BeforeTransactionResult,
   HandlerContext,
   SessionUser,
   TenantId,
@@ -16,9 +17,13 @@ import type { LinkedResourceEntry } from "../linked-resources.js";
 import {
   attachmentLimitFailure,
   attachmentNeedsMailTemplate,
+  createPreparedBundleResourceEntry,
+  type PreparedTemplateFile,
+  prepareTemplateAttachmentBeforeTransaction,
+  prepareTemplateResourceBeforeTransaction,
+  type Release,
   readTemplateResourceMaxBytes,
-  storeBundleAttachment,
-  storeTemplateResource,
+  releaseAll,
 } from "../store-template-resource.js";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.js";
 import type { TemplateBundle } from "../template-bundle.js";
@@ -92,64 +97,101 @@ async function collectBundleIssues(
   return issues;
 }
 
-async function storeBundleResources(
-  args: BundleImport,
-): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
-  const linked: Record<string, LinkedResourceEntry> = {};
-  const pdfLinks = Object.entries(args.bundle.pdfAttachments);
+export type PreparedBundleResources = ReadonlyMap<string, PreparedTemplateFile>;
+
+function checkBundleAttachments(bundle: TemplateBundle): WriteResult<null> {
   const attachmentCount =
-    Object.values(args.bundle.resources).filter((resource) => resource.purpose === "attachment")
-      .length + pdfLinks.length;
-  if (attachmentCount > 0 && args.bundle.kind !== "mail") return attachmentNeedsMailTemplate();
+    Object.values(bundle.resources).filter((resource) => resource.purpose === "attachment").length +
+    Object.keys(bundle.pdfAttachments).length;
+  if (attachmentCount > 0 && bundle.kind !== "mail") return attachmentNeedsMailTemplate();
   if (attachmentCount > MAX_FILE_ATTACHMENTS_PER_TEMPLATE) return attachmentLimitFailure();
-  // The document template is not looked up: a bundle may carry it later than the mail.
-  for (const [key, link] of pdfLinks) linked[key] = { kind: "rendered-pdf", ...link };
+  return { isSuccess: true, data: null };
+}
+
+// beforeTransaction half: validates the bundle and uploads every resource file to the target
+// tenant's storage. A failed or throwing upload releases the ones before it.
+export async function prepareTemplateBundleBeforeTransaction(
+  args: BundleImport & { readonly status: BundleImportStatus },
+): Promise<BeforeTransactionResult<PreparedBundleResources>> {
+  const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
+  if (refused !== null) return refused;
+  const issues = await collectBundleIssues(args, args.status);
+  if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
+  const attachmentCheck = checkBundleAttachments(args.bundle);
+  if (!attachmentCheck.isSuccess) return attachmentCheck;
+
   const maxBytes = await readTemplateResourceMaxBytes(args.ctx.config, args.ctx.registry);
-  // A bundle is untrusted input like an upload: the same re-encoding decides the stored
-  // content type, so a declared image/png can't smuggle SVG or HTML into a mail or PDF.
-  for (const [key, resource] of Object.entries(args.bundle.resources)) {
-    const bytes = Uint8Array.from(Buffer.from(resource.base64, "base64"));
-    if (resource.purpose === "attachment") {
-      const attachment = await storeBundleAttachment({
+  const prepared = new Map<string, PreparedTemplateFile>();
+  const releases: Release[] = [];
+  try {
+    // A bundle is untrusted input like an upload: the same re-encoding decides the stored
+    // content type, so a declared image/png can't smuggle SVG or HTML into a mail or PDF.
+    for (const [key, resource] of Object.entries(args.bundle.resources)) {
+      const bytes = Uint8Array.from(Buffer.from(resource.base64, "base64"));
+      const common = {
         ctx: args.ctx,
         user: args.user,
         tenantId: args.tenantId,
         bytes,
         maxBytes,
         key,
-        fileName: resource.fileName,
-      });
-      if (!attachment.isSuccess) return attachment;
-      linked[key] = attachment.data;
-      continue;
+      };
+      const result =
+        resource.purpose === "attachment"
+          ? await prepareTemplateAttachmentBeforeTransaction({
+              ...common,
+              fileName: resource.fileName,
+            })
+          : await prepareTemplateResourceBeforeTransaction(common);
+      if (!result.isSuccess) {
+        await releaseAll(releases);
+        return result;
+      }
+      if (result.release) releases.push(result.release);
+      prepared.set(key, result.data);
     }
-    const stored = await storeTemplateResource({
-      ctx: args.ctx,
-      user: args.user,
-      tenantId: args.tenantId,
-      bytes,
-      maxBytes,
-      key,
-    });
-    if (!stored.isSuccess) return stored;
-    linked[key] = stored.data.fileRefId;
+  } catch (cause) {
+    await releaseAll(releases);
+    throw cause;
+  }
+  return { isSuccess: true, data: prepared, release: () => releaseAll(releases) };
+}
+
+async function linkPreparedBundleResources(
+  args: BundleImport,
+  prepared: PreparedBundleResources,
+): Promise<WriteResult<Record<string, LinkedResourceEntry>>> {
+  const linked: Record<string, LinkedResourceEntry> = {};
+  // The document template is not looked up: a bundle may carry it later than the mail.
+  for (const [key, link] of Object.entries(args.bundle.pdfAttachments)) {
+    linked[key] = { kind: "rendered-pdf", ...link };
+  }
+  for (const [key, file] of prepared) {
+    const entry = await createPreparedBundleResourceEntry(
+      { ctx: args.ctx, user: args.user, tenantId: args.tenantId },
+      file,
+    );
+    if (!entry.isSuccess) return entry;
+    linked[key] = entry.data;
   }
   return { isSuccess: true, data: linked };
 }
 
-// Validates every locale first, stores the resource files, then writes one row
-// per locale, so a bad locale never leaves files or half a bundle behind. An image
-// that fails re-encoding stops the import before any row is written; files stored
-// for the resources before it stay as unlinked FileRefs, like a replaced upload.
+// Validates every locale first, so a bad locale is refused before anything is written.
+// The resource files are uploaded in the beforeTransaction phase; a rolled-back transaction
+// releases them there. A crash between the upload and the commit leaves the binaries unreferenced.
 export async function importTemplateBundle(
-  args: BundleImport & { readonly status: BundleImportStatus },
+  args: BundleImport & {
+    readonly status: BundleImportStatus;
+    readonly prepared: PreparedBundleResources;
+  },
 ): Promise<WriteResult<{ ids: Record<string, string> }>> {
   const refused = refuseTenantScopeUnderSystemTenant(args.scope, args.tenantId);
   if (refused !== null) return refused;
   const issues = await collectBundleIssues(args, args.status);
   if (issues.length > 0) return writeFailure(new ValidationError({ fields: [...issues] }));
 
-  const linked = await storeBundleResources(args);
+  const linked = await linkPreparedBundleResources(args, args.prepared);
   if (!linked.isSuccess) return linked;
 
   const variableSchema = args.bundle.variableSchema ?? {};

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

@@ -7,7 +7,7 @@ import {
 import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.js";
-import { COLLECTION_REFUSED_KINDS } from "../constants.js";
+import { isCollectionRefusedKind } from "../constants.js";
 import { documentViolationsToFieldIssues, sanitizeTemplateBody } from "../document-sanitizer.js";
 import {
   type CollectionEntryRow,
@@ -43,12 +43,13 @@ export function makeCollectionSetWrite(collection: ContentCollectionDefinition)
         ? `Creates or overwrites the caller's own "${collection.id}" entry at a slug and locale, live on save with no draft stage; it always writes the acting user's entry, never another user's.`
         : `Creates or overwrites the tenant-wide "${collection.id}" entry at a slug and locale, live on save with no draft stage; the change is visible to everyone who may reach this shared collection.`,
     handler: async (event, ctx) => {
-      if (COLLECTION_REFUSED_KINDS.includes(collection.kind)) {
+      // Defense in depth: createTemplateResolverFeature already refuses these kinds at mount.
+      if (isCollectionRefusedKind(collection.kind)) {
         return writeFailure(
           new ValidationError({
             fields: [
               {
-                path: "kind",
+                path: "",
                 code: "kind_not_allowed",
                 i18nKey: "templateResolver.errors.collection.kindNotAllowed",
                 params: { detail: collection.kind },