@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/iife/excelts.iife.js

@@ -1,5 +1,5 @@
 /*!
-* @cj-tech-master/excelts v9.6.1
+* @cj-tech-master/excelts v10.0.0
 * Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.
 * (c) 2026 cjnoname
 * Released under the MIT License
@@ -17695,7 +17695,8 @@ onmessage = async (ev) => {
 			set model(value) {
 				const { note } = value;
 				const { texts } = note;
-				if (texts && texts.length === 1 && Object.keys(texts[0]).length === 1) this.note = texts[0].text;
+				const hasCustomSize = note.width !== void 0 || note.height !== void 0;
+				if (texts && texts.length === 1 && Object.keys(texts[0]).length === 1 && !hasCustomSize) this.note = texts[0].text;
 				else this.note = note;
 				this.author = value.author;
 			}
@@ -19865,6 +19866,30 @@ onmessage = async (ev) => {
 	}));
 	//#endregion
 	//#region src/modules/excel/row.ts
+	/**
+	* Resolve a column key against a row object, supporting dotted nested paths.
+	*
+	* A key without a `.` takes the original fast path (`obj[key]`), preserving
+	* exact backward compatibility — including keys that legitimately contain a
+	* dot only as a flat property name, which still resolve via the fast path
+	* first. A dotted key (e.g. `"address.city"`) is resolved by walking each
+	* segment; if any segment is missing or not an object, the result is
+	* `undefined` (the same signal the caller already uses to skip a cell).
+	*
+	* @param obj - The row object supplied to `row.values = {...}` / `addRow({...})`.
+	* @param key - The column key, optionally a dotted path.
+	* @returns The resolved value, or `undefined` when the path cannot be followed.
+	*/
+	function resolveColumnKeyValue(obj, key) {
+		const direct = obj[key];
+		if (direct !== void 0 || !key.includes(".")) return direct;
+		let current = obj;
+		for (const segment of key.split(".")) {
+			if (current === null || typeof current !== "object") return;
+			current = current[segment];
+		}
+		return current;
+	}
 	var Row;
 	var init_row = __esmMin((() => {
 		init_cell();
@@ -20031,11 +20056,12 @@ onmessage = async (ev) => {
 						}).value = item;
 					});
 				} else this._worksheet.eachColumnKey((column, key) => {
-					if (value[key] !== void 0) this.getCellEx({
+					const resolved = resolveColumnKeyValue(value, key);
+					if (resolved !== void 0) this.getCellEx({
 						address: colCache.encodeAddress(this._number, column.number),
 						row: this._number,
 						col: column.number
-					}).value = value[key];
+					}).value = resolved;
 				});
 			}
 			/**
@@ -28148,11 +28174,13 @@ self.onmessage = async function(event) {
 	}));
 	//#endregion
 	//#region src/modules/excel/xlsx/xform/comment/vml-shape-xform.ts
-	var VmlShapeXform;
+	var DEFAULT_NOTE_WIDTH_PT, DEFAULT_NOTE_HEIGHT_PT, VmlShapeXform;
 	var init_vml_shape_xform = __esmMin((() => {
 		init_base_xform();
 		init_vml_client_data_xform();
 		init_vml_textbox_xform();
+		DEFAULT_NOTE_WIDTH_PT = 97.8;
+		DEFAULT_NOTE_HEIGHT_PT = 59.1;
 		VmlShapeXform = class VmlShapeXform extends BaseXform {
 			constructor() {
 				super();
@@ -28190,6 +28218,13 @@ self.onmessage = async function(event) {
 							editAs: "",
 							protection: {}
 						};
+						{
+							const style = node.attributes.style ?? "";
+							const width = VmlShapeXform.parseStyleLength(style, "width");
+							const height = VmlShapeXform.parseStyleLength(style, "height");
+							if (width !== void 0 && width !== DEFAULT_NOTE_WIDTH_PT) this.model.width = width;
+							if (height !== void 0 && height !== DEFAULT_NOTE_HEIGHT_PT) this.model.height = height;
+						}
 						break;
 					default:
 						this.parser = this.map[node.name];
@@ -28220,15 +28255,29 @@ self.onmessage = async function(event) {
 					default: return true;
 				}
 			}
+			/**
+			* Extract a points-valued length (e.g. `width:120pt`) from a VML style
+			* string. Returns `undefined` when the property is absent or not in `pt`.
+			*/
+			static parseStyleLength(style, prop) {
+				const match = new RegExp(`(?:^|;)\\s*${prop}\\s*:\\s*([0-9.]+)pt`, "i").exec(style);
+				if (!match) return;
+				const value = parseFloat(match[1]);
+				return Number.isFinite(value) ? value : void 0;
+			}
 			static {
-				this.V_SHAPE_ATTRIBUTES = (model, index) => ({
-					id: `_x0000_s${1025 + index}`,
-					type: "#_x0000_t202",
-					style: "position:absolute; margin-left:105.3pt;margin-top:10.5pt;width:97.8pt;height:59.1pt;z-index:1;visibility:hidden",
-					fillcolor: "infoBackground [80]",
-					strokecolor: "none [81]",
-					"o:insetmode": model.note.margins && model.note.margins.insetmode
-				});
+				this.V_SHAPE_ATTRIBUTES = (model, index) => {
+					const width = model.note?.width ?? DEFAULT_NOTE_WIDTH_PT;
+					const height = model.note?.height ?? DEFAULT_NOTE_HEIGHT_PT;
+					return {
+						id: `_x0000_s${1025 + index}`,
+						type: "#_x0000_t202",
+						style: `position:absolute; margin-left:105.3pt;margin-top:10.5pt;width:${width}pt;height:${height}pt;z-index:1;visibility:hidden`,
+						fillcolor: "infoBackground [80]",
+						strokecolor: "none [81]",
+						"o:insetmode": model.note.margins && model.note.margins.insetmode
+					};
+				};
 			}
 		};
 	}));
@@ -28549,6 +28598,19 @@ self.onmessage = async function(event) {
 				},
 				range: medium.range
 			};
+			if (bookImage.svgMediaId !== void 0) {
+				const svgKey = `svg:${bookImage.svgMediaId}`;
+				let rIdSvg = imageRIdMap[svgKey];
+				if (!rIdSvg) {
+					const svgImage = options.getBookImage(bookImage.svgMediaId);
+					if (svgImage) {
+						rIdSvg = options.nextRId(rels);
+						imageRIdMap[svgKey] = rIdSvg;
+						rels.push(buildImageRel(rIdSvg, svgImage));
+					}
+				}
+				if (rIdSvg) anchor.picture.svgRId = rIdSvg;
+			}
 			if (medium.opacity !== void 0) {
 				const clamped = Math.max(0, Math.min(1, medium.opacity));
 				anchor.picture.alphaModFix = Math.round(clamped * 1e5);
@@ -28584,7 +28646,7 @@ self.onmessage = async function(event) {
 			if (a == null) return false;
 			if (a.range?.pos !== void 0) return !!a.picture || !!a.graphicFrame || !!a.shape;
 			if (a.range?.br && a.shape) return true;
-			if (!a.range?.br && !a.picture && !a.graphicFrame) return false;
+			if (!a.range?.br && !a.picture && !a.graphicFrame && !a.shape) return false;
 			if (a.range?.br && !a.picture && !a.shape && !a.graphicFrame) return false;
 			return true;
 		});
@@ -33201,7 +33263,7 @@ self.onmessage = async function(event) {
 							mediaHash[imageType] = true;
 							xmlStream.leafNode("Default", {
 								Extension: imageType,
-								ContentType: `image/${imageType}`
+								ContentType: imageType === "svg" ? "image/svg+xml" : `image/${imageType}`
 							});
 						}
 					}
@@ -33634,7 +33696,16 @@ self.onmessage = async function(event) {
 						const name = match[1];
 						const mediaId = options.mediaIndex[name];
 						const medium = options.media[mediaId];
-						if (medium && model.alphaModFix !== void 0) return {
+						if (!medium) return;
+						if (model.svgRId) {
+							const svgRel = options.rels[model.svgRId];
+							const svgMatch = svgRel && svgRel.Target.match(/.*\/media\/(.+[.][a-zA-Z]{3,4})/);
+							if (svgMatch) {
+								const svgMediaId = options.mediaIndex[svgMatch[1]];
+								if (svgMediaId !== void 0) medium.svgMediaId = svgMediaId;
+							}
+						}
+						if (model.alphaModFix !== void 0) return {
 							...medium,
 							alphaModFix: model.alphaModFix
 						};
@@ -33873,9 +33944,12 @@ self.onmessage = async function(event) {
 	}));
 	//#endregion
 	//#region src/modules/excel/xlsx/xform/drawing/blip-xform.ts
-	var BlipXform;
+	var SVG_BLIP_EXT_URI, SVG_BLIP_NS, REL_NS, BlipXform;
 	var init_blip_xform = __esmMin((() => {
 		init_base_xform();
+		SVG_BLIP_EXT_URI = "{96DAC541-7B7A-43D3-8B79-37D633B846F1}";
+		SVG_BLIP_NS = "http://schemas.microsoft.com/office/drawing/2016/SVG/main";
+		REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
 		BlipXform = class extends BaseXform {
 			constructor() {
 				super();
@@ -33886,19 +33960,33 @@ self.onmessage = async function(event) {
 			}
 			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",
+				const hasAlpha = model.alphaModFix !== void 0 && model.alphaModFix < 1e5;
+				const hasSvg = model.svgRId !== void 0;
+				if (!hasAlpha && !hasSvg) {
+					xmlStream.leafNode(this.tag, {
+						"xmlns:r": REL_NS,
 						[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",
+					return;
+				}
+				xmlStream.openNode(this.tag, {
+					"xmlns:r": REL_NS,
 					[relAttr]: model.rId,
 					cstate: "print"
 				});
+				if (hasAlpha) xmlStream.leafNode("a:alphaModFix", { amt: String(model.alphaModFix) });
+				if (hasSvg) {
+					xmlStream.openNode("a:extLst");
+					xmlStream.openNode("a:ext", { uri: SVG_BLIP_EXT_URI });
+					xmlStream.leafNode("asvg:svgBlip", {
+						"xmlns:asvg": SVG_BLIP_NS,
+						"r:embed": model.svgRId
+					});
+					xmlStream.closeNode();
+					xmlStream.closeNode();
+				}
+				xmlStream.closeNode();
 			}
 			parseOpen(node) {
 				switch (node.name) {
@@ -33914,6 +34002,11 @@ self.onmessage = async function(event) {
 					case "a:alphaModFix":
 						if (node.attributes.amt) this.model.alphaModFix = parseInt(node.attributes.amt, 10);
 						return true;
+					case "asvg:svgBlip": {
+						const embed = node.attributes["r:embed"];
+						if (embed !== void 0 && this.model) this.model.svgRId = embed;
+						return true;
+					}
 					default: return true;
 				}
 			}
@@ -34251,7 +34344,8 @@ self.onmessage = async function(event) {
 				this.map["xdr:blipFill"].render(xmlStream, {
 					rId: model.rId,
 					alphaModFix: model.alphaModFix,
-					external: model.external
+					external: model.external,
+					svgRId: model.svgRId
 				});
 				this.map["xdr:spPr"].render(xmlStream, model);
 				xmlStream.closeNode();
@@ -34289,6 +34383,105 @@ self.onmessage = async function(event) {
 		};
 	}));
 	//#endregion
+	//#region src/modules/excel/xlsx/xform/drawing/shape-xform.ts
+	/**
+	* Normalize a user-supplied colour to the bare 6-digit RGB hex that OOXML's
+	* `<a:srgbClr val="...">` requires:
+	* - strips a leading `#`
+	* - accepts 8-digit ARGB (the form excelts uses for cell fills) and drops the
+	*   leading alpha byte, since `srgbClr` carries no alpha channel
+	* - upper-cases
+	*
+	* Anything that isn't a 6- or 8-digit hex string is passed through unchanged so
+	* a caller using a less common form is not silently broken.
+	*/
+	function normalizeColor(color) {
+		const hex = color.startsWith("#") ? color.slice(1) : color;
+		if (/^[0-9a-fA-F]{8}$/.test(hex)) return hex.slice(2).toUpperCase();
+		if (/^[0-9a-fA-F]{6}$/.test(hex)) return hex.toUpperCase();
+		return hex;
+	}
+	var EMU_PER_POINT$1, ShapeXform;
+	var init_shape_xform = __esmMin((() => {
+		init_base_xform();
+		EMU_PER_POINT$1 = 12700;
+		ShapeXform = class extends BaseXform {
+			get tag() {
+				return "xdr:sp";
+			}
+			render(xmlStream, model) {
+				xmlStream.openNode("xdr:sp", {
+					macro: "",
+					textlink: ""
+				});
+				xmlStream.openNode("xdr:nvSpPr");
+				xmlStream.leafNode("xdr:cNvPr", {
+					id: model.cNvPrId,
+					name: model.name
+				});
+				xmlStream.leafNode("xdr:cNvSpPr", {});
+				xmlStream.closeNode();
+				xmlStream.openNode("xdr:spPr");
+				xmlStream.openNode("a:xfrm");
+				xmlStream.leafNode("a:off", {
+					x: 0,
+					y: 0
+				});
+				xmlStream.leafNode("a:ext", {
+					cx: 0,
+					cy: 0
+				});
+				xmlStream.closeNode();
+				xmlStream.openNode("a:prstGeom", { prst: model.shapeType });
+				xmlStream.leafNode("a:avLst");
+				xmlStream.closeNode();
+				if (model.fill && model.fill.color) {
+					xmlStream.openNode("a:solidFill");
+					xmlStream.leafNode("a:srgbClr", { val: normalizeColor(model.fill.color) });
+					xmlStream.closeNode();
+				} else xmlStream.leafNode("a:noFill");
+				if (model.line && (model.line.color || model.line.width !== void 0)) {
+					const lnAttrs = {};
+					if (model.line.width !== void 0) lnAttrs.w = Math.round(model.line.width * EMU_PER_POINT$1);
+					xmlStream.openNode("a:ln", lnAttrs);
+					if (model.line.color) {
+						xmlStream.openNode("a:solidFill");
+						xmlStream.leafNode("a:srgbClr", { val: normalizeColor(model.line.color) });
+						xmlStream.closeNode();
+					}
+					xmlStream.closeNode();
+				} else {
+					xmlStream.openNode("a:ln");
+					xmlStream.leafNode("a:noFill");
+					xmlStream.closeNode();
+				}
+				xmlStream.closeNode();
+				xmlStream.openNode("xdr:txBody");
+				xmlStream.leafNode("a:bodyPr", {
+					vertOverflow: "clip",
+					wrap: "square",
+					anchor: "ctr"
+				});
+				xmlStream.leafNode("a:lstStyle");
+				xmlStream.openNode("a:p");
+				xmlStream.openNode("a:pPr", { algn: "ctr" });
+				xmlStream.closeNode();
+				if (model.text) {
+					xmlStream.openNode("a:r");
+					xmlStream.openNode("a:rPr", { lang: "en-US" });
+					xmlStream.closeNode();
+					xmlStream.openNode("a:t");
+					xmlStream.writeText(model.text);
+					xmlStream.closeNode();
+					xmlStream.closeNode();
+				} else xmlStream.leafNode("a:endParaRPr", { lang: "en-US" });
+				xmlStream.closeNode();
+				xmlStream.closeNode();
+				xmlStream.closeNode();
+			}
+		};
+	}));
+	//#endregion
 	//#region src/modules/excel/xlsx/xform/drawing/absolute-anchor-xform.ts
 	var EMU_PER_PIXEL_AT_96_DPI, PosXform, AbsoluteAnchorXform;
 	var init_absolute_anchor_xform = __esmMin((() => {
@@ -34297,6 +34490,7 @@ self.onmessage = async function(event) {
 		init_ext_xform();
 		init_graphic_frame_xform();
 		init_pic_xform();
+		init_shape_xform();
 		init_static_xform();
 		EMU_PER_PIXEL_AT_96_DPI = 9525;
 		PosXform = class extends BaseXform {
@@ -34340,6 +34534,7 @@ self.onmessage = async function(event) {
 					"xdr:ext": new ExtXform({ tag: "xdr:ext" }),
 					"xdr:pic": new PicXform(),
 					"xdr:graphicFrame": new GraphicFrameXform(),
+					"xdr:userShape": new ShapeXform(),
 					"xdr:clientData": new StaticXform({ tag: "xdr:clientData" })
 				};
 			}
@@ -34359,6 +34554,7 @@ self.onmessage = async function(event) {
 				this.map["xdr:ext"].render(xmlStream, model.range.ext);
 				if (model.picture) this.map["xdr:pic"].render(xmlStream, model.picture);
 				else if (model.graphicFrame) this.map["xdr:graphicFrame"].render(xmlStream, model.graphicFrame);
+				else if (model.shape?.kind === "userShape") this.map["xdr:userShape"].render(xmlStream, model.shape);
 				this.map["xdr:clientData"].render(xmlStream, {});
 				xmlStream.closeNode();
 			}
@@ -34472,6 +34668,7 @@ self.onmessage = async function(event) {
 		init_ext_xform();
 		init_graphic_frame_xform();
 		init_pic_xform();
+		init_shape_xform();
 		init_static_xform();
 		OneCellAnchorXform = class extends BaseCellAnchorXform {
 			constructor() {
@@ -34480,6 +34677,7 @@ self.onmessage = async function(event) {
 					"xdr:from": new CellPositionXform({ tag: "xdr:from" }),
 					"xdr:ext": new ExtXform({ tag: "xdr:ext" }),
 					"xdr:pic": new PicXform(),
+					"xdr:userShape": new ShapeXform(),
 					"xdr:graphicFrame": new GraphicFrameXform(),
 					"xdr:clientData": new StaticXform({ tag: "xdr:clientData" })
 				};
@@ -34497,6 +34695,7 @@ self.onmessage = async function(event) {
 				this.map["xdr:ext"].render(xmlStream, model.range.ext);
 				if (model.picture) this.map["xdr:pic"].render(xmlStream, model.picture);
 				else if (model.graphicFrame) this.map["xdr:graphicFrame"].render(xmlStream, model.graphicFrame);
+				else if (model.shape?.kind === "userShape") this.map["xdr:userShape"].render(xmlStream, model.shape);
 				this.map["xdr:clientData"].render(xmlStream, {});
 				xmlStream.closeNode();
 			}
@@ -34659,6 +34858,7 @@ self.onmessage = async function(event) {
 		init_cell_position_xform();
 		init_graphic_frame_xform();
 		init_pic_xform();
+		init_shape_xform();
 		init_sp_xform();
 		init_static_xform();
 		TwoCellAnchorXform = class extends BaseCellAnchorXform {
@@ -34673,6 +34873,7 @@ self.onmessage = async function(event) {
 					"xdr:to": new CellPositionXform({ tag: "xdr:to" }),
 					"xdr:pic": new PicXform(),
 					"xdr:sp": new SpXform(),
+					"xdr:userShape": new ShapeXform(),
 					"xdr:graphicFrame": new GraphicFrameXform(),
 					"xdr:clientData": new StaticXform({ tag: "xdr:clientData" })
 				};
@@ -34703,7 +34904,8 @@ self.onmessage = async function(event) {
 				if (isChartEx) this.renderChartExAlternateContent(xmlStream, model);
 				else if (model.picture) this.map["xdr:pic"].render(xmlStream, model.picture);
 				else if (model.graphicFrame) this.map["xdr:graphicFrame"].render(xmlStream, model.graphicFrame);
-				else if (model.shape) this.map["xdr:sp"].render(xmlStream, model.shape);
+				else if (model.shape) if (model.shape.kind === "userShape") this.map["xdr:userShape"].render(xmlStream, model.shape);
+				else this.map["xdr:sp"].render(xmlStream, model.shape);
 				this.map["xdr:clientData"].render(xmlStream, {});
 				xmlStream.closeNode();
 				if (wrapAnchorInAc) {
@@ -35561,13 +35763,25 @@ self.onmessage = async function(event) {
 			* ```
 			*/
 			addImage(image) {
+				const { svg, ...raster } = image;
+				if (svg && raster.link && raster.buffer == null && raster.base64 == null && raster.filename == null) throw new ImageError("An SVG image requires an embedded raster fallback (buffer/base64/filename); it cannot be combined with an external link.");
 				const id = this.media.length;
 				const medium = {
-					...image,
+					...raster,
 					type: "image",
-					name: `image${id}.${image.extension}`
+					name: `image${id}.${raster.extension}`
 				};
 				this.media.push(medium);
+				if (svg) {
+					const svgId = this.media.length;
+					this.media.push({
+						...svg,
+						type: "image",
+						extension: "svg",
+						name: `image${svgId}.svg`
+					});
+					medium.svgMediaId = svgId;
+				}
 				return id;
 			}
 			getImage(id) {
@@ -41539,6 +41753,7 @@ self.onmessage = async function(event) {
 				this.views = options.views ?? [];
 				this.autoFilter = options.autoFilter ?? null;
 				this._media = [];
+				this._shapes = [];
 				this._charts = [];
 				this._sparklineGroups = [];
 				this.sheetProtection = null;
@@ -42139,6 +42354,74 @@ self.onmessage = async function(event) {
 				};
 				this._media.push(new Image(this, model));
 			}
+			/**
+			* Add a free-form drawing shape (rectangle, ellipse, line, text box, …) to
+			* the worksheet, anchored to a cell range.
+			*
+			* Unlike images, shapes need no media file — the geometry, fill, outline and
+			* optional text label are written directly into the drawing part.
+			*
+			* @example
+			* ```typescript
+			* worksheet.addShape({
+			*   type: "rect",
+			*   range: "B2:D5",
+			*   fillColor: "FFD966",
+			*   lineColor: "000000",
+			*   lineWidth: 1,
+			*   text: "Important"
+			* });
+			* ```
+			*/
+			addShape(options) {
+				const range = options.range;
+				if (!(typeof range === "string" && range.includes(":") || typeof range === "object" && range !== null && ("br" in range || "ext" in range || "pos" in range))) throw new ImageError("addShape requires a range covering an area: a cell range like \"B2:D5\", or an object with `br`, `ext`, or `pos`.");
+				this._shapes.push({
+					type: "shape",
+					shapeType: options.type ?? "rect",
+					range,
+					fillColor: options.fillColor,
+					lineColor: options.lineColor,
+					lineWidth: options.lineWidth,
+					text: options.text,
+					name: options.name
+				});
+			}
+			/** All shapes added to this worksheet. */
+			getShapes() {
+				return this._shapes.slice();
+			}
+			/**
+			* Resolve a shape's `range` into concrete two-cell anchor coordinates,
+			* reusing the `Image` range parser so cell-address/anchor handling stays in
+			* one place. Returns a serializable ShapeModel for the worksheet xform.
+			*/
+			_resolveShapeModel(shape) {
+				let range;
+				try {
+					range = new Image(this, {
+						type: "image",
+						imageId: "",
+						range: shape.range
+					}).model.range;
+				} catch {
+					range = void 0;
+				}
+				if (!range) return {
+					...shape,
+					anchorRange: void 0
+				};
+				return {
+					...shape,
+					anchorRange: {
+						tl: range.tl,
+						br: range.br,
+						ext: range.ext,
+						pos: range.pos,
+						editAs: range.editAs
+					}
+				};
+			}
 			getImages() {
 				return this._media.filter((m) => m.type === "image");
 			}
@@ -42787,6 +43070,7 @@ self.onmessage = async function(event) {
 					views: this.views,
 					autoFilter: this.autoFilter,
 					media: this._media.map((medium) => medium.model),
+					shapes: this._shapes.map((shape) => this._resolveShapeModel(shape)),
 					sheetProtection: this.sheetProtection,
 					tables: Object.values(this.tables).map((table) => table.model),
 					pivotTables: this.pivotTables,
@@ -42840,6 +43124,7 @@ self.onmessage = async function(event) {
 				this.views = value.views;
 				this.autoFilter = value.autoFilter;
 				this._media = value.media.map((medium) => new Image(this, medium));
+				this._shapes = value.shapes ? value.shapes.slice() : [];
 				this._watermark = value.watermark ?? null;
 				if (!this._watermark) {
 					for (const medium of this._media) if (medium.type === "watermark") {
@@ -51335,6 +51620,60 @@ self.onmessage = async function(event) {
 						});
 					}
 				}
+				const shapes = model.shapes ?? [];
+				if (shapes.length > 0) {
+					let { drawing } = model;
+					if (!drawing) {
+						drawing = model.drawing = {
+							rId: nextRid(rels),
+							name: `drawing${++options.drawingsCount}`,
+							anchors: [],
+							rels: []
+						};
+						options.drawings.push(drawing);
+						rels.push({
+							Id: drawing.rId,
+							Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing",
+							Target: drawingRelTargetFromWorksheet(drawing.name)
+						});
+					}
+					for (const shape of shapes) {
+						const anchorRange = shape.anchorRange;
+						if (!anchorRange) continue;
+						let range;
+						if (anchorRange.pos) range = {
+							pos: anchorRange.pos,
+							ext: anchorRange.ext,
+							editAs: "absolute"
+						};
+						else if (anchorRange.br) range = {
+							tl: anchorRange.tl,
+							br: anchorRange.br,
+							editAs: anchorRange.editAs ?? "oneCell"
+						};
+						else range = {
+							tl: anchorRange.tl,
+							ext: anchorRange.ext,
+							editAs: anchorRange.editAs ?? "oneCell"
+						};
+						const cNvPrId = drawing.anchors.length + 1;
+						drawing.anchors.push({
+							range,
+							shape: {
+								kind: "userShape",
+								cNvPrId,
+								name: shape.name ?? `Shape ${cNvPrId}`,
+								shapeType: shape.shapeType,
+								fill: shape.fillColor ? { color: shape.fillColor } : void 0,
+								line: shape.lineColor !== void 0 || shape.lineWidth !== void 0 ? {
+									color: shape.lineColor,
+									width: shape.lineWidth
+								} : void 0,
+								text: shape.text
+							}
+						});
+					}
+				}
 				if (headerImageMedia.length > 0) {
 					const medium = headerImageMedia[0];
 					const bookImage = options.media[medium.imageId];
@@ -58425,13 +58764,35 @@ self.onmessage = async function(event) {
 			* const id = workbook.addImage({ extension: "png", link: "https://example.com/logo.png" });
 			* worksheet.addImage(id, "B2:D6");
 			* ```
+			*
+			* @example SVG with raster fallback — crisp in modern Excel, safe everywhere
+			* ```typescript
+			* const id = workbook.addImage({
+			*   buffer: pngFallbackBytes, // shown by older Excel / non-SVG consumers
+			*   extension: "png",
+			*   svg: { buffer: svgBytes } // shown by Excel 2016+
+			* });
+			* worksheet.addImage(id, "B2:D6");
+			* ```
 			*/
 			addImage(image) {
+				const { svg, ...raster } = image;
+				if (svg && raster.link && raster.buffer == null && raster.base64 == null && raster.filename == null) throw new ImageError("An SVG image requires an embedded raster fallback (buffer/base64/filename); it cannot be combined with an external link.");
 				const id = this.media.length;
-				this.media.push({
-					...image,
+				const rasterMedia = {
+					...raster,
 					type: "image"
-				});
+				};
+				this.media.push(rasterMedia);
+				if (svg) {
+					const svgId = this.media.length;
+					this.media.push({
+						...svg,
+						type: "image",
+						extension: "svg"
+					});
+					rasterMedia.svgMediaId = svgId;
+				}
 				return id;
 			}
 			getImage(id) {
@@ -60675,6 +61036,17 @@ self.onmessage = async function(event) {
 				return this;
 			}
 			/**
+			* Append a deferred fragment whose body is evaluated only at serialization
+			* time. Used by text drawing so the final byte encoding can be chosen after
+			* the document's fonts are resolved at build time. The fragment occupies its
+			* draw-order slot immediately, so z-order relative to other operators is
+			* preserved.
+			*/
+			deferred(produce) {
+				this.parts.push(produce);
+				return this;
+			}
+			/**
 			* Save the current graphics state (push onto state stack).
 			* Must be balanced with a corresponding restore().
 			*/
@@ -61033,10 +61405,23 @@ self.onmessage = async function(event) {
 				return this;
 			}
 			/**
-			* Get the content stream as a string.
+			* Whether any fragment has been appended. Unlike `toString().length > 0`,
+			* this does NOT evaluate deferred fragments, so it is safe to call before
+			* fonts are resolved (e.g. when probing for overlay content during an
+			* editor save, prior to `writeFontResources`). A deferred text fragment
+			* counts as content even though its bytes are not produced yet.
+			*/
+			hasContent() {
+				return this.parts.length > 0;
+			}
+			/**
+			* Get the content stream as a string. Deferred fragments (see `deferred`)
+			* are evaluated here, after font resolution has completed at build time.
 			*/
 			toString() {
-				return this.parts.join("\n");
+				const out = [];
+				for (const part of this.parts) out.push(typeof part === "function" ? part() : part);
+				return out.join("\n");
 			}
 			/**
 			* Get the content stream as a Uint8Array (UTF-8 encoded).
@@ -87314,18 +87699,42 @@ self.onmessage = async function(event) {
 				return this.embeddedResourceName;
 			}
 			/**
+			* Resolve the resource name a draw-time-resolved Type1 resource should
+			* actually render (and be measured) with, given the font manager's
+			* *current* state. If an embedded font exists (possibly auto-discovered
+			* at build time, after the text was drawn against a Type1 resource), the
+			* embedded resource name is returned so both measurement and encoding go
+			* through the CIDFont. Otherwise the original Type1 resource name is kept;
+			* `measureText` handles Type3-fallback widths internally from that name.
+			*
+			* Centralises the routing rule shared by the deferred text renderer and
+			* any deferred measurement (anchor alignment, word wrapping) so the two
+			* never disagree.
+			*/
+			resolveRenderResourceName(type1ResourceName) {
+				return this.embeddedFont ? this.embeddedResourceName : type1ResourceName;
+			}
+			/**
 			* Record that a text string will be rendered, tracking its code points.
 			* Must be called for every text string before writing the PDF.
+			*
+			* Two sets are maintained because font selection may be decided *after*
+			* drawing (e.g. `PdfDocumentBuilder.build()` auto-discovers and embeds a
+			* system font once it sees the accumulated non-WinAnsi code points):
+			*
+			*   - `usedCodePoints` — every code point seen, always. If an embedded
+			*     font ends up being used (whether registered up front or
+			*     auto-discovered at build time), the subset must cover all of these,
+			*     including plain ASCII, so the CIDFont can encode the full run.
+			*   - `type3CodePoints` — non-WinAnsi code points only. Drives the
+			*     build-time decision to auto-embed a system font, and the Type3
+			*     fallback when none is available.
 			*/
 			trackText(text) {
-				if (this.embeddedFont) for (let i = 0; i < text.length; i++) {
-					const cp = text.codePointAt(i);
-					this.usedCodePoints.add(cp);
-					if (cp > 65535) i++;
-				}
-				else for (let i = 0; i < text.length; i++) {
+				for (let i = 0; i < text.length; i++) {
 					const cp = text.codePointAt(i);
 					if (cp > 65535) i++;
+					this.usedCodePoints.add(cp);
 					if (!isWinAnsiCodePoint(cp)) this.type3CodePoints.add(cp);
 				}
 			}
@@ -88540,7 +88949,7 @@ self.onmessage = async function(event) {
 			emitTextWithMatrix(stream, line, cos, sin, -sin, cos, tx, ty, resourceName, fontSize, fontManager, useType3);
 		}
 	}
-	/** Emit a text string with hex encoding if available. */
+	/** Emit a text string with hex encoding if available, onto a sink stream. */
 	function emitText(stream, fontManager, text, resourceName) {
 		const hex = fontManager.encodeText(text, resourceName);
 		if (hex) stream.showTextHex(hex);
@@ -88551,37 +88960,65 @@ self.onmessage = async function(event) {
 	* when needed.  For each sub-run the matrix origin is advanced along the
 	* text direction (cos, sin) by the rendered width.
 	*
-	* When `useType3` is false this collapses to a single BT/ET pair — identical
-	* to the old `emitText()` path but wrapped in begin/end for convenience.
-	*/
-	function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, useType3) {
-		if (!useType3) {
-			stream.beginText();
-			stream.setFont(type1ResourceName, fontSize);
-			stream.setTextMatrix(a, b, c, d, tx, ty);
-			emitText(stream, fontManager, text, type1ResourceName);
-			stream.endText();
-			return;
+	* The emitted operators are written as a *deferred* fragment (see
+	* `PdfContentStream.deferred`). The fragment is only evaluated at
+	* serialization time, by which point `PdfDocumentBuilder.build()` has
+	* finalised the document's fonts (auto-discovered embedded CIDFont,
+	* Type3 fallback, or plain Type1). This is essential: at draw time the
+	* font manager has not yet decided whether a non-WinAnsi code point (e.g.
+	* U+2192 →) will be served by an embedded font or a Type3 glyph, so eager
+	* encoding would irreversibly degrade those characters to spaces via the
+	* WinAnsi fallback. Deferring the encode keeps the fragment at its exact
+	* draw-order slot (preserving z-order) while choosing the correct bytes
+	* once fonts are known.
+	*
+	* The `useType3` argument is the caller's *draw-time* guess and is ignored;
+	* the deferred body recomputes the routing from the now-settled font
+	* manager state.
+	*/
+	function emitTextWithMatrix(stream, text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager, _useType3) {
+		stream.deferred(() => renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager));
+	}
+	/**
+	* Produce the PDF operator string for a positioned text run, choosing the
+	* encoding from the font manager's *current* (build-time) state:
+	*   - embedded font  → single BT/ET with CIDFont hex encoding
+	*   - Type3 fallback → split into WinAnsi (Type1) and per-glyph Type3 runs
+	*   - neither        → single BT/ET with Type1/WinAnsi encoding
+	*
+	* Must only be called after font resolution (i.e. from a deferred fragment).
+	*/
+	function renderTextBlock(text, a, b, c, d, tx, ty, type1ResourceName, fontSize, fontManager) {
+		const sink = new PdfContentStream();
+		if (!(fontManager.hasType3Fonts() && !fontManager.hasEmbeddedFont())) {
+			const resourceName = fontManager.resolveRenderResourceName(type1ResourceName);
+			sink.beginText();
+			sink.setFont(resourceName, fontSize);
+			sink.setTextMatrix(a, b, c, d, tx, ty);
+			emitText(sink, fontManager, text, resourceName);
+			sink.endText();
+			return sink.toString();
 		}
 		const runs = splitTextRuns(text, fontManager);
 		let curTx = tx;
 		let curTy = ty;
 		for (const run of runs) {
-			stream.beginText();
+			sink.beginText();
 			if (run.type3) {
-				stream.setFont(run.type3.resourceName, fontSize);
-				stream.setTextMatrix(a, b, c, d, curTx, curTy);
-				stream.showTextHex(run.type3.hex);
+				sink.setFont(run.type3.resourceName, fontSize);
+				sink.setTextMatrix(a, b, c, d, curTx, curTy);
+				sink.showTextHex(run.type3.hex);
 			} else {
-				stream.setFont(type1ResourceName, fontSize);
-				stream.setTextMatrix(a, b, c, d, curTx, curTy);
-				emitText(stream, fontManager, run.text, type1ResourceName);
+				sink.setFont(type1ResourceName, fontSize);
+				sink.setTextMatrix(a, b, c, d, curTx, curTy);
+				emitText(sink, fontManager, run.text, type1ResourceName);
 			}
-			stream.endText();
+			sink.endText();
 			const w = fontManager.measureText(run.text, run.type3?.resourceName ?? type1ResourceName, fontSize);
 			curTx += a * w;
 			curTy += b * w;
 		}
+		return sink.toString();
 	}
 	/**
 	* Split a line of text into runs of consecutive WinAnsi and non-WinAnsi