@cosmicdrift/kumiko-bundled-features 0.364.0 → 0.365.0

package/dist/shared/index.d.ts

@@ -18,6 +18,7 @@ export { rateLimitedTextResponse } from "./rate-limited-text-response.js";
 export { redactBotTokens, redactEmailAddresses, redactErrorText, redactUrls, } from "./redact.js";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";
 export { requireForTenant } from "./require-for-tenant.js";
+export { extensionForResourceContentType, isResourceImageContentType, isResourceImageFormat, RESOURCE_IMAGE_FORMATS, type ResourceImageContentType, type ResourceImageFormat, } from "./resource-image-formats.js";
 export { type RowBoundGrantResult, redeemRowBoundGrant, signRowBoundGrant, } from "./row-bound-grant.js";
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";

package/dist/shared/index.js

@@ -18,6 +18,7 @@ export { rateLimitedTextResponse } from "./rate-limited-text-response.js";
 export { redactBotTokens, redactEmailAddresses, redactErrorText, redactUrls, } from "./redact.js";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";
 export { requireForTenant } from "./require-for-tenant.js";
+export { extensionForResourceContentType, isResourceImageContentType, isResourceImageFormat, RESOURCE_IMAGE_FORMATS, } from "./resource-image-formats.js";
 export { redeemRowBoundGrant, signRowBoundGrant, } from "./row-bound-grant.js";
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";

package/dist/shared/resource-image-formats.d.ts

@@ -0,0 +1,23 @@
+export declare const RESOURCE_IMAGE_FORMATS: {
+    readonly png: {
+        readonly contentType: "image/png";
+        readonly extension: "png";
+    };
+    readonly jpeg: {
+        readonly contentType: "image/jpeg";
+        readonly extension: "jpg";
+    };
+    readonly gif: {
+        readonly contentType: "image/gif";
+        readonly extension: "gif";
+    };
+    readonly webp: {
+        readonly contentType: "image/webp";
+        readonly extension: "webp";
+    };
+};
+export type ResourceImageFormat = keyof typeof RESOURCE_IMAGE_FORMATS;
+export type ResourceImageContentType = (typeof RESOURCE_IMAGE_FORMATS)[ResourceImageFormat]["contentType"];
+export declare function isResourceImageFormat(format: string | undefined): format is ResourceImageFormat;
+export declare function isResourceImageContentType(contentType: string): contentType is ResourceImageContentType;
+export declare function extensionForResourceContentType(contentType: string): string | undefined;

package/dist/shared/resource-image-formats.js

@@ -0,0 +1,21 @@
+// Single source for the raster formats a template resource image may have: the normalizer, the
+// stored file extension, the data-URI embedding and the inline mail attachment name all derive
+// from it, so a new format cannot be accepted in one place and dropped in another.
+export const RESOURCE_IMAGE_FORMATS = {
+    png: { contentType: "image/png", extension: "png" },
+    jpeg: { contentType: "image/jpeg", extension: "jpg" },
+    gif: { contentType: "image/gif", extension: "gif" },
+    webp: { contentType: "image/webp", extension: "webp" },
+};
+export function isResourceImageFormat(format) {
+    return format !== undefined && Object.hasOwn(RESOURCE_IMAGE_FORMATS, format);
+}
+function formatForContentType(contentType) {
+    return Object.values(RESOURCE_IMAGE_FORMATS).find((entry) => entry.contentType === contentType);
+}
+export function isResourceImageContentType(contentType) {
+    return formatForContentType(contentType) !== undefined;
+}
+export function extensionForResourceContentType(contentType) {
+    return formatForContentType(contentType)?.extension;
+}

package/dist/shared/sharp-input-limits.js

@@ -4,19 +4,18 @@
 // 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,
 };
-// 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) {
     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.");
+        throw new Error("SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this code doesn't need to cross.");
     }
 }

package/dist/step-dispatcher/webhook-runner.js

@@ -79,8 +79,8 @@ let fetchImpl = globalThis.fetch.bind(globalThis);
 export function setWebhookFetch(fn) {
     fetchImpl = fn;
 }
-// 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
 // tenant-chosen name, but the error still reaches the tenant via the

package/dist/template-resolver/compile-document-body.d.ts

@@ -2,10 +2,13 @@ import type { TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
 export type CompileDocumentBodyOptions = {
     readonly resourceSrc?: (key: string) => string | undefined;
     readonly resourceImageMaxWidthPx?: number;
+    readonly resourceImageMaxHeightPx?: number;
     readonly alignmentAsInlineStyle?: boolean;
     readonly buttonAsInlineStyle?: boolean;
     readonly tableAsInlineStyle?: boolean;
     readonly buttonInlineStyle?: string;
+    readonly headingAsInlineStyle?: boolean;
+    readonly stepsColor?: string;
 };
 export declare function collectDocumentResourceKeys(html: string): readonly string[];
 export declare function toResourceDataUri(contentType: string, bytes: Uint8Array): string;

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
@@ -52,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)) {
@@ -94,18 +123,17 @@ const MAIL_BUTTON_STYLE = "display:inline-block;padding:10px 20px;border-radius:
 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 = {
+    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}`);
 }
-const RESOURCE_IMAGE_CONTENT_TYPES = new Set([
-    "image/png",
-    "image/jpeg",
-    "image/gif",
-    "image/webp",
-]);
 // Unique valid resource keys in document order.
 export function collectDocumentResourceKeys(html) {
     return withParsedDocument(html, (root) => {
@@ -119,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")}`;
@@ -130,7 +158,7 @@ function rewriteAlignment(element) {
     if (isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align))
         element.setAttribute("style", `text-align:${align}`);
 }
-function rewriteResourceImage(element, resourceSrc, maxWidthPx) {
+function rewriteResourceImage(element, resourceSrc, maxWidthPx, maxHeightPx) {
     const key = element.getAttribute("data-resource") ?? "";
     const src = isDocumentResourceKey(key) ? resourceSrc?.(key) : undefined;
     if (src === undefined) {
@@ -140,14 +168,18 @@ function rewriteResourceImage(element, resourceSrc, maxWidthPx) {
     }
     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(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);
+        rewriteResourceImage(element, options.resourceSrc, options.resourceImageMaxWidthPx, options.resourceImageMaxHeightPx);
     }
     for (const element of Array.from(root.querySelectorAll("*")))
         stripActiveContent(element);
@@ -161,6 +193,13 @@ function applyAlignmentInlineStyles(root) {
         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);
@@ -190,8 +229,20 @@ export function compileDocumentBodyToHandlebars(html, variables, options = {}) {
         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/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 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,14 +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 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,12 +3,13 @@ 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 DocumentTable: Node<import("@tiptap/extension-table").TableOptions, any>;
 export declare const DocumentTableCell: Node<import("@tiptap/extension-table").TableCellOptions, any>;

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

@@ -8,6 +8,7 @@ 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";
+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_.-]*$/;
@@ -63,6 +64,7 @@ export const DOCUMENT_NODE_NAMES = [
     "button",
     "divider",
     "pageBreak",
+    "steps",
 ];
 export const DocumentVariable = Node.create({
     name: "variable",
@@ -121,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() {
@@ -166,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({
@@ -311,6 +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.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";
@@ -29,8 +30,16 @@ 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([

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