modern-pdf-lib 0.12.1 → 0.13.0

package/dist/{pdfPage-JiCJLV3x.mjs → pdfPage-B7vA518n.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-95iHPtFO.mjs";
-import { a as formatPdfDate, f as PdfNumber, g as PdfString, h as PdfStream, l as PdfDict, s as PdfArray, u as PdfName } from "./pdfCatalog-CTfeeqtF.mjs";
+import { a as formatPdfDate, c as PdfBool, f as PdfNumber, g as PdfString, h as PdfStream, l as PdfDict, s as PdfArray, u as PdfName } from "./pdfCatalog-CTfeeqtF.mjs";
 
 //#region src/core/operators/text.ts
 /**
@@ -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__ */ __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 PdfDict();
+	fn.set("/FunctionType", PdfNumber.of(2));
+	fn.set("/Domain", PdfArray.fromNumbers([0, 1]));
+	fn.set("/C0", PdfArray.fromNumbers([
+		c0.r,
+		c0.g,
+		c0.b
+	]));
+	fn.set("/C1", PdfArray.fromNumbers([
+		c1.r,
+		c1.g,
+		c1.b
+	]));
+	fn.set("/N", 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 PdfDict();
+	stitchDict.set("/FunctionType", PdfNumber.of(3));
+	stitchDict.set("/Domain", 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", PdfArray.of(subFunctions));
+	stitchDict.set("/Bounds", PdfArray.fromNumbers(bounds));
+	stitchDict.set("/Encode", 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 PdfDict();
+	shadingDict.set("/ShadingType", PdfNumber.of(gradient.shadingType));
+	shadingDict.set("/ColorSpace", PdfName.of("DeviceRGB"));
+	shadingDict.set("/Coords", PdfArray.fromNumbers([...gradient.coords]));
+	shadingDict.set("/Function", fnRef);
+	shadingDict.set("/Extend", PdfArray.of([PdfBool.of(gradient.extend), PdfBool.of(gradient.extend)]));
+	const shadingRef = registry.register(shadingDict);
+	const patternDict = new PdfDict();
+	patternDict.set("/Type", PdfName.of("Pattern"));
+	patternDict.set("/PatternType", 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 PdfDict();
+	dict.set("/Type", PdfName.of("Pattern"));
+	dict.set("/PatternType", PdfNumber.of(1));
+	dict.set("/PaintType", PdfNumber.of(pattern.paintType));
+	dict.set("/TilingType", PdfNumber.of(pattern.tilingType));
+	dict.set("/BBox", PdfArray.fromNumbers([
+		0,
+		0,
+		pattern.width,
+		pattern.height
+	]));
+	dict.set("/XStep", PdfNumber.of(pattern.width));
+	dict.set("/YStep", PdfNumber.of(pattern.height));
+	dict.set("/Resources", new PdfDict());
+	const stream = 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__ */ __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 PdfDict();
+		groupDict.set("/S", PdfName.of("Transparency"));
+		groupDict.set("/I", PdfBool.of(group.options.isolated ?? true));
+		groupDict.set("/K", PdfBool.of(group.options.knockout ?? false));
+		groupDict.set("/CS", PdfName.of(colorSpace));
+		const bbox = PdfArray.fromNumbers([
+			this.mediaX,
+			this.mediaY,
+			this.mediaX + this.mediaWidth,
+			this.mediaY + this.mediaHeight
+		]);
+		const formDict = new PdfDict();
+		formDict.set("/Type", PdfName.of("XObject"));
+		formDict.set("/Subtype", PdfName.of("Form"));
+		formDict.set("/BBox", bbox);
+		formDict.set("/Group", groupDict);
+		const formStream = 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 PdfDict();
+		smaskDict.set("/S", PdfName.of("Luminosity"));
+		smaskDict.set("/G", mask.ref);
+		const gsDict = new PdfDict();
+		gsDict.set("/Type", 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 PdfDict();
+		gsDict.set("/Type", PdfName.of("ExtGState"));
+		gsDict.set("/SMask", 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 PdfDict();
+			for (const [name, ref] of this.patterns) patDict.set(name, ref);
+			resources.set("/Pattern", patDict);
+		}
 		resources.set("/ProcSet", PdfArray.of([
 			PdfName.of("PDF"),
 			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 PdfDict();
+				resources.set("/Pattern", patObj);
+			}
+			const patDict = patObj;
+			for (const [name, ref] of this.patterns) patDict.set(name, ref);
+		}
 		return resources;
 	}
 	/**
@@ -4385,160 +4966,7 @@ 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
-export { setFillColor as $, showTextArray as $t, endMarkedContent as A, moveTo as At, saveState as B, endText as Bt, beginArtifact as C, ellipsePath as Ct, beginMarkedContentWithProperties as D, fillEvenOdd as Dt, beginMarkedContentSequence as E, fillAndStroke as Et, radians as F, setLineJoin as Ft, applyFillColor as G, setFont as Gt, setGraphicsState as H, moveTextSetLeading as Ht, radiansToDegrees as I, setLineWidth as It, colorToComponents as J, setTextMatrix as Jt, applyStrokeColor as K, setFontSize as Kt, restoreState as L, setMiterLimit as Lt, concatMatrix as M, setDashPattern as Mt, degrees as N, setFlatness as Nt, createMarkedContentScope as O, fillEvenOddAndStroke as Ot, degreesToRadians as P, setLineCap as Pt, setColorSpace as Q, showText as Qt, rotate as R, stroke as Rt, createAnnotation as S, curveToInitial as St, beginMarkedContent as T, fill as Tt, skew as U, nextLine as Ut, scale as V, moveText as Vt, translate as W, setCharacterSpacing as Wt, grayscale as X, setTextRise as Xt, componentsToColor as Y, setTextRenderingMode as Yt, rgb as Z, setWordSpacing as Zt, parseSvgTransform as _, closeFillAndStroke as _t, applyRedactions as a, setStrokeColorCmyk as at, annotationFromDict as b, curveTo as bt, PdfLayer as c, setStrokeColorSpace as ct, endLayerContent as d, drawImageXObject as dt, showTextHex as en, setFillColorCmyk as et, drawSvgOnPage as f, drawXObject as ft, parseSvgPath as g, closeAndStroke as gt, parseSvgColor as h, clipEvenOdd as ht, wrapText as i, setStrokeColor as it, wrapInMarkedContent as j, rectangle as jt, endArtifact as k, lineTo as kt, PdfLayerManager as l, setStrokingColor as lt, parseSvg as m, clip as mt, PdfPage as n, showTextWithSpacing as nn, setFillColorRgb as nt, getRedactionMarks as o, setStrokeColorGray as ot, svgToPdfOperators as p, circlePath as pt, cmyk as q, setLeading as qt, pdfPage_exports as r, setFillingColor as rt, markForRedaction as s, setStrokeColorRgb as st, PageSizes as t, showTextNextLine as tn, setFillColorGray as tt, beginLayerContent as u, drawImageWithMatrix as ut, AnnotationFlags as v, closeFillEvenOddAndStroke as vt, beginArtifactWithType as w, endPath as wt, buildAnnotationDict as x, curveToFinal as xt, PdfAnnotation as y, closePath as yt, rotationMatrix as z, beginText as zt };
-//# sourceMappingURL=pdfPage-JiCJLV3x.mjs.map
+export { colorToComponents as $, setTextMatrix as $t, beginMarkedContent as A, fill as At, radians as B, setLineJoin as Bt, AnnotationFlags as C, closeFillEvenOddAndStroke as Ct, createAnnotation as D, curveToInitial as Dt, buildAnnotationDict as E, curveToFinal as Et, endMarkedContent as F, moveTo as Ft, saveState as G, endText as Gt, restoreState as H, setMiterLimit as Ht, wrapInMarkedContent as I, rectangle as It, skew as J, nextLine as Jt, scale as K, moveText as Kt, concatMatrix as L, setDashPattern as Lt, beginMarkedContentWithProperties as M, fillEvenOdd as Mt, createMarkedContentScope as N, fillEvenOddAndStroke as Nt, beginArtifact as O, ellipsePath as Ot, endArtifact as P, lineTo as Pt, cmyk as Q, setLeading as Qt, degrees as R, setFlatness as Rt, parseSvgTransform as S, closeFillAndStroke as St, annotationFromDict as T, curveTo as Tt, rotate as U, stroke as Ut, radiansToDegrees as V, setLineWidth as Vt, rotationMatrix as W, beginText as Wt, applyFillColor as X, setFont as Xt, translate as Y, setCharacterSpacing as Yt, applyStrokeColor as Z, setFontSize as Zt, drawSvgOnPage as _, drawXObject as _t, buildGradientObjects as a, showTextHex as an, setFillColorCmyk as at, parseSvgColor as b, clipEvenOdd as bt, radialGradient as c, setFillingColor as ct, getRedactionMarks as d, setStrokeColorGray as dt, setTextRenderingMode as en, componentsToColor as et, markForRedaction as f, setStrokeColorRgb as ft, endLayerContent as g, drawImageXObject as gt, beginLayerContent as h, drawImageWithMatrix as ht, wrapText as i, showTextArray as in, setFillColor as it, beginMarkedContentSequence as j, fillAndStroke as jt, beginArtifactWithType as k, endPath as kt, tilingPattern as l, setStrokeColor as lt, PdfLayerManager as m, setStrokingColor as mt, PdfPage as n, setWordSpacing as nn, rgb as nt, buildPatternObjects as o, showTextNextLine as on, setFillColorGray as ot, PdfLayer as p, setStrokeColorSpace as pt, setGraphicsState as q, moveTextSetLeading as qt, pdfPage_exports as r, showText as rn, setColorSpace as rt, linearGradient as s, showTextWithSpacing as sn, setFillColorRgb as st, PageSizes as t, setTextRise as tn, grayscale as tt, applyRedactions as u, setStrokeColorCmyk as ut, svgToPdfOperators as v, circlePath as vt, PdfAnnotation as w, closePath as wt, parseSvgPath as x, closeAndStroke as xt, parseSvg as y, clip as yt, degreesToRadians as z, setLineCap as zt };
+//# sourceMappingURL=pdfPage-B7vA518n.mjs.map