@cosmicdrift/kumiko-samples 0.364.0 → 0.365.0

package/packages/bundled-features/src/feature-toggles/toggle-runtime.ts

@@ -7,6 +7,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import {
+  type CacheSyncBus,
   type ClosableCacheSyncBus,
   createDefaultCacheSyncBus,
 } from "@cosmicdrift/kumiko-framework/redis";
@@ -40,9 +41,11 @@ export type ToggleSyncSignal = {
 // per-instance behavior for the only process there is.
 export class GlobalFeatureToggleRuntime {
   private snapshot = new Map<string, boolean>();
-  // Flips applied while a snapshot load is in flight. The load's SELECT may have
-  // started before the flip committed, so its rows can be older than these.
-  private appliedDuringLoad: Map<string, boolean> | undefined;
+  // One buffer per requested load, open from the call until its SELECT finished: the SELECT
+  // may have started before a flip committed, so its rows can be older than the flips collected.
+  private readonly pendingFlipBuffers = new Set<Map<string, boolean>>();
+  // Loads run one at a time so the older rows of one cannot overwrite the result of another.
+  private loadInFlight: Promise<void> = Promise.resolve();
 
   constructor(
     private readonly db: DbConnection,
@@ -69,10 +72,16 @@ export class GlobalFeatureToggleRuntime {
     await this.ownedBus?.close();
   }
 
-  async initialize(): Promise<void> {
-    type Row = { featureName: string; enabled: boolean };
+  initialize(): Promise<void> {
     const pendingFlips = new Map<string, boolean>();
-    this.appliedDuringLoad = pendingFlips;
+    this.pendingFlipBuffers.add(pendingFlips);
+    const load = this.loadInFlight.then(() => this.loadSnapshot(pendingFlips));
+    this.loadInFlight = load.catch(() => undefined);
+    return load;
+  }
+
+  private async loadSnapshot(pendingFlips: Map<string, boolean>): Promise<void> {
+    type Row = { featureName: string; enabled: boolean };
     try {
       const rows = await selectMany<Row>(this.db, globalFeatureStateTable);
       this.snapshot = new Map([
@@ -80,7 +89,7 @@ export class GlobalFeatureToggleRuntime {
         ...pendingFlips,
       ]);
     } finally {
-      this.appliedDuringLoad = undefined;
+      this.pendingFlipBuffers.delete(pendingFlips);
     }
   }
 
@@ -98,7 +107,7 @@ export class GlobalFeatureToggleRuntime {
   // lock. Kept alongside refresh() so both options are explicit.
   apply(featureName: string, enabled: boolean): void {
     this.snapshot.set(featureName, enabled);
-    this.appliedDuringLoad?.set(featureName, enabled);
+    for (const pendingFlips of this.pendingFlipBuffers) pendingFlips.set(featureName, enabled);
   }
 
   // Called by the toggle-cache-sync MSP handler (feature.ts) — the one
@@ -144,15 +153,20 @@ export class GlobalFeatureToggleRuntime {
 
 // Factory for app-boot wiring: instantiate, initialize, return the runtime (for the
 // set-handler to refresh; its effectiveFeatures feeds createDispatcher). Without an explicit
-// syncSignal the runtime builds one on the framework cache-sync bus: Redis-backed when
-// REDIS_URL is set, process-local otherwise. close() releases a bus it created.
+// syncSignal the signal runs on the given cacheSyncBus or, failing that, on a bus the runtime
+// creates itself (Redis-backed when REDIS_URL is set, process-local otherwise). close() releases
+// only a bus the runtime created.
 export async function createFeatureToggleRuntime(
   db: DbConnection,
   registry: Registry,
   syncSignal?: ToggleSyncSignal,
+  // The server's own bus (the one handed to the dispatcher): reusing it avoids a second set of
+  // Redis connections that nothing closes at shutdown.
+  cacheSyncBus?: CacheSyncBus,
 ): Promise<GlobalFeatureToggleRuntime> {
-  const ownedBus = syncSignal ? undefined : createDefaultCacheSyncBus();
-  const signal = syncSignal ?? (ownedBus ? createCacheSyncToggleSignal(ownedBus) : undefined);
+  const ownedBus = syncSignal || cacheSyncBus ? undefined : createDefaultCacheSyncBus();
+  const sharedBus = cacheSyncBus ?? ownedBus;
+  const signal = syncSignal ?? (sharedBus ? createCacheSyncToggleSignal(sharedBus) : undefined);
   const runtime = new GlobalFeatureToggleRuntime(db, registry, signal, ownedBus);
   try {
     await runtime.initialize();

package/packages/bundled-features/src/files-tenant-data/index.ts

@@ -27,8 +27,10 @@ import { fileRefStorageDestroyHook, fileRefTenantDestroyHook } from "./hooks.js"
 const SWEEP_ORPHANED_DERIVATIVES_ESCAPE_HATCH_REASON =
   "iterates every tenant and checks fileRef owners per tenant";
 
+export const FILES_TENANT_DATA_FEATURE = "files-tenant-data" as const;
+
 export function createFilesTenantDataFeature(): FeatureDefinition {
-  return defineFeature("files-tenant-data", (r) => {
+  return defineFeature(FILES_TENANT_DATA_FEATURE, (r) => {
     r.describe(
       "GDPR coverage for the `files` feature's `fileRef` entity: tenant-destroy row purge (EXT_TENANT_DATA) and full storage-prefix binary wipe (EXT_STORAGE_PROVIDER), plus a manual backfill/GC job that sweeps derivatives orphaned by a forget/tenant-destroy that ran before #2461 wired binary cleanup into those flows. Requires `tenant-lifecycle`, optionalRequires `files`.",
     );

package/packages/bundled-features/src/form-draft/db/queries/owned-file-refs.ts

@@ -1,5 +1,8 @@
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
-import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  instantToTimestamptzParam,
+  unsafeReadRetrying,
+} from "@cosmicdrift/kumiko-framework/bun-db";
+import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 
@@ -68,7 +71,13 @@ export async function filterOwnedFileRefs(
      WHERE "tenant_id" = $1 AND "inserted_by_id" = $2
        AND "storage_key" = ANY($3::text[]) AND "is_deleted" = false
        AND ($5::boolean OR "inserted_at" > $4::timestamptz)`,
-    [tenantId, ownerId, candidateKeys, draftInsertedAt.toString(), isCreateMode],
+    [
+      tenantId,
+      ownerId,
+      toPostgresArrayLiteral(candidateKeys),
+      instantToTimestamptzParam(draftInsertedAt),
+      isCreateMode,
+    ],
   );
   return rows.map((row) => ({ id: row.id, storageKey: row.storage_key }));
 }

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

@@ -93,7 +93,7 @@ export const discardDraftWrite = defineWriteHandler({
         await releaseDraftFileRefs(
           keys,
           async (key) => {
-            await files.ref(key).delete();
+            await files.refFromFileRef({ storageKey: key }).delete();
           },
           log,
         );

package/packages/bundled-features/src/jobs/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Finished tenant run reads its timestamp under the lock",
+    "detail": "The run that finishes last in lock order now carries the latest finishedAt, so a stale timestamp can no longer make the newest run the row that gets pruned."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Older migration notes that say \"kumiko migrate generate\" mean kumiko-schema generate",
+    "detail": "Migration notes of the delivery, jobs, metrics and sessions features name a command that does not exist, `kumiko migrate generate`. Run `kumiko-schema generate <name>` and then `kumiko-schema apply` instead. The published notes stay as they were."
+  },
   {
     "version": "0.364.0",
     "type": "fix",

package/packages/bundled-features/src/jobs/job-run-logger.ts

@@ -341,13 +341,16 @@ async function recordTenantRunOutcome(
       TENANT_JOB_RUN_LOCK_NAMESPACE,
       JSON.stringify([key.tenantId, key.jobName, key.subject]),
     );
+    // Read under the lock: the run that finishes last in lock order must also carry the
+    // latest finishedAt, otherwise a stale timestamp makes it the row that gets pruned.
+    const finishedAt = Temporal.Now.instant();
     await upsertOnConflict(
       tx,
       tenantJobRunsTable,
-      { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
+      { ...key, bullJobId, status: result, finishedAt, updatedAt: finishedAt },
       {
         conflictKeys: [...TENANT_RUN_CONFLICT_KEYS],
-        update: { status: result, finishedAt: now, updatedAt: now },
+        update: { status: result, finishedAt, updatedAt: finishedAt },
       },
     );
     await deleteMany(tx, tenantJobRunsTable, {

package/packages/bundled-features/src/metrics/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Metric integer filters reject fractions and out-of-range values; feature-name constants exported",
+    "detail": "Filters on smallint, integer and bigint columns now fail validation for decimals and values outside the column range instead of a Postgres cast error. FILES_FEATURE and FILES_TENANT_DATA_FEATURE are exported and reused by compose-features."
+  },
   {
     "version": "0.349.0",
     "type": "improvement",

package/packages/bundled-features/src/metrics/filters.ts

@@ -7,26 +7,34 @@ export const RESERVED_PAYLOAD_KEYS: readonly string[] = ["range", "timeZone", "t
 
 // Dashboard select options always send strings.
 const NUMERIC_STRING = /^-?\d+(\.\d+)?$/;
+const INTEGER_STRING = /^-?\d+$/;
 const MAX_FILTER_STRING_LENGTH = 200;
-const NUMERIC_PG_TYPES: ReadonlySet<string> = new Set([
-  "integer",
-  "int4",
-  "smallint",
-  "int2",
-  "bigint",
-  "serial",
-  "bigserial",
-  "double precision",
-]);
+const INTEGER_RANGES = {
+  smallint: { min: -32_768, max: 32_767 },
+  integer: { min: -2_147_483_648, max: 2_147_483_647 },
+  // bigint is bound as a JS number, so only the exactly representable range is accepted.
+  bigint: { min: Number.MIN_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER },
+} as const;
+const PG_INTEGER_KINDS: Readonly<Record<string, keyof typeof INTEGER_RANGES>> = {
+  smallint: "smallint",
+  int2: "smallint",
+  integer: "integer",
+  int4: "integer",
+  serial: "integer",
+  bigint: "bigint",
+  bigserial: "bigint",
+};
 
-export type FilterValueKind = "uuid" | "number" | "string";
+export type FilterValueKind = "uuid" | "number" | "string" | keyof typeof INTEGER_RANGES;
 
 /** Undefined = the column type cannot be filtered by a payload value without risking a Postgres cast error. */
 export function filterValueKindOf(pgType: string | undefined): FilterValueKind | undefined {
   if (pgType === undefined) return undefined;
   if (pgType === "uuid") return "uuid";
   if (pgType === "text") return "string";
-  if (NUMERIC_PG_TYPES.has(pgType) || pgType.startsWith("numeric")) return "number";
+  const integerKind = PG_INTEGER_KINDS[pgType];
+  if (integerKind !== undefined) return integerKind;
+  if (pgType === "double precision" || pgType.startsWith("numeric")) return "number";
   return undefined;
 }
 
@@ -44,8 +52,16 @@ export function metricFilterEntries(metric: MetricDefinition): readonly MetricFi
   );
 }
 
+function integerValueSchema(range: { readonly min: number; readonly max: number }): z.ZodType {
+  const bounded = z.number().int().min(range.min).max(range.max);
+  return z.union([bounded, z.string().regex(INTEGER_STRING).transform(Number).pipe(bounded)]);
+}
+
 function filterValueSchema(kind: FilterValueKind): z.ZodType {
   if (kind === "uuid") return z.uuid();
+  if (kind === "smallint" || kind === "integer" || kind === "bigint") {
+    return integerValueSchema(INTEGER_RANGES[kind]);
+  }
   if (kind === "number")
     return z.union([z.number(), z.string().regex(NUMERIC_STRING).transform(Number)]);
   return z.string().min(1).max(MAX_FILTER_STRING_LENGTH);

package/packages/bundled-features/src/personal-access-tokens/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "revokeAllPatTokensForUser detects begin() the same way as the transaction helpers",
+    "detail": "The transaction probe looked for begin() directly on the handle, so a pool wrapped by a legacy Drizzle connection fell back to a non-atomic update plus append. It now uses runnerCanBeginTransaction from bun-db, which unwraps the client first."
+  },
   {
     "version": "0.347.0",
     "type": "improvement",

package/packages/bundled-features/src/personal-access-tokens/revoke-for-user.ts

@@ -1,10 +1,13 @@
-import { transaction, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  runnerCanBeginTransaction,
+  transaction,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { append } from "@cosmicdrift/kumiko-framework/event-store";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import {
   PAT_REVOKED_AGGREGATE_TYPE,
   PAT_REVOKED_EVENT_QN,
@@ -12,11 +15,6 @@ import {
 } from "./pat-revoked-event.js";
 import { apiTokenTable } from "./schema/api-token.js";
 
-// A pool has begin(); a tx/savepoint handle does not and is already atomic.
-function canBeginTransaction(db: DbRunner): boolean {
-  return typeof propertyOf(db, "begin") === "function";
-}
-
 // Cross-tenant revoke: password-change and MFA-enable/disable are account-
 // level security events, not scoped to one tenant. Mirrors sessions'
 // sessionMassRevoker (session-callbacks.ts) which passes the boot-time
@@ -24,7 +22,8 @@ function canBeginTransaction(db: DbRunner): boolean {
 export async function revokeAllPatTokensForUser(db: DbRunner, userId: string): Promise<number> {
   // Update and event commit together: otherwise a failed append leaves the
   // tokens revoked with no event, and a retry matches no live row.
-  return canBeginTransaction(db)
+  // A pool has begin(); a tx/savepoint handle does not and is already atomic.
+  return runnerCanBeginTransaction(db)
     ? transaction(db, (tx) => revokeAndAppend(tx, userId))
     : revokeAndAppend(db, userId);
 }

package/packages/bundled-features/src/secrets/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "secrets delete no longer requires a declared key",
+    "detail": "secrets:write:delete used to answer 404 unknownKey for a key that no feature declares, so a row stored before the declaration gate existed could never be removed. Delete now skips the declaration check; writeRoles of a declared key or namespace still apply, and set keeps the gate."
+  },
   {
     "version": "0.364.0",
     "type": "improvement",

package/packages/bundled-features/src/secrets/handlers/delete.write.ts

@@ -18,7 +18,9 @@ export function createDeleteHandler(access: AccessRule = DEFAULT_SECRETS_ACCESS)
     access,
     handler: async (event, ctx) => {
       const secrets = requireSecretsContext(ctx, "secrets:write:delete");
-      const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key);
+      const gate = checkSecretKeyWrite(ctx.registry, event.user.roles, event.payload.key, {
+        allowUndeclared: true,
+      });
       if (!gate.ok) return gate.failure;
       const removed = await secrets.delete(event.user.tenantId, event.payload.key, {
         deletedBy: event.user.id,

package/packages/bundled-features/src/secrets/write-gate.ts

@@ -37,15 +37,21 @@ function namespaceAcceptsKey(namespace: SecretNamespaceDefinition, key: string):
 // Only keys declared via r.secret() or under a declared r.secretNamespace()
 // are writable through the API, so a tenant admin cannot plant arbitrary rows
 // next to the feature-owned ones. writeRoles narrows the handler access
-// further for a key or a whole namespace.
+// further for a key or a whole namespace. Delete passes allowUndeclared: it
+// creates nothing, and legacy rows under since-undeclared keys must stay removable.
 export function checkSecretKeyWrite(
   registry: Registry,
   userRoles: readonly string[],
   key: string,
+  options: { readonly allowUndeclared?: boolean } = {},
 ): SecretKeyWriteCheck {
   const keyDef = registry.getSecretKey(key);
   const namespace = keyDef ? undefined : registry.findSecretNamespace(key);
-  if (!keyDef && !(namespace && namespaceAcceptsKey(namespace, key))) {
+  if (
+    !keyDef &&
+    !(namespace && namespaceAcceptsKey(namespace, key)) &&
+    options.allowUndeclared !== true
+  ) {
     return unknownKeyFailure(key);
   }
   const writeRoles = keyDef?.writeRoles ?? namespace?.writeRoles;

package/packages/bundled-features/src/shared/index.ts

@@ -40,6 +40,14 @@ export {
 } from "./redact.js";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.js";
 export { requireForTenant } from "./require-for-tenant.js";
+export {
+  extensionForResourceContentType,
+  isResourceImageContentType,
+  isResourceImageFormat,
+  RESOURCE_IMAGE_FORMATS,
+  type ResourceImageContentType,
+  type ResourceImageFormat,
+} from "./resource-image-formats.js";
 export {
   type RowBoundGrantResult,
   redeemRowBoundGrant,

package/packages/bundled-features/src/shared/resource-image-formats.ts

@@ -0,0 +1,31 @@
+// Single source for the raster formats a template resource image may have: the normalizer, the
+// stored file extension, the data-URI embedding and the inline mail attachment name all derive
+// from it, so a new format cannot be accepted in one place and dropped in another.
+export const RESOURCE_IMAGE_FORMATS = {
+  png: { contentType: "image/png", extension: "png" },
+  jpeg: { contentType: "image/jpeg", extension: "jpg" },
+  gif: { contentType: "image/gif", extension: "gif" },
+  webp: { contentType: "image/webp", extension: "webp" },
+} as const;
+
+export type ResourceImageFormat = keyof typeof RESOURCE_IMAGE_FORMATS;
+export type ResourceImageContentType =
+  (typeof RESOURCE_IMAGE_FORMATS)[ResourceImageFormat]["contentType"];
+
+export function isResourceImageFormat(format: string | undefined): format is ResourceImageFormat {
+  return format !== undefined && Object.hasOwn(RESOURCE_IMAGE_FORMATS, format);
+}
+
+function formatForContentType(contentType: string) {
+  return Object.values(RESOURCE_IMAGE_FORMATS).find((entry) => entry.contentType === contentType);
+}
+
+export function isResourceImageContentType(
+  contentType: string,
+): contentType is ResourceImageContentType {
+  return formatForContentType(contentType) !== undefined;
+}
+
+export function extensionForResourceContentType(contentType: string): string | undefined {
+  return formatForContentType(contentType)?.extension;
+}

package/packages/bundled-features/src/shared/sharp-input-limits.ts

@@ -5,22 +5,21 @@
 // to be an OOM primitive for a single request.
 export const MAX_INPUT_PIXELS = 100_000_000;
 // sequentialRead trades random pixel access for lower peak memory on
-// streamed formats — applied at every decode entry point below since none
-// of them need non-sequential access to the *original* bytes (extract runs
-// against a single already-buffered region per call).
+// streamed formats. Shared by every sharp caller since none of them need
+// non-sequential access to the original bytes.
 export const SHARP_INPUT_OPTIONS = {
   limitInputPixels: MAX_INPUT_PIXELS,
   sequentialRead: true,
 } as const;
 
-// Shared trust boundary for every image byte source this renderer decodes —
-// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
-// alike: a base64 string in a field declaration isn't more trustworthy than
-// an upload just because it came from app code.
+// Shared trust boundary for every image byte source decoded through sharp:
+// uploads, overlay layers and template resources alike. A base64 string in a
+// field declaration isn't more trustworthy than an upload just because it
+// came from app code.
 export function assertNotSvg(format: string | undefined): void {
   if (format === "svg") {
     throw new Error(
-      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+      "SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this code doesn't need to cross.",
     );
   }
 }

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -118,8 +118,8 @@ export type WebhookDispatchDeps = {
   readonly requestTimeoutMs?: number;
 };
 
-// One hanging tenant-controlled receiver must not stall the shared
-// step-dispatcher consumer for every tenant.
+// Bounds a single hanging tenant-controlled receiver to this long. The consumer
+// is sequential and shared, so N hanging requests still delay other tenants by N times this.
 export const WEBHOOK_REQUEST_TIMEOUT_MS = 10_000;
 
 // Never includes the secret name or value — spec.auth.secret is a

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

@@ -1,4 +1,85 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "copy-locale copies the system default's files in a beforeTransaction phase and can no longer run as a nested write",
+    "detail": "When a tenant copies a locale from the system default, the image and attachment files are now read and written to the tenant's storage in a beforeTransaction phase. The transaction only creates the fileRef rows, and the uploaded binaries are released when it does not commit. Before, the storage I/O held the database transaction open.",
+    "migration": "Dispatch copy-locale as a top-level command, or from a perCommand handler via ctx.write. A handler that called it nested moves that call into a client or job, or becomes a perCommand handler."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Opening a document or mail editor with an empty body no longer marks the form as changed",
+    "detail": "Switching the editor's editable state on mount emitted an update, so DocumentTiptapEditor called onChange(\"<p></p>\") before the user typed anything and the surrounding form counted as dirty."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "onEditorReady receives null when the editor is destroyed",
+    "detail": "DocumentTiptapEditor and PlaceholderLineEditor call onEditorReady(null) on destroy, so a held handle no longer points at a destroyed editor. The callback type is (handle: DocumentEditorHandle | null) => void. The document designer drops the handle of an unmounted field, so placeholder insertion no longer targets a destroyed editor.",
+    "migration": "A custom onEditorReady callback must accept null and drop its stored handle when it receives it."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Document editor no longer blanks the app when late placeholders rebuild it",
+    "detail": "When the system placeholders or resource previews arrived in the same render as a new value (layout editor after opening or saving), the editor rebuilt itself and the value sync then read the destroyed editor. The TypeError unmounted the whole app and left a blank page. Both sync effects now skip a destroyed editor; the replacement editor picks up the value on its next render."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Steps block in mail and PDF templates",
+    "detail": "The document editor offers a steps block in the toolbar block menu. It stores a fixed list of stages (value=label, at most 8) and the variable that names the current stage. Mail and PDF render it as a row of bars and labels; stages up to the current one are coloured, the current label is bold. Invalid blocks are dropped by the sanitizer and render nothing. Layout regions do not offer the block."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A paragraph or heading that only holds an empty placeholder is left out of the rendered document",
+    "detail": "compileDocumentBodyToHandlebars wraps a p or h1 to h4 whose only content is one placeholder in an if block, so an empty optional value no longer leaves a blank line in mails and PDFs. Zero numbers and money values still render. Blocks with static text, images or several placeholders are unchanged."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "Mail layout buttons follow the branding accent colour",
+    "detail": "mailLayoutAppearance takes the tenant branding accent colour. When the layout uses the branding accent line, buttons in the mail body use that colour instead of the fixed dark teal. Invalid colours fall back to the previous default."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "A placeholder inside a button label is kept",
+    "detail": "The document schema allows placeholder chips inside a button label. Before, saving or seeding a body such as a button reading \"View {{pageName}}\" split the button: the label stopped at the placeholder and the rest landed in a new paragraph outside the button."
+  },
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "compileDocumentBodyToHandlebars takes a height cap for resource images",
+    "detail": "The new resourceImageMaxHeightPx option adds max-height and width:auto to resource images. The mail renderer caps images in a layout header at 64 px, so a square logo stays small while a wide wordmark keeps its 180 px width cap."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "resource-upload refuses key collisions between images and attachments and linking a non-active PDF template",
+    "detail": "Uploading an attachment under a key that holds an inline image, or an image under a key that holds an attachment or linked PDF, fails with template_attachment_invalid (code key_in_use) instead of silently replacing the entry. resource-link-pdf only accepts an active document-pdf template, so draft or archived templates no longer produce mails that fail at send time. When the link write fails after the file was stored, the orphaned storage object is deleted."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "collection kinds fail at boot; validate, diff-to-system, overview, seeding, bundle import and placeholder checks follow the write rules",
+    "detail": "createTemplateResolverFeature throws for a collection whose kind is mail, mail-layout or pdf-layout instead of failing on every save. The validate query ignores scope system for non-SystemAdmins. diff-to-system compares only against an active system template like reset-to-system. The overview reads rows in a stable order and reports truncated when its row limit is hit. Re-seeding notification templates reactivates an archived system row and applies a changed parentTemplateId. A bundle holds at most 50 locales. Dotted placeholders under a declared variable or list item field are reported as unknown because they never render a value. The document editor fallbacks are read-only and the placeholder line editor recolors chips when systemVariables change."
+  },
+  {
+    "version": "0.365.0",
+    "type": "fix",
+    "title": "Resource image formats come from one list",
+    "detail": "PNG, JPEG, GIF and WebP content types and extensions are defined once in the shared module and reused by the resource upload, the document body compiler and the email channel."
+  },
+  {
+    "version": "0.365.0",
+    "type": "breaking",
+    "title": "resource-upload, import-bundle and import-bundle-system upload in a beforeTransaction phase and can no longer run as nested writes",
+    "detail": "The three handlers now validate and upload their files before the write transaction opens and only create the fileRef and template rows inside it, so no database connection sits idle in a transaction during storage I/O. A rolled-back transaction releases the uploaded bytes. Because they now have a pre-transaction phase, the dispatcher rejects a nested ctx.write, ctx.writeAs or handler-to-handler call of them (\"has a pre-transaction phase\"). The exported storeTemplateResource is replaced by prepareTemplateResourceBeforeTransaction (beforeTransaction half) and storePreparedTemplateResource (in-transaction half).",
+    "migration": "Dispatch resource-upload, import-bundle and import-bundle-system as top-level commands, or from a perCommand handler via ctx.write. A handler that called them nested moves that call into a client or job, or becomes a perCommand handler. Code that called storeTemplateResource calls prepareTemplateResourceBeforeTransaction in a beforeTransaction phase and passes the result to storePreparedTemplateResource in the handler."
+  },
   {
     "version": "0.364.0",
     "type": "fix",