@cj-tech-master/excelts 9.0.0 → 9.1.0

package/dist/browser/modules/excel/xlsx/xform/drawing/blip-xform.js

@@ -8,12 +8,23 @@ class BlipXform extends BaseXform {
         return "a:blip";
     }
     render(xmlStream, model) {
-        xmlStream.leafNode(this.tag, {
-            "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
-            "r:embed": model.rId,
-            cstate: "print"
-        });
-        // TODO: handle children (e.g. a:extLst=>a:ext=>a14:useLocalDpi
+        if (model.alphaModFix !== undefined && model.alphaModFix < 100000) {
+            // Render as open/close node with a:alphaModFix child
+            xmlStream.openNode(this.tag, {
+                "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+                "r:embed": model.rId,
+                cstate: "print"
+            });
+            xmlStream.leafNode("a:alphaModFix", { amt: String(model.alphaModFix) });
+            xmlStream.closeNode();
+        }
+        else {
+            xmlStream.leafNode(this.tag, {
+                "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+                "r:embed": model.rId,
+                cstate: "print"
+            });
+        }
     }
     parseOpen(node) {
         switch (node.name) {
@@ -22,6 +33,11 @@ class BlipXform extends BaseXform {
                     rId: node.attributes["r:embed"]
                 };
                 return true;
+            case "a:alphaModFix":
+                if (node.attributes.amt) {
+                    this.model.alphaModFix = parseInt(node.attributes.amt, 10);
+                }
+                return true;
             default:
                 return true;
         }

package/dist/browser/modules/excel/xlsx/xform/drawing/pic-xform.d.ts

@@ -1,6 +1,9 @@
 import { BaseXform } from "../base-xform.js";
 interface PicModel {
     index?: number;
+    rId?: string;
+    /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
+    alphaModFix?: number;
     [key: string]: any;
 }
 declare class PicXform extends BaseXform {

package/dist/browser/modules/excel/xlsx/xform/drawing/pic-xform.js

@@ -21,7 +21,11 @@ class PicXform extends BaseXform {
     render(xmlStream, model) {
         xmlStream.openNode(this.tag);
         this.map["xdr:nvPicPr"].render(xmlStream, model);
-        this.map["xdr:blipFill"].render(xmlStream, model);
+        // Pass alphaModFix through to blipFill → blip
+        this.map["xdr:blipFill"].render(xmlStream, {
+            rId: model.rId,
+            alphaModFix: model.alphaModFix
+        });
         this.map["xdr:spPr"].render(xmlStream, model);
         xmlStream.closeNode();
     }

package/dist/browser/modules/excel/xlsx/xform/drawing/vml-drawing-xform.d.ts

@@ -9,11 +9,22 @@ import { type FormCheckboxModel } from "../../../form-control.js";
  *
  * This unified xform renders both into a single VML file.
  */
+/** Header/footer image model for VML rendering. */
+interface VmlHeaderImageModel {
+    /** rId referencing the image in the VML drawing's .rels */
+    imageRelId: string;
+    /** Image width in points */
+    width?: number;
+    /** Image height in points */
+    height?: number;
+}
 interface VmlDrawingModel {
     /** Comment/note shapes */
     comments?: any[];
     /** Form control checkboxes */
     formControls?: FormCheckboxModel[];
+    /** Header/footer image (for watermark in header mode) */
+    headerImage?: VmlHeaderImageModel;
 }
 declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
     map: {
@@ -26,6 +37,10 @@ declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
      * Render VML drawing containing both notes and form controls
      */
     render(xmlStream: any, model?: VmlDrawingModel): void;
+    /**
+     * Render a header/footer image shape for watermark
+     */
+    private _renderHeaderImageShape;
     /**
      * Render a checkbox form control shape
      */
@@ -33,6 +48,10 @@ declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
     parseOpen(node: any): boolean;
     parseText(text: string): void;
     parseClose(name: string): boolean;
+    private _parsingHeaderImage;
+    private _headerImageRelId?;
+    private _headerImageWidth?;
+    private _headerImageHeight?;
     static DRAWING_ATTRIBUTES: {
         "xmlns:v": string;
         "xmlns:o": string;

package/dist/browser/modules/excel/xlsx/xform/drawing/vml-drawing-xform.js

@@ -5,6 +5,8 @@ import { FormCheckbox } from "../../../form-control.js";
 class VmlDrawingXform extends BaseXform {
     constructor() {
         super();
+        // Internal state for parsing header image shapes
+        this._parsingHeaderImage = false;
         this.map = {
             "v:shape": new VmlShapeXform()
         };
@@ -20,8 +22,10 @@ class VmlDrawingXform extends BaseXform {
         const renderModel = (model || this.model);
         const comments = renderModel.comments;
         const formControls = renderModel.formControls;
+        const headerImage = renderModel.headerImage;
         const hasComments = comments && comments.length > 0;
         const hasFormControls = formControls && formControls.length > 0;
+        const hasHeaderImage = !!headerImage;
         xmlStream.openXml(StdDocAttributes);
         xmlStream.openNode(this.tag, VmlDrawingXform.DRAWING_ATTRIBUTES);
         // Shape layout - shared by both notes and form controls
@@ -59,6 +63,40 @@ class VmlDrawingXform extends BaseXform {
             xmlStream.leafNode("o:lock", { "v:ext": "edit", shapetype: "t" });
             xmlStream.closeNode();
         }
+        // Shapetype 75 for header/footer image (watermark)
+        if (hasHeaderImage) {
+            xmlStream.openNode("v:shapetype", {
+                id: "_x0000_t75",
+                coordsize: "21600,21600",
+                "o:spt": "75",
+                "o:preferrelative": "t",
+                path: "m@4@5l@4@11@9@11@9@5xe",
+                filled: "f",
+                stroked: "f"
+            });
+            xmlStream.leafNode("v:stroke", { joinstyle: "miter" });
+            xmlStream.openNode("v:formulas");
+            xmlStream.leafNode("v:f", { eqn: "if lineDrawn pixelLineWidth 0" });
+            xmlStream.leafNode("v:f", { eqn: "sum @0 1 0" });
+            xmlStream.leafNode("v:f", { eqn: "sum 0 0 @1" });
+            xmlStream.leafNode("v:f", { eqn: "prod @2 1 2" });
+            xmlStream.leafNode("v:f", { eqn: "prod @3 21600 pixelWidth" });
+            xmlStream.leafNode("v:f", { eqn: "prod @3 21600 pixelHeight" });
+            xmlStream.leafNode("v:f", { eqn: "sum @0 0 1" });
+            xmlStream.leafNode("v:f", { eqn: "prod @6 1 2" });
+            xmlStream.leafNode("v:f", { eqn: "prod @7 21600 pixelWidth" });
+            xmlStream.leafNode("v:f", { eqn: "sum @8 21600 0" });
+            xmlStream.leafNode("v:f", { eqn: "prod @7 21600 pixelHeight" });
+            xmlStream.leafNode("v:f", { eqn: "sum @10 21600 0" });
+            xmlStream.closeNode(); // v:formulas
+            xmlStream.leafNode("v:path", {
+                "o:extrusionok": "f",
+                gradientshapeok: "t",
+                "o:connecttype": "rect"
+            });
+            xmlStream.leafNode("o:lock", { "v:ext": "edit", aspectratio: "t" });
+            xmlStream.closeNode(); // v:shapetype
+        }
         // Render comment shapes
         if (hasComments) {
             for (let i = 0; i < comments.length; i++) {
@@ -71,8 +109,32 @@ class VmlDrawingXform extends BaseXform {
                 this._renderCheckboxShape(xmlStream, control);
             }
         }
+        // Render header/footer image shape
+        if (hasHeaderImage) {
+            this._renderHeaderImageShape(xmlStream, headerImage);
+        }
         xmlStream.closeNode();
     }
+    /**
+     * Render a header/footer image shape for watermark
+     */
+    _renderHeaderImageShape(xmlStream, headerImage) {
+        const width = headerImage.width ?? 467.25;
+        const height = headerImage.height ?? 311.25;
+        // CH = Center Header, used by Excel for center-positioned header images
+        xmlStream.openNode("v:shape", {
+            id: "CH",
+            "o:spid": "_x0000_s2049",
+            type: "#_x0000_t75",
+            style: `position:absolute;margin-left:0;margin-top:0;width:${width}pt;height:${height}pt;z-index:1`
+        });
+        xmlStream.leafNode("v:imagedata", {
+            "o:relid": headerImage.imageRelId,
+            "o:title": "watermark"
+        });
+        xmlStream.leafNode("o:lock", { "v:ext": "edit", rotation: "t" });
+        xmlStream.closeNode(); // v:shape
+    }
     /**
      * Render a checkbox form control shape
      */
@@ -141,7 +203,7 @@ class VmlDrawingXform extends BaseXform {
         xmlStream.closeNode(); // x:ClientData
         xmlStream.closeNode(); // v:shape
     }
-    // Parsing - delegate to VmlShapeXform for notes
+    // Parsing - delegate to VmlShapeXform for notes, handle header images directly
     parseOpen(node) {
         if (this.parser) {
             this.parser.parseOpen(node);
@@ -155,10 +217,34 @@ class VmlDrawingXform extends BaseXform {
                     formControls: []
                 };
                 break;
+            case "v:shape":
+                // Check if this is a header image shape (type="#_x0000_t75")
+                if (node.attributes.type === "#_x0000_t75") {
+                    this._parsingHeaderImage = true;
+                    // Extract width/height from style
+                    const style = node.attributes.style || "";
+                    const widthMatch = /width:([0-9.]+)pt/.exec(style);
+                    const heightMatch = /height:([0-9.]+)pt/.exec(style);
+                    this._headerImageWidth = widthMatch ? parseFloat(widthMatch[1]) : undefined;
+                    this._headerImageHeight = heightMatch ? parseFloat(heightMatch[1]) : undefined;
+                }
+                else {
+                    // Regular shape — delegate to VmlShapeXform (comments)
+                    this.parser = this.map[node.name];
+                    if (this.parser) {
+                        this.parser.parseOpen(node);
+                    }
+                }
+                break;
             default:
-                this.parser = this.map[node.name];
-                if (this.parser) {
-                    this.parser.parseOpen(node);
+                if (this._parsingHeaderImage && node.name === "v:imagedata") {
+                    this._headerImageRelId = node.attributes["o:relid"];
+                }
+                else {
+                    this.parser = this.map[node.name];
+                    if (this.parser) {
+                        this.parser.parseOpen(node);
+                    }
                 }
                 break;
         }
@@ -178,6 +264,19 @@ class VmlDrawingXform extends BaseXform {
             return true;
         }
         switch (name) {
+            case "v:shape":
+                if (this._parsingHeaderImage && this._headerImageRelId) {
+                    this.model.headerImage = {
+                        imageRelId: this._headerImageRelId,
+                        width: this._headerImageWidth,
+                        height: this._headerImageHeight
+                    };
+                }
+                this._parsingHeaderImage = false;
+                this._headerImageRelId = undefined;
+                this._headerImageWidth = undefined;
+                this._headerImageHeight = undefined;
+                return true;
             case this.tag:
                 return false;
             default:

package/dist/browser/modules/excel/xlsx/xform/sheet/worksheet-xform.js

@@ -26,7 +26,7 @@ import { ColBreaksXform } from "./col-breaks-xform.js";
 import { HeaderFooterXform } from "./header-footer-xform.js";
 import { ConditionalFormattingsXform } from "./cf/conditional-formattings-xform.js";
 import { ExtLstXform } from "./ext-lst-xform.js";
-import { commentsRelTargetFromWorksheet, ctrlPropRelTargetFromWorksheet, drawingRelTargetFromWorksheet, pivotTableRelTargetFromWorksheet, tableRelTargetFromWorksheet, vmlDrawingRelTargetFromWorksheet } from "../../../utils/ooxml-paths.js";
+import { commentsRelTargetFromWorksheet, ctrlPropRelTargetFromWorksheet, drawingRelTargetFromWorksheet, pivotTableRelTargetFromWorksheet, tableRelTargetFromWorksheet, vmlDrawingRelTargetFromWorksheet, vmlDrawingHFRelTargetFromWorksheet } from "../../../utils/ooxml-paths.js";
 import { buildDrawingAnchorsAndRels, resolveMediaTarget } from "../../../utils/drawing-utils.js";
 const mergeRule = (rule, extRule) => {
     Object.keys(extRule).forEach(key => {
@@ -232,6 +232,8 @@ class WorkSheetXform extends BaseXform {
         // Process background and image media entries
         const backgroundMedia = [];
         const imageMedia = [];
+        const watermarkMedia = [];
+        const headerImageMedia = [];
         model.media.forEach(medium => {
             if (medium.type === "background") {
                 backgroundMedia.push(medium);
@@ -239,6 +241,12 @@ class WorkSheetXform extends BaseXform {
             else if (medium.type === "image") {
                 imageMedia.push(medium);
             }
+            else if (medium.type === "watermark") {
+                watermarkMedia.push(medium);
+            }
+            else if (medium.type === "headerImage") {
+                headerImageMedia.push(medium);
+            }
         });
         // Handle background images
         backgroundMedia.forEach(medium => {
@@ -276,6 +284,107 @@ class WorkSheetXform extends BaseXform {
             drawing.anchors.push(...result.anchors);
             drawing.rels = result.rels;
         }
+        // Handle watermark overlay images — placed as a full-sheet drawing with transparency
+        if (watermarkMedia.length > 0) {
+            let { drawing } = model;
+            if (!drawing) {
+                drawing = model.drawing = {
+                    rId: nextRid(rels),
+                    name: `drawing${++options.drawingsCount}`,
+                    anchors: [],
+                    rels: []
+                };
+                options.drawings.push(drawing);
+                rels.push({
+                    Id: drawing.rId,
+                    Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
+                    Target: drawingRelTargetFromWorksheet(drawing.name)
+                });
+            }
+            for (const medium of watermarkMedia) {
+                const bookImage = options.media[medium.imageId];
+                if (!bookImage) {
+                    continue;
+                }
+                const rIdImage = nextRid(drawing.rels);
+                drawing.rels.push({
+                    Id: rIdImage,
+                    Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+                    Target: resolveMediaTarget(bookImage)
+                });
+                // Convert opacity (0-1) to OOXML percentage (0-100000), clamped
+                const rawOpacity = medium.opacity !== undefined ? medium.opacity : 0.15;
+                const clampedOpacity = Math.max(0, Math.min(1, rawOpacity));
+                const alphaModFix = Math.round(clampedOpacity * 100000);
+                // Compute coverage based on actual worksheet dimensions.
+                // Use the model's dimensions if available, otherwise use generous defaults.
+                const dims = model.dimensions;
+                const maxCol = dims ? Math.max(dims.model?.right ?? 100, 100) : 100;
+                const maxRow = dims ? Math.max(dims.model?.bottom ?? 200, 200) : 200;
+                drawing.anchors.push({
+                    picture: {
+                        rId: rIdImage,
+                        alphaModFix
+                    },
+                    // Cover the full data area with extra margin
+                    range: {
+                        editAs: "absolute",
+                        tl: { nativeCol: 0, nativeColOff: 0, nativeRow: 0, nativeRowOff: 0 },
+                        br: { nativeCol: maxCol, nativeColOff: 0, nativeRow: maxRow, nativeRowOff: 0 }
+                    }
+                });
+            }
+        }
+        // Handle header watermark images — VML header/footer image
+        if (headerImageMedia.length > 0) {
+            const medium = headerImageMedia[0]; // Only one header image per sheet
+            const bookImage = options.media[medium.imageId];
+            if (bookImage) {
+                const rIdVml = nextRid(rels);
+                rels.push({
+                    Id: rIdVml,
+                    Type: RelType.VmlDrawing,
+                    Target: vmlDrawingHFRelTargetFromWorksheet(fileIndex)
+                });
+                // Store header image info on the model for the VML writer and worksheet render
+                model.headerImage = {
+                    vmlRelId: rIdVml,
+                    imageId: medium.imageId,
+                    bookImage,
+                    headerWidth: medium.headerWidth,
+                    headerHeight: medium.headerHeight
+                };
+                // Flag for content-types registration
+                options.hasHeaderWatermark = true;
+                // Update headerFooter to include &G placeholder.
+                // Respects the applyTo option: "all" (default), "odd", "even", "first".
+                if (!model.headerFooter) {
+                    model.headerFooter = {};
+                }
+                const applyTo = medium.applyTo || "all";
+                const insertG = (field) => {
+                    const existing = model.headerFooter[field] || "";
+                    if (existing.includes("&G")) {
+                        return existing;
+                    }
+                    if (existing.includes("&C")) {
+                        return existing.replace("&C", "&C&G");
+                    }
+                    return existing + "&C&G";
+                };
+                if (applyTo === "all" || applyTo === "odd") {
+                    model.headerFooter.oddHeader = insertG("oddHeader");
+                }
+                if (applyTo === "all" || applyTo === "even") {
+                    model.headerFooter.evenHeader = insertG("evenHeader");
+                    model.headerFooter.differentOddEven = true;
+                }
+                if (applyTo === "all" || applyTo === "first") {
+                    model.headerFooter.firstHeader = insertG("firstHeader");
+                    model.headerFooter.differentFirst = true;
+                }
+            }
+        }
         // prepare tables
         model.tables.forEach(table => {
             // relationships
@@ -436,10 +545,18 @@ class WorkSheetXform extends BaseXform {
             // NOTE: Excel is picky about worksheet child element order; legacyDrawing must come before controls.
             model.rels.forEach(rel => {
                 if (rel.Type === RelType.VmlDrawing) {
+                    // Skip VML rels that are for header images (they use legacyDrawingHF instead)
+                    if (model.headerImage && rel.Id === model.headerImage.vmlRelId) {
+                        return;
+                    }
                     xmlStream.leafNode("legacyDrawing", { "r:id": rel.Id });
                 }
             });
         }
+        // legacyDrawingHF — VML drawing for header/footer images (watermark in header mode)
+        if (model.headerImage) {
+            xmlStream.leafNode("legacyDrawingHF", { "r:id": model.headerImage.vmlRelId });
+        }
         // Controls section for legacy form controls (checkboxes, etc.)
         // Excel expects <controls> entries that reference ctrlProp relationships.
         if (model.formControls && model.formControls.length > 0) {
@@ -655,13 +772,23 @@ class WorkSheetXform extends BaseXform {
                         // Also extract images to model.media for backward compatibility
                         drawing.anchors.forEach(anchor => {
                             if (anchor.medium) {
-                                const image = {
-                                    type: "image",
-                                    imageId: anchor.medium.index,
-                                    range: anchor.range,
-                                    hyperlinks: anchor.picture.hyperlinks
-                                };
-                                model.media.push(image);
+                                // Detect overlay watermarks: drawings that carry alphaModFix
+                                const hasAlpha = anchor.medium.alphaModFix !== undefined && anchor.medium.alphaModFix < 100000;
+                                if (hasAlpha) {
+                                    model.media.push({
+                                        type: "watermark",
+                                        imageId: anchor.medium.index,
+                                        opacity: anchor.medium.alphaModFix / 100000
+                                    });
+                                }
+                                else {
+                                    model.media.push({
+                                        type: "image",
+                                        imageId: anchor.medium.index,
+                                        range: anchor.range,
+                                        hyperlinks: anchor.picture.hyperlinks
+                                    });
+                                }
                             }
                         });
                     }

package/dist/browser/modules/excel/xlsx/xlsx.browser.d.ts

@@ -223,6 +223,7 @@ declare class XLSX {
     _processDrawingEntry(stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
     _processDrawingRelsEntry(entry: any, model: any, name: string): Promise<void>;
     _processVmlDrawingEntry(entry: any, model: any, name: string): Promise<void>;
+    _processVmlDrawingHFEntry(entry: any, model: any, _name: string): Promise<void>;
     _processThemeEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotTableEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotTableRelsEntry(stream: IParseStream, model: any, name: string): Promise<void>;

package/dist/browser/modules/excel/xlsx/xlsx.browser.js

@@ -35,7 +35,7 @@ import { StreamingZip, ZipDeflateFile } from "../../archive/zip/stream.js";
 import { ZipParser } from "../../archive/unzip/zip-parser.js";
 import { PassThrough } from "../../stream/index.browser.js";
 import { concatUint8Arrays } from "../../../utils/binary.js";
-import { commentsPath, commentsRelTargetFromWorksheetName, ctrlPropPath, drawingPath, drawingRelsPath, OOXML_REL_TARGETS, pivotTableRelTargetFromWorksheetName, pivotCacheDefinitionRelTargetFromWorkbook, getCommentsIndexFromPath, getDrawingNameFromPath, getDrawingNameFromRelsPath, getMediaFilenameFromPath, mediaPath, getPivotCacheDefinitionNameFromPath, getPivotCacheDefinitionNameFromRelsPath, getPivotCacheRecordsNameFromPath, getPivotTableNameFromPath, getPivotTableNameFromRelsPath, pivotCacheDefinitionPath, pivotCacheDefinitionRelsPath, pivotCacheDefinitionRelTargetFromPivotTable, pivotCacheRecordsPath, pivotCacheRecordsRelTarget, pivotTablePath, pivotTableRelsPath, getTableNameFromPath, tablePath, tableRelTargetFromWorksheetName, themePath, getThemeNameFromPath, getVmlDrawingNameFromPath, getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, isBinaryEntryPath, normalizeZipPath, OOXML_PATHS, vmlDrawingRelTargetFromWorksheetName, vmlDrawingPath, worksheetPath, worksheetRelsPath, worksheetRelTarget } from "../utils/ooxml-paths.js";
+import { commentsPath, commentsRelTargetFromWorksheetName, ctrlPropPath, drawingPath, drawingRelsPath, OOXML_REL_TARGETS, pivotTableRelTargetFromWorksheetName, pivotCacheDefinitionRelTargetFromWorkbook, getCommentsIndexFromPath, getDrawingNameFromPath, getDrawingNameFromRelsPath, getMediaFilenameFromPath, mediaPath, getPivotCacheDefinitionNameFromPath, getPivotCacheDefinitionNameFromRelsPath, getPivotCacheRecordsNameFromPath, getPivotTableNameFromPath, getPivotTableNameFromRelsPath, pivotCacheDefinitionPath, pivotCacheDefinitionRelsPath, pivotCacheDefinitionRelTargetFromPivotTable, pivotCacheRecordsPath, pivotCacheRecordsRelTarget, pivotTablePath, pivotTableRelsPath, getTableNameFromPath, tablePath, tableRelTargetFromWorksheetName, themePath, getThemeNameFromPath, getVmlDrawingNameFromPath, getVmlDrawingHFNameFromPath, getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, isBinaryEntryPath, normalizeZipPath, OOXML_PATHS, vmlDrawingRelTargetFromWorksheetName, vmlDrawingPath, vmlDrawingHFPath, vmlDrawingHFRelsPath, worksheetPath, worksheetRelsPath, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { filterDrawingAnchors } from "../utils/drawing-utils.js";
 import { PassthroughManager } from "../utils/passthrough-manager.js";
 class StreamingZipWriterAdapter {
@@ -906,6 +906,17 @@ class XLSX {
         const vmlDrawing = await xform.parseStream(entry);
         model.vmlDrawings[vmlDrawingRelTargetFromWorksheetName(name)] = vmlDrawing;
     }
+    async _processVmlDrawingHFEntry(entry, model, _name) {
+        const xform = new VmlDrawingXform();
+        const vmlDrawing = await xform.parseStream(entry);
+        // Store parsed header image info for reconciliation
+        if (vmlDrawing && vmlDrawing.headerImage) {
+            if (!model.vmlDrawingHF) {
+                model.vmlDrawingHF = {};
+            }
+            model.vmlDrawingHF[_name] = vmlDrawing.headerImage;
+        }
+    }
     async _processThemeEntry(stream, model, name) {
         await new Promise((resolve, reject) => {
             const streamBuf = this.createStreamBuf();
@@ -1020,6 +1031,13 @@ class XLSX {
             await this._processVmlDrawingEntry(stream, model, vmlDrawingName);
             return true;
         }
+        // VML header/footer drawings (watermark in header mode).
+        // Parse to extract header image info for round-trip preservation.
+        const vmlHFName = getVmlDrawingHFNameFromPath(entryName);
+        if (vmlHFName) {
+            await this._processVmlDrawingHFEntry(stream, model, vmlHFName);
+            return true;
+        }
         const commentsIndex = getCommentsIndexFromPath(entryName);
         if (commentsIndex) {
             await this._processCommentEntry(stream, model, `comments${commentsIndex}`);
@@ -1226,6 +1244,35 @@ class XLSX {
                     formControls: hasFormControls ? worksheet.formControls : []
                 });
             }
+            // Generate VML drawing for header/footer images (watermark in header mode)
+            if (worksheet.headerImage) {
+                const hdrImage = worksheet.headerImage;
+                const bookImage = hdrImage.bookImage;
+                const imageFileName = bookImage.name &&
+                    bookImage.extension &&
+                    bookImage.name.endsWith(`.${bookImage.extension}`)
+                    ? bookImage.name
+                    : `${bookImage.name}.${bookImage.extension}`;
+                const imageRelTarget = `../media/${imageFileName}`;
+                // Write the VML file for the header image
+                await this._renderToZip(zip, vmlDrawingHFPath(fileIndex), vmlDrawingXform, {
+                    comments: [],
+                    formControls: [],
+                    headerImage: {
+                        imageRelId: "rId1",
+                        width: hdrImage.headerWidth,
+                        height: hdrImage.headerHeight
+                    }
+                });
+                // Write the VML rels file referencing the image
+                await this._renderToZip(zip, vmlDrawingHFRelsPath(fileIndex), relationshipsXform, [
+                    {
+                        Id: "rId1",
+                        Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+                        Target: imageRelTarget
+                    }
+                ]);
+            }
             // Generate ctrlProp files for form controls
             if (hasFormControls) {
                 for (const control of worksheet.formControls) {
@@ -1372,6 +1419,7 @@ class XLSX {
         worksheetOptions.drawings = model.drawings = [];
         worksheetOptions.commentRefs = model.commentRefs = [];
         worksheetOptions.formControlRefs = model.formControlRefs = [];
+        model.hasHeaderWatermark = false;
         let tableCount = 0;
         model.tables = [];
         model.worksheets.forEach((worksheet, index) => {
@@ -1390,6 +1438,10 @@ class XLSX {
         });
         // ContentTypesXform expects this flag
         model.hasCheckboxes = model.styles.hasCheckboxes;
+        // Propagate header watermark flag from worksheet prepare options
+        if (worksheetOptions.hasHeaderWatermark) {
+            model.hasHeaderWatermark = true;
+        }
         // Build passthroughContentTypes for ContentTypesXform using PassthroughManager
         const passthrough = model.passthrough || {};
         const passthroughManager = new PassthroughManager();

package/dist/browser/modules/pdf/core/pdf-writer.d.ts

@@ -71,7 +71,7 @@ export declare class PdfWriter {
         parentRef: number;
         width: number;
         height: number;
-        contentsRef: number;
+        contentsRef: number | string;
         resourcesRef: number;
         annotRefs?: number[];
     }): number;

package/dist/browser/modules/pdf/core/pdf-writer.js

@@ -129,11 +129,12 @@ export class PdfWriter {
     addPage(options) {
         const objNum = this.allocObject();
         const mediaBox = `[0 0 ${pdfNumber(options.width)} ${pdfNumber(options.height)}]`;
+        const contentsValue = typeof options.contentsRef === "string" ? options.contentsRef : pdfRef(options.contentsRef);
         const dict = new PdfDict()
             .set("Type", "/Page")
             .set("Parent", pdfRef(options.parentRef))
             .set("MediaBox", mediaBox)
-            .set("Contents", pdfRef(options.contentsRef))
+            .set("Contents", contentsValue)
             .set("Resources", pdfRef(options.resourcesRef));
         if (options.annotRefs && options.annotRefs.length > 0) {
             dict.set("Annots", "[" + options.annotRefs.map(r => pdfRef(r)).join(" ") + "]");

package/dist/browser/modules/pdf/index.d.ts

@@ -47,7 +47,7 @@ export { excelToPdf } from "./excel-bridge.js";
 /** Read a PDF file and extract text, images, and metadata. */
 export { readPdf } from "./reader/pdf-reader.js";
 export type { PdfCell, PdfRow, PdfColumn, PdfSheet, PdfBook, PdfImage } from "./pdf.js";
-export type { PdfExportOptions, PdfOrientation, PdfPageSize, PdfMargins, PdfColor, PageSizeName } from "./types.js";
+export type { PdfExportOptions, PdfOrientation, PdfPageSize, PdfMargins, PdfColor, PageSizeName, PdfWatermark, PdfTextWatermark, PdfImageWatermark, PdfWatermarkFilter } from "./types.js";
 export { PageSizes } from "./types.js";
 export type { ReadPdfOptions, ReadPdfResult, ReadPdfPage } from "./reader/pdf-reader.js";
 export type { PdfMetadata } from "./reader/metadata-reader.js";

package/dist/browser/modules/pdf/render/page-renderer.d.ts

@@ -11,7 +11,7 @@
  */
 import { PdfContentStream } from "../core/pdf-stream.js";
 import type { FontManager } from "../font/font-manager.js";
-import type { LayoutPage, ResolvedPdfOptions, PdfRect } from "../types.js";
+import type { LayoutPage, ResolvedPdfOptions, PdfRect, PdfWatermark } from "../types.js";
 /**
  * Result of rendering a page.
  */
@@ -40,3 +40,31 @@ export declare function computeTextX(align: "left" | "center" | "right", rect: {
  * Uses a greedy word-wrap algorithm.
  */
 export declare function wrapTextLines(text: string, measure: (s: string) => number, maxWidth: number): string[];
+/**
+ * Result of rendering a watermark on a page.
+ * Contains any alpha values and image XObjects that need to be registered
+ * in the page's resource dictionary.
+ */
+export interface WatermarkRenderResult {
+    /** Alpha values used by the watermark. */
+    alphaValues: number[];
+    /** Image XObject entries: name → raw image data + format. */
+    imageXObjects: Array<{
+        name: string;
+        data: Uint8Array;
+        format: "jpeg" | "png";
+    }>;
+}
+/**
+ * Render a watermark onto a PDF content stream.
+ * This should be called BEFORE the cell/grid content is rendered so the
+ * watermark sits behind everything (under-content).
+ */
+export declare function renderWatermark(stream: PdfContentStream, page: LayoutPage, watermark: PdfWatermark, fontManager: FontManager): WatermarkRenderResult;
+/**
+ * Parse image dimensions from raw JPEG or PNG data without a full decode.
+ */
+export declare function parseImageDimensions(data: Uint8Array, format: "jpeg" | "png"): {
+    width: number;
+    height: number;
+};