@cj-tech-master/excelts 9.5.9 → 9.6.0

package/dist/browser/modules/excel/stream/workbook-writer.browser.d.ts

@@ -186,6 +186,23 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
     private _commitWorksheets;
     commit(): Promise<void>;
     get nextId(): number;
+    /**
+     * Register an image with the workbook and return its numeric id.
+     *
+     * Supply `buffer`/`base64`/`filename` to **embed** the bytes, or only `link`
+     * (a URL or local file path) to reference it **externally** — in which case
+     * no bytes are written into the package and the relationship is emitted with
+     * `TargetMode="External"`. If both are provided, embedding wins.
+     *
+     * Linked images work with cell pictures and overlay watermarks; worksheet
+     * background images and header/footer (VML) watermarks cannot be linked.
+     *
+     * @example
+     * ```typescript
+     * const id = wb.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * ws.addImage(id, "B2:D6");
+     * ```
+     */
     addImage(image: ImageData): number;
     getImage(id: number): Medium | undefined;
     /**

package/dist/browser/modules/excel/stream/workbook-writer.browser.js

@@ -11,7 +11,7 @@ import { Zip, ZipDeflate } from "../../archive/zip/stream.js";
 import { DefinedNames } from "../defined-names.js";
 import { ExcelNotSupportedError, ImageError } from "../errors.js";
 import { WorksheetWriter } from "./worksheet-writer.js";
-import { filterDrawingAnchors } from "../utils/drawing-utils.js";
+import { filterDrawingAnchors, isExternalImage } from "../utils/drawing-utils.js";
 import { drawingPath, drawingRelsPath, mediaPath, OOXML_PATHS, OOXML_REL_TARGETS, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { SharedStrings } from "../utils/shared-strings.js";
 import { StreamBuf } from "../utils/stream-buf.js";
@@ -369,6 +369,23 @@ export class WorkbookWriterBase {
         }
         return this._worksheets.length || 1;
     }
+    /**
+     * Register an image with the workbook and return its numeric id.
+     *
+     * Supply `buffer`/`base64`/`filename` to **embed** the bytes, or only `link`
+     * (a URL or local file path) to reference it **externally** — in which case
+     * no bytes are written into the package and the relationship is emitted with
+     * `TargetMode="External"`. If both are provided, embedding wins.
+     *
+     * Linked images work with cell pictures and overlay watermarks; worksheet
+     * background images and header/footer (VML) watermarks cannot be linked.
+     *
+     * @example
+     * ```typescript
+     * const id = wb.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * ws.addImage(id, "B2:D6");
+     * ```
+     */
     addImage(image) {
         const id = this.media.length;
         const medium = {
@@ -486,6 +503,11 @@ export class WorkbookWriterBase {
     addMedia() {
         return Promise.all(this.media.map(async (medium) => {
             if (medium.type === "image") {
+                // External (linked) images carry only a `link` target — no bytes
+                // are written into the package.
+                if (isExternalImage(medium)) {
+                    return;
+                }
                 const filename = mediaPath(medium.name);
                 if (medium.buffer) {
                     this._addFile(medium.buffer, filename);

package/dist/browser/modules/excel/stream/workbook-writer.js

@@ -6,6 +6,7 @@
 import { ImageError } from "../errors.js";
 import { WorkbookWriterBase } from "./workbook-writer.browser.js";
 import { WorksheetWriter } from "./worksheet-writer.js";
+import { isExternalImage } from "../utils/drawing-utils.js";
 import { mediaPath } from "../utils/ooxml-paths.js";
 import { readFileBytes, createWriteStream } from "../../../utils/fs.browser.js";
 class WorkbookWriter extends WorkbookWriterBase {
@@ -27,6 +28,11 @@ class WorkbookWriter extends WorkbookWriterBase {
     addMedia() {
         return Promise.all(this.media.map(async (medium) => {
             if (medium.type === "image") {
+                // External (linked) images carry only a `link` target — no bytes
+                // are written into the package.
+                if (isExternalImage(medium)) {
+                    return;
+                }
                 const filename = mediaPath(medium.name);
                 // Node.js: support loading from file
                 if (medium.filename) {

package/dist/browser/modules/excel/stream/worksheet-writer.d.ts

@@ -179,6 +179,12 @@ declare class WorksheetWriter {
     /**
      * Add a watermark to the worksheet using an image from `WorkbookWriter.addImage()`.
      * Supports overlay mode (DrawingML with transparency) and header mode (VML behind content).
+     *
+     * `mode: "overlay"` supports external (linked) images; `mode: "header"` does
+     * not — VML header/footer images require embedded media, so a linked image
+     * with `mode: "header"` throws an `ImageError`.
+     *
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      */
     addWatermark(options: WatermarkOptions): void;
     /**

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

@@ -1,13 +1,13 @@
 import { Anchor } from "../anchor.js";
 import { Column } from "../column.js";
 import { DataValidations } from "../data-validations.js";
-import { ExcelStreamStateError, MergeConflictError, RowOutOfBoundsError } from "../errors.js";
+import { ExcelStreamStateError, ImageError, MergeConflictError, RowOutOfBoundsError } from "../errors.js";
 import { Dimensions } from "../range.js";
 import { Row } from "../row.js";
 import { SheetCommentsWriter } from "./sheet-comments-writer.js";
 import { SheetRelsWriter } from "./sheet-rels-writer.js";
 import { colCache } from "../utils/col-cache.js";
-import { buildDrawingAnchorsAndRels } from "../utils/drawing-utils.js";
+import { buildDrawingAnchorsAndRels, isExternalImage } from "../utils/drawing-utils.js";
 import { applyMergeBorders, collectMergeBorders } from "../utils/merge-borders.js";
 import { drawingRelTargetFromWorksheet, mediaRelTargetFromRels, worksheetPath } from "../utils/ooxml-paths.js";
 import { buildSheetProtection } from "../utils/sheet-protection.js";
@@ -440,6 +440,12 @@ class WorksheetWriter {
     }
     // =========================================================================
     addBackgroundImage(imageId) {
+        const bookImage = this._workbook.getImage(Number(imageId));
+        if (bookImage && isExternalImage(bookImage)) {
+            throw new ImageError("Background images cannot be external (linked) images. " +
+                "Use an embedded image (buffer/base64/filename). " +
+                "External images are only supported for cell pictures and overlay watermarks.");
+        }
         this._background = {
             imageId: Number(imageId)
         };
@@ -469,14 +475,32 @@ class WorksheetWriter {
     /**
      * Add a watermark to the worksheet using an image from `WorkbookWriter.addImage()`.
      * Supports overlay mode (DrawingML with transparency) and header mode (VML behind content).
+     *
+     * `mode: "overlay"` supports external (linked) images; `mode: "header"` does
+     * not — VML header/footer images require embedded media, so a linked image
+     * with `mode: "header"` throws an `ImageError`.
+     *
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      */
     addWatermark(options) {
+        const mode = options.mode ?? "overlay";
+        // Validate BEFORE mutating any state: VML header/footer images use
+        // embedded media; external (linked) images are not representable here.
+        // Reject them up front so a failed call leaves existing watermark media
+        // untouched (no partial mutation).
+        if (mode === "header") {
+            const bookImage = this._workbook.getImage(Number(options.imageId));
+            if (bookImage && isExternalImage(bookImage)) {
+                throw new ImageError("Header watermark images cannot be external (linked) images. " +
+                    "Use an embedded image (buffer/base64/filename), or use overlay mode for linked images.");
+            }
+        }
         // 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",
+            mode,
             opacity,
             headerWidth: options.headerWidth,
             headerHeight: options.headerHeight,
@@ -794,6 +818,8 @@ class WorksheetWriter {
                 if (!image) {
                     return;
                 }
+                // Background images are always embedded — external (linked) images are
+                // rejected up front in addBackgroundImage (Excel drops them).
                 const pictureId = this._sheetRelsWriter.addMedia({
                     Target: mediaRelTargetFromRels(image.name),
                     Type: RelType.Image

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

@@ -480,6 +480,23 @@ export interface ImageData {
     base64?: string;
     filename?: string;
     buffer?: Buffer;
+    /**
+     * Reference the image as an **external link** instead of embedding its bytes.
+     *
+     * When set (and `buffer`/`base64`/`filename` are all omitted), the image is
+     * written as a linked DrawingML picture (`<a:blip r:link>`) whose relationship
+     * uses `TargetMode="External"`. No bytes are stored in the `.xlsx` package, so
+     * the file size stays small. The value may be either:
+     *
+     * - an absolute/relative URL (e.g. `"https://example.com/logo.png"`), or
+     * - a local file path (e.g. `"file:///C:/images/logo.png"` or `"images/logo.png"`).
+     *
+     * Note: Excel treats linked images as volatile — a moved/missing target shows a
+     * broken-image placeholder, and modern Excel may not auto-load remote URLs for
+     * security reasons. Use embedding (`buffer`/`base64`) when self-contained files
+     * are required.
+     */
+    link?: string;
 }
 export interface ImagePosition {
     tl: {

package/dist/browser/modules/excel/utils/drawing-utils.d.ts

@@ -14,6 +14,11 @@ export interface DrawingAnchor {
         };
         /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
         alphaModFix?: number;
+        /**
+         * When true, the picture references an external linked image
+         * (`<a:blip r:link>`) instead of an embedded one (`<a:blip r:embed>`).
+         */
+        external?: boolean;
     };
     range: any;
 }
@@ -37,6 +42,19 @@ interface ImageMedium {
     /** Opacity 0-1 for watermark overlay mode. */
     opacity?: number;
 }
+/**
+ * Minimal shape of a book-level media entry needed by the embed-vs-link
+ * decision and image-rel construction. Carries the optional link target plus
+ * the three mutually-exclusive embedded byte sources.
+ */
+export interface MediaLike {
+    name?: string;
+    extension?: string;
+    link?: string;
+    buffer?: unknown;
+    base64?: unknown;
+    filename?: unknown;
+}
 /**
  * Resolves a media filename into the drawing-level relative target path.
  *
@@ -50,13 +68,37 @@ export declare function resolveMediaTarget(medium: {
     name?: string;
     extension?: string;
 }): string;
+/**
+ * Determine whether a media entry is an **external (linked) image** rather than
+ * an embedded one. An external image carries a `link` target and supplies no
+ * embedded bytes (`buffer`/`base64`/`filename`). Embedding always takes
+ * precedence: if any byte source is present the image is embedded even if a
+ * `link` was also provided.
+ */
+export declare function isExternalImage(medium: MediaLike): boolean;
+/**
+ * Best-effort image extension inference from an external link's path.
+ *
+ * Normalises to the extension vocabulary used by `ImageData`
+ * (`"jpeg" | "png" | "gif"`); unknown extensions fall back to `"png"`.
+ * The extension is advisory only for linked images — the relationship
+ * Target carries the real reference — but keeping it within the documented
+ * set avoids surprising consumers that branch on `medium.extension`.
+ */
+export declare function inferExternalImageExtension(link: string): "jpeg" | "png" | "gif";
+/**
+ * Build an image relationship for the given rId, choosing between an embedded
+ * package target (`../media/imageN.ext`) and an external link target
+ * (`TargetMode="External"`) based on whether the image is external.
+ *
+ * Shared by the drawing, background, and watermark write paths so the
+ * embed-vs-link decision lives in exactly one place.
+ */
+export declare function buildImageRel(rId: string, bookImage: MediaLike): DrawingRel;
 /** Options for {@link buildDrawingAnchorsAndRels}. */
 interface BuildDrawingOptions {
     /** Look up a book-level image by its id. Return `undefined` if not found. */
-    getBookImage: (imageId: string | number) => {
-        name?: string;
-        extension?: string;
-    } | undefined;
+    getBookImage: (imageId: string | number) => MediaLike | undefined;
     /** Generate the next unique rId string for the drawing rels. */
     nextRId: (rels: DrawingRel[]) => string;
 }

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

@@ -26,6 +26,65 @@ export function resolveMediaTarget(medium) {
         : `${medium.name}.${medium.extension}`;
     return mediaRelTargetFromRels(filename);
 }
+/**
+ * Determine whether a media entry is an **external (linked) image** rather than
+ * an embedded one. An external image carries a `link` target and supplies no
+ * embedded bytes (`buffer`/`base64`/`filename`). Embedding always takes
+ * precedence: if any byte source is present the image is embedded even if a
+ * `link` was also provided.
+ */
+export function isExternalImage(medium) {
+    return !!medium.link && medium.buffer == null && medium.base64 == null && medium.filename == null;
+}
+/**
+ * Best-effort image extension inference from an external link's path.
+ *
+ * Normalises to the extension vocabulary used by `ImageData`
+ * (`"jpeg" | "png" | "gif"`); unknown extensions fall back to `"png"`.
+ * The extension is advisory only for linked images — the relationship
+ * Target carries the real reference — but keeping it within the documented
+ * set avoids surprising consumers that branch on `medium.extension`.
+ */
+export function inferExternalImageExtension(link) {
+    const match = /\.([a-zA-Z0-9]{2,5})(?:[?#].*)?$/.exec(link);
+    const ext = match ? match[1].toLowerCase() : "";
+    switch (ext) {
+        case "jpg":
+        case "jpeg":
+            return "jpeg";
+        case "gif":
+            return "gif";
+        case "png":
+        default:
+            return "png";
+    }
+}
+// =============================================================================
+// Anchor / Rel Building
+// =============================================================================
+/**
+ * Build an image relationship for the given rId, choosing between an embedded
+ * package target (`../media/imageN.ext`) and an external link target
+ * (`TargetMode="External"`) based on whether the image is external.
+ *
+ * Shared by the drawing, background, and watermark write paths so the
+ * embed-vs-link decision lives in exactly one place.
+ */
+export function buildImageRel(rId, bookImage) {
+    if (isExternalImage(bookImage)) {
+        return {
+            Id: rId,
+            Type: RelType.Image,
+            Target: bookImage.link,
+            TargetMode: "External"
+        };
+    }
+    return {
+        Id: rId,
+        Type: RelType.Image,
+        Target: resolveMediaTarget(bookImage)
+    };
+}
 /**
  * Build the drawing anchors and relationships from a list of image media entries.
  *
@@ -47,20 +106,19 @@ export function buildDrawingAnchorsAndRels(media, existingRels, options) {
         if (!bookImage) {
             continue;
         }
+        // An external (linked) image has a `link` target and no embedded bytes.
+        const isExternal = isExternalImage(bookImage);
         // Deduplicate: reuse rId if same imageId already has a drawing rel
         let rIdImage = imageRIdMap[imageId];
         if (!rIdImage) {
             rIdImage = options.nextRId(rels);
             imageRIdMap[imageId] = rIdImage;
-            rels.push({
-                Id: rIdImage,
-                Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
-                Target: resolveMediaTarget(bookImage)
-            });
+            rels.push(buildImageRel(rIdImage, bookImage));
         }
         const anchor = {
             picture: {
-                rId: rIdImage
+                rId: rIdImage,
+                ...(isExternal ? { external: true } : {})
             },
             range: medium.range
         };

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

@@ -32,6 +32,8 @@ export interface WorkbookMedia {
     buffer?: ExcelBuffer | Uint8Array;
     base64?: string;
     name?: string;
+    /** External link target — when set, the image is referenced, not embedded. */
+    link?: string;
 }
 /** Internal model type for serialization */
 export interface WorkbookModel {
@@ -782,7 +784,42 @@ declare class Workbook {
     unregisterFunction(name: string): boolean;
     clearThemes(): void;
     /**
-     * Add Image to Workbook and return the id
+     * Register an image with the workbook and return its numeric id. Pass the id
+     * to {@link Worksheet.addImage}, {@link Worksheet.addBackgroundImage}, or
+     * {@link Worksheet.addWatermark} to place it.
+     *
+     * The image is either **embedded** or **linked (external)**:
+     *
+     * - **Embedded** — supply `buffer`, `base64`, or `filename`. The bytes are
+     *   written into the `.xlsx` package (`xl/media/imageN.ext`). Self-contained,
+     *   but inflates file size.
+     * - **Linked (external)** — supply only `link` (a URL or local file path).
+     *   No bytes are stored; the package keeps a relationship with
+     *   `TargetMode="External"` and the picture is rendered via `<a:blip r:link>`.
+     *   Keeps the file small, but the image is resolved by Excel at open time.
+     *
+     * If both bytes and a `link` are provided, **embedding wins**.
+     *
+     * Linked images work with **cell pictures** ({@link Worksheet.addImage}) and
+     * **overlay watermarks** ({@link Worksheet.addWatermark} with `mode:
+     * "overlay"`). Worksheet background images and header/footer (VML) watermarks
+     * cannot be linked — they require an embedded image.
+     *
+     * Note: Excel treats linked images as volatile — a moved/missing target
+     * shows a broken-image placeholder, and modern Excel may not auto-load
+     * remote URLs for security reasons. Prefer embedding for self-contained files.
+     *
+     * @example Embedded image
+     * ```typescript
+     * const id = workbook.addImage({ buffer: pngBytes, extension: "png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
+     *
+     * @example Linked (external) image — no bytes stored
+     * ```typescript
+     * const id = workbook.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
      */
     addImage(image: ImageData): number;
     getImage(id: number | string): WorkbookMedia | undefined;

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

@@ -1697,7 +1697,42 @@ class Workbook {
     // Images
     // ===========================================================================
     /**
-     * Add Image to Workbook and return the id
+     * Register an image with the workbook and return its numeric id. Pass the id
+     * to {@link Worksheet.addImage}, {@link Worksheet.addBackgroundImage}, or
+     * {@link Worksheet.addWatermark} to place it.
+     *
+     * The image is either **embedded** or **linked (external)**:
+     *
+     * - **Embedded** — supply `buffer`, `base64`, or `filename`. The bytes are
+     *   written into the `.xlsx` package (`xl/media/imageN.ext`). Self-contained,
+     *   but inflates file size.
+     * - **Linked (external)** — supply only `link` (a URL or local file path).
+     *   No bytes are stored; the package keeps a relationship with
+     *   `TargetMode="External"` and the picture is rendered via `<a:blip r:link>`.
+     *   Keeps the file small, but the image is resolved by Excel at open time.
+     *
+     * If both bytes and a `link` are provided, **embedding wins**.
+     *
+     * Linked images work with **cell pictures** ({@link Worksheet.addImage}) and
+     * **overlay watermarks** ({@link Worksheet.addWatermark} with `mode:
+     * "overlay"`). Worksheet background images and header/footer (VML) watermarks
+     * cannot be linked — they require an embedded image.
+     *
+     * Note: Excel treats linked images as volatile — a moved/missing target
+     * shows a broken-image placeholder, and modern Excel may not auto-load
+     * remote URLs for security reasons. Prefer embedding for self-contained files.
+     *
+     * @example Embedded image
+     * ```typescript
+     * const id = workbook.addImage({ buffer: pngBytes, extension: "png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
+     *
+     * @example Linked (external) image — no bytes stored
+     * ```typescript
+     * const id = workbook.addImage({ extension: "png", link: "https://example.com/logo.png" });
+     * worksheet.addImage(id, "B2:D6");
+     * ```
      */
     addImage(image) {
         const id = this.media.length;

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

@@ -467,7 +467,12 @@ declare class Worksheet {
      */
     removeSparklineGroup(groupOrIndex: SparklineGroup | number): boolean;
     /**
-     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet.
+     *
+     * The image must be **embedded** (`buffer`/`base64`/`filename`). Worksheet
+     * background pictures (`<picture r:id>`) do not support external (linked)
+     * images — Excel silently drops a background whose relationship uses
+     * `TargetMode="External"`, so this rejects linked images up front.
      */
     addBackgroundImage(imageId: string | number): void;
     getBackgroundImageId(): string | undefined;
@@ -483,7 +488,14 @@ declare class Worksheet {
      *   Visible in Page Layout view and when printed. Renders behind cell content.
      *   Transparency must be baked into the image (PNG with alpha channel).
      *
+     * **External (linked) images:** `mode: "overlay"` supports external images
+     * (registered via `workbook.addImage({ link })`). `mode: "header"` does
+     * **not** — VML header/footer images require embedded media, so passing a
+     * linked image with `mode: "header"` throws an `ImageError`. Use an embedded
+     * image (`buffer`/`base64`/`filename`) or switch to `mode: "overlay"`.
+     *
      * @param options - Watermark configuration
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      *
      * @example Overlay watermark with transparency:
      * ```typescript

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

@@ -7,7 +7,7 @@ import { getChartSupport, tryGetChartSupport } from "./chart-host-registry.js";
 import { Column } from "./column.js";
 import { DataValidations } from "./data-validations.js";
 import { Enums } from "./enums.js";
-import { MergeConflictError, TableError } from "./errors.js";
+import { ImageError, MergeConflictError, TableError } from "./errors.js";
 import { FormCheckbox } from "./form-control.js";
 import { Image } from "./image.js";
 import { withPivotChartSource } from "./pivot-chart.js";
@@ -20,6 +20,7 @@ import { decodeCell, decodeRange, encodeCol } from "./utils/address.js";
 import { getCellDisplayText } from "./utils/cell-format.js";
 import { colCache } from "./utils/col-cache.js";
 import { copyStyle } from "./utils/copy-style.js";
+import { isExternalImage } from "./utils/drawing-utils.js";
 import { applyMergeBorders, collectMergeBorders } from "./utils/merge-borders.js";
 import { buildSheetProtection } from "./utils/sheet-protection.js";
 import { calculateAutoFitWidth, getMaxDigitWidth, getColumnContentWidthPx, getCellTextWidthPx, getCellHeightPt } from "./utils/text-metrics.js";
@@ -1306,9 +1307,20 @@ class Worksheet {
         return true;
     }
     /**
-     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet.
+     *
+     * The image must be **embedded** (`buffer`/`base64`/`filename`). Worksheet
+     * background pictures (`<picture r:id>`) do not support external (linked)
+     * images — Excel silently drops a background whose relationship uses
+     * `TargetMode="External"`, so this rejects linked images up front.
      */
     addBackgroundImage(imageId) {
+        const bookImage = this._workbook.getImage(imageId);
+        if (bookImage && isExternalImage(bookImage)) {
+            throw new ImageError("Background images cannot be external (linked) images. " +
+                "Use an embedded image (buffer/base64/filename). " +
+                "External images are only supported for cell pictures and overlay watermarks.");
+        }
         const model = {
             type: "background",
             imageId: String(imageId)
@@ -1333,7 +1345,14 @@ class Worksheet {
      *   Visible in Page Layout view and when printed. Renders behind cell content.
      *   Transparency must be baked into the image (PNG with alpha channel).
      *
+     * **External (linked) images:** `mode: "overlay"` supports external images
+     * (registered via `workbook.addImage({ link })`). `mode: "header"` does
+     * **not** — VML header/footer images require embedded media, so passing a
+     * linked image with `mode: "header"` throws an `ImageError`. Use an embedded
+     * image (`buffer`/`base64`/`filename`) or switch to `mode: "overlay"`.
+     *
      * @param options - Watermark configuration
+     * @throws {ImageError} If `mode: "header"` is used with an external (linked) image.
      *
      * @example Overlay watermark with transparency:
      * ```typescript
@@ -1348,11 +1367,23 @@ class Worksheet {
      * ```
      */
     addWatermark(options) {
+        const mode = options.mode ?? "overlay";
+        // Validate BEFORE mutating any state: VML header/footer images use
+        // embedded media (`<v:imagedata o:relid>`); external (linked) images are
+        // not representable here. Reject them up front so a failed call leaves the
+        // existing watermark untouched (no partial mutation).
+        if (mode === "header") {
+            const bookImage = this._workbook.getImage(options.imageId);
+            if (bookImage && isExternalImage(bookImage)) {
+                throw new ImageError("Header watermark images cannot be external (linked) images. " +
+                    "Use an embedded image (buffer/base64/filename), or use overlay mode for linked images.");
+            }
+        }
         // Remove any existing watermark media entries first
         this._media = this._media.filter(m => m.type !== "watermark" && m.type !== "headerImage");
         this._watermark = {
             imageId: String(options.imageId),
-            mode: options.mode ?? "overlay",
+            mode,
             opacity: options.opacity,
             headerWidth: options.headerWidth,
             headerHeight: options.headerHeight,
@@ -1368,7 +1399,7 @@ class Worksheet {
             this._media.push(new Image(this, model));
         }
         else {
-            // Header mode: add as a "headerImage" media entry for the VML pipeline
+            // Header mode: add as a "headerImage" media entry for the VML pipeline.
             const model = {
                 type: "headerImage",
                 imageId: String(options.imageId),

package/dist/browser/modules/excel/xlsx/xform/core/content-types-xform.js

@@ -1,3 +1,4 @@
+import { isExternalImage } from "../../../utils/drawing-utils.js";
 import { OOXML_PATHS, chartsheetPath, commentsPathFromName, ctrlPropPath, drawingPath, externalLinkPath, chartPath, chartUserShapesPath, chartExPath, chartStylePath, chartColorsPath, chartExStylePath, chartExColorsPath, pivotCacheDefinitionPath, pivotCacheRecordsPath, pivotTablePath, tablePath, toContentTypesPartName, worksheetPath } from "../../../utils/ooxml-paths.js";
 import { BaseXform } from "../base-xform.js";
 import { StdDocAttributes } from "../../../../xml/writer.js";
@@ -10,6 +11,11 @@ class ContentTypesXform extends BaseXform {
         const mediaHash = {};
         (model.media ?? []).forEach((medium) => {
             if (medium.type === "image") {
+                // External (linked) images add no part to the package, so they need
+                // no Default content-type registration.
+                if (isExternalImage(medium)) {
+                    return;
+                }
                 const imageType = medium.extension;
                 if (!mediaHash[imageType]) {
                     mediaHash[imageType] = true;

package/dist/browser/modules/excel/xlsx/xform/drawing/base-cell-anchor-xform.d.ts

@@ -9,5 +9,11 @@ declare abstract class BaseCellAnchorXform extends BaseXform {
     parseOpen(node: any): boolean;
     parseText(text: string): void;
     reconcilePicture(model: any, options: any): any;
+    /**
+     * Resolve (or create) the media entry for an external linked image. The
+     * synthesized entry is appended to `options.media` and indexed by its link
+     * so repeated references to the same external image share one entry.
+     */
+    private reconcileExternalPicture;
 }
 export { BaseCellAnchorXform };

package/dist/browser/modules/excel/xlsx/xform/drawing/base-cell-anchor-xform.js

@@ -1,3 +1,4 @@
+import { inferExternalImageExtension } from "../../../utils/drawing-utils.js";
 import { BaseXform } from "../base-xform.js";
 class BaseCellAnchorXform extends BaseXform {
     parseOpen(node) {
@@ -34,6 +35,13 @@ class BaseCellAnchorXform extends BaseXform {
             if (!rel) {
                 return undefined;
             }
+            // External (linked) image: the relationship uses TargetMode="External"
+            // and there is no media part in the package. Synthesize a media entry
+            // carrying the `link` target so it round-trips and surfaces on the
+            // worksheet as an external image. Entries are deduplicated by link.
+            if (rel.TargetMode === "External" || model.external) {
+                return this.reconcileExternalPicture(rel.Target, options);
+            }
             const match = rel.Target.match(/.*\/media\/(.+[.][a-zA-Z]{3,4})/);
             if (match) {
                 const name = match[1];
@@ -48,5 +56,29 @@ class BaseCellAnchorXform extends BaseXform {
         }
         return undefined;
     }
+    /**
+     * Resolve (or create) the media entry for an external linked image. The
+     * synthesized entry is appended to `options.media` and indexed by its link
+     * so repeated references to the same external image share one entry.
+     */
+    reconcileExternalPicture(link, options) {
+        if (!link) {
+            return undefined;
+        }
+        const indexKey = `external:${link}`;
+        let mediaId = options.mediaIndex[indexKey];
+        if (mediaId === undefined) {
+            mediaId = options.media.length;
+            const medium = {
+                type: "image",
+                extension: inferExternalImageExtension(link),
+                link,
+                index: mediaId
+            };
+            options.media.push(medium);
+            options.mediaIndex[indexKey] = mediaId;
+        }
+        return options.media[mediaId];
+    }
 }
 export { BaseCellAnchorXform };