@cosmicdrift/kumiko-samples 0.373.0 → 0.377.0

package/packages/bundled-features/src/inbound-mail-foundation/screens.ts

@@ -0,0 +1,100 @@
+import {
+  i18nKey,
+  MAX_LIST_LIMIT,
+  type ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { ActionFormScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  InboundMailAccountStatuses,
+  InboundMailFoundationHandlers,
+  InboundMailFoundationQueries,
+} from "./constants.ts";
+
+export const MAIL_ACCOUNT_LIST_SCREEN_ID = "mail-accounts";
+export const MAIL_ACCOUNT_EDIT_SCREEN_ID = "mail-account-edit";
+
+export const MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX = "inboundMail.accounts.status.";
+
+// Same roles as the update/disconnect handlers: a screen rule wider than the
+// handlers would only render actions that 403.
+const MAIL_ACCOUNT_ADMIN_ACCESS = { roles: ["SystemAdmin", "TenantAdmin"] } as const;
+
+// Several mailboxes per tenant, one row each. The bound query already filters
+// personal mailboxes the caller neither owns nor administers and returns no
+// credential: the secret lives in the secrets feature, never in the row.
+// dormant: the consuming app places the list in its own settings nav.
+export const mailAccountListScreen: ProjectionListScreenDefinition = {
+  id: MAIL_ACCOUNT_LIST_SCREEN_ID,
+  type: "projectionList",
+  agent: { expose: false },
+  query: InboundMailFoundationQueries.listAccounts,
+  pagination: false,
+  pageSize: MAX_LIST_LIMIT,
+  columns: [
+    { field: "displayName", label: i18nKey("inboundMail.accounts.col.name"), sortable: false },
+    { field: "address", label: i18nKey("inboundMail.accounts.col.address"), sortable: false },
+    {
+      field: "provider",
+      label: i18nKey("inboundMail.accounts.col.provider"),
+      sortable: false,
+      hideOnNarrow: true,
+    },
+    {
+      field: "status",
+      label: i18nKey("inboundMail.accounts.col.status"),
+      sortable: false,
+      renderer: { format: "enumOption", keyPrefix: MAIL_ACCOUNT_STATUS_OPTION_KEY_PREFIX },
+    },
+    {
+      field: "connectedAt",
+      label: i18nKey("inboundMail.accounts.col.connected"),
+      sortable: false,
+      hideOnNarrow: true,
+      renderer: { format: "timestamp" },
+    },
+  ],
+  rowActions: [
+    {
+      kind: "navigate",
+      id: "edit",
+      label: i18nKey("inboundMail.accounts.edit"),
+      screen: MAIL_ACCOUNT_EDIT_SCREEN_ID,
+      params: { map: { accountId: "id", displayName: "displayName" } },
+      visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+    },
+    {
+      kind: "writeHandler",
+      id: "disconnect",
+      label: i18nKey("inboundMail.accounts.disconnect"),
+      handler: InboundMailFoundationHandlers.disconnectAccount,
+      payload: { map: { accountId: "id" } },
+      style: "danger",
+      confirm: i18nKey("inboundMail.accounts.disconnect.confirm"),
+      visible: { field: "status", ne: InboundMailAccountStatuses.disconnected },
+    },
+  ],
+  access: MAIL_ACCOUNT_ADMIN_ACCESS,
+  dormant: true,
+};
+
+// The reason is the audit label update-account requires; it is not in the
+// layout, so the default is what gets written.
+export const mailAccountEditScreen: ActionFormScreenDefinition = {
+  id: MAIL_ACCOUNT_EDIT_SCREEN_ID,
+  type: "actionForm",
+  agent: { expose: false },
+  handler: InboundMailFoundationHandlers.updateAccount,
+  fields: {
+    accountId: { type: "text", required: true },
+    displayName: { type: "text", required: true, maxLength: 200 },
+    reason: { type: "text", default: "tenant_admin" },
+  },
+  layout: {
+    sections: [{ fields: [{ field: "accountId", readOnly: true }, "displayName"] }],
+  },
+  submitLabel: i18nKey("inboundMail.accounts.edit.submit"),
+  redirect: MAIL_ACCOUNT_LIST_SCREEN_ID,
+  cancelTarget: MAIL_ACCOUNT_LIST_SCREEN_ID,
+  access: MAIL_ACCOUNT_ADMIN_ACCESS,
+  dormant: true,
+};

package/packages/bundled-features/src/inbound-mail-foundation/types.ts

@@ -21,7 +21,7 @@ import { INBOUND_MAIL_PROVIDER_EXTENSION, type InboundMailAccountStatus } from "
  *   config   — tenant config reads (host/port/... of the plugins)
  *   registry — extension lookup in the factory (not plugin-internal)
  *   secrets  — tenant secret reads (IMAP password, OAuth refresh token)
- *   _userId  — audit identity for secret reads. Handler path: the dispatcher
+ *   auditUserId  — audit identity for secret reads. Handler path: the dispatcher
  *              sets the caller user ID; worker path: system identity.
  *   metricsFor — metrics handle of a feature by name, same behavior as
  *              HandlerContext.metricsFor: unregistered metrics are a silent
@@ -31,7 +31,7 @@ export type InboundMailContext = {
   readonly config?: ConfigAccessor;
   readonly registry?: Registry;
   readonly secrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
-  readonly _userId?: string | undefined;
+  readonly auditUserId?: string | undefined;
   readonly metricsFor?: (featureName: string) => MetricsHandle;
 };
 

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

@@ -1,6 +1,6 @@
 // @runtime client
 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 { JOBS_FEATURE } from "../constants.ts";
 import { defaultTranslations } from "./i18n.ts";
 

package/packages/bundled-features/src/legal-pages/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "Legal layout receives alternates",
+    "detail": "createLegalPagesLayout passes alternates as second argument to headerHtml and footerHtml, and legal-pages routes provide the other-language paths of the same slug, so a layout can render a language switch."
+  },
   {
     "version": "0.370.0",
     "type": "improvement",

package/packages/bundled-features/src/legal-pages/feature.ts

@@ -4,7 +4,7 @@ import {
   type FeatureDefinition,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { escapeHtml } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml } from "@cosmicdrift/kumiko-renderer/headless";
 import {
   cachedSecurePageResponse,
   type PublicPageWrapLayout,
@@ -90,6 +90,17 @@ export type LegalPagesOptions = {
   readonly terms?: boolean;
 };
 
+// Only slugs served in more than one language get alternates.
+function alternatesBySlugOf(
+  routes: readonly LegalPageRoute[],
+): ReadonlyMap<string, Readonly<Record<string, string>>> {
+  const bySlug = new Map<string, Record<string, string>>();
+  for (const route of routes) {
+    bySlug.set(route.slug, { ...bySlug.get(route.slug), [route.lang]: route.path });
+  }
+  return new Map([...bySlug].filter(([, byLang]) => Object.keys(byLang).length > 1));
+}
+
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
   const routes: readonly LegalPageRoute[] = [
@@ -108,6 +119,7 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
       );
     }
   }
+  const alternatesBySlug = alternatesBySlugOf(routes);
   return defineFeature("legal-pages", (r) => {
     r.describe(
       "Opt-in wrapper around `template-resolver` text-blocks that registers public HTML routes (default: `/legal/impressum`, `/legal/datenschutz`, `/legal/imprint`, `/legal/privacy`) with Markdown-to-HTML rendering and a boot-time job that hard-fails in production when the required blocks (default: `imprint/de`, `privacy/de`) are not seeded in `SYSTEM_TENANT`. Both are configurable via `routes`/`requiredBlocks` for apps with a different default language or additional pages. Requires `anonymousAccess: { defaultTenantId: SYSTEM_TENANT_ID }` and `extraContext.templateResolver` to be wired at app bootstrap; for per-tenant imprints or a custom layout call `template-resolver:query:by-slug` directly.",
@@ -189,6 +201,7 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
               : renderedBody,
             lang: route.lang,
             slug: route.slug,
+            alternates: alternatesBySlug.get(route.slug),
           });
 
           return cachedSecurePageResponse(c.req.raw, {

package/packages/bundled-features/src/legal-pages/layout.ts

@@ -1,4 +1,4 @@
-import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
 import { type PublicPageWrapLayout, TENANT_CONTENT_ATTR } from "../page-render/index.ts";
 
 export type LegalPagesLayoutOptions = {
@@ -8,8 +8,8 @@ export type LegalPagesLayoutOptions = {
   readonly css?: string;
   readonly stylesheetHrefs?: readonly string[];
   // Trusted app chrome per language; the feature passes the route's `lang`.
-  readonly headerHtml?: (lang: string) => string;
-  readonly footerHtml?: (lang: string) => string;
+  readonly headerHtml?: (lang: string, alternates?: Readonly<Record<string, string>>) => string;
+  readonly footerHtml?: (lang: string, alternates?: Readonly<Record<string, string>>) => string;
   readonly contentClass?: string;
 };
 
@@ -22,9 +22,9 @@ export function createLegalPagesLayout(options: LegalPagesLayoutOptions): Public
   const contentClass = options.contentClass
     ? ` class="${escapeHtmlAttr(options.contentClass)}"`
     : "";
-  return ({ title, bodyHtml, lang }) => {
-    const headerHtml = options.headerHtml?.(lang) ?? "";
-    const footerHtml = options.footerHtml?.(lang) ?? "";
+  return ({ title, bodyHtml, lang, alternates }) => {
+    const headerHtml = options.headerHtml?.(lang, alternates) ?? "";
+    const footerHtml = options.footerHtml?.(lang, alternates) ?? "";
     return `<!doctype html>
 <html lang="${escapeHtmlAttr(lang)}">
 <head>

package/packages/bundled-features/src/legal-pages/web/client-plugin.ts

@@ -17,7 +17,7 @@
 // fehlende Pflicht-Blocks.
 
 import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
-import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
 import { LEGAL_OPTIONAL_BLOCKS, LEGAL_REQUIRED_BLOCKS } from "../constants.ts";
 
 const treeProvider: TreeChildrenSubscribe = () => (emit) => {

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/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,22 @@
 [
+  {
+    "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/document-blocks.ts

@@ -0,0 +1,34 @@
+// @runtime client
+export type DocumentToolbarBlock =
+  | "image"
+  | "table"
+  | "button"
+  | "divider"
+  | "repeat"
+  | "pageBreak"
+  | "align"
+  | "steps";
+
+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",
+  "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;
+}