@cosmicdrift/kumiko-bundled-features 0.363.0 → 0.365.0

package/dist/template-resolver/compile-document-body.js

@@ -1,4 +1,6 @@
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isResourceImageContentType } from "../shared/index.js";
+import { rewriteStepsBlock } from "./compile-steps-block.js";
 import { withParsedDocument } from "./document-sanitizer.js";
 import { DOCUMENT_TEXT_ALIGNMENTS, isAllowedDocumentLinkHref, isDocumentPlaceholderHref, isDocumentReferenceName, isDocumentResourceKey, } from "./document-schema.js";
 // Private-use characters mark where a Handlebars expression goes. Author text
@@ -37,6 +39,8 @@ function valueExpression(path, def) {
         return `{{money ${path}}}`;
     if (def?.type === "date")
         return `{{date ${path}}}`;
+    if (def?.type === "richText")
+        return `{{richText ${path}}}`;
     return `{{${path}}}`;
 }
 function rewriteVariable(element, state) {
@@ -50,6 +54,33 @@ function pathAndDef(name, element, state) {
     const { path, def } = resolveReference(name, rowScopeOf(element, state), state.variables);
     return [path, def];
 }
+const VARIABLE_ONLY_BLOCK_SELECTOR = "p, h1, h2, h3, h4";
+function soleVariableName(block) {
+    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, state) {
+    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, state) {
     const href = element.getAttribute("href") ?? "";
     if (isDocumentPlaceholderHref(href)) {
@@ -88,12 +119,21 @@ function stripActiveContent(element) {
 function neutralizeBraces(html) {
     return html.replace(/[{}]/g, (brace) => (brace === "{" ? "{" : "}"));
 }
-const RESOURCE_IMAGE_CONTENT_TYPES = new Set([
-    "image/png",
-    "image/jpeg",
-    "image/gif",
-    "image/webp",
-]);
+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 = {
+    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, style) {
+    const existing = element.getAttribute("style");
+    element.setAttribute("style", existing === null ? style : `${existing};${style}`);
+}
 // Unique valid resource keys in document order.
 export function collectDocumentResourceKeys(html) {
     return withParsedDocument(html, (root) => {
@@ -107,7 +147,7 @@ export function collectDocumentResourceKeys(html) {
     });
 }
 export function toResourceDataUri(contentType, bytes) {
-    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")}`;
@@ -118,7 +158,7 @@ function rewriteAlignment(element) {
     if (isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align))
         element.setAttribute("style", `text-align:${align}`);
 }
-function rewriteResourceImage(element, resourceSrc) {
+function rewriteResourceImage(element, resourceSrc, maxWidthPx, maxHeightPx) {
     const key = element.getAttribute("data-resource") ?? "";
     const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
     if (src === undefined) {
@@ -128,6 +168,56 @@ function rewriteResourceImage(element, resourceSrc) {
     }
     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, options) {
+    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) {
+    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) {
+    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) {
+    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, state, options) {
+    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
 // rewritten in document order; list rows last so their placeholders still see
@@ -136,24 +226,27 @@ export function compileDocumentBodyToHandlebars(html, variables, options = {}) {
     const state = { 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/dist/template-resolver/compile-steps-block.d.ts

@@ -0,0 +1,10 @@
+import type { Element as ScanElement } from "happy-dom";
+export declare const DEFAULT_STEPS_COLOR = "#1f5468";
+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;
+};
+export declare function rewriteStepsBlock(element: ScanElement, hooks: StepsCompileHooks): void;

package/dist/template-resolver/compile-steps-block.js

@@ -0,0 +1,45 @@
+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";
+// 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, hooks) {
+    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, state, yes, no) => `${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/dist/template-resolver/constants.d.ts

@@ -9,16 +9,19 @@ export type TemplateKind = (typeof TEMPLATE_KINDS)[number];
 export declare const UPSERT_KINDS: readonly ["mail", "document-pdf", "image-snapshot", "ai-prompt", "mail-layout", "pdf-layout"];
 export type UpsertKind = (typeof UPSERT_KINDS)[number];
 export declare const TEXT_BLOCK_KIND: "text-block";
-export declare const COLLECTION_REFUSED_KINDS: readonly string[];
+export declare const COLLECTION_REFUSED_KINDS: readonly ["mail", "mail-layout", "pdf-layout"];
+export declare function isCollectionRefusedKind(kind: string): boolean;
 export declare const CONTENT_FORMATS: readonly ["markdown", "mjml", "html", "plain"];
 export type ContentFormat = (typeof CONTENT_FORMATS)[number];
 export declare const TEMPLATE_SCOPES: readonly ["system", "tenant"];
 export type TemplateScope = (typeof TEMPLATE_SCOPES)[number];
 export declare const TEMPLATE_STATUSES: readonly ["draft", "active", "archived"];
 export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];
-export declare const PDF_PAGE_FORMATS: readonly ["A4", "Letter"];
-export type PdfPageFormat = (typeof PDF_PAGE_FORMATS)[number];
+export declare const ACTIVE_TEMPLATE_STATUS = "active";
+export { PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, type PdfOrientation, type PdfPageFormat, } from "./pdf-constants.js";
+export declare const HEX_COLOR_PATTERN: RegExp;
 export declare const DEFAULT_MAIL_LAYOUT_SLUG = "default";
+export declare const DEFAULT_PDF_LAYOUT_SLUG = "default";
 export declare const MAIL_PREVIEW_MAX_BYTES: number;
 export declare const TEST_MAIL_NOTIFICATION_TYPE = "template-resolver:test-mail";
 export declare const TEST_MAIL_SUBJECT_PREFIX = "[TEST] ";

package/dist/template-resolver/constants.js

@@ -40,12 +40,23 @@ export const TEXT_BLOCK_KIND = "text-block";
 // 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 = ["mail", "mail-layout", "pdf-layout"];
+export const COLLECTION_REFUSED_KINDS = [
+    "mail",
+    "mail-layout",
+    "pdf-layout",
+];
+export function isCollectionRefusedKind(kind) {
+    return COLLECTION_REFUSED_KINDS.some((refused) => refused === kind);
+}
 export const CONTENT_FORMATS = ["markdown", "mjml", "html", "plain"];
 export const TEMPLATE_SCOPES = ["system", "tenant"];
 export const TEMPLATE_STATUSES = ["draft", "active", "archived"];
-export const PDF_PAGE_FORMATS = ["A4", "Letter"];
+export const ACTIVE_TEMPLATE_STATUS = "active";
+export { PDF_DEFAULT_MARGIN_MM, PDF_FOOTER_MARGIN_MM, PDF_HEADER_MARGIN_MM, PDF_ORIENTATIONS, PDF_PAGE_FORMATS, } from "./pdf-constants.js";
+// Colors end up inside MJML attributes, so only a strict hex is ever written there.
+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;
 export const TEST_MAIL_NOTIFICATION_TYPE = "template-resolver:test-mail";

package/dist/template-resolver/document-sanitizer.js

@@ -3,6 +3,7 @@ import { generateHTML, generateJSON } from "@tiptap/html/server";
 import { Window } from "happy-dom";
 import { DOCUMENT_HTML_KINDS } from "./constants.js";
 import { documentExtensions, isAllowedDocumentLinkHref, isDocumentPlaceholderHref, isDocumentReferenceName, isDocumentResourceKey, } from "./document-schema.js";
+import { isDocumentStepKey } from "./document-steps.js";
 export function violation(code, detail, message) {
     return { code, detail, message };
 }
@@ -56,6 +57,8 @@ const REFERENCE_ATTRIBUTES = [
     ["data-variable", isDocumentReferenceName],
     ["data-each", isDocumentReferenceName],
     ["data-resource", isDocumentResourceKey],
+    ["data-steps", isDocumentReferenceName],
+    ["data-step", isDocumentStepKey],
 ];
 function scanReferences(tag, element, out) {
     for (const [attribute, isValid] of REFERENCE_ATTRIBUTES) {

package/dist/template-resolver/document-schema.d.ts

@@ -3,14 +3,14 @@ export declare function isDocumentPlaceholderHref(href: string): boolean;
 export declare function isAllowedDocumentLinkHref(href: string): boolean;
 export declare function isDocumentReferenceName(value: string): boolean;
 export declare function isDocumentResourceKey(value: string): boolean;
-export declare const DOCUMENT_NODE_NAMES: readonly ["variable", "resource", "button", "divider", "pageBreak"];
+export declare const DOCUMENT_NODE_NAMES: readonly ["variable", "resource", "button", "divider", "pageBreak", "steps"];
 export declare const DocumentVariable: Node<any, any>;
 export declare const DocumentResource: Node<any, any>;
 export declare const DocumentButton: Node<any, any>;
 export declare const DocumentDivider: Node<any, any>;
 export declare const DocumentPageBreak: Node<any, any>;
+export declare const DocumentSteps: Node<any, any>;
 export declare const DocumentTableRow: Node<import("@tiptap/extension-table").TableRowOptions, any>;
-export declare const DocumentRepeatRow: Node<import("@tiptap/extension-table").TableRowOptions, any>;
 export declare const DocumentTable: Node<import("@tiptap/extension-table").TableOptions, any>;
 export declare const DocumentTableCell: Node<import("@tiptap/extension-table").TableCellOptions, any>;
 export declare const DocumentTableHeader: Node<import("@tiptap/extension-table").TableHeaderOptions, any>;
@@ -18,4 +18,5 @@ export declare const DocumentLink: import("@tiptap/core").Mark<import("@tiptap/e
 export declare const DOCUMENT_TEXT_ALIGNMENTS: readonly ["left", "center", "right", "justify"];
 export type DocumentTextAlignment = (typeof DOCUMENT_TEXT_ALIGNMENTS)[number];
 export declare const DocumentTextAlign: Extension<any, any>;
+export declare const DocumentTextSize: Extension<any, any>;
 export declare const documentExtensions: Extensions;

package/dist/template-resolver/document-schema.js

@@ -8,12 +8,14 @@ import { Extension, 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";
-const PLACEHOLDER_HREF = /^\{\{[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*\}\}$/;
+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_]*)*$/;
 const RESOURCE_KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const ALLOWED_LINK_SCHEMES = ["https://", "http://", "mailto:", "tel:"];
 export function isDocumentPlaceholderHref(href) {
-    return PLACEHOLDER_HREF.test(href);
+    const name = PLACEHOLDER_HREF.exec(href)?.[1];
+    return name !== undefined && isDocumentReferenceName(name);
 }
 const UNSAFE_URL_CHARACTERS = new Set(["<", ">", '"']);
 const FORBIDDEN_REFERENCE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
@@ -62,6 +64,7 @@ export const DOCUMENT_NODE_NAMES = [
     "button",
     "divider",
     "pageBreak",
+    "steps",
 ];
 export const DocumentVariable = Node.create({
     name: "variable",
@@ -120,7 +123,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() {
@@ -165,6 +169,7 @@ export const DocumentPageBreak = Node.create({
         return ["div", { "data-page-break": "" }];
     },
 });
+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({
@@ -189,7 +194,6 @@ export const DocumentTableRow = TableRow.extend({
         };
     },
 });
-export const DocumentRepeatRow = DocumentTableRow;
 export const DocumentTable = Table.extend({
     renderHTML() {
         return ["table", ["tbody", 0]];
@@ -261,6 +265,25 @@ export const DocumentTextAlign = Extension.create({
         ];
     },
 });
+// Only "small" exists: the sender line above an address block. Serialized as data-size for the
+// same reason as data-align.
+export const DocumentTextSize = Extension.create({
+    name: "documentTextSize",
+    addGlobalAttributes() {
+        return [
+            {
+                types: ["paragraph"],
+                attributes: {
+                    textSize: {
+                        default: null,
+                        parseHTML: (element) => element.getAttribute("data-size") === "small" ? "small" : null,
+                        renderHTML: (attributes) => attributes["textSize"] === "small" ? { "data-size": "small" } : {},
+                    },
+                },
+            },
+        ];
+    },
+});
 export const documentExtensions = [
     StarterKit.configure({
         blockquote: false,
@@ -292,5 +315,7 @@ export const documentExtensions = [
     DocumentButton,
     DocumentDivider,
     DocumentPageBreak,
+    DocumentSteps,
     DocumentTextAlign,
+    DocumentTextSize,
 ];

package/dist/template-resolver/document-steps.d.ts

@@ -0,0 +1,17 @@
+import { Node } from "@tiptap/core";
+export declare const DOCUMENT_STEPS_MAX = 8;
+export type DocumentStep = {
+    readonly key: string;
+    readonly label: string;
+};
+export declare function isDocumentStepKey(value: string): boolean;
+export declare function documentStepKeyOf(label: string): string;
+export declare function parseDocumentStepsInput(text: string): readonly DocumentStep[] | null;
+export declare function readDocumentSteps(element: {
+    querySelectorAll(selector: string): ArrayLike<{
+        getAttribute(name: string): string | null;
+        textContent: string | null;
+    }>;
+}): readonly DocumentStep[] | null;
+export declare function readDocumentStepsAttribute(value: unknown): readonly DocumentStep[];
+export declare function createDocumentStepsNode(isReferenceName: (value: string) => boolean): Node<any, any>;

package/dist/template-resolver/document-steps.js

@@ -0,0 +1,93 @@
+// @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 function isDocumentStepKey(value) {
+    return STEP_KEY.test(value);
+}
+export function documentStepKeyOf(label) {
+    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) {
+    const steps = text
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "")
+        .map((entry) => {
+        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) {
+    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) {
+    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) {
+    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) {
+    return Array.isArray(value) ? value.filter(isDocumentStep) : [];
+}
+export function createDocumentStepsNode(isReferenceName) {
+    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]),
+            ];
+        },
+    });
+}

package/dist/template-resolver/feature.d.ts

@@ -20,6 +20,8 @@ export declare function createTemplateResolverFeature(opts?: TemplateResolverOpt
             archive: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             publishSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             archiveSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            discardDraft: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            discardDraftSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             resetToSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             set: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             importBundle: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;

package/dist/template-resolver/feature.js

@@ -1,4 +1,5 @@
 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";
@@ -6,6 +7,7 @@ import { makeCollectionListQuery } from "./handlers/collection-list.query.js";
 import { makeCollectionSetWrite } from "./handlers/collection-set.write.js";
 import { copyLocaleWrite } from "./handlers/copy-locale.write.js";
 import { diffToSystemQuery } from "./handlers/diff-to-system.query.js";
+import { discardDraftSystemWrite, discardDraftWrite } from "./handlers/discard-draft.write.js";
 import { exportBundleQuery } from "./handlers/export-bundle.query.js";
 import { findByIdQuery } from "./handlers/find-by-id.query.js";
 import { importBundleWrite } from "./handlers/import-bundle.write.js";
@@ -28,13 +30,21 @@ import { usageQuery } from "./handlers/usage.query.js";
 import { validateQuery } from "./handlers/validate.query.js";
 import { templateResourceEntity } from "./table.js";
 import { userContentEntryEntity } from "./user-content-table.js";
+function assertCollectionKindsAllowed(collections) {
+    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 = {}) {
     const collections = opts.collections ?? [];
+    assertCollectionKindsAllowed(collections);
     const hasUserOwned = collections.some((c) => c.ownership === "user");
     return defineFeature("template-resolver", (r) => {
         r.describe([
             "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).",
-            "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`.",
+            "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.",
             "Text an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.",
             "How a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).",
             'A collection is tenant-wide by default. With `ownership: "user"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.',
@@ -67,6 +77,8 @@ export function createTemplateResolverFeature(opts = {}) {
             archive: r.writeHandler(archiveWrite),
             publishSystem: r.writeHandler(publishSystemWrite),
             archiveSystem: r.writeHandler(archiveSystemWrite),
+            discardDraft: r.writeHandler(discardDraftWrite),
+            discardDraftSystem: r.writeHandler(discardDraftSystemWrite),
             resetToSystem: r.writeHandler(resetToSystemWrite),
             set: r.writeHandler(setWrite),
             importBundle: r.writeHandler(importBundleWrite),

package/dist/template-resolver/handlers/bundle-import.d.ts

@@ -1,6 +1,7 @@
-import type { HandlerContext, SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import type { BeforeTransactionResult, HandlerContext, SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { type FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
 import type { TemplateWriteScope } from "../layout-regions.js";
+import { type PreparedTemplateFile } from "../store-template-resource.js";
 import type { TemplateBundle } from "../template-bundle.js";
 export declare function targetExistsIssue(locale: string): FieldIssue;
 type BundleImport = {
@@ -12,8 +13,13 @@ type BundleImport = {
     readonly overwrite: boolean;
 };
 type BundleImportStatus = "draft" | "active";
+export type PreparedBundleResources = ReadonlyMap<string, PreparedTemplateFile>;
+export declare function prepareTemplateBundleBeforeTransaction(args: BundleImport & {
+    readonly status: BundleImportStatus;
+}): Promise<BeforeTransactionResult<PreparedBundleResources>>;
 export declare function importTemplateBundle(args: BundleImport & {
     readonly status: BundleImportStatus;
+    readonly prepared: PreparedBundleResources;
 }): Promise<WriteResult<{
     ids: Record<string, string>;
 }>>;