@cj-tech-master/excelts 9.0.0 → 9.1.0

package/dist/browser/modules/pdf/render/pdf-exporter.js

@@ -8,12 +8,13 @@
  * It is used internally by the public `pdf()` and `excelToPdf()` APIs.
  */
 import { PdfWriter } from "../core/pdf-writer.js";
+import { PdfContentStream } from "../core/pdf-stream.js";
 import { PdfDict, pdfRef, pdfNumber, pdfString as pdfStr } from "../core/pdf-object.js";
 import { FontManager, resolvePdfFontName } from "../font/font-manager.js";
 import { parseTtf } from "../font/ttf-parser.js";
 import { initEncryption } from "../core/encryption.js";
 import { layoutSheet } from "./layout-engine.js";
-import { renderPage, alphaGsName } from "./page-renderer.js";
+import { renderPage, alphaGsName, renderWatermark, parseImageDimensions } from "./page-renderer.js";
 import { decodePng } from "./png-decoder.js";
 import { PdfError, PdfRenderError } from "../errors.js";
 import { PageSizes } from "../types.js";
@@ -83,8 +84,21 @@ async function finishExport(ctx, workbook, options) {
     ensureAtLeastOnePage(allPages, documentOptions, sheets);
     fixPageNumbers(allPages);
     trackFontsForHeaders(allPages, fontManager);
+    // Track watermark fonts
+    const watermark = documentOptions.watermark;
+    if (watermark && watermark.type === "text") {
+        const wmFontFamily = watermark.fontFamily ?? "Helvetica";
+        const wmBold = watermark.bold ?? false;
+        const wmItalic = watermark.italic ?? false;
+        if (fontManager.hasEmbeddedFont()) {
+            fontManager.trackText(watermark.text);
+        }
+        else {
+            fontManager.ensureFont(resolvePdfFontName(wmFontFamily, wmBold, wmItalic));
+        }
+    }
     const fontObjectMap = fontManager.writeFontResources(writer);
-    const { pageObjNums, sheetFirstPage, pagesTreeObjNum } = await renderAllPages(allPages, fontManager, writer, fontObjectMap);
+    const { pageObjNums, sheetFirstPage, pagesTreeObjNum } = await renderAllPages(allPages, fontManager, writer, fontObjectMap, watermark);
     return buildFinalPdf(writer, pageObjNums, pagesTreeObjNum, sheetFirstPage, documentOptions, workbook, options);
 }
 function ensureAtLeastOnePage(allPages, documentOptions, sheets) {
@@ -133,20 +147,20 @@ function trackFontsForHeaders(allPages, fontManager) {
         }
     }
 }
-async function renderAllPages(allPages, fontManager, writer, fontObjectMap) {
+async function renderAllPages(allPages, fontManager, writer, fontObjectMap, watermark) {
     const pageObjNums = [];
     const pagesTreeObjNum = writer.allocObject();
     const sheetFirstPage = new Map();
     const totalPages = allPages.length;
     for (let i = 0; i < allPages.length; i++) {
-        renderSinglePage(allPages[i], fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage);
+        renderSinglePage(allPages[i], fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage, watermark);
         if (i < allPages.length - 1) {
             await yieldToEventLoop();
         }
     }
     return { pageObjNums, sheetFirstPage, pagesTreeObjNum };
 }
-function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage) {
+function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage, watermark) {
     try {
         const { stream: contentStream, alphaValues } = renderPage(page, page.options, fontManager, totalPages);
         // Handle images: create XObject Image entries and draw them
@@ -160,10 +174,46 @@ function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages,
                 contentStream.drawImage(imgName, img.rect.x, img.rect.y, img.rect.width, img.rect.height);
             }
         }
-        // Add content stream object
+        // --- Render watermark into a separate content stream ---
+        // PDF supports Contents as an array of stream references. The watermark stream
+        // is placed BEFORE the main content stream so it renders behind everything.
+        let watermarkContentObjNum;
+        const shouldApplyWatermark = watermark && isWatermarkApplicable(watermark, page);
+        if (shouldApplyWatermark) {
+            const wmContentStream = new PdfContentStream();
+            const wmResult = renderWatermark(wmContentStream, page, watermark, fontManager);
+            // Register watermark alpha values in the shared set
+            for (const alpha of wmResult.alphaValues) {
+                alphaValues.add(alpha);
+            }
+            // Register watermark image XObjects
+            for (const wmImg of wmResult.imageXObjects) {
+                const imgObjNum = writeImageXObject(writer, wmImg.data, wmImg.format);
+                imageXObjects.set(wmImg.name, imgObjNum);
+            }
+            // Write watermark content stream object
+            watermarkContentObjNum = writer.allocObject();
+            writer.addStreamObject(watermarkContentObjNum, new PdfDict(), wmContentStream);
+        }
+        // Add main content stream object
         const contentObjNum = writer.allocObject();
-        const contentDict = new PdfDict();
-        writer.addStreamObject(contentObjNum, contentDict, contentStream);
+        writer.addStreamObject(contentObjNum, new PdfDict(), contentStream);
+        // Build Contents reference — array if watermark exists, single ref otherwise.
+        // placement "under" (default): watermark stream first, then content
+        // placement "over": content first, then watermark stream on top
+        let contentsRef;
+        if (watermarkContentObjNum) {
+            const placement = watermark?.placement ?? "under";
+            if (placement === "over") {
+                contentsRef = `[${pdfRef(contentObjNum)} ${pdfRef(watermarkContentObjNum)}]`;
+            }
+            else {
+                contentsRef = `[${pdfRef(watermarkContentObjNum)} ${pdfRef(contentObjNum)}]`;
+            }
+        }
+        else {
+            contentsRef = pdfRef(contentObjNum);
+        }
         // Add resources dictionary object
         const resourcesObjNum = writer.allocObject();
         const fontDictStr = fontManager.buildFontDictString(fontObjectMap);
@@ -212,7 +262,7 @@ function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages,
             parentRef: pagesTreeObjNum,
             width: page.width,
             height: page.height,
-            contentsRef: contentObjNum,
+            contentsRef: contentsRef,
             resourcesRef: resourcesObjNum,
             annotRefs: annotRefs.length > 0 ? annotRefs : undefined
         });
@@ -337,7 +387,8 @@ function resolveOptions(options, sheet) {
         title: options?.title ?? "",
         author: options?.author ?? "",
         subject: options?.subject ?? "",
-        creator: options?.creator ?? "excelts"
+        creator: options?.creator ?? "excelts",
+        watermark: options?.watermark
     };
 }
 /** Map PaperSize enum values to PDF page sizes. */
@@ -428,6 +479,28 @@ function buildOutlines(writer, sheetFirstPage, pageObjNums) {
     return outlinesObjNum;
 }
 // =============================================================================
+// Watermark Filtering
+// =============================================================================
+/**
+ * Check if a watermark should be applied to a specific page based on
+ * optional page number and sheet name filters.
+ */
+function isWatermarkApplicable(watermark, page) {
+    if (watermark.pages && watermark.pages.length > 0) {
+        if (!watermark.pages.includes(page.pageNumber)) {
+            return false;
+        }
+    }
+    if (watermark.sheets && watermark.sheets.length > 0) {
+        // Case-insensitive sheet name matching, consistent with the rest of the API
+        const sheetLower = page.sheetName.toLowerCase();
+        if (!watermark.sheets.some(s => s.toLowerCase() === sheetLower)) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
 // Image XObject
 // =============================================================================
 /**
@@ -444,7 +517,7 @@ function writeImageXObject(writer, data, format) {
  */
 function writeJpegImageXObject(writer, data) {
     const objNum = writer.allocObject();
-    const dims = getJpegDimensions(data);
+    const dims = parseImageDimensions(data, "jpeg");
     const dict = new PdfDict()
         .set("Type", "/XObject")
         .set("Subtype", "/Image")
@@ -486,39 +559,3 @@ function writePngImageXObject(writer, data) {
     writer.addStreamObject(objNum, dict, png.pixels);
     return objNum;
 }
-/**
- * Extract width and height from a JPEG file header.
- * Scans for SOF markers (SOF0-SOF3, SOF5-SOF7, SOF9-SOF11, SOF13-SOF15)
- * which all share the same frame header layout.
- * Handles 0xFF padding bytes per JPEG spec.
- */
-function getJpegDimensions(data) {
-    let offset = 2; // skip SOI marker (0xFFD8)
-    while (offset < data.length - 1) {
-        // Skip any 0xFF fill bytes
-        while (offset < data.length && data[offset] === 0xff && data[offset + 1] === 0xff) {
-            offset++;
-        }
-        if (offset >= data.length - 1 || data[offset] !== 0xff) {
-            break;
-        }
-        const marker = data[offset + 1];
-        // SOF markers: C0-C3, C5-C7, C9-CB, CD-CF (excluding C4=DHT, C8=JPG, CC=DAC)
-        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
-        if (isSof) {
-            if (offset + 8 < data.length) {
-                const height = (data[offset + 5] << 8) | data[offset + 6];
-                const width = (data[offset + 7] << 8) | data[offset + 8];
-                return { width, height };
-            }
-            break;
-        }
-        // Skip segment: 2 byte marker + segment length (includes the 2 length bytes)
-        if (offset + 3 >= data.length) {
-            break;
-        }
-        const segLen = (data[offset + 2] << 8) | data[offset + 3];
-        offset += 2 + segLen;
-    }
-    return { width: 1, height: 1 };
-}

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

@@ -339,7 +339,241 @@ export interface PdfExportOptions {
             printHighQuality: boolean;
         }>;
     };
+    /**
+     * Watermark to render on every page.
+     * Supports text watermarks (e.g. "CONFIDENTIAL") and image watermarks (e.g. company logo).
+     *
+     * @example Text watermark:
+     * ```typescript
+     * watermark: {
+     *   type: "text",
+     *   text: "DRAFT",
+     *   opacity: 0.1,
+     *   rotation: -45
+     * }
+     * ```
+     *
+     * @example Image watermark:
+     * ```typescript
+     * watermark: {
+     *   type: "image",
+     *   data: logoPng,
+     *   format: "png",
+     *   opacity: 0.08
+     * }
+     * ```
+     */
+    watermark?: PdfWatermark;
 }
+/**
+ * Text watermark configuration for PDF export.
+ *
+ * Renders semi-transparent text (e.g. "CONFIDENTIAL", "DRAFT") on every page.
+ *
+ * @example
+ * ```typescript
+ * const bytes = await pdf(data, {
+ *   watermark: {
+ *     type: "text",
+ *     text: "CONFIDENTIAL",
+ *     color: { r: 0.8, g: 0, b: 0 },
+ *     opacity: 0.1,
+ *     rotation: -45
+ *   }
+ * });
+ * ```
+ */
+export interface PdfTextWatermark {
+    type: "text";
+    /** The watermark text to display. */
+    text: string;
+    /**
+     * Font size in points.
+     * @default 54
+     */
+    fontSize?: number;
+    /**
+     * Text color (RGB, each 0-1).
+     * @default { r: 0.75, g: 0.75, b: 0.75 }
+     */
+    color?: PdfColor;
+    /**
+     * Opacity (0 = fully transparent, 1 = fully opaque).
+     * @default 0.15
+     */
+    opacity?: number;
+    /**
+     * Rotation angle in degrees (positive = counter-clockwise).
+     * @default -45
+     */
+    rotation?: number;
+    /**
+     * Font family name. Must be a standard PDF font (Type1) or the embedded font.
+     * @default "Helvetica"
+     */
+    fontFamily?: string;
+    /**
+     * Whether to render in bold.
+     * @default false
+     */
+    bold?: boolean;
+    /**
+     * Whether to render in italic.
+     * @default false
+     */
+    italic?: boolean;
+    /**
+     * Position on the page. `"center"` places the watermark at the geometric center.
+     * A custom `{ x, y }` object specifies the **center point** of the watermark
+     * in PDF points (origin at bottom-left corner of the page).
+     * @default "center"
+     */
+    position?: "center" | {
+        x: number;
+        y: number;
+    };
+    /**
+     * When true, the watermark text is tiled in a repeating grid across the entire page.
+     * @default false
+     */
+    repeat?: boolean;
+    /**
+     * Horizontal spacing (in points) between repeated watermark tiles.
+     * Only used when `repeat` is true.
+     * @default 200
+     */
+    repeatSpacingX?: number;
+    /**
+     * Vertical spacing (in points) between repeated watermark tiles.
+     * Only used when `repeat` is true.
+     * @default 200
+     */
+    repeatSpacingY?: number;
+}
+/**
+ * Image watermark configuration for PDF export.
+ *
+ * Embeds a semi-transparent image (e.g. company logo) on every page.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from "fs";
+ * const logo = readFileSync("logo.png");
+ *
+ * const bytes = await pdf(data, {
+ *   watermark: {
+ *     type: "image",
+ *     data: logo,
+ *     format: "png",
+ *     opacity: 0.08,
+ *     scale: 0.4
+ *   }
+ * });
+ * ```
+ */
+export interface PdfImageWatermark {
+    type: "image";
+    /** Raw image bytes (JPEG or PNG). */
+    data: Uint8Array;
+    /** Image format. */
+    format: "jpeg" | "png";
+    /**
+     * Opacity (0 = fully transparent, 1 = fully opaque).
+     * @default 0.15
+     */
+    opacity?: number;
+    /**
+     * Rotation angle in degrees (positive = counter-clockwise).
+     * @default 0
+     */
+    rotation?: number;
+    /**
+     * Scale factor relative to the page size.
+     * 0.5 means the image's largest dimension will be scaled to
+     * 50% of the smaller page dimension (width or height).
+     * Ignored when `width` and `height` are explicitly provided.
+     * @default 0.5
+     */
+    scale?: number;
+    /**
+     * Explicit image width in PDF points. When set together with `height`,
+     * overrides `scale` and renders the image at the exact specified dimensions.
+     */
+    width?: number;
+    /**
+     * Explicit image height in PDF points. When set together with `width`,
+     * overrides `scale` and renders the image at the exact specified dimensions.
+     */
+    height?: number;
+    /**
+     * Position on the page. `"center"` places the watermark at the geometric center.
+     * A custom `{ x, y }` object specifies the **center point** of the watermark
+     * in PDF points (origin at bottom-left corner of the page).
+     * @default "center"
+     */
+    position?: "center" | {
+        x: number;
+        y: number;
+    };
+    /**
+     * When true, the watermark image is tiled in a repeating grid across the entire page.
+     * @default false
+     */
+    repeat?: boolean;
+    /**
+     * Horizontal spacing (in points) between repeated watermark tiles.
+     * Only used when `repeat` is true.
+     * @default 200
+     */
+    repeatSpacingX?: number;
+    /**
+     * Vertical spacing (in points) between repeated watermark tiles.
+     * Only used when `repeat` is true.
+     * @default 200
+     */
+    repeatSpacingY?: number;
+}
+/**
+ * Common watermark filter and placement options shared by text and image watermarks.
+ */
+export interface PdfWatermarkFilter {
+    /**
+     * Restrict the watermark to specific page numbers (1-based, document-global).
+     * When set, only pages whose number is in this array get the watermark.
+     * If omitted, all pages receive the watermark.
+     *
+     * @example Only on the first page:
+     * ```typescript
+     * watermark: { type: "text", text: "COVER", pages: [1] }
+     * ```
+     */
+    pages?: number[];
+    /**
+     * Restrict the watermark to specific sheet names (case-insensitive).
+     * When set, only pages belonging to the named sheets get the watermark.
+     * If omitted, all sheets receive the watermark.
+     *
+     * @example Only on the "Summary" sheet:
+     * ```typescript
+     * watermark: { type: "text", text: "DRAFT", sheets: ["Summary"] }
+     * ```
+     */
+    sheets?: string[];
+    /**
+     * Watermark layering relative to page content.
+     *
+     * - `"under"` — watermark renders **behind** all page content including
+     *   cell fills, borders, text, grid lines, headers, and footers (default)
+     * - `"over"` — watermark renders **on top of** all page content
+     *
+     * @default "under"
+     */
+    placement?: "under" | "over";
+}
+/**
+ * Watermark configuration — either text or image, with optional page/sheet filters.
+ */
+export type PdfWatermark = (PdfTextWatermark | PdfImageWatermark) & PdfWatermarkFilter;
 /**
  * Page margins in PDF points.
  */
@@ -369,6 +603,7 @@ export interface ResolvedPdfOptions {
     author: string;
     subject: string;
     creator: string;
+    watermark?: PdfWatermark;
 }
 /**
  * RGBA color used internally for PDF rendering.

package/dist/cjs/index.js

@@ -17,8 +17,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PdfRenderError = exports.PdfError = exports.PageSizes = exports.excelToPdf = exports.pdf = exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
-exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = void 0;
+exports.PdfError = exports.PageSizes = exports.excelToPdf = exports.pdf = exports.uint8ArrayToString = exports.stringToUint8Array = exports.toUint8Array = exports.concatUint8Arrays = exports.getRootCause = exports.getErrorChain = exports.errorToJSON = exports.toError = exports.BaseError = exports.getSupportedFormats = exports.DateFormatter = exports.DateParser = exports.xmlDecode = exports.xmlEncode = exports.uint8ArrayToBase64 = exports.base64ToUint8Array = exports.excelToDate = exports.dateToExcel = exports.encodeRange = exports.decodeRange = exports.encodeCell = exports.decodeCell = exports.encodeRow = exports.decodeRow = exports.encodeCol = exports.decodeCol = exports.DefinedNames = exports.createCsvFormatterStream = exports.createCsvParserStream = exports.CsvFormatterStream = exports.CsvParserStream = exports.createTextWatermarkImage = exports.WorksheetReader = exports.WorksheetWriter = exports.WorkbookReader = exports.WorkbookWriter = exports.FormCheckbox = exports.DataValidations = exports.Table = exports.Image = exports.Range = exports.Cell = exports.Column = exports.Row = exports.Worksheet = exports.Workbook = void 0;
+exports.MarkdownParseError = exports.MarkdownError = exports.MaxItemsExceededError = exports.ImageError = exports.TableError = exports.PivotTableError = exports.WorksheetNameError = exports.XmlParseError = exports.InvalidValueTypeError = exports.MergeConflictError = exports.RowOutOfBoundsError = exports.ColumnOutOfBoundsError = exports.InvalidAddressError = exports.ExcelStreamStateError = exports.ExcelNotSupportedError = exports.ExcelDownloadError = exports.ExcelFileError = exports.isExcelError = exports.ExcelError = exports.isPdfError = exports.PdfStructureError = exports.PdfFontError = exports.PdfRenderError = void 0;
 var workbook_1 = require("./modules/excel/workbook.js");
 Object.defineProperty(exports, "Workbook", { enumerable: true, get: function () { return workbook_1.Workbook; } });
 var worksheet_1 = require("./modules/excel/worksheet.js");
@@ -61,6 +61,9 @@ __exportStar(require("./modules/excel/enums.js"), exports);
 // =============================================================================
 // Export all type definitions from types.ts
 __exportStar(require("./modules/excel/types.js"), exports);
+// Watermark image generator utility
+var watermark_image_1 = require("./modules/excel/utils/watermark-image.js");
+Object.defineProperty(exports, "createTextWatermarkImage", { enumerable: true, get: function () { return watermark_image_1.createTextWatermarkImage; } });
 var stream_1 = require("./modules/csv/stream/index.js");
 Object.defineProperty(exports, "CsvParserStream", { enumerable: true, get: function () { return stream_1.CsvParserStream; } });
 Object.defineProperty(exports, "CsvFormatterStream", { enumerable: true, get: function () { return stream_1.CsvFormatterStream; } });

package/dist/cjs/modules/excel/image.js

@@ -18,6 +18,20 @@ class Image {
                     type: this.type,
                     imageId: this.imageId ?? ""
                 };
+            case "watermark":
+                return {
+                    type: this.type,
+                    imageId: this.imageId ?? "",
+                    opacity: this.opacity
+                };
+            case "headerImage":
+                return {
+                    type: this.type,
+                    imageId: this.imageId ?? "",
+                    headerWidth: this.headerWidth,
+                    headerHeight: this.headerHeight,
+                    applyTo: this.applyTo
+                };
             case "image": {
                 const range = this.range;
                 if (!range) {
@@ -39,9 +53,13 @@ class Image {
                 throw new errors_1.ImageError("Invalid Image Type");
         }
     }
-    set model({ type, imageId, range, hyperlinks }) {
+    set model({ type, imageId, range, hyperlinks, opacity, headerWidth, headerHeight, applyTo }) {
         this.type = type;
         this.imageId = imageId;
+        this.opacity = opacity;
+        this.headerWidth = headerWidth;
+        this.headerHeight = headerHeight;
+        this.applyTo = applyTo;
         if (type === "image") {
             if (typeof range === "string") {
                 const decoded = col_cache_1.colCache.decode(range);
@@ -70,6 +88,10 @@ class Image {
         const cloned = new Image(target);
         cloned.type = this.type;
         cloned.imageId = this.imageId;
+        cloned.opacity = this.opacity;
+        cloned.headerWidth = this.headerWidth;
+        cloned.headerHeight = this.headerHeight;
+        cloned.applyTo = this.applyTo;
         if (this.range) {
             cloned.range = {
                 tl: this.range.tl.clone(target),

package/dist/cjs/modules/excel/stream/worksheet-writer.js

@@ -154,6 +154,8 @@ class WorksheetWriter {
         // auto filter
         this.autoFilter = options.autoFilter ?? null;
         this._media = [];
+        // watermark
+        this._watermark = null;
         // worksheet protection
         this.sheetProtection = null;
         // start writing to stream now
@@ -451,6 +453,57 @@ class WorksheetWriter {
     getImages() {
         return this._media;
     }
+    // =========================================================================
+    // Watermark
+    /**
+     * Add a watermark to the worksheet using an image from `WorkbookWriter.addImage()`.
+     * Supports overlay mode (DrawingML with transparency) and header mode (VML behind content).
+     */
+    addWatermark(options) {
+        // Remove existing watermark entries (both stored type tags)
+        this._media = this._media.filter(m => m._watermarkTag !== true);
+        const opacity = options.opacity !== undefined ? Math.max(0, Math.min(1, options.opacity)) : 0.15;
+        this._watermark = {
+            imageId: String(options.imageId),
+            mode: options.mode ?? "overlay",
+            opacity,
+            headerWidth: options.headerWidth,
+            headerHeight: options.headerHeight,
+            applyTo: options.applyTo
+        };
+        if (this._watermark.mode === "overlay") {
+            // Coverage range is computed lazily during commit() via _resolveWatermarkRange()
+            const entry = {
+                type: "image",
+                imageId: String(options.imageId),
+                range: {
+                    tl: { nativeCol: 0, nativeColOff: 0, nativeRow: 0, nativeRowOff: 0 },
+                    br: { nativeCol: 100, nativeColOff: 0, nativeRow: 200, nativeRowOff: 0 },
+                    editAs: "absolute"
+                },
+                // Internal tag for dedup — not part of the WriterImageModel type
+                _watermarkTag: true,
+                opacity
+            };
+            this._media.push(entry);
+        }
+        // Note: header mode for streaming writer is limited — the VML file generation
+        // happens in WorkbookWriter.addWorksheets(), which handles worksheet.headerImage.
+        // We store the config in _watermark and it's picked up by the commit path.
+    }
+    /**
+     * Get the current watermark configuration.
+     */
+    getWatermark() {
+        return this._watermark;
+    }
+    /**
+     * Remove the watermark from the worksheet.
+     */
+    removeWatermark() {
+        this._watermark = null;
+        this._media = this._media.filter(m => m._watermarkTag !== true);
+    }
     /**
      * Parse the user-supplied range into a normalised internal model
      * mirroring what the regular Worksheet / Image class does.
@@ -629,6 +682,21 @@ class WorksheetWriter {
         if (this._media.length === 0) {
             return;
         }
+        // Resolve watermark coverage range from actual worksheet dimensions
+        // (at commit time, all rows have been flushed so _dimensions is accurate)
+        for (const entry of this._media) {
+            if (entry._watermarkTag) {
+                const dims = this._dimensions.model;
+                const maxCol = dims ? Math.max(dims.right ?? 100, 100) : 100;
+                const maxRow = dims ? Math.max(dims.bottom ?? 200, 200) : 200;
+                entry.range.br = {
+                    nativeCol: maxCol,
+                    nativeColOff: 0,
+                    nativeRow: maxRow,
+                    nativeRowOff: 0
+                };
+            }
+        }
         // Build the drawing model from the stored images.
         // The drawing XML will be generated later by WorkbookWriterBase.addDrawings().
         const drawingName = `drawing${this.id}`;

package/dist/cjs/modules/excel/utils/drawing-utils.js

@@ -69,6 +69,11 @@ function buildDrawingAnchorsAndRels(media, existingRels, options) {
             },
             range: medium.range
         };
+        // Pass through watermark opacity as alphaModFix
+        if (medium.opacity !== undefined) {
+            const clamped = Math.max(0, Math.min(1, medium.opacity));
+            anchor.picture.alphaModFix = Math.round(clamped * 100000);
+        }
         // Handle image hyperlinks
         if (medium.hyperlinks && medium.hyperlinks.hyperlink) {
             const rIdHyperlink = options.nextRId(rels);