@cj-tech-master/excelts 9.5.9 → 9.6.0

package/dist/iife/excelts.iife.js

@@ -1,5 +1,5 @@
 /*!
-* @cj-tech-master/excelts v9.5.9
+* @cj-tech-master/excelts v9.6.0
 * Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.
 * (c) 2026 cjnoname
 * Released under the MIT License
@@ -26215,7 +26215,7 @@ self.onmessage = async function(event) {
 			}
 			write(chunk, callback) {
 				if (this.ended) {
-					handleError(this, new Error(WRITE_AFTER_END_ERROR), callback);
+					handleError(this, /* @__PURE__ */ new Error(WRITE_AFTER_END_ERROR), callback);
 					return false;
 				}
 				if (chunk.byteLength === 0) {
@@ -26270,7 +26270,7 @@ self.onmessage = async function(event) {
 			}
 			write(chunk, callback) {
 				if (this.ended) {
-					handleError(this, new Error(WRITE_AFTER_END_ERROR), callback);
+					handleError(this, /* @__PURE__ */ new Error(WRITE_AFTER_END_ERROR), callback);
 					return false;
 				}
 				if (chunk.byteLength === 0) {
@@ -28457,6 +28457,55 @@ self.onmessage = async function(event) {
 		return mediaRelTargetFromRels(medium.name && medium.extension && medium.name.endsWith(`.${medium.extension}`) ? medium.name : `${medium.name}.${medium.extension}`);
 	}
 	/**
+	* 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);
+		switch (match ? match[1].toLowerCase() : "") {
+			case "jpg":
+			case "jpeg": return "jpeg";
+			case "gif": return "gif";
+			default: return "png";
+		}
+	}
+	/**
+	* 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: 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.
 	*
 	* This is the core logic shared between:
@@ -28474,18 +28523,18 @@ self.onmessage = async function(event) {
 			const imageId = String(medium.imageId);
 			const bookImage = options.getBookImage(medium.imageId);
 			if (!bookImage) continue;
+			const isExternal = isExternalImage(bookImage);
 			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 },
+				picture: {
+					rId: rIdImage,
+					...isExternal ? { external: true } : {}
+				},
 				range: medium.range
 			};
 			if (medium.opacity !== void 0) {
@@ -32181,6 +32230,8 @@ self.onmessage = async function(event) {
 				else this.conditionalFormatting = [];
 			}
 			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) };
 			}
 			getBackgroundImageId() {
@@ -32204,13 +32255,24 @@ self.onmessage = async function(event) {
 			/**
 			* 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";
+				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.");
+				}
 				this._media = this._media.filter((m) => m._watermarkTag !== true);
 				const opacity = options.opacity !== void 0 ? Math.max(0, Math.min(1, options.opacity)) : .15;
 				this._watermark = {
 					imageId: String(options.imageId),
-					mode: options.mode ?? "overlay",
+					mode,
 					opacity,
 					headerWidth: options.headerWidth,
 					headerHeight: options.headerHeight,
@@ -33110,6 +33172,7 @@ self.onmessage = async function(event) {
 	//#region src/modules/excel/xlsx/xform/core/content-types-xform.ts
 	var ContentTypesXform;
 	var init_content_types_xform = __esmMin((() => {
+		init_drawing_utils();
 		init_ooxml_paths();
 		init_base_xform();
 		init_writer();
@@ -33120,6 +33183,7 @@ self.onmessage = async function(event) {
 				const mediaHash = {};
 				(model.media ?? []).forEach((medium) => {
 					if (medium.type === "image") {
+						if (isExternalImage(medium)) return;
 						const imageType = medium.extension;
 						if (!mediaHash[imageType]) {
 							mediaHash[imageType] = true;
@@ -33525,6 +33589,7 @@ self.onmessage = async function(event) {
 	//#region src/modules/excel/xlsx/xform/drawing/base-cell-anchor-xform.ts
 	var BaseCellAnchorXform;
 	var init_base_cell_anchor_xform = __esmMin((() => {
+		init_drawing_utils();
 		init_base_xform();
 		BaseCellAnchorXform = class extends BaseXform {
 			parseOpen(node) {
@@ -33551,6 +33616,7 @@ self.onmessage = async function(event) {
 				if (model && model.rId) {
 					const rel = options.rels[model.rId];
 					if (!rel) return;
+					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];
@@ -33564,6 +33630,28 @@ self.onmessage = async function(event) {
 					}
 				}
 			}
+			/**
+			* 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;
+				const indexKey = `external:${link}`;
+				let mediaId = options.mediaIndex[indexKey];
+				if (mediaId === void 0) {
+					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];
+			}
 		};
 	}));
 	//#endregion
@@ -33785,25 +33873,32 @@ self.onmessage = async function(event) {
 				return "a:blip";
 			}
 			render(xmlStream, model) {
+				const relAttr = model.external ? "r:link" : "r:embed";
 				if (model.alphaModFix !== void 0 && model.alphaModFix < 1e5) {
 					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) });
 					xmlStream.closeNode();
 				} 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: {
+						const link = node.attributes["r:link"];
+						if (link !== void 0) 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);
 						return true;
@@ -34143,7 +34238,8 @@ self.onmessage = async function(event) {
 				this.map["xdr:nvPicPr"].render(xmlStream, model);
 				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();
@@ -35435,6 +35531,23 @@ self.onmessage = async function(event) {
 				for (let i = 1; i < this._worksheets.length; i++) if (!this._worksheets[i]) return i;
 				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 = {
@@ -35558,6 +35671,7 @@ self.onmessage = async function(event) {
 			addMedia() {
 				return Promise.all(this.media.map(async (medium) => {
 					if (medium.type === "image") {
+						if (isExternalImage(medium)) return;
 						const filename = mediaPath(medium.name);
 						if (medium.buffer) {
 							this._addFile(medium.buffer, filename);
@@ -41344,6 +41458,7 @@ self.onmessage = async function(event) {
 		init_cell_format();
 		init_col_cache();
 		init_copy_style();
+		init_drawing_utils();
 		init_merge_borders();
 		init_sheet_protection();
 		init_text_metrics();
@@ -42320,9 +42435,16 @@ self.onmessage = async function(event) {
 				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)
@@ -42345,7 +42467,14 @@ self.onmessage = async function(event) {
 			*   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
@@ -42360,10 +42489,15 @@ self.onmessage = async function(event) {
 			* ```
 			*/
 			addWatermark(options) {
+				const mode = options.mode ?? "overlay";
+				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.");
+				}
 				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,
@@ -51104,15 +51238,16 @@ self.onmessage = async function(event) {
 					else if (medium.type === "headerImage") headerImageMedia.push(medium);
 				});
 				backgroundMedia.forEach((medium) => {
-					const rId = nextRid(rels);
 					const bookImage = options.media[medium.imageId];
+					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;
 				});
 				if (imageMedia.length > 0) {
 					let { drawing } = model;
@@ -51156,12 +51291,9 @@ self.onmessage = async function(event) {
 					for (const medium of watermarkMedia) {
 						const bookImage = options.media[medium.imageId];
 						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));
 						const rawOpacity = medium.opacity !== void 0 ? medium.opacity : .15;
 						const alphaModFix = Math.round(Math.max(0, Math.min(1, rawOpacity)) * 1e5);
 						const dims = model.dimensions;
@@ -51170,7 +51302,8 @@ self.onmessage = async function(event) {
 						drawing.anchors.push({
 							picture: {
 								rId: rIdImage,
-								alphaModFix
+								alphaModFix,
+								...isExternal ? { external: true } : {}
 							},
 							range: {
 								editAs: "absolute",
@@ -55095,6 +55228,7 @@ self.onmessage = async function(event) {
 			async addMedia(zip, model) {
 				await Promise.all(model.media.map(async (medium) => {
 					if (medium.type !== "image") throw new ImageError("Unsupported media");
+					if (isExternalImage(medium)) return;
 					const filename = mediaPath(`${medium.name ?? "undefined"}.${medium.extension}`);
 					if (medium.filename) {
 						if (this.readFileAsync) {
@@ -58243,7 +58377,42 @@ self.onmessage = async function(event) {
 				this._themes = void 0;
 			}
 			/**
-			* 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;