@cosmicdrift/kumiko-samples 0.374.0 → 0.378.0

package/packages/bundled-features/src/template-resolver/feature.ts

@@ -3,41 +3,48 @@ import {
   createSystemConfig,
   defineFeature,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { isCollectionRefusedKind } from "./constants.ts";
+import { DEFAULT_COLLECTION_ACCESS, isCollectionRefusedKind } from "./constants.ts";
 import { bySlugQuery } from "./handlers/by-slug.query.ts";
 import { byTenantQuery } from "./handlers/by-tenant.query.ts";
 import { makeCollectionItemQuery } from "./handlers/collection-item.query.ts";
 import { makeCollectionListQuery } from "./handlers/collection-list.query.ts";
 import { makeCollectionSetWrite } from "./handlers/collection-set.write.ts";
-import { copyLocaleWrite } from "./handlers/copy-locale.write.ts";
+import { makeCopyLocaleWrite } from "./handlers/copy-locale.write.ts";
 import { diffToSystemQuery } from "./handlers/diff-to-system.query.ts";
-import { discardDraftSystemWrite, discardDraftWrite } from "./handlers/discard-draft.write.ts";
+import {
+  makeDiscardDraftSystemWrite,
+  makeDiscardDraftWrite,
+} from "./handlers/discard-draft.write.ts";
+import { documentBlocksQuery } from "./handlers/document-blocks.query.ts";
 import { exportBundleQuery } from "./handlers/export-bundle.query.ts";
 import { findByIdQuery } from "./handlers/find-by-id.query.ts";
-import { importBundleWrite } from "./handlers/import-bundle.write.ts";
+import { makeImportBundleWrite } from "./handlers/import-bundle.write.ts";
 import { importBundleSystemWrite } from "./handlers/import-bundle-system.write.ts";
 import { layoutSourceQuery } from "./handlers/layout-source.query.ts";
 import { listQuery } from "./handlers/list.query.ts";
-import { overviewQuery } from "./handlers/overview.query.ts";
+import { makeOverviewQuery } from "./handlers/overview.query.ts";
+import { makePatchDraftWrite } from "./handlers/patch-draft.write.ts";
 import { previewQuery } from "./handlers/preview.query.ts";
-import { resetToSystemWrite } from "./handlers/reset-to-system.write.ts";
-import { resourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.ts";
-import { resourceRemoveWrite } from "./handlers/resource-remove.write.ts";
-import { resourceUploadWrite } from "./handlers/resource-upload.write.ts";
-import { sendTestWrite } from "./handlers/send-test.write.ts";
-import { setWrite } from "./handlers/set.write.ts";
+import { makeResetToSystemWrite } from "./handlers/reset-to-system.write.ts";
+import { makeResourceLinkPdfWrite } from "./handlers/resource-link-pdf.write.ts";
+import { makeResourceRemoveWrite } from "./handlers/resource-remove.write.ts";
+import { makeResourceUploadWrite } from "./handlers/resource-upload.write.ts";
+import { makeSendTestWrite } from "./handlers/send-test.write.ts";
+import { sendTestStatusQuery } from "./handlers/send-test-status.query.ts";
+import { makeSetWrite } from "./handlers/set.write.ts";
 import { tenantOverridesQuery } from "./handlers/tenant-overrides.query.ts";
 import {
-  archiveSystemWrite,
-  archiveWrite,
-  publishSystemWrite,
-  publishWrite,
+  makeArchiveSystemWrite,
+  makeArchiveWrite,
+  makePublishSystemWrite,
+  makePublishWrite,
 } from "./handlers/toggle-status.write.ts";
 import { upsertSystemWrite } from "./handlers/upsert-system.write.ts";
-import { upsertTenantWrite } from "./handlers/upsert-tenant.write.ts";
+import { makeUpsertTenantWrite } from "./handlers/upsert-tenant.write.ts";
 import { usageQuery } from "./handlers/usage.query.ts";
 import { validateQuery } from "./handlers/validate.query.ts";
 import { templateResourceEntity } from "./table.ts";
+import type { TenantEditableTemplate } from "./template-edit-policy.ts";
 import { userContentEntryEntity } from "./user-content-table.ts";
 
 // template-resolver — structured template storage with tenant-override
@@ -59,6 +66,13 @@ export type TemplateResolverOptions = {
    *  access rule, so the dispatcher enforces the separation instead of a
    *  branch in a shared handler. */
   readonly collections?: readonly ContentCollectionDefinition[];
+  /** Templates a TenantAdmin may edit for the own tenant (override, draft, publish, archive,
+   *  reset, copy-locale, import, resources). Without an entry only a SystemAdmin edits.
+   *  A tenant-edited mail goes out under the platform's name, so the app opts in per
+   *  template instead of the framework guessing which ones a tenant may reword.
+   *  `access` is required: the host decides its role vocabulary here, like for
+   *  `collections`. SystemAdmin always passes. */
+  readonly tenantEditable?: readonly TenantEditableTemplate[];
 };
 
 function assertCollectionKindsAllowed(collections: readonly ContentCollectionDefinition[]): void {
@@ -71,20 +85,45 @@ function assertCollectionKindsAllowed(collections: readonly ContentCollectionDef
   }
 }
 
+function assertTenantEditableValid(entries: readonly TenantEditableTemplate[]): void {
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    const key = `${entry.kind}/${entry.slug}`;
+    if (seen.has(key)) {
+      throw new Error(`template-resolver: tenantEditable lists "${key}" twice`);
+    }
+    seen.add(key);
+    if (entry.slug.trim() === "") {
+      throw new Error(
+        `template-resolver: tenantEditable entry of kind "${entry.kind}" has an empty slug`,
+      );
+    }
+    if (entry.access.roles.length === 0) {
+      throw new Error(
+        `template-resolver: tenantEditable entry "${entry.kind}/${entry.slug}" has no roles in access`,
+      );
+    }
+  }
+}
+
 export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}) {
   const collections = opts.collections ?? [];
   assertCollectionKindsAllowed(collections);
+  const tenantEditable = opts.tenantEditable ?? [];
+  assertTenantEditableValid(tenantEditable);
+  const policy = { tenantEditable };
   const hasUserOwned = collections.some((c) => c.ownership === "user");
   return defineFeature("template-resolver", (r) => {
     r.describe(
       [
         "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).",
         "Reading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.",
+        'Editing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: "mail", slug: "status-update", access: { roles: ["TenantAdmin"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host\'s roles. Reading and delivery do not depend on it: a tenant override that exists is served. A collection mounted without `access` is SystemAdmin only.',
         "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.",
+        "`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. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address.",
         '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"),
@@ -108,22 +147,23 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
 
     const handlers = {
       upsertSystem: r.writeHandler(upsertSystemWrite),
-      upsertTenant: r.writeHandler(upsertTenantWrite),
-      publish: r.writeHandler(publishWrite),
-      archive: r.writeHandler(archiveWrite),
-      publishSystem: r.writeHandler(publishSystemWrite),
-      archiveSystem: r.writeHandler(archiveSystemWrite),
-      discardDraft: r.writeHandler(discardDraftWrite),
-      discardDraftSystem: r.writeHandler(discardDraftSystemWrite),
-      resetToSystem: r.writeHandler(resetToSystemWrite),
-      set: r.writeHandler(setWrite),
-      importBundle: r.writeHandler(importBundleWrite),
+      upsertTenant: r.writeHandler(makeUpsertTenantWrite(policy)),
+      publish: r.writeHandler(makePublishWrite(policy)),
+      archive: r.writeHandler(makeArchiveWrite(policy)),
+      publishSystem: r.writeHandler(makePublishSystemWrite(policy)),
+      archiveSystem: r.writeHandler(makeArchiveSystemWrite(policy)),
+      discardDraft: r.writeHandler(makeDiscardDraftWrite(policy)),
+      discardDraftSystem: r.writeHandler(makeDiscardDraftSystemWrite(policy)),
+      resetToSystem: r.writeHandler(makeResetToSystemWrite(policy)),
+      set: r.writeHandler(makeSetWrite(policy)),
+      importBundle: r.writeHandler(makeImportBundleWrite(policy)),
       importBundleSystem: r.writeHandler(importBundleSystemWrite),
-      copyLocale: r.writeHandler(copyLocaleWrite),
-      resourceUpload: r.writeHandler(resourceUploadWrite),
-      resourceRemove: r.writeHandler(resourceRemoveWrite),
-      resourceLinkPdf: r.writeHandler(resourceLinkPdfWrite),
-      sendTest: r.writeHandler(sendTestWrite),
+      copyLocale: r.writeHandler(makeCopyLocaleWrite(policy)),
+      resourceUpload: r.writeHandler(makeResourceUploadWrite(policy)),
+      resourceRemove: r.writeHandler(makeResourceRemoveWrite(policy)),
+      resourceLinkPdf: r.writeHandler(makeResourceLinkPdfWrite(policy)),
+      sendTest: r.writeHandler(makeSendTestWrite(policy)),
+      patchDraft: r.writeHandler(makePatchDraftWrite(policy)),
     };
 
     const queries = {
@@ -132,17 +172,22 @@ export function createTemplateResolverFeature(opts: TemplateResolverOptions = {}
       bySlug: r.queryHandler(bySlugQuery),
       byTenant: r.queryHandler(byTenantQuery),
       usage: r.queryHandler(usageQuery),
-      overview: r.queryHandler(overviewQuery),
+      overview: r.queryHandler(makeOverviewQuery(policy)),
       layoutSource: r.queryHandler(layoutSourceQuery),
       tenantOverrides: r.queryHandler(tenantOverridesQuery),
       diffToSystem: r.queryHandler(diffToSystemQuery),
       validate: r.queryHandler(validateQuery),
       preview: r.queryHandler(previewQuery),
+      documentBlocks: r.queryHandler(documentBlocksQuery),
       exportBundle: r.queryHandler(exportBundleQuery),
+      sendTestStatus: r.queryHandler(sendTestStatusQuery),
     };
 
     for (const collection of collections) {
-      r.contentCollection(collection);
+      r.contentCollection({
+        ...collection,
+        access: collection.access ?? DEFAULT_COLLECTION_ACCESS,
+      });
       r.queryHandler(makeCollectionListQuery(collection));
       r.queryHandler(makeCollectionItemQuery(collection));
       r.writeHandler(makeCollectionSetWrite(collection));

package/packages/bundled-features/src/template-resolver/handlers/bundle-import.ts

@@ -214,6 +214,7 @@ export async function importTemplateBundle(
       contentFormat: args.bundle.contentFormat,
       variableSchema,
       meta: entry.meta,
+      ...(entry.title !== undefined && { title: entry.title }),
     };
     const written = await writeTemplateRow({
       ctx: args.ctx,

package/packages/bundled-features/src/template-resolver/handlers/collection-item.query.ts

@@ -4,10 +4,10 @@ import {
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { DEFAULT_COLLECTION_ACCESS } from "../constants.ts";
 import {
   type CollectionEntryRow,
   collectionStore,
-  DEFAULT_COLLECTION_ACCESS,
   toCollectionEntry,
 } from "./collection-shared.ts";
 

package/packages/bundled-features/src/template-resolver/handlers/collection-list.query.ts

@@ -4,10 +4,10 @@ import {
   defineQueryHandler,
 } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { DEFAULT_COLLECTION_ACCESS } from "../constants.ts";
 import {
   type CollectionEntryRow,
   collectionStore,
-  DEFAULT_COLLECTION_ACCESS,
   toCollectionEntry,
 } from "./collection-shared.ts";
 

package/packages/bundled-features/src/template-resolver/handlers/collection-set.write.ts

@@ -7,13 +7,9 @@ import {
 import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { requireForTenant } from "../../shared/index.ts";
-import { isCollectionRefusedKind } from "../constants.ts";
+import { DEFAULT_COLLECTION_ACCESS, isCollectionRefusedKind } from "../constants.ts";
 import { documentViolationsToFieldIssues, sanitizeTemplateBody } from "../document-sanitizer.ts";
-import {
-  type CollectionEntryRow,
-  collectionStore,
-  DEFAULT_COLLECTION_ACCESS,
-} from "./collection-shared.ts";
+import { type CollectionEntryRow, collectionStore } from "./collection-shared.ts";
 import { contentFormatSchema, folderSchema, localeSchema, slugSchema } from "./shared.ts";
 
 // Upsert inside one collection. Mirrors set.write for text-blocks, but the

package/packages/bundled-features/src/template-resolver/handlers/collection-shared.ts

@@ -1,7 +1,6 @@
 import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import type {
-  AccessRule,
   ContentCollectionDefinition,
   SessionUser,
   TenantId,
@@ -11,11 +10,6 @@ import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { templateResourceEntity, templateResourcesTable } from "../table.ts";
 import { userContentEntriesTable, userContentEntryEntity } from "../user-content-table.ts";
 
-// Applies when an app mounts a collection without saying who may reach it.
-// Deliberately narrow: a collection whose access nobody decided should be
-// invisible to normal users rather than open by default.
-export const DEFAULT_COLLECTION_ACCESS: AccessRule = { roles: ["TenantAdmin", "SystemAdmin"] };
-
 const templateExecutor = createEventStoreExecutor(templateResourcesTable, templateResourceEntity, {
   entityName: "template-resource",
 });

package/packages/bundled-features/src/template-resolver/handlers/copy-locale.write.ts

@@ -25,6 +25,11 @@ import {
 } from "../store-template-resource.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
 import { toWorkingRow, type WorkingRow } from "../template-draft.ts";
+import {
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+  templateEditAccess,
+} from "../template-edit-policy.ts";
 import { attachTemplateResources } from "../template-resources.ts";
 import { resolveTemplateVariables } from "../template-validation.ts";
 import { targetExistsIssue } from "./bundle-import.ts";
@@ -97,6 +102,7 @@ type CopyRequest = {
 // Runs before the upload (reject early, store nothing) and again in the transaction on the fresh rows.
 async function checkCopyRequest(
   ctx: WriteCtx,
+  policy: TemplateEditPolicy,
   event: {
     readonly user: SessionUser;
     readonly payload: z.infer<typeof copyLocaleSchema>;
@@ -113,6 +119,7 @@ async function checkCopyRequest(
   }
   const tenantId = scope === "system" ? SYSTEM_TENANT_ID : event.user.tenantId;
   const refused =
+    (scope === "tenant" ? refuseTemplateEdit(policy, event.user, { slug, kind }) : null) ??
     refuseTenantScopeUnderSystemTenant(scope, tenantId) ??
     refuseSystemOnlyTenantOverride(ctx.registry, scope, slug, kind);
   if (refused !== null) return refused;
@@ -155,62 +162,64 @@ async function checkCopyRequest(
   };
 }
 
-export const copyLocaleWrite = defineWriteHandler({
-  name: "copy-locale",
-  schema: copyLocaleSchema,
-  access: { roles: ["TenantAdmin", "SystemAdmin"] },
-  description:
-    "Copies the text of one locale of a template into another locale as a draft override of the caller's tenant, taking the tenant's own row or else the system default as the source; use it as the starting point for a translation. It refuses an existing target unless overwrite is set. With scope system (SystemAdmin only) both source and target are system-default rows and the target lands as a system draft; any other caller gets a 403.",
-  beforeTransaction: async (event, ctx) => {
-    const request = await checkCopyRequest(ctx, event);
-    if (!request.isSuccess) return request;
-    if (!request.data.sourceIsForeign) return { isSuccess: true, data: [] };
-    return prepareLinkedResourceCopiesBeforeTransaction({
-      ctx,
-      user: event.user,
-      tenantId: request.data.tenantId,
-      resources: request.data.sourceResources,
-    });
-  },
-  handler: async (event, ctx) => {
-    const { slug, kind, toLocale } = event.payload;
-    const request = await checkCopyRequest(ctx, event);
-    if (!request.isSuccess) return request;
-    const { scope, tenantId, source, contentFormat, sourceResources, sourceIsForeign } =
-      request.data;
+export function makeCopyLocaleWrite(policy: TemplateEditPolicy) {
+  return defineWriteHandler({
+    name: "copy-locale",
+    schema: copyLocaleSchema,
+    access: templateEditAccess(policy.tenantEditable),
+    description:
+      "Copies the text of one locale of a template into another locale as a draft override of the caller's tenant, taking the tenant's own row or else the system default as the source; use it as the starting point for a translation. It refuses an existing target unless overwrite is set. With scope system (SystemAdmin only) both source and target are system-default rows and the target lands as a system draft; any other caller gets a 403. A TenantAdmin may copy only templates the app lists in tenantEditable, otherwise SystemAdmin only.",
+    beforeTransaction: async (event, ctx) => {
+      const request = await checkCopyRequest(ctx, policy, event);
+      if (!request.isSuccess) return request;
+      if (!request.data.sourceIsForeign) return { isSuccess: true, data: [] };
+      return prepareLinkedResourceCopiesBeforeTransaction({
+        ctx,
+        user: event.user,
+        tenantId: request.data.tenantId,
+        resources: request.data.sourceResources,
+      });
+    },
+    handler: async (event, ctx) => {
+      const { slug, kind, toLocale } = event.payload;
+      const request = await checkCopyRequest(ctx, policy, event);
+      if (!request.isSuccess) return request;
+      const { scope, tenantId, source, contentFormat, sourceResources, sourceIsForeign } =
+        request.data;
 
-    const variableSchema = storedRecord(source.variableSchema);
-    const written = await writeTemplateRow({
-      ctx,
-      user: event.user,
-      tenantId,
-      scope,
-      status: "draft",
-      variables: resolveTemplateVariables(ctx.registry, slug, variableSchema),
-      payload: {
-        slug,
-        kind,
-        locale: toLocale,
-        content: source.content,
-        contentFormat,
-        variableSchema,
-        meta: parseStoredJson(source.meta),
-        title: source.title,
-        folder: source.folder,
-      },
-    });
-    if (!written.isSuccess) return written;
-    const resources = sourceIsForeign
-      ? await createLinkedResourceCopies({ ctx, user: event.user, tenantId }, event.prepared)
-      : { isSuccess: true as const, data: sourceResources };
-    if (!resources.isSuccess) return resources;
-    const attached = await attachTemplateResources(ctx, {
-      user: event.user,
-      tenantId,
-      templateId: written.data.id,
-      resources: resources.data,
-    });
-    if (!attached.isSuccess) return attached;
-    return written;
-  },
-});
+      const variableSchema = storedRecord(source.variableSchema);
+      const written = await writeTemplateRow({
+        ctx,
+        user: event.user,
+        tenantId,
+        scope,
+        status: "draft",
+        variables: resolveTemplateVariables(ctx.registry, slug, variableSchema),
+        payload: {
+          slug,
+          kind,
+          locale: toLocale,
+          content: source.content,
+          contentFormat,
+          variableSchema,
+          meta: parseStoredJson(source.meta),
+          title: source.title,
+          folder: source.folder,
+        },
+      });
+      if (!written.isSuccess) return written;
+      const resources = sourceIsForeign
+        ? await createLinkedResourceCopies({ ctx, user: event.user, tenantId }, event.prepared)
+        : { isSuccess: true as const, data: sourceResources };
+      if (!resources.isSuccess) return resources;
+      const attached = await attachTemplateResources(ctx, {
+        user: event.user,
+        tenantId,
+        templateId: written.data.id,
+        resources: resources.data,
+      });
+      if (!attached.isSuccess) return attached;
+      return written;
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/handlers/discard-draft.write.ts

@@ -2,19 +2,36 @@ import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { TemplateResolverErrors } from "../qualified-names.ts";
+import {
+  refuseMissingTemplate,
+  refuseTemplateEdit,
+  type TemplateEditPolicy,
+} from "../template-edit-policy.ts";
 import { executor } from "./shared.ts";
 import { loadTargetRow, type StatusTarget, writeAccessFor } from "./toggle-status.write.ts";
 
-function createDiscardDraftHandler(name: string, target: StatusTarget, description: string) {
+function createDiscardDraftHandler(
+  policy: TemplateEditPolicy,
+  name: string,
+  target: StatusTarget,
+  description: string,
+) {
   return defineWriteHandler({
     name,
     schema: z.object({ id: z.string().min(1) }),
-    access: writeAccessFor(target),
+    access: writeAccessFor(target, policy),
     ...(target === "system" ? { agent: { risk: "high" as const } } : {}),
     description,
     handler: async (event, ctx) => {
       const { db, scoped, row } = await loadTargetRow(ctx, target, event.user, event.payload.id);
-      if (!row) return writeFailure(new NotFoundError("template-resource", event.payload.id));
+      if (!row) {
+        const refused = target === "own" ? refuseMissingTemplate(policy, event.user) : null;
+        return refused ?? writeFailure(new NotFoundError("template-resource", event.payload.id));
+      }
+      if (target === "own") {
+        const refused = refuseTemplateEdit(policy, event.user, row);
+        if (refused !== null) return refused;
+      }
       if (row.draft === null) {
         return writeFailure(
           new ValidationError({
@@ -40,13 +57,19 @@ function createDiscardDraftHandler(name: string, target: StatusTarget, descripti
   });
 }
 
-export const discardDraftWrite = createDiscardDraftHandler(
-  "discard-draft",
-  "own",
-  "Throws away the open draft of one template resource of the caller's tenant so the editor shows the active version again; the served version is untouched. Refused with no_draft when there is no draft.",
-);
-export const discardDraftSystemWrite = createDiscardDraftHandler(
-  "discard-draft-system",
-  "system",
-  "Throws away the open draft of one system-default template; the served version stays. SystemAdmin only, refused with no_draft when there is no draft.",
-);
+export function makeDiscardDraftWrite(policy: TemplateEditPolicy) {
+  return createDiscardDraftHandler(
+    policy,
+    "discard-draft",
+    "own",
+    "Throws away the open draft of one template resource of the caller's tenant so the editor shows the active version again; the served version is untouched. Refused with no_draft when there is no draft. Outside the templates the app lists in tenantEditable only a SystemAdmin may use it.",
+  );
+}
+export function makeDiscardDraftSystemWrite(policy: TemplateEditPolicy) {
+  return createDiscardDraftHandler(
+    policy,
+    "discard-draft-system",
+    "system",
+    "Throws away the open draft of one system-default template; the served version stays. SystemAdmin only, refused with no_draft when there is no draft.",
+  );
+}

package/packages/bundled-features/src/template-resolver/handlers/document-base.ts

@@ -0,0 +1,86 @@
+import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type HandlerContext,
+  type SessionUser,
+  SYSTEM_TENANT_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import type { DocumentHtmlKind } from "../constants.ts";
+import { type TemplateResourceRow, templateResourcesTable } from "../table.ts";
+import { isHiddenSystemDraft, toWorkingRow } from "../template-draft.ts";
+import { isSystemOnlyTemplateHiddenFrom } from "../template-system-only.ts";
+import { parseStoredJson } from "./template-gates.ts";
+
+export type DocumentBase = {
+  readonly scope: "tenant" | "system";
+  /** The stored row's own version, which counts every draft save. */
+  readonly version: number;
+};
+
+export type LoadedDocument = {
+  readonly rowId: string;
+  readonly base: DocumentBase;
+  readonly status: string;
+  readonly content: string;
+  readonly meta: Readonly<Record<string, unknown>>;
+  readonly variableSchema: Readonly<Record<string, unknown>>;
+  readonly title: string | null;
+  readonly folder: string | null;
+  readonly parentTemplateId: string | null;
+};
+
+function recordOrEmpty(raw: string | null): Readonly<Record<string, unknown>> {
+  const parsed = parseStoredJson(raw);
+  return isPlainObject(parsed) ? parsed : {};
+}
+
+// The version an editor works on: the caller's own row (its open draft if there is one),
+// else the served system default. A system default as base is what a patch copies into a tenant draft.
+export async function loadDocumentBase(
+  ctx: HandlerContext,
+  user: SessionUser,
+  where: { readonly slug: string; readonly kind: DocumentHtmlKind; readonly locale: string },
+): Promise<LoadedDocument | null> {
+  const own = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+    tenantId: user.tenantId,
+    ...where,
+  });
+  if (own !== undefined && !isSystemOnlyTemplateHiddenFrom(user, ctx.registry, own)) {
+    const working = toWorkingRow(own, user.tenantId);
+    return {
+      rowId: String(own.id),
+      base: { scope: own.scope === "system" ? "system" : "tenant", version: own.version },
+      status: working.status,
+      content: working.content ?? "",
+      meta: recordOrEmpty(working.meta),
+      variableSchema: recordOrEmpty(working.variableSchema),
+      title: working.title,
+      folder: working.folder,
+      parentTemplateId: working.parentTemplateId,
+    };
+  }
+  const system = await fetchOne<TemplateResourceRow>(ctx.db, templateResourcesTable, {
+    tenantId: SYSTEM_TENANT_ID,
+    scope: "system",
+    status: "active",
+    ...where,
+  });
+  if (
+    system === undefined ||
+    isHiddenSystemDraft(user, system) ||
+    isSystemOnlyTemplateHiddenFrom(user, ctx.registry, system)
+  ) {
+    return null;
+  }
+  return {
+    rowId: String(system.id),
+    base: { scope: "system", version: system.version },
+    status: system.status,
+    content: system.content ?? "",
+    meta: recordOrEmpty(system.meta),
+    variableSchema: recordOrEmpty(system.variableSchema),
+    title: system.title,
+    folder: system.folder,
+    parentTemplateId: String(system.id),
+  };
+}

package/packages/bundled-features/src/template-resolver/handlers/document-blocks.query.ts

@@ -0,0 +1,48 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { DOCUMENT_HTML_KINDS } from "../constants.ts";
+import { documentBlocksForKind } from "../document-blocks.ts";
+import { documentBlocksOf } from "../document-ops.ts";
+import { parseDocumentJson } from "../document-sanitizer.ts";
+import { resolveTemplateVariables } from "../template-validation.ts";
+import { loadDocumentBase } from "./document-base.ts";
+import { localeSchema, templateSlugSchema } from "./shared.ts";
+import { knownResourceKeysFor } from "./validate.query.ts";
+
+export const documentBlocksQuery = defineQueryHandler({
+  name: "document-blocks",
+  schema: z.object({
+    slug: templateSlugSchema,
+    kind: z.enum(DOCUMENT_HTML_KINDS),
+    locale: localeSchema,
+  }),
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  description:
+    "Reads a mail or PDF document template as a list of blocks with stable ids (b0, b1, ...) for structured editing: each block has its type (paragraph, heading, list, table, repeat, image, button, divider, pageBreak, steps), its text with {{name}} placeholders and its settings, plus the meta, the stored and effective variables (variablesDeclaredByFeature is true when a notification declares them, so they cannot be changed), the block types allowed for the kind and the uploaded image keys. It reads the caller's own version (the open draft if there is one), else the served system default; base carries the scope and version that patch-draft expects back.",
+  handler: async (query, ctx) => {
+    const { slug, kind, locale } = query.payload;
+    const loaded = await loadDocumentBase(ctx, query.user, { slug, kind, locale });
+    if (loaded === null) throw new NotFoundError("template-resource", slug);
+    return {
+      slug,
+      kind,
+      locale,
+      base: loaded.base,
+      status: loaded.status,
+      blocks: documentBlocksOf(parseDocumentJson(loaded.content)),
+      meta: loaded.meta,
+      variableSchema: loaded.variableSchema,
+      variables: resolveTemplateVariables(ctx.registry, slug, loaded.variableSchema),
+      variablesDeclaredByFeature:
+        ctx.registry.getAllNotifications().get(slug)?.variables !== undefined,
+      allowedBlocks: documentBlocksForKind(kind),
+      resourceKeys: await knownResourceKeysFor(ctx, query.user, {
+        slug,
+        kind,
+        scope: "tenant",
+        locale,
+      }),
+    };
+  },
+});