@cj-tech-master/excelts 9.5.9 → 9.6.0

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

@@ -3,6 +3,11 @@ interface BlipModel {
     rId: string;
     /** Alpha modulation (opacity) as OOXML percentage (e.g. 15000 = 15%). */
     alphaModFix?: number;
+    /**
+     * When true, the blip references an external linked image via `r:link`
+     * instead of an embedded one via `r:embed`.
+     */
+    external?: boolean;
 }
 declare class BlipXform extends BaseXform<BlipModel> {
     constructor();

package/dist/browser/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/browser/modules/excel/xlsx/xform/drawing/pic-xform.d.ts

@@ -4,6 +4,8 @@ interface PicModel {
     rId?: string;
     /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
     alphaModFix?: number;
+    /** When true, render the picture as an external linked image (`r:link`). */
+    external?: boolean;
     [key: string]: any;
 }
 declare class PicXform extends BaseXform {

package/dist/browser/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/browser/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/browser/modules/excel/xlsx/xlsx.browser.d.ts

@@ -187,6 +187,8 @@ export interface WorkbookMediaLike {
     filename?: string;
     buffer?: Uint8Array;
     base64?: string;
+    /** External link target — when set, the image is referenced, not embedded. */
+    link?: string;
 }
 export interface MediaModel {
     media: WorkbookMediaLike[];

package/dist/browser/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}`);

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

@@ -372,6 +372,23 @@ 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 = {
@@ -489,6 +506,11 @@ 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 ((0, drawing_utils_1.isExternalImage)(medium)) {
+                    return;
+                }
                 const filename = (0, ooxml_paths_1.mediaPath)(medium.name);
                 if (medium.buffer) {
                     this._addFile(medium.buffer, filename);

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

@@ -9,6 +9,7 @@ exports.WorkbookWriter = void 0;
 const errors_1 = require("../errors.js");
 const workbook_writer_browser_1 = require("./workbook-writer.browser.js");
 const worksheet_writer_1 = require("./worksheet-writer.js");
+const drawing_utils_1 = require("../utils/drawing-utils.js");
 const ooxml_paths_1 = require("../utils/ooxml-paths.js");
 const fs_1 = require("../../../utils/fs.js");
 class WorkbookWriter extends workbook_writer_browser_1.WorkbookWriterBase {
@@ -30,6 +31,11 @@ class WorkbookWriter extends workbook_writer_browser_1.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 ((0, drawing_utils_1.isExternalImage)(medium)) {
+                    return;
+                }
                 const filename = (0, ooxml_paths_1.mediaPath)(medium.name);
                 // Node.js: support loading from file
                 if (medium.filename) {

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

@@ -443,6 +443,12 @@ class WorksheetWriter {
     }
     // =========================================================================
     addBackgroundImage(imageId) {
+        const bookImage = this._workbook.getImage(Number(imageId));
+        if (bookImage && (0, drawing_utils_1.isExternalImage)(bookImage)) {
+            throw new errors_1.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)
         };
@@ -472,14 +478,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 && (0, drawing_utils_1.isExternalImage)(bookImage)) {
+                throw new errors_1.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,
@@ -797,6 +821,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: (0, ooxml_paths_1.mediaRelTargetFromRels)(image.name),
                     Type: rel_type_1.RelType.Image

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

@@ -8,6 +8,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveMediaTarget = resolveMediaTarget;
+exports.isExternalImage = isExternalImage;
+exports.inferExternalImageExtension = inferExternalImageExtension;
+exports.buildImageRel = buildImageRel;
 exports.buildDrawingAnchorsAndRels = buildDrawingAnchorsAndRels;
 exports.filterDrawingAnchors = filterDrawingAnchors;
 const ooxml_paths_1 = require("./ooxml-paths.js");
@@ -31,6 +34,65 @@ function resolveMediaTarget(medium) {
         : `${medium.name}.${medium.extension}`;
     return (0, ooxml_paths_1.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.
+ */
+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`.
+ */
+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.
+ */
+function buildImageRel(rId, bookImage) {
+    if (isExternalImage(bookImage)) {
+        return {
+            Id: rId,
+            Type: rel_type_1.RelType.Image,
+            Target: bookImage.link,
+            TargetMode: "External"
+        };
+    }
+    return {
+        Id: rId,
+        Type: rel_type_1.RelType.Image,
+        Target: resolveMediaTarget(bookImage)
+    };
+}
 /**
  * Build the drawing anchors and relationships from a list of image media entries.
  *
@@ -52,20 +114,19 @@ 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/cjs/modules/excel/workbook.browser.js

@@ -1700,7 +1700,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/cjs/modules/excel/worksheet.js

@@ -23,6 +23,7 @@ const address_1 = require("./utils/address.js");
 const cell_format_1 = require("./utils/cell-format.js");
 const col_cache_1 = require("./utils/col-cache.js");
 const copy_style_1 = require("./utils/copy-style.js");
+const drawing_utils_1 = require("./utils/drawing-utils.js");
 const merge_borders_1 = require("./utils/merge-borders.js");
 const sheet_protection_1 = require("./utils/sheet-protection.js");
 const text_metrics_1 = require("./utils/text-metrics.js");
@@ -1309,9 +1310,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 && (0, drawing_utils_1.isExternalImage)(bookImage)) {
+            throw new errors_1.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)
@@ -1336,7 +1348,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
@@ -1351,11 +1370,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 && (0, drawing_utils_1.isExternalImage)(bookImage)) {
+                throw new errors_1.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,
@@ -1371,7 +1402,7 @@ class Worksheet {
             this._media.push(new image_1.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/cjs/modules/excel/xlsx/xform/core/content-types-xform.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContentTypesXform = void 0;
+const drawing_utils_1 = require("../../../utils/drawing-utils.js");
 const ooxml_paths_1 = require("../../../utils/ooxml-paths.js");
 const base_xform_1 = require("../base-xform.js");
 const writer_1 = require("../../../../xml/writer.js");
@@ -13,6 +14,11 @@ class ContentTypesXform extends base_xform_1.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 ((0, drawing_utils_1.isExternalImage)(medium)) {
+                    return;
+                }
                 const imageType = medium.extension;
                 if (!mediaHash[imageType]) {
                     mediaHash[imageType] = true;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCellAnchorXform = void 0;
+const drawing_utils_1 = require("../../../utils/drawing-utils.js");
 const base_xform_1 = require("../base-xform.js");
 class BaseCellAnchorXform extends base_xform_1.BaseXform {
     parseOpen(node) {
@@ -37,6 +38,13 @@ class BaseCellAnchorXform extends base_xform_1.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];
@@ -51,5 +59,29 @@ class BaseCellAnchorXform extends base_xform_1.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: (0, drawing_utils_1.inferExternalImageExtension)(link),
+                link,
+                index: mediaId
+            };
+            options.media.push(medium);
+            options.mediaIndex[indexKey] = mediaId;
+        }
+        return options.media[mediaId];
+    }
 }
 exports.BaseCellAnchorXform = BaseCellAnchorXform;

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

@@ -11,11 +11,13 @@ class BlipXform extends base_xform_1.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) });
@@ -24,18 +26,24 @@ class BlipXform extends base_xform_1.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/cjs/modules/excel/xlsx/xform/drawing/pic-xform.js

@@ -27,7 +27,8 @@ class PicXform extends base_xform_1.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();