h17-sspdf 0.4.1 → 1.0.0

package/DOCUMENTATION.md

@@ -30,9 +30,11 @@ Controls page geometry, background, and baseline rendering state.
 ```js
 page: {
   // Page geometry
-  format: "a4",                   // only "a4" is supported
+  format: "a4",                   // named format: "a4", "letter", etc.
   orientation: "portrait",        // "portrait" or "landscape"
   unit: "mm",                     // only "mm" is supported
+  pageWidthMm: 338,               // custom width in mm (overrides format)
+  pageHeightMm: 190,              // custom height in mm (overrides format)
   compress: true,                 // PDF compression (default true)
 
   // Margins - individual margins override the shared `margin` value
@@ -76,7 +78,9 @@ page: {
 }
 ```
 
-The content area runs from `marginTop` to `pageHeight - marginBottom` vertically, and `marginLeft` to `pageWidth - marginRight` horizontally. On A4 portrait, the page is 210 × 297 mm.
+The content area runs from `marginTop` to `pageHeight - marginBottom` vertically, and `marginLeft` to `pageWidth - marginRight` horizontally. On A4 portrait, the page is 210 x 297 mm.
+
+When `pageWidthMm` and `pageHeightMm` are both set, they override the `format` field and create a page with those exact dimensions. This is useful for non-standard formats like 16:9 presentations (e.g. 338 x 190 mm). All layout math -- margins, content area, pagination -- adapts automatically.
 
 ### `labels` (required)
 
@@ -235,6 +239,7 @@ Shared layout defaults read by operation handlers.
 ```js
 layout: {
   bulletIndentMm: 4.5,     // text indent after bullet marker (default: 4)
+  chartAlign: "center",    // chart horizontal alignment: "left" (default) or "center"
 }
 ```
 
@@ -553,6 +558,16 @@ Three forms (use exactly one):
 | `px` | number | Fixed space in CSS px |
 | `label` | string | Theme label with `spaceMm` or `spacePx` |
 
+#### `pageBreak`
+
+Forces a new page. The cursor resets to the top content area. Page templates (headers/footers) are applied to the new page automatically.
+
+```json
+{ "type": "pageBreak" }
+```
+
+No fields required. Useful for presentation-style layouts where each section should start on its own page.
+
 #### `hiddenText`
 
 Renders text in the background color so it's invisible but present in the PDF text layer (for ATS keyword injection).
@@ -1714,11 +1729,12 @@ main();
 | `chartType` | yes | string | Chart.js type: `"bar"`, `"line"`, `"doughnut"`, etc. |
 | `data` | yes | object | Chart.js `data` config (`labels` + `datasets`) |
 | `widthMm` | no | number | Width in the PDF in mm (default: content area width) |
-| `heightMm` | no | number | Height in the PDF in mm (default: 80) |
+| `heightMm` | no | number or `"fill"` | Height in mm (default: 80). `"fill"` uses remaining page space. |
 | `canvasWidth` | no | number | Canvas render width in pixels (default: 1600) |
 | `canvasHeight` | no | number | Canvas render height in pixels (default: 800) |
 | `options` | no | object | Chart.js `options` object. `responsive: false` and `animation: false` are injected automatically. |
 | `xMm` | no | number | Left edge in mm (default: content left margin) |
+| `align` | no | string | `"left"` (default) or `"center"`. Can also be set globally via `layout.chartAlign` in the theme. |
 
 ### Resolution
 

package/README.md

@@ -263,6 +263,7 @@ labels: {
 | `divider` | Horizontal rule | `label`, `x1Mm`, `x2Mm` |
 | `image` | Embedded PNG/JPEG | `src`, `width` (percentage or mm), `caption` |
 | `spacer` | Vertical gap | `mm`, `px`, or `label` |
+| `pageBreak` | Force new page | (none) |
 | `hiddenText` | Invisible text | `label`, `text` |
 | `quote` | Blockquote with attribution | `label`, `text`, `attribution` |
 | `block` | Group children, optional background + border | `children`, `keepTogether` |
@@ -466,7 +467,7 @@ Claude Code skills for generating PDFs and themes are available in the `skills/`
 
 ## Constraints
 
-- A4 only
+- Page format defaults to A4; custom dimensions supported via `pageWidthMm`/`pageHeightMm` (e.g. 16:9 presentations)
 - Single-line `row` cells, no multi-line column pairs
 - `{{page}}` gives the current page number; `{{pages}}` (total page count) is not supported because keep-together rules make the final page count unpredictable until the last operation is laid out
 - Charts require the `canvas` npm package (native C++ addon) for server-side rendering; everything else is zero native dependencies

package/core/pdf-core.js

@@ -77,6 +77,8 @@ class PDFCore {
    * @param {number} [theme.page.margin]
    * @param {string} [theme.page.format]
    * @param {string} [theme.page.orientation]
+   * @param {number} [theme.page.pageWidthMm]
+   * @param {number} [theme.page.pageHeightMm]
    * @param {string} [theme.page.unit]
    * @param {boolean} [theme.page.compress]
    * @param {number[]} [theme.page.backgroundColor]
@@ -102,11 +104,13 @@ class PDFCore {
     this.margin = this.marginLeftMm;
     this.headerHeightMm = Number(this.page.headerHeightMm) || 0;
     this.footerHeightMm = Number(this.page.footerHeightMm) || 0;
-    this.format = String(this.page.format || "a4").toLowerCase();
+    const customW = Number(this.page.pageWidthMm) || 0;
+    const customH = Number(this.page.pageHeightMm) || 0;
+    const hasCustomDimensions = customW > 0 && customH > 0;
 
-    if (this.format !== "a4") {
-      throw new Error(`Unsupported page format "${this.page.format}". Only A4 is supported.`);
-    }
+    this.format = hasCustomDimensions
+      ? [customW, customH]
+      : String(this.page.format || "a4").toLowerCase();
 
     this.doc = new jsPDF({
       orientation: this.page.orientation || "portrait",
@@ -119,6 +123,8 @@ class PDFCore {
     this.pageHeight = this.doc.internal.pageSize.getHeight();
     this.backgroundColor = this._resolveColor(this.page.backgroundColor);
     this.lastDrawnBounds = null;
+    this.documentStateDepth = 0;
+    this.hasDeferredInitialRenderState = Array.isArray(theme.customFonts) && theme.customFonts.length > 0;
     this.defaultRenderState = this._buildDefaultRenderState(this.page);
     this.contentTopY = this.marginTopMm + this.headerHeightMm;
     this.contentBottomY = this.pageHeight - this.marginBottomMm - this.footerHeightMm;
@@ -134,7 +140,12 @@ class PDFCore {
     });
 
     this.paintBackground();
-    this.applyDefaultRenderState();
+    // Custom fonts are registered by renderDocument() after core construction.
+    // Deferring the first setFont() avoids jsPDF warnings when page.defaultText
+    // uses a custom family that is not yet in the font map.
+    if (!this.hasDeferredInitialRenderState) {
+      this.applyDefaultRenderState();
+    }
   }
 
   /**
@@ -174,9 +185,11 @@ class PDFCore {
    * Force a new page and reset cursor to top margin.
    */
   addPage() {
+    const reopenedStateDepth = this._closeDocumentStatesForPageBreak();
     this.doc.addPage();
     this.paintBackground();
     this.applyDefaultRenderState();
+    this._reopenDocumentStatesAfterPageBreak(reopenedStateDepth);
     this.cursorY = this.contentTopY;
   }
 
@@ -194,6 +207,7 @@ class PDFCore {
       && typeof this.doc.restoreGraphicsState === "function";
     if (canSaveGraphicsState) {
       this.doc.saveGraphicsState();
+      this.documentStateDepth += 1;
     }
 
     try {
@@ -201,6 +215,7 @@ class PDFCore {
     } finally {
       if (canSaveGraphicsState) {
         this.doc.restoreGraphicsState();
+        this.documentStateDepth = Math.max(0, this.documentStateDepth - 1);
       }
       this.applyDefaultRenderState();
     }
@@ -494,11 +509,21 @@ class PDFCore {
     const baseline = y + baselineOffsetMm;
 
     if (markerStyle.shape) {
-      // Vector shape marker: renders via core/shapes.js, no text encoding needed
+      // Vector shape marker: renders via core/shapes.js, no text encoding needed.
+      // Wrapped in saveGraphicsState/restoreGraphicsState to isolate draw state
+      // mutations (setLineCap, setFillColor, etc.) from the main content stream.
+      // Without this, accumulated state operators can cause print rendering issues
+      // where printer RIPs interpret the stacked state differently than screen viewers.
       const { renderShape, getShapeWidth } = require("./shapes");
       const shapeColor = markerStyle.shapeColor || markerStyle.color || [0, 0, 0];
       const shapeSize = markerStyle.shapeSize || 1;
+      if (typeof this.doc.saveGraphicsState === "function") {
+        this.doc.saveGraphicsState();
+      }
       renderShape(markerStyle.shape, this.doc, x, baseline, shapeColor, shapeSize, textFontSize);
+      if (typeof this.doc.restoreGraphicsState === "function") {
+        this.doc.restoreGraphicsState();
+      }
       this.applyDefaultRenderState();
     } else {
       // Text-based marker (existing behavior)
@@ -1066,6 +1091,29 @@ class PDFCore {
       fillColor: this._resolveColor(page.defaultFillColor),
     };
   }
+
+  _closeDocumentStatesForPageBreak() {
+    if (this.documentStateDepth <= 0) {
+      return 0;
+    }
+
+    for (let i = 0; i < this.documentStateDepth; i += 1) {
+      this.doc.restoreGraphicsState();
+    }
+
+    return this.documentStateDepth;
+  }
+
+  _reopenDocumentStatesAfterPageBreak(depth) {
+    const count = Number(depth) || 0;
+    if (count <= 0) {
+      return;
+    }
+
+    for (let i = 0; i < count; i += 1) {
+      this.doc.saveGraphicsState();
+    }
+  }
 }
 
 module.exports = {

package/core/plugin-chart.js

@@ -132,14 +132,30 @@ module.exports = {
       );
     }
 
-    const widthMm  = operation.widthMm  || (bounds.right - bounds.left);
-    const heightMm = operation.heightMm || 80;
-    const x        = operation.xMm !== undefined ? operation.xMm : bounds.left;
+    const { theme } = ctx;
+    const contentWidth = bounds.right - bounds.left;
+    const widthMm  = operation.widthMm  || contentWidth;
+    const heightMm = operation.heightMm === "fill"
+      ? Math.max(0, core.contentBottomY - core.getCursorY())
+      : (operation.heightMm || 80);
+    const align = operation.align || (theme && theme.layout && theme.layout.chartAlign) || "left";
+
+    let x;
+    if (operation.xMm !== undefined) {
+      x = operation.xMm;
+    } else if (align === "center") {
+      x = bounds.left + (contentWidth - widthMm) / 2;
+    } else {
+      x = bounds.left;
+    }
 
     core.drawImage({ data: operation._buf, format: 'PNG', x, widthMm, heightMm });
   },
 
   estimateHeight(ctx) {
+    if (ctx.operation.heightMm === "fill") {
+      return ctx.core.contentBottomY - ctx.core.getCursorY();
+    }
     return (ctx.operation.heightMm || 80) + 4;
   },
 

package/core/render-document.js

@@ -47,6 +47,7 @@ function renderDocument(input) {
 
   const core = new PDFCore(runtimeTheme);
   registerThemeFonts(core, runtimeTheme);
+  core.applyDefaultRenderState();
 
   installPageTemplates(core, runtimeTheme, built.pageTemplates);
 
@@ -221,17 +222,21 @@ function executeOperations(ctx) {
       }
     }
 
-    core.withDocumentState(() => {
-      executeOperation({
-        core,
-        theme,
-        operation,
-        index,
-        templateMode,
-        templateBypassMargins,
-        insideContainer,
+    if (operation.type === "pageBreak") {
+      core.addPage();
+    } else {
+      core.withDocumentState(() => {
+        executeOperation({
+          core,
+          theme,
+          operation,
+          index,
+          templateMode,
+          templateBypassMargins,
+          insideContainer,
+        });
       });
-    });
+    }
   }
 }
 
@@ -335,6 +340,7 @@ function isOperationType(type) {
     || type === "bullet"
     || type === "divider"
     || type === "spacer"
+    || type === "pageBreak"
     || type === "hiddenText"
     || type === "table"
     || type === "image"
@@ -1026,6 +1032,10 @@ function estimateOperationHeight(ctx) {
     throw new Error(`Spacer operation at index ${index} must provide mm, px, or label with spaceMm/spacePx`);
   }
 
+  if (operation.type === "pageBreak") {
+    return 0;
+  }
+
   if (operation.type === "hiddenText") {
     return 0;
   }