modern-pdf-lib 0.12.0 → 0.13.0

package/dist/{pdfPage-BMGFx7Xd.cjs → pdfPage-BebMv6fN.cjs}

@@ -2705,6 +2705,162 @@ function drawSvgOnPage(page, svgString, options) {
 	page.pushOperators(ops);
 }
 
+//#endregion
+//#region src/core/pdfPageSvg.ts
+/** Format a number for PDF output. */
+function fmtN(value) {
+	if (Number.isInteger(value)) return value.toString();
+	const s = value.toFixed(6).replace(/\.?0+$/, "");
+	return s === "-0" ? "0" : s;
+}
+/** Magic constant for circular arc approximation: 4*(sqrt(2)-1)/3. */
+const KAPPA = .5522847498;
+/**
+* Approximate an SVG arc command as cubic Bezier curve(s) (PDF operators).
+*
+* SVG arcs use endpoint parameterization; PDF has no native arc command.
+*/
+function svgArcToPdfOps(fromX, fromY, rx0, ry0, rotationDeg, largeArcFlag, sweepFlag, toX, toY) {
+	let rx = Math.abs(rx0);
+	let ry = Math.abs(ry0);
+	if (rx === 0 || ry === 0) return `${fmtN(toX)} ${fmtN(toY)} l\n`;
+	const phi = rotationDeg * Math.PI / 180;
+	const cosPhi = Math.cos(phi);
+	const sinPhi = Math.sin(phi);
+	const dx2 = (fromX - toX) / 2;
+	const dy2 = (fromY - toY) / 2;
+	const x1p = cosPhi * dx2 + sinPhi * dy2;
+	const y1p = -sinPhi * dx2 + cosPhi * dy2;
+	let rxSq = rx * rx;
+	let rySq = ry * ry;
+	const x1pSq = x1p * x1p;
+	const y1pSq = y1p * y1p;
+	const lambda = x1pSq / rxSq + y1pSq / rySq;
+	if (lambda > 1) {
+		const s = Math.sqrt(lambda);
+		rx *= s;
+		ry *= s;
+		rxSq = rx * rx;
+		rySq = ry * ry;
+	}
+	let sq = (rxSq * rySq - rxSq * y1pSq - rySq * x1pSq) / (rxSq * y1pSq + rySq * x1pSq);
+	if (sq < 0) sq = 0;
+	sq = Math.sqrt(sq);
+	if (largeArcFlag === sweepFlag) sq = -sq;
+	const cxp = sq * rx * y1p / ry;
+	const cyp = -sq * ry * x1p / rx;
+	const cx = cosPhi * cxp - sinPhi * cyp + (fromX + toX) / 2;
+	const cy = sinPhi * cxp + cosPhi * cyp + (fromY + toY) / 2;
+	function vecAngle(ux, uy, vx, vy) {
+		const sign = ux * vy - uy * vx < 0 ? -1 : 1;
+		let r = (ux * vx + uy * vy) / (Math.sqrt(ux * ux + uy * uy) * Math.sqrt(vx * vx + vy * vy));
+		if (r < -1) r = -1;
+		if (r > 1) r = 1;
+		return sign * Math.acos(r);
+	}
+	const theta1 = vecAngle(1, 0, (x1p - cxp) / rx, (y1p - cyp) / ry);
+	let dTheta = vecAngle((x1p - cxp) / rx, (y1p - cyp) / ry, (-x1p - cxp) / rx, (-y1p - cyp) / ry);
+	if (sweepFlag === 0 && dTheta > 0) dTheta -= 2 * Math.PI;
+	if (sweepFlag === 1 && dTheta < 0) dTheta += 2 * Math.PI;
+	const segs = Math.ceil(Math.abs(dTheta) / (Math.PI / 2));
+	const segAngle = dTheta / segs;
+	let ops = "";
+	let angle = theta1;
+	for (let i = 0; i < segs; i++) {
+		const a1 = angle;
+		const a2 = angle + segAngle;
+		const alpha = 4 / 3 * Math.tan((a2 - a1) / 4);
+		const cos1 = Math.cos(a1), sin1 = Math.sin(a1);
+		const cos2 = Math.cos(a2), sin2 = Math.sin(a2);
+		const ep1x = cosPhi * rx * cos1 - sinPhi * ry * sin1 + cx;
+		const ep1y = sinPhi * rx * cos1 + cosPhi * ry * sin1 + cy;
+		const cp1x = ep1x + alpha * (-cosPhi * rx * sin1 - sinPhi * ry * cos1);
+		const cp1y = ep1y + alpha * (-sinPhi * rx * sin1 + cosPhi * ry * cos1);
+		const ep2x = cosPhi * rx * cos2 - sinPhi * ry * sin2 + cx;
+		const ep2y = sinPhi * rx * cos2 + cosPhi * ry * sin2 + cy;
+		const cp2x = ep2x - alpha * (-cosPhi * rx * sin2 - sinPhi * ry * cos2);
+		const cp2y = ep2y - alpha * (-sinPhi * rx * sin2 + cosPhi * ry * cos2);
+		ops += `${fmtN(cp1x)} ${fmtN(cp1y)} ${fmtN(cp2x)} ${fmtN(cp2y)} ${fmtN(ep2x)} ${fmtN(ep2y)} c\n`;
+		angle = a2;
+	}
+	return ops;
+}
+/**
+* Convert parsed SVG draw commands into PDF path construction operators.
+*
+* Does **not** emit painting operators (fill / stroke) -- the caller
+* is responsible for that.
+*/
+function svgCommandsToPdfOps(commands) {
+	let ops = "";
+	let curX = 0;
+	let curY = 0;
+	for (const cmd of commands) switch (cmd.type) {
+		case "moveTo":
+			curX = cmd.params[0];
+			curY = cmd.params[1];
+			ops += `${fmtN(curX)} ${fmtN(curY)} m\n`;
+			break;
+		case "lineTo":
+			curX = cmd.params[0];
+			curY = cmd.params[1];
+			ops += `${fmtN(curX)} ${fmtN(curY)} l\n`;
+			break;
+		case "curveTo":
+			ops += `${fmtN(cmd.params[0])} ${fmtN(cmd.params[1])} ${fmtN(cmd.params[2])} ${fmtN(cmd.params[3])} ${fmtN(cmd.params[4])} ${fmtN(cmd.params[5])} c\n`;
+			curX = cmd.params[4];
+			curY = cmd.params[5];
+			break;
+		case "quadCurveTo": {
+			const cpx = cmd.params[0];
+			const cpy = cmd.params[1];
+			const toX = cmd.params[2];
+			const toY = cmd.params[3];
+			const cp1x = curX + 2 / 3 * (cpx - curX);
+			const cp1y = curY + 2 / 3 * (cpy - curY);
+			const cp2x = toX + 2 / 3 * (cpx - toX);
+			const cp2y = toY + 2 / 3 * (cpy - toY);
+			ops += `${fmtN(cp1x)} ${fmtN(cp1y)} ${fmtN(cp2x)} ${fmtN(cp2y)} ${fmtN(toX)} ${fmtN(toY)} c\n`;
+			curX = toX;
+			curY = toY;
+			break;
+		}
+		case "closePath":
+			ops += "h\n";
+			break;
+		case "rect":
+			ops += `${fmtN(cmd.params[0])} ${fmtN(cmd.params[1])} ${fmtN(cmd.params[2])} ${fmtN(cmd.params[3])} re\n`;
+			break;
+		case "circle": {
+			const ccx = cmd.params[0], ccy = cmd.params[1], r = cmd.params[2];
+			const ox = r * KAPPA, oy = r * KAPPA;
+			ops += `${fmtN(ccx)} ${fmtN(ccy + r)} m\n`;
+			ops += `${fmtN(ccx + ox)} ${fmtN(ccy + r)} ${fmtN(ccx + r)} ${fmtN(ccy + oy)} ${fmtN(ccx + r)} ${fmtN(ccy)} c\n`;
+			ops += `${fmtN(ccx + r)} ${fmtN(ccy - oy)} ${fmtN(ccx + ox)} ${fmtN(ccy - r)} ${fmtN(ccx)} ${fmtN(ccy - r)} c\n`;
+			ops += `${fmtN(ccx - ox)} ${fmtN(ccy - r)} ${fmtN(ccx - r)} ${fmtN(ccy - oy)} ${fmtN(ccx - r)} ${fmtN(ccy)} c\n`;
+			ops += `${fmtN(ccx - r)} ${fmtN(ccy + oy)} ${fmtN(ccx - ox)} ${fmtN(ccy + r)} ${fmtN(ccx)} ${fmtN(ccy + r)} c\n`;
+			break;
+		}
+		case "ellipse": {
+			const ecx = cmd.params[0], ecy = cmd.params[1];
+			const erx = cmd.params[2], ery = cmd.params[3];
+			const eox = erx * KAPPA, eoy = ery * KAPPA;
+			ops += `${fmtN(ecx)} ${fmtN(ecy + ery)} m\n`;
+			ops += `${fmtN(ecx + eox)} ${fmtN(ecy + ery)} ${fmtN(ecx + erx)} ${fmtN(ecy + eoy)} ${fmtN(ecx + erx)} ${fmtN(ecy)} c\n`;
+			ops += `${fmtN(ecx + erx)} ${fmtN(ecy - eoy)} ${fmtN(ecx + eox)} ${fmtN(ecy - ery)} ${fmtN(ecx)} ${fmtN(ecy - ery)} c\n`;
+			ops += `${fmtN(ecx - eox)} ${fmtN(ecy - ery)} ${fmtN(ecx - erx)} ${fmtN(ecy - eoy)} ${fmtN(ecx - erx)} ${fmtN(ecy)} c\n`;
+			ops += `${fmtN(ecx - erx)} ${fmtN(ecy + eoy)} ${fmtN(ecx - eox)} ${fmtN(ecy + ery)} ${fmtN(ecx)} ${fmtN(ecy + ery)} c\n`;
+			break;
+		}
+		case "arc":
+			ops += svgArcToPdfOps(curX, curY, cmd.params[0], cmd.params[1], cmd.params[2], cmd.params[3], cmd.params[4], cmd.params[5], cmd.params[6]);
+			curX = cmd.params[5];
+			curY = cmd.params[6];
+			break;
+	}
+	return ops;
+}
+
 //#endregion
 //#region src/layers/optionalContent.ts
 /**
@@ -3009,66 +3165,238 @@ function getRedactionMarks(page) {
 }
 
 //#endregion
-//#region src/core/pdfPage.ts
-var pdfPage_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
-	PageSizes: () => PageSizes,
-	PdfPage: () => PdfPage,
-	wrapText: () => wrapText
-});
-/** Pre-defined page sizes as `[width, height]` tuples in PDF points. */
-const PageSizes = {
-	"4A0": [4767.87, 6740.79],
-	"2A0": [3370.39, 4767.87],
-	A0: [2383.94, 3370.39],
-	A1: [1683.78, 2383.94],
-	A2: [1190.55, 1683.78],
-	A3: [841.89, 1190.55],
-	A4: [595.28, 841.89],
-	A5: [419.53, 595.28],
-	A6: [297.64, 419.53],
-	A7: [209.76, 297.64],
-	A8: [147.4, 209.76],
-	A9: [104.88, 147.4],
-	A10: [73.7, 104.88],
-	B0: [2834.65, 4008.19],
-	B1: [2004.09, 2834.65],
-	B2: [1417.32, 2004.09],
-	B3: [1000.63, 1417.32],
-	B4: [708.66, 1000.63],
-	B5: [498.9, 708.66],
-	B6: [354.33, 498.9],
-	B7: [249.45, 354.33],
-	B8: [175.75, 249.45],
-	B9: [124.72, 175.75],
-	B10: [87.87, 124.72],
-	Letter: [612, 792],
-	Legal: [612, 1008],
-	Tabloid: [792, 1224],
-	Ledger: [1224, 792],
-	Executive: [521.86, 756],
-	Folio: [612, 936],
-	C0: [2599.37, 3676.54],
-	C1: [1836.85, 2599.37],
-	C2: [1298.27, 1836.85],
-	C3: [918.43, 1298.27],
-	C4: [649.13, 918.43],
-	C5: [459.21, 649.13],
-	C6: [323.15, 459.21],
-	C7: [229.61, 323.15],
-	C8: [161.57, 229.61],
-	C9: [113.39, 161.57],
-	C10: [79.37, 113.39],
-	RA0: [2437.8, 3458.27],
-	RA1: [1729.13, 2437.8],
-	RA2: [1218.9, 1729.13],
-	RA3: [864.57, 1218.9],
-	RA4: [609.45, 864.57],
-	SRA0: [2551.18, 3628.35],
-	SRA1: [1814.17, 2551.18],
-	SRA2: [1275.59, 1814.17],
-	SRA3: [907.09, 1275.59],
-	SRA4: [637.8, 907.09]
-};
+//#region src/core/patterns.ts
+/** Convert a Color to RGB components (0..1). CMYK/gray are converted. */
+function colorToRgb(c) {
+	switch (c.type) {
+		case "rgb": return {
+			r: c.r,
+			g: c.g,
+			b: c.b
+		};
+		case "grayscale": return {
+			r: c.gray,
+			g: c.gray,
+			b: c.gray
+		};
+		case "cmyk": return {
+			r: (1 - c.c) * (1 - c.k),
+			g: (1 - c.m) * (1 - c.k),
+			b: (1 - c.y) * (1 - c.k)
+		};
+	}
+}
+/** Check if a stop is a ColorStop (has `offset` property). */
+function isColorStop(stop) {
+	return "offset" in stop && "color" in stop;
+}
+/**
+* Normalise an array of stops into sorted, explicit-offset RGB stops.
+* Bare Color values get evenly-distributed offsets.
+*/
+function normalizeStops(stops) {
+	if (stops.length < 2) throw new Error("Gradient requires at least 2 colour stops");
+	const result = [];
+	for (let i = 0; i < stops.length; i++) {
+		const stop = stops[i];
+		let offset;
+		let color;
+		if (isColorStop(stop)) {
+			offset = stop.offset;
+			color = stop.color;
+		} else {
+			offset = i / (stops.length - 1);
+			color = stop;
+		}
+		const { r, g, b } = colorToRgb(color);
+		result.push({
+			offset,
+			r,
+			g,
+			b
+		});
+	}
+	result.sort((a, b) => a.offset - b.offset);
+	return result;
+}
+/**
+* Create a linear (axial) gradient descriptor.
+*
+* The gradient runs from `(x1, y1)` to `(x2, y2)` through the given
+* colour stops.  By default the gradient extends beyond its endpoints.
+*
+* @param options  Gradient parameters.
+* @returns A {@link GradientFill} descriptor.
+*/
+function linearGradient(options) {
+	const normalizedStops = normalizeStops(options.stops);
+	return {
+		kind: "gradient",
+		shadingType: 2,
+		coords: [
+			options.x1,
+			options.y1,
+			options.x2,
+			options.y2
+		],
+		normalizedStops,
+		extend: options.extend ?? true
+	};
+}
+/**
+* Create a radial gradient descriptor.
+*
+* The gradient interpolates between two circles: the start circle at
+* `(x0, y0)` with radius `r0` and the end circle at `(x1, y1)` with
+* radius `r1`.
+*
+* @param options  Gradient parameters.
+* @returns A {@link GradientFill} descriptor (with `shadingType: 3`).
+*/
+function radialGradient(options) {
+	const normalizedStops = normalizeStops(options.stops);
+	return {
+		kind: "gradient",
+		shadingType: 3,
+		coords: [
+			options.x0,
+			options.y0,
+			options.r0,
+			options.x1,
+			options.y1,
+			options.r1
+		],
+		normalizedStops,
+		extend: options.extend ?? true
+	};
+}
+/**
+* Create a tiling pattern descriptor.
+*
+* @param options  Pattern parameters including the tile content stream.
+* @returns A {@link PatternFill} descriptor.
+*/
+function tilingPattern(options) {
+	return {
+		kind: "pattern",
+		width: options.width,
+		height: options.height,
+		paintType: options.paintType ?? 1,
+		tilingType: options.tilingType ?? 1,
+		ops: options.ops
+	};
+}
+/**
+* Build a Type 2 (exponential interpolation) function for a single
+* colour-transition segment between two RGB stops.
+*/
+function buildType2Function(c0, c1) {
+	const fn = new require_pdfCatalog.PdfDict();
+	fn.set("/FunctionType", require_pdfCatalog.PdfNumber.of(2));
+	fn.set("/Domain", require_pdfCatalog.PdfArray.fromNumbers([0, 1]));
+	fn.set("/C0", require_pdfCatalog.PdfArray.fromNumbers([
+		c0.r,
+		c0.g,
+		c0.b
+	]));
+	fn.set("/C1", require_pdfCatalog.PdfArray.fromNumbers([
+		c1.r,
+		c1.g,
+		c1.b
+	]));
+	fn.set("/N", require_pdfCatalog.PdfNumber.of(1));
+	return fn;
+}
+/**
+* Build the shading function for a gradient.
+*
+* - 2 stops → single Type 2 (exponential interpolation) function.
+* - 3+ stops → Type 3 (stitching) function wrapping one Type 2 per segment.
+*/
+function buildShadingFunction(stops, registry) {
+	if (stops.length === 2) {
+		const fn = buildType2Function(stops[0], stops[1]);
+		return registry.register(fn);
+	}
+	const stitchDict = new require_pdfCatalog.PdfDict();
+	stitchDict.set("/FunctionType", require_pdfCatalog.PdfNumber.of(3));
+	stitchDict.set("/Domain", require_pdfCatalog.PdfArray.fromNumbers([0, 1]));
+	const subFunctions = [];
+	const bounds = [];
+	const encode = [];
+	for (let i = 0; i < stops.length - 1; i++) {
+		const fn = buildType2Function(stops[i], stops[i + 1]);
+		subFunctions.push(registry.register(fn));
+		if (i > 0) bounds.push(stops[i].offset);
+		encode.push(0, 1);
+	}
+	stitchDict.set("/Functions", require_pdfCatalog.PdfArray.of(subFunctions));
+	stitchDict.set("/Bounds", require_pdfCatalog.PdfArray.fromNumbers(bounds));
+	stitchDict.set("/Encode", require_pdfCatalog.PdfArray.fromNumbers(encode));
+	return registry.register(stitchDict);
+}
+/**
+* Materialise a {@link GradientFill} descriptor into actual PDF objects
+* in the given registry.
+*
+* @param gradient  The gradient descriptor.
+* @param registry  The document's object registry.
+* @returns An object with the pattern's indirect reference and a unique
+*          resource name.
+*/
+function buildGradientObjects(gradient, registry) {
+	const fnRef = buildShadingFunction(gradient.normalizedStops, registry);
+	const shadingDict = new require_pdfCatalog.PdfDict();
+	shadingDict.set("/ShadingType", require_pdfCatalog.PdfNumber.of(gradient.shadingType));
+	shadingDict.set("/ColorSpace", require_pdfCatalog.PdfName.of("DeviceRGB"));
+	shadingDict.set("/Coords", require_pdfCatalog.PdfArray.fromNumbers([...gradient.coords]));
+	shadingDict.set("/Function", fnRef);
+	shadingDict.set("/Extend", require_pdfCatalog.PdfArray.of([require_pdfCatalog.PdfBool.of(gradient.extend), require_pdfCatalog.PdfBool.of(gradient.extend)]));
+	const shadingRef = registry.register(shadingDict);
+	const patternDict = new require_pdfCatalog.PdfDict();
+	patternDict.set("/Type", require_pdfCatalog.PdfName.of("Pattern"));
+	patternDict.set("/PatternType", require_pdfCatalog.PdfNumber.of(2));
+	patternDict.set("/Shading", shadingRef);
+	const patternRef = registry.register(patternDict);
+	return {
+		patternRef,
+		patternName: `Pat${patternRef.objectNumber}`
+	};
+}
+/**
+* Materialise a {@link PatternFill} descriptor into actual PDF objects
+* in the given registry.
+*
+* @param pattern   The tiling pattern descriptor.
+* @param registry  The document's object registry.
+* @returns An object with the pattern's indirect reference and a unique
+*          resource name.
+*/
+function buildPatternObjects(pattern, registry) {
+	const dict = new require_pdfCatalog.PdfDict();
+	dict.set("/Type", require_pdfCatalog.PdfName.of("Pattern"));
+	dict.set("/PatternType", require_pdfCatalog.PdfNumber.of(1));
+	dict.set("/PaintType", require_pdfCatalog.PdfNumber.of(pattern.paintType));
+	dict.set("/TilingType", require_pdfCatalog.PdfNumber.of(pattern.tilingType));
+	dict.set("/BBox", require_pdfCatalog.PdfArray.fromNumbers([
+		0,
+		0,
+		pattern.width,
+		pattern.height
+	]));
+	dict.set("/XStep", require_pdfCatalog.PdfNumber.of(pattern.width));
+	dict.set("/YStep", require_pdfCatalog.PdfNumber.of(pattern.height));
+	dict.set("/Resources", new require_pdfCatalog.PdfDict());
+	const stream = require_pdfCatalog.PdfStream.fromString(pattern.ops, dict);
+	const patternRef = registry.register(stream);
+	return {
+		patternRef,
+		patternName: `Pat${patternRef.objectNumber}`
+	};
+}
+
+//#endregion
+//#region src/core/pdfPageText.ts
 /**
 * Break a single line of text into multiple lines that fit within `maxWidth`.
 *
@@ -3153,6 +3481,67 @@ function breakWord(word, maxWidth, font, size) {
 	if (current !== "") fragments.push(current);
 	return fragments;
 }
+
+//#endregion
+//#region src/core/pdfPage.ts
+var pdfPage_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
+	PageSizes: () => PageSizes,
+	PdfPage: () => PdfPage
+});
+/** Pre-defined page sizes as `[width, height]` tuples in PDF points. */
+const PageSizes = {
+	"4A0": [4767.87, 6740.79],
+	"2A0": [3370.39, 4767.87],
+	A0: [2383.94, 3370.39],
+	A1: [1683.78, 2383.94],
+	A2: [1190.55, 1683.78],
+	A3: [841.89, 1190.55],
+	A4: [595.28, 841.89],
+	A5: [419.53, 595.28],
+	A6: [297.64, 419.53],
+	A7: [209.76, 297.64],
+	A8: [147.4, 209.76],
+	A9: [104.88, 147.4],
+	A10: [73.7, 104.88],
+	B0: [2834.65, 4008.19],
+	B1: [2004.09, 2834.65],
+	B2: [1417.32, 2004.09],
+	B3: [1000.63, 1417.32],
+	B4: [708.66, 1000.63],
+	B5: [498.9, 708.66],
+	B6: [354.33, 498.9],
+	B7: [249.45, 354.33],
+	B8: [175.75, 249.45],
+	B9: [124.72, 175.75],
+	B10: [87.87, 124.72],
+	Letter: [612, 792],
+	Legal: [612, 1008],
+	Tabloid: [792, 1224],
+	Ledger: [1224, 792],
+	Executive: [521.86, 756],
+	Folio: [612, 936],
+	C0: [2599.37, 3676.54],
+	C1: [1836.85, 2599.37],
+	C2: [1298.27, 1836.85],
+	C3: [918.43, 1298.27],
+	C4: [649.13, 918.43],
+	C5: [459.21, 649.13],
+	C6: [323.15, 459.21],
+	C7: [229.61, 323.15],
+	C8: [161.57, 229.61],
+	C9: [113.39, 161.57],
+	C10: [79.37, 113.39],
+	RA0: [2437.8, 3458.27],
+	RA1: [1729.13, 2437.8],
+	RA2: [1218.9, 1729.13],
+	RA3: [864.57, 1218.9],
+	RA4: [609.45, 864.57],
+	SRA0: [2551.18, 3628.35],
+	SRA1: [1814.17, 2551.18],
+	SRA2: [1275.59, 1814.17],
+	SRA3: [907.09, 1275.59],
+	SRA4: [637.8, 907.09]
+};
 /**
 * A single page in a PDF document.
 *
@@ -3180,10 +3569,25 @@ var PdfPage = class PdfPage {
 	*/
 	extGStates = /* @__PURE__ */ new Map();
 	/**
+	* Pattern resources referenced by this page.
+	* Maps a resource name (e.g. `Pat5`) to its indirect reference.
+	* Used for gradient fills and tiling patterns.
+	*/
+	patterns = /* @__PURE__ */ new Map();
+	/**
 	* Counter for ExtGState resource names (`GS1`, `GS2`, ...).
 	*/
 	extGStateCounter = 0;
 	/**
+	* Counter for transparency group XObject resource names (`TG1`, `TG2`, ...).
+	*/
+	transparencyGroupCounter = 0;
+	/**
+	* Stack of transparency group state.  Each entry records the ops length
+	* at the time `beginTransparencyGroup()` was called, plus the options.
+	*/
+	transparencyGroupStack = [];
+	/**
 	* Cache mapping composite keys (opacity + blend mode) to their ExtGState
 	* resource names, so the same combination reuses the same graphics state
 	* dictionary.
@@ -3323,6 +3727,10 @@ var PdfPage = class PdfPage {
 	registerExtGState(name, ref) {
 		this.extGStates.set(name, ref);
 	}
+	/** @internal Register a Pattern resource on this page. */
+	registerPattern(name, ref) {
+		this.patterns.set(name, ref);
+	}
 	/**
 	* Set the default font used by {@link drawText} when the `font` option
 	* is not provided.
@@ -4224,6 +4632,51 @@ var PdfPage = class PdfPage {
 		this.ops += restoreState();
 	}
 	/**
+	* Draw a gradient fill (linear or radial) clipped to a rectangle.
+	*
+	* The gradient is registered as a `/Pattern` resource on this page
+	* and painted within the specified rectangular region.
+	*
+	* @param gradient  A gradient descriptor from {@link linearGradient}
+	*                  or {@link radialGradient}.
+	* @param rect      The rectangle to fill.
+	*/
+	drawGradient(gradient, rect) {
+		const { patternRef, patternName } = buildGradientObjects(gradient, this.registry);
+		this.patterns.set(patternName, patternRef);
+		this.ops += saveState();
+		this.ops += rectangle(rect.x, rect.y, rect.width, rect.height);
+		this.ops += clip();
+		this.ops += endPath();
+		this.ops += setColorSpace("Pattern");
+		this.ops += `/${patternName} scn\n`;
+		this.ops += rectangle(rect.x, rect.y, rect.width, rect.height);
+		this.ops += fill();
+		this.ops += restoreState();
+	}
+	/**
+	* Draw a tiling pattern fill clipped to a rectangle.
+	*
+	* The pattern is registered as a `/Pattern` resource on this page
+	* and painted within the specified rectangular region.
+	*
+	* @param pattern  A pattern descriptor from {@link tilingPattern}.
+	* @param rect     The rectangle to fill.
+	*/
+	drawPattern(pattern, rect) {
+		const { patternRef, patternName } = buildPatternObjects(pattern, this.registry);
+		this.patterns.set(patternName, patternRef);
+		this.ops += saveState();
+		this.ops += rectangle(rect.x, rect.y, rect.width, rect.height);
+		this.ops += clip();
+		this.ops += endPath();
+		this.ops += setColorSpace("Pattern");
+		this.ops += `/${patternName} scn\n`;
+		this.ops += rectangle(rect.x, rect.y, rect.width, rect.height);
+		this.ops += fill();
+		this.ops += restoreState();
+	}
+	/**
 	* Begin layer-specific content.
 	*
 	* Content drawn after this call and before {@link endLayer} will be
@@ -4244,6 +4697,120 @@ var PdfPage = class PdfPage {
 		this.ops += endLayerContent();
 	}
 	/**
+	* Begin a transparency group.  All drawing operations until
+	* {@link endTransparencyGroup} will be captured and composited as a
+	* single Form XObject with a `/Group` transparency dictionary.
+	*
+	* Transparency groups enable isolated and knockout compositing effects
+	* that are not possible with simple opacity settings.
+	*
+	* Groups can be nested — each call must be paired with a matching
+	* {@link endTransparencyGroup}.
+	*
+	* @param options  Isolation, knockout, and color-space settings.
+	*
+	* @example
+	* ```ts
+	* page.beginTransparencyGroup({ isolated: true });
+	* page.drawRectangle({ x: 50, y: 50, width: 100, height: 100, opacity: 0.5 });
+	* page.drawCircle({ x: 100, y: 100, size: 60, opacity: 0.5 });
+	* page.endTransparencyGroup();
+	* ```
+	*/
+	beginTransparencyGroup(options) {
+		this.transparencyGroupStack.push({
+			opsStart: this.ops.length,
+			options: options ?? {}
+		});
+	}
+	/**
+	* End the current transparency group and composite it onto the page
+	* as a Form XObject.
+	*
+	* @throws {Error} If there is no matching {@link beginTransparencyGroup}.
+	*/
+	endTransparencyGroup() {
+		const group = this.transparencyGroupStack.pop();
+		if (!group) throw new Error("No transparency group to end — call beginTransparencyGroup() first");
+		const groupOps = this.ops.slice(group.opsStart);
+		this.ops = this.ops.slice(0, group.opsStart);
+		const colorSpace = group.options.colorSpace ?? "DeviceRGB";
+		const groupDict = new require_pdfCatalog.PdfDict();
+		groupDict.set("/S", require_pdfCatalog.PdfName.of("Transparency"));
+		groupDict.set("/I", require_pdfCatalog.PdfBool.of(group.options.isolated ?? true));
+		groupDict.set("/K", require_pdfCatalog.PdfBool.of(group.options.knockout ?? false));
+		groupDict.set("/CS", require_pdfCatalog.PdfName.of(colorSpace));
+		const bbox = require_pdfCatalog.PdfArray.fromNumbers([
+			this.mediaX,
+			this.mediaY,
+			this.mediaX + this.mediaWidth,
+			this.mediaY + this.mediaHeight
+		]);
+		const formDict = new require_pdfCatalog.PdfDict();
+		formDict.set("/Type", require_pdfCatalog.PdfName.of("XObject"));
+		formDict.set("/Subtype", require_pdfCatalog.PdfName.of("Form"));
+		formDict.set("/BBox", bbox);
+		formDict.set("/Group", groupDict);
+		const formStream = require_pdfCatalog.PdfStream.fromString(groupOps, formDict);
+		const formRef = this.registry.register(formStream);
+		this.transparencyGroupCounter++;
+		const name = `TG${this.transparencyGroupCounter}`;
+		this.registerXObject(name, formRef);
+		this.ops += saveState();
+		this.ops += drawXObject(name);
+		this.ops += restoreState();
+	}
+	/**
+	* Apply a soft mask (luminosity-based) for subsequent drawing operations.
+	*
+	* White regions in the mask are fully opaque; black regions are fully
+	* transparent.  The mask stays active until {@link clearSoftMask} is
+	* called or the graphics state is restored.
+	*
+	* @param mask  A soft mask reference created by
+	*              {@link PdfDocument.createSoftMask}.
+	*
+	* @example
+	* ```ts
+	* const mask = doc.createSoftMask(200, 200, (b) => {
+	*   b.drawRectangle(0, 0, 200, 200, 1);   // white = opaque
+	*   b.drawCircle(100, 100, 80, 0);         // black = transparent
+	* });
+	* page.applySoftMask(mask);
+	* page.drawImage(image, { x: 50, y: 50, width: 200, height: 200 });
+	* page.clearSoftMask();
+	* ```
+	*/
+	applySoftMask(mask) {
+		const smaskDict = new require_pdfCatalog.PdfDict();
+		smaskDict.set("/S", require_pdfCatalog.PdfName.of("Luminosity"));
+		smaskDict.set("/G", mask.ref);
+		const gsDict = new require_pdfCatalog.PdfDict();
+		gsDict.set("/Type", require_pdfCatalog.PdfName.of("ExtGState"));
+		gsDict.set("/SMask", smaskDict);
+		const gsRef = this.registry.register(gsDict);
+		this.extGStateCounter++;
+		const gsName = `GS${this.extGStateCounter}`;
+		this.extGStates.set(gsName, gsRef);
+		this.ops += setGraphicsState(gsName);
+	}
+	/**
+	* Clear the current soft mask, resetting to no masking.
+	*
+	* This emits an ExtGState with `/SMask /None`, which removes any
+	* previously applied soft mask for subsequent drawing operations.
+	*/
+	clearSoftMask() {
+		const gsDict = new require_pdfCatalog.PdfDict();
+		gsDict.set("/Type", require_pdfCatalog.PdfName.of("ExtGState"));
+		gsDict.set("/SMask", require_pdfCatalog.PdfName.of("None"));
+		const gsRef = this.registry.register(gsDict);
+		this.extGStateCounter++;
+		const gsName = `GS${this.extGStateCounter}`;
+		this.extGStates.set(gsName, gsRef);
+		this.ops += setGraphicsState(gsName);
+	}
+	/**
 	* Mark a rectangular region on this page for redaction.
 	*
 	* The mark is stored but not applied until `doc.applyRedactions()`
@@ -4296,6 +4863,11 @@ var PdfPage = class PdfPage {
 			for (const [name, ref] of this.extGStates) gsDict.set(name, ref);
 			resources.set("/ExtGState", gsDict);
 		}
+		if (this.patterns.size > 0) {
+			const patDict = new require_pdfCatalog.PdfDict();
+			for (const [name, ref] of this.patterns) patDict.set(name, ref);
+			resources.set("/Pattern", patDict);
+		}
 		resources.set("/ProcSet", require_pdfCatalog.PdfArray.of([
 			require_pdfCatalog.PdfName.of("PDF"),
 			require_pdfCatalog.PdfName.of("Text"),
@@ -4341,6 +4913,15 @@ var PdfPage = class PdfPage {
 			const gsDict = gsObj;
 			for (const [name, ref] of this.extGStates) gsDict.set(name, ref);
 		}
+		if (this.patterns.size > 0) {
+			let patObj = resources.get("/Pattern");
+			if (patObj === void 0 || patObj.kind !== "dict") {
+				patObj = new require_pdfCatalog.PdfDict();
+				resources.set("/Pattern", patObj);
+			}
+			const patDict = patObj;
+			for (const [name, ref] of this.patterns) patDict.set(name, ref);
+		}
 		return resources;
 	}
 	/**
@@ -4385,159 +4966,6 @@ var PdfPage = class PdfPage {
 		};
 	}
 };
-/** Format a number for PDF output. */
-function fmtN(value) {
-	if (Number.isInteger(value)) return value.toString();
-	const s = value.toFixed(6).replace(/\.?0+$/, "");
-	return s === "-0" ? "0" : s;
-}
-/** Magic constant for circular arc approximation: 4*(sqrt(2)-1)/3. */
-const KAPPA = .5522847498;
-/**
-* Approximate an SVG arc command as cubic Bezier curve(s) (PDF operators).
-*
-* SVG arcs use endpoint parameterization; PDF has no native arc command.
-*/
-function svgArcToPdfOps(fromX, fromY, rx0, ry0, rotationDeg, largeArcFlag, sweepFlag, toX, toY) {
-	let rx = Math.abs(rx0);
-	let ry = Math.abs(ry0);
-	if (rx === 0 || ry === 0) return `${fmtN(toX)} ${fmtN(toY)} l\n`;
-	const phi = rotationDeg * Math.PI / 180;
-	const cosPhi = Math.cos(phi);
-	const sinPhi = Math.sin(phi);
-	const dx2 = (fromX - toX) / 2;
-	const dy2 = (fromY - toY) / 2;
-	const x1p = cosPhi * dx2 + sinPhi * dy2;
-	const y1p = -sinPhi * dx2 + cosPhi * dy2;
-	let rxSq = rx * rx;
-	let rySq = ry * ry;
-	const x1pSq = x1p * x1p;
-	const y1pSq = y1p * y1p;
-	const lambda = x1pSq / rxSq + y1pSq / rySq;
-	if (lambda > 1) {
-		const s = Math.sqrt(lambda);
-		rx *= s;
-		ry *= s;
-		rxSq = rx * rx;
-		rySq = ry * ry;
-	}
-	let sq = (rxSq * rySq - rxSq * y1pSq - rySq * x1pSq) / (rxSq * y1pSq + rySq * x1pSq);
-	if (sq < 0) sq = 0;
-	sq = Math.sqrt(sq);
-	if (largeArcFlag === sweepFlag) sq = -sq;
-	const cxp = sq * rx * y1p / ry;
-	const cyp = -sq * ry * x1p / rx;
-	const cx = cosPhi * cxp - sinPhi * cyp + (fromX + toX) / 2;
-	const cy = sinPhi * cxp + cosPhi * cyp + (fromY + toY) / 2;
-	function vecAngle(ux, uy, vx, vy) {
-		const sign = ux * vy - uy * vx < 0 ? -1 : 1;
-		let r = (ux * vx + uy * vy) / (Math.sqrt(ux * ux + uy * uy) * Math.sqrt(vx * vx + vy * vy));
-		if (r < -1) r = -1;
-		if (r > 1) r = 1;
-		return sign * Math.acos(r);
-	}
-	const theta1 = vecAngle(1, 0, (x1p - cxp) / rx, (y1p - cyp) / ry);
-	let dTheta = vecAngle((x1p - cxp) / rx, (y1p - cyp) / ry, (-x1p - cxp) / rx, (-y1p - cyp) / ry);
-	if (sweepFlag === 0 && dTheta > 0) dTheta -= 2 * Math.PI;
-	if (sweepFlag === 1 && dTheta < 0) dTheta += 2 * Math.PI;
-	const segs = Math.ceil(Math.abs(dTheta) / (Math.PI / 2));
-	const segAngle = dTheta / segs;
-	let ops = "";
-	let angle = theta1;
-	for (let i = 0; i < segs; i++) {
-		const a1 = angle;
-		const a2 = angle + segAngle;
-		const alpha = 4 / 3 * Math.tan((a2 - a1) / 4);
-		const cos1 = Math.cos(a1), sin1 = Math.sin(a1);
-		const cos2 = Math.cos(a2), sin2 = Math.sin(a2);
-		const ep1x = cosPhi * rx * cos1 - sinPhi * ry * sin1 + cx;
-		const ep1y = sinPhi * rx * cos1 + cosPhi * ry * sin1 + cy;
-		const cp1x = ep1x + alpha * (-cosPhi * rx * sin1 - sinPhi * ry * cos1);
-		const cp1y = ep1y + alpha * (-sinPhi * rx * sin1 + cosPhi * ry * cos1);
-		const ep2x = cosPhi * rx * cos2 - sinPhi * ry * sin2 + cx;
-		const ep2y = sinPhi * rx * cos2 + cosPhi * ry * sin2 + cy;
-		const cp2x = ep2x - alpha * (-cosPhi * rx * sin2 - sinPhi * ry * cos2);
-		const cp2y = ep2y - alpha * (-sinPhi * rx * sin2 + cosPhi * ry * cos2);
-		ops += `${fmtN(cp1x)} ${fmtN(cp1y)} ${fmtN(cp2x)} ${fmtN(cp2y)} ${fmtN(ep2x)} ${fmtN(ep2y)} c\n`;
-		angle = a2;
-	}
-	return ops;
-}
-/**
-* Convert parsed SVG draw commands into PDF path construction operators.
-*
-* Does **not** emit painting operators (fill / stroke) -- the caller
-* is responsible for that.
-*/
-function svgCommandsToPdfOps(commands) {
-	let ops = "";
-	let curX = 0;
-	let curY = 0;
-	for (const cmd of commands) switch (cmd.type) {
-		case "moveTo":
-			curX = cmd.params[0];
-			curY = cmd.params[1];
-			ops += `${fmtN(curX)} ${fmtN(curY)} m\n`;
-			break;
-		case "lineTo":
-			curX = cmd.params[0];
-			curY = cmd.params[1];
-			ops += `${fmtN(curX)} ${fmtN(curY)} l\n`;
-			break;
-		case "curveTo":
-			ops += `${fmtN(cmd.params[0])} ${fmtN(cmd.params[1])} ${fmtN(cmd.params[2])} ${fmtN(cmd.params[3])} ${fmtN(cmd.params[4])} ${fmtN(cmd.params[5])} c\n`;
-			curX = cmd.params[4];
-			curY = cmd.params[5];
-			break;
-		case "quadCurveTo": {
-			const cpx = cmd.params[0];
-			const cpy = cmd.params[1];
-			const toX = cmd.params[2];
-			const toY = cmd.params[3];
-			const cp1x = curX + 2 / 3 * (cpx - curX);
-			const cp1y = curY + 2 / 3 * (cpy - curY);
-			const cp2x = toX + 2 / 3 * (cpx - toX);
-			const cp2y = toY + 2 / 3 * (cpy - toY);
-			ops += `${fmtN(cp1x)} ${fmtN(cp1y)} ${fmtN(cp2x)} ${fmtN(cp2y)} ${fmtN(toX)} ${fmtN(toY)} c\n`;
-			curX = toX;
-			curY = toY;
-			break;
-		}
-		case "closePath":
-			ops += "h\n";
-			break;
-		case "rect":
-			ops += `${fmtN(cmd.params[0])} ${fmtN(cmd.params[1])} ${fmtN(cmd.params[2])} ${fmtN(cmd.params[3])} re\n`;
-			break;
-		case "circle": {
-			const ccx = cmd.params[0], ccy = cmd.params[1], r = cmd.params[2];
-			const ox = r * KAPPA, oy = r * KAPPA;
-			ops += `${fmtN(ccx)} ${fmtN(ccy + r)} m\n`;
-			ops += `${fmtN(ccx + ox)} ${fmtN(ccy + r)} ${fmtN(ccx + r)} ${fmtN(ccy + oy)} ${fmtN(ccx + r)} ${fmtN(ccy)} c\n`;
-			ops += `${fmtN(ccx + r)} ${fmtN(ccy - oy)} ${fmtN(ccx + ox)} ${fmtN(ccy - r)} ${fmtN(ccx)} ${fmtN(ccy - r)} c\n`;
-			ops += `${fmtN(ccx - ox)} ${fmtN(ccy - r)} ${fmtN(ccx - r)} ${fmtN(ccy - oy)} ${fmtN(ccx - r)} ${fmtN(ccy)} c\n`;
-			ops += `${fmtN(ccx - r)} ${fmtN(ccy + oy)} ${fmtN(ccx - ox)} ${fmtN(ccy + r)} ${fmtN(ccx)} ${fmtN(ccy + r)} c\n`;
-			break;
-		}
-		case "ellipse": {
-			const ecx = cmd.params[0], ecy = cmd.params[1];
-			const erx = cmd.params[2], ery = cmd.params[3];
-			const eox = erx * KAPPA, eoy = ery * KAPPA;
-			ops += `${fmtN(ecx)} ${fmtN(ecy + ery)} m\n`;
-			ops += `${fmtN(ecx + eox)} ${fmtN(ecy + ery)} ${fmtN(ecx + erx)} ${fmtN(ecy + eoy)} ${fmtN(ecx + erx)} ${fmtN(ecy)} c\n`;
-			ops += `${fmtN(ecx + erx)} ${fmtN(ecy - eoy)} ${fmtN(ecx + eox)} ${fmtN(ecy - ery)} ${fmtN(ecx)} ${fmtN(ecy - ery)} c\n`;
-			ops += `${fmtN(ecx - eox)} ${fmtN(ecy - ery)} ${fmtN(ecx - erx)} ${fmtN(ecy - eoy)} ${fmtN(ecx - erx)} ${fmtN(ecy)} c\n`;
-			ops += `${fmtN(ecx - erx)} ${fmtN(ecy + eoy)} ${fmtN(ecx - eox)} ${fmtN(ecy + ery)} ${fmtN(ecx)} ${fmtN(ecy + ery)} c\n`;
-			break;
-		}
-		case "arc":
-			ops += svgArcToPdfOps(curX, curY, cmd.params[0], cmd.params[1], cmd.params[2], cmd.params[3], cmd.params[4], cmd.params[5], cmd.params[6]);
-			curX = cmd.params[5];
-			curY = cmd.params[6];
-			break;
-	}
-	return ops;
-}
 
 //#endregion
 Object.defineProperty(exports, 'AnnotationFlags', {
@@ -4648,6 +5076,18 @@ Object.defineProperty(exports, 'buildAnnotationDict', {
     return buildAnnotationDict;
   }
 });
+Object.defineProperty(exports, 'buildGradientObjects', {
+  enumerable: true,
+  get: function () {
+    return buildGradientObjects;
+  }
+});
+Object.defineProperty(exports, 'buildPatternObjects', {
+  enumerable: true,
+  get: function () {
+    return buildPatternObjects;
+  }
+});
 Object.defineProperty(exports, 'circlePath', {
   enumerable: true,
   get: function () {
@@ -4858,6 +5298,12 @@ Object.defineProperty(exports, 'lineTo', {
     return lineTo;
   }
 });
+Object.defineProperty(exports, 'linearGradient', {
+  enumerable: true,
+  get: function () {
+    return linearGradient;
+  }
+});
 Object.defineProperty(exports, 'markForRedaction', {
   enumerable: true,
   get: function () {
@@ -4918,6 +5364,12 @@ Object.defineProperty(exports, 'pdfPage_exports', {
     return pdfPage_exports;
   }
 });
+Object.defineProperty(exports, 'radialGradient', {
+  enumerable: true,
+  get: function () {
+    return radialGradient;
+  }
+});
 Object.defineProperty(exports, 'radians', {
   enumerable: true,
   get: function () {
@@ -5182,6 +5634,12 @@ Object.defineProperty(exports, 'svgToPdfOperators', {
     return svgToPdfOperators;
   }
 });
+Object.defineProperty(exports, 'tilingPattern', {
+  enumerable: true,
+  get: function () {
+    return tilingPattern;
+  }
+});
 Object.defineProperty(exports, 'translate', {
   enumerable: true,
   get: function () {
@@ -5200,4 +5658,4 @@ Object.defineProperty(exports, 'wrapText', {
     return wrapText;
   }
 });
-//# sourceMappingURL=pdfPage-BMGFx7Xd.cjs.map
+//# sourceMappingURL=pdfPage-BebMv6fN.cjs.map