@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.363.0

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

@@ -0,0 +1,201 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+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";
+export function violation(code, detail, message) {
+    return { code, detail, message };
+}
+// Same switches tiptap's generateJSON uses, plus navigation off: the scan
+// window must never fetch or navigate anything.
+function createScanWindow() {
+    return new Window({
+        settings: {
+            disableJavaScriptEvaluation: true,
+            disableJavaScriptFileLoading: true,
+            disableCSSFileLoading: true,
+            disableIframePageLoading: true,
+            disableComputedStyleRendering: true,
+            navigation: {
+                disableMainFrameNavigation: true,
+                disableChildFrameNavigation: true,
+                disableChildPageNavigation: true,
+            },
+        },
+    });
+}
+function scanScriptAndHandlers(tag, element, out) {
+    if (tag === "script") {
+        out.push(violation("script_element", "script", "<script> elements are not allowed in template bodies"));
+    }
+    for (const attribute of Array.from(element.attributes)) {
+        if (/^on/i.test(attribute.name)) {
+            out.push(violation("event_handler_attribute", attribute.name, `Inline event handler "${attribute.name}" on <${tag}> is not allowed`));
+        }
+    }
+}
+function scanAnchor(element, out) {
+    const href = element.getAttribute("href");
+    if (href !== null && !isAllowedDocumentLinkHref(href)) {
+        out.push(violation("disallowed_link_href", href, `Link target "${href}" is not allowed; use https, http, mailto, tel or a {{placeholder}}`));
+    }
+    if (element.hasAttribute("data-button") && !isDocumentPlaceholderHref(href ?? "")) {
+        out.push(violation("button_href_not_placeholder", href ?? "", `Button target "${href ?? ""}" must be a {{placeholder}}`));
+    }
+}
+function scanImage(element, out) {
+    const source = element.getAttribute("src") ?? element.getAttribute("srcset");
+    if (source !== null) {
+        out.push(violation("external_image_source", source, `Images must reference an uploaded resource via data-resource; external or inline image source "${source}" is not allowed`));
+    }
+    if (!element.hasAttribute("data-resource")) {
+        out.push(violation("image_without_resource", "img", "Images must reference an uploaded resource via the data-resource attribute"));
+    }
+}
+const REFERENCE_ATTRIBUTES = [
+    ["data-variable", isDocumentReferenceName],
+    ["data-each", isDocumentReferenceName],
+    ["data-resource", isDocumentResourceKey],
+];
+function scanReferences(tag, element, out) {
+    for (const [attribute, isValid] of REFERENCE_ATTRIBUTES) {
+        const value = element.getAttribute(attribute);
+        if (value !== null && !isValid(value)) {
+            out.push(violation("invalid_reference_name", value, `Value "${value}" of ${attribute} on <${tag}> is not a valid name`));
+        }
+    }
+}
+const EMBEDDING_TAGS = new Set([
+    "iframe",
+    "frame",
+    "frameset",
+    "object",
+    "embed",
+    "applet",
+    "portal",
+]);
+const SVG_IMAGE_TAGS = new Set(["image", "feimage", "use"]);
+const URL_ATTRIBUTES = ["href", "xlink:href", "action", "formaction"];
+function scanEmbedding(tag, out) {
+    if (EMBEDDING_TAGS.has(tag)) {
+        out.push(violation("embedded_content", tag, `<${tag}> elements are not allowed in template bodies`));
+    }
+}
+// html <a href> has its own rules in scanAnchor; everywhere else (svg, base,
+// form controls) a URL attribute has no business in a template body.
+function scanUrlAttributes(tag, element, out) {
+    for (const name of URL_ATTRIBUTES) {
+        const value = element.getAttribute(name);
+        if (value === null || (tag === "a" && name === "href"))
+            continue;
+        if (SVG_IMAGE_TAGS.has(tag) && name.endsWith("href")) {
+            out.push(violation("external_image_source", value, `Images must reference an uploaded resource via data-resource; image source "${value}" is not allowed`));
+        }
+        else if (tag === "base" || !isAllowedDocumentLinkHref(value)) {
+            out.push(violation("disallowed_link_href", value, `Link target "${value}" is not allowed; use https, http, mailto, tel or a {{placeholder}}`));
+        }
+    }
+}
+// happy-dom serializes < and > inside attribute values unescaped, so a later
+// parser (MJML) could read them as markup.
+function scanAltText(element, out) {
+    const alt = element.getAttribute("alt");
+    if (alt !== null && /[<>]/.test(alt)) {
+        out.push(violation("unsafe_attribute_value", alt, `Attribute alt must not contain "<" or ">": "${alt}"`));
+    }
+}
+function scanElement(element, out) {
+    const tag = element.tagName.toLowerCase();
+    scanEmbedding(tag, out);
+    scanUrlAttributes(tag, element, out);
+    scanAltText(element, out);
+    scanScriptAndHandlers(tag, element, out);
+    if (tag === "a")
+        scanAnchor(element, out);
+    if (tag === "img")
+        scanImage(element, out);
+    scanReferences(tag, element, out);
+}
+// Parses `html` in the hardened scan window and always closes it again, also
+// when `read` throws. Shared by the sanitizer and the placeholder scan so there
+// is exactly one DOM setup.
+export function withParsedDocument(html, read) {
+    const window = createScanWindow();
+    try {
+        const parsed = new window.DOMParser().parseFromString(["<!DOCTYPE html><html><body>", html, "</body></html>"].join(""), "text/html");
+        return read(parsed.body);
+    }
+    finally {
+        window.happyDOM.abort();
+        window.happyDOM.close();
+    }
+}
+function scanDocumentHtml(html) {
+    const violations = [];
+    withParsedDocument(html, (body) => {
+        // A second `<body ...>` in the input merges its attributes into this body.
+        for (const element of [body, ...Array.from(body.querySelectorAll("*"))]) {
+            scanElement(element, violations);
+        }
+    });
+    return violations;
+}
+// Rejects hostile constructs, then rebuilds the body from the document model.
+// The rebuilt HTML is always what gets returned (never the input), so anything
+// the model cannot express is dropped silently.
+export function sanitizeDocumentHtml(html) {
+    const violations = scanDocumentHtml(html);
+    if (violations.length > 0)
+        return { ok: false, violations };
+    return {
+        ok: true,
+        html: generateHTML(generateJSON(html, documentExtensions), documentExtensions),
+    };
+}
+// Snippets accept any format, but their html is as untrusted as a mail body.
+function isSanitizedHtmlKind(kind) {
+    return kind === "snippet" || isOneOf(DOCUMENT_HTML_KINDS, kind);
+}
+const HTML_ONLY_KINDS = new Set(DOCUMENT_HTML_KINDS);
+function requiredFormatViolation(kind, contentFormat) {
+    if (HTML_ONLY_KINDS.has(kind) && contentFormat !== "html") {
+        return violation("document_requires_html_format", contentFormat, `Templates of kind ${kind} require contentFormat html, got "${contentFormat}"`);
+    }
+    return null;
+}
+export function sanitizeTemplateBody(input) {
+    const formatViolation = requiredFormatViolation(input.kind, input.contentFormat);
+    if (formatViolation !== null)
+        return { ok: false, violations: [formatViolation] };
+    if (!isSanitizedHtmlKind(input.kind) ||
+        input.contentFormat !== "html" ||
+        input.content === null) {
+        return { ok: true, content: input.content };
+    }
+    const result = sanitizeDocumentHtml(input.content);
+    return result.ok ? { ok: true, content: result.html } : result;
+}
+const VIOLATION_I18N_KEYS = {
+    script_element: "templateResolver.errors.document.scriptElement",
+    event_handler_attribute: "templateResolver.errors.document.eventHandlerAttribute",
+    disallowed_link_href: "templateResolver.errors.document.disallowedLinkHref",
+    external_image_source: "templateResolver.errors.document.externalImageSource",
+    image_without_resource: "templateResolver.errors.document.imageWithoutResource",
+    invalid_reference_name: "templateResolver.errors.document.invalidReferenceName",
+    embedded_content: "templateResolver.errors.document.embeddedContent",
+    unsafe_attribute_value: "templateResolver.errors.document.unsafeAttributeValue",
+    button_href_not_placeholder: "templateResolver.errors.document.buttonHrefNotPlaceholder",
+    document_requires_html_format: "templateResolver.errors.document.documentRequiresHtmlFormat",
+    layout_requires_mjml_format: "templateResolver.errors.document.layoutRequiresMjmlFormat",
+    layout_invalid_structure: "templateResolver.errors.document.layoutInvalidStructure",
+    layout_missing_content_slot: "templateResolver.errors.document.layoutMissingContentSlot",
+    layout_source_system_only: "templateResolver.errors.document.layoutSourceSystemOnly",
+};
+export function documentViolationsToFieldIssues(violations) {
+    return violations.map((item) => ({
+        path: "content",
+        code: item.code,
+        i18nKey: VIOLATION_I18N_KEYS[item.code],
+        params: { detail: item.detail },
+    }));
+}

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

@@ -0,0 +1,21 @@
+import { Extension, type Extensions, Node } from "@tiptap/core";
+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 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 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>;
+export declare const DocumentLink: import("@tiptap/core").Mark<import("@tiptap/extension-link").LinkOptions, any>;
+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 documentExtensions: Extensions;

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

@@ -0,0 +1,296 @@
+// @runtime client
+// Canonical document model for template bodies (kinds mail, document-pdf).
+// Universal on purpose: the web editor and the server sanitizer load the same
+// extension list, so what the editor can produce is exactly what the server
+// keeps. No DOM access at module level, no happy-dom here.
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+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_]*)*\}\}$/;
+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 UNSAFE_URL_CHARACTERS = new Set(["<", ">", '"']);
+const FORBIDDEN_REFERENCE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+function hasUnsafeUrlCharacter(value) {
+    return Array.from(value).some((character) => {
+        const code = character.charCodeAt(0);
+        return UNSAFE_URL_CHARACTERS.has(character) || code <= 0x1f || code === 0x7f;
+    });
+}
+function isParsableWebUrl(href, protocol) {
+    try {
+        return new URL(href).protocol === protocol;
+    }
+    catch {
+        return false;
+    }
+}
+function hasAllowedLinkScheme(href) {
+    if (href.startsWith("https://"))
+        return isParsableWebUrl(href, "https:");
+    if (href.startsWith("http://"))
+        return isParsableWebUrl(href, "http:");
+    return ALLOWED_LINK_SCHEMES.some((scheme) => href.startsWith(scheme));
+}
+// Exact lowercase prefix on the unchanged value: no trim, no case folding, so
+// "JaVaScRiPt:", "HTTPS://" or a leading tab can never slip through as a
+// scheme variant. Markup and control characters are refused outright because
+// downstream parsers (MJML, PDF renderer) re-read the serialized attribute.
+export function isAllowedDocumentLinkHref(href) {
+    if (hasUnsafeUrlCharacter(href))
+        return false;
+    return hasAllowedLinkScheme(href) || isDocumentPlaceholderHref(href);
+}
+// Segments that hit the prototype chain are refused: the renderer later walks
+// the dotted path into a data object.
+export function isDocumentReferenceName(value) {
+    return (REFERENCE_NAME.test(value) &&
+        !value.split(".").some((segment) => FORBIDDEN_REFERENCE_SEGMENTS.has(segment)));
+}
+export function isDocumentResourceKey(value) {
+    return RESOURCE_KEY.test(value);
+}
+export const DOCUMENT_NODE_NAMES = [
+    "variable",
+    "resource",
+    "button",
+    "divider",
+    "pageBreak",
+];
+export const DocumentVariable = Node.create({
+    name: "variable",
+    group: "inline",
+    inline: true,
+    atom: true,
+    addAttributes() {
+        return { name: { default: null } };
+    },
+    parseHTML() {
+        return [
+            {
+                tag: "span[data-variable]",
+                getAttrs: (element) => {
+                    const name = element.getAttribute("data-variable");
+                    return name !== null && isDocumentReferenceName(name) ? { name } : false;
+                },
+            },
+        ];
+    },
+    renderHTML({ node }) {
+        return ["span", { "data-variable": node.attrs["name"] }];
+    },
+});
+export const DocumentResource = Node.create({
+    name: "resource",
+    group: "block",
+    atom: true,
+    addAttributes() {
+        return { resource: { default: null }, alt: { default: null } };
+    },
+    parseHTML() {
+        return [
+            {
+                tag: "img[data-resource]",
+                getAttrs: (element) => {
+                    const resource = element.getAttribute("data-resource");
+                    if (resource === null || !isDocumentResourceKey(resource))
+                        return false;
+                    return { resource, alt: element.getAttribute("alt") };
+                },
+            },
+        ];
+    },
+    // Never emits src: the renderer resolves the resource key at render time.
+    renderHTML({ node }) {
+        const alt = node.attrs["alt"];
+        return [
+            "img",
+            alt === null || alt === undefined
+                ? { "data-resource": node.attrs["resource"] }
+                : { "data-resource": node.attrs["resource"], alt },
+        ];
+    },
+});
+export const DocumentButton = Node.create({
+    name: "button",
+    group: "block",
+    content: "text*",
+    marks: "",
+    defining: true,
+    addAttributes() {
+        return { href: { default: null } };
+    },
+    parseHTML() {
+        return [
+            {
+                tag: "a[data-button]",
+                // Must win against the Link mark's `a[href]` rule.
+                priority: 1000,
+                getAttrs: (element) => {
+                    const href = element.getAttribute("href");
+                    return href !== null && isDocumentPlaceholderHref(href) ? { href } : false;
+                },
+            },
+        ];
+    },
+    renderHTML({ node }) {
+        return ["a", { "data-button": "", href: node.attrs["href"] }, 0];
+    },
+});
+export const DocumentDivider = Node.create({
+    name: "divider",
+    group: "block",
+    atom: true,
+    parseHTML() {
+        return [{ tag: "hr" }];
+    },
+    renderHTML() {
+        return ["hr"];
+    },
+});
+export const DocumentPageBreak = Node.create({
+    name: "pageBreak",
+    group: "block",
+    atom: true,
+    parseHTML() {
+        return [{ tag: "div[data-page-break]" }];
+    },
+    renderHTML() {
+        return ["div", { "data-page-break": "" }];
+    },
+});
+// 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({
+    addAttributes() {
+        return {
+            each: {
+                default: null,
+                parseHTML: (element) => {
+                    const each = element.getAttribute("data-each");
+                    return each !== null && isDocumentReferenceName(each) ? each : null;
+                },
+                renderHTML: (attributes) => {
+                    const each = attributes["each"];
+                    return typeof each === "string" && each ? { "data-each": each } : {};
+                },
+            },
+            repeatHeader: {
+                default: false,
+                parseHTML: (element) => element.hasAttribute("data-repeat-header"),
+                renderHTML: (attributes) => attributes["repeatHeader"] ? { "data-repeat-header": "" } : {},
+            },
+        };
+    },
+});
+export const DocumentRepeatRow = DocumentTableRow;
+export const DocumentTable = Table.extend({
+    renderHTML() {
+        return ["table", ["tbody", 0]];
+    },
+});
+// Span attributes are rendered only when they differ from the default, and
+// colwidth (an editor-resize artefact) never, so `<td><p>x</p></td>` is the
+// canonical cell.
+function plainObjectOrEmpty(value) {
+    return isPlainObject(value) ? value : {};
+}
+function canonicalCellAttributes(attributes) {
+    return {
+        ...attributes,
+        colspan: {
+            ...plainObjectOrEmpty(attributes["colspan"]),
+            renderHTML: (attrs) => attrs["colspan"] && attrs["colspan"] !== 1 ? { colspan: attrs["colspan"] } : {},
+        },
+        rowspan: {
+            ...plainObjectOrEmpty(attributes["rowspan"]),
+            renderHTML: (attrs) => attrs["rowspan"] && attrs["rowspan"] !== 1 ? { rowspan: attrs["rowspan"] } : {},
+        },
+        colwidth: {
+            ...plainObjectOrEmpty(attributes["colwidth"]),
+            renderHTML: () => ({}),
+        },
+    };
+}
+export const DocumentTableCell = TableCell.extend({
+    addAttributes() {
+        return canonicalCellAttributes(this.parent?.() ?? {});
+    },
+});
+export const DocumentTableHeader = TableHeader.extend({
+    addAttributes() {
+        return canonicalCellAttributes(this.parent?.() ?? {});
+    },
+});
+// Only href survives a parse: target, rel, class and title from the input would
+// otherwise be kept verbatim, and the renderer decides those itself.
+export const DocumentLink = Link.extend({
+    addAttributes() {
+        return { href: { default: null, parseHTML: (element) => element.getAttribute("href") } };
+    },
+});
+export const DOCUMENT_TEXT_ALIGNMENTS = ["left", "center", "right", "justify"];
+// Serialized as data-align, never as a style attribute: the sanitizer keeps
+// styles out of the model, and each renderer maps the value to its own CSS.
+export const DocumentTextAlign = Extension.create({
+    name: "documentTextAlign",
+    addGlobalAttributes() {
+        return [
+            {
+                types: ["paragraph", "heading"],
+                attributes: {
+                    textAlign: {
+                        default: null,
+                        parseHTML: (element) => {
+                            const align = element.getAttribute("data-align");
+                            return isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align) ? align : null;
+                        },
+                        renderHTML: (attributes) => {
+                            const align = attributes["textAlign"];
+                            return isOneOf(DOCUMENT_TEXT_ALIGNMENTS, align) ? { "data-align": align } : {};
+                        },
+                    },
+                },
+            },
+        ];
+    },
+});
+export const documentExtensions = [
+    StarterKit.configure({
+        blockquote: false,
+        code: false,
+        codeBlock: false,
+        strike: false,
+        horizontalRule: false,
+        dropcursor: false,
+        gapcursor: false,
+        undoRedo: false,
+        trailingNode: false,
+        listKeymap: false,
+        heading: { levels: [1, 2, 3] },
+        link: false,
+    }),
+    DocumentLink.configure({
+        openOnClick: false,
+        autolink: false,
+        linkOnPaste: false,
+        HTMLAttributes: { target: null, rel: null, class: null },
+        isAllowedUri: (url) => isAllowedDocumentLinkHref(url),
+    }),
+    DocumentTable,
+    DocumentTableRow,
+    DocumentTableHeader,
+    DocumentTableCell,
+    DocumentVariable,
+    DocumentResource,
+    DocumentButton,
+    DocumentDivider,
+    DocumentPageBreak,
+    DocumentTextAlign,
+];

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

@@ -18,13 +18,31 @@ export declare function createTemplateResolverFeature(opts?: TemplateResolverOpt
             upsertTenant: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             publish: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             archive: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            publishSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            archiveSystem: 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;
+            importBundleSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            copyLocale: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            resourceUpload: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            resourceRemove: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            resourceLinkPdf: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            sendTest: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
         };
         queries: {
             findById: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             list: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             bySlug: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
             byTenant: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            usage: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            overview: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            layoutSource: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            tenantOverrides: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            diffToSystem: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            validate: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            preview: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
+            exportBundle: import("@cosmicdrift/kumiko-types/handlers").HandlerRef;
         };
         treeHandle: import("@cosmicdrift/kumiko-types/tree-node").TreeActionsHandle<"template-resolver", {
             readonly edit: {

package/dist/template-resolver/feature.js

@@ -1,15 +1,31 @@
-import { defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemConfig, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 import { bySlugQuery } from "./handlers/by-slug.query.js";
 import { byTenantQuery } from "./handlers/by-tenant.query.js";
 import { makeCollectionItemQuery } from "./handlers/collection-item.query.js";
 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 { exportBundleQuery } from "./handlers/export-bundle.query.js";
 import { findByIdQuery } from "./handlers/find-by-id.query.js";
+import { importBundleWrite } from "./handlers/import-bundle.write.js";
+import { importBundleSystemWrite } from "./handlers/import-bundle-system.write.js";
+import { layoutSourceQuery } from "./handlers/layout-source.query.js";
 import { listQuery } from "./handlers/list.query.js";
+import { overviewQuery } from "./handlers/overview.query.js";
+import { previewQuery } from "./handlers/preview.query.js";
+import { resetToSystemWrite } from "./handlers/reset-to-system.write.js";
+import { resourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.js";
+import { resourceRemoveWrite } from "./handlers/resource-remove.write.js";
+import { resourceUploadWrite } from "./handlers/resource-upload.write.js";
+import { sendTestWrite } from "./handlers/send-test.write.js";
 import { setWrite } from "./handlers/set.write.js";
-import { archiveWrite, publishWrite } from "./handlers/toggle-status.write.js";
+import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.js";
+import { archiveSystemWrite, archiveWrite, publishSystemWrite, publishWrite, } from "./handlers/toggle-status.write.js";
 import { upsertSystemWrite } from "./handlers/upsert-system.write.js";
 import { upsertTenantWrite } from "./handlers/upsert-tenant.write.js";
+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";
 export function createTemplateResolverFeature(opts = {}) {
@@ -17,11 +33,14 @@ export function createTemplateResolverFeature(opts = {}) {
     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-html`, `document-pdf`, `ai-prompt`, `text-block`, `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.",
+            "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`.",
             "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.',
+            "`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.",
+            "`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted.",
+            'Images used by a template (`<img data-resource="logo">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: "attachment"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail\'s own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.',
             "Replaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
         ].join("\n\n"));
         r.uiHints({
@@ -29,6 +48,11 @@ export function createTemplateResolverFeature(opts = {}) {
             category: "notifications",
             recommended: false,
         });
+        r.config({
+            keys: {
+                resourceMaxBytes: createSystemConfig("number", { default: 2_097_152, bounds: { min: 1 } }),
+            },
+        });
         r.entity("template-resource", templateResourceEntity);
         // Only when the app actually mounts a user-owned collection: the entity's
         // `content` is `userOwned`, which makes it subject data — the boot guard
@@ -41,13 +65,31 @@ export function createTemplateResolverFeature(opts = {}) {
             upsertTenant: r.writeHandler(upsertTenantWrite),
             publish: r.writeHandler(publishWrite),
             archive: r.writeHandler(archiveWrite),
+            publishSystem: r.writeHandler(publishSystemWrite),
+            archiveSystem: r.writeHandler(archiveSystemWrite),
+            resetToSystem: r.writeHandler(resetToSystemWrite),
             set: r.writeHandler(setWrite),
+            importBundle: r.writeHandler(importBundleWrite),
+            importBundleSystem: r.writeHandler(importBundleSystemWrite),
+            copyLocale: r.writeHandler(copyLocaleWrite),
+            resourceUpload: r.writeHandler(resourceUploadWrite),
+            resourceRemove: r.writeHandler(resourceRemoveWrite),
+            resourceLinkPdf: r.writeHandler(resourceLinkPdfWrite),
+            sendTest: r.writeHandler(sendTestWrite),
         };
         const queries = {
             findById: r.queryHandler(findByIdQuery),
             list: r.queryHandler(listQuery),
             bySlug: r.queryHandler(bySlugQuery),
             byTenant: r.queryHandler(byTenantQuery),
+            usage: r.queryHandler(usageQuery),
+            overview: r.queryHandler(overviewQuery),
+            layoutSource: r.queryHandler(layoutSourceQuery),
+            tenantOverrides: r.queryHandler(tenantOverridesQuery),
+            diffToSystem: r.queryHandler(diffToSystemQuery),
+            validate: r.queryHandler(validateQuery),
+            preview: r.queryHandler(previewQuery),
+            exportBundle: r.queryHandler(exportBundleQuery),
         };
         for (const collection of collections) {
             r.contentCollection(collection);
@@ -58,10 +100,12 @@ export function createTemplateResolverFeature(opts = {}) {
         // Visual-tree actions for the text-block content tree. The handle is
         // propagated through the setup export so other features can build
         // compile-time-typed cross-feature edit targets.
+        // r.treeActions keeps literal types (const generic); the args only declare string-typed slots.
+        const emptyString = "";
         const treeHandle = r.treeActions({
-            edit: { args: { slug: "", locale: "" } },
+            edit: { args: { slug: emptyString, locale: emptyString } },
             list: {},
-            create: { args: { folder: "" } },
+            create: { args: { folder: emptyString } },
         });
         return { handlers, queries, treeHandle };
     });