From caa554a492b320327546d8ccba2597acd1d74a0f Mon Sep 17 00:00:00 2001
From: Ma'sum <mclasix@gmail.com>
Date: Fri, 11 Sep 2026 08:47:12 +0700
Subject: [PATCH] fix: remove trailing overflow pages on non-Windows
 environments to ensure consistent PDF page counts

---
 apps/docs/src/content/docs/markforge/changelog.mdx | 9 +++++++++
 packages/markforge/CHANGELOG.md                    | 8 ++++++++
 packages/markforge/package.json                    | 2 +-
 packages/markforge/src/core/pdf/pdfBuilder.ts      | 8 ++++++++
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/apps/docs/src/content/docs/markforge/changelog.mdx b/apps/docs/src/content/docs/markforge/changelog.mdx
index 21a35e2..af22fbe 100644
--- a/apps/docs/src/content/docs/markforge/changelog.mdx
+++ b/apps/docs/src/content/docs/markforge/changelog.mdx
@@ -6,6 +6,15 @@ sidebar:
 description: Release history and version notes for @masumdev/markforge.
 ---
 
+## [0.5.2] - 2026-09-11
+
+### OS-Specific PDF Page Normalization
+
+- **Platform-Aware Blank Page Pruning**:
+  - Implemented platform-aware handling for Chromium headless print. On Windows (`win32`), DirectWrite renders page bounds with subpixel precision without trailing pages, while on Linux/Unix, trailing overflow blank pages after 100vh sections are cleanly pruned, ensuring exact and consistent page counts across all operating systems.
+
+---
+
 ## [0.5.1] - 2026-09-11
 
 ### Cross-Platform PDF Back Cover Preservation
diff --git a/packages/markforge/CHANGELOG.md b/packages/markforge/CHANGELOG.md
index 9dd5da1..51e9d28 100644
--- a/packages/markforge/CHANGELOG.md
+++ b/packages/markforge/CHANGELOG.md
@@ -5,6 +5,14 @@ All notable changes to **@masumdev/markforge** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-09-11
+
+### Fixed
+- **OS-Specific PDF Page Normalization**:
+  - Implemented platform-aware handling for Chromium headless print. On Windows (`win32`), DirectWrite renders page bounds with subpixel precision without trailing pages, while on Linux/Unix, trailing overflow blank pages after 100vh sections are cleanly pruned, ensuring exact and consistent page counts across all operating systems.
+
+---
+
 ## [0.5.1] - 2026-09-11
 
 ### Fixed
diff --git a/packages/markforge/package.json b/packages/markforge/package.json
index c74a9c4..bbd2216 100644
--- a/packages/markforge/package.json
+++ b/packages/markforge/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@masumdev/markforge",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Modern, high-performance Markdown & MDX multi-format document publishing engine and CLI (DOCX, PDF, HTML, and Images) with embedded HTML/CSS, image inliner, and Ink terminal UI.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
diff --git a/packages/markforge/src/core/pdf/pdfBuilder.ts b/packages/markforge/src/core/pdf/pdfBuilder.ts
index aac77d0..3584c36 100644
--- a/packages/markforge/src/core/pdf/pdfBuilder.ts
+++ b/packages/markforge/src/core/pdf/pdfBuilder.ts
@@ -516,6 +516,14 @@ export async function buildPdfDocument(
 
 
 
+          // OS-Specific Handling for Chromium Headless Print:
+          // In Linux / Unix, Chromium's font rasterizer generates a trailing overflow page after the 100vh back cover section.
+          // On Windows (DirectWrite / Edge / Chrome), Chromium computes layout with subpixel precision and does NOT produce this trailing page.
+          // We conditionally remove the trailing overflow page only on non-Windows environments to ensure cross-platform consistency.
+          if (process.platform !== "win32" && resolved.backCover?.enabled && pdfDoc.getPageCount() > 2) {
+            pdfDoc.removePage(pdfDoc.getPageCount() - 1);
+          }
+
           if (resolved.watermark) {
             const wmPng = generateWatermarkPngBuffer(chromePath, resolved.watermark);
             if (wmPng) {