@cosmicdrift/kumiko-samples 0.359.0 → 0.360.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.359.0",
+  "version": "0.360.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.359.0",
+  "version": "0.360.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -116,6 +116,7 @@
     "./channel-teams": "./src/channel-teams/index.ts",
     "./channel-telegram": "./src/channel-telegram/index.ts",
     "./renderer-simple": "./src/renderer-simple/index.ts",
+    "./renderer-pdf": "./src/renderer-pdf/index.ts",
     "./files-provider-s3": "./src/files-provider-s3/index.ts",
     "./rate-limiting": "./src/rate-limiting/index.ts",
     "./presets": "./src/presets/index.ts",
@@ -166,6 +167,7 @@
     "mailparser": "^3.9.32",
     "marked": "^18.0.3",
     "nodemailer": "^10.0.13",
+    "pdf-lib": "^1.17.1",
     "qrcode": "^1.5.4",
     "react": "^19.2.6",
     "sharp": "^0.35.5",
@@ -555,6 +557,10 @@
         "types": "./dist/renderer-simple/index.d.ts",
         "default": "./dist/renderer-simple/index.js"
       },
+      "./renderer-pdf": {
+        "types": "./dist/renderer-pdf/index.d.ts",
+        "default": "./dist/renderer-pdf/index.js"
+      },
       "./files-provider-s3": {
         "types": "./dist/files-provider-s3/index.d.ts",
         "default": "./dist/files-provider-s3/index.js"
@@ -683,6 +689,7 @@
     "@testing-library/user-event": "^14.6.1",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
-    "jsqr": "^1.4.0"
+    "jsqr": "^1.4.0",
+    "unpdf": "^1.8.1"
   }
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-pages.ts

@@ -1,7 +1,7 @@
 // Public § 312k pages (/legal/kuendigen, /legal/cancel): form → review → confirm,
 // no JavaScript. Every echoed value goes through escapeHtml/escapeHtmlAttr.
 
-import type { AnonymousExtraRoute } from "@cosmicdrift/kumiko-framework/api";
+import { type AnonymousExtraRoute, getSessionCookies } from "@cosmicdrift/kumiko-framework/api";
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { Context } from "hono";
 import { getCookie } from "hono/cookie";
@@ -279,7 +279,6 @@ type WriteResponseBody = {
 const RATE_LIMITED_CODE = "rate_limited";
 
 const TENANT_HEADER = "x-tenant";
-const TENANT_COOKIE = "kumiko_tenant";
 // Exactly what the anonymous tenant resolution reads. The resolver and its
 // trust rules still decide; the re-entry only sees what a direct /api/write
 // from this client would see. Never the session cookie or Authorization (the
@@ -298,9 +297,10 @@ function reentryHeaders(c: Context): Headers {
     const value = c.req.header(name);
     if (value !== undefined) headers.set(name, value);
   }
-  const tenantCookie = getCookie(c, TENANT_COOKIE);
+  const tenantCookieName = getSessionCookies(c).names.tenant;
+  const tenantCookie = getCookie(c, tenantCookieName);
   if (tenantCookie !== undefined) {
-    headers.set("cookie", `${TENANT_COOKIE}=${encodeURIComponent(tenantCookie)}`);
+    headers.set("cookie", `${tenantCookieName}=${encodeURIComponent(tenantCookie)}`);
   }
   return headers;
 }

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.360.0",
+    "type": "fix",
+    "title": "Finished tenant job run replaces the older one atomically",
+    "detail": "recordTenantRunOutcome wrote the new completed or failed row and pruned older finished rows of the same tenant, job and subject in two separate statements, so the store briefly held two finished rows per subject, and two runs of one subject finishing together could each miss the other's row and leave both. Both writes now run in one transaction under a per-key advisory lock (namespace tjrl). jobs:query:tenant-runs already showed only the newest finished row, so its result does not change."
+  },
   {
     "version": "0.354.0",
     "type": "breaking",

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

@@ -167,6 +167,8 @@ async function encryptStartedPayload(
 // pg_advisory_xact_lock namespace (int4): 'tjfl' as ASCII, disjoint from the
 // framework's other fixed advisory-lock keys.
 const TENANT_JOB_FAILURE_LOCK_NAMESPACE = 0x746a666c;
+// 'tjrl': serialises the finished-row write + prune per tenant run key.
+const TENANT_JOB_RUN_LOCK_NAMESPACE = 0x746a726c;
 
 // fw#3079 — which row the tenant-visible failure record lives in: one per
 // (tenant, job, subject), so the next outcome of the same work replaces or
@@ -311,16 +313,27 @@ async function recordTenantRunOutcome(
     // skip: retry pending, the row stays active until the final attempt
     return;
   }
-  await upsertOnConflict(
-    db,
-    tenantJobRunsTable,
-    { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
-    { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
-  );
-  await deleteMany(db, tenantJobRunsTable, {
-    ...key,
-    status: { in: ["completed", "failed"] },
-    bullJobId: { ne: bullJobId },
+  // One transaction: a reader never sees the new finished row next to the
+  // one it replaces. The per-key lock keeps two runs of the same subject that
+  // finish together from each missing the other's uncommitted row and leaving
+  // both behind.
+  await transaction(db, async (tx) => {
+    await acquireNamespacedAdvisoryLock(
+      tx,
+      TENANT_JOB_RUN_LOCK_NAMESPACE,
+      JSON.stringify([key.tenantId, key.jobName, key.subject]),
+    );
+    await upsertOnConflict(
+      tx,
+      tenantJobRunsTable,
+      { ...key, bullJobId, status: result, finishedAt: now, updatedAt: now },
+      { conflictKeys: ["bullJobId"], update: { status: result, finishedAt: now, updatedAt: now } },
+    );
+    await deleteMany(tx, tenantJobRunsTable, {
+      ...key,
+      status: { in: ["completed", "failed"] },
+      bullJobId: { ne: bullJobId },
+    });
   });
 }
 

package/packages/bundled-features/src/renderer-pdf/README.md

@@ -0,0 +1,27 @@
+# renderer-pdf
+
+Public `document-pdf` renderer plugin: draws a table document as PDF in pure JavaScript (`pdf-lib`, standard Helvetica fonts), no browser and no Puppeteer service. Same input gives byte-identical output.
+
+## Pure function
+
+```typescript
+import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
+
+const { pdfBytes, pageCount } = await renderTablePdf(
+  {
+    title: "Prüfprotokoll",
+    meta: [{ label: "Anlage", value: "Kessel 3" }],
+    columns: [{ header: "Datum" }, { header: "Prüfer", weight: 2 }, { header: "Kosten", align: "right" }],
+    rows: [["03.02.2026", "Müller", "120,00 €"]],
+    footerText: "Kumiko GmbH",
+    pageLabel: "Seite {page} von {pages}",
+  },
+  { format: "A4" },
+);
+```
+
+The caller passes ready-formatted strings (dates, numbers); the renderer never reads the clock. Characters Helvetica (WinAnsi) cannot encode are drawn as `?`; umlauts, `ß` and `€` are kept.
+
+## Plugin
+
+Mount `createRendererPdfFeature()` next to `renderer-foundation`. It serves `kind: "document-pdf"` with a `PdfTableDocument` in `payload.variables`; `options.format` and `options.marginMm` apply. Invalid variables raise `RendererError("invalid_payload")`. A Puppeteer plugin keeps precedence (`DEFAULT_PLUGIN_BY_KIND`) when mounted.

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

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "Pure-JS PDF renderer for table documents",
+    "detail": "renderTablePdf(doc, options?) renders a PdfTableDocument (title, subtitle, meta lines, weighted columns, wrapped cells, header row repeated per page, footerText and a pageLabel template with {page} and {pages}) to PDF bytes with pdf-lib. Characters outside WinAnsi are replaced by \"?\". Identical input yields identical bytes. createRendererPdfFeature() registers it as plugin \"pdf\" for kind \"document-pdf\"; payload.variables is validated against pdfTableDocumentSchema, anything else fails with RendererError invalid_payload."
+  }
+]

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

@@ -0,0 +1,48 @@
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  RENDERER_EXTENSION,
+  RendererError,
+  type RenderRequest,
+  type RenderResponse,
+} from "../renderer-foundation/index.js";
+import { pdfTableDocumentSchema, renderTablePdf } from "./render-table-pdf.js";
+
+export async function renderTablePdfRequest(req: RenderRequest): Promise<RenderResponse> {
+  if (req.kind !== "document-pdf") {
+    throw new RendererError(
+      `renderer-pdf supports only kind="document-pdf", got "${req.kind}"`,
+      "invalid_payload",
+    );
+  }
+  const parsed = pdfTableDocumentSchema.safeParse(req.payload.variables);
+  if (!parsed.success) {
+    throw new RendererError(
+      `renderer-pdf: payload.variables is not a table document: ${parsed.error.message}`,
+      "invalid_payload",
+    );
+  }
+  const { pdfBytes, pageCount } = await renderTablePdf(parsed.data, {
+    ...(req.options?.format && { format: req.options.format }),
+    ...(req.options?.marginMm && { marginMm: req.options.marginMm }),
+  });
+  return { kind: "document-pdf", pdfBytes, pageCount, sizeBytes: pdfBytes.byteLength };
+}
+
+export function createRendererPdfFeature(): FeatureDefinition {
+  return defineFeature("renderer-pdf", (r) => {
+    r.describe(
+      'Renderer plugin for `kind="document-pdf"` that draws a table document (title, meta lines, weighted columns, repeating header, page footer) as a PDF in pure JavaScript, without a browser or Puppeteer service. `payload.variables` must be a `PdfTableDocument`. Requires `renderer-foundation`; mount a Puppeteer-based plugin instead when you need HTML/CSS layouts.',
+    );
+    r.uiHints({
+      displayLabel: "Renderer · PDF tables",
+      category: "notifications",
+      recommended: false,
+    });
+    r.requires("renderer-foundation");
+
+    r.useExtension(RENDERER_EXTENSION, "pdf", {
+      kinds: ["document-pdf"] as const,
+      render: (req) => renderTablePdfRequest(req),
+    });
+  });
+}

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

@@ -0,0 +1,9 @@
+export { createRendererPdfFeature } from "./feature.js";
+export {
+  type PdfTableColumn,
+  type PdfTableDocument,
+  type PdfTableOptions,
+  type PdfTableResult,
+  pdfTableDocumentSchema,
+  renderTablePdf,
+} from "./render-table-pdf.js";

package/packages/bundled-features/src/renderer-pdf/render-table-pdf.ts

@@ -0,0 +1,433 @@
+import { PDFDocument, type PDFFont, type PDFPage, rgb, StandardFonts } from "pdf-lib";
+import * as z from "zod";
+import { RendererError } from "../renderer-foundation/index.js";
+
+export const pdfTableDocumentSchema = z.object({
+  title: z.string(),
+  subtitle: z.string().optional(),
+  meta: z.array(z.object({ label: z.string(), value: z.string() })).optional(),
+  columns: z
+    .array(
+      z.object({
+        header: z.string(),
+        weight: z.number().positive().optional(),
+        align: z.enum(["left", "right"]).optional(),
+      }),
+    )
+    .min(1),
+  rows: z.array(z.array(z.string())),
+  emptyText: z.string().optional(),
+  footerText: z.string().optional(),
+  pageLabel: z.string().optional(),
+});
+
+export type PdfTableColumn = {
+  readonly header: string;
+  readonly weight?: number;
+  readonly align?: "left" | "right";
+};
+
+export type PdfTableDocument = {
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly meta?: readonly { readonly label: string; readonly value: string }[];
+  readonly columns: readonly PdfTableColumn[];
+  readonly rows: readonly (readonly string[])[];
+  readonly emptyText?: string;
+  readonly footerText?: string;
+  /** Template with `{page}` and `{pages}`; default `"{page} / {pages}"`. */
+  readonly pageLabel?: string;
+};
+
+export type PdfTableOptions = {
+  readonly format?: "A4" | "Letter";
+  readonly marginMm?: {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+  };
+};
+
+export type PdfTableResult = { readonly pdfBytes: Uint8Array; readonly pageCount: number };
+
+const POINTS_PER_MM = 72 / 25.4;
+const PAGE_SIZE_POINTS = {
+  A4: { width: 595.28, height: 841.89 },
+  Letter: { width: 612, height: 792 },
+} as const;
+const DEFAULT_MARGIN_MM = { top: 18, right: 15, bottom: 18, left: 15 } as const;
+
+const TITLE_SIZE = 16;
+const SUBTITLE_SIZE = 11;
+const BODY_SIZE = 9;
+const FOOTER_SIZE = 8;
+const LINE_HEIGHT_FACTOR = 1.3;
+const CELL_PADDING_X = 4;
+const CELL_PADDING_Y = 3;
+const FOOTER_RESERVE = 16;
+const META_LABEL_GAP = 10;
+const BLOCK_GAP = 10;
+const REPLACEMENT_CHAR = "?";
+const ELLIPSIS = "...";
+
+const TEXT_COLOR = rgb(0.1, 0.1, 0.1);
+const MUTED_COLOR = rgb(0.4, 0.4, 0.4);
+const HEADER_FILL = rgb(0.92, 0.93, 0.95);
+const RULE_COLOR = rgb(0.8, 0.8, 0.82);
+
+type Fonts = { readonly regular: PDFFont; readonly bold: PDFFont };
+
+function lineHeightFor(size: number): number {
+  return size * LINE_HEIGHT_FACTOR;
+}
+
+function createEncodableText(font: PDFFont): (text: string) => string {
+  const supported = new Set(font.getCharacterSet());
+  return (text) => {
+    let result = "";
+    for (const char of text.replace(/\t/g, " ")) {
+      const codePoint = char.codePointAt(0) ?? 0;
+      result += codePoint === 0x0a || supported.has(codePoint) ? char : REPLACEMENT_CHAR;
+    }
+    return result;
+  };
+}
+
+function breakLongWord(word: string, font: PDFFont, size: number, maxWidth: number): string[] {
+  const pieces: string[] = [];
+  let current = "";
+  for (const char of word) {
+    if (current !== "" && font.widthOfTextAtSize(current + char, size) > maxWidth) {
+      pieces.push(current);
+      current = char;
+    } else {
+      current += char;
+    }
+  }
+  if (current !== "") pieces.push(current);
+  return pieces;
+}
+
+function wrapText(text: string, font: PDFFont, size: number, maxWidth: number): string[] {
+  const lines: string[] = [];
+  for (const paragraph of text.split(/\r\n|\n|\r/)) {
+    let current = "";
+    for (const word of paragraph.split(" ").filter((w) => w !== "")) {
+      const candidate = current === "" ? word : `${current} ${word}`;
+      if (font.widthOfTextAtSize(candidate, size) <= maxWidth) {
+        current = candidate;
+        continue;
+      }
+      if (current !== "") lines.push(current);
+      const pieces =
+        font.widthOfTextAtSize(word, size) <= maxWidth
+          ? [word]
+          : breakLongWord(word, font, size, maxWidth);
+      lines.push(...pieces.slice(0, -1));
+      current = pieces[pieces.length - 1] ?? "";
+    }
+    lines.push(current);
+  }
+  return lines;
+}
+
+function fitSingleLine(text: string, font: PDFFont, size: number, maxWidth: number): string {
+  if (font.widthOfTextAtSize(text, size) <= maxWidth) return text;
+  let fitted = text;
+  while (fitted !== "" && font.widthOfTextAtSize(fitted + ELLIPSIS, size) > maxWidth) {
+    fitted = fitted.slice(0, -1);
+  }
+  return fitted + ELLIPSIS;
+}
+
+function resolveColumnWidths(columns: readonly PdfTableColumn[], totalWidth: number): number[] {
+  const totalWeight = columns.reduce((sum, column) => sum + (column.weight ?? 1), 0);
+  return columns.map((column) => (totalWidth * (column.weight ?? 1)) / totalWeight);
+}
+
+function assertRowShape(doc: PdfTableDocument): void {
+  doc.rows.forEach((row, index) => {
+    if (row.length !== doc.columns.length) {
+      throw new RendererError(
+        `row ${index} has ${row.length} cells but the table has ${doc.columns.length} columns`,
+        "invalid_payload",
+      );
+    }
+  });
+}
+
+export async function renderTablePdf(
+  doc: PdfTableDocument,
+  options?: PdfTableOptions,
+): Promise<PdfTableResult> {
+  if (doc.columns.length === 0) {
+    throw new RendererError("table needs at least one column", "invalid_payload");
+  }
+  assertRowShape(doc);
+
+  const pdf = await PDFDocument.create({ updateMetadata: false });
+  const fonts: Fonts = {
+    regular: await pdf.embedFont(StandardFonts.Helvetica),
+    bold: await pdf.embedFont(StandardFonts.HelveticaBold),
+  };
+  const clean = createEncodableText(fonts.regular);
+
+  const pageSize = PAGE_SIZE_POINTS[options?.format ?? "A4"];
+  const margin = {
+    top: (options?.marginMm?.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
+    right: (options?.marginMm?.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
+    bottom: (options?.marginMm?.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
+    left: (options?.marginMm?.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
+  };
+  const contentWidth = pageSize.width - margin.left - margin.right;
+  const contentBottom = margin.bottom + FOOTER_RESERVE;
+  const columnWidths = resolveColumnWidths(doc.columns, contentWidth);
+  const bodyLineHeight = lineHeightFor(BODY_SIZE);
+
+  const rowSpaceOnEmptyPage = pageSize.height - margin.top - contentBottom;
+  if (rowSpaceOnEmptyPage < 4 * bodyLineHeight) {
+    throw new RendererError("margins leave no room for table rows", "invalid_payload");
+  }
+
+  const headerLines = doc.columns.map((column, index) =>
+    wrapText(
+      clean(column.header),
+      fonts.bold,
+      BODY_SIZE,
+      (columnWidths[index] ?? contentWidth) - 2 * CELL_PADDING_X,
+    ),
+  );
+  const headerHeight =
+    Math.max(...headerLines.map((lines) => lines.length)) * bodyLineHeight + 2 * CELL_PADDING_Y;
+
+  let page: PDFPage = pdf.addPage([pageSize.width, pageSize.height]);
+  let cursorY = pageSize.height - margin.top;
+
+  function drawLines(
+    lines: readonly string[],
+    font: PDFFont,
+    size: number,
+    left: number,
+    width: number,
+    topY: number,
+    align: "left" | "right",
+    color = TEXT_COLOR,
+  ): void {
+    lines.forEach((line, index) => {
+      const lineWidth = font.widthOfTextAtSize(line, size);
+      const x = align === "right" ? left + width - lineWidth : left;
+      page.drawText(line, {
+        x,
+        y: topY - size - index * lineHeightFor(size),
+        size,
+        font,
+        color,
+      });
+    });
+  }
+
+  function drawIntroBlock(): void {
+    const titleLines = wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth);
+    drawLines(titleLines, fonts.bold, TITLE_SIZE, margin.left, contentWidth, cursorY, "left");
+    cursorY -= titleLines.length * lineHeightFor(TITLE_SIZE);
+
+    if (doc.subtitle !== undefined) {
+      const subtitleLines = wrapText(
+        clean(doc.subtitle),
+        fonts.regular,
+        SUBTITLE_SIZE,
+        contentWidth,
+      );
+      drawLines(
+        subtitleLines,
+        fonts.regular,
+        SUBTITLE_SIZE,
+        margin.left,
+        contentWidth,
+        cursorY,
+        "left",
+        MUTED_COLOR,
+      );
+      cursorY -= subtitleLines.length * lineHeightFor(SUBTITLE_SIZE);
+    }
+
+    const meta = doc.meta ?? [];
+    if (meta.length > 0) {
+      cursorY -= BLOCK_GAP / 2;
+      const labels = meta.map((entry) => clean(entry.label));
+      const labelWidth =
+        Math.max(...labels.map((label) => fonts.bold.widthOfTextAtSize(label, BODY_SIZE))) +
+        META_LABEL_GAP;
+      meta.forEach((entry, index) => {
+        const valueLines = wrapText(
+          clean(entry.value),
+          fonts.regular,
+          BODY_SIZE,
+          contentWidth - labelWidth,
+        );
+        drawLines(
+          [labels[index] ?? ""],
+          fonts.bold,
+          BODY_SIZE,
+          margin.left,
+          labelWidth,
+          cursorY,
+          "left",
+        );
+        drawLines(
+          valueLines,
+          fonts.regular,
+          BODY_SIZE,
+          margin.left + labelWidth,
+          contentWidth - labelWidth,
+          cursorY,
+          "left",
+        );
+        cursorY -= valueLines.length * bodyLineHeight;
+      });
+    }
+    cursorY -= BLOCK_GAP;
+  }
+
+  function drawTableHeader(): void {
+    page.drawRectangle({
+      x: margin.left,
+      y: cursorY - headerHeight,
+      width: contentWidth,
+      height: headerHeight,
+      color: HEADER_FILL,
+    });
+    let x = margin.left;
+    doc.columns.forEach((column, index) => {
+      const width = columnWidths[index] ?? 0;
+      drawLines(
+        headerLines[index] ?? [],
+        fonts.bold,
+        BODY_SIZE,
+        x + CELL_PADDING_X,
+        width - 2 * CELL_PADDING_X,
+        cursorY - CELL_PADDING_Y,
+        column.align ?? "left",
+      );
+      x += width;
+    });
+    cursorY -= headerHeight;
+  }
+
+  function startContinuationPage(): void {
+    page = pdf.addPage([pageSize.width, pageSize.height]);
+    cursorY = pageSize.height - margin.top;
+    drawTableHeader();
+  }
+
+  function drawRowSlice(
+    cellLines: readonly (readonly string[])[],
+    from: number,
+    count: number,
+  ): void {
+    const height = count * bodyLineHeight + 2 * CELL_PADDING_Y;
+    let x = margin.left;
+    doc.columns.forEach((column, index) => {
+      const width = columnWidths[index] ?? 0;
+      drawLines(
+        (cellLines[index] ?? []).slice(from, from + count),
+        fonts.regular,
+        BODY_SIZE,
+        x + CELL_PADDING_X,
+        width - 2 * CELL_PADDING_X,
+        cursorY - CELL_PADDING_Y,
+        column.align ?? "left",
+      );
+      x += width;
+    });
+    page.drawLine({
+      start: { x: margin.left, y: cursorY - height },
+      end: { x: margin.left + contentWidth, y: cursorY - height },
+      thickness: 0.5,
+      color: RULE_COLOR,
+    });
+    cursorY -= height;
+  }
+
+  function drawRow(cellLines: readonly (readonly string[])[]): void {
+    const lineCount = Math.max(...cellLines.map((lines) => lines.length));
+    const rowHeight = lineCount * bodyLineHeight + 2 * CELL_PADDING_Y;
+    const emptyPageSpace = pageSize.height - margin.top - headerHeight - contentBottom;
+
+    if (rowHeight > cursorY - contentBottom && rowHeight <= emptyPageSpace) {
+      startContinuationPage();
+    }
+    let drawn = 0;
+    while (drawn < lineCount) {
+      const fitting = Math.floor((cursorY - contentBottom - 2 * CELL_PADDING_Y) / bodyLineHeight);
+      if (fitting < 1) {
+        startContinuationPage();
+        continue;
+      }
+      const count = Math.min(fitting, lineCount - drawn);
+      drawRowSlice(cellLines, drawn, count);
+      drawn += count;
+    }
+  }
+
+  drawIntroBlock();
+  drawTableHeader();
+
+  if (doc.rows.length === 0 && doc.emptyText !== undefined) {
+    drawRow([
+      wrapText(clean(doc.emptyText), fonts.regular, BODY_SIZE, contentWidth - 2 * CELL_PADDING_X),
+    ]);
+  }
+  for (const row of doc.rows) {
+    drawRow(
+      row.map((cell, index) =>
+        wrapText(
+          clean(cell),
+          fonts.regular,
+          BODY_SIZE,
+          (columnWidths[index] ?? contentWidth) - 2 * CELL_PADDING_X,
+        ),
+      ),
+    );
+  }
+
+  const pages = pdf.getPages();
+  const pageLabelTemplate = doc.pageLabel ?? "{page} / {pages}";
+  const footerBaseline = margin.bottom;
+  pages.forEach((footerPage, index) => {
+    const label = clean(
+      pageLabelTemplate
+        .replaceAll("{page}", String(index + 1))
+        .replaceAll("{pages}", String(pages.length)),
+    );
+    const labelWidth = fonts.regular.widthOfTextAtSize(label, FOOTER_SIZE);
+    if (doc.footerText !== undefined) {
+      footerPage.drawText(
+        fitSingleLine(
+          clean(doc.footerText.replace(/\s+/g, " ")),
+          fonts.regular,
+          FOOTER_SIZE,
+          contentWidth - labelWidth - 2 * CELL_PADDING_X,
+        ),
+        {
+          x: margin.left,
+          y: footerBaseline,
+          size: FOOTER_SIZE,
+          font: fonts.regular,
+          color: MUTED_COLOR,
+        },
+      );
+    }
+    footerPage.drawText(label, {
+      x: margin.left + contentWidth - labelWidth,
+      y: footerBaseline,
+      size: FOOTER_SIZE,
+      font: fonts.regular,
+      color: MUTED_COLOR,
+    });
+  });
+
+  const pdfBytes = await pdf.save();
+  return { pdfBytes, pageCount: pages.length };
+}

package/packages/bundled-features/src/user-profile/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.360.0",
+    "type": "improvement",
+    "title": "change-email can be switched off",
+    "detail": "createUserProfileFeature({ allowEmailChange: false }) neither registers the change-email write handler nor shows the email section on the profile screen. Without the option nothing changes."
+  },
   {
     "version": "0.243.1",
     "type": "fix",

package/packages/bundled-features/src/user-profile/feature.ts

@@ -12,13 +12,21 @@ import {
 } from "./constants.js";
 import { changeEmailWrite } from "./handlers/change-email.write.js";
 
-export function createUserProfileFeature(): FeatureDefinition {
+export type UserProfileFeatureOptions = {
+  /** Default true. false drops the change-email handler and the email
+   *  section — for apps whose login email is managed elsewhere (SSO, admin-set). */
+  readonly allowEmailChange?: boolean;
+};
+
+export function createUserProfileFeature(options?: UserProfileFeatureOptions): FeatureDefinition {
+  const allowEmailChange = options?.allowEmailChange ?? true;
   return defineFeature("user-profile", (r) => {
     r.describe(
       "Self-service account page (fw#2312: declarative `projectionDetail` bound to " +
         "the signed-in user's own `me` row) plus its `change-email` write handler " +
         "(re-auth via current password, uniqueness check, resets emailVerified and " +
-        "expects the app to trigger the verification flow). Change-password and " +
+        "expects the app to trigger the verification flow; opt out with " +
+        "`allowEmailChange: false`, which drops handler and section). Change-password and " +
         "change-email stay custom `EditExtensionSection` components (re-auth flows a " +
         "declarative action can't express); account deletion (user-data-rights " +
         "request/cancel with grace period) is declarative fields + actions. Apps " +
@@ -38,9 +46,7 @@ export function createUserProfileFeature(): FeatureDefinition {
     r.requires("user-data-rights");
     r.requires("user-data-rights-defaults");
 
-    const handlers = {
-      changeEmail: r.writeHandler(changeEmailWrite),
-    };
+    const handlers = allowEmailChange ? { changeEmail: r.writeHandler(changeEmailWrite) } : {};
 
     // Boot-validator requires a "screen:<id>.title" key per r.screen(), plus
     // one entry per i18nKey()-marked dot-form label below — kept inline (not
@@ -100,12 +106,16 @@ export function createUserProfileFeature(): FeatureDefinition {
       },
       layout: {
         sections: [
-          {
-            kind: "extension",
-            title: i18nKey("profile.email.title"),
-            component: { react: { __component: CHANGE_EMAIL_SECTION_EXTENSION_NAME } },
-            entityName: "user",
-          },
+          ...(allowEmailChange
+            ? [
+                {
+                  kind: "extension" as const,
+                  title: i18nKey("profile.email.title"),
+                  component: { react: { __component: CHANGE_EMAIL_SECTION_EXTENSION_NAME } },
+                  entityName: "user",
+                },
+              ]
+            : []),
           {
             kind: "extension",
             title: i18nKey("profile.password.title"),

package/packages/bundled-features/src/user-profile/index.ts

@@ -8,4 +8,4 @@ export {
   UserProfileHandlers,
   UserProfileQueries,
 } from "./constants.js";
-export { createUserProfileFeature } from "./feature.js";
+export { createUserProfileFeature, type UserProfileFeatureOptions } from "./feature.js";

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -1,6 +1,6 @@
 {
   "source": "samples/apps/use-all-bundled APP_FEATURES (composeFeatures includeBundled + signup)",
-  "featureCount": 81,
+  "featureCount": 82,
   "features": [
     {
       "name": "admin-shell",
@@ -2072,6 +2072,32 @@
         "recommended": false
       }
     },
+    {
+      "name": "renderer-pdf",
+      "description": "Renderer plugin for `kind=\"document-pdf\"` that draws a table document (title, meta lines, weighted columns, repeating header, page footer) as a PDF in pure JavaScript, without a browser or Puppeteer service. `payload.variables` must be a `PdfTableDocument`. Requires `renderer-foundation`; mount a Puppeteer-based plugin instead when you need HTML/CSS layouts.",
+      "toggleableDefault": null,
+      "requires": [
+        "renderer-foundation"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "renderer",
+          "entityName": "pdf"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Renderer · PDF tables",
+        "category": "notifications",
+        "recommended": false
+      }
+    },
     {
       "name": "renderer-simple",
       "description": "Default renderer plugin for `kind=\"notification\"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails — swap it for `renderer-mail-html` if you need MJML/Markdown layouts.",
@@ -3054,7 +3080,7 @@
     },
     {
       "name": "user-profile",
-      "description": "Self-service account page (fw#2312: declarative `projectionDetail` bound to the signed-in user's own `me` row) plus its `change-email` write handler (re-auth via current password, uniqueness check, resets emailVerified and expects the app to trigger the verification flow). Change-password and change-email stay custom `EditExtensionSection` components (re-auth flows a declarative action can't express); account deletion (user-data-rights request/cancel with grace period) is declarative fields + actions. Apps place the screen (id \"profile\") in their logged-in area via r.nav — no `type: \"custom\"` / `__component` registration needed on the app side anymore. Requires `user`, `auth-email-password`, `user-data-rights`, and `user-data-rights-defaults` (so the GDPR boot-validator finds export/delete hooks for `user`'s PII fields once user-data-rights is mounted).",
+      "description": "Self-service account page (fw#2312: declarative `projectionDetail` bound to the signed-in user's own `me` row) plus its `change-email` write handler (re-auth via current password, uniqueness check, resets emailVerified and expects the app to trigger the verification flow; opt out with `allowEmailChange: false`, which drops handler and section). Change-password and change-email stay custom `EditExtensionSection` components (re-auth flows a declarative action can't express); account deletion (user-data-rights request/cancel with grace period) is declarative fields + actions. Apps place the screen (id \"profile\") in their logged-in area via r.nav — no `type: \"custom\"` / `__component` registration needed on the app side anymore. Requires `user`, `auth-email-password`, `user-data-rights`, and `user-data-rights-defaults` (so the GDPR boot-validator finds export/delete hooks for `user`'s PII fields once user-data-rights is mounted).",
       "toggleableDefault": null,
       "requires": [
         "user",

package/samples/apps/use-all-bundled/schema/generate.ts

@@ -322,6 +322,11 @@ const FEATURE_IMPORT_REGISTRY: Record<string, FeatureImport> = {
     path: "@cosmicdrift/kumiko-bundled-features/renderer-simple",
     factory: "createRendererSimpleFeature",
   },
+  "renderer-pdf": {
+    kind: "factory",
+    path: "@cosmicdrift/kumiko-bundled-features/renderer-pdf",
+    factory: "createRendererPdfFeature",
+  },
   "rate-limiting": {
     kind: "factory",
     path: "@cosmicdrift/kumiko-bundled-features/rate-limiting",

package/samples/apps/use-all-bundled/src/run-config.ts

@@ -76,6 +76,7 @@ import { createPersonalAccessTokensFeature } from "@cosmicdrift/kumiko-bundled-f
 import { securityBaselineFeatures } from "@cosmicdrift/kumiko-bundled-features/presets";
 import { readinessFeature } from "@cosmicdrift/kumiko-bundled-features/readiness";
 import { createRendererFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-foundation";
+import { createRendererPdfFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
 import { createRendererSimpleFeature } from "@cosmicdrift/kumiko-bundled-features/renderer-simple";
 import { createSecretsFeature } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { createSeoFeature } from "@cosmicdrift/kumiko-bundled-features/seo";
@@ -336,6 +337,7 @@ export const APP_FEATURES = [
   collectionLabelsFeature,
   createRendererFoundationFeature(),
   createRendererSimpleFeature(),
+  createRendererPdfFeature(),
 
   // managed-pages: requires config (auto-bundled). Smoke resolver never serves
   // (boot-only). allowCustomCss:true boot-validates the CSS code path + emits

package/samples/recipes/pdf-audit-export/README.md

@@ -0,0 +1,22 @@
+# PDF Audit Export
+
+A write handler exports tenant data as a PDF and keeps it as a FileRef.
+
+## What it shows
+
+- `renderTablePdf` (`@cosmicdrift/kumiko-bundled-features/renderer-pdf`) draws a table document in pure JavaScript: repeating header, weighted columns, page footer. The handler passes ready-formatted strings.
+- `createFileRefFromBytes` (`@cosmicdrift/kumiko-framework/files`) stores the bytes like an upload (validation, tenant-prefixed storage key, `fileRef.created` event); the tenant comes from the caller.
+- The result is a normal FileRef: `GET /api/files/:id` serves it with `Content-Type: application/pdf`, other tenants get 404.
+
+## Source
+
+Feature entry point: `src/feature.ts`. The export reads at most 200 inspections per call.
+
+## Tests
+
+Needs a running Postgres and `TEST_DATABASE_URL` set (e.g. `postgres://postgres:postgres@127.0.0.1:5432/postgres`, see `demo/.env.example`).
+
+```bash
+cd samples/recipes/pdf-audit-export
+bun test
+```

package/samples/recipes/pdf-audit-export/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@cosmicdrift/kumiko-sample-pdf-audit-export",
+  "description": "Exports an audit table as a PDF: a write handler renders rows with renderTablePdf and stores the bytes as a FileRef via createFileRefFromBytes.",
+  "private": true,
+  "dependencies": {
+    "@cosmicdrift/kumiko-bundled-features": "workspace:*",
+    "@cosmicdrift/kumiko-framework": "workspace:*"
+  },
+  "devDependencies": {
+    "unpdf": "^1.8.1"
+  }
+}

package/samples/recipes/pdf-audit-export/src/feature.ts

@@ -0,0 +1,114 @@
+// PDF Audit Export Sample
+//
+// A write handler turns tenant data into a PDF and keeps it as a regular
+// FileRef: renderTablePdf draws the table (pure JS, no browser), then
+// createFileRefFromBytes stores the bytes through the same validation,
+// storage layout and fileRef.created event as an upload.
+
+import { renderTablePdf } from "@cosmicdrift/kumiko-bundled-features/renderer-pdf";
+import {
+  createDateField,
+  createEntity,
+  createEntityExecutor,
+  createSelectField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createFileRefFromBytes } from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+
+export const INSPECTION_RESULTS = ["ok", "defect"] as const;
+
+export const inspectionEntity = createEntity({
+  table: "read_sample_inspections",
+  fields: {
+    assetName: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    inspectedOn: createDateField({ required: true }),
+    result: createSelectField({ options: INSPECTION_RESULTS, required: true }),
+    inspector: createTextField({ personal: "ref" }),
+  },
+});
+
+const RESULT_LABELS: Readonly<Record<(typeof INSPECTION_RESULTS)[number], string>> = {
+  ok: "In Ordnung",
+  defect: "Mangel",
+};
+
+// The renderer takes ready-formatted strings, so date formatting stays with the caller.
+function formatGermanDate(isoDate: string): string {
+  const [year, month, day] = isoDate.split("-");
+  return `${day}.${month}.${year}`;
+}
+
+function toFileNameSegment(text: string): string {
+  return text.replaceAll(/[^A-Za-z0-9_-]+/g, "-");
+}
+
+const AUDIT_ROW_LIMIT = 200;
+
+const access = { access: { roles: ["Admin", "User"] } } as const;
+
+export const pdfAuditExportFeature = defineFeature("pdf-audit-export", (r) => {
+  r.entity("inspection", inspectionEntity);
+  const { executor: inspectionExecutor } = createEntityExecutor("inspection", inspectionEntity);
+
+  r.writeHandler(
+    "inspection:create",
+    z.object({
+      assetName: z.string().min(1),
+      inspectedOn: z.iso.date(),
+      result: z.enum(INSPECTION_RESULTS),
+      inspector: z.string().optional(),
+    }),
+    async (event, ctx) => inspectionExecutor.create(event.payload, event.user, ctx.db),
+    access,
+  );
+
+  r.writeHandler(
+    "export-audit",
+    z.object({ assetName: z.string().min(1), from: z.iso.date(), to: z.iso.date() }),
+    async (event, ctx) => {
+      const { assetName, from, to } = event.payload;
+      const inspections = await inspectionExecutor.list(
+        {
+          filters: [
+            { field: "assetName", op: "eq", value: assetName },
+            { field: "inspectedOn", op: "gte", value: from },
+            { field: "inspectedOn", op: "lte", value: to },
+          ],
+          sort: "inspectedOn",
+          sortDirection: "asc",
+          limit: AUDIT_ROW_LIMIT,
+        },
+        event.user,
+        ctx.db,
+      );
+
+      const { pdfBytes } = await renderTablePdf({
+        title: `Prüfprotokoll ${assetName}`,
+        meta: [
+          { label: "Zeitraum", value: `${formatGermanDate(from)} bis ${formatGermanDate(to)}` },
+          { label: "Prüfungen", value: String(inspections.rows.length) },
+        ],
+        columns: [{ header: "Datum" }, { header: "Ergebnis" }, { header: "Prüfer", weight: 2 }],
+        rows: inspections.rows.map((row) => [
+          formatGermanDate(String(row["inspectedOn"])),
+          RESULT_LABELS[z.enum(INSPECTION_RESULTS).parse(row["result"])],
+          String(row["inspector"] ?? ""),
+        ]),
+        emptyText: "Keine Prüfungen im Zeitraum",
+        footerText: `Prüfbericht ${assetName}`,
+        pageLabel: "Seite {page} von {pages}",
+      });
+
+      const created = await createFileRefFromBytes(ctx, {
+        fileName: `audit-${toFileNameSegment(assetName)}.pdf`,
+        mimeType: "application/pdf",
+        data: pdfBytes,
+      });
+      if (!created.isSuccess) return created;
+      return { isSuccess: true as const, data: { fileRefId: created.data.id } };
+    },
+    access,
+  );
+});