@cj-tech-master/excelts 9.5.9 → 9.6.0

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

@@ -410,17 +410,23 @@ class WorkSheetXform extends base_xform_1.BaseXform {
                 headerImageMedia.push(medium);
             }
         });
-        // Handle background images
+        // Handle background images. Background pictures are always embedded —
+        // external (linked) images are rejected in addBackgroundImage because Excel
+        // drops a background whose relationship uses TargetMode="External".
         backgroundMedia.forEach(medium => {
-            const rId = nextRid(rels);
             const bookImage = options.media[medium.imageId];
+            // Guard against an invalid imageId — same as the image/watermark paths.
+            if (!bookImage) {
+                return;
+            }
+            const rId = nextRid(rels);
             rels.push({
                 Id: rId,
                 Type: rel_type_1.RelType.Image,
                 Target: (0, drawing_utils_1.resolveMediaTarget)(bookImage)
             });
             model.background = { rId };
-            model.image = options.media[medium.imageId];
+            model.image = bookImage;
         });
         // Handle embedded images — create drawing model using shared utility
         if (imageMedia.length > 0) {
@@ -468,12 +474,9 @@ class WorkSheetXform extends base_xform_1.BaseXform {
                 if (!bookImage) {
                     continue;
                 }
+                const isExternal = (0, drawing_utils_1.isExternalImage)(bookImage);
                 const rIdImage = nextRid(drawing.rels);
-                drawing.rels.push({
-                    Id: rIdImage,
-                    Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
-                    Target: (0, drawing_utils_1.resolveMediaTarget)(bookImage)
-                });
+                drawing.rels.push((0, drawing_utils_1.buildImageRel)(rIdImage, 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));
@@ -486,7 +489,8 @@ class WorkSheetXform extends base_xform_1.BaseXform {
                 drawing.anchors.push({
                     picture: {
                         rId: rIdImage,
-                        alphaModFix
+                        alphaModFix,
+                        ...(isExternal ? { external: true } : {})
                     },
                     // Cover the full data area with extra margin
                     range: {

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

@@ -4287,6 +4287,12 @@ class XLSX {
             if (medium.type !== "image") {
                 throw new errors_1.ImageError("Unsupported media");
             }
+            // External (linked) images carry only a `link` target — no bytes are
+            // written into the package; the relationship (TargetMode="External")
+            // references the image in place.
+            if ((0, drawing_utils_1.isExternalImage)(medium)) {
+                return;
+            }
             // Preserve legacy behavior: `${undefined}` becomes "undefined" in template strings
             const mediaName = medium.name ?? "undefined";
             const filename = (0, ooxml_paths_1.mediaPath)(`${mediaName}.${medium.extension}`);

package/dist/esm/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/esm/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.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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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 };

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

@@ -8,11 +8,13 @@ class BlipXform extends BaseXform {
         return "a:blip";
     }
     render(xmlStream, model) {
+        // External (linked) images use `r:link`; embedded images use `r:embed`.
+        const relAttr = model.external ? "r:link" : "r:embed";
         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,
+                [relAttr]: model.rId,
                 cstate: "print"
             });
             xmlStream.leafNode("a:alphaModFix", { amt: String(model.alphaModFix) });
@@ -21,18 +23,24 @@ class BlipXform extends BaseXform {
         else {
             xmlStream.leafNode(this.tag, {
                 "xmlns:r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
-                "r:embed": model.rId,
+                [relAttr]: model.rId,
                 cstate: "print"
             });
         }
     }
     parseOpen(node) {
         switch (node.name) {
-            case this.tag:
-                this.model = {
-                    rId: node.attributes["r:embed"]
-                };
+            case this.tag: {
+                // A blip may carry `r:embed` (embedded) or `r:link` (external linked).
+                const link = node.attributes["r:link"];
+                if (link !== undefined) {
+                    this.model = { rId: link, external: true };
+                }
+                else {
+                    this.model = { rId: node.attributes["r:embed"] };
+                }
                 return true;
+            }
             case "a:alphaModFix":
                 if (node.attributes.amt) {
                     this.model.alphaModFix = parseInt(node.attributes.amt, 10);

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

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

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

@@ -1,5 +1,5 @@
 import { colCache } from "../../../utils/col-cache.js";
-import { buildDrawingAnchorsAndRels, resolveMediaTarget } from "../../../utils/drawing-utils.js";
+import { buildDrawingAnchorsAndRels, buildImageRel, isExternalImage, resolveMediaTarget } from "../../../utils/drawing-utils.js";
 import { chartRelTargetFromDrawing, chartExRelTargetFromDrawing, commentsRelTargetFromWorksheet, ctrlPropRelTargetFromWorksheet, drawingRelTargetFromWorksheet, pivotTableRelTargetFromWorksheet, resolveRelTarget, tableRelTargetFromWorksheet, vmlDrawingRelTargetFromWorksheet, vmlDrawingHFRelTargetFromWorksheet } from "../../../utils/ooxml-paths.js";
 import { RelType } from "../../rel-type.js";
 import { BaseXform } from "../base-xform.js";
@@ -407,17 +407,23 @@ class WorkSheetXform extends BaseXform {
                 headerImageMedia.push(medium);
             }
         });
-        // Handle background images
+        // Handle background images. Background pictures are always embedded —
+        // external (linked) images are rejected in addBackgroundImage because Excel
+        // drops a background whose relationship uses TargetMode="External".
         backgroundMedia.forEach(medium => {
-            const rId = nextRid(rels);
             const bookImage = options.media[medium.imageId];
+            // Guard against an invalid imageId — same as the image/watermark paths.
+            if (!bookImage) {
+                return;
+            }
+            const rId = nextRid(rels);
             rels.push({
                 Id: rId,
                 Type: RelType.Image,
                 Target: resolveMediaTarget(bookImage)
             });
             model.background = { rId };
-            model.image = options.media[medium.imageId];
+            model.image = bookImage;
         });
         // Handle embedded images — create drawing model using shared utility
         if (imageMedia.length > 0) {
@@ -465,12 +471,9 @@ class WorkSheetXform extends BaseXform {
                 if (!bookImage) {
                     continue;
                 }
+                const isExternal = isExternalImage(bookImage);
                 const rIdImage = nextRid(drawing.rels);
-                drawing.rels.push({
-                    Id: rIdImage,
-                    Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
-                    Target: resolveMediaTarget(bookImage)
-                });
+                drawing.rels.push(buildImageRel(rIdImage, 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));
@@ -483,7 +486,8 @@ class WorkSheetXform extends BaseXform {
                 drawing.anchors.push({
                     picture: {
                         rId: rIdImage,
-                        alphaModFix
+                        alphaModFix,
+                        ...(isExternal ? { external: true } : {})
                     },
                     // Cover the full data area with extra margin
                     range: {

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

@@ -16,7 +16,7 @@ import { StreamingZip, ZipDeflateFile } from "../../archive/zip/stream.js";
 // erased at runtime; runtime entry points route through `getChartSupport()`.
 import { getChartSupport } from "../chart-host-registry.js";
 import { ExcelStreamStateError, ExcelFileError, ImageError, ExcelNotSupportedError, XmlParseError, TableError, ChartOptionsError } from "../errors.js";
-import { filterDrawingAnchors } from "../utils/drawing-utils.js";
+import { filterDrawingAnchors, isExternalImage } from "../utils/drawing-utils.js";
 import { rewriteExternalRefs } from "../utils/external-link-formula.js";
 import { commentsPath, chartsheetPath, chartsheetRelsPath, getChartsheetNoFromPath, getChartsheetNoFromRelsPath, ctrlPropPath, drawingPath, drawingRelsPath, externalLinkPath, externalLinkRelsPath, externalLinkRelTargetFromWorkbook, OOXML_REL_TARGETS, pivotCacheDefinitionRelTargetFromWorkbook, pivotTablePathFromName, isCommentsPath, chartPath, chartRelsPath, chartStylePath, chartColorsPath, chartExStylePath, chartExColorsPath, chartStyleRelTarget, chartExStyleRelTarget, chartExPath, chartExRelsPath, getChartExNumberFromPath, getChartExNumberFromRelsPath, chartColorsRelTarget, chartExColorsRelTarget, chartRelTargetFromDrawing, chartExRelTargetFromDrawing, chartUserShapesPath, chartUserShapesRelTarget, getChartNumberFromPath, getChartNumberFromRelsPath, getChartStyleNumberFromPath, getChartColorsNumberFromPath, getChartExStyleNumberFromPath, getChartExColorsNumberFromPath, getDrawingNameFromPath, getChartUserShapesNameFromPath, getDrawingNameFromRelsPath, getExternalLinkIndexFromPath, getExternalLinkIndexFromRelsPath, getMediaFilenameFromPath, mediaPath, getPivotCacheDefinitionNameFromPath, getPivotCacheDefinitionNameFromRelsPath, getPivotCacheRecordsNameFromPath, getPivotTableNameFromPath, getPivotTableNameFromRelsPath, pivotCacheDefinitionPath, pivotCacheDefinitionRelsPath, pivotCacheDefinitionRelTargetFromPivotTable, pivotCacheRecordsPath, pivotCacheRecordsRelTarget, pivotTablePath, pivotTableRelsPath, getTableNameFromPath, tablePath, themePath, getThemeNameFromPath, getVmlDrawingNameFromPath, getVmlDrawingHFNameFromPath, getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, isBinaryEntryPath, normalizeZipPath, OOXML_PATHS, resolveRelTarget, vmlDrawingPath, vmlDrawingHFPath, vmlDrawingHFRelsPath, worksheetPath, worksheetRelsPath, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { validateXlsxBuffer } from "../utils/ooxml-validator/index.js";
@@ -4284,6 +4284,12 @@ class XLSX {
             if (medium.type !== "image") {
                 throw new ImageError("Unsupported media");
             }
+            // External (linked) images carry only a `link` target — no bytes are
+            // written into the package; the relationship (TargetMode="External")
+            // references the image in place.
+            if (isExternalImage(medium)) {
+                return;
+            }
             // Preserve legacy behavior: `${undefined}` becomes "undefined" in template strings
             const mediaName = medium.name ?? "undefined";
             const filename = mediaPath(`${mediaName}.${medium.extension}`);