@cosmicdrift/kumiko-samples 0.362.0 → 0.363.0

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

@@ -1,4 +1,43 @@
 [
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "document-pdf requests name a template, the response carries fileName",
+    "detail": "The document-pdf payload is { slug, locale, variables } instead of ready HTML in content. The response has a fileName, RendererContext gets an optional filesForTenant (file access per tenant) and RendererError has the new code unavailable for a renderer backend that cannot be reached.",
+    "migration": "Callers that sent `payload: { content }` switch to a document-pdf template and pass slug, locale and variables (money-horse credit-schedule-pdf follows in #621); renderer-pdf callers pass slug and locale too. The enterprise package @cosmicdriftgamestudio/kumiko-renderer-puppeteer-client no longer builds against these types and is replaced by @cosmicdrift/kumiko-renderer-puppeteer-client."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "renderer plugins can preview a document",
+    "detail": "RendererPlugin gets the optional capability previewDocument(req, ctx), which returns the filled-in body and layout regions without calling the print service. template-resolver:query:preview with kind document-pdf uses it, so the editor shows replaced placeholders and the resource and required-placeholder checks; without such a plugin the preview keeps returning the body and raw layout."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "PdfOptions has landscape",
+    "detail": "The document-pdf options gain landscape, which the puppeteer-service passes to Chromium."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "RenderRequest kind mail replaces mail-html",
+    "detail": "RenderRequest and RenderResponse use kind mail with a MailPayload ({ slug, locale, variables, unsubscribeUrl? }) and a response of { subject, html, text, previewText? }. The export MailHtmlPayload is removed; use MailPayload. The default plugin name for kind mail stays mail-html. RendererContext gains an optional config accessor that plugins use for tenant locale, currency and branding.",
+    "migration": "Replace kind mail-html with mail in createRendererForTenant and render calls, pass { slug, locale, variables } instead of content/contentFormat, and read the subject from the response instead of building it yourself. Pass ctx.config in the RendererContext to get tenant locale, currency and branding."
+  },
+  {
+    "version": "0.363.0",
+    "type": "breaking",
+    "title": "renderer-simple, MailBranding and renderer kind \"notification\" are removed",
+    "detail": "Every mail is a stored template rendered by renderer-mail-html now. renderer-simple (createRendererSimpleFeature, simpleRenderer, createSimpleRenderer, RendererSimpleOptions, mail blocks with LocalizedText, MailBadge, MailChip, MailStage, MailStageState and MailTone), the MailBranding type, the renderer kind \"notification\" and AuthMailContent are gone. NotificationRenderer and RendererInput are removed from delivery, and createChannelEmailFeature no longer takes a renderer option. The type NotificationPayload is removed from renderer-foundation. The template-resolver keeps \"notification\" only as a stored kind so legacy rows stay readable; RENDER_KINDS is mail, document-pdf and image-snapshot.",
+    "migration": "Remove createRendererSimpleFeature() and any renderer or mailBranding option from your feature list and createChannelEmailFeature call. An r.notification that is sent by email needs template + meta (or localizedTemplate) and variables; the sections/header/footer data it carried is replaced by template variables. Branding (logo, footer) now comes from the tenant branding config and the mail layout of renderer-mail-html. Mount template-resolver, renderer-foundation and @cosmicdrift/kumiko-renderer-mail-html (composeRendererStack() mounts all of them) and run seedNotificationTemplates at boot. Existing template rows with kind \"notification\" are no longer rendered; re-create them as kind \"mail\" or archive them."
+  },
+  {
+    "version": "0.363.0",
+    "type": "improvement",
+    "title": "MailPayload.draft renders an unsaved mail template; RendererContext.db also accepts a TenantDb",
+    "detail": "MailDraft (content, meta, variableSchema) replaces the stored body and subject of the template with the payload's slug and keeps its stored images; a slug without a stored template renders as a tenant draft. The renderer sanitizes the draft body and validates its meta again, and the response carries no template provenance. RendererContext.db is widened from DbConnection to DbRunner | TenantDb."
+  },
   {
     "version": "0.306.0",
     "type": "breaking",

package/packages/bundled-features/src/renderer-foundation/constants.ts

@@ -1,11 +1,10 @@
-// Re-export aus template-resolver — gleiche RenderKind-Domäne. Beide
-// Bundles teilen sich die Enum, damit Plugins (renderer-mail-html etc.)
-// nicht zwei Quellen importieren müssen. Cross-feature-Imports gehen
-// über das Barrel (../template-resolver), nicht via deep-import.
+// Re-export from template-resolver — same RenderKind domain. Both
+// bundles share the enum so plugins (@cosmicdrift/kumiko-renderer-mail-html etc.)
+// do not have to import two sources. Cross-feature imports go
+// through the barrel (../template-resolver), not via deep import.
 import type { RenderKind as RenderKindLocal } from "../template-resolver/index.js";
 
-// Extension-point name for renderer plugins (renderer-simple,
-// renderer-mail-html, renderer-puppeteer-client, ...).
+// Extension-point name for renderer plugins (@cosmicdrift/kumiko-renderer-mail-html, @cosmicdrift/kumiko-renderer-puppeteer-client, ...).
 export const RENDERER_EXTENSION = "renderer" as const;
 
 export {
@@ -18,8 +17,7 @@ export {
 // Standard-Default-Plugin pro Kind, wenn Tenant keine explizite Config
 // gesetzt hat. App-Bootstrap kann das via TenantConfigKey überschreiben.
 export const DEFAULT_PLUGIN_BY_KIND: Readonly<Record<RenderKindLocal, string>> = {
-  notification: "simple",
-  "mail-html": "mail-html",
+  mail: "mail-html",
   "document-pdf": "puppeteer",
   "image-snapshot": "puppeteer",
 };

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

@@ -2,18 +2,18 @@ import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engi
 import { RENDERER_EXTENSION } from "./constants.js";
 import { isRendererRegistrationPlugin, type RendererPlugin } from "./types.js";
 
-// renderer-foundation — Plugin-Foundation für Renderer (Notification,
-// HTML-Mail, PDF, Image). Plan-Doc:
+// renderer-foundation — plugin foundation for renderers (HTML mail, PDF,
+// image). Plan doc:
 // kumiko-platform/docs/plans/features/renderer-foundation.md
 //
-// Pattern symmetrisch zu ai-foundation: Foundation definiert den
-// Extension-Point `renderer`, Plugins (renderer-simple, renderer-mail-html,
-// renderer-puppeteer-client) registrieren sich via `r.useExtension`.
-// Konsumenten holen sich Plugin runtime via createRendererForTenant.
+// Pattern symmetric to ai-foundation: the foundation defines the
+// extension point `renderer`, plugins (@cosmicdrift/kumiko-renderer-mail-html,
+// @cosmicdrift/kumiko-renderer-puppeteer-client) register via `r.useExtension`.
+// Consumers get a plugin at runtime via createRendererForTenant.
 export function createRendererFoundationFeature() {
   return defineFeature("renderer-foundation", (r) => {
     r.describe(
-      'Plugin registry for content rendering (notification HTML, mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block \u2014 add `renderer-simple` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.',
+      'Plugin registry for content rendering (mail HTML, PDF, images): call `foundation.createRendererForTenant({ tenantId, kind })` at render time to get the right renderer plugin selected by kind, with tenant-level overrides via the `rendererPluginByKind` config key. Requires `template-resolver` (declared via `r.requires`). Low-level building block \u2014 add `renderer-mail-html` (or write a custom plugin via `r.useExtension("renderer", name, { kinds, render })`) rather than using this feature alone.',
     );
     r.uiHints({
       displayLabel: "Renderer Foundation",

package/packages/bundled-features/src/renderer-foundation/index.ts

@@ -1,3 +1,4 @@
+export { attachmentFileNameSchema } from "../shared/index.js";
 export {
   createRendererFoundationApi,
   type RendererFoundationApi,
@@ -14,15 +15,25 @@ export {
 export { collectRendererPlugins, createRendererFoundationFeature } from "./feature.js";
 export {
   type DocumentPayload,
+  type DocumentPdfDraft,
+  type DocumentPdfPayload,
+  type DocumentPreview,
+  type DocumentPreviewRequest,
+  type FileAttachmentRef,
   type ImageOptions,
+  type InlineAttachmentRef,
   isRendererRegistrationPlugin,
-  type MailHtmlPayload,
-  type NotificationPayload,
+  type MailAttachmentRef,
+  type MailDraft,
+  type MailPayload,
   type PdfOptions,
+  type RenderedPdfAttachmentRef,
+  type RenderedTemplateRef,
   type RendererContext,
   RendererError,
   type RendererPlugin,
   type RendererRegistrationPlugin,
+  type RenderProvenance,
   type RenderRequest,
   type RenderResponse,
 } from "./types.js";

package/packages/bundled-features/src/renderer-foundation/types.ts

@@ -1,43 +1,101 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { ConfigAccessor, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FileContext } from "@cosmicdrift/kumiko-framework/files";
+import type {
+  LinkedResourceEntry,
+  MailTemplateMeta,
+  PdfPageFormat,
+  PdfTemplateMeta,
+  TemplateScope,
+} from "../template-resolver/index.js";
 import { type ContentFormat, RENDERER_EXTENSION, type RenderKind } from "./constants.js";
 
 // RenderRequest — Plugins erhalten das. Resource-Mode wählt der Caller
 // (renderer-foundation api) je nach kind oder explizit. Plugin selbst
 // entscheidet nicht — es bekommt eine schon aufgelöste Form.
 export type RenderRequest =
-  | { kind: "notification"; payload: NotificationPayload }
-  | { kind: "mail-html"; payload: MailHtmlPayload }
-  | { kind: "document-pdf"; payload: DocumentPayload; options?: PdfOptions }
+  | { kind: "mail"; payload: MailPayload }
+  | { kind: "document-pdf"; payload: DocumentPdfPayload; options?: PdfOptions }
   | { kind: "image-snapshot"; payload: DocumentPayload; options?: ImageOptions };
 
-export type RenderResponse =
-  | { kind: "notification"; html: string; text?: string }
-  | { kind: "mail-html"; html: string; text: string }
-  | { kind: "document-pdf"; pdfBytes: Uint8Array; pageCount: number; sizeBytes: number }
+export type RenderedTemplateRef = {
+  readonly templateId: string;
+  readonly templateVersion: number;
+  readonly scope: TemplateScope;
+};
+
+export type RenderProvenance = {
+  readonly template?: RenderedTemplateRef;
+  readonly layout?: RenderedTemplateRef;
+};
+
+// Image a rendered mail embeds by Content-ID; the send job reads the bytes.
+export type InlineAttachmentRef = {
+  readonly kind: "inline";
+  readonly cid: string;
+  readonly fileRefId: string;
+};
+
+// A stored file attached as-is; the send job reads the bytes.
+export type FileAttachmentRef = {
+  readonly kind: "file";
+  readonly fileRefId: string;
+  readonly fileName: string;
+};
+
+// A PDF rendered from a stored document template when the mail is sent, so the job
+// payload carries the variables instead of the bytes.
+export type RenderedPdfAttachmentRef = {
+  readonly kind: "rendered-pdf";
+  readonly templateSlug: string;
+  readonly variables: Readonly<Record<string, unknown>>;
+  readonly fileName: string;
+  readonly locale?: string;
+};
+
+export type MailAttachmentRef = InlineAttachmentRef | FileAttachmentRef | RenderedPdfAttachmentRef;
+
+export type RenderResponse = (
+  | {
+      kind: "mail";
+      subject: string;
+      html: string;
+      text: string;
+      previewText?: string;
+      attachments?: readonly MailAttachmentRef[];
+    }
+  | {
+      kind: "document-pdf";
+      pdfBytes: Uint8Array;
+      pageCount: number;
+      sizeBytes: number;
+      fileName: string;
+    }
   | {
       kind: "image-snapshot";
       imageBytes: Uint8Array;
       format: "png" | "jpg";
       width: number;
       height: number;
-    };
+    }
+) &
+  RenderProvenance;
 
-export type NotificationPayload = {
-  readonly template?: string;
-  readonly content?: string;
-  readonly contentFormat?: ContentFormat;
-  readonly variables?: Readonly<Record<string, unknown>>;
-  readonly locale?: string;
+// An unsaved version of the mail template; rendering it never reads its stored body or subject.
+export type MailDraft = {
+  readonly content: string;
+  readonly meta: MailTemplateMeta;
+  readonly variableSchema?: Readonly<Record<string, unknown>>;
+  /** Images and attachments of the row being edited; absent means those of the stored template. */
+  readonly linkedResources?: Readonly<Record<string, LinkedResourceEntry>>;
 };
 
-export type MailHtmlPayload = {
-  readonly template?: string;
-  readonly content?: string;
-  readonly contentFormat?: ContentFormat;
-  readonly variables?: Readonly<Record<string, unknown>>;
-  readonly locale?: string;
-  readonly subject?: string;
+export type MailPayload = {
+  readonly slug: string;
+  readonly locale: string;
+  readonly variables: Readonly<Record<string, unknown>>;
+  readonly unsubscribeUrl?: string;
+  readonly draft?: MailDraft;
 };
 
 export type DocumentPayload = {
@@ -48,13 +106,46 @@ export type DocumentPayload = {
   readonly locale?: string;
 };
 
+export type DocumentPdfPayload = {
+  readonly slug: string;
+  readonly locale: string;
+  readonly variables: Readonly<Record<string, unknown>>;
+};
+
+// An unsaved version of the document template, like MailDraft.
+export type DocumentPdfDraft = {
+  readonly content: string;
+  readonly meta: PdfTemplateMeta | null;
+  readonly variableSchema?: Readonly<Record<string, unknown>>;
+};
+
+export type DocumentPreviewRequest = DocumentPdfPayload & { readonly draft?: DocumentPdfDraft };
+
+// What an editor shows for a document: the printable HTML with the values filled in,
+// without calling any print service.
+export type DocumentPreview = {
+  readonly title: string;
+  readonly fileName: string;
+  readonly bodyHtml: string;
+  readonly layout: {
+    readonly slug: string;
+    readonly scope: TemplateScope;
+    readonly headerHtml: string;
+    readonly signatureHtml: string;
+    readonly footerHtml: string;
+  } | null;
+  /** Image keys the body or the layout asks for that no file is linked to. */
+  readonly missingResourceKeys: readonly string[];
+};
+
 export type PdfOptions = {
-  readonly format?: "A4" | "Letter";
+  readonly format?: PdfPageFormat;
   readonly marginMm?: { top?: number; right?: number; bottom?: number; left?: number };
   readonly headerTemplate?: string;
   readonly footerTemplate?: string;
   readonly printBackground?: boolean;
   readonly displayHeaderFooter?: boolean;
+  readonly landscape?: boolean;
 };
 
 export type ImageOptions = {
@@ -75,33 +166,39 @@ export type ImageOptions = {
 //   const tplApi = createTemplateResolverApi(ctx.db);
 //   const layout = await tplApi.resolveTemplate({ tenantId: ctx.tenantId, slug, kind });
 export type RendererContext = {
-  readonly db: DbConnection;
+  readonly db: DbRunner | TenantDb;
   readonly registry: Registry;
   readonly tenantId: TenantId;
+  /** Tenant-scoped config for plugins that read the tenant currency or
+   *  branding; plugins fall back to request defaults when absent. */
+  readonly config?: ConfigAccessor;
+  /** Only plugins that embed resource bytes (PDF) need it; without it images are dropped. */
+  readonly filesForTenant?: (tenantId: string) => FileContext | undefined;
 };
 
-// RendererPlugin-Contract — pro Plugin (renderer-simple, renderer-mail-html,
+// RendererPlugin-Contract — pro Plugin (renderer-mail-html,
 // renderer-puppeteer-client). Plugin deklariert welche kinds es bedienen
 // kann; Foundation-Resolver wählt basierend auf Tenant-Config + kind.
 //
-// **Plugin-Invarianten:**
-// - `kinds` muss min. 1 Element haben (sonst nie ausgewählt)
-// - `render(req, ctx)`-Response.kind MUSS req.kind matchen
-// - Plugin ist zustandslos: kein internal-state zwischen render-Calls
-// - Plugin wirft `RendererError` für domain-Fehler (nicht bare Error)
-// - `ctx` ist required. Plugins ohne Service-Deps (z.B. renderer-simple)
-//   ignorieren ihn einfach — TS function-arg variance erlaubt `(req) => ...`-
-//   Implementations weiterhin (Implementation-Args ≤ Contract-Args ist OK).
+// Plugin invariants:
+// - `kinds` has at least one entry, otherwise the plugin is never picked.
+// - The response kind of `render(req, ctx)` matches req.kind.
+// - Plugins are stateless between render calls.
+// - Domain failures throw `RendererError`, not a bare Error.
+// - `ctx` is required; plugins without service deps ignore it. Function-arg
+//   variance still lets `(req) => ...` implementations satisfy the contract.
 export type RendererPlugin = {
   readonly name: string;
   readonly kinds: ReadonlyArray<RenderKind>;
   render(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
+  /** Optional: plugins that print documents offer a preview that never reaches the print service. */
+  previewDocument?(req: DocumentPreviewRequest, ctx: RendererContext): Promise<DocumentPreview>;
 };
 
 export class RendererError extends Error {
   constructor(
     message: string,
-    public readonly code: "no_plugin_for_kind" | "invalid_payload" | "other",
+    public readonly code: "no_plugin_for_kind" | "invalid_payload" | "unavailable" | "other",
   ) {
     super(message);
     this.name = "RendererError";

package/packages/bundled-features/src/renderer-pdf/feature.ts

@@ -25,7 +25,13 @@ export async function renderTablePdfRequest(req: RenderRequest): Promise<RenderR
     ...(req.options?.format && { format: req.options.format }),
     ...(req.options?.marginMm && { marginMm: req.options.marginMm }),
   });
-  return { kind: "document-pdf", pdfBytes, pageCount, sizeBytes: pdfBytes.byteLength };
+  return {
+    kind: "document-pdf",
+    pdfBytes,
+    pageCount,
+    sizeBytes: pdfBytes.byteLength,
+    fileName: `${req.payload.slug}.pdf`,
+  };
 }
 
 export function createRendererPdfFeature(): FeatureDefinition {

package/packages/bundled-features/src/sessions/db/queries/cleanup.ts

@@ -6,7 +6,7 @@ export async function deleteStaleSessionsBatch(
   olderThanDays: number,
   batchSize: number,
 ): Promise<number> {
-  const rows = (await asRawClient(db).unsafe(
+  const rows = await asRawClient(db).unsafe<{ id: string }>(
     `DELETE FROM "store_user_sessions"
      WHERE "id" IN (
        SELECT "id" FROM "store_user_sessions"
@@ -16,6 +16,6 @@ export async function deleteStaleSessionsBatch(
      )
      RETURNING "id"`,
     [olderThanDays, batchSize],
-  )) as readonly { id: string }[];
+  );
   return rows.length;
 }

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

@@ -71,11 +71,9 @@ export function bindAutoRevokeFromFeature(
 ): BindAutoRevokeOnPasswordChange | undefined {
   const exports = feature.exports;
   if (exports && typeof exports === "object" && "bindAutoRevokeOnPasswordChange" in exports) {
-    const { bindAutoRevokeOnPasswordChange } = exports as {
-      bindAutoRevokeOnPasswordChange: unknown;
-    };
+    const { bindAutoRevokeOnPasswordChange } = exports;
     if (typeof bindAutoRevokeOnPasswordChange === "function") {
-      // @cast-boundary exports-walk — feature.exports is untyped by design
+      // @cast-boundary feature-exports — feature.exports is untyped by design
       return bindAutoRevokeOnPasswordChange as BindAutoRevokeOnPasswordChange;
     }
   }

package/packages/bundled-features/src/sessions/handlers/list.query.ts

@@ -4,6 +4,7 @@ import {
   definePagedQueryHandler,
   MAX_LIST_LIMIT,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { decryptStoredPii } from "../../shared/index.js";
 import { userSessionTable } from "../schema/user-session.js";
@@ -17,7 +18,7 @@ const SORTABLE_COLUMNS = ["id", "userId", "createdAt", "expiresAt", "revokedAt"]
 type SortableColumn = (typeof SORTABLE_COLUMNS)[number];
 
 function isSortableColumn(value: string): value is SortableColumn {
-  return (SORTABLE_COLUMNS as readonly string[]).includes(value);
+  return isOneOf(SORTABLE_COLUMNS, value);
 }
 
 // Admin view of every session in the active tenant. ctx.db (TenantDb)

package/packages/bundled-features/src/shared/attachment-file-name.ts

@@ -0,0 +1,39 @@
+import * as z from "zod";
+
+const MAX_FILE_NAME_LENGTH = 255;
+
+function hasControlCharacter(value: string): boolean {
+  return value.split("").some((char) => {
+    const code = char.charCodeAt(0);
+    return code <= 0x1f || code === 0x7f;
+  });
+}
+
+export const attachmentFileNameSchema = z
+  .string()
+  .min(1)
+  .max(MAX_FILE_NAME_LENGTH)
+  .refine((name) => !name.includes("/") && !name.includes("\\") && !hasControlCharacter(name), {
+    message: "file name must not contain path separators or control characters",
+  });
+
+const PDF_FILE_NAME_MAX_LENGTH = 200;
+const PDF_EXTENSION = ".pdf";
+
+// Shared by everything that names a rendered PDF, so a mail attachment and a download of the same
+// template get the same name. The cut leaves room for the extension: the attachment schema caps
+// rendered-pdf names, and a name that only fits without ".pdf" would fail it.
+export function sanitizePdfAttachmentFileName(raw: string, templateSlug: string): string {
+  const cleaned = raw
+    .split("")
+    .filter((char) => !hasControlCharacter(char))
+    .join("")
+    .replace(/[/\\";]/g, "-")
+    .replaceAll("..", "-")
+    .trim()
+    .slice(0, PDF_FILE_NAME_MAX_LENGTH - PDF_EXTENSION.length)
+    .trim();
+  const lastSegment = templateSlug.split(":").pop() ?? templateSlug;
+  if (cleaned === "") return `${lastSegment}${PDF_EXTENSION}`;
+  return cleaned.toLowerCase().endsWith(PDF_EXTENSION) ? cleaned : `${cleaned}${PDF_EXTENSION}`;
+}

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

@@ -1,5 +1,9 @@
 export { collectErasureFailure, throwIfErasureFailed } from "./assert-erased.js";
 export { assertNoWhereRuleInOwnershipWrite } from "./assert-no-where-rule-in-ownership-write.js";
+export {
+  attachmentFileNameSchema,
+  sanitizePdfAttachmentFileName,
+} from "./attachment-file-name.js";
 export {
   type ChunkedMigrationOptions,
   type ChunkedMigrationResult,
@@ -18,6 +22,7 @@ export { isWithinGracePeriod } from "./grace-period.js";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.js";
 export { isTenantDb } from "./is-tenant-db.js";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.js";
+export { mailHeading, mailParagraph, mailRepeatedRows } from "./mail-template-body.js";
 export { mapWithConcurrency } from "./map-with-concurrency.js";
 export {
   denyUnlessJoinRowParentVisible,
@@ -43,6 +48,7 @@ export {
 export { runInSubTransaction } from "./run-in-sub-transaction.js";
 export { registrationLocaleFromRequest, sessionLocaleField } from "./session-locale-field.js";
 export { sessionTimezoneField } from "./session-timezone-field.js";
+export { assertNotSvg, MAX_INPUT_PIXELS, SHARP_INPUT_OPTIONS } from "./sharp-input-limits.js";
 export {
   peekTokenSubject,
   signToken,

package/packages/bundled-features/src/shared/is-tenant-db.ts

@@ -5,5 +5,5 @@ import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 // Shared so retention/compliance-profile resolvers that accept either (bulk cron
 // vs. per-hook TenantDb) branch through one predicate instead of duplicating it.
 export function isTenantDb(db: DbRunner | TenantDb): db is TenantDb {
-  return typeof (db as Partial<TenantDb>).unsafeRaw === "function";
+  return "unsafeRaw" in db && typeof db.unsafeRaw === "function";
 }

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

@@ -0,0 +1,25 @@
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+
+const SLOT_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+// Author text uses `{name}` slots. The text is escaped first and the slots are
+// swapped for variable nodes afterwards, so a slot can never smuggle markup.
+export function mailTextWithSlotsHtml(text: string): string {
+  return escapeHtml(text).replace(
+    SLOT_PATTERN,
+    (_, name: string) => `<span data-variable="${escapeHtmlAttr(name)}"></span>`,
+  );
+}
+
+export function mailParagraph(text: string): string {
+  return `<p>${mailTextWithSlotsHtml(text)}</p>`;
+}
+
+export function mailHeading(text: string): string {
+  return `<h2>${mailTextWithSlotsHtml(text)}</h2>`;
+}
+
+// One table row per list entry; the cell shows the entry's `field`.
+export function mailRepeatedRows(listName: string, field: string): string {
+  return `<table><tbody><tr data-each="${escapeHtmlAttr(listName)}"><td><p><span data-variable="${escapeHtmlAttr(field)}"></span></p></td></tr></tbody></table>`;
+}

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

@@ -0,0 +1,26 @@
+// Sharp-free so callers can import the limits without loading the native binding.
+
+// Above this, a decoded pixel buffer runs into hundreds of MB before any
+// resize even happens — sharp's own default (~268MP) is still large enough
+// 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).
+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.
+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.",
+    );
+  }
+}

package/packages/bundled-features/src/shared/signup-handover.ts

@@ -13,6 +13,7 @@
 
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 
 export const EXT_SIGNUP_HANDOVER = "signupHandover" as const;
 
@@ -46,10 +47,9 @@ export type SignupHandoverProvider = {
 
 export function isSignupHandoverProvider(options: unknown): options is SignupHandoverProvider {
   return (
-    typeof options === "object" &&
-    options !== null &&
-    typeof (options as Record<string, unknown>)["verifyGrant"] === "function" &&
-    typeof (options as Record<string, unknown>)["mintClaim"] === "function"
+    isPlainObject(options) &&
+    typeof options["verifyGrant"] === "function" &&
+    typeof options["mintClaim"] === "function"
   );
 }
 

package/packages/bundled-features/src/tags/handlers/assign-tag.write.ts

@@ -1,5 +1,6 @@
 import type { AccessRule, WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { denyUnlessJoinRowParentVisible } from "../../shared/index.js";
 import { tagAssignmentAggregateId } from "../aggregate-id.js";
 import { DEFAULT_TAG_ACCESS } from "../constants.js";
@@ -67,7 +68,10 @@ export function createAssignTagHandler(
       // above and this restore() call, so restore() correctly refuses with
       // "not_deleted" — but the desired end state is already true. Converge
       // like the create() race below instead of surfacing a spurious error.
-      if ((restored.error.details as { reason?: string } | undefined)?.reason === "not_deleted") {
+      if (
+        isPlainObject(restored.error.details) &&
+        restored.error.details["reason"] === "not_deleted"
+      ) {
         return { isSuccess: true as const, data: { id } };
       }
       if (restored.error.code !== "not_found") return restored;

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

@@ -21,7 +21,8 @@ export function contrastText(color: string): "#000000" | "#ffffff" | null {
 function hexToRgb(color: string): { r: number; g: number; b: number } | null {
   const match = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(color.trim());
   if (match === null) return null;
-  const short = match[1] as string;
+  const short = match[1];
+  if (short === undefined) return null;
   const hex =
     short.length === 3
       ? `${short[0]}${short[0]}${short[1]}${short[1]}${short[2]}${short[2]}`