reamkit 1.15.4 → 1.17.0

package/dist/esm/core/drawingml/preset-geometry.js

@@ -86,8 +86,33 @@ function presetPaths(preset, w, h, adjust) {
 				[0, h / 2]
 			])];
 		}
+		case "round1Rect":
+		case "round2SameRect":
+		case "round2DiagRect":
+		case "snip1Rect":
+		case "snip2SameRect":
+		case "snip2DiagRect":
+		case "snipRoundRect": return [cornerRect(preset, w, h, adjust)];
+		case "star4":
+		case "star5":
+		case "star6":
+		case "star7":
+		case "star8":
+		case "star10":
+		case "star12":
+		case "star16":
+		case "star24":
+		case "star32": {
+			const s = STARS.get(preset);
+			return s ? [star(w, h, s, adjust)] : null;
+		}
 		case "line":
 		case "straightConnector1": return [new PathBuilder().moveTo(0, h).lineTo(w, 0).build()];
+		case "bentConnector2": return [new PathBuilder().moveTo(0, h).lineTo(w, h).lineTo(w, 0).build()];
+		case "bentConnector3": {
+			const bx = clamp(frac(adjust, "adj1", 5e4), 0, 1) * w;
+			return [new PathBuilder().moveTo(0, h).lineTo(bx, h).lineTo(bx, 0).lineTo(w, 0).build()];
+		}
 		case "rightArrow": return [blockArrow(w, h, adjust, "right")];
 		case "leftArrow": return [blockArrow(w, h, adjust, "left")];
 		case "upArrow": return [blockArrow(w, h, adjust, "up")];
@@ -157,6 +182,214 @@ function customPaths(geom, wPt, hPt) {
 	}
 	return [b.build()];
 }
+var SQUARE = {
+	cut: 0,
+	round: false
+};
+var CORNER_RECTS = new Map([
+	["round1Rect", {
+		defaults: [16667, 0],
+		corners: [
+			void 0,
+			0,
+			void 0,
+			void 0
+		],
+		round: true
+	}],
+	["snip1Rect", {
+		defaults: [16667, 0],
+		corners: [
+			void 0,
+			0,
+			void 0,
+			void 0
+		],
+		round: false
+	}],
+	["round2SameRect", {
+		defaults: [16667, 0],
+		corners: [
+			0,
+			0,
+			1,
+			1
+		],
+		round: true
+	}],
+	["snip2SameRect", {
+		defaults: [16667, 0],
+		corners: [
+			0,
+			0,
+			1,
+			1
+		],
+		round: false
+	}],
+	["round2DiagRect", {
+		defaults: [16667, 0],
+		corners: [
+			0,
+			1,
+			0,
+			1
+		],
+		round: true
+	}],
+	["snip2DiagRect", {
+		defaults: [16667, 0],
+		corners: [
+			0,
+			1,
+			0,
+			1
+		],
+		round: false
+	}],
+	["snipRoundRect", {
+		defaults: [16667, 16667],
+		corners: [
+			0,
+			1,
+			void 0,
+			void 0
+		],
+		round: [false, true]
+	}]
+]);
+function cornerRect(preset, w, h, adjust) {
+	const spec = CORNER_RECTS.get(preset);
+	const ss = Math.min(w, h);
+	const guide = (i) => {
+		return clamp((adjust.get(i === 0 ? "adj1" : "adj2") ?? (i === 0 ? adjust.get("adj") : void 0) ?? spec.defaults[i]) / 1e5, 0, .5) * ss;
+	};
+	return roundedCorners(w, h, spec.corners.map((g) => {
+		if (g === void 0) return SQUARE;
+		const round = typeof spec.round === "boolean" ? spec.round : spec.round[g];
+		return {
+			cut: guide(g),
+			round
+		};
+	}));
+}
+function roundedCorners(w, h, [tl, tr, br, bl]) {
+	const at = [
+		{
+			c: tl,
+			from: [0, h - tl.cut],
+			to: [tl.cut, h],
+			centre: [tl.cut, h - tl.cut],
+			start: Math.PI
+		},
+		{
+			c: tr,
+			from: [w - tr.cut, h],
+			to: [w, h - tr.cut],
+			centre: [w - tr.cut, h - tr.cut],
+			start: Math.PI / 2
+		},
+		{
+			c: br,
+			from: [w, br.cut],
+			to: [w - br.cut, 0],
+			centre: [w - br.cut, br.cut],
+			start: 0
+		},
+		{
+			c: bl,
+			from: [bl.cut, 0],
+			to: [0, bl.cut],
+			centre: [bl.cut, bl.cut],
+			start: -Math.PI / 2
+		}
+	];
+	const b = new PathBuilder();
+	at.forEach((corner, i) => {
+		if (i === 0) b.moveTo(corner.from[0], corner.from[1]);
+		else b.lineTo(corner.from[0], corner.from[1]);
+		if (corner.c.cut <= 0) return;
+		if (corner.c.round) b.append(arcToBeziers(corner.centre[0], corner.centre[1], corner.c.cut, corner.c.cut, corner.start, -Math.PI / 2));
+		else b.lineTo(corner.to[0], corner.to[1]);
+	});
+	return b.close().build();
+}
+var STARS = new Map([
+	["star4", {
+		points: 4,
+		adj: 12500,
+		hf: 1e5,
+		vf: 1e5
+	}],
+	["star5", {
+		points: 5,
+		adj: 19098,
+		hf: 105146,
+		vf: 110557
+	}],
+	["star6", {
+		points: 6,
+		adj: 28868,
+		hf: 115470,
+		vf: 1e5
+	}],
+	["star7", {
+		points: 7,
+		adj: 34601,
+		hf: 102572,
+		vf: 105210
+	}],
+	["star8", {
+		points: 8,
+		adj: 37500,
+		hf: 1e5,
+		vf: 1e5
+	}],
+	["star10", {
+		points: 10,
+		adj: 42533,
+		hf: 105146,
+		vf: 1e5
+	}],
+	["star12", {
+		points: 12,
+		adj: 37500,
+		hf: 1e5,
+		vf: 1e5
+	}],
+	["star16", {
+		points: 16,
+		adj: 37500,
+		hf: 1e5,
+		vf: 1e5
+	}],
+	["star24", {
+		points: 24,
+		adj: 37500,
+		hf: 1e5,
+		vf: 1e5
+	}],
+	["star32", {
+		points: 32,
+		adj: 37500,
+		hf: 1e5,
+		vf: 1e5
+	}]
+]);
+function star(w, h, preset, adjust) {
+	const inner = clamp(frac(adjust, "adj", preset.adj) * 2, 0, 1);
+	const hf = preset.hf / 1e5;
+	const vf = preset.vf / 1e5;
+	const pts = [];
+	for (let i = 0; i < preset.points; i++) {
+		const out = -Math.PI / 2 + i * 2 * Math.PI / preset.points;
+		for (const [angle, r] of [[out, 1], [out + Math.PI / preset.points, inner]]) {
+			const x = w / 2 * (1 + hf * r * Math.cos(angle));
+			pts.push([x, h - h / 2 * vf * (1 + r * Math.sin(angle))]);
+		}
+	}
+	return polygon(pts);
+}
 function regularPolygon(w, h, n) {
 	const cx = w / 2;
 	const cy = h / 2;
@@ -172,10 +405,11 @@ function regularPolygon(w, h, n) {
 function blockArrow(w, h, adjust, dir) {
 	const thick = clamp(frac(adjust, "adj1", 5e4), 0, 1);
 	const head = clamp(frac(adjust, "adj2", 5e4), 0, 1);
+	const ss = Math.min(w, h);
 	if (dir === "right" || dir === "left") {
-		const sb = h * (1 - thick) / 2;
-		const st = h * (1 + thick) / 2;
-		const hl = head * w;
+		const sb = (h - ss * thick) / 2;
+		const st = (h + ss * thick) / 2;
+		const hl = head * ss;
 		if (dir === "right") {
 			const bx = w - hl;
 			return polygon([
@@ -199,9 +433,9 @@ function blockArrow(w, h, adjust, dir) {
 			[w, st]
 		]);
 	}
-	const sl = w * (1 - thick) / 2;
-	const sr = w * (1 + thick) / 2;
-	const hh = head * h;
+	const sl = (w - ss * thick) / 2;
+	const sr = (w + ss * thick) / 2;
+	const hh = head * ss;
 	if (dir === "up") {
 		const by = h - hh;
 		return polygon([

package/dist/esm/core/drawingml/shape-render.d.ts

@@ -37,6 +37,18 @@ export declare function gradientToSolid(gradient: ShapeGradient): string;
  * @returns The `<linearGradient>` or `<radialGradient>` markup.
  */
 export declare function gradientSvgDef(id: string, g: ShapeGradient): string;
+/**
+ * §20.1.8.24 / §20.1.8.42 — the arrowheads a line asks for at its ends, as
+ * filled paths in the same local frame as the shape's own geometry. The head
+ * rides the first point of the first subpath and the tail the last point of
+ * the last one, each turned along the segment that reaches it.
+ *
+ * @param paths        The shape's geometry paths.
+ * @param line         The parsed line (its `headEnd`/`tailEnd` are read).
+ * @param strokeWidthPt The pen width the decorations are sized against.
+ * @returns The decoration paths (empty when the line asks for none).
+ */
+export declare function lineEndPaths(paths: ReadonlyArray<VectorPath>, line: ShapeLine | undefined, strokeWidthPt: number): Array<VectorPath>;
 /**
  * Build a {@link StrokeStyle} from a shape's `a:ln` line, resolving the default
  * width (0.75pt), dash pattern and line cap. Returns `undefined` for no line or

package/dist/esm/core/drawingml/shape-render.js

@@ -60,12 +60,125 @@ function gradientToSolid(gradient) {
 function gradientSvgDef(id, g) {
 	const n = (x) => String(Math.round(x * 1e4) / 1e4);
 	const stops = g.stops.map((s) => `<stop offset="${n(s.offset)}" stop-color="#${s.colorHex}"/>`).join("");
-	if (g.kind === "radial") return `<radialGradient id="${id}">${stops}</radialGradient>`;
+	if (g.kind === "radial") {
+		const c = g.center;
+		if (!c) return `<radialGradient id="${id}">${stops}</radialGradient>`;
+		const r = Math.SQRT2 / 2;
+		return `<radialGradient id="${id}" cx="${n(c.x)}" cy="${n(c.y)}" r="${n(r)}">${stops}</radialGradient>`;
+	}
 	const rad = -(g.angle ?? 0) * Math.PI / 180;
 	const dx = Math.cos(rad) / 2;
 	const dy = Math.sin(rad) / 2;
 	return `<linearGradient id="${id}" x1="${n(.5 - dx)}" y1="${n(.5 - dy)}" x2="${n(.5 + dx)}" y2="${n(.5 + dy)}">${stops}</linearGradient>`;
 }
+var LINE_END_STEPS = {
+	sm: 3,
+	med: 4.5,
+	lg: 6
+};
+var MIN_LINE_END_PEN_PT = 1;
+/**
+* §20.1.8.24 / §20.1.8.42 — the arrowheads a line asks for at its ends, as
+* filled paths in the same local frame as the shape's own geometry. The head
+* rides the first point of the first subpath and the tail the last point of
+* the last one, each turned along the segment that reaches it.
+*
+* @param paths        The shape's geometry paths.
+* @param line         The parsed line (its `headEnd`/`tailEnd` are read).
+* @param strokeWidthPt The pen width the decorations are sized against.
+* @returns The decoration paths (empty when the line asks for none).
+*/
+function lineEndPaths(paths, line, strokeWidthPt) {
+	if (!line || !line.headEnd && !line.tailEnd || line.fill === "none") return [];
+	const pts = pathPoints(paths);
+	if (pts.length < 2) return [];
+	const out = [];
+	const pen = Math.max(strokeWidthPt, MIN_LINE_END_PEN_PT);
+	if (line.headEnd) {
+		const p = pts[0];
+		const q = pts[1];
+		const path = endPath(line.headEnd, p, q, pen);
+		if (path) out.push(path);
+	}
+	if (line.tailEnd) {
+		const p = pts[pts.length - 1];
+		const q = pts[pts.length - 2];
+		const path = endPath(line.tailEnd, p, q, pen);
+		if (path) out.push(path);
+	}
+	return out;
+}
+function pathPoints(paths) {
+	const out = [];
+	for (const path of paths) for (const seg of path.segments) {
+		if (seg.op === "close") continue;
+		out.push({
+			x: seg.x,
+			y: seg.y
+		});
+	}
+	return out;
+}
+function endPath(end, tip, from, pen) {
+	const dx = tip.x - from.x;
+	const dy = tip.y - from.y;
+	const len = Math.hypot(dx, dy);
+	if (len < 1e-6) return void 0;
+	const ux = dx / len;
+	const uy = dy / len;
+	const nx = -uy;
+	const ny = ux;
+	const L = LINE_END_STEPS[end.length ?? "med"] * pen;
+	const W = LINE_END_STEPS[end.width ?? "med"] * pen;
+	const at = (along, across) => ({
+		x: tip.x - ux * along + nx * across,
+		y: tip.y - uy * along + ny * across
+	});
+	const segments = [];
+	const move = (p) => {
+		segments.push({
+			op: "move",
+			x: p.x,
+			y: p.y
+		});
+	};
+	const line2 = (p) => {
+		segments.push({
+			op: "line",
+			x: p.x,
+			y: p.y
+		});
+	};
+	if (end.type === "diamond") {
+		move(at(0, 0));
+		line2(at(L / 2, W / 2));
+		line2(at(L, 0));
+		line2(at(L / 2, -W / 2));
+	} else if (end.type === "oval") {
+		const r = W / 2;
+		const c = at(L / 2, 0);
+		for (let i = 0; i < 8; i++) {
+			const a = i / 8 * 2 * Math.PI;
+			const p = {
+				x: c.x + r * Math.cos(a),
+				y: c.y + r * Math.sin(a)
+			};
+			if (i === 0) move(p);
+			else line2(p);
+		}
+	} else if (end.type === "stealth") {
+		move(at(0, 0));
+		line2(at(L, W / 2));
+		line2(at(L * .6, 0));
+		line2(at(L, -W / 2));
+	} else {
+		move(at(0, 0));
+		line2(at(L, W / 2));
+		line2(at(L, -W / 2));
+	}
+	segments.push({ op: "close" });
+	return { segments };
+}
 /**
 * Build a {@link StrokeStyle} from a shape's `a:ln` line, resolving the default
 * width (0.75pt), dash pattern and line cap. Returns `undefined` for no line or
@@ -77,7 +190,7 @@ function gradientSvgDef(id, g) {
 function buildStroke(line) {
 	if (!line || line.fill === "none") return void 0;
 	const widthPt = line.width ?? DEFAULT_LINE_WIDTH_EMU / 12700;
-	const dash = line.dash && line.dash !== "solid" ? dashPattern(line.dash, widthPt) : void 0;
+	const dash = line.customDash?.map((n) => Math.max(.01, n * widthPt)) ?? (line.dash && line.dash !== "solid" ? dashPattern(line.dash, widthPt) : void 0);
 	const cap = line.cap === "flat" ? "butt" : line.cap;
 	return {
 		colorHex: line.colorHex ?? "000000",
@@ -148,4 +261,4 @@ function buildShapeTransform(pageX, pageY, widthPt, heightPt, rotation60k, flipH
 	];
 }
 //#endregion
-export { DEFAULT_INSET_LR_PT, DEFAULT_INSET_TB_PT, buildShapePaths, buildShapeTransform, buildStroke, gradientSvgDef, gradientToSolid };
+export { DEFAULT_INSET_LR_PT, DEFAULT_INSET_TB_PT, buildShapePaths, buildShapeTransform, buildStroke, gradientSvgDef, gradientToSolid, lineEndPaths };

package/dist/esm/core/drawingml/sparkline-geometry.js

@@ -59,14 +59,16 @@ function columnSpark(values, w, h, color) {
 	const slot = w / n;
 	const bw = slot * .72;
 	const off = (slot - bw) / 2;
-	const pad = h * .06;
 	const paths = [];
+	const at = (v) => (v - min) / span * h;
+	const zero = Math.min(h, Math.max(0, at(0)));
 	for (let i = 0; i < n; i++) {
 		const v = values[i];
 		if (v === null || v === void 0) continue;
-		const frac = (v - min) / span;
-		const bh = Math.max(.4, pad + frac * (h - pad));
-		paths.push(rectPath(i * slot + off, 0, bw, bh));
+		const y = at(v);
+		const bottom = Math.min(zero, y);
+		const bh = Math.max(.4, Math.abs(y - zero));
+		paths.push(rectPath(i * slot + off, bottom, bw, bh));
 	}
 	return paths.length > 0 ? [{
 		paths,

package/dist/esm/core/drawingml/theme-parser.d.ts

@@ -1,3 +1,4 @@
+import { PoNode } from '../po-helpers.js';
 /**
  * Parse a DrawingML theme part (ECMA-376 §20.1.6.2, `a:clrScheme`) into a
  * `name → hex` colour map. Reads the twelve scheme slots — `dk1`/`lt1`/`dk2`/
@@ -10,3 +11,53 @@
  *          empty when no `a:clrScheme` is present.
  */
 export declare function parseTheme(themeXml: Uint8Array): Map<string, string>;
+/**
+ * Parse a theme's line-style widths (ECMA-376 §20.1.4.1.21 `a:lnStyleLst`).
+ *
+ * A shape drawn from the gallery keeps its outline as `<a:lnRef idx="N">`,
+ * which is a 1-based index into this list — the reference names the colour and
+ * the list holds the width. The standard Office theme is 0.75pt / 2pt / 3pt.
+ *
+ * @param themeXml The raw theme part bytes, UTF-8.
+ * @returns The widths in points, in list order; empty when the theme declares
+ *          no `a:fmtScheme`.
+ */
+export declare function parseThemeLineWidths(themeXml: Uint8Array): Array<number>;
+/**
+ * Parse a theme's fill styles (§20.1.4.1.13 `a:fillStyleLst`), as the raw nodes.
+ *
+ * A shape drawn from the gallery carries no fill of its own — only
+ * `<a:fillRef idx="N">`, a 1-based index into this list, and a colour to put
+ * where the styles say `phClr`. The standard Office theme's slots are a solid,
+ * a subtle gradient and a stronger one, so reading the reference's colour alone
+ * paints slot 3 flat: 47504.xlsx's rectangle is a gradient in both references
+ * and a single blue in ours.
+ *
+ * The nodes are handed back unparsed because what they hold is a whole fill —
+ * solid, gradient, pattern — which the shape readers already know how to read.
+ *
+ * @param themeXml The raw theme part bytes, UTF-8.
+ * @returns The `a:fillStyleLst` children in list order; empty when the theme
+ *          declares no `a:fmtScheme`.
+ */
+export declare function parseThemeFillStyles(themeXml: Uint8Array): Array<PoNode>;
+/**
+ * Parse a theme's BACKGROUND fill styles (§20.1.4.1.7 `a:bgFillStyleLst`), as
+ * the raw nodes. An `<a:fillRef>` reaches them with an index past 1000 — slot
+ * 1001 is the first — and that is where the page-sized backdrops Word's cover
+ * pages are built from live (fdo78957.docx).
+ *
+ * @param themeXml The raw theme part bytes, UTF-8.
+ * @returns The fill children in list order; empty when the theme declares none.
+ */
+export declare function parseThemeBgFillStyles(themeXml: Uint8Array): Array<PoNode>;
+/**
+ * Parse a theme's effect styles (§20.1.4.1.15 `a:effectStyleLst`), as the raw
+ * nodes. `<a:effectRef idx="N">` is a 1-based index into this list, exactly as
+ * the fill and line references index theirs.
+ *
+ * @param themeXml The raw theme part bytes, UTF-8.
+ * @returns The `a:effectStyle` children in list order; empty when the theme
+ *          declares no `a:fmtScheme`.
+ */
+export declare function parseThemeEffectStyles(themeXml: Uint8Array): Array<PoNode>;

package/dist/esm/core/drawingml/theme-parser.js

@@ -3,6 +3,7 @@ import { XMLParser } from "fast-xml-parser";
 //#region src/core/drawingml/theme-parser.ts
 var decoder = new TextDecoder("utf-8");
 var parser = new XMLParser({
+	htmlEntities: true,
 	ignoreAttributes: false,
 	attributeNamePrefix: "@_",
 	preserveOrder: true,
@@ -53,6 +54,96 @@ function parseTheme(themeXml) {
 	}
 	return out;
 }
+/**
+* Parse a theme's line-style widths (ECMA-376 §20.1.4.1.21 `a:lnStyleLst`).
+*
+* A shape drawn from the gallery keeps its outline as `<a:lnRef idx="N">`,
+* which is a 1-based index into this list — the reference names the colour and
+* the list holds the width. The standard Office theme is 0.75pt / 2pt / 3pt.
+*
+* @param themeXml The raw theme part bytes, UTF-8.
+* @returns The widths in points, in list order; empty when the theme declares
+*          no `a:fmtScheme`.
+*/
+function parseThemeLineWidths(themeXml) {
+	const list = poFindByPath(parser.parse(decoder.decode(themeXml)), [
+		"a:theme",
+		"a:themeElements",
+		"a:fmtScheme",
+		"a:lnStyleLst"
+	]);
+	if (!list) return [];
+	const out = [];
+	for (const ln of poChildren(list)) {
+		if (!poIs(ln, "a:ln")) continue;
+		const w = Number(poAttr(ln, "w") ?? "");
+		out.push(Number.isFinite(w) && w > 0 ? w / EMU_PER_POINT : .75);
+	}
+	return out;
+}
+/**
+* Parse a theme's fill styles (§20.1.4.1.13 `a:fillStyleLst`), as the raw nodes.
+*
+* A shape drawn from the gallery carries no fill of its own — only
+* `<a:fillRef idx="N">`, a 1-based index into this list, and a colour to put
+* where the styles say `phClr`. The standard Office theme's slots are a solid,
+* a subtle gradient and a stronger one, so reading the reference's colour alone
+* paints slot 3 flat: 47504.xlsx's rectangle is a gradient in both references
+* and a single blue in ours.
+*
+* The nodes are handed back unparsed because what they hold is a whole fill —
+* solid, gradient, pattern — which the shape readers already know how to read.
+*
+* @param themeXml The raw theme part bytes, UTF-8.
+* @returns The `a:fillStyleLst` children in list order; empty when the theme
+*          declares no `a:fmtScheme`.
+*/
+function parseThemeFillStyles(themeXml) {
+	const list = poFindByPath(parser.parse(decoder.decode(themeXml)), [
+		"a:theme",
+		"a:themeElements",
+		"a:fmtScheme",
+		"a:fillStyleLst"
+	]);
+	return list ? [...poChildren(list)] : [];
+}
+/**
+* Parse a theme's BACKGROUND fill styles (§20.1.4.1.7 `a:bgFillStyleLst`), as
+* the raw nodes. An `<a:fillRef>` reaches them with an index past 1000 — slot
+* 1001 is the first — and that is where the page-sized backdrops Word's cover
+* pages are built from live (fdo78957.docx).
+*
+* @param themeXml The raw theme part bytes, UTF-8.
+* @returns The fill children in list order; empty when the theme declares none.
+*/
+function parseThemeBgFillStyles(themeXml) {
+	const list = poFindByPath(parser.parse(decoder.decode(themeXml)), [
+		"a:theme",
+		"a:themeElements",
+		"a:fmtScheme",
+		"a:bgFillStyleLst"
+	]);
+	return list ? [...poChildren(list)] : [];
+}
+/**
+* Parse a theme's effect styles (§20.1.4.1.15 `a:effectStyleLst`), as the raw
+* nodes. `<a:effectRef idx="N">` is a 1-based index into this list, exactly as
+* the fill and line references index theirs.
+*
+* @param themeXml The raw theme part bytes, UTF-8.
+* @returns The `a:effectStyle` children in list order; empty when the theme
+*          declares no `a:fmtScheme`.
+*/
+function parseThemeEffectStyles(themeXml) {
+	const list = poFindByPath(parser.parse(decoder.decode(themeXml)), [
+		"a:theme",
+		"a:themeElements",
+		"a:fmtScheme",
+		"a:effectStyleLst"
+	]);
+	return list ? [...poChildren(list)] : [];
+}
+var EMU_PER_POINT = 12700;
 function colorOf(slot) {
 	for (const c of poChildren(slot)) if (poIs(c, "a:srgbClr")) {
 		const v = poAttr(c, "val");
@@ -63,4 +154,4 @@ function colorOf(slot) {
 	}
 }
 //#endregion
-export { parseTheme };
+export { parseTheme, parseThemeBgFillStyles, parseThemeEffectStyles, parseThemeFillStyles, parseThemeLineWidths };

package/dist/esm/core/font/measure.d.ts

@@ -12,6 +12,11 @@ export interface FontMeasure {
     readonly textWidthPt: (text: string, fontSize: number) => number;
     /** Encode `text` as a hex string of 4-digit glyph ids (Identity-H addressing). */
     readonly encodeTextAsCidHex: (text: string) => string;
+    /**
+     * The complete PDF text-showing operator for `text` — `<hex> Tj`, or a
+     * `[…] TJ` array when shaping moved a glyph off its own advance.
+     */
+    readonly showText: (text: string) => string;
 }
 /**
  * Build a {@link FontMeasure} over a parsed font.

package/dist/esm/core/font/measure.js

@@ -33,10 +33,30 @@ function createFontMeasure(parsed, kern = true) {
 		for (const gid of shaped.gids) out += gid.toString(16).padStart(4, "0").toUpperCase();
 		return out;
 	};
+	const showText = (text) => {
+		const shaped = shapeText(text, parsed.glyphForCodepoint, parsed.advanceWidths, parsed.ligatures, kerning, parsed.joiningForms);
+		const parts = [];
+		let hex = "";
+		let kerned = false;
+		for (let i = 0; i < shaped.gids.length; i++) {
+			const gid = shaped.gids[i];
+			hex += gid.toString(16).padStart(4, "0").toUpperCase();
+			const delta = (shaped.advances[i] ?? 0) - (parsed.advanceWidths[gid] ?? 0);
+			if (delta === 0) continue;
+			const adj = -delta * 1e3 / parsed.unitsPerEm;
+			parts.push(`<${hex}>`, String(Number(adj.toFixed(2))));
+			hex = "";
+			kerned = true;
+		}
+		if (!kerned) return `<${hex}> Tj`;
+		if (hex !== "") parts.push(`<${hex}>`);
+		return `[${parts.join(" ")}] TJ`;
+	};
 	return {
 		pdfWidthForGid,
 		textWidthPt,
-		encodeTextAsCidHex
+		encodeTextAsCidHex,
+		showText
 	};
 }
 //#endregion