@libpdf/core 0.2.1 → 0.2.3

package/dist/index.mjs

@@ -9,7 +9,7 @@ import { createCMSECDSASignature } from "pkijs";
 import { base64 } from "@scure/base";
 
 //#region package.json
-var version = "0.2.1";
+var version = "0.2.3";
 
 //#endregion
 //#region src/objects/pdf-array.ts
@@ -22717,7 +22717,7 @@ function validateFollowingOperator(scanner) {
 		const tokenStart = pos + i;
 		const firstCh = scanner.peekAt(tokenStart);
 		if (firstCh === -1) return false;
-		if (isNumberStart(firstCh)) {
+		if (isNumberStart$1(firstCh)) {
 			i++;
 			while (i < lookahead) {
 				const ch = scanner.peekAt(pos + i);
@@ -22772,7 +22772,7 @@ function validateFollowingOperator(scanner) {
 	}
 	return false;
 }
-function isNumberStart(ch) {
+function isNumberStart$1(ch) {
 	return ch >= DIGIT_0 && ch <= DIGIT_9 || ch === CHAR_PLUS || ch === CHAR_MINUS || ch === CHAR_PERIOD;
 }
 /**
@@ -23722,6 +23722,854 @@ function getPaintOp(hasFill, hasStroke) {
 	return stroke();
 }
 
+//#endregion
+//#region src/svg/arc-to-bezier.ts
+/**
+* Convert an SVG arc to one or more cubic bezier curves.
+*
+* Handles edge cases according to SVG spec:
+* - If rx=0 or ry=0, returns a line to the endpoint
+* - If start and end points are the same, returns empty array
+* - If radii are too small, they're scaled up automatically
+*
+* @param arc - Arc parameters in endpoint form
+* @returns Array of bezier curves that approximate the arc
+*/
+function arcToBezier(arc) {
+	const { x1, y1, x2, y2, xAxisRotation, largeArcFlag, sweepFlag } = arc;
+	let { rx, ry } = arc;
+	if (x1 === x2 && y1 === y2) return [];
+	if (rx === 0 || ry === 0) return [{
+		cp1x: x1,
+		cp1y: y1,
+		cp2x: x2,
+		cp2y: y2,
+		x: x2,
+		y: y2
+	}];
+	rx = Math.abs(rx);
+	ry = Math.abs(ry);
+	const phi = xAxisRotation * Math.PI / 180;
+	const cosPhi = Math.cos(phi);
+	const sinPhi = Math.sin(phi);
+	const dx = (x1 - x2) / 2;
+	const dy = (y1 - y2) / 2;
+	const x1p = cosPhi * dx + sinPhi * dy;
+	const y1p = -sinPhi * dx + cosPhi * dy;
+	const lambda = x1p * x1p / (rx * rx) + y1p * y1p / (ry * ry);
+	if (lambda > 1) {
+		const sqrtLambda = Math.sqrt(lambda);
+		rx = sqrtLambda * rx;
+		ry = sqrtLambda * ry;
+	}
+	const rx2 = rx * rx;
+	const ry2 = ry * ry;
+	const x1p2 = x1p * x1p;
+	const y1p2 = y1p * y1p;
+	let sq = (rx2 * ry2 - rx2 * y1p2 - ry2 * x1p2) / (rx2 * y1p2 + ry2 * x1p2);
+	if (sq < 0) sq = 0;
+	const coef = (largeArcFlag === sweepFlag ? -1 : 1) * Math.sqrt(sq);
+	const cxp = coef * rx * y1p / ry;
+	const cyp = -coef * ry * x1p / rx;
+	const midX = (x1 + x2) / 2;
+	const midY = (y1 + y2) / 2;
+	const cx = cosPhi * cxp - sinPhi * cyp + midX;
+	const cy = sinPhi * cxp + cosPhi * cyp + midY;
+	const ux = (x1p - cxp) / rx;
+	const uy = (y1p - cyp) / ry;
+	const vx = (-x1p - cxp) / rx;
+	const vy = (-y1p - cyp) / ry;
+	const theta1 = angleBetween(1, 0, ux, uy);
+	let dTheta = angleBetween(ux, uy, vx, vy);
+	if (!sweepFlag && dTheta > 0) dTheta -= 2 * Math.PI;
+	if (sweepFlag && dTheta < 0) dTheta += 2 * Math.PI;
+	const numSegments = Math.ceil(Math.abs(dTheta) / (Math.PI / 2));
+	const segmentAngle = dTheta / numSegments;
+	const curves = [];
+	let currentAngle = theta1;
+	for (let i = 0; i < numSegments; i++) {
+		const nextAngle = currentAngle + segmentAngle;
+		const curve = arcSegmentToBezier(cx, cy, rx, ry, phi, currentAngle, nextAngle);
+		curves.push(curve);
+		currentAngle = nextAngle;
+	}
+	return curves;
+}
+/**
+* Compute the angle between two vectors.
+*/
+function angleBetween(ux, uy, vx, vy) {
+	const sign = ux * vy - uy * vx < 0 ? -1 : 1;
+	let cos = (ux * vx + uy * vy) / (Math.sqrt(ux * ux + uy * uy) * Math.sqrt(vx * vx + vy * vy));
+	if (cos < -1) cos = -1;
+	if (cos > 1) cos = 1;
+	return sign * Math.acos(cos);
+}
+/**
+* Convert a single arc segment (up to 90 degrees) to a cubic bezier.
+*
+* Uses the standard arc approximation formula:
+* For an arc of angle theta centered at origin:
+* CP1 = P0 + alpha * tangent at P0
+* CP2 = P1 - alpha * tangent at P1
+*
+* Where alpha = (4/3) * tan(theta/4)
+*/
+function arcSegmentToBezier(cx, cy, rx, ry, phi, theta1, theta2) {
+	const dTheta = theta2 - theta1;
+	const t = Math.tan(dTheta / 4);
+	const alpha = Math.sin(dTheta) * (Math.sqrt(4 + 3 * t * t) - 1) / 3;
+	const cosPhi = Math.cos(phi);
+	const sinPhi = Math.sin(phi);
+	const cos1 = Math.cos(theta1);
+	const sin1 = Math.sin(theta1);
+	const cos2 = Math.cos(theta2);
+	const sin2 = Math.sin(theta2);
+	const p0x = cx + cosPhi * rx * cos1 - sinPhi * ry * sin1;
+	const p0y = cy + sinPhi * rx * cos1 + cosPhi * ry * sin1;
+	const p1x = cx + cosPhi * rx * cos2 - sinPhi * ry * sin2;
+	const p1y = cy + sinPhi * rx * cos2 + cosPhi * ry * sin2;
+	const t0x = -cosPhi * rx * sin1 - sinPhi * ry * cos1;
+	const t0y = -sinPhi * rx * sin1 + cosPhi * ry * cos1;
+	const t1x = -cosPhi * rx * sin2 - sinPhi * ry * cos2;
+	const t1y = -sinPhi * rx * sin2 + cosPhi * ry * cos2;
+	return {
+		cp1x: p0x + alpha * t0x,
+		cp1y: p0y + alpha * t0y,
+		cp2x: p1x - alpha * t1x,
+		cp2y: p1y - alpha * t1y,
+		x: p1x,
+		y: p1y
+	};
+}
+
+//#endregion
+//#region src/svg/path-parser.ts
+/**
+* Number of parameters required for each command type.
+*/
+const COMMAND_PARAMS = {
+	M: 2,
+	m: 2,
+	L: 2,
+	l: 2,
+	H: 1,
+	h: 1,
+	V: 1,
+	v: 1,
+	C: 6,
+	c: 6,
+	S: 4,
+	s: 4,
+	Q: 4,
+	q: 4,
+	T: 2,
+	t: 2,
+	A: 7,
+	a: 7,
+	Z: 0,
+	z: 0
+};
+/**
+* Check if a character is a command letter.
+*/
+function isCommandLetter(char) {
+	return /^[MmLlHhVvCcSsQqTtAaZz]$/.test(char);
+}
+/**
+* Check if a character can start a number.
+*/
+function isNumberStart(char) {
+	return /^[0-9.+-]$/.test(char);
+}
+/**
+* Tokenizer for SVG path strings.
+* Extracts command letters and numbers from the path string.
+*/
+var PathTokenizer = class {
+	path;
+	pos = 0;
+	constructor(path) {
+		this.path = path;
+	}
+	/**
+	* Skip whitespace and commas.
+	*/
+	skipWhitespaceAndCommas() {
+		while (this.pos < this.path.length) {
+			const char = this.path[this.pos];
+			if (char === " " || char === "	" || char === "\n" || char === "\r" || char === ",") this.pos++;
+			else break;
+		}
+	}
+	/**
+	* Read a number from the current position.
+	* Handles integers, decimals, negative numbers, and scientific notation.
+	*/
+	readNumber() {
+		this.skipWhitespaceAndCommas();
+		if (this.pos >= this.path.length) return null;
+		const char = this.path[this.pos];
+		if (isCommandLetter(char)) return null;
+		if (!isNumberStart(char)) {
+			this.pos++;
+			return null;
+		}
+		let numStr = "";
+		let hasDecimal = false;
+		let hasExponent = false;
+		if (char === "+" || char === "-") {
+			numStr += char;
+			this.pos++;
+		}
+		while (this.pos < this.path.length) {
+			const c = this.path[this.pos];
+			if (c >= "0" && c <= "9") {
+				numStr += c;
+				this.pos++;
+			} else if (c === "." && !hasDecimal && !hasExponent) {
+				numStr += c;
+				hasDecimal = true;
+				this.pos++;
+			} else if ((c === "e" || c === "E") && !hasExponent && numStr.length > 0) {
+				numStr += c;
+				hasExponent = true;
+				this.pos++;
+				if (this.pos < this.path.length) {
+					const signChar = this.path[this.pos];
+					if (signChar === "+" || signChar === "-") {
+						numStr += signChar;
+						this.pos++;
+					}
+				}
+			} else break;
+		}
+		if (numStr === "" || numStr === "+" || numStr === "-" || numStr === ".") return null;
+		const value = Number.parseFloat(numStr);
+		return Number.isNaN(value) ? null : value;
+	}
+	/**
+	* Read a command letter from the current position.
+	*/
+	readCommand() {
+		this.skipWhitespaceAndCommas();
+		if (this.pos >= this.path.length) return null;
+		const char = this.path[this.pos];
+		if (isCommandLetter(char)) {
+			this.pos++;
+			return char;
+		}
+		return null;
+	}
+	/**
+	* Peek at the next character without consuming it.
+	*/
+	peek() {
+		this.skipWhitespaceAndCommas();
+		if (this.pos >= this.path.length) return null;
+		return this.path[this.pos];
+	}
+	/**
+	* Check if there's more content to parse.
+	*/
+	hasMore() {
+		this.skipWhitespaceAndCommas();
+		return this.pos < this.path.length;
+	}
+	/**
+	* Read a single flag digit (0 or 1) for arc commands.
+	* SVG arc flags are special - they're single digits that can be
+	* concatenated without separators: "00" means two flags, both 0.
+	*/
+	readFlag() {
+		this.skipWhitespaceAndCommas();
+		if (this.pos >= this.path.length) return null;
+		const char = this.path[this.pos];
+		if (char === "0" || char === "1") {
+			this.pos++;
+			return char === "1" ? 1 : 0;
+		}
+		return null;
+	}
+};
+/**
+* Parse an SVG path string into an array of commands.
+*
+* @param pathData - The SVG path `d` attribute string
+* @returns Array of parsed path commands
+*
+* @example
+* ```typescript
+* const commands = parseSvgPath("M 10 10 L 100 10 L 100 100 Z");
+* // [
+* //   { type: "M", x: 10, y: 10 },
+* //   { type: "L", x: 100, y: 10 },
+* //   { type: "L", x: 100, y: 100 },
+* //   { type: "Z" },
+* // ]
+* ```
+*/
+function parseSvgPath(pathData) {
+	const commands = [];
+	const tokenizer = new PathTokenizer(pathData);
+	let currentCommand = null;
+	let isFirstInSequence = true;
+	while (tokenizer.hasMore()) {
+		const nextChar = tokenizer.peek();
+		if (nextChar && isCommandLetter(nextChar)) {
+			currentCommand = tokenizer.readCommand();
+			isFirstInSequence = true;
+		}
+		if (!currentCommand) break;
+		const paramCount = COMMAND_PARAMS[currentCommand];
+		if (currentCommand === "Z" || currentCommand === "z") {
+			commands.push({ type: currentCommand });
+			currentCommand = null;
+			continue;
+		}
+		const params = [];
+		const isArc = currentCommand === "A" || currentCommand === "a";
+		for (let i = 0; i < paramCount; i++) {
+			let num;
+			if (isArc && (i === 3 || i === 4)) num = tokenizer.readFlag();
+			else num = tokenizer.readNumber();
+			if (num === null) break;
+			params.push(num);
+		}
+		if (params.length !== paramCount) continue;
+		const command = createCommand(currentCommand, params);
+		if (command) commands.push(command);
+		if (isFirstInSequence) {
+			isFirstInSequence = false;
+			if (currentCommand === "M") currentCommand = "L";
+			else if (currentCommand === "m") currentCommand = "l";
+		}
+		const nextPeek = tokenizer.peek();
+		if (!nextPeek || isCommandLetter(nextPeek)) {
+			if (!nextPeek) break;
+		}
+	}
+	return commands;
+}
+/**
+* Create a command object from type and parameters.
+*/
+function createCommand(type, params) {
+	switch (type) {
+		case "M":
+		case "m": return {
+			type,
+			x: params[0],
+			y: params[1]
+		};
+		case "L":
+		case "l": return {
+			type,
+			x: params[0],
+			y: params[1]
+		};
+		case "H":
+		case "h": return {
+			type,
+			x: params[0]
+		};
+		case "V":
+		case "v": return {
+			type,
+			y: params[0]
+		};
+		case "C":
+		case "c": return {
+			type,
+			x1: params[0],
+			y1: params[1],
+			x2: params[2],
+			y2: params[3],
+			x: params[4],
+			y: params[5]
+		};
+		case "S":
+		case "s": return {
+			type,
+			x2: params[0],
+			y2: params[1],
+			x: params[2],
+			y: params[3]
+		};
+		case "Q":
+		case "q": return {
+			type,
+			x1: params[0],
+			y1: params[1],
+			x: params[2],
+			y: params[3]
+		};
+		case "T":
+		case "t": return {
+			type,
+			x: params[0],
+			y: params[1]
+		};
+		case "A":
+		case "a": return {
+			type,
+			rx: params[0],
+			ry: params[1],
+			xAxisRotation: params[2],
+			largeArcFlag: params[3] !== 0,
+			sweepFlag: params[4] !== 0,
+			x: params[5],
+			y: params[6]
+		};
+		case "Z":
+		case "z": return { type };
+		default: return null;
+	}
+}
+
+//#endregion
+//#region src/svg/path-executor.ts
+/**
+* SVG Path Executor
+*
+* Executes parsed SVG path commands via a callback interface.
+* Handles:
+* - Relative to absolute coordinate conversion
+* - Smooth curve control point reflection
+* - Arc to bezier conversion
+* - Y-axis flipping for PDF coordinate system (optional, default: true)
+*/
+/**
+* Execute SVG path commands via a callback interface.
+*
+* The executor handles all coordinate transformations and command
+* normalization, so the sink receives only absolute coordinates
+* and standard path operations.
+*
+* @param options - Execution options
+* @param options.commands - Parsed SVG path commands
+* @param options.sink - Callback interface for path operations
+* @param options.initialX - Initial X coordinate (default: 0)
+* @param options.initialY - Initial Y coordinate (default: 0)
+* @param options.flipY - Flip Y coordinates for PDF (default: true)
+* @param options.scale - Scale factor (default: 1)
+* @param options.translateX - X offset after transform (default: 0)
+* @param options.translateY - Y offset after transform (default: 0)
+* @returns Final position {x, y} after executing all commands
+*/
+function executeSvgPath(options) {
+	const { commands, sink, initialX = 0, initialY = 0, flipY = true, scale = 1, translateX = 0, translateY = 0 } = options;
+	const yFlip = flipY ? -1 : 1;
+	const initialOutputX = initialX + translateX;
+	const initialOutputY = initialY + translateY;
+	const state = {
+		currentX: initialOutputX,
+		currentY: initialOutputY,
+		subpathStartX: initialOutputX,
+		subpathStartY: initialOutputY,
+		lastControlX: initialOutputX,
+		lastControlY: initialOutputY,
+		lastCommand: null,
+		yFlip,
+		scale,
+		translateX,
+		translateY
+	};
+	for (const cmd of commands) executeCommand(cmd, state, sink);
+	return {
+		x: state.currentX,
+		y: state.currentY
+	};
+}
+/**
+* Transform an SVG coordinate to output space.
+* Applies: scale, Y-flip, then translate.
+*/
+function transformX(x, state) {
+	return x * state.scale + state.translateX;
+}
+function transformY(y, state) {
+	return y * state.yFlip * state.scale + state.translateY;
+}
+/**
+* Execute a single SVG path command.
+*/
+function executeCommand(cmd, state, sink) {
+	switch (cmd.type) {
+		case "M":
+			executeMoveTo({
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "m":
+			executeMoveTo({
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "L":
+			executeLineTo({
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "l":
+			executeLineTo({
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "H":
+			executeHorizontalLine({
+				x: cmd.x,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "h":
+			executeHorizontalLine({
+				x: cmd.x,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "V":
+			executeVerticalLine({
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "v":
+			executeVerticalLine({
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "C":
+			executeCubicCurve({
+				x1: cmd.x1,
+				y1: cmd.y1,
+				x2: cmd.x2,
+				y2: cmd.y2,
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "c":
+			executeCubicCurve({
+				x1: cmd.x1,
+				y1: cmd.y1,
+				x2: cmd.x2,
+				y2: cmd.y2,
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "S":
+			executeSmoothCubic({
+				x2: cmd.x2,
+				y2: cmd.y2,
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "s":
+			executeSmoothCubic({
+				x2: cmd.x2,
+				y2: cmd.y2,
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "Q":
+			executeQuadratic({
+				x1: cmd.x1,
+				y1: cmd.y1,
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "q":
+			executeQuadratic({
+				x1: cmd.x1,
+				y1: cmd.y1,
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "T":
+			executeSmoothQuadratic({
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "t":
+			executeSmoothQuadratic({
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "A":
+			executeArc({
+				rx: cmd.rx,
+				ry: cmd.ry,
+				xAxisRotation: cmd.xAxisRotation,
+				largeArcFlag: cmd.largeArcFlag,
+				sweepFlag: cmd.sweepFlag,
+				x: cmd.x,
+				y: cmd.y,
+				relative: false,
+				state,
+				sink
+			});
+			break;
+		case "a":
+			executeArc({
+				rx: cmd.rx,
+				ry: cmd.ry,
+				xAxisRotation: cmd.xAxisRotation,
+				largeArcFlag: cmd.largeArcFlag,
+				sweepFlag: cmd.sweepFlag,
+				x: cmd.x,
+				y: cmd.y,
+				relative: true,
+				state,
+				sink
+			});
+			break;
+		case "Z":
+		case "z":
+			executeClose({
+				state,
+				sink
+			});
+			break;
+	}
+	state.lastCommand = cmd.type;
+}
+function executeMoveTo(options) {
+	const { x, y, relative, state, sink } = options;
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.moveTo(outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.subpathStartX = outX;
+	state.subpathStartY = outY;
+	state.lastControlX = outX;
+	state.lastControlY = outY;
+}
+function executeLineTo(options) {
+	const { x, y, relative, state, sink } = options;
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.lineTo(outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = outX;
+	state.lastControlY = outY;
+}
+function executeHorizontalLine(options) {
+	const { x, relative, state, sink } = options;
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	sink.lineTo(outX, state.currentY);
+	state.currentX = outX;
+	state.lastControlX = outX;
+	state.lastControlY = state.currentY;
+}
+function executeVerticalLine(options) {
+	const { y, relative, state, sink } = options;
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.lineTo(state.currentX, outY);
+	state.currentY = outY;
+	state.lastControlX = state.currentX;
+	state.lastControlY = outY;
+}
+function executeCubicCurve(options) {
+	const { x1, y1, x2, y2, x, y, relative, state, sink } = options;
+	const outX1 = relative ? state.currentX + x1 * state.scale : transformX(x1, state);
+	const outY1 = relative ? state.currentY + y1 * state.yFlip * state.scale : transformY(y1, state);
+	const outX2 = relative ? state.currentX + x2 * state.scale : transformX(x2, state);
+	const outY2 = relative ? state.currentY + y2 * state.yFlip * state.scale : transformY(y2, state);
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.curveTo(outX1, outY1, outX2, outY2, outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = outX2;
+	state.lastControlY = outY2;
+}
+function executeSmoothCubic(options) {
+	const { x2, y2, x, y, relative, state, sink } = options;
+	let cp1x;
+	let cp1y;
+	if (state.lastCommand === "C" || state.lastCommand === "c" || state.lastCommand === "S" || state.lastCommand === "s") {
+		cp1x = 2 * state.currentX - state.lastControlX;
+		cp1y = 2 * state.currentY - state.lastControlY;
+	} else {
+		cp1x = state.currentX;
+		cp1y = state.currentY;
+	}
+	const outX2 = relative ? state.currentX + x2 * state.scale : transformX(x2, state);
+	const outY2 = relative ? state.currentY + y2 * state.yFlip * state.scale : transformY(y2, state);
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.curveTo(cp1x, cp1y, outX2, outY2, outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = outX2;
+	state.lastControlY = outY2;
+}
+function executeQuadratic(options) {
+	const { x1, y1, x, y, relative, state, sink } = options;
+	const outCpX = relative ? state.currentX + x1 * state.scale : transformX(x1, state);
+	const outCpY = relative ? state.currentY + y1 * state.yFlip * state.scale : transformY(y1, state);
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.quadraticCurveTo(outCpX, outCpY, outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = outCpX;
+	state.lastControlY = outCpY;
+}
+function executeSmoothQuadratic(options) {
+	const { x, y, relative, state, sink } = options;
+	let cpx;
+	let cpy;
+	if (state.lastCommand === "Q" || state.lastCommand === "q" || state.lastCommand === "T" || state.lastCommand === "t") {
+		cpx = 2 * state.currentX - state.lastControlX;
+		cpy = 2 * state.currentY - state.lastControlY;
+	} else {
+		cpx = state.currentX;
+		cpy = state.currentY;
+	}
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	sink.quadraticCurveTo(cpx, cpy, outX, outY);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = cpx;
+	state.lastControlY = cpy;
+}
+function executeArc(options) {
+	const { rx, ry, xAxisRotation, largeArcFlag, sweepFlag, x, y, relative, state, sink } = options;
+	const outX = relative ? state.currentX + x * state.scale : transformX(x, state);
+	const outY = relative ? state.currentY + y * state.yFlip * state.scale : transformY(y, state);
+	const scaledRx = rx * state.scale;
+	const scaledRy = ry * state.scale;
+	const effectiveSweepFlag = state.yFlip === -1 ? !sweepFlag : sweepFlag;
+	const curves = arcToBezier({
+		x1: state.currentX,
+		y1: state.currentY,
+		rx: scaledRx,
+		ry: scaledRy,
+		xAxisRotation,
+		largeArcFlag,
+		sweepFlag: effectiveSweepFlag,
+		x2: outX,
+		y2: outY
+	});
+	for (const curve of curves) sink.curveTo(curve.cp1x, curve.cp1y, curve.cp2x, curve.cp2y, curve.x, curve.y);
+	state.currentX = outX;
+	state.currentY = outY;
+	state.lastControlX = outX;
+	state.lastControlY = outY;
+}
+function executeClose(options) {
+	const { state, sink } = options;
+	sink.close();
+	state.currentX = state.subpathStartX;
+	state.currentY = state.subpathStartY;
+	state.lastControlX = state.subpathStartX;
+	state.lastControlY = state.subpathStartY;
+}
+/**
+* Parse and execute an SVG path string.
+*
+* This is a convenience function that combines parsing and execution.
+*
+* By default, Y coordinates are flipped (negated) to convert from SVG's
+* top-left origin to PDF's bottom-left origin. Set `flipY: false` in
+* options to disable this behavior.
+*
+* @param options - Execution options
+* @param options.pathData - SVG path d string
+* @param options.sink - Callback interface for path operations
+* @param options.initialX - Initial X coordinate (default: 0)
+* @param options.initialY - Initial Y coordinate (default: 0)
+* @param options.flipY - Flip Y coordinates for PDF (default: true)
+* @param options.scale - Scale factor (default: 1)
+* @param options.translateX - X offset after transform (default: 0)
+* @param options.translateY - Y offset after transform (default: 0)
+* @returns Final position {x, y} after executing all commands
+*
+* @example
+* ```typescript
+* const sink = {
+*   moveTo: (x, y) => console.log(`M ${x} ${y}`),
+*   lineTo: (x, y) => console.log(`L ${x} ${y}`),
+*   curveTo: (cp1x, cp1y, cp2x, cp2y, x, y) => console.log(`C ...`),
+*   quadraticCurveTo: (cpx, cpy, x, y) => console.log(`Q ...`),
+*   close: () => console.log(`Z`),
+* };
+*
+* executeSvgPathString({ pathData: "M 10 10 L 100 10 L 100 100 Z", sink });
+* ```
+*/
+function executeSvgPathString(options) {
+	const { pathData, sink, initialX, initialY, ...executorOptions } = options;
+	return executeSvgPath({
+		commands: parseSvgPath(pathData),
+		sink,
+		initialX,
+		initialY,
+		...executorOptions
+	});
+}
+
 //#endregion
 //#region src/api/drawing/path-builder.ts
 /**
@@ -23848,6 +24696,71 @@ var PathBuilder = class {
 		return this.moveTo(cx - rx, cy).curveTo(cx - rx, cy + ky, cx - kx, cy + ry, cx, cy + ry).curveTo(cx + kx, cy + ry, cx + rx, cy + ky, cx + rx, cy).curveTo(cx + rx, cy - ky, cx + kx, cy - ry, cx, cy - ry).curveTo(cx - kx, cy - ry, cx - rx, cy - ky, cx - rx, cy).close();
 	}
 	/**
+	* Append an SVG path string to the current path.
+	*
+	* Parses the SVG path `d` attribute string and adds all commands to this path.
+	* Relative commands (lowercase) are converted to absolute coordinates based on
+	* the current point. Smooth curves (S, T) and arcs (A) are converted to
+	* cubic bezier curves.
+	*
+	* By default, this method does NOT transform coordinates (flipY: false).
+	* Use the options to apply scale, translation, and Y-flip for SVG paths.
+	*
+	* @param pathData - SVG path `d` attribute string
+	* @param options - Execution options (flipY, scale, translate)
+	* @returns This PathBuilder for chaining
+	*
+	* @example
+	* ```typescript
+	* // Simple path (no transform)
+	* page.drawPath()
+	*   .appendSvgPath("M 10 10 L 100 10 L 55 90 Z")
+	*   .fill({ color: rgb(1, 0, 0) });
+	*
+	* // SVG icon with full transform
+	* page.drawPath()
+	*   .appendSvgPath(iconPath, {
+	*     flipY: true,
+	*     scale: 0.1,
+	*     translateX: 100,
+	*     translateY: 500,
+	*   })
+	*   .fill({ color: rgb(0, 0, 0) });
+	* ```
+	*/
+	appendSvgPath(pathData, options = {}) {
+		const executorOptions = {
+			flipY: options.flipY ?? false,
+			scale: options.scale,
+			translateX: options.translateX,
+			translateY: options.translateY
+		};
+		executeSvgPathString({
+			pathData,
+			sink: {
+				moveTo: (x, y) => {
+					this.moveTo(x, y);
+				},
+				lineTo: (x, y) => {
+					this.lineTo(x, y);
+				},
+				curveTo: (cp1x, cp1y, cp2x, cp2y, x, y) => {
+					this.curveTo(cp1x, cp1y, cp2x, cp2y, x, y);
+				},
+				quadraticCurveTo: (cpx, cpy, x, y) => {
+					this.quadraticCurveTo(cpx, cpy, x, y);
+				},
+				close: () => {
+					this.close();
+				}
+			},
+			initialX: this.currentX,
+			initialY: this.currentY,
+			...executorOptions
+		});
+		return this;
+	}
+	/**
 	* Stroke the path with the given options.
 	*/
 	stroke(options = {}) {
@@ -23904,7 +24817,7 @@ var PathBuilder = class {
 			dashArray: options.dashArray,
 			dashPhase: options.dashPhase,
 			windingRule: options.windingRule,
-			graphicsStateName: gsName ?? void 0
+			graphicsStateName: gsName ? `/${gsName}` : void 0
 		});
 		this.emitOps(ops);
 	}
@@ -24499,7 +25412,7 @@ var PDFPage = class PDFPage {
 			dashArray: options.borderDashArray,
 			dashPhase: options.borderDashPhase,
 			cornerRadius: options.cornerRadius,
-			graphicsStateName: gsName ?? void 0,
+			graphicsStateName: gsName ? `/${gsName}` : void 0,
 			rotate
 		});
 		this.appendOperators(ops);
@@ -24538,7 +25451,7 @@ var PDFPage = class PDFPage {
 			dashArray: options.dashArray,
 			dashPhase: options.dashPhase,
 			lineCap: options.lineCap,
-			graphicsStateName: gsName ?? void 0
+			graphicsStateName: gsName ? `/${gsName}` : void 0
 		});
 		this.appendOperators(ops);
 	}
@@ -24566,7 +25479,7 @@ var PDFPage = class PDFPage {
 			fillColor: options.color,
 			strokeColor: options.borderColor,
 			strokeWidth: options.borderWidth,
-			graphicsStateName: gsName ?? void 0
+			graphicsStateName: gsName ? `/${gsName}` : void 0
 		});
 		this.appendOperators(ops);
 	}
@@ -24613,7 +25526,7 @@ var PDFPage = class PDFPage {
 			fillColor: options.color,
 			strokeColor: options.borderColor,
 			strokeWidth: options.borderWidth,
-			graphicsStateName: gsName ?? void 0,
+			graphicsStateName: gsName ? `/${gsName}` : void 0,
 			rotate
 		});
 		this.appendOperators(ops);
@@ -24670,7 +25583,7 @@ var PDFPage = class PDFPage {
 			width: measureText(line, font, fontSize)
 		}));
 		const ops = [pushGraphicsState()];
-		if (gsName) ops.push(setGraphicsState(gsName));
+		if (gsName) ops.push(setGraphicsState(`/${gsName}`));
 		if (options.rotate) {
 			const textWidth = options.maxWidth ?? Math.max(...lines.map((l) => l.width));
 			let ascent;
@@ -24839,6 +25752,76 @@ var PDFPage = class PDFPage {
 	drawPath() {
 		return new PathBuilder((content) => this.appendContent(content), (fillOpacity, strokeOpacity) => this.registerGraphicsStateForOpacity(fillOpacity, strokeOpacity));
 	}
+	/**
+	* Draw an SVG path on the page.
+	*
+	* This is a convenience method that parses an SVG path `d` attribute string
+	* and draws it with the specified options. For more control, use `drawPath()`
+	* with `appendSvgPath()`.
+	*
+	* By default, the path is filled with black. Specify `borderColor` without
+	* `color` to stroke without filling.
+	*
+	* SVG paths are automatically transformed from SVG coordinate space (Y-down)
+	* to PDF coordinate space (Y-up). Use `x`, `y` to position the path, and
+	* `scale` to resize it.
+	*
+	* @param pathData - SVG path `d` attribute string
+	* @param options - Drawing options (x, y, scale, color, etc.)
+	*
+	* @example
+	* ```typescript
+	* // Draw a Font Awesome heart icon at position (100, 500)
+	* // Icon is 512x512 in SVG, scale to ~50pt
+	* page.drawSvgPath(faHeartPath, {
+	*   x: 100,
+	*   y: 500,
+	*   scale: 0.1,
+	*   color: rgb(1, 0, 0),
+	* });
+	*
+	* // Draw a simple triangle at default position (0, 0)
+	* page.drawSvgPath("M 0 0 L 50 0 L 25 40 Z", {
+	*   color: rgb(0, 0, 1),
+	* });
+	*
+	* // Stroke a curve
+	* page.drawSvgPath("M 0 0 C 10 10, 30 10, 40 0", {
+	*   x: 200,
+	*   y: 300,
+	*   borderColor: rgb(0, 0, 0),
+	*   borderWidth: 2,
+	* });
+	* ```
+	*/
+	drawSvgPath(pathData, options = {}) {
+		const x = options.x ?? 0;
+		const y = options.y ?? 0;
+		const scale = options.scale ?? 1;
+		const flipY = options.flipY ?? true;
+		const builder = this.drawPath();
+		builder.appendSvgPath(pathData, {
+			flipY,
+			scale,
+			translateX: x,
+			translateY: y
+		});
+		const hasFill = options.color !== void 0;
+		const hasStroke = options.borderColor !== void 0;
+		if (hasFill && hasStroke) {
+			builder.fillAndStroke(options);
+			return;
+		}
+		if (hasStroke) {
+			builder.stroke(options);
+			return;
+		}
+		const fillOptions = hasFill ? options : {
+			...options,
+			color: black
+		};
+		builder.fill(fillOptions);
+	}
 	/** Cached annotations for this page */
 	_annotationCache = null;
 	/**
@@ -25447,8 +26430,8 @@ var PDFPage = class PDFPage {
 	registerGraphicsStateForOpacity(fillOpacity, strokeOpacity) {
 		if (fillOpacity === void 0 && strokeOpacity === void 0) return null;
 		const params = {};
-		if (fillOpacity !== void 0) params.CA = Math.max(0, Math.min(1, fillOpacity));
-		if (strokeOpacity !== void 0) params.ca = Math.max(0, Math.min(1, strokeOpacity));
+		if (fillOpacity !== void 0) params.ca = Math.max(0, Math.min(1, fillOpacity));
+		if (strokeOpacity !== void 0) params.CA = Math.max(0, Math.min(1, strokeOpacity));
 		return this.addGraphicsState(params);
 	}
 	/**