@cosmicdrift/kumiko-samples 0.362.0 → 0.364.0

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,103 @@
-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;
+      fromName?: string;
+      replyTo?: 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 +108,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 +168,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/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "renderTablePdf rejects tables above 10000 rows, 30 columns or 5000 characters per cell",
+    "detail": "The table document schema now caps rows at 10000, columns at 30 and each cell string at 5000 characters. Larger input fails with invalid_payload instead of exhausting memory during layout."
+  },
+  {
+    "version": "0.364.0",
+    "type": "fix",
+    "title": "render-table-pdf validates input and paginates its intro",
+    "detail": "Table documents reject negative margins and unusable column widths, normalize CRLF and paginate the intro text and the first header row."
+  },
   {
     "version": "0.360.0",
     "type": "improvement",

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/renderer-pdf/render-table-pdf.ts

@@ -1,52 +1,56 @@
 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;
-};
+import type { PdfPageFormat } from "../template-resolver/index.js";
+
+// Upper bounds keep a hostile or runaway payload from exhausting memory and CPU in layout.
+const PDF_TABLE_MAX_ROWS = 10_000;
+const PDF_TABLE_MAX_COLUMNS = 30;
+const PDF_TABLE_MAX_CELL_LENGTH = 5_000;
+
+const pdfTableColumnSchema = z
+  .object({
+    header: z.string(),
+    weight: z.number().positive().optional(),
+    align: z.enum(["left", "right"]).optional(),
+  })
+  .readonly();
+
+export const pdfTableDocumentSchema = z
+  .object({
+    title: z.string(),
+    subtitle: z.string().optional(),
+    meta: z
+      .array(z.object({ label: z.string(), value: z.string() }).readonly())
+      .readonly()
+      .optional(),
+    columns: z.array(pdfTableColumnSchema).min(1).max(PDF_TABLE_MAX_COLUMNS).readonly(),
+    rows: z
+      .array(z.array(z.string().max(PDF_TABLE_MAX_CELL_LENGTH)).readonly())
+      .max(PDF_TABLE_MAX_ROWS)
+      .readonly(),
+    emptyText: z.string().optional(),
+    footerText: z.string().optional(),
+    // Template with `{page}` and `{pages}`; default `"{page} / {pages}"`.
+    pageLabel: z.string().optional(),
+  })
+  .readonly();
+
+export type PdfTableColumn = z.infer<typeof pdfTableColumnSchema>;
+export type PdfTableDocument = z.infer<typeof pdfTableDocumentSchema>;
+
+const marginMmSchema = z
+  .object({
+    top: z.number().nonnegative().optional(),
+    right: z.number().nonnegative().optional(),
+    bottom: z.number().nonnegative().optional(),
+    left: z.number().nonnegative().optional(),
+  })
+  .readonly();
 
 export type PdfTableOptions = {
-  readonly format?: "A4" | "Letter";
-  readonly marginMm?: {
-    readonly top?: number;
-    readonly right?: number;
-    readonly bottom?: number;
-    readonly left?: number;
-  };
+  readonly format?: PdfPageFormat;
+  readonly marginMm?: z.input<typeof marginMmSchema>;
 };
 
 export type PdfTableResult = { readonly pdfBytes: Uint8Array; readonly pageCount: number };
@@ -55,7 +59,7 @@ 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;
+} as const satisfies Record<PdfPageFormat, { readonly width: number; readonly height: number }>;
 const DEFAULT_MARGIN_MM = { top: 18, right: 15, bottom: 18, left: 15 } as const;
 
 const TITLE_SIZE = 16;
@@ -66,6 +70,7 @@ const LINE_HEIGHT_FACTOR = 1.3;
 const CELL_PADDING_X = 4;
 const CELL_PADDING_Y = 3;
 const FOOTER_RESERVE = 16;
+const MIN_COLUMN_WIDTH = 20;
 const META_LABEL_GAP = 10;
 const BLOCK_GAP = 10;
 const REPLACEMENT_CHAR = "?";
@@ -86,7 +91,7 @@ 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, " ")) {
+    for (const char of text.replace(/\r\n?/g, "\n").replace(/\t/g, " ")) {
       const codePoint = char.codePointAt(0) ?? 0;
       result += codePoint === 0x0a || supported.has(codePoint) ? char : REPLACEMENT_CHAR;
     }
@@ -157,30 +162,43 @@ function assertRowShape(doc: PdfTableDocument): void {
   });
 }
 
-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),
+type TableLayout = {
+  readonly pageSize: { readonly width: number; readonly height: number };
+  readonly margin: {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
   };
-  const clean = createEncodableText(fonts.regular);
+  readonly contentWidth: number;
+  readonly contentBottom: number;
+  readonly columnWidths: readonly number[];
+  readonly bodyLineHeight: number;
+  readonly headerLines: readonly (readonly string[])[];
+  readonly headerHeight: number;
+};
 
+function resolveTableLayout(
+  doc: PdfTableDocument,
+  options: PdfTableOptions | undefined,
+  fonts: Fonts,
+  clean: (text: string) => string,
+): TableLayout {
+  const marginMm = marginMmSchema.safeParse(options?.marginMm ?? {});
+  if (!marginMm.success) {
+    throw new RendererError("margins must be non-negative numbers", "invalid_payload");
+  }
   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,
+    top: (marginMm.data.top ?? DEFAULT_MARGIN_MM.top) * POINTS_PER_MM,
+    right: (marginMm.data.right ?? DEFAULT_MARGIN_MM.right) * POINTS_PER_MM,
+    bottom: (marginMm.data.bottom ?? DEFAULT_MARGIN_MM.bottom) * POINTS_PER_MM,
+    left: (marginMm.data.left ?? DEFAULT_MARGIN_MM.left) * POINTS_PER_MM,
   };
   const contentWidth = pageSize.width - margin.left - margin.right;
+  if (contentWidth < MIN_COLUMN_WIDTH * doc.columns.length) {
+    throw new RendererError("margins leave no room for table columns", "invalid_payload");
+  }
   const contentBottom = margin.bottom + FOOTER_RESERVE;
   const columnWidths = resolveColumnWidths(doc.columns, contentWidth);
   const bodyLineHeight = lineHeightFor(BODY_SIZE);
@@ -200,6 +218,48 @@ export async function renderTablePdf(
   );
   const headerHeight =
     Math.max(...headerLines.map((lines) => lines.length)) * bodyLineHeight + 2 * CELL_PADDING_Y;
+  // A header this tall would leave every continuation page without room for a row.
+  if (rowSpaceOnEmptyPage - headerHeight < bodyLineHeight + 2 * CELL_PADDING_Y) {
+    throw new RendererError("table header leaves no room for rows", "invalid_payload");
+  }
+  return {
+    pageSize,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  };
+}
+
+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,
+    margin,
+    contentWidth,
+    contentBottom,
+    columnWidths,
+    bodyLineHeight,
+    headerLines,
+    headerHeight,
+  } = resolveTableLayout(doc, options, fonts, clean);
 
   let page: PDFPage = pdf.addPage([pageSize.width, pageSize.height]);
   let cursorY = pageSize.height - margin.top;
@@ -227,29 +287,50 @@ export async function renderTablePdf(
     });
   }
 
+  function startBlankPage(): void {
+    page = pdf.addPage([pageSize.width, pageSize.height]);
+    cursorY = pageSize.height - margin.top;
+  }
+
+  function ensureRoom(height: number): void {
+    if (cursorY - height < contentBottom) startBlankPage();
+  }
+
+  // Line by line, so a block taller than one page continues on the next.
+  function flowLines(
+    lines: readonly string[],
+    font: PDFFont,
+    size: number,
+    left: number,
+    width: number,
+    color = TEXT_COLOR,
+  ): void {
+    const lineHeight = lineHeightFor(size);
+    for (const line of lines) {
+      ensureRoom(lineHeight);
+      drawLines([line], font, size, left, width, cursorY, "left", color);
+      cursorY -= lineHeight;
+    }
+  }
+
   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);
+    flowLines(
+      wrapText(clean(doc.title), fonts.bold, TITLE_SIZE, contentWidth),
+      fonts.bold,
+      TITLE_SIZE,
+      margin.left,
+      contentWidth,
+    );
 
     if (doc.subtitle !== undefined) {
-      const subtitleLines = wrapText(
-        clean(doc.subtitle),
-        fonts.regular,
-        SUBTITLE_SIZE,
-        contentWidth,
-      );
-      drawLines(
-        subtitleLines,
+      flowLines(
+        wrapText(clean(doc.subtitle), fonts.regular, SUBTITLE_SIZE, contentWidth),
         fonts.regular,
         SUBTITLE_SIZE,
         margin.left,
         contentWidth,
-        cursorY,
-        "left",
         MUTED_COLOR,
       );
-      cursorY -= subtitleLines.length * lineHeightFor(SUBTITLE_SIZE);
     }
 
     const meta = doc.meta ?? [];
@@ -266,6 +347,7 @@ export async function renderTablePdf(
           BODY_SIZE,
           contentWidth - labelWidth,
         );
+        ensureRoom(bodyLineHeight);
         drawLines(
           [labels[index] ?? ""],
           fonts.bold,
@@ -275,16 +357,13 @@ export async function renderTablePdf(
           cursorY,
           "left",
         );
-        drawLines(
+        flowLines(
           valueLines,
           fonts.regular,
           BODY_SIZE,
           margin.left + labelWidth,
           contentWidth - labelWidth,
-          cursorY,
-          "left",
         );
-        cursorY -= valueLines.length * bodyLineHeight;
       });
     }
     cursorY -= BLOCK_GAP;
@@ -372,6 +451,7 @@ export async function renderTablePdf(
   }
 
   drawIntroBlock();
+  ensureRoom(headerHeight + bodyLineHeight + 2 * CELL_PADDING_Y);
   drawTableHeader();
 
   if (doc.rows.length === 0 && doc.emptyText !== undefined) {

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.364.0",
+    "type": "improvement",
+    "title": "SecretsContext.withRunner(tx) runs secret access on a given transaction",
+    "detail": "The OAuth refresh now reads and writes the refresh token on its advisory-lock transaction, so a refresh holds one pool connection instead of two and parallel refreshes cannot starve the pool. Custom SecretsContext implementations need a `withRunner` method."
+  },
   {
     "version": "0.343.0",
     "type": "improvement",