@cosmicdrift/kumiko-samples 0.374.0 → 0.378.0

package/packages/bundled-features/src/mail-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Email sending offers a platform default and an own SMTP server",
+    "detail": "The provider field is labelled \"Send via\" with the options \"Platform sending (default)\" (empty, saved as \"\") and \"Own SMTP server\"; the SMTP fields show only while the own server is picked."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/mail-foundation/feature.ts

@@ -58,34 +58,33 @@ export const MAIL_TRANSPORT_EXTENSION = "mailTransport" as const;
 // =============================================================================
 
 /**
- * Schmaler Surface-Type fuer Transport-Plugins — gespiegelt von
- * file-foundation's FileProviderContext. HandlerContext ist zu fett
- * (haelt tx, actor, signal etc.); Plugins beschraenken sich auf die
- * read-Felder die fuer Tenant-Config + Secret-Lookup noetig sind.
+ * Narrow surface type for transport plugins, mirroring file-foundation's
+ * FileProviderContext. HandlerContext carries tx, actor, signal and more;
+ * plugins only get the read fields needed for tenant config and secret lookup.
  *
- * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job-getriggerte
- * Transport-Builds, z.B. der user-data-rights forget/export-Cron) gibt es
- * keinen per-request `config`/`tx`/`actor` — der Wrapper baut den per-Tenant-
- * ConfigAccessor aus `ctx.configResolver`. Ein Plugin das `ctx.tx` oder
- * andere request-only-Felder liest, wuerde den Worker-Pfad zur Runtime
- * brechen — und das fiele NUR mit echtem SMTP und nur in production auf.
- * Cast `ctx as unknown as HandlerContext` macht den Compiler happy, fliegt
- * aber zur Runtime im Worker. Plugin das mehr braucht: MailTransportContext
- * explizit erweitern (sichtbarer breaking change) statt ctx-cast.
+ * **Why not the full HandlerContext?** On the worker path (transport builds
+ * triggered by r.job, such as the user-data-rights forget/export cron) there
+ * is no per-request `config`/`tx`/`actor`; the wrapper builds the per-tenant
+ * ConfigAccessor from `ctx.configResolver`. A plugin reading `ctx.tx` or other
+ * request-only fields would break the worker path at runtime, and that would
+ * only show up with real SMTP in production. Casting
+ * `ctx as unknown as HandlerContext` satisfies the compiler but fails at
+ * runtime in the worker. A plugin that needs more extends MailTransportContext
+ * explicitly (a visible breaking change) instead of casting ctx.
  *
- * **Felder:**
- *   config   — tenant-config-reads (host/port/from/... der Plugins)
- *   registry — extension-Lookup in der Factory (nicht plugin-intern)
- *   secrets  — tenant-secret-reads (smtp.password)
- *   _userId  — Audit-Identity fuer secret-reads. Handler-Pfad: dispatcher
- *              setzt Caller-User-ID; Worker-Pfad: r.job-Wrap setzt eine
- *              System-Identity.
+ * **Fields:**
+ *   config      — tenant config reads (the plugin's host/port/from/...)
+ *   registry    — extension lookup in the factory (not plugin-internal)
+ *   secrets     — tenant secret reads (smtp.password)
+ *   auditUserId — audit identity for secret reads. Handler path: the
+ *                 dispatcher sets the caller's user id; worker path: the
+ *                 r.job wrap sets a system identity.
  */
 export type MailTransportContext = {
   readonly config?: ConfigAccessor;
   readonly registry?: Registry;
   readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
-  readonly _userId?: string | undefined;
+  readonly auditUserId?: string | undefined;
 };
 
 /**
@@ -283,7 +282,7 @@ export function tenantMailTransport(
       config: scope.config,
       registry: scope.registry,
       secrets: scope.secrets,
-      _userId: createSystemUser(scope.tenantId).id,
+      auditUserId: createSystemUser(scope.tenantId).id,
     },
     scope.tenantId,
     "channel-email",

package/packages/bundled-features/src/mail-foundation/i18n.ts

@@ -1,8 +1,9 @@
 export const MAIL_FOUNDATION_I18N = {
   "screen:mail-foundation-tenant.title": { en: "Email sending" },
   "mail-foundation.settings": { en: "Email sending" },
-  "mail-foundation.provider": { en: "Own mail server" },
+  "mail-foundation.provider": { en: "Send via" },
   "mail-foundation.provider.description": {
-    en: "Without one, the platform sends the mails. Reset the choice to go back to that.",
+    en: "Choose who sends your emails. The platform default needs no settings of your own.",
   },
+  "mail-foundation.provider.platformDefault": { en: "Platform sending (default)" },
 } as const;

package/packages/bundled-features/src/mail-transport-smtp/i18n.ts

@@ -1,6 +1,6 @@
 export const MAIL_TRANSPORT_SMTP_I18N = {
   // Also the option label of mail-foundation's provider select.
-  "mail-transport-smtp.settings": { en: "SMTP server" },
+  "mail-transport-smtp.settings": { en: "Own SMTP server" },
   "mail-transport-smtp.settings.secrets": { en: "SMTP sign-in" },
   "mail-transport-smtp.settings.description": {
     en: "The connection details come from your mail provider, for example Brevo, Postmark, Amazon SES or your own server.",

package/packages/bundled-features/src/managed-pages/web/client-plugin.tsx

@@ -6,7 +6,7 @@
 // [managedPagesClient()] }), damit die Admin-Labels übersetzt rendern.
 
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
-import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { defaultTranslations } from "./i18n.ts";
 
 export type ManagedPagesClientOptions = {

package/packages/bundled-features/src/notes-history/web/client-plugin.tsx

@@ -1,6 +1,6 @@
 // @runtime client
 
-import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { NOTES_HISTORY_FEATURE_NAME, NOTES_SECTION_EXTENSION_NAME } from "../constants.ts";
 import { defaultTranslations } from "./i18n.ts";
 import { NotesSection } from "./notes-section.tsx";

package/packages/bundled-features/src/page-render/branding.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
 
 // Tenant-branding tokens resolved at render time (managed-pages reads them
 // from config — see managed-pages/branding.ts). Empty string = "unset, use

package/packages/bundled-features/src/page-render/layout.ts

@@ -1,5 +1,5 @@
-import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
-import { type ApexHead, renderApexHeadTags } from "@cosmicdrift/kumiko-headless/apex";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
+import { type ApexHead, renderApexHeadTags } from "@cosmicdrift/kumiko-renderer/headless/apex";
 import { type BrandingTokens, brandingHeaderHtml, brandingStyleBlock } from "./branding.ts";
 import { sanitizeTenantCss } from "./css-sanitize.ts";
 

package/packages/bundled-features/src/page-render/markdown.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, isSafeHref } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, isSafeHref } from "@cosmicdrift/kumiko-renderer/headless";
 import { Marked } from "marked";
 
 // Geteilter, gehärteter Markdown→HTML-Kern für server-gerenderte Public-

package/packages/bundled-features/src/personal-access-tokens/i18n.ts

@@ -1,5 +1,5 @@
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
-import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-headless";
+import { fieldLabelKey, fieldOptionLabelKey } from "@cosmicdrift/kumiko-renderer/headless";
 import { PAT_FEATURE } from "./constants.ts";
 import type { PatScopeConfig } from "./scopes.ts";
 

package/packages/bundled-features/src/personal-access-tokens/screens.ts

@@ -5,7 +5,7 @@ import {
   type SecretMintScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { ACTION_FORM_ENTITY } from "@cosmicdrift/kumiko-framework/ui-types";
-import { fieldOptionLabelKeyPrefix } from "@cosmicdrift/kumiko-headless";
+import { fieldOptionLabelKeyPrefix } from "@cosmicdrift/kumiko-renderer/headless";
 import {
   PAT_FEATURE,
   PAT_MINT_SCREEN_ID,

package/packages/bundled-features/src/secrets/feature.ts

@@ -79,11 +79,11 @@ export const JOIN_REQUEST_TRANSACTION_REASON =
 // FileProviderContext-Pfade (S3-Plugin im Worker) liefern dieselben
 // zwei Felder, also reicht die schmale ctx-shape — kein voller
 // HandlerContext-Import noetig.
-// Handler contexts carry the caller as ctx.user, provider contexts set _userId (takes precedence).
+// Handler contexts carry the caller as ctx.user, provider contexts set auditUserId (takes precedence).
 export function requireSecretsContext(
   ctx: {
     readonly secrets?: SecretsContext;
-    readonly _userId?: string | undefined;
+    readonly auditUserId?: string | undefined;
     readonly user?: { readonly id: string };
   },
   handlerName: string,
@@ -95,10 +95,10 @@ export function requireSecretsContext(
         "createSecretsContext({db, masterKeyProvider, registry}) via extraContext.secrets at boot.",
     });
   }
-  const userId = ctx._userId ?? ctx.user?.id;
+  const userId = ctx.auditUserId ?? ctx.user?.id;
   if (!userId) {
     throw new InternalError({
-      message: `[${handlerName}] ctx._userId missing (and no ctx.user) — cannot audit secret reads without a caller identity.`,
+      message: `[${handlerName}] ctx.auditUserId missing (and no ctx.user) — cannot audit secret reads without a caller identity.`,
     });
   }
   const withAudit = (raw: SecretsContext): SecretsContext => ({

package/packages/bundled-features/src/seo/sitemap.ts

@@ -1,4 +1,4 @@
-import { escapeXml } from "@cosmicdrift/kumiko-headless";
+import { escapeXml } from "@cosmicdrift/kumiko-renderer/headless";
 
 export type SitemapEntry = {
   readonly loc: string;

package/packages/bundled-features/src/shared/mail-template-body.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
 
 const SLOT_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
 

package/packages/bundled-features/src/shared/purge-files-reaching-subject.ts

@@ -16,9 +16,14 @@ import {
   type EntityDefinition,
   parseTenantId,
   type Registry,
+  SYSTEM_USER_ID,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+import {
+  FILE_REF_ENTITY_NAME,
+  fileRefEntity,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
 import {
   collectSingleFileHolders,
   type FileRefPurgeOutcome,
@@ -155,7 +160,8 @@ export async function purgeFilesReachingSubject(args: {
   const storageByTenant = new Map<TenantId, Promise<DeleteFileBytes | undefined>>();
   let firstFailure: FileSweepError | undefined;
 
-  for (const fileEntity of collectFileEntities(registry)) {
+  const fileEntities = collectFileEntities(registry);
+  for (const fileEntity of fileEntities) {
     const seenRowIds = new Set<string>();
     for (const where of candidateWheres(subject, recordTenantId, fileEntity)) {
       const rows = await selectMany<Record<string, unknown>>(db, fileEntity.table, where);
@@ -202,5 +208,124 @@ export async function purgeFilesReachingSubject(args: {
       }
     }
   }
+  // Runs even after an entity-sweep failure: one failed row must not leave the pending uploads.
+  const pendingFailure = await purgePendingUploadsOfUser({
+    db,
+    registry,
+    subject,
+    fileFieldKeys: pendingFieldKeys(fileEntities),
+    fileHolders,
+    storageByTenant,
+    resolveDeleteBytes,
+    missingStorage,
+  });
+  firstFailure ??= pendingFailure;
   if (firstFailure) throw firstFailure;
 }
+
+const pendingFieldKey = (entityType: unknown, fieldName: unknown) =>
+  `${entityType}\u0000${fieldName}`;
+
+function pendingFieldKeys(fileEntities: readonly FileEntity[]): ReadonlySet<string> {
+  const keys = new Set<string>();
+  for (const { entityName, fileFields } of fileEntities) {
+    for (const fieldName of fileFields) keys.add(pendingFieldKey(entityName, fieldName));
+  }
+  return keys;
+}
+
+async function isFileRefHeldByRecord(
+  db: DbRunner,
+  holders: readonly SingleFileHolder[],
+  tenantId: TenantId,
+  fileRefId: string,
+): Promise<boolean> {
+  for (const holder of holders) {
+    for (const field of holder.singleFields) {
+      const where: WhereObject = { [field]: fileRefId };
+      if (holder.tableHasTenantId) where["tenantId"] = tenantId;
+      if ((await selectMany(db, holder.table, where, { limit: 1 })).length > 0) return true;
+    }
+  }
+  return false;
+}
+
+// An upload the user made but never bound to a record has no entity row to find it through, so
+// the uploader id is the only link. Only refs that originate from a registered entity file
+// field count as pending uploads: config saves (a tenant logo) and server-made files never
+// bind and must outlive the uploader. A legacy unbound ref a record's single file column still
+// names is not pending but in use and stays with that record.
+async function purgePendingUploadsOfUser(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly subject: SubjectId;
+  readonly fileFieldKeys: ReadonlySet<string>;
+  readonly fileHolders: readonly SingleFileHolder[];
+  readonly storageByTenant: Map<TenantId, Promise<DeleteFileBytes | undefined>>;
+  readonly resolveDeleteBytes: (tenantId: TenantId) => Promise<DeleteFileBytes | undefined>;
+  readonly missingStorage: MissingStoragePolicy;
+}): Promise<FileSweepError | undefined> {
+  const { db, registry, subject, fileFieldKeys } = args;
+  // skip: only a user uploads files without binding them to a record
+  if (subject.kind !== "user") return undefined;
+  // skip: the system user is not a person; its server-made files are not pending uploads
+  if (subject.userId === SYSTEM_USER_ID) return undefined;
+  // skip: without the files feature there is no file_refs table to sweep
+  if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined) return undefined;
+  const pending = await selectMany<Record<string, unknown>>(db, fileRefsTable, {
+    insertedById: subject.userId,
+    entityId: null,
+  });
+  let firstFailure: FileSweepError | undefined;
+  for (const fileRef of pending) {
+    // skip: not uploaded for a registered entity file field (config, server-made, unknown origin)
+    if (!fileFieldKeys.has(pendingFieldKey(fileRef["entityType"], fileRef["fieldName"]))) continue;
+    firstFailure ??= await purgePendingFileRef(args, fileRef);
+  }
+  return firstFailure;
+}
+
+async function purgePendingFileRef(
+  args: {
+    readonly db: DbRunner;
+    readonly fileHolders: readonly SingleFileHolder[];
+    readonly storageByTenant: Map<TenantId, Promise<DeleteFileBytes | undefined>>;
+    readonly resolveDeleteBytes: (tenantId: TenantId) => Promise<DeleteFileBytes | undefined>;
+    readonly missingStorage: MissingStoragePolicy;
+  },
+  fileRef: Record<string, unknown>,
+): Promise<FileSweepError | undefined> {
+  const { db, fileHolders, storageByTenant, resolveDeleteBytes, missingStorage } = args;
+  const tenantId = parseTenantId(fileRef["tenantId"]);
+  const fileRefId = String(fileRef["id"]);
+  const storageKey = fileRef["storageKey"];
+  // skip: a ref without tenant or key has no bytes this sweep could address
+  if (tenantId === null || typeof storageKey !== "string" || storageKey === "") return undefined;
+  // skip: a record still uses this file
+  if (await isFileRefHeldByRecord(db, fileHolders, tenantId, fileRefId)) return undefined;
+
+  let storagePromise = storageByTenant.get(tenantId);
+  if (storagePromise === undefined) {
+    storagePromise = resolveDeleteBytes(tenantId);
+    storageByTenant.set(tenantId, storagePromise);
+  }
+  const deleteBytes = await storagePromise;
+  if (deleteBytes === undefined) {
+    if (missingStorage.mode === "skip") {
+      missingStorage.warn(tenantId);
+      return undefined;
+    }
+    return new FileSweepError("missing_file_storage", FILE_REF_ENTITY_NAME);
+  }
+  if ((await deleteBytesFailingClosed(deleteBytes, storageKey)).length > 0) {
+    return new FileSweepError("file_delete_failed", FILE_REF_ENTITY_NAME);
+  }
+  const forgotten = await fileRefExecutor.forget(
+    { id: fileRefId },
+    createSystemUser(tenantId),
+    createTenantDb({ db, tenantId, mode: "system" }),
+  );
+  return forgotten.isSuccess
+    ? undefined
+    : new FileSweepError("file_delete_failed", FILE_REF_ENTITY_NAME);
+}

package/packages/bundled-features/src/tags/web/client-plugin.tsx

@@ -1,6 +1,6 @@
 // @runtime client
 
-import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import {
   TAGS_COLUMN_RENDERER_NAME,
   TAGS_FEATURE_NAME,

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

@@ -1,4 +1,42 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Document PDFs embed the images of a record",
+    "detail": "A template variable of type images (templateVariable.images()) holds FileRef ids of the record. The new Images block (div[data-images], PDF templates only, rejected for mail kinds) renders them as data-URI images in the real PDF render. Only files of the rendering tenant are read, only png, jpeg, gif and webp, at most 24 images and 20 MB per document; missing, foreign, oversized or non-image ids are dropped silently. Previews and draft PDFs never read files and show one placeholder box per block. An images variable never renders as inline text. i18n keys template-resolver.documentEditor.images, template-resolver.documentEditor.imagesVariable and templateResolver.errors.document.imagesBlockPdfOnly ship in de, es, fr and it.",
+    "migration": "Declare a template variable with type `images`, place the Images block, and pass FileRef ids of the record in `variables`. Images resolve only in the real PDF render, previews show placeholders. The ids must come from the record on the server, never from client input: a resolved id is read for the whole tenant without an entity access check."
+  },
+  {
+    "version": "0.378.0",
+    "type": "breaking",
+    "title": "Template editing is SystemAdmin-only unless the app unlocks it",
+    "detail": "Every tenant write handler, the overview and resource upload accept SystemAdmin only, plus the roles of the tenantEditable entries. A write on a template that is not unlocked fails with templateNotTenantEditable. The test send follows the same rule. For a non-SystemAdmin an unknown template id answers 403 like a locked one, so the response does not reveal whether it exists. Collections without an access rule default to SystemAdmin.",
+    "migration": "Where TenantAdmins must keep editing a template, pass tenantEditable to createTemplateResolverFeature, for example tenantEditable: [{ kind: \"mail\", slug: \"billing:notify:invoice-issued\", access: { roles: [\"TenantAdmin\"] } }]. Give template collections an explicit access rule if tenants should manage them."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "send-test-status query for the template test mail",
+    "detail": "template-resolver:query:send-test-status answers whether a test mail can be sent (canSend) and, if not, why (no_channel or no_address), so clients can disable the action instead of failing on send."
+  },
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "seedSystemTemplateBundle sets a title per template",
+    "detail": "Bundle locale entries accept an optional title, written to the template resource and exported again by the bundle export. SeedSystemTemplateOptions gets title. The template overview shows it instead of the slug."
+  },
+  {
+    "version": "0.375.0",
+    "type": "improvement",
+    "title": "Preview and test mail render with the values of a picked record",
+    "detail": "`template-resolver:query:preview` and `template-resolver:write:send-test` accept an optional `variables` object that replaces the declared example values for the named variables. The values are checked against the template's variable schema like a real send (unknown names and wrong types are rejected as `variables.<name>` validation errors); variables not passed keep their example. The mail editor now passes the values picked through the preview record picker into the preview and the test mail instead of only listing them."
+  },
+  {
+    "version": "0.375.0",
+    "type": "improvement",
+    "title": "Read a mail or PDF template as blocks and change it with structured operations",
+    "detail": "The query `template-resolver:query:document-blocks` returns a document template as blocks with stable ids (b0, b1, ...), its meta, variables, allowed block types and uploaded image keys, plus a `base` (scope and version). The write `template-resolver:write:patch-draft` applies up to 50 operations (insertBlock, replaceText, removeBlock, setResource, setMeta, setVariable) to that state and stores the result as the caller's tenant draft; an active version keeps being served until publish. Block ids refer to the state that was read. If the template changed since `base` was read, the call fails with `version_conflict` and writes nothing; a patch that removes a required placeholder or sets variables a notification declares is refused. `writeTemplateRow` accepts an optional `expectedVersion`. The universal helpers `placeholder-text` and the toolbar block sets moved out of `web/` without changing the web exports."
+  },
   {
     "version": "0.372.0",
     "type": "improvement",

package/packages/bundled-features/src/template-resolver/compile-document-body.ts

@@ -78,10 +78,15 @@ function valueExpression(
   return `{{${path}}}`;
 }
 
+// Never interpolated as text: its value is a list of file ids.
+function isImagesVariable(def: TemplateVariableDef | undefined): boolean {
+  return def?.type === "images";
+}
+
 function rewriteVariable(element: ScanElement, state: CompileState): void {
   const name = element.getAttribute("data-variable") ?? "";
   const replacement = element.ownerDocument.createTextNode(
-    isDocumentReferenceName(name)
+    isDocumentReferenceName(name) && !isImagesVariable(pathAndDef(name, element, state)[1])
       ? marker(
           state,
           valueExpression(
@@ -131,6 +136,8 @@ function wrapVariableOnlyBlock(block: ScanElement, state: CompileState): void {
   // skip: a line with static content or several placeholders stays as it is
   if (name === null) return;
   const [path, def] = pathAndDef(name, block, state);
+  // skip: images blocks are rewritten by rewriteImagesBlock
+  if (isImagesVariable(def)) return;
   const host =
     def?.type === "richText" && block.tagName === "P" ? richTextBlockHost(block, state) : block;
   const document = host.ownerDocument;
@@ -158,8 +165,8 @@ function rewriteLink(element: ScanElement, state: CompileState): void {
   if (isDocumentPlaceholderHref(href)) {
     const name = href.slice(2, -2);
     if (isDocumentReferenceName(name)) {
-      const [path] = pathAndDef(name, element, state);
-      element.setAttribute("href", marker(state, `{{link ${path}}}`));
+      const [path, def] = pathAndDef(name, element, state);
+      element.setAttribute("href", isImagesVariable(def) ? "#" : marker(state, `{{link ${path}}}`));
     } else {
       element.setAttribute("href", "#");
     }
@@ -225,8 +232,14 @@ export type CompileDocumentBodyOptions = {
   readonly headingAsInlineStyle?: boolean;
   // Bar color of reached stages in a steps block; ignored unless it is a #rrggbb hex.
   readonly stepsColor?: string;
+  // Data URIs of the record's images for the images block bound to `variable`.
+  readonly recordImagesSrc?: (variable: string) => readonly string[];
+  // Previews and drafts never read the record's files; each images block shows one neutral box.
+  readonly recordImagesPlaceholder?: boolean;
 };
 
+const IMAGES_PLACEHOLDER_STYLE = "height:96px;margin:8px 0;border-radius:4px;background:#e5e7eb";
+
 const MAIL_BUTTON_STYLE =
   "display:inline-block;padding:10px 20px;border-radius:6px;background-color:#1f5468;color:#ffffff;font-weight:600;text-decoration:none";
 
@@ -258,6 +271,48 @@ export function collectDocumentResourceKeys(html: string): readonly string[] {
   });
 }
 
+// Unique valid names of the images blocks in document order.
+export function collectDocumentImageVariables(html: string): readonly string[] {
+  return withParsedDocument(html, (root) => {
+    const names = new Set<string>();
+    for (const element of Array.from(root.querySelectorAll("div[data-images]"))) {
+      const name = element.getAttribute("data-images") ?? "";
+      if (isDocumentReferenceName(name)) names.add(name);
+    }
+    return [...names];
+  });
+}
+
+function rewriteImagesBlock(
+  element: ScanElement,
+  state: CompileState,
+  options: CompileDocumentBodyOptions,
+): void {
+  const name = element.getAttribute("data-images") ?? "";
+  const declared =
+    isDocumentReferenceName(name) && isImagesVariable(ownVariable(state.variables, name));
+  if (!declared) {
+    element.remove();
+    // skip: an images block bound to anything but a declared images variable renders nothing
+    return;
+  }
+  const document = element.ownerDocument;
+  element.removeAttribute("data-images");
+  if (options.recordImagesPlaceholder === true) {
+    element.setAttribute("class", "kumiko-doc-image-placeholder");
+    element.setAttribute("style", IMAGES_PLACEHOLDER_STYLE);
+    // skip: preview and drafts never resolve record images
+    return;
+  }
+  element.setAttribute("class", "kumiko-doc-images");
+  for (const src of options.recordImagesSrc?.(name) ?? []) {
+    const image = document.createElement("img");
+    image.setAttribute("src", src);
+    image.setAttribute("alt", "");
+    element.append(image);
+  }
+}
+
 export function toResourceDataUri(contentType: string, bytes: Uint8Array): string {
   if (!isResourceImageContentType(contentType)) {
     throw new Error(`resource content type "${contentType}" cannot be embedded as an image`);
@@ -374,6 +429,9 @@ export function compileDocumentBodyToHandlebars(
         color: options.stepsColor,
       });
     }
+    for (const element of Array.from(root.querySelectorAll("div[data-images]"))) {
+      rewriteImagesBlock(element, state, options);
+    }
     for (const block of Array.from(root.querySelectorAll(`[${DOCUMENT_CONDITION_ATTRIBUTE}]`))) {
       rewriteConditionalBlock(block, state);
     }

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

@@ -99,3 +99,6 @@ export { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 // Default-Locale wenn Tenant keinen eigenen Default konfiguriert. Resolver
 // fällt darauf zurück wenn requested locale + tenant-default fehlen.
 export const FALLBACK_LOCALE = "de";
+
+// A collection mounted without `access` is maintained by the platform only; TenantAdmin access is an explicit mount decision.
+export const DEFAULT_COLLECTION_ACCESS = { roles: ["SystemAdmin"] } as const;

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

@@ -0,0 +1,36 @@
+// @runtime client
+export type DocumentToolbarBlock =
+  | "image"
+  | "table"
+  | "button"
+  | "divider"
+  | "repeat"
+  | "pageBreak"
+  | "align"
+  | "steps"
+  | "images";
+
+export const MAIL_DOCUMENT_BLOCKS = [
+  "image",
+  "table",
+  "button",
+  "divider",
+  "repeat",
+  "steps",
+] as const satisfies readonly DocumentToolbarBlock[];
+
+export const PDF_DOCUMENT_BLOCKS = [
+  "align",
+  "image",
+  "table",
+  "divider",
+  "repeat",
+  "steps",
+  "images",
+  "pageBreak",
+] as const satisfies readonly DocumentToolbarBlock[];
+
+/** Block set for a template-resource kind; every kind except "document-pdf" gets the mail set. */
+export function documentBlocksForKind(kind: string | undefined): readonly DocumentToolbarBlock[] {
+  return kind === "document-pdf" ? PDF_DOCUMENT_BLOCKS : MAIL_DOCUMENT_BLOCKS;
+}

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

@@ -0,0 +1,29 @@
+// @runtime client
+// The record's photos: a block bound to an `images` variable whose FileRef ids the
+// app passes at render time. Universal like document-schema.ts.
+import { Node } from "@tiptap/core";
+
+export function createDocumentImagesNode(isReferenceName: (value: string) => boolean) {
+  return Node.create({
+    name: "images",
+    group: "block",
+    atom: true,
+    addAttributes() {
+      return { variable: { default: null } };
+    },
+    parseHTML() {
+      return [
+        {
+          tag: "div[data-images]",
+          getAttrs: (element) => {
+            const variable = element.getAttribute("data-images");
+            return variable !== null && isReferenceName(variable) ? { variable } : false;
+          },
+        },
+      ];
+    },
+    renderHTML({ node }) {
+      return ["div", { "data-images": node.attrs["variable"] }];
+    },
+  });
+}