h17-sspdf 0.1.8 → 0.4.1

package/DOCUMENTATION.md

@@ -494,6 +494,49 @@ Renders a data table with optional header row, per-column alignment, alternating
 
 **Style cascade:** Engine defaults, then theme label, then source-level overrides. The source operation can override `altRowColor`, `cellPaddingMm`, and all border properties directly.
 
+#### `image`
+
+Embeds a PNG or JPEG image from a file path. The image and its caption are always kept together on the same page.
+
+```json
+{
+  "type": "image",
+  "src": "photos/cityscape.jpg",
+  "width": "100%",
+  "label": "editorial.photo",
+  "caption": "Fig. 1 - Downtown skyline at dusk",
+  "captionLabel": "editorial.photo.caption"
+}
+```
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `src` | yes | string | File path to a PNG or JPEG image (absolute, or relative to CWD) |
+| `width` | no | string | Percentage of content width (e.g., `"100%"`, `"50%"`). Height derived from aspect ratio. |
+| `widthMm` | no | number | Explicit width in mm. If `heightMm` is omitted, height derived from aspect ratio. |
+| `heightMm` | no | number | Explicit height in mm. If both `widthMm` and `heightMm` are set, the image may distort. |
+| `label` | no | string | Theme label for padding and margins around the image |
+| `caption` | no | string | Caption text rendered centered below the image |
+| `captionLabel` | no | string | Theme label for caption styling (default: `label + ".caption"`) |
+
+**Size resolution priority:**
+
+1. `widthMm` + `heightMm` both set: exact slot, may distort if aspect ratio differs
+2. `width: "80%"`: percentage of content area width, height from aspect ratio
+3. `widthMm` only: fixed width, height from aspect ratio
+4. `heightMm` only: fixed height, width from aspect ratio
+5. Nothing set: fills content width, height from aspect ratio
+
+When the image is narrower than the content area, it is centered horizontally within the padded bounds.
+
+**Caption behavior:** If `caption` is set, the text renders centered below the image. The caption label defaults to `label + ".caption"`. If no `captionLabel` or derived label exists in the theme, the engine applies defaults: same font family as `page.defaultText`, italic, 2pt smaller, centered, with a 1.5mm gap above the caption. Color is inherited from `defaultText` (not hardcoded), so it works on any background. To override the defaults, declare a `captionLabel` in the theme.
+
+**Image label properties:** The `label` on an image operation controls spacing around the image block (padding and margins), not typography. Use it to set `paddingTopMm`, `paddingBottomMm`, `paddingLeftMm`, `paddingRightMm`, `marginTopMm`, `marginBottomMm`. If no `label` is set, the image renders with zero padding and margins.
+
+**Keep-together:** The image and its caption are always rendered as one unit. If the total height (margins + padding + image + caption) does not fit on the current page, the entire block moves to the next page.
+
+**Works in any layout:** The image operation is a core type, not a plugin. It works in any source JSON with any theme. No registration or setup needed.
+
 #### `spacer`
 
 Adds vertical space without drawing anything.
@@ -615,6 +658,7 @@ The engine positions content using a cursor that starts at `marginTopMm` and mov
 | `spacer` | the specified mm/px value |
 | `hiddenText` | 0 |
 | `table` | marginTop + headerRowHeight + sum(dataRowHeights) + marginBottom |
+| `image` | marginTop + paddingTop + imageHeightMm + captionHeight + paddingBottom + marginBottom |
 | `block` | sum of children deltas (+ spaceAfter if defined) |
 
 Where:
@@ -1285,6 +1329,7 @@ This applies to all color properties: `color`, `backgroundColor`, `borderColor`,
 | `bullet` | `label`, `text`/`items`/`bullets` | `markerLabel`, `marker`, `textIndentMm` |
 | `divider` | `label` | `x1Mm`, `x2Mm` |
 | `table` | `label`, `columns`, `rows` | `headerLabel`, `xMm`, `maxWidthMm`, border/padding overrides |
+| `image` | `src` | `width`, `widthMm`, `heightMm`, `label`, `caption`, `captionLabel` |
 | `spacer` | `mm` or `px` or `label` | - |
 | `block` | `children`/`content`/`items` | `label`, `keepTogether`, `spaceAfterMm`/`Px`/`Label` |
 | `section` | `content` | `label`, `keepTogether` |

package/README.md

@@ -261,6 +261,7 @@ labels: {
 | `row` | Left/right pair on one line | `leftLabel`, `rightLabel`, `leftText`, `rightText` |
 | `bullet` | Marker + wrapped text | `label`, `markerLabel`, `bullets` (array) |
 | `divider` | Horizontal rule | `label`, `x1Mm`, `x2Mm` |
+| `image` | Embedded PNG/JPEG | `src`, `width` (percentage or mm), `caption` |
 | `spacer` | Vertical gap | `mm`, `px`, or `label` |
 | `hiddenText` | Invisible text | `label`, `text` |
 | `quote` | Blockquote with attribution | `label`, `text`, `attribution` |

package/core/image-utils.js

@@ -0,0 +1,112 @@
+"use strict";
+
+/**
+ * Read native width/height from PNG or JPEG buffer.
+ * Returns { width, height, format } or throws.
+ */
+function getImageDimensions(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    buf = Buffer.from(buf);
+  }
+
+  // PNG: signature 89 50 4E 47, dimensions in IHDR at bytes 16-23
+  if (buf.length >= 24 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4E && buf[3] === 0x47) {
+    const width = buf.readUInt32BE(16);
+    const height = buf.readUInt32BE(20);
+    return { width, height, format: "PNG" };
+  }
+
+  // JPEG: signature FF D8
+  if (buf.length >= 4 && buf[0] === 0xFF && buf[1] === 0xD8) {
+    let offset = 2;
+    while (offset < buf.length - 1) {
+      if (buf[offset] !== 0xFF) {
+        offset++;
+        continue;
+      }
+      const marker = buf[offset + 1];
+
+      // SOF markers: C0-C3, C5-C7, C9-CB, CD-CF
+      if (
+        (marker >= 0xC0 && marker <= 0xC3) ||
+        (marker >= 0xC5 && marker <= 0xC7) ||
+        (marker >= 0xC9 && marker <= 0xCB) ||
+        (marker >= 0xCD && marker <= 0xCF)
+      ) {
+        // offset+2 = length (2 bytes), offset+4 = precision (1 byte)
+        // offset+5 = height (2 bytes), offset+7 = width (2 bytes)
+        if (offset + 8 < buf.length) {
+          const height = buf.readUInt16BE(offset + 5);
+          const width = buf.readUInt16BE(offset + 7);
+          return { width, height, format: "JPEG" };
+        }
+      }
+
+      // Skip marker segment
+      if (marker === 0xD0 || marker === 0xD1 || marker === 0xD2 || marker === 0xD3 ||
+          marker === 0xD4 || marker === 0xD5 || marker === 0xD6 || marker === 0xD7 ||
+          marker === 0xD8 || marker === 0xD9 || marker === 0x01) {
+        offset += 2;
+        continue;
+      }
+
+      if (offset + 3 < buf.length) {
+        const segLen = buf.readUInt16BE(offset + 2);
+        offset += 2 + segLen;
+      } else {
+        break;
+      }
+    }
+    throw new Error("JPEG file: could not find SOF marker for dimensions");
+  }
+
+  throw new Error("Unsupported image format. Only PNG and JPEG are supported.");
+}
+
+/**
+ * Resolve display dimensions from source operation and content bounds.
+ *
+ * @param {object} op - Operation with width/widthMm/heightMm
+ * @param {number} nativeW - Native image width in pixels
+ * @param {number} nativeH - Native image height in pixels
+ * @param {number} contentWidthMm - Available content width in mm
+ * @returns {{ widthMm: number, heightMm: number }}
+ */
+function resolveImageSize(op, nativeW, nativeH, contentWidthMm) {
+  const ratio = nativeH / nativeW;
+
+  // Explicit mm for both dimensions (may distort)
+  if (op.widthMm !== undefined && op.heightMm !== undefined) {
+    return { widthMm: Number(op.widthMm), heightMm: Number(op.heightMm) };
+  }
+
+  // Percentage width, derive height from aspect ratio
+  if (op.width !== undefined) {
+    const pctStr = String(op.width);
+    let widthMm;
+    if (pctStr.endsWith("%")) {
+      const pct = parseFloat(pctStr) / 100;
+      widthMm = contentWidthMm * pct;
+    } else {
+      widthMm = parseFloat(pctStr);
+    }
+    return { widthMm, heightMm: widthMm * ratio };
+  }
+
+  // Explicit widthMm only, derive height
+  if (op.widthMm !== undefined) {
+    const widthMm = Number(op.widthMm);
+    return { widthMm, heightMm: widthMm * ratio };
+  }
+
+  // Explicit heightMm only, derive width
+  if (op.heightMm !== undefined) {
+    const heightMm = Number(op.heightMm);
+    return { widthMm: heightMm / ratio, heightMm };
+  }
+
+  // Default: fill content width
+  return { widthMm: contentWidthMm, heightMm: contentWidthMm * ratio };
+}
+
+module.exports = { getImageDimensions, resolveImageSize };

package/core/pdf-core.js

@@ -614,6 +614,10 @@ class PDFCore {
       ? Number(payload.y) + marginTopMm
       : this.cursorY + marginTopMm;
 
+    // Save/restore graphics state around addImage to prevent jsPDF font leak
+    if (typeof this.doc.saveGraphicsState === "function") {
+      this.doc.saveGraphicsState();
+    }
     this.doc.addImage(
       payload.data,
       payload.format || "PNG",
@@ -622,6 +626,10 @@ class PDFCore {
       widthMm,
       heightMm
     );
+    if (typeof this.doc.restoreGraphicsState === "function") {
+      this.doc.restoreGraphicsState();
+    }
+    this.applyDefaultRenderState();
 
     const endY = drawY + heightMm;
     this.lastDrawnBounds = {

package/core/plugin-registry.js

@@ -2,7 +2,7 @@ const _plugins = new Map();
 
 const BUILT_IN_TYPES = new Set([
   "text", "row", "bullet", "divider", "spacer", "hiddenText",
-  "block", "section", "group", "quote", "table",
+  "block", "section", "group", "quote", "table", "image",
 ]);
 
 function registerPlugin(type, handler) {

package/core/render-document.js

@@ -1,8 +1,11 @@
+const fs = require("fs");
+const path = require("path");
 const { PDFCore, getStyleMarginsMm, getTextPaddingMm, applyTextTransform } = require("./pdf-core");
 const { pxToMm, resolveLineHeightMm } = require("./units");
 const { registerThemeFonts } = require("./font-registry");
 const { getPlugin, hasPlugin } = require("./plugin-registry");
 const { validateSource, validateTheme, validateSourceAgainstTheme } = require("./validate");
+const { getImageDimensions, resolveImageSize } = require("./image-utils");
 
 /**
  * Render a document by executing labeled operations.
@@ -334,6 +337,7 @@ function isOperationType(type) {
     || type === "spacer"
     || type === "hiddenText"
     || type === "table"
+    || type === "image"
     || hasPlugin(type);
 }
 
@@ -731,6 +735,138 @@ function executeOperation(ctx) {
     return;
   }
 
+  if (operation.type === "image") {
+    const bounds = getHorizontalBounds(core, templateBypassMargins);
+    const contentWidthMm = bounds.right - bounds.left;
+
+    // Read image file
+    const srcPath = operation.src;
+    if (!srcPath) {
+      throw new Error(`Operation ${index} (image) missing "src" field`);
+    }
+    const resolvedPath = path.isAbsolute(srcPath) ? srcPath : path.resolve(process.cwd(), srcPath);
+    let buf;
+    try {
+      buf = fs.readFileSync(resolvedPath);
+    } catch (err) {
+      throw new Error(`Operation ${index} (image) could not read file "${resolvedPath}": ${err.message}`);
+    }
+    if (!buf || buf.length === 0) {
+      throw new Error(`Operation ${index} (image) file is empty: "${resolvedPath}"`);
+    }
+    let imgInfo;
+    try {
+      imgInfo = getImageDimensions(buf);
+    } catch (err) {
+      throw new Error(`Operation ${index} (image) could not read dimensions from "${resolvedPath}": ${err.message}`);
+    }
+    if (!imgInfo || !imgInfo.width || !imgInfo.height) {
+      throw new Error(`Operation ${index} (image) invalid dimensions from "${resolvedPath}"`);
+    }
+    const { widthMm, heightMm } = resolveImageSize(operation, imgInfo.width, imgInfo.height, contentWidthMm);
+    if (!widthMm || widthMm <= 0 || !heightMm || heightMm <= 0) {
+      throw new Error(`Operation ${index} (image) resolved to invalid size: ${widthMm}x${heightMm}mm`);
+    }
+
+    // Resolve padding from label
+    const style = operation.label
+      ? resolveLabelStyle(theme, operation.label, operation, index, "label", true) || {}
+      : {};
+    const padding = getTextPaddingMm(style);
+    const marginTop = getStyleMarginsMm(style).top;
+    const marginBottom = getStyleMarginsMm(style).bottom;
+
+    // Caption style and height
+    let captionLines = [];
+    let captionStyle = null;
+    let captionLineHeightMm = 0;
+    let captionHeight = 0;
+    if (operation.caption) {
+      const capLabel = operation.captionLabel || (operation.label ? operation.label + ".caption" : null);
+      captionStyle = capLabel
+        ? resolveLabelStyle(theme, capLabel, operation, index, "captionLabel", true)
+        : null;
+      if (!captionStyle) {
+        // Fall back to theme default text: same family, italic, smaller, gray, centered, with gap
+        const dt = theme.page.defaultText || {};
+        captionStyle = Object.assign({}, dt, {
+          fontStyle: "italic",
+          fontSize: Math.max((Number(dt.fontSize) || 10) - 2, 7),
+          align: "center",
+          marginTopMm: 1.5,
+        });
+      }
+      if (!captionStyle.align) {
+        captionStyle.align = "center";
+      }
+      captionLineHeightMm = resolveLineHeightMm(
+        Number(captionStyle.fontSize) || 10,
+        captionStyle.lineHeight || 1.2
+      );
+      const captionWidth = widthMm - padding.left - padding.right;
+      captionLines = core.measureWrappedLines(
+        applyTextTransform(operation.caption, captionStyle.textTransform),
+        captionWidth > 0 ? captionWidth : widthMm,
+        captionStyle
+      );
+      const captionMargins = getStyleMarginsMm(captionStyle);
+      captionHeight = captionMargins.top + (Math.max(captionLines.length, 1) * captionLineHeightMm) + captionMargins.bottom;
+    }
+
+    // Total block height
+    const totalHeight = marginTop + padding.top + heightMm + captionHeight + padding.bottom + marginBottom;
+
+    if (!templateMode) {
+      core.ensureSpace(totalHeight);
+    }
+
+    const startY = core.cursorY + marginTop;
+    const innerLeft = bounds.left + padding.left;
+    const innerWidth = contentWidthMm - padding.left - padding.right;
+
+    // Center image within padded area
+    const imgX = innerLeft + (innerWidth - widthMm) / 2;
+    const imgY = startY + padding.top;
+
+    // Draw image
+    const base64 = buf.toString("base64");
+    core.drawImage({
+      data: base64,
+      format: imgInfo.format,
+      x: imgX,
+      y: imgY,
+      widthMm,
+      heightMm,
+      style: {},
+      advance: false,
+      allowPageBreak: false,
+    });
+
+    // Reset jsPDF font state after addImage (jsPDF addImage corrupts the
+    // font state in the PDF content stream without updating its internal tracker,
+    // so subsequent setFont calls may be silently ignored)
+    core.applyDefaultRenderState();
+
+    // Draw caption at the correct Y by setting cursor before drawText
+    if (operation.caption && captionStyle && captionLines.length > 0) {
+      core.cursorY = imgY + heightMm;
+      const captionX = innerLeft;
+      const captionWidth = innerWidth > 0 ? innerWidth : widthMm;
+      core.drawText({
+        text: operation.caption,
+        style: captionStyle,
+        x: captionX,
+        maxWidth: captionWidth,
+        advance: true,
+        allowPageBreak: false,
+      });
+    }
+
+    // Advance cursor past the whole block
+    core.cursorY = startY + padding.top + heightMm + captionHeight + padding.bottom + marginBottom;
+    return;
+  }
+
   const plugin = getPlugin(operation.type);
   if (plugin) {
     const bounds = getHorizontalBounds(core, templateBypassMargins);
@@ -935,6 +1071,45 @@ function estimateOperationHeight(ctx) {
     return total;
   }
 
+  if (operation.type === "image") {
+    const style = operation.label
+      ? resolveLabelStyle(theme, operation.label, operation, index)
+      : {};
+    const margins = getStyleMarginsMm(style);
+    const padding = getTextPaddingMm(style);
+    const contentWidthMm = core.pageWidth - core.marginLeftMm - core.marginRightMm;
+
+    // Read image to get dimensions for height calculation
+    let imgHeightMm = 80; // fallback
+    if (operation.src) {
+      try {
+        const resolvedPath = path.isAbsolute(operation.src) ? operation.src : path.resolve(process.cwd(), operation.src);
+        const buf = fs.readFileSync(resolvedPath);
+        const imgInfo = getImageDimensions(buf);
+        const resolved = resolveImageSize(operation, imgInfo.width, imgInfo.height, contentWidthMm - padding.left - padding.right);
+        imgHeightMm = resolved.heightMm;
+      } catch (e) {
+        // If file can't be read during height calc, use fallback
+      }
+    } else if (operation.heightMm !== undefined) {
+      imgHeightMm = Number(operation.heightMm);
+    }
+
+    let captionHeight = 0;
+    if (operation.caption) {
+      const capLabel = operation.captionLabel || (operation.label ? operation.label + ".caption" : null);
+      const captionStyle = capLabel
+        ? resolveLabelStyle(theme, capLabel, operation, index, "captionLabel", true)
+        : Object.assign({}, theme.page.defaultText);
+      const capLh = resolveLineHeightMm(Number(captionStyle.fontSize) || 10, captionStyle.lineHeight || 1.2);
+      const capMargins = getStyleMarginsMm(captionStyle);
+      // Rough: 1 line for caption height calc
+      captionHeight = capMargins.top + capLh + capMargins.bottom;
+    }
+
+    return margins.top + padding.top + imgHeightMm + captionHeight + padding.bottom + margins.bottom;
+  }
+
   const plugin = getPlugin(operation.type);
   if (plugin) {
     if (typeof plugin.estimateHeight === "function") {

package/core/validate.js

@@ -2,7 +2,7 @@ const { hasPlugin } = require("./plugin-registry");
 
 const OPERATION_TYPES = new Set([
   "text", "row", "bullet", "divider", "spacer", "hiddenText",
-  "block", "group", "section", "quote", "table",
+  "block", "group", "section", "quote", "table", "image",
 ]);
 
 function validateSource(source) {
@@ -94,6 +94,11 @@ function validateOperation(op, path) {
     return;
   }
 
+  if (type === "image") {
+    if (!op.src) throw new Error(`${path}: image requires src`);
+    return;
+  }
+
   if (type === "block" || type === "group" || type === "section") {
     const children = op.children || op.content || op.items || op.sections;
     if (!Array.isArray(children)) {
@@ -150,10 +155,17 @@ function collectLabels(node, missing, themeLabels) {
   if (node.headerLabel && !themeLabels.has(node.headerLabel)) missing.push(node.headerLabel);
   if (node.spaceAfterLabel && !themeLabels.has(node.spaceAfterLabel)) missing.push(node.spaceAfterLabel);
 
+  if (node.captionLabel && !themeLabels.has(node.captionLabel)) missing.push(node.captionLabel);
+
   if (node.type === "quote" && node.attribution) {
     const attrLabel = node.attributionLabel || (node.label + ".attribution");
     if (!themeLabels.has(attrLabel)) missing.push(attrLabel);
   }
+
+  if (node.type === "image" && node.caption && !node.captionLabel && node.label) {
+    const capLabel = node.label + ".caption";
+    if (!themeLabels.has(capLabel)) missing.push(capLabel);
+  }
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h17-sspdf",
-  "version": "0.1.8",
+  "version": "0.4.1",
   "description": "Declarative PDF engine - define layout once, feed it JSON, get consistent PDFs",
   "main": "index.js",
   "author": "Hugo Palma",
@@ -38,7 +38,7 @@
     "type": "git",
     "url": "git+ssh://git@github.com/hugopalma17/sspdf.git"
   },
-  "homepage": "https://github.com/hugopalma17/sspdf#readme",
+  "homepage": "https://h17.ai/docs/sspdf",
   "bugs": {
     "url": "https://github.com/hugopalma17/sspdf/issues"
   },