@signiphi/pdf-compose 0.1.0-beta.6 → 0.1.0-beta.8

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export type { Acknowledgement, DocumentGeneratorField, DocumentGeneratorVariable
 export { FormFieldType } from './types';
 export { suppressZeroContent, isZeroLike, expandRepeatContent, extractVariablesFromContent } from './utils/variable-helpers';
 export { generatePdfFromMarkdown, generatePdfFromTiptap } from './utils/template-pipeline';
-export type { HeadlessPdfResult } from './utils/template-pipeline';
+export type { HeadlessPdfResult, HeadlessPdfOptions } from './utils/template-pipeline';
+export type { PdfTheme, PdfPageHeader, PdfPageFooter } from './utils/pdf-generator';
 export { markdownToTiptap } from './utils/markdown-parser';
 export { tiptapToMarkdown } from './utils/markdown-writer';
 export { RepeatNode } from './extensions/repeat-node';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,6BAA6B,EAC7B,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAG7H,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGnE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAGzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,6BAA6B,EAC7B,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAG7H,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACvF,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAG1E,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -608,6 +608,11 @@ function replaceVariablesInContent(content, values) {
       }
       return textNode;
     }
+    if (node.type === "imageNode" && node.attrs?.varName) {
+      const varName = node.attrs.varName;
+      const resolved = values[varName] || node.attrs.src || "";
+      return { ...node, attrs: { ...node.attrs, src: resolved } };
+    }
     if (node.content) {
       return { ...node, content: node.content.map(walkNode) };
     }
@@ -736,7 +741,8 @@ function expandRepeatContent(content, values) {
     values: enrichedValues
   };
 }
-var TOKEN_REGEX = /\{\{(field|var)\|([^}]+)\}\}/g;
+var TOKEN_REGEX = /\{\{(field|var|image)\|([^}]+)\}\}/g;
+var BLOCK_IMAGE_REGEX = /^!\[([^\]]*)\]\(([^)\s]+)\)$/;
 var DIRECTIVE_OPEN = /^:::(panel|columns|col|watermark|repeat|subtotals)(?:\{([^}]*)\})?$/;
 var DIRECTIVE_CLOSE = /^:::$/;
 function parseDirectiveAttrs(str) {
@@ -881,6 +887,44 @@ function parseVariableToken(tokenBody) {
   }
   return attrs;
 }
+function parseImageToken(tokenBody) {
+  const attrs = {
+    src: "",
+    varName: "",
+    alt: "",
+    width: "",
+    height: "",
+    align: ""
+  };
+  const pairs = tokenBody.split("|");
+  for (const pair of pairs) {
+    const colonIdx = pair.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = pair.slice(0, colonIdx).trim();
+    const value = pair.slice(colonIdx + 1).trim();
+    switch (key) {
+      case "src":
+        attrs.src = value;
+        break;
+      case "var":
+        attrs.varName = value;
+        break;
+      case "alt":
+        attrs.alt = value;
+        break;
+      case "width":
+        attrs.width = value;
+        break;
+      case "height":
+        attrs.height = value;
+        break;
+      case "align":
+        attrs.align = value;
+        break;
+    }
+  }
+  return attrs;
+}
 function parseInline(text) {
   text = preprocessMarkedTokens(text);
   const nodes = [];
@@ -904,6 +948,8 @@ function parseInline(text) {
       const node = { type: "variableNode", attrs };
       if (marks.length > 0) node.marks = marks;
       nodes.push(node);
+    } else if (match[1] === "image") {
+      nodes.push({ type: "imageNode", attrs: parseImageToken(match[2]) });
     }
     lastIndex = match.index + match[0].length;
   }
@@ -1217,10 +1263,24 @@ function parseBlocks(lines, startIdx, stopCondition) {
       i++;
       continue;
     }
-    content.push({
-      type: "paragraph",
-      content: parseInline(line)
-    });
+    const imageMatch = line.trim().match(BLOCK_IMAGE_REGEX);
+    if (imageMatch) {
+      content.push({
+        type: "imageNode",
+        attrs: { src: imageMatch[2], varName: "", alt: imageMatch[1], width: "", height: "", align: "" }
+      });
+      i++;
+      continue;
+    }
+    const inlineNodes = parseInline(line);
+    const nonWhitespace = inlineNodes.filter(
+      (n) => !(n.type === "text" && !(n.text || "").trim())
+    );
+    if (nonWhitespace.length === 1 && nonWhitespace[0].type === "imageNode") {
+      content.push(nonWhitespace[0]);
+    } else {
+      content.push({ type: "paragraph", content: inlineNodes });
+    }
     i++;
   }
   return { blocks: content, nextIdx: i };
@@ -1371,6 +1431,34 @@ var CONTENT_WIDTH = PAGE_WIDTH - 2 * MARGIN;
 var CONTENT_HEIGHT = PAGE_HEIGHT - 2 * MARGIN;
 var LINE_HEIGHT_FACTOR = 1.4;
 var BODY_FONT_SIZE = 10;
+function hexToRgbColor(hex) {
+  if (!hex) return null;
+  const m = hex.trim().match(/^#?([0-9a-fA-F]{6})$/);
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return pdfLib.rgb((n >> 16 & 255) / 255, (n >> 8 & 255) / 255, (n & 255) / 255);
+}
+function contrastTextColor(fill) {
+  const c = fill;
+  const luminance = 0.299 * c.red + 0.587 * c.green + 0.114 * c.blue;
+  return luminance > 0.6 ? pdfLib.rgb(0, 0, 0) : pdfLib.rgb(1, 1, 1);
+}
+function resolveTheme(theme) {
+  const primary = hexToRgbColor(theme?.primaryColor);
+  const accent = hexToRgbColor(theme?.accentColor);
+  const border = hexToRgbColor(theme?.borderColor);
+  return {
+    tableHeaderBg: primary ?? pdfLib.rgb(0.3, 0.3, 0.3),
+    tableHeaderText: primary ? contrastTextColor(primary) : pdfLib.rgb(1, 1, 1),
+    tableBorder: border ?? pdfLib.rgb(0.75, 0.75, 0.75),
+    panelDarkHeaderBg: primary ?? pdfLib.rgb(0.25, 0.25, 0.25),
+    panelDarkHeaderText: primary ? contrastTextColor(primary) : pdfLib.rgb(1, 1, 1),
+    panelBorder: border ?? pdfLib.rgb(0.6, 0.6, 0.6),
+    rule: primary ?? pdfLib.rgb(0, 0, 0),
+    pageHeaderText: primary ?? pdfLib.rgb(0, 0, 0),
+    pageHeaderRule: accent ?? primary ?? pdfLib.rgb(0.75, 0.75, 0.75)
+  };
+}
 var DEFAULT_REGION = { leftX: MARGIN, width: CONTENT_WIDTH };
 var FIELD_DISPLAY = {
   ["text" /* TEXT */]: { label: "Text", width: 120, height: 30 },
@@ -1402,6 +1490,53 @@ function getFieldDimensions(fieldType, attrs, font, fontSize) {
   const height = textLineHeight + 4;
   return { width, height };
 }
+async function loadImageBytes(src) {
+  if (src.startsWith("data:")) {
+    const comma = src.indexOf(",");
+    if (comma === -1) throw new Error("malformed data URL");
+    const meta = src.slice(0, comma);
+    if (!/;base64$/i.test(meta)) throw new Error("data URL must be base64-encoded");
+    const bin = atob(src.slice(comma + 1));
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes;
+  }
+  const res = await fetch(src);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return new Uint8Array(await res.arrayBuffer());
+}
+function describeImageSrc(src) {
+  return src.length > 80 ? `${src.slice(0, 77)}...` : src;
+}
+async function preloadImages(pdfDoc, content) {
+  const srcs = /* @__PURE__ */ new Set();
+  (function walk(node) {
+    if (node.type === "imageNode") {
+      const src = node.attrs?.src || "";
+      if (src) srcs.add(src);
+    }
+    for (const child of node.content || []) walk(child);
+  })(content);
+  const images = /* @__PURE__ */ new Map();
+  const warnings = [];
+  for (const src of srcs) {
+    try {
+      const bytes = await loadImageBytes(src);
+      const isPng = bytes.length > 4 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71;
+      const isJpeg = bytes.length > 2 && bytes[0] === 255 && bytes[1] === 216;
+      if (isPng) {
+        images.set(src, await pdfDoc.embedPng(bytes));
+      } else if (isJpeg) {
+        images.set(src, await pdfDoc.embedJpg(bytes));
+      } else {
+        warnings.push(`Image skipped (unsupported format \u2014 only PNG/JPEG embed): ${describeImageSrc(src)}`);
+      }
+    } catch (err) {
+      warnings.push(`Image skipped (${getErrorMessage(err)}): ${describeImageSrc(src)}`);
+    }
+  }
+  return { images, warnings };
+}
 function ensureSpace(state, neededHeight) {
   if (state.y + neededHeight > CONTENT_HEIGHT) {
     const newPage = state.pdfDoc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
@@ -1749,9 +1884,9 @@ function renderTable(state, node, region = DEFAULT_REGION) {
   const cellPadding = borderless ? 2 : 4;
   const lineHeight = fontSize * LINE_HEIGHT_FACTOR;
   const rowPadding = cellPadding * 2;
-  const borderColor = pdfLib.rgb(0.75, 0.75, 0.75);
-  const headerBg = pdfLib.rgb(0.3, 0.3, 0.3);
-  const headerTextColor = pdfLib.rgb(1, 1, 1);
+  const borderColor = state.theme.tableBorder;
+  const headerBg = state.theme.tableHeaderBg;
+  const headerTextColor = state.theme.tableHeaderText;
   const firstRow = tableRows[0];
   const colCount = firstRow.content?.length || 0;
   if (colCount === 0) return;
@@ -1999,7 +2134,7 @@ function processBlock(state, node, region = DEFAULT_REGION) {
         start: { x: region.leftX, y: ruleY },
         end: { x: region.leftX + region.width, y: ruleY },
         thickness: 2.5,
-        color: pdfLib.rgb(0, 0, 0)
+        color: state.theme.rule
       });
       state.y += 4;
       break;
@@ -2032,6 +2167,39 @@ function processBlock(state, node, region = DEFAULT_REGION) {
       renderTable(state, node, region);
       break;
     }
+    case "imageNode": {
+      const src = node.attrs?.src || "";
+      const image = src ? state.images.get(src) : void 0;
+      if (!image) break;
+      const natW = image.width;
+      const natH = image.height;
+      let w = parseFloat(node.attrs?.width || "") || 0;
+      let h = parseFloat(node.attrs?.height || "") || 0;
+      if (w && !h) h = natH / natW * w;
+      else if (h && !w) w = natW / natH * h;
+      else if (!w && !h) {
+        w = natW;
+        h = natH;
+      }
+      if (w > region.width) {
+        h = h * (region.width / w);
+        w = region.width;
+      }
+      const maxH = CONTENT_HEIGHT * 0.6;
+      if (h > maxH) {
+        w = w * (maxH / h);
+        h = maxH;
+      }
+      ensureSpace(state, h + 4);
+      const align = node.attrs?.align || "left";
+      let x = region.leftX;
+      if (align === "center") x = region.leftX + (region.width - w) / 2;
+      else if (align === "right") x = region.leftX + region.width - w;
+      const pdfY = PAGE_HEIGHT - MARGIN - state.y - h;
+      state.currentPage.drawImage(image, { x, y: pdfY, width: w, height: h });
+      state.y += h + 4;
+      break;
+    }
     // ─── Layout directives ─────────────────────────────────────────
     case "panel": {
       const title = node.attrs?.title || "";
@@ -2068,8 +2236,8 @@ function processBlock(state, node, region = DEFAULT_REGION) {
           y: titleBarY,
           width: region.width,
           height: titleHeight,
-          color: isDarkHeader ? pdfLib.rgb(0.25, 0.25, 0.25) : pdfLib.rgb(0.93, 0.93, 0.93),
-          borderColor: pdfLib.rgb(0.6, 0.6, 0.6),
+          color: isDarkHeader ? state.theme.panelDarkHeaderBg : pdfLib.rgb(0.93, 0.93, 0.93),
+          borderColor: state.theme.panelBorder,
           borderWidth: 0.75
         });
         startPage.drawText(title, {
@@ -2077,7 +2245,7 @@ function processBlock(state, node, region = DEFAULT_REGION) {
           y: titleBarY + 4,
           size: titleFontSize,
           font: state.fonts.bold,
-          color: isDarkHeader ? pdfLib.rgb(1, 1, 1) : pdfLib.rgb(0, 0, 0)
+          color: isDarkHeader ? state.theme.panelDarkHeaderText : pdfLib.rgb(0, 0, 0)
         });
       }
       if (border !== "none") {
@@ -2090,7 +2258,7 @@ function processBlock(state, node, region = DEFAULT_REGION) {
             y: borderY,
             width: region.width,
             height: panelHeight,
-            borderColor: pdfLib.rgb(0.6, 0.6, 0.6),
+            borderColor: state.theme.panelBorder,
             borderWidth: 0.75,
             borderDashArray
           });
@@ -2102,7 +2270,7 @@ function processBlock(state, node, region = DEFAULT_REGION) {
             y: startBorderBottom,
             width: region.width,
             height: startPanelHeight,
-            borderColor: pdfLib.rgb(0.6, 0.6, 0.6),
+            borderColor: state.theme.panelBorder,
             borderWidth: 0.75,
             borderDashArray
           });
@@ -2114,7 +2282,7 @@ function processBlock(state, node, region = DEFAULT_REGION) {
             y: contBorderY,
             width: region.width,
             height: contHeight,
-            borderColor: pdfLib.rgb(0.6, 0.6, 0.6),
+            borderColor: state.theme.panelBorder,
             borderWidth: 0.75,
             borderDashArray
           });
@@ -2418,6 +2586,24 @@ async function addFormFields(pdfDoc, fieldPositions, fields) {
               pdfLib.PDFString.of(field.label)
             );
           }
+          const initialsFontSize = Math.min(
+            72,
+            Math.max(8, Math.round(position.height * 0.55))
+          );
+          try {
+            initialsField.setFontSize(initialsFontSize);
+            const acro = initialsField;
+            const daRef = acro.acroField.dict.get(pdfLib.PDFName.of("DA"));
+            if (daRef) {
+              const daStr = daRef.value;
+              if (typeof daStr === "string") {
+                const newDa = daStr.replace(/\/Helv\b/, "/TiBo").replace(/\/HeBo\b/, "/TiBo");
+                acro.acroField.dict.set(pdfLib.PDFName.of("DA"), pdfLib.PDFString.of(newDa));
+              }
+            }
+          } catch (fontError) {
+            console.warn(`Failed to set initials font:`, fontError);
+          }
           initialsField.enableReadOnly();
           if (field.required) initialsField.enableRequired();
           break;
@@ -2528,7 +2714,8 @@ async function addFormFields(pdfDoc, fieldPositions, fields) {
   return warnings;
 }
 async function generatePdfFromContent(content, options = {}) {
-  const { drawFieldPlaceholders = false, embedFormFields = false, fields = [] } = options;
+  const { drawFieldPlaceholders = false, embedFormFields = false, fields = [], header, footer } = options;
+  const theme = resolveTheme(options.theme);
   const pdfDoc = await pdfLib.PDFDocument.create();
   const firstPage = pdfDoc.addPage([PAGE_WIDTH, PAGE_HEIGHT]);
   const fonts = {
@@ -2538,6 +2725,7 @@ async function generatePdfFromContent(content, options = {}) {
     boldItalic: await pdfDoc.embedFont(pdfLib.StandardFonts.HelveticaBoldOblique)
   };
   const watermarkNodes = collectWatermarkNodes(content);
+  const { images, warnings: imageWarnings } = await preloadImages(pdfDoc, content);
   const state = {
     currentPage: firstPage,
     pageIndex: 0,
@@ -2546,7 +2734,9 @@ async function generatePdfFromContent(content, options = {}) {
     pdfDoc,
     fieldPositions: /* @__PURE__ */ new Map(),
     drawFieldPlaceholders,
-    watermarkNodes
+    watermarkNodes,
+    theme,
+    images
   };
   renderWatermarksOnPage(firstPage, fonts, watermarkNodes);
   if (content.content) {
@@ -2557,6 +2747,8 @@ async function generatePdfFromContent(content, options = {}) {
   const allPages = pdfDoc.getPages();
   const totalPages = allPages.length;
   const pageNumFontSize = 9;
+  const hfFontSize = 8;
+  const hfColor = pdfLib.rgb(0.45, 0.45, 0.45);
   for (let i = 0; i < totalPages; i++) {
     const page = allPages[i];
     const label = `Page ${i + 1} of ${totalPages}`;
@@ -2568,35 +2760,77 @@ async function generatePdfFromContent(content, options = {}) {
       font: fonts.bold,
       color: pdfLib.rgb(0, 0, 0)
     });
+    if (header && (header.left || header.right) && !(header.skipFirstPage && i === 0)) {
+      const headerBaseY = PAGE_HEIGHT - MARGIN + 10;
+      if (header.left) {
+        page.drawText(header.left, {
+          x: MARGIN,
+          y: headerBaseY,
+          size: pageNumFontSize,
+          font: fonts.bold,
+          color: theme.pageHeaderText
+        });
+      }
+      if (header.right) {
+        const rightWidth = fonts.regular.widthOfTextAtSize(header.right, hfFontSize);
+        page.drawText(header.right, {
+          x: PAGE_WIDTH - MARGIN - rightWidth,
+          y: headerBaseY,
+          size: hfFontSize,
+          font: fonts.regular,
+          color: hfColor
+        });
+      }
+      page.drawLine({
+        start: { x: MARGIN, y: headerBaseY - 6 },
+        end: { x: PAGE_WIDTH - MARGIN, y: headerBaseY - 6 },
+        thickness: 0.75,
+        color: theme.pageHeaderRule
+      });
+    }
+    if (footer?.left) {
+      page.drawText(footer.left, {
+        x: MARGIN,
+        y: MARGIN / 2 - pageNumFontSize / 2,
+        size: hfFontSize,
+        font: fonts.regular,
+        color: hfColor
+      });
+    }
   }
   let fieldWarnings;
   if (embedFormFields && fields.length > 0) {
     const warnings = await addFormFields(pdfDoc, state.fieldPositions, fields);
     if (warnings.length > 0) fieldWarnings = warnings;
   }
-  const pdfBytes = await pdfDoc.save({ useObjectStreams: false });
+  const pdfBytes = new Uint8Array(await pdfDoc.save({ useObjectStreams: false }));
   return {
     pdfBytes,
     fieldPositions: state.fieldPositions,
-    fieldWarnings
+    fieldWarnings,
+    imageWarnings: imageWarnings.length > 0 ? imageWarnings : void 0
   };
 }
 
 // src/utils/template-pipeline.ts
-async function generatePdfFromTiptap(content, values) {
+async function generatePdfFromTiptap(content, values, options = {}) {
   const { content: expanded, values: enrichedValues } = expandRepeatContent(content, values);
   const suppressed = suppressZeroContent(expanded, enrichedValues);
   const replaced = replaceVariablesInContent(suppressed, enrichedValues);
   const fields = extractFieldsFromContent(replaced);
   const result = await generatePdfFromContent(replaced, {
     embedFormFields: fields.length > 0,
-    fields
+    fields,
+    theme: options.theme,
+    header: options.header,
+    footer: options.footer,
+    drawFieldPlaceholders: options.drawFieldPlaceholders
   });
-  return { pdfBytes: result.pdfBytes };
+  return { pdfBytes: result.pdfBytes, imageWarnings: result.imageWarnings };
 }
-async function generatePdfFromMarkdown(markdown, values) {
+async function generatePdfFromMarkdown(markdown, values, options = {}) {
   const content = markdownToTiptap(markdown);
-  return generatePdfFromTiptap(content, values);
+  return generatePdfFromTiptap(content, values, options);
 }
 
 // src/utils/markdown-writer.ts
@@ -2616,6 +2850,20 @@ function serializeFieldToken(attrs) {
   if (attrs.acknowledgements) parts.push(`acks:${btoa(attrs.acknowledgements)}`);
   return `{{${parts.join("|")}}}`;
 }
+function serializeImageNode(attrs) {
+  const hasExtras = attrs.varName || attrs.width || attrs.height || attrs.align;
+  if (!hasExtras && attrs.src) {
+    return `![${attrs.alt || ""}](${attrs.src})`;
+  }
+  const parts = ["image"];
+  if (attrs.varName) parts.push(`var:${attrs.varName}`);
+  else if (attrs.src) parts.push(`src:${attrs.src}`);
+  if (attrs.alt) parts.push(`alt:${attrs.alt}`);
+  if (attrs.width) parts.push(`width:${attrs.width}`);
+  if (attrs.height) parts.push(`height:${attrs.height}`);
+  if (attrs.align) parts.push(`align:${attrs.align}`);
+  return `{{${parts.join("|")}}}`;
+}
 function serializeVariableToken(attrs) {
   const parts = ["var"];
   if (attrs.varName) parts.push(`name:${attrs.varName}`);
@@ -2633,6 +2881,10 @@ function serializeInline(content) {
       result += serializeFieldToken(node.attrs || {});
       continue;
     }
+    if (node.type === "imageNode") {
+      result += serializeImageNode(node.attrs || {});
+      continue;
+    }
     if (node.type === "variableNode") {
       let token = serializeVariableToken(node.attrs || {});
       const varMarks = node.marks || [];
@@ -2739,6 +2991,9 @@ ${text}
     case "tableCell": {
       return (node.content || []).map(serializeBlock).join("");
     }
+    case "imageNode": {
+      return serializeImageNode(node.attrs || {});
+    }
     case "watermark": {
       const attrs = node.attrs || {};
       const parts = [];
@@ -4802,8 +5057,8 @@ function validateMarkdown(markdown) {
         errors.push(`Malformed token at line ${lineNum}: missing | delimiter`);
       } else {
         const tokenType = tokenContent.slice(0, pipeIdx);
-        if (tokenType !== "field" && tokenType !== "var") {
-          errors.push(`Unknown token type "${tokenType}" at line ${lineNum} (expected "field" or "var")`);
+        if (tokenType !== "field" && tokenType !== "var" && tokenType !== "image") {
+          errors.push(`Unknown token type "${tokenType}" at line ${lineNum} (expected "field", "var" or "image")`);
         } else {
           const body = tokenContent.slice(pipeIdx + 1);
           const pairs = body.split("|");
@@ -4817,6 +5072,11 @@ function validateMarkdown(markdown) {
             if (!hasName) {
               errors.push(`Variable token at line ${lineNum} is missing required "name" attribute`);
             }
+          } else if (tokenType === "image") {
+            const hasSource = pairs.some((p) => p.startsWith("src:") || p.startsWith("var:"));
+            if (!hasSource) {
+              errors.push(`Image token at line ${lineNum} needs a "src" or "var" attribute`);
+            }
           }
         }
       }