documonster 0.7.0 → 0.8.0

package/dist/cjs/modules/pdf/render/layout-engine.js

@@ -89,25 +89,39 @@ async function layoutSheet(sheet, options, fontManager) {
     }
     const layoutPages = [];
     const totalOutputPages = ctx.rowPages.length * ctx.colGroups.length;
-    for (const rowPage of ctx.rowPages) {
-        for (const colGroup of ctx.colGroups) {
+    // Excel's "Page order". `downThenOver` (Excel's default) walks each column
+    // band top to bottom before moving right; `overThenDown` walks each row band
+    // left to right before moving down. Only the nesting differs, so pick which
+    // axis is outer rather than materialising every pair.
+    const overThenDown = options.pageOrder === "overThenDown";
+    const outer = overThenDown ? ctx.rowPages : ctx.colGroups;
+    const inner = overThenDown ? ctx.colGroups : ctx.rowPages;
+    for (const outerTracks of outer) {
+        for (const innerTracks of inner) {
+            const rowPage = overThenDown ? outerTracks : innerTracks;
+            const colGroup = overThenDown ? innerTracks : outerTracks;
             layoutPages.push(buildPageLayout(ctx, rowPage, colGroup, layoutPages.length, sheet, options, fontManager));
             if (layoutPages.length < totalOutputPages) {
                 await (0, utils_base_1.yieldToEventLoop)();
             }
         }
     }
-    if (layoutPages.length > 0 && sheet.images) {
+    // Draft quality omits graphics, matching Excel's "Draft quality" option.
+    if (layoutPages.length > 0 && sheet.images && !options.draft) {
         assignImagesToPages(sheet.images, layoutPages, ctx.scaleFactor);
     }
-    if (layoutPages.length > 0 && sheet.charts) {
+    if (layoutPages.length > 0 && sheet.charts && !options.draft) {
         assignChartsToPages(sheet.charts, layoutPages, ctx.scaleFactor);
     }
-    const firstPageNumber = sheet.pageSetup?.firstPageNumber ?? 1;
+    // Excel's "Comments: at end of sheet" — appended after the grid so the page
+    // numbering below covers them too.
+    if (options.cellComments === "atEnd" && sheet.comments?.length) {
+        layoutPages.push(...buildCommentPages(sheet, sheet.comments, options, fontManager));
+    }
+    // Only the per-sheet index is settled here; `fixPageNumbers` in the exporter
+    // owns `pageNumber`, `sheetPageNumber` and the document-wide `sheetPageCount`.
     for (let i = 0; i < layoutPages.length; i++) {
-        layoutPages[i].sheetPageNumber = firstPageNumber + i;
         layoutPages[i].sheetPageIndex = i + 1;
-        layoutPages[i].sheetPageCount = layoutPages.length;
     }
     return layoutPages;
 }
@@ -137,14 +151,10 @@ function layoutChartsheet(sheet, documentOptions) {
     // affected when a single chartsheet flips to portrait.
     const orientation = sheet.orientation ?? documentOptions.orientation;
     const options = { ...documentOptions, orientation };
-    let pageWidth = options.pageSize.width;
-    let pageHeight = options.pageSize.height;
-    if (options.orientation === "landscape") {
-        [pageWidth, pageHeight] = [pageHeight, pageWidth];
-    }
+    const { width: pageWidth, height: pageHeight } = pageDimensions(options);
     const margins = options.margins;
-    const headerHeight = options.showSheetNames ? 20 : 0;
-    const footerHeight = options.showPageNumbers ? 20 : 0;
+    const headerHeight = options.showSheetNames ? constants_1.SHEET_NAME_BAND_HEIGHT : 0;
+    const footerHeight = options.showPageNumbers ? constants_1.PAGE_NUMBER_BAND_HEIGHT : 0;
     const contentX = margins.left;
     const contentY = margins.bottom + footerHeight;
     const contentWidth = pageWidth - margins.left - margins.right;
@@ -159,7 +169,38 @@ function layoutChartsheet(sheet, documentOptions) {
         drawVector: sheet.chart.drawVector,
         raster: sheet.chart.raster
     };
-    const page = {
+    return [
+        {
+            ...blankPage(sheet, options),
+            // Draft quality omits graphics. A chartsheet is nothing but a graphic, so
+            // the page is still emitted — Excel likewise prints a blank sheet rather
+            // than dropping it from the page count.
+            charts: options.draft ? [] : [chart]
+        }
+    ];
+}
+// =============================================================================
+// Internal — Shared Layout Pipeline
+// =============================================================================
+/**
+ * Page dimensions for the resolved options, with landscape applied.
+ *
+ * `pageSize` is always stored portrait-wise, so every consumer has to swap the
+ * axes itself; centralised here so the four layout entry points cannot disagree.
+ */
+function pageDimensions(options) {
+    const { width, height } = options.pageSize;
+    return options.orientation === "landscape" ? { width: height, height: width } : { width, height };
+}
+/**
+ * A `LayoutPage` with every field at its empty value.
+ *
+ * The shape has ~20 members and four construction sites; building them from one
+ * skeleton means a new field cannot be forgotten in three of them.
+ */
+function blankPage(sheet, options) {
+    const { width, height } = pageDimensions(options);
+    return {
         pageNumber: 1,
         sheetPageNumber: sheet.pageSetup?.firstPageNumber ?? 1,
         sheetPageIndex: 1,
@@ -167,8 +208,8 @@ function layoutChartsheet(sheet, documentOptions) {
         firstPageNumber: sheet.pageSetup?.firstPageNumber,
         options,
         cells: [],
-        width: pageWidth,
-        height: pageHeight,
+        width,
+        height,
         sheetName: sheet.name,
         sheetCols: [],
         columnOffsets: [],
@@ -177,11 +218,10 @@ function layoutChartsheet(sheet, documentOptions) {
         rowYPositions: [],
         rowHeights: [],
         images: [],
-        charts: [chart],
+        charts: [],
         scaleFactor: 1,
         headerFooter: options.includeHeadersFooters ? sheet.headerFooter : undefined
     };
-    return [page];
 }
 /**
  * Steps 1–5: compute columns, scale, rows, merges, pagination.
@@ -189,45 +229,90 @@ function layoutChartsheet(sheet, documentOptions) {
  */
 function prepareLayout(sheet, options, fontManager) {
     const { margins } = options;
-    let pageWidth = options.pageSize.width;
-    let pageHeight = options.pageSize.height;
-    if (options.orientation === "landscape") {
-        [pageWidth, pageHeight] = [pageHeight, pageWidth];
-    }
-    const contentWidth = pageWidth - margins.left - margins.right;
-    const contentHeight = pageHeight - margins.top - margins.bottom;
-    const headerHeight = options.showSheetNames ? 20 : 0;
+    const { width: pageWidth, height: pageHeight } = pageDimensions(options);
+    const headerHeight = options.showSheetNames ? constants_1.SHEET_NAME_BAND_HEIGHT : 0;
     const printRange = getPrintRange(sheet, options);
-    // --- Step 1: Visible columns and widths ---
-    const { columnWidths, visibleCols } = computeColumnWidths(sheet, printRange);
+    // Excel's "Row and column headings". The bands are deliberately *not*
+    // scaled with the grid: they are a print aid rather than content, and a
+    // fixed size stays legible at small print scales while letting us reserve
+    // exactly the space we later draw into.
+    const headings = options.showRowColHeaders
+        ? computeHeadingMetrics(sheet, printRange, fontManager, options)
+        : undefined;
+    const gutterWidth = headings?.gutterWidth ?? 0;
+    const bandHeight = headings?.bandHeight ?? 0;
+    const contentWidth = pageWidth - margins.left - margins.right - gutterWidth;
+    const contentHeight = pageHeight - margins.top - margins.bottom - bandHeight;
+    // --- Step 1: Visible columns and widths (title columns lead) ---
+    const { columnWidths, visibleCols, repeatColIndices } = computeColumnWidths(sheet, printRange, options.repeatCols);
     if (visibleCols.length === 0) {
         return null;
     }
     // --- Step 2: Scale ---
+    // Rows are measured once, unscaled: heights are linear in the print scale, so
+    // the fit solver can probe by multiplying instead of re-measuring.
+    const natural = computeRowHeights(sheet, printRange, fontManager, options, options.repeatRows);
+    // Break sets are derived once: the fit solver paginates ~25 times per axis.
+    const rowBreaks = buildBreakSet(sheet.rowBreaks ?? [], natural.visibleRows);
+    const colBreaks = buildBreakSet(sheet.colBreaks ?? [], visibleCols);
     const totalTableWidth = columnWidths.reduce((sum, w) => sum + w, 0);
+    const footerHeight = options.showPageNumbers ? constants_1.PAGE_NUMBER_BAND_HEIGHT : 0;
+    const availableHeight = contentHeight - headerHeight - footerHeight;
     let scaleFactor = options.scale;
-    if (options.fitToPage && totalTableWidth > 0) {
-        const fitScale = contentWidth / totalTableWidth;
+    if (options.fitToWidth > 0 || options.fitToHeight > 0) {
+        // Excel's "Fit to N page(s) wide by M tall". Like Excel, this only ever
+        // shrinks — a grid smaller than the target is left at actual size.
+        //
+        // A total-size ratio alone does not deliver the promise: pagination packs
+        // indivisible columns/rows greedily, and repeated title bands consume space
+        // on every page after the first. Three columns at 60% of the page width fit
+        // "1.8 pages" by area yet still need three pages. So the ratio is only a
+        // starting upper bound, which we then tighten against the real packer.
+        let fit = 1;
+        // Excel's 10% floor applies to the *final* scale, so express it relative to
+        // the factor already in play.
+        const minFit = Math.min(1, constants_1.FIT_MIN_SCALE / scaleFactor);
+        if (options.fitToWidth > 0 && totalTableWidth > 0) {
+            fit = Math.min(fit, (contentWidth * options.fitToWidth) / (totalTableWidth * scaleFactor));
+            fit = tightenToPageCount(candidate => paginateTracks(columnWidths.map(w => w * scaleFactor * candidate), contentWidth, repeatColIndices, colBreaks, constants_1.COLUMN_FIT_EPSILON).length, options.fitToWidth, fit, minFit);
+        }
+        if (options.fitToHeight > 0 && availableHeight > 0) {
+            const totalTableHeight = natural.rowHeights.reduce((sum, h) => sum + h, 0);
+            if (totalTableHeight > 0) {
+                let heightFit = Math.min(fit, (availableHeight * options.fitToHeight) / (totalTableHeight * scaleFactor));
+                heightFit = tightenToPageCount(candidate => paginateTracks(natural.rowHeights.map(h => h * scaleFactor * candidate), availableHeight, natural.repeatRowIndices, rowBreaks).length, options.fitToHeight, heightFit, minFit);
+                fit = Math.min(fit, heightFit);
+            }
+        }
+        if (fit < 1) {
+            scaleFactor = Math.max(scaleFactor * fit, constants_1.FIT_MIN_SCALE);
+        }
+    }
+    else if (options.fitToPage && totalTableWidth > 0) {
+        // Same contract as `fitToWidth: 1`: it is the *final* width that must fit
+        // one page, so `scale` belongs inside the ratio rather than multiplied on
+        // top of it. Dividing by the running factor makes this `min(scale,
+        // contentWidth / totalTableWidth)`, which neither overflows when `scale`
+        // enlarges nor shrinks twice when it already reduces.
+        const fitScale = contentWidth / (totalTableWidth * scaleFactor);
         if (fitScale < 1) {
             scaleFactor *= fitScale;
         }
     }
     const scaledColumnWidths = columnWidths.map(w => w * scaleFactor);
-    const footerHeight = options.showPageNumbers ? 20 : 0;
-    const availableHeight = contentHeight - headerHeight - footerHeight;
-    // --- Step 3: Visible rows and heights ---
-    const { rowHeights, visibleRows } = computeRowHeights(sheet, scaleFactor, printRange, fontManager, options);
+    // --- Step 3: Apply the final scale to the measured heights ---
+    const rowHeights = natural.rowHeights.map(h => h * scaleFactor);
+    const { visibleRows, repeatRowIndices } = natural;
     // --- Step 4: Merge map ---
     const mergeMap = buildMergeMap(sheet);
     // --- Step 5: Paginate ---
-    const repeatRowCount = typeof options.repeatRows === "number" ? options.repeatRows : 0;
-    const rowBreakSet = buildRowBreakSet(sheet, visibleRows);
-    const rowPages = paginateRows(rowHeights, availableHeight, repeatRowCount, rowBreakSet);
-    const colGroups = paginateColumns(scaledColumnWidths, contentWidth, sheet, visibleCols);
+    const rowPages = paginateTracks(rowHeights, availableHeight, repeatRowIndices, rowBreaks);
+    const colGroups = paginateTracks(scaledColumnWidths, contentWidth, repeatColIndices, colBreaks, constants_1.COLUMN_FIT_EPSILON);
     return {
         pageWidth,
         pageHeight,
         contentWidth,
+        availableHeight,
         headerHeight,
         scaleFactor,
         scaledColumnWidths,
@@ -237,31 +322,179 @@ function prepareLayout(sheet, options, fontManager) {
         mergeMap,
         rowPages,
         colGroups,
-        margins
+        margins,
+        headings
+    };
+}
+/**
+ * Size the row-number gutter and column-letter band for Excel's "Row and
+ * column headings" print option.
+ *
+ * The gutter is sized from the widest row label that can appear in the printed
+ * range, so the grid origin is stable across pages instead of jittering as row
+ * numbers gain digits.
+ */
+function computeHeadingMetrics(sheet, printRange, fontManager, options) {
+    const fontSize = constants_1.HEADING_FONT_SIZE;
+    const resourceName = fontManager.hasEmbeddedFont()
+        ? fontManager.getEmbeddedResourceName()
+        : fontManager.ensureFont((0, font_manager_1.resolvePdfFontName)(options.defaultFontFamily, false, false));
+    const lastRow = printRange?.endRow ?? sheet.bounds.bottom;
+    const widestLabel = String(Math.max(1, lastRow));
+    fontManager.trackText(widestLabel);
+    const labelWidth = fontManager.measureText(widestLabel, resourceName, fontSize);
+    return {
+        gutterWidth: labelWidth + 2 * constants_1.HEADING_PADDING,
+        bandHeight: fontSize + 2 * constants_1.HEADING_PADDING,
+        fontSize
     };
 }
+/**
+ * Largest scale ≤ `startScale` whose real pagination lands within `target`
+ * pages, found by bisection.
+ *
+ * The caller passes a closure that re-paginates at a candidate scale, so the
+ * answer respects indivisible columns/rows, manual breaks and repeated title
+ * bands instead of trusting a total-size ratio. Returns `startScale` untouched
+ * when it already fits, so nothing is shrunk needlessly.
+ *
+ * `minScale` is the floor the result may not go below. When the target is
+ * unreachable even there — manual page breaks alone can force more pages than
+ * requested — the floor is returned and the sheet simply spans more than
+ * `target` pages, which is preferable to shrinking it into illegibility.
+ */
+function tightenToPageCount(pageCountAt, target, startScale, minScale) {
+    const start = Math.max(startScale, minScale);
+    if (pageCountAt(start) <= target || start <= minScale) {
+        return start;
+    }
+    let lo = minScale;
+    let hi = start;
+    if (pageCountAt(lo) > target) {
+        return lo;
+    }
+    // 24 halvings resolve the scale to ~6e-8 of the starting bound, far below one
+    // device pixel, and each probe is pure arithmetic over the track sizes.
+    for (let i = 0; i < 24; i++) {
+        const mid = (lo + hi) / 2;
+        if (pageCountAt(mid) <= target) {
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return lo;
+}
+/**
+ * Lay out Excel's "Comments at end of sheet" as extra pages.
+ *
+ * Each entry becomes an ordinary {@link LayoutCell} spanning the content width,
+ * so the existing page renderer draws them with no special casing — including
+ * word wrapping, which long comment bodies need. Pages are filled top to bottom
+ * and a new one starts when the next entry would overflow.
+ */
+function buildCommentPages(sheet, comments, options, fontManager) {
+    const { width: pageWidth, height: pageHeight } = pageDimensions(options);
+    const { margins } = options;
+    const headerHeight = options.showSheetNames ? constants_1.SHEET_NAME_BAND_HEIGHT : 0;
+    const footerHeight = options.showPageNumbers ? constants_1.PAGE_NUMBER_BAND_HEIGHT : 0;
+    const contentWidth = pageWidth - margins.left - margins.right;
+    const top = pageHeight - margins.top - headerHeight;
+    const bottom = margins.bottom + footerHeight;
+    const fontSize = options.defaultFontSize;
+    const resourceName = fontManager.hasEmbeddedFont()
+        ? fontManager.getEmbeddedResourceName()
+        : fontManager.ensureFont((0, font_manager_1.resolvePdfFontName)(options.defaultFontFamily, false, false));
+    const measure = (text) => fontManager.measureText(text, resourceName, fontSize);
+    const lineHeight = fontSize * constants_1.LINE_HEIGHT_FACTOR;
+    const textColor = { r: 0, g: 0, b: 0 };
+    const pages = [];
+    let cells = [];
+    let cursor = top;
+    const flush = () => {
+        if (cells.length > 0) {
+            pages.push({ ...blankPage(sheet, options), cells });
+            cells = [];
+            cursor = top;
+        }
+    };
+    const push = (text, bold) => {
+        fontManager.trackText(text);
+        const lines = (0, page_renderer_1.wrapTextLines)(text, measure, Math.max(contentWidth - 2 * constants_1.CELL_PADDING_H, 1));
+        const height = Math.max(lines.length, 1) * lineHeight + 2 * constants_1.CELL_PADDING_V;
+        if (cursor - height < bottom) {
+            flush();
+        }
+        cells.push({
+            text,
+            rect: { x: margins.left, y: cursor - height, width: contentWidth, height },
+            fontFamily: options.defaultFontFamily,
+            fontSize,
+            bold,
+            italic: false,
+            strike: false,
+            underline: false,
+            textColor,
+            fillColor: null,
+            horizontalAlign: "left",
+            verticalAlign: "top",
+            wrapText: true,
+            borders: { top: null, right: null, bottom: null, left: null },
+            borderInsets: { top: 0, right: 0, bottom: 0, left: 0 },
+            colSpan: 1,
+            rowSpan: 1,
+            hyperlink: null,
+            richText: null,
+            textRotation: 0,
+            indent: 0,
+            textOverflowWidth: 0
+        });
+        cursor -= height;
+    };
+    push(`${sheet.name} — comments`, true);
+    for (const comment of comments) {
+        const author = comment.author ? ` (${comment.author})` : "";
+        push(`${comment.ref}${author}: ${comment.text}`, false);
+    }
+    flush();
+    return pages;
+}
 /**
  * Build the LayoutPage for a single rowPage × colGroup combination.
  */
 function buildPageLayout(ctx, rowPage, colGroup, currentPageCount, sheet, options, fontManager) {
-    const { scaledColumnWidths, rowHeights, visibleRows, visibleCols, mergeMap, pageWidth, pageHeight, contentWidth, headerHeight, scaleFactor, margins } = ctx;
+    const { scaledColumnWidths, rowHeights, visibleRows, visibleCols, mergeMap, pageWidth, pageHeight, contentWidth, availableHeight, headerHeight, scaleFactor, margins, headings } = ctx;
     const cells = [];
-    // Compute column offsets for this column group
+    // The row-number gutter and column-letter band shift the grid origin right
+    // and down respectively; both are 0 when headings are not printed.
+    const gridLeft = margins.left + (headings?.gutterWidth ?? 0);
+    const gridTop = pageHeight - margins.top - headerHeight - (headings?.bandHeight ?? 0);
+    // Compute column offsets for this column group. Content starts at the left
+    // margin, matching Excel's print behaviour; it is only centered when the
+    // sheet (or the caller) asks for it via Excel's "Center on page →
+    // Horizontally" print option.
     const groupColWidths = colGroup.map(ci => scaledColumnWidths[ci]);
     const groupTotalWidth = groupColWidths.reduce((s, w) => s + w, 0);
     const groupColOffsets = [];
-    let gx = margins.left;
-    if (groupTotalWidth < contentWidth) {
-        gx = margins.left + (contentWidth - groupTotalWidth) / 2;
+    let gx = gridLeft;
+    if (options.horizontalCentered && groupTotalWidth < contentWidth) {
+        gx = gridLeft + (contentWidth - groupTotalWidth) / 2;
     }
     for (const w of groupColWidths) {
         groupColOffsets.push(gx);
         gx += w;
     }
-    // Row Y positions
+    // Row Y positions. Same rule as above for the vertical axis.
     const rowYPositions = [];
     const pageRowHeights = [];
-    let currentY = pageHeight - margins.top - headerHeight;
+    let currentY = gridTop;
+    if (options.verticalCentered) {
+        const pageTotalHeight = rowPage.reduce((sum, rowIdx) => sum + (rowHeights[rowIdx] ?? DEFAULT_ROW_HEIGHT * scaleFactor), 0);
+        if (pageTotalHeight < availableHeight) {
+            currentY -= (availableHeight - pageTotalHeight) / 2;
+        }
+    }
     for (const rowIdx of rowPage) {
         const rowH = rowHeights[rowIdx] ?? DEFAULT_ROW_HEIGHT * scaleFactor;
         rowYPositions.push(currentY);
@@ -325,6 +558,12 @@ function buildPageLayout(ctx, rowPage, colGroup, currentPageCount, sheet, option
             // Propagate merged cell borders from boundary cells
             if (mergeInfo?.isMaster) {
                 propagateMergeBorders(layoutCell, mergeInfo, wsRowNumber, wsColNumber, sheet);
+                // Propagation re-converts the boundary cell's border straight from the
+                // Excel style, bypassing the conversion in `buildLayoutCell`, so the
+                // black-and-white pass has to be reapplied to the result.
+                if (options.blackAndWhite) {
+                    layoutCell.borders = (0, style_converter_1.grayscaleBorders)(layoutCell.borders);
+                }
             }
             cellGrid.set(`${ri}:${gci}`, layoutCell);
         }
@@ -354,37 +593,101 @@ function buildPageLayout(ctx, rowPage, colGroup, currentPageCount, sheet, option
         images: [],
         charts: [],
         scaleFactor,
+        headings,
+        commentBoxes: options.cellComments === "asDisplayed"
+            ? placeCommentBoxes(sheet, colGroup.map(ci => visibleCols[ci]), groupColOffsets, groupColWidths, rowPage.map(ri => visibleRows[ri]), rowYPositions, pageRowHeights, options, scaleFactor)
+            : undefined,
         headerFooter: options.includeHeadersFooters ? sheet.headerFooter : undefined
     };
 }
-function createEmptyPage(sheet, options) {
-    let pageWidth = options.pageSize.width;
-    let pageHeight = options.pageSize.height;
-    if (options.orientation === "landscape") {
-        [pageWidth, pageHeight] = [pageHeight, pageWidth];
+/**
+ * Position each comment box on a page, for `cellComments: "asDisplayed"`.
+ *
+ * A comment is placed when its box overlaps the page's tracks. Fractional VML
+ * coordinates are interpolated against the page's own column offsets and row
+ * positions, so a box lands correctly even when the scale, hidden tracks or
+ * repeated title bands have moved the grid around. Comments whose box falls
+ * entirely outside the page are skipped, which keeps each one on a single page
+ * rather than slicing it across the seam.
+ */
+function placeCommentBoxes(sheet, sheetCols, columnOffsets, columnWidths, sheetRows, rowYPositions, rowHeights, options, scaleFactor) {
+    const comments = sheet.comments;
+    if (!comments?.length || sheetCols.length === 0 || sheetRows.length === 0) {
+        return undefined;
     }
-    return {
-        pageNumber: 1,
-        sheetPageNumber: sheet.pageSetup?.firstPageNumber ?? 1,
-        sheetPageIndex: 1,
-        sheetPageCount: 1,
-        firstPageNumber: sheet.pageSetup?.firstPageNumber,
-        options,
-        cells: [],
-        width: pageWidth,
-        height: pageHeight,
-        sheetName: sheet.name,
-        sheetCols: [],
-        columnOffsets: [],
-        columnWidths: [],
-        sheetRows: [],
-        rowYPositions: [],
-        rowHeights: [],
-        images: [],
-        charts: [],
-        scaleFactor: 1,
-        headerFooter: options.includeHeadersFooters ? sheet.headerFooter : undefined
+    // VML coordinates are 0-based; the page tracks are 1-based sheet numbers.
+    const xAt = (col) => {
+        const index = sheetCols.indexOf(Math.floor(col) + 1);
+        if (index < 0) {
+            return undefined;
+        }
+        return columnOffsets[index] + (col - Math.floor(col)) * columnWidths[index];
+    };
+    const yAt = (row) => {
+        const index = sheetRows.indexOf(Math.floor(row) + 1);
+        if (index < 0) {
+            return undefined;
+        }
+        return rowYPositions[index] - (row - Math.floor(row)) * rowHeights[index];
     };
+    const boxes = [];
+    for (const comment of comments) {
+        const anchor = comment.anchor ?? defaultCommentAnchor(comment.ref);
+        if (!anchor) {
+            continue;
+        }
+        const left = xAt(anchor.left);
+        const right = xAt(anchor.right);
+        const top = yAt(anchor.top);
+        const bottom = yAt(anchor.bottom);
+        if (left === undefined || right === undefined || top === undefined || bottom === undefined) {
+            continue;
+        }
+        const width = right - left;
+        const height = top - bottom;
+        if (width <= 0 || height <= 0) {
+            continue;
+        }
+        const cell = parseCellRef(comment.ref);
+        const markerCol = sheetCols.indexOf(cell.c + 1);
+        const markerRow = sheetRows.indexOf(cell.r + 1);
+        const author = comment.author ? `${comment.author}:\n` : "";
+        boxes.push({
+            rect: { x: left, y: bottom, width, height },
+            text: `${author}${comment.text}`,
+            fontSize: options.defaultFontSize * scaleFactor,
+            marker: markerCol >= 0 && markerRow >= 0
+                ? {
+                    x: columnOffsets[markerCol] + columnWidths[markerCol],
+                    y: rowYPositions[markerRow],
+                    size: constants_1.COMMENT_MARKER_SIZE * scaleFactor
+                }
+                : undefined
+        });
+    }
+    return boxes.length > 0 ? boxes : undefined;
+}
+/**
+ * Excel's default comment placement, used when the note carries no VML anchor.
+ *
+ * Mirrors the geometry Excel writes for a fresh comment: the box starts at the
+ * commented cell's column, two rows above it, and spans two columns by four
+ * rows.
+ */
+function defaultCommentAnchor(ref) {
+    let cell;
+    try {
+        cell = parseCellRef(ref);
+    }
+    catch {
+        return undefined;
+    }
+    const left = cell.c + 6 / 68;
+    const top = Math.max(cell.r - 2, 0) + 14 / 18;
+    return { left, top, right: left + 2, bottom: top + 4 };
+}
+function createEmptyPage(sheet, options) {
+    return blankPage(sheet, options);
 }
 /**
  * Parse a cell reference like "A1" into 0-indexed { c, r }.
@@ -448,46 +751,80 @@ function getPrintRange(sheet, options) {
 // =============================================================================
 // Column Width Computation
 // =============================================================================
-function computeColumnWidths(sheet, printRange) {
+function computeColumnWidths(sheet, printRange, titleBand) {
     const bounds = sheet.bounds;
     const hasData = bounds.top > 0 && bounds.left > 0;
     if (!hasData) {
-        return { columnWidths: [], visibleCols: [] };
+        return { columnWidths: [], visibleCols: [], repeatColIndices: [] };
     }
     const startCol = printRange?.startCol ?? bounds.left;
     const endCol = printRange?.endCol ?? bounds.right;
     const columnWidths = [];
     const visibleCols = [];
-    for (let c = startCol; c <= endCol; c++) {
+    const emitted = new Set();
+    const push = (c) => {
+        if (emitted.has(c)) {
+            return;
+        }
         const col = sheet.columns.get(c);
         if (col?.hidden) {
-            continue;
+            return;
         }
+        emitted.add(c);
         const excelWidth = col?.width ?? DEFAULT_COLUMN_WIDTH;
         const pixelWidth = (0, units_1.charWidthToPixel)(excelWidth, constants_1.MAX_DIGIT_WIDTH_PX);
         const pointWidth = Math.max(pixelWidth * constants_1.PX_TO_PT, MIN_COLUMN_WIDTH);
         columnWidths.push(pointWidth);
         visibleCols.push(c);
+    };
+    // Print titles are independent of the print area, so a band that is not
+    // fully inside it must be emitted first: it prints down the left of every
+    // page. A band wholly inside keeps the sheet's natural order, so the first
+    // page is not reshuffled — only later pages get the repeated prefix.
+    const titleFullyInside = titleBand && titleBand.first >= startCol && titleBand.last <= endCol;
+    if (titleBand && !titleFullyInside) {
+        for (let c = titleBand.first; c <= titleBand.last; c++) {
+            push(c);
+        }
     }
-    return { columnWidths, visibleCols };
+    for (let c = startCol; c <= endCol; c++) {
+        push(c);
+    }
+    const repeatColIndices = titleBand
+        ? visibleCols.flatMap((c, i) => (c >= titleBand.first && c <= titleBand.last ? [i] : []))
+        : [];
+    return { columnWidths, visibleCols, repeatColIndices };
 }
 // =============================================================================
 // Row Height Computation
 // =============================================================================
-function computeRowHeights(sheet, scaleFactor, printRange, fontManager, options) {
+/**
+ * Measure every printable row at 100% scale.
+ *
+ * Heights are deliberately unscaled: `countWrapLines` derives the wrapped line
+ * count from ratios that are independent of the print scale, so a scaled height
+ * is exactly `unscaled * scale`. Measuring once and multiplying avoids re-running
+ * the most expensive step of layout for every probe of the fit solver.
+ */
+function computeRowHeights(sheet, printRange, fontManager, options, titleBand) {
     const bounds = sheet.bounds;
     if (bounds.top <= 0) {
-        return { rowHeights: [], visibleRows: [] };
+        return { rowHeights: [], visibleRows: [], repeatRowIndices: [] };
     }
     const startRow = printRange?.startRow ?? bounds.top;
     const endRow = printRange?.endRow ?? bounds.bottom;
     const rowHeights = [];
     const visibleRows = [];
-    for (let r = startRow; r <= endRow; r++) {
+    const emitted = new Set();
+    const push = (r) => {
+        if (emitted.has(r)) {
+            return;
+        }
         const row = sheet.rows.get(r);
         if (row?.hidden) {
-            continue;
+            return;
         }
+        emitted.add(r);
         let height;
         if (row?.height && row.customHeight) {
             // Custom height explicitly set by user — use as-is
@@ -498,27 +835,41 @@ function computeRowHeights(sheet, scaleFactor, printRange, fontManager, options)
             // the row is tall enough for wrapped text.  The stored height may be
             // stale when columns are narrower in the PDF layout or when the PDF
             // uses different font metrics than the original Excel file.
-            height = Math.max(row.height, autoRowHeight(row, scaleFactor, sheet, fontManager, options));
+            height = Math.max(row.height, autoRowHeight(row, sheet, fontManager, options));
         }
         else {
             // No height info: auto-size based on cell content
-            height = autoRowHeight(row, scaleFactor, sheet, fontManager, options);
+            height = autoRowHeight(row, sheet, fontManager, options);
         }
-        rowHeights.push(height * scaleFactor);
+        rowHeights.push(height);
         visibleRows.push(r);
+    };
+    // Mirrors `computeColumnWidths`: a title band not fully inside the print area
+    // leads, otherwise the sheet's natural row order is preserved.
+    const titleFullyInside = titleBand && titleBand.first >= startRow && titleBand.last <= endRow;
+    if (titleBand && !titleFullyInside) {
+        for (let r = titleBand.first; r <= titleBand.last; r++) {
+            push(r);
+        }
     }
-    return { rowHeights, visibleRows };
+    for (let r = startRow; r <= endRow; r++) {
+        push(r);
+    }
+    const repeatRowIndices = titleBand
+        ? visibleRows.flatMap((r, i) => (r >= titleBand.first && r <= titleBand.last ? [i] : []))
+        : [];
+    return { rowHeights, visibleRows, repeatRowIndices };
 }
 /**
  * Compute the minimum row height required to display wrapped cell content.
  * Returns at least `DEFAULT_ROW_HEIGHT`.
  */
-function autoRowHeight(row, scaleFactor, sheet, fontManager, options) {
+function autoRowHeight(row, sheet, fontManager, options) {
     let height = DEFAULT_ROW_HEIGHT;
     if (row) {
         for (const cell of row.cells.values()) {
             const fontSize = getCellFontSize(cell);
-            const wrapLineCount = countWrapLines(cell, fontSize, scaleFactor, sheet, fontManager, options);
+            const wrapLineCount = countWrapLines(cell, fontSize, sheet, fontManager, options);
             const lineHeight = fontSize * constants_1.LINE_HEIGHT_FACTOR;
             // Account for border width: half of each border extends inward
             const borderTop = cell.style?.border?.top?.style
@@ -560,7 +911,7 @@ function getCellFontSize(cell) {
  * Count the wrap-line count for a cell, using actual font measurements
  * so row heights match the page renderer exactly.
  */
-function countWrapLines(cell, fontSize, scaleFactor, sheet, fontManager, options) {
+function countWrapLines(cell, fontSize, sheet, fontManager, options) {
     const text = typeof cell.text === "string" ? cell.text : String(cell.text ?? "");
     const lineCount = Math.max(1, (text.match(/\n/g) ?? []).length + 1);
     if (!cell.style?.alignment?.wrapText || text.length === 0) {
@@ -568,7 +919,7 @@ function countWrapLines(cell, fontSize, scaleFactor, sheet, fontManager, options
     }
     const col = sheet.columns.get(cell.col);
     const colWidth = col?.width ?? DEFAULT_COLUMN_WIDTH;
-    const scaledColPts = (0, units_1.charWidthToPixel)(colWidth, constants_1.MAX_DIGIT_WIDTH_PX) * constants_1.PX_TO_PT * scaleFactor;
+    const colPts = (0, units_1.charWidthToPixel)(colWidth, constants_1.MAX_DIGIT_WIDTH_PX) * constants_1.PX_TO_PT;
     const indent = cell.style.alignment.indent ?? 0;
     const borderLeft = cell.style?.border?.left?.style
         ? (0, style_converter_1.borderStyleToLineWidth)(cell.style.border.left.style) / 2
@@ -576,26 +927,27 @@ function countWrapLines(cell, fontSize, scaleFactor, sheet, fontManager, options
     const borderRight = cell.style?.border?.right?.style
         ? (0, style_converter_1.borderStyleToLineWidth)(cell.style.border.right.style) / 2
         : 0;
+    // Width, padding and font size are all unscaled here, which is what makes the
+    // wrapped line count independent of the print scale.
     const padding = constants_1.CELL_PADDING_H + borderLeft + (constants_1.CELL_PADDING_H + borderRight) + indent * constants_1.INDENT_WIDTH;
-    const effectiveWidth = Math.max(scaledColPts - padding, 1);
+    const effectiveWidth = Math.max(colPts - padding, 1);
     // For rich text cells, use per-run font size measurement to match rendering
     if (cell.type === types_1.PdfCellType.RichText) {
         const value = cell.value;
         if (value && typeof value === "object" && "richText" in value) {
             const runs = value.richText;
             if (runs.length > 0) {
-                const wrappedCount = countRichTextWrapLines(text, runs, scaleFactor, effectiveWidth, fontManager, options, cell.style?.font);
+                const wrappedCount = countRichTextWrapLines(text, runs, effectiveWidth, fontManager, options, cell.style?.font);
                 return Math.max(lineCount, wrappedCount);
             }
         }
     }
-    const scaledFontSize = fontSize * scaleFactor;
     const fontProps = (0, style_converter_1.extractFontProperties)(cell.style.font, options.defaultFontFamily, options.defaultFontSize);
     const pdfFontName = (0, font_manager_1.resolvePdfFontName)(fontProps.fontFamily, fontProps.bold, fontProps.italic);
     const resourceName = fontManager.hasEmbeddedFont()
         ? fontManager.getEmbeddedResourceName()
         : fontManager.ensureFont(pdfFontName);
-    const measure = (s) => fontManager.measureText(s, resourceName, scaledFontSize);
+    const measure = (s) => fontManager.measureText(s, resourceName, fontSize);
     const wrappedLines = (0, page_renderer_1.wrapTextLines)(text, measure, effectiveWidth);
     return Math.max(lineCount, wrappedLines.length);
 }
@@ -604,7 +956,7 @@ function countWrapLines(cell, fontSize, scaleFactor, sheet, fontManager, options
  * This mirrors the logic in wrapRichTextLines (page-renderer) so that
  * the row height calculation matches the actual rendering.
  */
-function countRichTextWrapLines(text, runs, scaleFactor, effectiveWidth, fontManager, options, cellFont) {
+function countRichTextWrapLines(text, runs, effectiveWidth, fontManager, options, cellFont) {
     // Use cell-level font as fallback for runs without their own font
     const defaultFamily = cellFont?.name ?? options.defaultFontFamily;
     const defaultSize = cellFont?.size ?? options.defaultFontSize;
@@ -645,7 +997,7 @@ function countRichTextWrapLines(text, runs, scaleFactor, effectiveWidth, fontMan
             }
             : cellFont;
         const fontProps = (0, style_converter_1.extractFontProperties)(effectiveRunFont, defaultFamily, defaultSize);
-        return fontProps.fontSize * scaleFactor;
+        return fontProps.fontSize;
     });
     // Measure a range of fullText using per-character run font sizes
     const measureRange = (start, end) => {
@@ -738,24 +1090,26 @@ function countRichTextWrapLines(text, runs, scaleFactor, effectiveWidth, fontMan
 // Row Breaks
 // =============================================================================
 /**
- * Build a set of visible-row indices where manual page breaks occur.
+ * Translate manual break positions from sheet track numbers into indices of the
+ * printed track list.
+ *
+ * A break sits *after* its track, so the following index starts a new page.
+ * Shared by both axes; computed once per sheet because the fit solver paginates
+ * many times and must not rebuild the lookup on every probe.
  */
-function buildRowBreakSet(sheet, visibleRows) {
+function buildBreakSet(breakTracks, visibleTracks) {
     const breaks = new Set();
-    const rowBreaks = sheet.rowBreaks ?? [];
-    if (rowBreaks.length === 0) {
+    if (breakTracks.length === 0) {
         return breaks;
     }
-    // Map row numbers to visible-row indices
-    const rowToIndex = new Map();
-    for (let i = 0; i < visibleRows.length; i++) {
-        rowToIndex.set(visibleRows[i], i);
+    const trackToIndex = new Map();
+    for (let i = 0; i < visibleTracks.length; i++) {
+        trackToIndex.set(visibleTracks[i], i);
     }
-    for (const brk of rowBreaks) {
-        const idx = rowToIndex.get(brk);
-        if (idx !== undefined) {
-            // Break AFTER this row, so the next row starts a new page
-            breaks.add(idx + 1);
+    for (const track of breakTracks) {
+        const index = trackToIndex.get(track);
+        if (index !== undefined) {
+            breaks.add(index + 1);
         }
     }
     return breaks;
@@ -793,115 +1147,100 @@ function buildMergeMap(sheet) {
 // =============================================================================
 // Pagination
 // =============================================================================
-function paginateRows(rowHeights, availableHeight, repeatRowCount, rowBreaks) {
-    if (rowHeights.length === 0) {
+/**
+ * Split a track list (rows or columns) into pages.
+ *
+ * One implementation serves both axes: heights against the available page
+ * height, widths against the content width. The axes differ only in the overflow
+ * tolerance, so `epsilon` is the sole parameter that distinguishes them —
+ * columns need a small slack because scaled point widths accumulate rounding.
+ *
+ * `repeatIndices` are the tracks of a print-title band. They are re-emitted at
+ * the start of every page after the first, which is why they are absolute
+ * indices rather than a count: a band may sit in the middle of the printed range
+ * (Excel allows `printTitlesColumn = "C:D"`).
+ *
+ * Manual breaks are honoured via `breaks`, holding the index that must start a
+ * new page.
+ */
+function paginateTracks(sizes, available, repeatIndices, breaks, epsilon = 0) {
+    if (sizes.length === 0) {
         return [[]];
     }
     const pages = [];
-    let currentPage = [];
-    let currentPageHeight = 0;
+    let current = [];
+    let used = 0;
     let isFirstPage = true;
     let repeatedPrefixCount = 0;
-    const addRepeatRows = () => {
+    const repeatSet = new Set(repeatIndices);
+    const addRepeats = () => {
         repeatedPrefixCount = 0;
-        for (let h = 0; h < repeatRowCount && h < rowHeights.length; h++) {
-            if (currentPageHeight + rowHeights[h] > availableHeight && currentPage.length > 0) {
+        for (const index of repeatIndices) {
+            if (index >= sizes.length) {
+                continue;
+            }
+            if (used + sizes[index] > available + epsilon && current.length > 0) {
                 break;
             }
-            currentPage.push(h);
-            currentPageHeight += rowHeights[h];
+            current.push(index);
+            used += sizes[index];
             repeatedPrefixCount++;
         }
     };
-    for (let i = 0; i < rowHeights.length; i++) {
-        const rowHeight = rowHeights[i];
-        const pageAvailable = availableHeight;
-        let skipRepeatedRow = false;
-        while (true) {
-            // Force page break at row break positions, or when content overflows
-            const forceBreak = rowBreaks.has(i) && currentPage.length > 0;
-            if ((forceBreak || currentPageHeight + rowHeight > pageAvailable) && currentPage.length > 0) {
-                const pageHasOnlyRepeatRows = !forceBreak &&
-                    !isFirstPage &&
-                    currentPage.length > 0 &&
-                    currentPage.length === repeatedPrefixCount;
-                if (pageHasOnlyRepeatRows) {
-                    currentPage = [];
-                    currentPageHeight = 0;
+    for (let i = 0; i < sizes.length; i++) {
+        const size = sizes[i];
+        // A manual break at `i` must fire at most once. Without this latch the break
+        // stays true after the repeated title tracks are re-added, so the loop keeps
+        // flushing title-only pages forever (heap exhaustion).
+        let breakConsumed = false;
+        for (;;) {
+            const forceBreak = !breakConsumed && breaks.has(i) && current.length > 0;
+            if ((forceBreak || used + size > available + epsilon) && current.length > 0) {
+                if (forceBreak) {
+                    breakConsumed = true;
+                }
+                // Never emit a page holding nothing but the repeated prefix.
+                if (!forceBreak && !isFirstPage && current.length === repeatedPrefixCount) {
+                    current = [];
+                    used = 0;
                     repeatedPrefixCount = 0;
                     continue;
                 }
-                pages.push(currentPage);
-                currentPage = [];
-                currentPageHeight = 0;
+                pages.push(current);
+                current = [];
+                used = 0;
                 repeatedPrefixCount = 0;
                 isFirstPage = false;
-                addRepeatRows();
+                addRepeats();
                 continue;
             }
-            if (!isFirstPage && i < repeatRowCount && currentPage.includes(i)) {
-                skipRepeatedRow = true;
-                break;
+            if (isFirstPage || !repeatSet.has(i) || !current.includes(i)) {
+                current.push(i);
+                used += size;
             }
-            currentPage.push(i);
-            currentPageHeight += rowHeight;
             break;
         }
-        if (skipRepeatedRow) {
-            continue;
-        }
     }
-    if (currentPage.length > 0) {
-        pages.push(currentPage);
+    if (current.length > 0) {
+        pages.push(current);
     }
-    return pages.length > 0 ? pages : [[]];
+    return pages;
 }
 /**
- * Split columns into groups for horizontal pagination.
+ * Row pagination. Thin wrapper over {@link paginateTracks} that also accepts a
+ * plain count, which reads better in the focused unit tests.
  */
-function paginateColumns(columnWidths, contentWidth, sheet, visibleCols) {
-    if (columnWidths.length === 0) {
-        return [[]];
-    }
-    // Build col break set (indices into visibleCols)
-    const colBreaks = new Set();
-    const wsColBreaks = sheet.colBreaks ?? [];
-    if (wsColBreaks.length > 0) {
-        const colToIndex = new Map();
-        for (let i = 0; i < visibleCols.length; i++) {
-            colToIndex.set(visibleCols[i], i);
-        }
-        for (const brk of wsColBreaks) {
-            const idx = colToIndex.get(brk);
-            if (idx !== undefined) {
-                colBreaks.add(idx + 1);
-            }
-        }
-    }
-    const groups = [];
-    let currentGroup = [];
-    let currentWidth = 0;
-    for (let i = 0; i < columnWidths.length; i++) {
-        const colWidth = columnWidths[i];
-        const forceBreak = colBreaks.has(i) && currentGroup.length > 0;
-        if ((forceBreak || currentWidth + colWidth > contentWidth + 0.01) && currentGroup.length > 0) {
-            groups.push(currentGroup);
-            currentGroup = [];
-            currentWidth = 0;
-        }
-        currentGroup.push(i);
-        currentWidth += colWidth;
-    }
-    if (currentGroup.length > 0) {
-        groups.push(currentGroup);
-    }
-    return groups.length > 0 ? groups : [Array.from({ length: columnWidths.length }, (_, i) => i)];
+function paginateRows(rowHeights, availableHeight, repeatRows, rowBreaks) {
+    const repeatIndices = Array.isArray(repeatRows)
+        ? repeatRows
+        : Array.from({ length: Math.max(0, repeatRows) }, (_, i) => i);
+    return paginateTracks(rowHeights, availableHeight, repeatIndices, rowBreaks);
 }
 // =============================================================================
 // Cell Layout
 // =============================================================================
 function buildLayoutCell(cell, x, y, width, height, colSpan, rowSpan, options, fontManager, scaleFactor) {
-    const text = cell?.text ?? "";
+    const text = resolveErrorText(cell, options.errors);
     const style = cell?.style ?? {};
     const fontProps = (0, style_converter_1.extractFontProperties)(style.font, options.defaultFontFamily, options.defaultFontSize);
     // Scale font size proportionally when fitToPage shrinks the layout
@@ -920,7 +1259,9 @@ function buildLayoutCell(cell, x, y, width, height, colSpan, rowSpan, options, f
     // their own font definition (e.g. the first run often has no font object
     // and should inherit the cell's style font including bold/italic).
     const richText = buildRichTextRuns(cell, options, fontManager, scaleFactor, style.font);
-    const borders = (0, style_converter_1.excelBordersToPdf)(style.border);
+    const rawBorders = (0, style_converter_1.excelBordersToPdf)(style.border);
+    const borders = options.blackAndWhite ? (0, style_converter_1.grayscaleBorders)(rawBorders) : rawBorders;
+    const rawFill = (0, style_converter_1.excelFillToPdfColor)(style.fill);
     return {
         text,
         rect: { x, y, width, height },
@@ -930,8 +1271,8 @@ function buildLayoutCell(cell, x, y, width, height, colSpan, rowSpan, options, f
         italic: fontProps.italic,
         strike: fontProps.strike,
         underline: fontProps.underline,
-        textColor: fontProps.textColor,
-        fillColor: (0, style_converter_1.excelFillToPdfColor)(style.fill),
+        textColor: options.blackAndWhite ? (0, style_converter_1.toGrayscale)(fontProps.textColor) : fontProps.textColor,
+        fillColor: options.blackAndWhite && rawFill !== null ? (0, style_converter_1.toGrayscale)(rawFill) : rawFill,
         horizontalAlign: resolveHorizontalAlign(style.alignment, cell?.type, cell?.result),
         verticalAlign: (0, style_converter_1.excelVAlignToPdf)(style.alignment),
         wrapText: style.alignment?.wrapText ?? false,
@@ -1042,7 +1383,7 @@ function resolveSharedBorders(cellGrid, rowCount, colCount) {
  *  - `br` — when present — locates the opposite corner, so the rect size is
  *    the difference.
  *  - `ext` — when present — overrides the size directly. Images use pixels
- *    (px × 0.75 = pt); charts use EMU (EMU / 9525 = pt). The `extUnit`
+ *    (px × 0.75 = pt); charts use EMU (EMU / 12700 = pt). The `extUnit`
  *    field disambiguates. Historical callers that omit `extUnit` keep
  *    the legacy px behaviour.
  *
@@ -1063,7 +1404,7 @@ function resolveAnchorRect(range, layoutPages, scaleFactor) {
     const baseY = targetPage.rowYPositions[pageRowIndex] ??
         targetPage.height -
             targetPage.options.margins.top -
-            (targetPage.options.showSheetNames ? 20 : 0);
+            (targetPage.options.showSheetNames ? constants_1.SHEET_NAME_BAND_HEIGHT : 0);
     // Apply sub-cell offsets, scaled to match page layout.
     const tlColOff = ((0, units_1.emuToPt)(tl.nativeColOff ?? 0) || 0) * scaleFactor;
     const tlRowOff = ((0, units_1.emuToPt)(tl.nativeRowOff ?? 0) || 0) * scaleFactor;
@@ -1075,9 +1416,11 @@ function resolveAnchorRect(range, layoutPages, scaleFactor) {
     const extUnit = range.extUnit ?? "px";
     if (range.ext) {
         if (extUnit === "emu") {
-            // EMU → px (the Excel drawing ext.cx/cy convention at 96 DPI).
-            width = (0, units_1.emuToPx)(range.ext.width) * scaleFactor;
-            height = (0, units_1.emuToPx)(range.ext.height) * scaleFactor;
+            // EMU → pt (÷12700). Using the px factor (÷9525) here rendered every
+            // EMU-sized chart 4/3 too large: a 4in chart came out 384pt instead of
+            // 288pt, overflowing the content area and skewing its aspect ratio.
+            width = (0, units_1.emuToPt)(range.ext.width) * scaleFactor;
+            height = (0, units_1.emuToPt)(range.ext.height) * scaleFactor;
         }
         else {
             // Legacy pixel → pt (0.75 factor = 72/96 dpi)
@@ -1234,13 +1577,20 @@ function assignChartsToPages(charts, layoutPages, scaleFactor) {
         // is near a page break: rather than clipping them to a sliver, we
         // push them onto the following page at full size.
         const tl = chart.range.tl;
+        const tlCol = (tl.nativeCol ?? tl.col ?? 0) + 1;
         const tlRow = (tl.nativeRow ?? tl.row ?? 0) + 1;
+        // Restrict the search to the column band that holds the anchor, then walk
+        // it in row order. Filtering before stepping keeps the result independent
+        // of `pageOrder`: that setting decides the array order, but "the next page
+        // down" is always the next row band within the same column band.
+        const band = layoutPages.filter(page => page.sheetCols.includes(tlCol));
+        const ordered = (band.length > 0 ? band : [...layoutPages]).sort((a, b) => (a.sheetRows[0] ?? 0) - (b.sheetRows[0] ?? 0));
         let targetPage;
-        for (let pi = 0; pi < layoutPages.length; pi++) {
-            const page = layoutPages[pi];
+        for (let pi = 0; pi < ordered.length; pi++) {
+            const page = ordered[pi];
             const lastPageRow = page.sheetRows[page.sheetRows.length - 1] ?? 0;
-            if (lastPageRow >= tlRow - 1 && pi + 1 < layoutPages.length) {
-                targetPage = layoutPages[pi + 1];
+            if (lastPageRow >= tlRow - 1 && pi + 1 < ordered.length) {
+                targetPage = ordered[pi + 1];
                 break;
             }
             if (lastPageRow >= tlRow) {
@@ -1249,11 +1599,11 @@ function assignChartsToPages(charts, layoutPages, scaleFactor) {
             }
         }
         if (!targetPage) {
-            targetPage = layoutPages[layoutPages.length - 1];
+            targetPage = ordered[ordered.length - 1];
         }
         if (targetPage) {
             const margins = targetPage.options.margins;
-            const headerH = targetPage.options.showSheetNames ? 20 : 0;
+            const headerH = targetPage.options.showSheetNames ? constants_1.SHEET_NAME_BAND_HEIGHT : 0;
             const contentX = margins.left;
             const contentY = margins.bottom;
             const contentW = targetPage.width - margins.left - margins.right;
@@ -1448,7 +1798,38 @@ function buildRichTextRuns(cell, options, fontManager, scaleFactor, cellFont) {
             italic: fontProps.italic,
             strike: fontProps.strike,
             underline: fontProps.underline,
-            textColor: fontProps.textColor
+            textColor: options.blackAndWhite ? (0, style_converter_1.toGrayscale)(fontProps.textColor) : fontProps.textColor
         };
     });
 }
+/**
+ * Apply Excel's "Cell errors as" print option to a cell's display text.
+ *
+ * Error values reach the PDF model in two shapes: a plain error cell
+ * (`PdfCellType.Error`) and a formula whose computed result is an error
+ * (`PdfCellType.Formula` with an `{ error }` result). Both must be substituted.
+ */
+function resolveErrorText(cell, mode) {
+    const text = cell?.text ?? "";
+    if (mode === "displayed" || !cell) {
+        return text;
+    }
+    const isError = cell.type === types_1.PdfCellType.Error ||
+        (cell.type === types_1.PdfCellType.Formula &&
+            typeof cell.result === "object" &&
+            cell.result !== null &&
+            "error" in cell.result);
+    if (!isError) {
+        return text;
+    }
+    switch (mode) {
+        case "blank":
+            return "";
+        case "dash":
+            return "--";
+        case "NA":
+            return "#N/A";
+        default:
+            return text;
+    }
+}