@cosmicdrift/kumiko-bundled-features 0.362.0 → 0.363.0

package/dist/template-resolver/template-preview.js

@@ -0,0 +1,374 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { NotFoundError, UnprocessableError, ValidationError, } from "@cosmicdrift/kumiko-framework/errors";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { createEmailAttachmentReader, createTemplateMailRenderer } from "../delivery/index.js";
+import { fileContextForTenant } from "../file-foundation/index.js";
+import { collectRendererPlugins, createRendererFoundationApi, RendererError, } from "../renderer-foundation/index.js";
+import { createTemplateResolverApi, TemplateNotFoundError } from "./api.js";
+import { collectDocumentResourceKeys } from "./compile-document-body.js";
+import { MAIL_PREVIEW_MAX_BYTES, SYSTEM_TENANT_ID } from "./constants.js";
+import { parseStoredJson } from "./handlers/template-gates.js";
+import { validateTemplateDraft } from "./handlers/validate.query.js";
+import { readLayoutRegions, sanitizeLayoutHtml } from "./layout-regions.js";
+import { parseLinkedResourceEntries } from "./linked-resources.js";
+import { buildDisplayHtml } from "./preview-display-html.js";
+import { TemplateResolverErrors } from "./qualified-names.js";
+import { templateResourcesTable } from "./table.js";
+import { isMailTemplateMeta, parseTemplateMeta, readPdfTemplateMeta, } from "./template-meta.js";
+const SAMPLE_LINK = "https://example.com";
+const SAMPLE_DATE = "2026-01-15";
+const SAMPLE_LIST_ROWS = 2;
+const DEFAULT_PDF_LAYOUT_SLUG = "default";
+function sampleScalar(name, def) {
+    if (def.example !== undefined)
+        return def.example;
+    switch (def.type) {
+        case "text":
+            return `[${def.label ?? name}]`;
+        case "link":
+            return SAMPLE_LINK;
+        case "money":
+            return 0;
+        case "date":
+            return SAMPLE_DATE;
+    }
+}
+function sampleRow(item, given = {}) {
+    const row = {};
+    for (const [name, def] of Object.entries(item))
+        row[name] = sampleScalar(name, def);
+    return { ...row, ...given };
+}
+function sampleList(def) {
+    const rows = (def.example ?? [])
+        .slice(0, SAMPLE_LIST_ROWS)
+        .map((given) => sampleRow(def.item, given));
+    while (rows.length < SAMPLE_LIST_ROWS)
+        rows.push(sampleRow(def.item));
+    return rows;
+}
+// Declared examples win; the fallbacks are deterministic so a preview never differs between calls.
+export function sampleValuesFor(variables) {
+    const values = {};
+    for (const [name, def] of Object.entries(variables)) {
+        values[name] = def.type === "list" ? sampleList(def) : sampleScalar(name, def);
+    }
+    return values;
+}
+const utf8Bytes = (value) => new TextEncoder().encode(value).length;
+const failed = (error) => ({ ok: false, error });
+async function loadStoredDraft(ctx, user, input) {
+    try {
+        return await createTemplateResolverApi(ctx.db).resolveTemplate({
+            tenantId: user.tenantId,
+            slug: input.slug,
+            kind: input.kind,
+            locale: input.locale,
+        });
+    }
+    catch (e) {
+        if (e instanceof TemplateNotFoundError)
+            return null;
+        throw e;
+    }
+}
+async function describeAttachments(ctx, refs) {
+    const fileRefIds = refs.flatMap((ref) => (ref.kind === "rendered-pdf" ? [] : [ref.fileRefId]));
+    const rows = fileRefIds.length === 0
+        ? []
+        : await selectMany(ctx.db, fileRefsTable, {
+            id: fileRefIds,
+        });
+    const sizeById = new Map(rows.map((row) => [row.id, Number(row.size)]));
+    // An inline image is named by its content id because the stored file name is personal data and
+    // may be ciphertext; a file attachment carries the name the admin gave it.
+    return refs.map((ref) => previewAttachmentOf(ref, sizeById));
+}
+function previewAttachmentOf(ref, sizeById) {
+    switch (ref.kind) {
+        case "inline":
+            return {
+                kind: "inline",
+                cid: ref.cid,
+                name: ref.cid,
+                sizeBytes: sizeById.get(ref.fileRefId) ?? 0,
+            };
+        case "file":
+            return { kind: "file", name: ref.fileName, sizeBytes: sizeById.get(ref.fileRefId) ?? 0 };
+        case "rendered-pdf":
+            return { kind: "rendered-pdf", name: ref.fileName, templateSlug: ref.templateSlug };
+    }
+}
+const attachmentSizeOf = (attachment) => attachment.kind === "rendered-pdf" ? 0 : attachment.sizeBytes;
+// The row an editor is working on, whatever its status: the stored template only resolves when
+// active, so a draft would otherwise lose the images and attachments uploaded to it.
+async function loadEditedRowResources(ctx, user, input) {
+    const rows = await selectMany(ctx.db, templateResourcesTable, { tenantId: user.tenantId, slug: input.slug, kind: "mail", locale: input.locale }, { limit: 1 });
+    const row = rows[0];
+    return row === undefined ? undefined : parseLinkedResourceEntries(row.linkedResources);
+}
+async function resolvePdfLayout(ctx, user, slug, locale) {
+    const api = createTemplateResolverApi(ctx.db);
+    const find = async (tenantId) => {
+        try {
+            return await api.resolveLayout({ tenantId, slug, kind: "pdf-layout", locale });
+        }
+        catch (e) {
+            if (e instanceof TemplateNotFoundError)
+                return null;
+            throw e;
+        }
+    };
+    let layout = await find(user.tenantId);
+    let html = layout?.content ?? "";
+    if (layout !== null && layout.scope !== "system") {
+        // Re-checked like the mail renderer does: a tenant row that predates the write gate must not pass.
+        const sanitized = sanitizeLayoutHtml(html);
+        if (sanitized.ok)
+            html = sanitized.html;
+        else {
+            layout = await find(SYSTEM_TENANT_ID);
+            html = layout?.content ?? "";
+        }
+    }
+    if (layout === null)
+        return null;
+    return { slug, scope: layout.scope, html, regions: readLayoutRegions(html) };
+}
+function missingResourceCheck(missing) {
+    return {
+        code: "resources_resolved",
+        ok: missing.length === 0,
+        i18nKey: "templateResolver.checks.resourcesResolved",
+        params: { missing },
+    };
+}
+function requiredPlaceholdersCheck(missing) {
+    return {
+        code: "required_placeholders",
+        ok: missing.length === 0,
+        i18nKey: "templateResolver.checks.requiredPlaceholders",
+        params: { missing },
+    };
+}
+function toRenderFailure(e) {
+    if (!(e instanceof RendererError))
+        throw e;
+    return failed(new UnprocessableError(TemplateResolverErrors.previewRenderFailed, {
+        i18nKey: "templateResolver.errors.preview.renderFailed",
+        details: { code: e.code },
+    }));
+}
+// Only a plugin that prints documents can show the filled-in page; without one the editor
+// still gets the body and the raw layout, just without placeholder values.
+function documentPreviewPlugin(ctx, tenantId) {
+    try {
+        const plugin = createRendererFoundationApi(collectRendererPlugins(ctx.registry)).createRendererForTenant({ tenantId, kind: "document-pdf" });
+        return plugin.previewDocument === undefined ? null : plugin;
+    }
+    catch (e) {
+        if (e instanceof RendererError && e.code === "no_plugin_for_kind")
+            return null;
+        throw e;
+    }
+}
+async function renderDocumentPreview(ctx, user, args) {
+    const { input, content, meta, validation, sampleValues } = args;
+    const pdfMeta = meta.ok ? readPdfTemplateMeta(meta.meta) : null;
+    const requiredCheck = requiredPlaceholdersCheck(validation.missingRequired);
+    const plugin = documentPreviewPlugin(ctx, user.tenantId);
+    if (plugin?.previewDocument === undefined) {
+        return {
+            ok: true,
+            mailAttachments: [],
+            preview: {
+                kind: "document-pdf",
+                subject: null,
+                previewText: null,
+                html: content,
+                text: null,
+                attachments: [],
+                layout: await resolvePdfLayout(ctx, user, pdfMeta?.layoutSlug ?? DEFAULT_PDF_LAYOUT_SLUG, input.locale),
+                sampleValues,
+                checks: [missingResourceCheck(validation.warnings.map((w) => w.detail)), requiredCheck],
+                validation,
+            },
+        };
+    }
+    let document;
+    try {
+        document = await plugin.previewDocument({
+            slug: input.slug,
+            locale: input.locale,
+            variables: sampleValues,
+            draft: { content, meta: pdfMeta, variableSchema: args.variableSchema },
+        }, {
+            db: ctx.db,
+            registry: ctx.registry,
+            tenantId: user.tenantId,
+            ...(ctx.config !== undefined && { config: ctx.config }),
+            filesForTenant: (fileTenantId) => fileContextForTenant(ctx, fileTenantId),
+        });
+    }
+    catch (e) {
+        return toRenderFailure(e);
+    }
+    const layout = document.layout;
+    return {
+        ok: true,
+        mailAttachments: [],
+        preview: {
+            kind: "document-pdf",
+            subject: null,
+            previewText: null,
+            html: document.bodyHtml,
+            text: null,
+            attachments: [],
+            layout: layout === null
+                ? null
+                : {
+                    slug: layout.slug,
+                    scope: layout.scope,
+                    html: `${layout.headerHtml}${layout.signatureHtml}${layout.footerHtml}`,
+                    regions: {
+                        header: layout.headerHtml,
+                        signature: layout.signatureHtml,
+                        footer: layout.footerHtml,
+                    },
+                },
+            sampleValues,
+            checks: [missingResourceCheck(document.missingResourceKeys), requiredCheck],
+            validation,
+        },
+    };
+}
+// A document draft is always tenant-scoped here, like in the preview: it passes the write gates
+// and a failing draft is rejected with the same problems as a save.
+export async function evaluateDocumentDraft(ctx, user, draft) {
+    const { response, evaluation } = await validateTemplateDraft(ctx, user, {
+        slug: draft.slug,
+        kind: "document-pdf",
+        contentFormat: "html",
+        content: draft.content,
+        meta: draft.meta,
+        variableSchema: draft.variableSchema,
+        locale: draft.locale,
+        scope: "tenant",
+    });
+    if (!evaluation.ok) {
+        return { ok: false, error: new ValidationError({ fields: [...evaluation.issues] }) };
+    }
+    const meta = parseTemplateMeta("document-pdf", parseStoredJson(evaluation.metaJson));
+    return {
+        ok: true,
+        content: evaluation.content ?? "",
+        meta: meta.ok ? readPdfTemplateMeta(meta.meta) : null,
+        variableSchema: draft.variableSchema,
+        sampleValues: sampleValuesFor(response.variables),
+    };
+}
+// Renders a draft (or, without content, the stored template) with sample values, going through
+// the same write gates and the same mail renderer as a real send. Nothing is stored or sent.
+export async function renderTemplatePreview(ctx, user, input) {
+    let draftContent = input.content;
+    let draftMeta = input.meta;
+    let draftVariableSchema = input.variableSchema;
+    if (draftContent === undefined) {
+        const stored = await loadStoredDraft(ctx, user, input);
+        if (stored === null)
+            return failed(new NotFoundError("template-resource", input.slug));
+        draftContent = stored.content;
+        draftMeta = stored.meta;
+        draftVariableSchema = stored.variableSchema;
+    }
+    const { response: validation, evaluation } = await validateTemplateDraft(ctx, user, {
+        slug: input.slug,
+        kind: input.kind,
+        contentFormat: "html",
+        content: draftContent,
+        meta: draftMeta,
+        variableSchema: draftVariableSchema,
+        locale: input.locale,
+        scope: "tenant",
+    });
+    if (!evaluation.ok)
+        return failed(new ValidationError({ fields: [...evaluation.issues] }));
+    const content = evaluation.content ?? "";
+    const meta = parseTemplateMeta(input.kind, parseStoredJson(evaluation.metaJson));
+    const sampleValues = sampleValuesFor(validation.variables);
+    if (input.kind === "document-pdf") {
+        return renderDocumentPreview(ctx, user, {
+            input,
+            content,
+            meta,
+            variableSchema: draftVariableSchema,
+            sampleValues,
+            validation,
+        });
+    }
+    if (!meta.ok || !isMailTemplateMeta(meta.meta)) {
+        return failed(new UnprocessableError(TemplateResolverErrors.previewRenderFailed, {
+            i18nKey: "templateResolver.errors.preview.renderFailed",
+            details: { code: "invalid_meta" },
+        }));
+    }
+    const mailMeta = meta.meta;
+    const editedResources = input.content === undefined ? undefined : await loadEditedRowResources(ctx, user, input);
+    let rendered;
+    try {
+        rendered = await createTemplateMailRenderer(ctx.db, ctx.registry, user.tenantId, ctx.config)({
+            slug: input.slug,
+            locale: input.locale,
+            variables: sampleValues,
+            draft: {
+                content,
+                meta: mailMeta,
+                variableSchema: draftVariableSchema,
+                ...(editedResources !== undefined && { linkedResources: editedResources }),
+            },
+        });
+    }
+    catch (e) {
+        return toRenderFailure(e);
+    }
+    const mailAttachments = rendered.attachments ?? [];
+    const inline = mailAttachments.filter((ref) => ref.kind === "inline");
+    const attachments = await describeAttachments(ctx, mailAttachments);
+    const displayHtml = await buildDisplayHtml(rendered.html, inline, createEmailAttachmentReader(ctx.db, ctx.registry, user.tenantId, ctx.config, (tenantId) => fileContextForTenant(ctx, tenantId)));
+    const resolvedCids = new Set(inline.map((ref) => ref.cid));
+    const unresolved = collectDocumentResourceKeys(content).filter((key) => !resolvedCids.has(key));
+    const totalBytes = utf8Bytes(rendered.html) +
+        utf8Bytes(rendered.text) +
+        attachments.reduce((sum, attachment) => sum + attachmentSizeOf(attachment), 0);
+    return {
+        ok: true,
+        mailAttachments,
+        preview: {
+            kind: "mail",
+            subject: rendered.subject,
+            previewText: rendered.previewText ?? null,
+            html: rendered.html,
+            displayHtml,
+            text: rendered.text,
+            attachments,
+            layout: null,
+            sampleValues,
+            checks: [
+                missingResourceCheck(unresolved),
+                {
+                    code: "text_present",
+                    ok: rendered.text.trim() !== "",
+                    i18nKey: "templateResolver.checks.textPresent",
+                },
+                {
+                    code: "size_under_cap",
+                    ok: totalBytes <= MAIL_PREVIEW_MAX_BYTES,
+                    i18nKey: "templateResolver.checks.sizeUnderCap",
+                    params: { totalBytes, maxBytes: MAIL_PREVIEW_MAX_BYTES },
+                },
+                requiredPlaceholdersCheck(validation.missingRequired),
+            ],
+            validation,
+        },
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { HandlerContext, SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
+import type { LinkedResourceEntry } from "./linked-resources.js";
+export type TemplateResourceFile = {
+    readonly fileName: string;
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+};
+export declare function readTemplateResource(ctx: Pick<HandlerContext, "db" | "files" | "user">, fileRefId: string): Promise<TemplateResourceFile | null>;
+export declare function attachTemplateResources(ctx: Pick<HandlerContext, "forTenant">, args: {
+    readonly user: SessionUser;
+    readonly tenantId: TenantId;
+    readonly templateId: string;
+    readonly resources: Readonly<Record<string, LinkedResourceEntry>>;
+}): Promise<WriteResult<null>>;

package/dist/template-resolver/template-resources.js

@@ -0,0 +1,42 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import { requireForTenant } from "../shared/index.js";
+import { executor } from "./handlers/shared.js";
+import { templateResourcesTable } from "./table.js";
+// Reads the file behind a template resource. Null when the fileRef is unknown
+// to the caller's tenant or has no bytes.
+export async function readTemplateResource(ctx, fileRefId) {
+    if (!ctx.files)
+        return null;
+    const row = await fetchOne(ctx.db, fileRefsTable, {
+        id: fileRefId,
+        isDeleted: false,
+    });
+    // ctx.files only reaches the caller's own key space.
+    if (!row?.storageKey.startsWith(`${ctx.user.tenantId}/`))
+        return null;
+    const handle = ctx.files.ref(row.storageKey);
+    if (!(await handle.exists()))
+        return null;
+    return { fileName: row.fileName, contentType: row.mimeType, bytes: await handle.read() };
+}
+// Replaces the whole key map of one row with files that are already stored (bundle import,
+// copy-locale). Single keys go through storeTemplateResource and resource-remove.
+export async function attachTemplateResources(ctx, args) {
+    if (Object.keys(args.resources).length === 0)
+        return { isSuccess: true, data: null };
+    const { db, streamTenantId } = requireForTenant(ctx, args.tenantId);
+    const row = await fetchOne(db, templateResourcesTable, {
+        id: args.templateId,
+        tenantId: args.tenantId,
+    });
+    if (!row)
+        return writeFailure(new NotFoundError("template-resource", args.templateId));
+    const result = await executor.update({
+        id: row.id,
+        version: row.version,
+        changes: { linkedResources: JSON.stringify(args.resources) },
+    }, args.user, db, { streamTenantId });
+    return result.isSuccess ? { isSuccess: true, data: null } : result;
+}

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

@@ -0,0 +1,12 @@
+import { type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { type TemplateKind } from "./constants.js";
+type UsageRole = "template" | "layout";
+export type TemplateUsageEntry = {
+    readonly qualifiedName: string;
+    readonly feature: string;
+    readonly notification: string;
+    readonly trigger: string | null;
+    readonly role: UsageRole;
+};
+export declare function collectTemplateUsage(registry: Registry, slug: string, kind: TemplateKind): TemplateUsageEntry[];
+export {};

package/dist/template-resolver/template-usage.js

@@ -0,0 +1,30 @@
+import { parseQn } from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_MAIL_LAYOUT_SLUG } from "./constants.js";
+export function collectTemplateUsage(registry, slug, kind) {
+    const usedBy = [];
+    if (kind === "mail" || kind === "mail-layout") {
+        for (const [qualifiedName, notification] of registry.getAllNotifications()) {
+            const role = kind === "mail" ? "template" : "layout";
+            const isUsed = kind === "mail"
+                ? qualifiedName === slug
+                : [
+                    ...new Set([
+                        ...Object.keys(notification.template ?? {}),
+                        ...Object.keys(notification.meta ?? {}),
+                    ]),
+                ].some((locale) => (notification.meta?.[locale]?.layoutSlug ?? DEFAULT_MAIL_LAYOUT_SLUG) === slug);
+            if (!isUsed)
+                continue;
+            const parsed = parseQn(qualifiedName);
+            usedBy.push({
+                qualifiedName,
+                feature: parsed.scope,
+                notification: parsed.name,
+                trigger: notification.trigger?.on ?? null,
+                role,
+            });
+        }
+    }
+    usedBy.sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+    return usedBy;
+}

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

@@ -0,0 +1,22 @@
+import type { Registry, TemplateVariables } from "@cosmicdrift/kumiko-framework/engine";
+import type { TemplateMeta } from "./template-meta.js";
+export declare const SYSTEM_PLACEHOLDERS: ReadonlySet<string>;
+export declare function systemPlaceholdersFor(kind: string): ReadonlySet<string>;
+export type TemplateValidation = {
+    readonly unknown: readonly string[];
+    readonly missingRequired: readonly string[];
+    readonly used: readonly string[];
+    /** data-resource keys with no uploaded file; a warning, never a blocker. */
+    readonly unknownResources: readonly string[];
+};
+export declare function resolveTemplateVariables(registry: Registry, slug: string, variableSchema: Readonly<Record<string, unknown>>): TemplateVariables;
+export declare function variablesFromSchema(variableSchema: Readonly<Record<string, unknown>>): TemplateVariables;
+export declare function validateTemplatePlaceholders(input: {
+    readonly kind: string;
+    readonly body: string;
+    readonly meta: TemplateMeta | null;
+    readonly variables: TemplateVariables;
+    /** data-resource keys with an uploaded file besides the built-in `logo`. */
+    readonly resourceKeys?: readonly string[];
+}): TemplateValidation;
+export declare function hasPlaceholderProblems(validation: TemplateValidation): boolean;

package/dist/template-resolver/template-validation.js

@@ -0,0 +1,172 @@
+import * as z from "zod";
+import { withParsedDocument } from "./document-sanitizer.js";
+import { isDocumentPlaceholderHref, isDocumentReferenceName } from "./document-schema.js";
+export const SYSTEM_PLACEHOLDERS = new Set([
+    "tenantName",
+    "signature",
+    "imprint",
+    "unsubscribeUrl",
+]);
+const PAGE_PLACEHOLDERS = ["page", "pages"];
+const PAGED_KINDS = new Set(["document-pdf", "pdf-layout"]);
+export function systemPlaceholdersFor(kind) {
+    return PAGED_KINDS.has(kind)
+        ? new Set([...SYSTEM_PLACEHOLDERS, ...PAGE_PLACEHOLDERS])
+        : SYSTEM_PLACEHOLDERS;
+}
+const BASE_RESOURCE_KEYS = ["logo"];
+// Mirrors TemplateVariableDef: a stored or draft schema keeps its label and example, which the
+// preview uses as sample values.
+const variableCommon = {
+    label: z.string().optional(),
+    required: z.boolean().optional(),
+};
+const textLikeExample = z.string().optional();
+const scalarVariableSchema = z.discriminatedUnion("type", [
+    z.object({ ...variableCommon, type: z.literal("text"), example: textLikeExample }),
+    z.object({ ...variableCommon, type: z.literal("link"), example: textLikeExample }),
+    z.object({
+        ...variableCommon,
+        type: z.literal("money"),
+        example: z
+            .union([z.number(), z.object({ amount: z.number(), currency: z.string() })])
+            .optional(),
+    }),
+    z.object({ ...variableCommon, type: z.literal("date"), example: textLikeExample }),
+]);
+const variableDefSchema = z.union([
+    scalarVariableSchema,
+    z.object({
+        ...variableCommon,
+        type: z.literal("list"),
+        item: z.record(z.string(), scalarVariableSchema),
+        example: z.array(z.record(z.string(), z.unknown())).optional(),
+    }),
+]);
+// A stored variableSchema value is either a bare string (legacy "this is a text
+// variable") or a TemplateVariableDef object; anything else is not declared and
+// therefore shows up as an unknown placeholder instead of being guessed at.
+function toVariableDef(raw) {
+    if (typeof raw === "string")
+        return { type: "text" };
+    const parsed = variableDefSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+export function resolveTemplateVariables(registry, slug, variableSchema) {
+    const declared = registry.getAllNotifications().get(slug)?.variables;
+    return declared ?? variablesFromSchema(variableSchema);
+}
+export function variablesFromSchema(variableSchema) {
+    const variables = {};
+    for (const [name, raw] of Object.entries(variableSchema)) {
+        const def = toVariableDef(raw);
+        if (def !== null)
+            variables[name] = def;
+    }
+    return variables;
+}
+function rootName(name) {
+    return name.split(".")[0] ?? name;
+}
+function listItemFields(variables, listName) {
+    const def = listName !== null && Object.hasOwn(variables, listName) ? variables[listName] : undefined;
+    return def?.type === "list" ? def.item : {};
+}
+function isKnownName(name, scope, itemFields) {
+    const { variables } = scope;
+    const root = rootName(name);
+    if (Object.hasOwn(itemFields, name) || Object.hasOwn(itemFields, root)) {
+        return { known: true, used: "" };
+    }
+    if (scope.systemPlaceholders.has(root))
+        return { known: true, used: "" };
+    if (Object.hasOwn(variables, name))
+        return { known: true, used: name };
+    if (Object.hasOwn(variables, root))
+        return { known: true, used: root };
+    return { known: false, used: "" };
+}
+function recordName(name, itemFields, scope) {
+    const resolution = isKnownName(name, scope, itemFields);
+    if (!resolution.known)
+        scope.unknown.add(name);
+    else if (resolution.used !== "")
+        scope.used.add(resolution.used);
+}
+function enclosingEachName(element) {
+    return element.closest("tr[data-each]")?.getAttribute("data-each") ?? null;
+}
+function scanBodyPlaceholders(body, scope) {
+    withParsedDocument(body, (root) => {
+        for (const element of Array.from(root.querySelectorAll("tr[data-each]"))) {
+            const listName = element.getAttribute("data-each") ?? "";
+            const def = Object.hasOwn(scope.variables, listName) ? scope.variables[listName] : undefined;
+            if (def?.type === "list")
+                scope.used.add(listName);
+            else
+                scope.unknown.add(listName);
+        }
+        for (const element of Array.from(root.querySelectorAll("span[data-variable], a[href], img[data-resource]"))) {
+            const itemFields = listItemFields(scope.variables, enclosingEachName(element));
+            const tag = element.tagName.toLowerCase();
+            if (tag === "span") {
+                recordName(element.getAttribute("data-variable") ?? "", itemFields, scope);
+            }
+            else if (tag === "a") {
+                const href = element.getAttribute("href") ?? "";
+                if (isDocumentPlaceholderHref(href))
+                    recordName(href.slice(2, -2), itemFields, scope);
+            }
+            else {
+                const key = element.getAttribute("data-resource") ?? "";
+                if (!scope.resourceKeys.has(key))
+                    scope.unknownResources.add(key);
+            }
+        }
+    });
+}
+const HANDLEBARS_EXPRESSION = /\{\{([^{}]*)\}\}/g;
+// Meta text supports only plain `{{name}}` / `{{name.field}}`; every other
+// Handlebars construct is reported as unknown so it can never reach the compiler.
+function scanMetaPlaceholders(text, scope) {
+    const leftover = text.replace(HANDLEBARS_EXPRESSION, (_match, inner) => {
+        const name = inner.trim();
+        if (isDocumentReferenceName(name))
+            recordName(name, {}, scope);
+        else
+            scope.unknown.add(`{{${inner}}}`);
+        return "";
+    });
+    if (/[{}]/.test(leftover))
+        scope.unknown.add("{");
+}
+function metaTexts(meta) {
+    if (meta === null || !("subject" in meta))
+        return [];
+    return [meta.subject, ...(meta.previewText === undefined ? [] : [meta.previewText])];
+}
+export function validateTemplatePlaceholders(input) {
+    const scope = {
+        variables: input.variables,
+        systemPlaceholders: systemPlaceholdersFor(input.kind),
+        resourceKeys: new Set([...BASE_RESOURCE_KEYS, ...(input.resourceKeys ?? [])]),
+        used: new Set(),
+        unknown: new Set(),
+        unknownResources: new Set(),
+    };
+    scanBodyPlaceholders(input.body, scope);
+    for (const text of metaTexts(input.meta))
+        scanMetaPlaceholders(text, scope);
+    const missingRequired = Object.entries(input.variables)
+        .filter(([name, def]) => def.required === true && !scope.used.has(name))
+        .map(([name]) => name);
+    return {
+        unknown: [...scope.unknown].sort(),
+        missingRequired: missingRequired.sort(),
+        used: [...scope.used].sort(),
+        unknownResources: [...scope.unknownResources].sort(),
+    };
+}
+export function hasPlaceholderProblems(validation) {
+    return validation.unknown.length > 0 || validation.missingRequired.length > 0;
+}