@cosmicdrift/kumiko-samples 0.377.0 → 0.379.0

package/packages/bundled-features/src/tags/web/i18n.ts

@@ -1,4 +1,3 @@
-// @runtime client
 // Default translation bundle for the tags UI. tagsClient() hangs it into the
 // LocaleProvider as a fallback bundle — apps override individual keys via
 // tagsClient({ translations }). Keys follow `tags.<area>.<slug>`.
@@ -25,7 +24,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "tags.manage.toggle": "Toggle label",
     "tags.manage.usage": "{count}×",
     "tags.manage.deleteConfirmTitle": "Delete label “{name}”?",
-    "tags.manage.deleteConfirmDesc": "Removes it from {count} objects. This can't be undone.",
+    "tags.manage.deleteConfirmDesc.one": "Removes it from 1 object. This can't be undone.",
+    "tags.manage.deleteConfirmDesc.other": "Removes it from {count} objects. This can't be undone.",
     "tags.picker.title": "Tags",
     "tags.picker.done": "Done",
     "tags.filter.label": "Filter by tag",

package/packages/bundled-features/src/tags/web/index.ts

@@ -1,4 +1,4 @@
-// @runtime client
+export { tagsClient } from "./client-plugin.tsx";
 export {
   TAGS_COLUMN_RENDERER_NAME,
   TAGS_EDIT_SCREEN_ID,
@@ -7,8 +7,7 @@ export {
   TAGS_SECTION_EXTENSION_NAME,
   TagsHandlers,
   TagsQueries,
-} from "../constants.ts";
-export { tagsClient } from "./client-plugin.tsx";
+} from "./constants.ts";
 export { EntityTags } from "./entity-tags.tsx";
 export { contrastText, TagChip } from "./tag-chip.tsx";
 export { TagFilter } from "./tag-filter.tsx";

package/packages/bundled-features/src/tags/web/tag-chip.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagChip — read-only colored label pill, GitLab-labels style. The tag's `color`
 // (a hex like "#22cc88") drives the background; the text color is chosen for
 // contrast (YIQ luminance) so light and dark labels both stay legible. A tag

package/packages/bundled-features/src/tags/web/tag-filter.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagFilter — a drop-in tag filter for ANY entityList toolbar. Register it as
 // the list's header slot (`screen.slots.header`); the renderer passes it the
 // list's screenId, and picking tags resolves the matching row ids and narrows
@@ -20,7 +19,7 @@ import {
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useState } from "react";
-import { TagsQueries } from "../constants.ts";
+import { TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 import { TagPicker } from "./tag-picker.tsx";
 

package/packages/bundled-features/src/tags/web/tag-manager.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagManager — the shared tag-catalog UI, GitLab-labels style. Built ONCE,
 // mounted twice:
 //   - standalone:  <TagManager />                       → the Tags admin screen
@@ -16,8 +15,9 @@ import {
   useQuery,
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
+import { pluralKey } from "@cosmicdrift/kumiko-renderer/headless";
 import { type ReactNode, useState } from "react";
-import { TagsHandlers, TagsQueries } from "../constants.ts";
+import { TagsHandlers, TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 
 type TagRow = {
@@ -139,6 +139,7 @@ export function TagManager({
   const usage = new Map<string, number>();
   for (const a of assignments.data?.rows ?? []) usage.set(a.tagId, (usage.get(a.tagId) ?? 0) + 1);
 
+  const deletingUsage = usage.get(deleting?.id ?? "") ?? 0;
   const selecting = selection !== undefined;
   const allTags = catalog.data?.rows ?? [];
   const tags = selecting
@@ -378,8 +379,8 @@ export function TagManager({
           if (!open) setDeleting(null);
         }}
         title={t("tags.manage.deleteConfirmTitle", { name: deleting?.name ?? "" })}
-        description={t("tags.manage.deleteConfirmDesc", {
-          count: usage.get(deleting?.id ?? "") ?? 0,
+        description={t(pluralKey("tags.manage.deleteConfirmDesc", deletingUsage), {
+          count: deletingUsage,
         })}
         confirmLabel={t("tags.manage.delete")}
         variant="danger"

package/packages/bundled-features/src/tags/web/tag-picker.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagPicker — the shared "manage + pick labels" modal. Wraps TagManager in
 // select-mode inside a Dialog: the user can create/recolor/delete labels (those
 // hit the catalog immediately) and toggle which ones apply (buffered). On

package/packages/bundled-features/src/tags/web/tag-section.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagSection — drop-in tag editor for ANY entity, GitLab-labels style. Shows the
 // entity's tags as colored chips plus an "Edit tags" button that opens the
 // shared TagPicker modal (pick + manage). Applying the picker diffs the
@@ -19,7 +18,7 @@ import {
   useTranslation,
 } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useState } from "react";
-import { TagsHandlers, TagsQueries } from "../constants.ts";
+import { TagsHandlers, TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 import { TagPicker } from "./tag-picker.tsx";
 

package/packages/bundled-features/src/tags/web/tags-cell.tsx

@@ -1,4 +1,3 @@
-// @runtime client
 // TagsCell — a reusable columnRenderer that shows an entity's tags as colored
 // chips inline in a list row. Drop it into ANY entityList by declaring a labeled
 // virtual column (no host-schema change), after mounting tagsClient():
@@ -17,7 +16,7 @@
 
 import { type ColumnRendererProps, useQuery } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
-import { TagsQueries } from "../constants.ts";
+import { TagsQueries } from "./constants.ts";
 import { TagChip } from "./tag-chip.tsx";
 
 type TagRow = { readonly id: string; readonly name: string; readonly color?: string | null };

package/packages/bundled-features/src/template-resolver/README.md

@@ -23,7 +23,7 @@ const features = [
 const app = createKumikoApp({
   features,
   extraContext: ({ db }) => ({
-    templateResolver: createTemplateResolverApi(db),
+    templateResolver: createTemplateResolverApi(db, registry),
   }),
 });
 ```

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

@@ -4,12 +4,10 @@
 
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
-import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { Registry, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { FileAttachmentRef } from "../renderer-foundation/index.ts";
-import type { ContentFormat, TemplateKind } from "./constants.ts";
-import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./constants.ts";
 import {
   fileAttachmentsOf,
   imageLinksOf,
@@ -18,8 +16,16 @@ import {
   type TemplatePdfAttachmentLink,
 } from "./linked-resources.ts";
 import { type TemplateResourceRow, templateResourcesTable } from "./table.ts";
-import { activeVersionOf, servedVersionOf } from "./template-draft.ts";
+import {
+  deliveryPolicyOf,
+  isRowServed,
+  isServedByCollectionOnly,
+  type TemplateDeliveryPolicy,
+} from "./template-delivery-policy.ts";
+import { activeVersionOf, isSystemAdmin, servedVersionOf } from "./template-draft.ts";
 import { parseTemplateMeta, type TemplateMeta } from "./template-meta.ts";
+import type { ContentFormat, TemplateKind } from "./web/constants.ts";
+import { FALLBACK_LOCALE, SYSTEM_TENANT_ID } from "./web/constants.ts";
 
 // Public TemplateResource: what consumers see. Hides DB-internal columns
 // (insertedById, internal id-type) but keeps the fields needed for rendering.
@@ -68,15 +74,11 @@ export type ResolveLayoutRequest = {
 
 export type TemplateResolverApi = {
   /**
-   * Findet ein konkretes Template by (tenantId, slug, kind, locale).
-   * Kein Locale-Fallback, keine Override-Hierarchie — Raw-Lookup für
-   * Admin-UI-Edits und Konformitäts-Tests. Für Render-Aufrufe immer
-   * `resolveTemplate` nutzen.
+   * Raw lookup by (tenantId, slug, kind, locale): no locale fallback, no override
+   * hierarchy. Render paths must use `resolveTemplate`. `scope: "system"` forces
+   * SYSTEM_TENANT_ID and ignores the passed tenantId.
    *
-   * `scope: "system"` zwingt Lookup gegen SYSTEM_TENANT_ID (ignoriert
-   * den übergebenen tenantId). Default = Lookup gegen den übergebenen
-   * tenantId direkt (Caller wählt entweder Tenant oder System per
-   * tenantId).
+   * Tenant rows of a template that is not tenantEditable are not returned.
    */
   readonly findExact: (args: {
     readonly tenantId: TenantId;
@@ -87,18 +89,10 @@ export type TemplateResolverApi = {
   }) => Promise<TemplateResource | null>;
 
   /**
-   * Resolver mit 4-Stufen-Fallback (siehe template-resolver.md):
-   *   1. tenant + requested-locale
-   *   2. system + requested-locale
-   *   3. tenant + FALLBACK_LOCALE
-   *   4. system + FALLBACK_LOCALE
-   * Resource-Substitution wird hier NICHT ausgeführt — das macht der
-   * Caller (renderer-foundation-Plugin) je nach kind-passendem Modus
-   * (inline-base64 vs. signed-url). API liefert TemplateResource pur.
-   *
-   * **Caller-Invariante:** `tenantId` MUSS vom Server kommen (typisch
-   * `ctx.user.tenantId`). Niemals direkt aus User-Input — sonst kann
-   * User cross-tenant Templates abfragen (Tenant-Isolation gebrochen).
+   * Four-step fallback: tenant+locale, system+locale, tenant+FALLBACK_LOCALE,
+   * system+FALLBACK_LOCALE (see template-resolver.md).
+   * Tenant rows count only for templates unlocked for tenants (tenantEditable,
+   * or a collection with access); locked overrides are skipped but stay stored.
    */
   readonly resolveTemplate: (args: ResolveRequest) => Promise<TemplateResource>;
 
@@ -114,12 +108,18 @@ export type TemplateResolverApi = {
   readonly resolveLayout: (args: ResolveLayoutRequest) => Promise<TemplateResource>;
 };
 
-export function createTemplateResolverApi(db: DbRunner | TenantDb): TemplateResolverApi {
+export function createTemplateResolverApi(
+  db: DbRunner | TenantDb,
+  registry: Registry,
+): TemplateResolverApi {
+  const deliveryPolicy = deliveryPolicyOf(registry);
+  // A collection entry must not shadow a system template of the same slug that the app did not unlock.
+  const isServed = (row: TemplateResourceRow) => isRowDelivered(db, deliveryPolicy, row);
   return {
     findExact: async ({ tenantId, slug, kind, locale, scope }) => {
       const effectiveTenantId = scope === "system" ? SYSTEM_TENANT_ID : tenantId;
       const row = await fetchTemplate(db, effectiveTenantId, slug, kind, locale);
-      return row ? toPublic(row) : null;
+      return row && (await isServed(row)) ? toPublic(row) : null;
     },
 
     resolveTemplate: async ({ tenantId, slug, kind, locale }) => {
@@ -135,14 +135,16 @@ export function createTemplateResolverApi(db: DbRunner | TenantDb): TemplateReso
           : []),
       ];
       for (const c of candidates) {
+        if (!isRowServed(deliveryPolicy, { tenantId: c.tid, kind, slug })) continue;
         const row = await fetchTemplate(db, c.tid, slug, kind, c.loc);
-        if (row && row.status === "active") return toPublic(row);
+        if (row && row.status === "active" && (await isServed(row))) return toPublic(row);
       }
       throw new TemplateNotFoundError({ slug, kind, locale });
     },
 
     resolveLayout: async ({ tenantId, slug, kind, locale }) => {
       for (const tid of [tenantId, SYSTEM_TENANT_ID]) {
+        if (!isRowServed(deliveryPolicy, { tenantId: tid, kind, slug })) continue;
         const rows = await selectMany<TemplateResourceRow>(db, templateResourcesTable, {
           tenantId: tid,
           slug,
@@ -156,6 +158,51 @@ export function createTemplateResolverApi(db: DbRunner | TenantDb): TemplateReso
   };
 }
 
+// The one delivery rule for a stored row: unlocked, and a collection entry never shadows a system
+// template of the same slug that the app did not unlock.
+export async function isRowDelivered(
+  db: DbRunner | TenantDb,
+  policy: TemplateDeliveryPolicy,
+  row: TemplateResourceRow,
+): Promise<boolean> {
+  if (!isRowServed(policy, row)) return false;
+  if (row.tenantId === SYSTEM_TENANT_ID || !isServedByCollectionOnly(policy, row)) return true;
+  return !(await systemTemplateExists(db, row.kind, row.slug));
+}
+
+export async function isRowDeliveredTo(
+  db: DbRunner | TenantDb,
+  policy: TemplateDeliveryPolicy,
+  user: { readonly roles: readonly string[] },
+  row: TemplateResourceRow,
+): Promise<boolean> {
+  return isSystemAdmin(user) || (await isRowDelivered(db, policy, row));
+}
+
+export async function filterDeliveredTo(
+  db: DbRunner | TenantDb,
+  policy: TemplateDeliveryPolicy,
+  user: { readonly roles: readonly string[] },
+  rows: readonly TemplateResourceRow[],
+): Promise<TemplateResourceRow[]> {
+  const flags = await Promise.all(rows.map((row) => isRowDeliveredTo(db, policy, user, row)));
+  return rows.filter((_, index) => flags[index]);
+}
+
+export async function systemTemplateExists(
+  db: DbRunner | TenantDb,
+  kind: string,
+  slug: string,
+): Promise<boolean> {
+  const rows = await selectMany(
+    db,
+    templateResourcesTable,
+    { tenantId: SYSTEM_TENANT_ID, slug, kind },
+    { limit: 1 },
+  );
+  return rows.length > 0;
+}
+
 function pickActiveLayoutRow(
   rows: readonly TemplateResourceRow[],
   locale: string,
@@ -268,7 +315,7 @@ export function requireTemplateResolver(
     throw new InternalError({
       message:
         `[${callerName}] ctx.templateResolver missing — App-Bootstrap muss ` +
-        `extraContext: { templateResolver: createTemplateResolverApi(db) } setzen ` +
+        `extraContext: { templateResolver: createTemplateResolverApi(db, registry) } setzen ` +
         `(siehe template-resolver/README.md).`,
     });
   }

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

@@ -1,4 +1,67 @@
 [
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Titles for the template-resolver write handlers",
+    "detail": "Every agent-callable template-resolver write handler now has a title in de, en, es, fr and it, so the AI assistant names actions such as \"Edit template draft\" instead of \"template-resolver:write:patch-draft\". The handlers of mounted content collections (`<id>-set`) stay untitled because their names depend on the app. The empty-field hint of the placeholder line editor now ends in an ellipsis inside the field instead of running past it."
+  },
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "Overrides of locked templates are no longer served",
+    "detail": "A tenant override of a mail, PDF or layout template is delivered (mail send, PDF render, linked PDFs, layouts, previews, export bundles, document blocks, overview, text blocks) only while the template is listed in tenantEditable. A locked override stays stored and has no effect; listing the template makes it effective again, nothing is deleted. A SystemAdmin sees locked overrides in the overview (`lockedOverride`, `lockedOverrideI18nKey`) and can reset or archive them with the existing handlers; the template-resolver queries do not show them to a TenantAdmin; the audit log keeps the history. Tenant rows of a collection mounted with `access` are served, except for a slug that has a system template outside tenantEditable: that system template wins, and the collection `-set` handler refuses such a slug for a non-SystemAdmin. createTemplateResolverApi(db) became createTemplateResolverApi(db, registry) because the delivery policy is read from the mounted feature; without the mounted feature no tenant override is served.",
+    "migration": "Overrides of templates that are not tenantEditable are no longer served; enable the template via tenantEditable to keep using them. Pass the registry as second argument to createTemplateResolverApi (ctx.registry in handlers, stack.registry in tests). Tenant rows without a system counterpart (for example text blocks seeded directly into a tenant) are hidden as well unless listed in tenantEditable."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Overview label for locked template overrides",
+    "detail": "Adds templateResolver.overview.lockedOverride."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Mail rendering follows the template delivery policy",
+    "detail": "Resolves templates through createTemplateResolverApi(db, registry); overrides of locked templates fall back to the system version."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "PDF rendering follows the template delivery policy",
+    "detail": "Resolves templates through createTemplateResolverApi(db, registry); overrides of locked templates fall back to the system version."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "Samples follow the createTemplateResolverApi(db, registry) signature",
+    "detail": "Recipes and sample apps build the template resolver API with the registry as second argument."
+  },
+  {
+    "version": "0.379.0",
+    "type": "improvement",
+    "title": "seedSystemTemplate accepts titleI18nKey",
+    "detail": "A seeded template can store an i18n key as its title (titleI18nKey, exclusive with title). The overview returns the key; the document-designer overview, mail editor and PDF link modal translate it and fall back to the raw text. Templates without a key behave as before; no migration."
+  },
+  {
+    "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",

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

@@ -11,7 +11,7 @@ import {
   isDocumentPlaceholderHref,
   isDocumentReferenceName,
   isDocumentResourceKey,
-} from "./document-schema.ts";
+} from "./web/document-schema.ts";
 
 // Private-use characters mark where a Handlebars expression goes. Author text
 // is scrubbed of them first and every `{`/`}` is entity-encoded before the
@@ -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/compile-steps-block.ts

@@ -1,7 +1,7 @@
 import type { Element as ScanElement } from "happy-dom";
-import { isDocumentReferenceName } from "./document-schema.ts";
-import { readDocumentSteps } from "./document-steps.ts";
 import { isHexColor } from "./layout-appearance.ts";
+import { isDocumentReferenceName } from "./web/document-schema.ts";
+import { readDocumentSteps } from "./web/document-steps.ts";
 
 export const DEFAULT_STEPS_COLOR = "#1f5468";
 const TODO_BAR_COLOR = "#ECEDEA";

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

@@ -1,17 +1,17 @@
 import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
 import { getSchema, type JSONContent } from "@tiptap/core";
 import * as z from "zod";
-import type { DocumentHtmlKind } from "./constants.ts";
-import { documentBlocksForKind } from "./document-blocks.ts";
+import { toVariableDef } from "./template-validation.ts";
+import type { DocumentHtmlKind } from "./web/constants.ts";
+import { documentBlocksForKind } from "./web/document-blocks.ts";
 import {
   DOCUMENT_TEXT_ALIGNMENTS,
   documentExtensions,
   isDocumentPlaceholderHref,
   isDocumentReferenceName,
   isDocumentResourceKey,
-} from "./document-schema.ts";
-import { contentToLine, lineToContent, singleLine } from "./placeholder-text.ts";
-import { toVariableDef } from "./template-validation.ts";
+} from "./web/document-schema.ts";
+import { contentToLine, lineToContent, singleLine } from "./web/placeholder-text.ts";
 
 export const MAX_DOCUMENT_OPS = 50;
 

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

@@ -5,8 +5,8 @@ import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { JSONContent } from "@tiptap/core";
 import { generateHTML, generateJSON } from "@tiptap/html/server";
 import { type Element as ScanElement, Window } from "happy-dom";
-import type { ContentFormat } from "./constants.ts";
-import { DOCUMENT_HTML_KINDS } from "./constants.ts";
+import type { ContentFormat } from "./web/constants.ts";
+import { DOCUMENT_HTML_KINDS } from "./web/constants.ts";
 import {
   DOCUMENT_CONDITION_ATTRIBUTE,
   documentExtensions,
@@ -14,8 +14,8 @@ import {
   isDocumentPlaceholderHref,
   isDocumentReferenceName,
   isDocumentResourceKey,
-} from "./document-schema.ts";
-import { isDocumentStepKey } from "./document-steps.ts";
+} from "./web/document-schema.ts";
+import { isDocumentStepKey } from "./web/document-steps.ts";
 
 export type DocumentViolationCode =
   | "script_element"
@@ -26,6 +26,7 @@ export type DocumentViolationCode =
   | "invalid_reference_name"
   | "embedded_content"
   | "unsafe_attribute_value"
+  | "images_block_pdf_only"
   | "button_href_not_placeholder"
   | "document_requires_html_format"
   | "layout_requires_mjml_format"
@@ -143,6 +144,7 @@ const REFERENCE_ATTRIBUTES: ReadonlyArray<readonly [string, (value: string) => b
   [DOCUMENT_CONDITION_ATTRIBUTE, isDocumentReferenceName],
   ["data-resource", isDocumentResourceKey],
   ["data-steps", isDocumentReferenceName],
+  ["data-images", isDocumentReferenceName],
   ["data-step", isDocumentStepKey],
 ];
 
@@ -313,6 +315,36 @@ function requiredFormatViolation(
   return null;
 }
 
+const IMAGES_BLOCK_KIND = "document-pdf";
+
+// The node is part of the shared document model, so a mail body would keep it after the
+// rebuild; only a PDF resolves the record's images.
+function imagesBlockViolation(input: {
+  readonly kind: string;
+  readonly contentFormat: ContentFormat;
+  readonly content: string | null;
+}): DocumentViolation | null {
+  if (
+    input.kind === IMAGES_BLOCK_KIND ||
+    !isSanitizedHtmlKind(input.kind) ||
+    input.contentFormat !== "html" ||
+    input.content === null
+  ) {
+    return null;
+  }
+  const hasImagesBlock = withParsedDocument(
+    input.content,
+    (body) => body.querySelector("div[data-images]") !== null,
+  );
+  return hasImagesBlock
+    ? violation(
+        "images_block_pdf_only",
+        input.kind,
+        `Record images blocks are only allowed in templates of kind ${IMAGES_BLOCK_KIND}`,
+      )
+    : null;
+}
+
 export function sanitizeTemplateBody(input: {
   readonly kind: string;
   readonly contentFormat: ContentFormat;
@@ -320,6 +352,8 @@ export function sanitizeTemplateBody(input: {
 }): SanitizeBodyResult {
   const formatViolation = requiredFormatViolation(input.kind, input.contentFormat);
   if (formatViolation !== null) return { ok: false, violations: [formatViolation] };
+  const imagesViolation = imagesBlockViolation(input);
+  if (imagesViolation !== null) return { ok: false, violations: [imagesViolation] };
   if (
     !isSanitizedHtmlKind(input.kind) ||
     input.contentFormat !== "html" ||
@@ -340,6 +374,7 @@ const VIOLATION_I18N_KEYS: Readonly<Record<DocumentViolationCode, string>> = {
   invalid_reference_name: "templateResolver.errors.document.invalidReferenceName",
   embedded_content: "templateResolver.errors.document.embeddedContent",
   unsafe_attribute_value: "templateResolver.errors.document.unsafeAttributeValue",
+  images_block_pdf_only: "templateResolver.errors.document.imagesBlockPdfOnly",
   button_href_not_placeholder: "templateResolver.errors.document.buttonHrefNotPlaceholder",
   document_requires_html_format: "templateResolver.errors.document.documentRequiresHtmlFormat",
   layout_requires_mjml_format: "templateResolver.errors.document.layoutRequiresMjmlFormat",