@cosmicdrift/kumiko-samples 0.364.0 → 0.365.1

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

@@ -1,4 +1,85 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "copy-locale copies the system default's files in a beforeTransaction phase and can no longer run as a nested write",
+    "detail": "When a tenant copies a locale from the system default, the image and attachment files are now read and written to the tenant's storage in a beforeTransaction phase. The transaction only creates the fileRef rows, and the uploaded binaries are released when it does not commit. Before, the storage I/O held the database transaction open.",
+    "migration": "Dispatch copy-locale as a top-level command, or from a perCommand handler via ctx.write. A handler that called it nested moves that call into a client or job, or becomes a perCommand handler."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Opening a document or mail editor with an empty body no longer marks the form as changed",
+    "detail": "Switching the editor's editable state on mount emitted an update, so DocumentTiptapEditor called onChange(\"<p></p>\") before the user typed anything and the surrounding form counted as dirty."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "onEditorReady receives null when the editor is destroyed",
+    "detail": "DocumentTiptapEditor and PlaceholderLineEditor call onEditorReady(null) on destroy, so a held handle no longer points at a destroyed editor. The callback type is (handle: DocumentEditorHandle | null) => void. The document designer drops the handle of an unmounted field, so placeholder insertion no longer targets a destroyed editor.",
+    "migration": "A custom onEditorReady callback must accept null and drop its stored handle when it receives it."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Document editor no longer blanks the app when late placeholders rebuild it",
+    "detail": "When the system placeholders or resource previews arrived in the same render as a new value (layout editor after opening or saving), the editor rebuilt itself and the value sync then read the destroyed editor. The TypeError unmounted the whole app and left a blank page. Both sync effects now skip a destroyed editor; the replacement editor picks up the value on its next render."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Steps block in mail and PDF templates",
+    "detail": "The document editor offers a steps block in the toolbar block menu. It stores a fixed list of stages (value=label, at most 8) and the variable that names the current stage. Mail and PDF render it as a row of bars and labels; stages up to the current one are coloured, the current label is bold. Invalid blocks are dropped by the sanitizer and render nothing. Layout regions do not offer the block."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A paragraph or heading that only holds an empty placeholder is left out of the rendered document",
+    "detail": "compileDocumentBodyToHandlebars wraps a p or h1 to h4 whose only content is one placeholder in an if block, so an empty optional value no longer leaves a blank line in mails and PDFs. Zero numbers and money values still render. Blocks with static text, images or several placeholders are unchanged."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Mail layout buttons follow the branding accent colour",
+    "detail": "mailLayoutAppearance takes the tenant branding accent colour. When the layout uses the branding accent line, buttons in the mail body use that colour instead of the fixed dark teal. Invalid colours fall back to the previous default."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A placeholder inside a button label is kept",
+    "detail": "The document schema allows placeholder chips inside a button label. Before, saving or seeding a body such as a button reading \"View {{pageName}}\" split the button: the label stopped at the placeholder and the rest landed in a new paragraph outside the button."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "compileDocumentBodyToHandlebars takes a height cap for resource images",
+    "detail": "The new resourceImageMaxHeightPx option adds max-height and width:auto to resource images. The mail renderer caps images in a layout header at 64 px, so a square logo stays small while a wide wordmark keeps its 180 px width cap."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "resource-upload refuses key collisions between images and attachments and linking a non-active PDF template",
+    "detail": "Uploading an attachment under a key that holds an inline image, or an image under a key that holds an attachment or linked PDF, fails with template_attachment_invalid (code key_in_use) instead of silently replacing the entry. resource-link-pdf only accepts an active document-pdf template, so draft or archived templates no longer produce mails that fail at send time. When the link write fails after the file was stored, the orphaned storage object is deleted."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "collection kinds fail at boot; validate, diff-to-system, overview, seeding, bundle import and placeholder checks follow the write rules",
+    "detail": "createTemplateResolverFeature throws for a collection whose kind is mail, mail-layout or pdf-layout instead of failing on every save. The validate query ignores scope system for non-SystemAdmins. diff-to-system compares only against an active system template like reset-to-system. The overview reads rows in a stable order and reports truncated when its row limit is hit. Re-seeding notification templates reactivates an archived system row and applies a changed parentTemplateId. A bundle holds at most 50 locales. Dotted placeholders under a declared variable or list item field are reported as unknown because they never render a value. The document editor fallbacks are read-only and the placeholder line editor recolors chips when systemVariables change."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Resource image formats come from one list",
+    "detail": "PNG, JPEG, GIF and WebP content types and extensions are defined once in the shared module and reused by the resource upload, the document body compiler and the email channel."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "resource-upload, import-bundle and import-bundle-system upload in a beforeTransaction phase and can no longer run as nested writes",
+    "detail": "The three handlers now validate and upload their files before the write transaction opens and only create the fileRef and template rows inside it, so no database connection sits idle in a transaction during storage I/O. A rolled-back transaction releases the uploaded bytes. Because they now have a pre-transaction phase, the dispatcher rejects a nested ctx.write, ctx.writeAs or handler-to-handler call of them (\"has a pre-transaction phase\"). The exported storeTemplateResource is replaced by prepareTemplateResourceBeforeTransaction (beforeTransaction half) and storePreparedTemplateResource (in-transaction half).",
+    "migration": "Dispatch resource-upload, import-bundle and import-bundle-system as top-level commands, or from a perCommand handler via ctx.write. A handler that called them nested moves that call into a client or job, or becomes a perCommand handler. Code that called storeTemplateResource calls prepareTemplateResourceBeforeTransaction in a beforeTransaction phase and passes the result to storePreparedTemplateResource in the handler."
+  },
   {
     "version": "0.364.0",
     "type": "fix",

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(