pptx-ts 3.7.0 → 4.0.0

package/dist/notes-Dh12JAbn.js

@@ -0,0 +1,3264 @@
+import { l as warn, n as InvalidOptionError, o as UnsupportedFeatureError, t as InternalError, u as warnOnce } from "./errors-C4oENPcu.js";
+import { B as DEF_TEXT_SHADOW, G as MAX_FONT_SIZE_PT, I as DEF_SHAPE_LINE_COLOR, N as DEF_FONT_COLOR, S as transparencyToAlpha, U as LEVEL_MARGINS_EMU, W as LEVEL_PPR_TAIL, a as convertRotationDegrees, c as inch2Emu, f as opacityToAlpha, g as ptsToEmuLenient, h as positiveCoordinateEmu, i as convertArcAngle, l as lineWidthToEmu, n as clampRangedInput, p as percentToFixedPercent, q as SLDNUMFLDID, r as convertAngleUnits, s as getSmartParseNumber, u as mapStated, z as DEF_TEXT_GLOW } from "./units-internal-XJlf-hOl.js";
+import { F as EMU_PER_INCH, I as EMU_PER_POINT, P as ptToHundredths, b as FIXED_PCT_PER_PERCENT, c as SchemeColor, p as VALID_SHAPE_PRESETS, w as PERCENT_SCALE } from "./table-cell-margins-EVg0EwxT.js";
+import { $t as THEME_REL, Ct as HYPERLINK_REL, E as EMBEDDED_FONT_SLOTS, F as LINE_END_TYPES, I as PRESET_LINE_DASHES, J as TEXT_TAB_ALIGN_TYPES, Rt as PACKAGE_REL_NS, St as FONT_REL, U as TEXT_AUTONUM_SCHEMES, W as TEXT_CAPS_TYPES, Y as TEXT_UNDERLINE_TYPES, Yt as SLIDE_REL, a as textAlignToken, an as PML_ROOT_NS, d as xsdBool, f as xsdBoolIfTrue, h as stripHash, in as OOXML_NS, jt as NOTES_MASTER_REL, l as checkEnumOrWarn, m as splitRgbaHex, p as isHexColor, q as TEXT_STRIKE_TYPES, s as lineCapToken, w as DEFAULT_COLOR_MAP } from "./image-size-CvN2iCA4.js";
+import { n as setOrClear } from "./options-internal-WqgMf720.js";
+//#region src/xml-escape.ts
+/**
+* ts-pptx: turning a caller's string into something that can sit inside XML.
+*
+* Three escapers with three notions of what is dangerous used to live here-and-there — one under
+* `gen/`, one under `read/oxml/`, and a fourth-of-a-job local one in `embedded-fonts.ts` — and the
+* weakest was the one reached by the least-checked input. `serializeEmbeddedFontLst` puts
+* `font.typeface` straight from `pptx.embedFont({ typeface })` through an escaper that handled
+* `& < > "` and nothing else, so `embedFont({ typeface: 'Foo\v' })` wrote a vertical tab into
+* `<p:font typeface="…">` — a character XML 1.0 forbids outright, and exactly what the write side
+* strips at every other emission site — and `'Foo\nBar'` lost its newline to attribute-value
+* normalisation.
+*
+* The copies had a real reason: `embedded-fonts.ts` is imported by `read/api/ops/`, so it must not
+* pull in `src/gen/`, and `read/oxml/dom.ts` is on the same side of that line. The answer to
+* "both halves need this" is a dependency-free root module, the same placement and rationale as
+* `hex-color.ts` — not a third, weaker copy.
+*
+* This module imports nothing.
+*/
+/**
+* Characters XML 1.0's `Char` production excludes that a string holds in one code unit, as a
+* character class: every C0 control except tab, line feed and carriage return, and the two
+* non-characters U+FFFE and U+FFFF. No document may carry one in any spelling, not even as a
+* character reference, and a part that does is one PowerPoint offers to repair.
+*
+* DEL (U+007F) is in the class too, although XML 1.0 allows it. Stripping it loses nothing a slide
+* could show, and it has always been stripped.
+*
+* Built from `String.fromCharCode` so `no-control-regex` cannot flag it statically, and built
+* ONCE: it was constructed inside the text escaper, which runs for every attribute value and
+* text child in the package, and again inside `validateObjectName` under a comment saying it was
+* the same set.
+*/
+const ILLEGAL_XML_CHARS_CLASS = ((cc) => `[${cc(0)}-${cc(8)}${cc(11)}${cc(12)}${cc(14)}-${cc(31)}${cc(127)}${cc(65534)}${cc(65535)}]`)(String.fromCharCode);
+/** The stripping form. Separate from {@link ILLEGAL_XML_CHARS} because a `g` regex is stateful under `.test`. */
+const ILLEGAL_XML_CHARS_G = new RegExp(ILLEGAL_XML_CHARS_CLASS, "g");
+/** The detecting form; see {@link ILLEGAL_XML_CHARS_G} for why the two are not one regex. */
+const ILLEGAL_XML_CHARS = new RegExp(ILLEGAL_XML_CHARS_CLASS);
+/** Does `value` carry a character XML 1.0 forbids? The escapers strip them; `validateObjectName` reports them. */
+function hasIllegalXmlChars(value) {
+	return ILLEGAL_XML_CHARS.test(value);
+}
+/**
+* Replace special XML characters with HTML-encoded strings.
+*
+* ELEMENT TEXT ONLY. A literal tab, carriage return or line feed is left alone here because in
+* character data it *is* the content (`<a:t>` line breaks depend on it). Inside an attribute value
+* the same three characters are destroyed by the parser rather than preserved — see
+* {@link encodeXmlAttrValue}, which every attribute-emitting path must use instead.
+* @param {string | number} xml - value to encode (numbers are stringified, as callers pass counts/sizes)
+* @returns {string} escaped XML
+*/
+function encodeXmlEntities(xml) {
+	if (typeof xml === "undefined" || xml == null) return "";
+	return xml.toString().replace(ILLEGAL_XML_CHARS_G, "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
+* Escape a value destined for an XML **attribute**.
+*
+* Everything {@link encodeXmlEntities} does, plus the three whitespace characters that survive in
+* element text but not in an attribute: XML 1.0 section 3.3.3 requires a parser to normalise a
+* literal tab, carriage return or line feed inside an attribute value to a single space *before any
+* consumer sees it*. Carrying one across therefore requires a character reference, so a caller's
+* `objectName: 'Abschnitts-\nuberschrift'` reads back with its line break rather than a space.
+*
+* Deliberately a separate function rather than a widening of `encodeXmlEntities`: that helper also
+* escapes element text, where a raw newline is meaningful content emitted as-is, and escaping it
+* there would change bytes across every text-bearing part in the package.
+* @param {string | number} xml - value to encode (numbers are stringified, as callers pass ids/sizes)
+* @returns {string} escaped XML, safe to place between attribute quotes
+*/
+function encodeXmlAttrValue(xml) {
+	return encodeXmlEntities(xml).replace(/\t/g, "&#9;").replace(/\n/g, "&#10;").replace(/\r/g, "&#13;");
+}
+//#endregion
+//#region src/gen/utils.ts
+/**
+* ts-pptx: shared generator helpers.
+*
+* The small cross-cutting pieces the OOXML writers all need and that belong to
+* no single part:
+*   - XML text                encodeXmlEntities (re-exported from `xml-escape.ts`)
+*   - Identifiers & naming    getUuid, validateObjectName, getDuplicateObjectNames
+*   - Slide relationships     getNewRelId, isHyperlinkRel, nextMediaTarget, preencodedPath
+*
+* DrawingML fragment builders moved to `gen/drawingml/{color,effect,fill,line}.ts`;
+* unit conversion to `units-internal.ts` (over the public primitives in `units.ts`);
+* base64/image-header decoding and media content types to `media/`.
+*/
+/**
+* Fill the `x`/`y` placeholders of a hex pattern with random nibbles.
+*
+* **Not replaceable by `crypto.randomUUID()`**, which exists on Node 24 and in every
+* browser. This takes a *format string*, and half its callers pass a partial one:
+* `gen/chart/plot-scatter.ts` asks for a bare tail (`-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)
+* to splice onto a padded point index, and its other two calls want a GUID shape with
+* no version nibble. Only `gen/define/zoom.ts` and `presentation.ts`, which pass a
+* v4-shaped pattern, could switch, and switching only those would leave two generators
+* where there is now one. The analysis is recorded here so it does not get re-derived:
+* the swap is low value and non-zero risk, and it is not on the roadmap.
+* @link https://stackoverflow.com/questions/105034/create-guid-uuid-in-javascript#answer-2117523
+* @param {string} uuidFormat - the pattern; `x` becomes a random nibble, `y` one of 8/9/a/b
+* @returns {string} the filled pattern
+*/
+function getUuid(uuidFormat) {
+	return uuidFormat.replace(/[xy]/g, function(c) {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+/**
+* A fresh v4 GUID in the braced, upper-case form OOXML attributes carry:
+* `{XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX}`.
+*
+* That is the spelling `p14:section@id` and `zmPr@id` both want, and it was written out three
+* times -- once as `zoomGuid` in `gen/define/zoom.ts` and twice inline in `presentation.ts`.
+* Nothing forced the three to agree, so a fix to the pattern in one was a fix in one.
+*/
+function bracedGuid() {
+	return `{${getUuid("xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx").toUpperCase()}}`;
+}
+/**
+* Practical maximum length for a `p:cNvPr` object name. PowerPoint does not
+* enforce a hard spec limit, but very long names are a strong signal of a bug
+* and are unwieldy in the Selection Pane.
+*/
+const MAX_OBJECT_NAME_LENGTH = 255;
+/**
+* Validate a user-supplied object name and warn (does not throw) when the value
+* cannot be preserved as a stable PowerPoint Selection Pane identity. This keeps
+* semantic-identity bugs visible at generation time without breaking existing
+* decks that pass loose names.
+* - Empty/whitespace-only names provide no usable identity.
+* - Control characters are stripped by `encodeXmlEntities` when the name is
+*   written, so the file carries a different name than the one supplied.
+* - Excessively long names may not round-trip through PowerPoint/consumers.
+* @param {string} name - the raw (pre-encoding) object name
+* @param {string} kind - object kind for the warning message (e.g. 'text')
+* @returns {string} the name unchanged (validation only)
+*/
+function validateObjectName(name, kind) {
+	if (typeof name !== "string") return name;
+	if (name.trim().length === 0) {
+		warn("object-name/empty", `${kind} objectName is empty or whitespace-only; it will not provide a stable Selection Pane identity.`);
+		return name;
+	}
+	if (hasIllegalXmlChars(name)) warn("object-name/control-characters", `${kind} objectName "${name}" contains characters XML 1.0 forbids (control characters, or U+FFFE or U+FFFF) that will be stripped from the name written to the file.`);
+	if (name.length > MAX_OBJECT_NAME_LENGTH) warn("object-name/too-long", `${kind} objectName exceeds ${MAX_OBJECT_NAME_LENGTH} characters and may not be preserved by PowerPoint.`);
+	return name;
+}
+/**
+* Return object names that appear more than once in the given list. Used to warn
+* when duplicate Selection Pane identities would be emitted on a single slide,
+* which breaks consumers (e.g. semantic manifests) that rely on unique names.
+* @param {string[]} names - object names emitted on one slide
+* @returns {string[]} the duplicated names (each listed once)
+*/
+function getDuplicateObjectNames(names) {
+	const seen = /* @__PURE__ */ new Set();
+	const dupes = /* @__PURE__ */ new Set();
+	names.forEach((name) => {
+		if (typeof name !== "string" || name.length === 0) return;
+		if (seen.has(name)) dupes.add(name);
+		else seen.add(name);
+	});
+	return Array.from(dupes);
+}
+/**
+* Get a new rel ID (rId) for charts, media, etc.
+*
+* Counting is the normal case: a slide's rels are minted in order, so one past the
+* total is free. It is not enough on its own, because a rel can arrive on a slide
+* carrying an id minted somewhere else — auto-paging re-registers a repeated header
+* row's hyperlink on each overflow slide under the id stamped on the shared
+* hyperlink object (`gen/define/hyperlinks.ts`). That id is then held but not
+* counted-to, so the next mint could hand out the same number and the part would
+* declare two `Relationship` elements sharing an `Id` — invalid OPC, and PowerPoint
+* resolves such a reference to whichever comes first. Hence the scan: start where
+* the count says, then step over anything the slide already holds.
+* @param {PresSlideInternal} target - the slide to use
+* @returns {number} the lowest free rId at or above the current rel count plus 1
+*/
+function getNewRelId(target) {
+	const held = heldRelIds(target);
+	let rId = target._rels.length + target._relsChart.length + target._relsMedia.length + 1;
+	while (held.has(rId)) rId++;
+	return rId;
+}
+/**
+* Every rel id a slide already holds, across its hyperlink, chart and media rels.
+* @param {PresSlideInternal} target - the slide to use
+* @returns {Set<number>} the held ids
+*/
+function heldRelIds(target) {
+	const held = /* @__PURE__ */ new Set();
+	target._rels.forEach((rel) => held.add(rel.rId));
+	target._relsChart.forEach((rel) => held.add(rel.rId));
+	target._relsMedia.forEach((rel) => held.add(rel.rId));
+	return held;
+}
+/**
+* Whether a slide relationship is a hyperlink (external URL or internal slide
+* link). The relationship `type` is stringly-typed (`'hyperlink'`, `'online'`,
+* mixed-case variants), so this centralizes the case-insensitive predicate that
+* was duplicated across the slide-rels writer (`gen/slide/slide.ts`) and the inspect path
+* (presentation.ts). For an internal slide-to-slide link, `rel.data === 'slide'` and
+* `rel.Target` is the 1-based target slide number.
+* @param {{ type: string }} rel - a slide relationship
+* @returns {boolean} true if the rel is any kind of hyperlink
+*/
+function isHyperlinkRel(rel) {
+	return rel.type.toLowerCase().includes("hyperlink");
+}
+/**
+* The slide-scoped segment of a media part's name.
+*
+* Media targets are namespaced by the slide that registered them so that slide
+* master (`sm`) and slide layout (`sl-N`) media never collide with regular slide
+* media names in large decks. A layout is identified by the `_slideNum >= 1000`
+* convention the layout builder stamps on it; a master has no `_slideNum` at all.
+* @param {PresSlideInternal} target - the slide, layout or master registering the media
+* @returns {string} the key to splice into the media part name
+*/
+function mediaSlideKey(target) {
+	if (target._slideNum == null) return "sm";
+	return target._slideNum >= 1e3 ? `sl-${target._slideNum}` : `${target._slideNum}`;
+}
+/**
+* The target of the media part the NEXT push onto `target._relsMedia` will create:
+* `../media/image-3-2.png`, or `../embeddings/oleObject-sm-1.xlsx` for a `dir` of
+* `embeddings`.
+*
+* The trailing number counts a target's media parts from one, and it is read *before* the
+* push that consumes the name — so this must be called in the object literal being pushed,
+* not hoisted above an earlier push, which would rename every part after it. Eight sites
+* spelled the rule out by hand with `_relsMedia.length + 1` inline; naming it is what lets
+* the off-by-one convention be stated once and read.
+*
+* @param target - the slide, layout or master registering the media
+* @param kind - the name's leading segment: `image`, `media`, `model3d`, `audio`, `oleObject`
+* @param extn - the part's file extension, without the dot
+* @param dir - which sibling directory the part lands in
+*/
+function nextMediaTarget(target, kind, extn, dir = "media") {
+	return `../${dir}/${kind}-${mediaSlideKey(target)}-${target._relsMedia.length + 1}.${extn}`;
+}
+/**
+* The `path` a media rel carries when its bytes came inline as `data` and there is no file to
+* name — `preencoded.png`, `preencoded.mp4`. Nothing loads it: the media pass tells it apart
+* with {@link isPreencodedPath}.
+*
+* The spelling still reaches a deck. An image object with no alt text falls back to its path for
+* the shape's description, so an inline image is described as `preencoded.png`, and changing
+* this changes those bytes.
+*
+* There were four spellings of it, one with no dot, and two SVG registrations that put the
+* base64 payload itself in `path`. They worked only because the media pass skipped any path
+* *containing* the word.
+* @param extn - the part's file extension, without the dot
+*/
+function preencodedPath(extn) {
+	return `preencoded.${extn}`;
+}
+/** Whether `path` is a {@link preencodedPath} placeholder rather than a file or URL to load. */
+function isPreencodedPath(path) {
+	return path.startsWith("preencoded.");
+}
+//#endregion
+//#region src/ooxml/xml-decl.ts
+/**
+* The XML prolog every OOXML part this library writes begins with, including the parts the read
+* side regenerates when it serializes a package it has changed.
+*
+* It lived with the generator-only constants, out of the read side's reach, so the read side's
+* serializers spelled it out again four times. A prolog that differs between two parts by one
+* attribute is not something any check reports, which is why it has one home that both sides can
+* import: this module imports nothing, and no `ooxml/` module imports from `gen/` or `read/`.
+*/
+const XML_DECL = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>";
+//#endregion
+//#region src/embedded-fonts.ts
+/**
+* Shared model + serializer for PresentationML embedded fonts, used by both the
+* write side (author-side `pptx.embedFont`, `gen/pres/presentation.ts`) and the read side
+* (the `embedFonts` carry in `importSlide`, `importSlides`, `importSlideMasters` and
+* `appendSlides`, `src/read/api/ops/embedded-fonts.ts`).
+*
+* Embedded fonts are three coordinated pieces (ECMA-376 transitional):
+*  1. binary font parts `/ppt/fonts/fontN.fntdata` — the **raw** TTF/OTF bytes
+*     (PresentationML does not obfuscate embedded fonts), content type
+*     `application/x-fontdata` via a single `fntdata` Default extension;
+*  2. one `font` relationship per face from `presentation.xml`;
+*  3. a `p:embeddedFontLst` in `presentation.xml`, at index 7 of the
+*     `CT_Presentation` child sequence (after `smartTags`, before `custShowLst`
+*     … `defaultTextStyle`).
+*
+* This module owns only the OOXML-shape knowledge; rId allocation and part
+* placement stay with each caller (their packaging models differ).
+*
+* It must not import from `src/gen/`, because `read/api/ops/embedded-fonts.ts` imports it. What
+* it needs from elsewhere -- the attribute escaper, the `font` relationship type and the face slot
+* list -- comes from modules that import nothing outside `src/ooxml/` themselves.
+*/
+/** Extension for the binary font parts (`/ppt/fonts/fontN.fntdata`). */
+const FONT_DATA_EXTENSION = "fntdata";
+/** Content type for a `.fntdata` part — one `Default` covers every font part. */
+const FONT_DATA_CONTENT_TYPE = "application/x-fontdata";
+/** Relationship type from `presentation.xml` to a font part (one per face). */
+const FONT_REL_TYPE = FONT_REL;
+/**
+* Flatten `fonts` into one ordered face list, assigning sequential part indices
+* (1-based) and relationship ids (starting at `firstRId`). Faces are emitted in
+* `fonts` order, each font's faces in {@link EMBEDDED_FONT_SLOTS} order. Faces
+* without `bytes` are skipped (nothing to write).
+*/
+function flattenEmbeddedFaces(fonts, firstRId) {
+	const flat = [];
+	let partIndex = 0;
+	let rId = firstRId;
+	fonts.forEach((font, fontIndex) => {
+		for (const slot of EMBEDDED_FONT_SLOTS) {
+			const face = font.faces.find((f) => f.slot === slot);
+			if (!face || !face.bytes) continue;
+			flat.push({
+				fontIndex,
+				slot,
+				bytes: face.bytes,
+				partIndex: ++partIndex,
+				rId: rId++
+			});
+		}
+	});
+	return flat;
+}
+/**
+* Serialize a `<p:embeddedFontLst>` from `fonts` and a `(fontIndex, slot) → rId`
+* lookup (typically backed by {@link flattenEmbeddedFaces}). Returns `''` when no
+* font has any face with an allocated rId, so callers can emit nothing. Assumes
+* the enclosing document declares the `p:` and `r:` prefixes (presentation.xml
+* does), so no namespace declarations are emitted here.
+*/
+function serializeEmbeddedFontLst(fonts, rIdForFace) {
+	const entries = [];
+	fonts.forEach((font, fontIndex) => {
+		const faceXml = [];
+		for (const slot of EMBEDDED_FONT_SLOTS) {
+			const rId = rIdForFace(fontIndex, slot);
+			if (rId === void 0) continue;
+			faceXml.push(`<p:${slot} r:id="rId${rId}"/>`);
+		}
+		if (faceXml.length === 0) return;
+		let fontAttrs = `typeface="${encodeXmlAttrValue(font.typeface)}"`;
+		if (font.panose !== void 0) fontAttrs += ` panose="${encodeXmlAttrValue(font.panose)}"`;
+		if (font.pitchFamily !== void 0) fontAttrs += ` pitchFamily="${font.pitchFamily}"`;
+		if (font.charset !== void 0) fontAttrs += ` charset="${font.charset}"`;
+		entries.push(`<p:embeddedFont><p:font ${fontAttrs}/>${faceXml.join("")}</p:embeddedFont>`);
+	});
+	if (entries.length === 0) return "";
+	return `<p:embeddedFontLst>${entries.join("")}</p:embeddedFontLst>`;
+}
+//#endregion
+//#region src/gen/oxml/el.ts
+/**
+* ts-pptx: XML element builder (write-side substrate)
+*
+* The write path historically concatenated template strings and called
+* `encodeXmlEntities` by hand at every interpolation — the source of escaping,
+* attribute-order and child-sequence bugs. This builder centralizes escaping
+* while reproducing today's exact byte layout, so a migration onto it can be
+* gated on strict byte-identity (`pnpm run byte-identity:check`) rather than on
+* looser schema equivalence.
+*
+* Mirrors `src/read/oxml/dom.ts` on the write side.
+*
+* Two rules make byte-identity achievable:
+*
+* 1. Self-closing is decided by ARITY, never by child value. `el()` always emits
+*    a paired tag; `voidEl()` always self-closes. This matters because
+*    `encodeXmlEntities(undefined)` returns `''`, so a value-based rule would
+*    turn today's `<dc:title></dc:title>` into `<dc:title/>` — a silent byte
+*    regression on every optional-text element in the tree.
+*
+*    Escaping is split to match: attribute values go through `encodeXmlAttrValue`
+*    (which adds the `&#9;`/`&#10;`/`&#13;` character references an XML parser
+*    would otherwise normalise to a space), text children through
+*    `encodeXmlEntities`, where those same characters are content.
+*
+* 2. Whitespace is explicit, per element, via `fmt`. Most emitted parts are flat
+*    (no `fmt` needed at all); the pretty-printed ones carry indentation that is
+*    not always depth-regular, so it is described rather than derived. Quirks
+*    like a misindented closing tag stay visible in the call site instead of
+*    being hidden inside a template literal.
+*/
+/** Wrap already-serialized XML so it is interpolated verbatim. */
+function raw(xml) {
+	return { raw: xml };
+}
+function isRaw(child) {
+	return typeof child === "object" && child !== null && typeof child.raw === "string";
+}
+function openTag(name, attrs, fmt) {
+	let out = (fmt?.openPrefix ?? "") + "<" + name;
+	for (const [key, value] of Object.entries(attrs ?? {})) {
+		if (value === void 0 || value === null) continue;
+		out += " " + key + "=\"" + encodeXmlAttrValue(value) + "\"";
+	}
+	return out;
+}
+/**
+* Paired element: `<name …>children</name>` — emitted even when `children` is
+* empty or `undefined`. Text children are escaped; `raw()` children are not.
+*/
+function el(name, attrs, children, fmt) {
+	let out = openTag(name, attrs, fmt) + ">";
+	const childPrefix = fmt?.childPrefix ?? "";
+	for (const child of Array.isArray(children) ? children : [children]) {
+		if (child === void 0 || child === null) continue;
+		out += childPrefix + (isRaw(child) ? child.raw : encodeXmlEntities(child));
+	}
+	return out + (fmt?.closePrefix ?? "") + "</" + name + ">";
+}
+/**
+* Self-closing element: `<name …/>`. `fmt.closePrefix` goes before the `/>` — a
+* handful of emitters write `<a:avLst />` with a space there, and that space is
+* byte-significant like any other.
+*/
+function voidEl(name, attrs, fmt) {
+	return openTag(name, attrs, fmt) + (fmt?.closePrefix ?? "") + "/>";
+}
+/**
+* Paired around `childXml` when it holds anything, self-closing when it does not.
+*
+* The one place arity follows content, and on purpose: a lock set, a binding list or an effect
+* that may be empty makes its element paired or self-closing, and PowerPoint writes it that way.
+* Rule 1 above still holds everywhere else. Each caller used to spell the choice as its own
+* `x ? el(n, a, raw(x)) : voidEl(n, a)`.
+* @param childXml - already-serialized children; empty or absent means self-closing
+*/
+function elOrVoid(name, attrs, childXml, fmt) {
+	return childXml ? el(name, attrs, raw(childXml), fmt) : voidEl(name, attrs, fmt);
+}
+//#endregion
+//#region src/gen/drawingml/color.ts
+/**
+* ts-pptx: DrawingML color elements
+*
+* Emit the bare `<a:srgbClr>` / `<a:schemeClr>` color element that every other
+* color context builds on (solid fills, gradient stops, effect alphas, line
+* fills, highlights, patterns).
+*
+* The RGB->hex helpers this module used to carry now live in
+* `gen/table/html-dom.ts`, their only caller: they are reachable exclusively from
+* the browser-only `tableToSlides` path, so keeping them here made them permanent
+* dead weight in the Node chunk's coverage report (33% functions on a file that is
+* otherwise fully exercised) while html-dom.ts is coverage-excluded wholesale.
+*/
+/**
+* Opening delimiter of an `<a:alpha>` child, for detecting one a caller already
+* supplied. A prefix rather than a whole element: the value is the caller's, and
+* this asks only whether the element is present.
+*/
+const ALPHA_TAG = "<a:alpha";
+/**
+* Emit a bare DrawingML color element — either `<a:schemeClr>` (scheme color) or `<a:srgbClr>`
+* (hex RGB). This is a low-level primitive: it is the shared building block for every color
+* context (solid fills, gradient stops, `<a:alpha>` on shadows/glow, line fills, highlight,
+* underline, patterns, …), so it is intentionally NOT limited to solid fills and cannot be
+* folded into `genXmlColorSelection`.
+*
+* When you specifically want a *solid fill*, prefer `genXmlColorSelection` (`fill.ts`), which
+* wraps this in `<a:solidFill>…</a:solidFill>` and also handles `alpha`/`transparency` and the
+* gradient/pattern/image fill types — reach for `createColorElement` directly only when you
+* need the raw color element (e.g. inside `<a:ln>`, `<a:gs>`, an effect, or a highlight).
+* @param {string|SCHEME_COLORS} colorStr - hex RGB (e.g. "FFFF00") or a scheme color constant (e.g. SchemeColor.ACCENT1)
+* @param {string} [innerElements] - additional elements that adjust the color, nested inside the color element
+* @returns {string} XML string
+*/
+function createColorElement(colorStr, innerElements) {
+	if (typeof colorStr !== "string") {
+		warn("color/not-a-string", `createColorElement: expected a string color value, got ${typeof colorStr}. "${DEF_FONT_COLOR}" used instead.`);
+		colorStr = DEF_FONT_COLOR;
+	}
+	if (colorStr === "") {
+		warnOnce("color/empty-string", `An empty string is not a color. "${DEF_FONT_COLOR}" used instead: this position requires one, so there is nothing to inherit. Omit the whole option if you meant to paint nothing.`);
+		colorStr = DEF_FONT_COLOR;
+	}
+	let colorVal = stripHash(colorStr || "");
+	const rgba = splitRgbaHex(colorVal);
+	if (rgba.alpha !== void 0) {
+		if (!innerElements?.includes(ALPHA_TAG)) innerElements = alphaEl(Math.round(rgba.alpha * PERCENT_SCALE)) + (innerElements || "");
+		colorVal = rgba.rgb;
+	}
+	if (!isColorValue(colorVal)) {
+		warn("color/invalid-value", `"${colorVal}" is not a valid scheme color or hex RGB! "${DEF_FONT_COLOR}" used instead. Only provide 6-digit RGB or 'SchemeColor' values!`);
+		colorVal = DEF_FONT_COLOR;
+	}
+	const isHex = isHexColor(colorVal);
+	return elOrVoid(isHex ? "a:srgbClr" : "a:schemeClr", { val: isHex ? colorVal.toUpperCase() : colorVal }, innerElements);
+}
+/**
+* Whether {@link createColorElement} paints `value` as given rather than replacing it: 6-digit or
+* 8-digit (RGBA) hex, with or without a leading `#`, or a {@link SchemeColor} name.
+*
+* A normalizer that wants to fall back to its own default instead of the emitter's black asks
+* this, so the two cannot disagree about what a colour is.
+* @param value - a colour option's value, whatever the caller passed
+*/
+function isColorValue(value) {
+	if (typeof value !== "string") return false;
+	const { rgb } = splitRgbaHex(value);
+	return isHexColor(rgb) || Object.values(SchemeColor).includes(rgb);
+}
+/**
+* Reject an empty colour string, reporting it once per option that named one.
+*
+* `''` is not a spelling of "no paint": omission already spells that, and `'inherit'` and
+* `'none'` spell the other two states a paint can be in. It reaches the library from the
+* caller's own missing value — an unset template field, `row.accent` on a row that has none
+* — so the useful answer is to say so and then behave exactly as omitting the option would
+* have. What it must not do is coerce to {@link DEF_FONT_COLOR}, which paints visible black
+* on a shape the caller expected to keep the theme's paint.
+*
+* Every site that consumes a caller-supplied colour calls this *before* its own fallback, so
+* the diagnostic names the option that carried the empty string rather than whichever
+* emitter happened to see it last. {@link createColorElement} is the exception and reports
+* the same code itself: its slot has no absent state to fall back to.
+* @param value - a colour option's value, whatever shape the option accepts
+* @param option - the option's name, for the message
+* @returns true when `value` was the empty string
+*/
+function rejectEmptyColor(value, option) {
+	if (value !== "") return false;
+	warnOnce("color/empty-string", `\`${option}\` is an empty string, which is not a color — the option was ignored, exactly as omitting it would be. Pass 6-digit hex RGB (e.g. "FF3399") or a SchemeColor value.`);
+	return true;
+}
+/**
+* The colour the caller named for `option`, or `fallback` when they named none.
+*
+* The `x ?? DEFAULT` and `x || DEFAULT` this replaces disagreed about `''`: the first passed
+* it through to be painted black or dropped, the second quietly resolved it to the default.
+* Here it is one rule — an empty string is a missing value, reported and then resolved the
+* way an absent option is.
+* @param value - the caller's colour option, possibly absent or empty
+* @param fallback - what an absent option resolves to at this site
+* @param option - the option's name, for the message
+*/
+function namedColorOr(value, fallback, option) {
+	if (value === void 0 || rejectEmptyColor(value, option)) return fallback;
+	return value;
+}
+/**
+* The `<a:alpha val>` child a colour element carries.
+*
+* Four sites built it: the RGBA split above, the gradient stop's `transparency`, the glow and
+* shadow `opacity`, and the chart's `chartColorsOpacity`. Each converts to the fixed
+* percentage its own option speaks first; this is only the element.
+* @param fixedPct - the alpha in `ST_PositiveFixedPercentage` units (`100%` is `100000`)
+*/
+function alphaEl(fixedPct) {
+	return voidEl("a:alpha", { val: fixedPct });
+}
+//#endregion
+//#region src/gen/drawingml/effect.ts
+/**
+* ts-pptx: DrawingML effects (glow and shadow)
+*
+* Emit the `<a:glow>` / `<a:outerShdw>` / `<a:innerShdw>` children of an
+* `<a:effectLst>`, and normalize the user-facing `shadow` options into the
+* internal shape every emit site reads.
+* @see http://officeopenxml.com/drwSp-effects.php
+*/
+/**
+* Creates `a:glow` element
+* @param {TextGlowProps} options glow properties
+* @param {TextGlowProps} defaults defaults for unspecified properties in `opts`
+* @see http://officeopenxml.com/drwSp-effects.php
+* { size: 8, color: 'FFFFFF', opacity: 0.75 };
+*/
+function createGlowElement(options, defaults) {
+	const opts = {
+		...defaults,
+		...options
+	};
+	const size = positiveCoordinateEmu(opts.size, "glow/size-out-of-range", "glow.size");
+	const color = namedColorOr(opts.color, DEF_FONT_COLOR, "glow.color");
+	const opacity = opacityToAlpha(opts.opacity ?? 0);
+	return el("a:glow", { rad: size }, raw(createColorElement(color, alphaEl(opacity))));
+}
+/**
+* Creates an `a:outerShdw`/`a:innerShdw` element for a text run, shape, image, or chart.
+* Returns the shadow element only (no wrapping `a:effectLst`) so callers can either combine
+* it with other effects (e.g. glow) inside one `a:effectLst`, or wrap a lone shadow via
+* {@link createShadowEffectLst}.
+*
+* Colors go through {@link createColorElement}, so scheme colors (e.g. `accent1`) are honored
+* — earlier per-site copies hardcoded `a:srgbClr` and silently emitted invalid OOXML for them.
+* @param {ShadowPropsInternal} options shadow properties
+* @param {ShadowPropsInternal} defaults defaults for unspecified properties in `options`
+* @see http://officeopenxml.com/drwSp-effects.php
+* @returns {string} XML string, or '' when type is 'none'
+*/
+function createShadowElement(options, defaults) {
+	const opts = {
+		...defaults,
+		...options
+	};
+	if (opts.type === "none") return "";
+	const type = opts.type || "outer";
+	const blur = positiveCoordinateEmu(opts.blur ?? 0, "shadow/blur-out-of-range", "shadow.blur");
+	const offset = positiveCoordinateEmu(opts.offset ?? 0, "shadow/offset-out-of-range", "shadow.offset");
+	const angle = convertAngleUnits(opts.angle ?? 0, "shadow.angle");
+	const opacity = Math.round((opts._alpha ?? .75) * PERCENT_SCALE);
+	const color = namedColorOr(opts.color, DEF_FONT_COLOR, "shadow.color");
+	const attrs = {
+		...type === "outer" ? {
+			sx: 1e5,
+			sy: 1e5,
+			kx: 0,
+			ky: 0,
+			algn: "bl",
+			rotWithShape: xsdBool(opts.rotateWithShape)
+		} : {},
+		blurRad: blur,
+		dist: offset,
+		dir: angle
+	};
+	return el(`a:${type}Shdw`, attrs, raw(createColorElement(color, alphaEl(opacity))));
+}
+/**
+* Wraps a lone shadow in the `a:effectLst` that CT_ShapeProperties (shapes/images) and chart
+* marker/data-point properties require. Returns a self-closing `<a:effectLst/>` when there is
+* no shadow (missing/non-object options, or `type: 'none'`), matching the "no effects" element
+* PowerPoint emits. Use this instead of {@link createShadowElement} when the shadow is the only
+* effect; use `createShadowElement` directly when combining with other effects (e.g. glow).
+* @param {ShadowPropsInternal} options shadow properties
+* @param {ShadowPropsInternal} defaults defaults for unspecified properties in `options`
+* @returns {string} `<a:effectLst>…</a:effectLst>` or `<a:effectLst/>`
+*/
+function createShadowEffectLst(options, defaults) {
+	if (!options || typeof options !== "object") return voidEl("a:effectLst");
+	return elOrVoid("a:effectLst", null, createShadowElement(options, defaults));
+}
+/**
+* Normalize a caller's `shadow` into the internal shape every emit site reads: a legal `type`, a
+* whole-degree `angle` inside `ST_PositiveFixedAngle`, a `_alpha` derived from `transparency` or
+* from an RGBA colour's alpha byte, and a colour with no `#` and no alpha byte.
+*
+* **Pure.** It used to normalize the caller's object *in place* and return it, and its four call
+* sites split on which of the two contracts they used — two assigned the result, two discarded it
+* and relied on the mutation. That made the obvious cleanup a trap: making it pure without
+* converting every caller silently drops `transparency` and RGBA alpha on every text run, because
+* `_alpha` is what `genXmlTextRunProperties` reads and nothing else writes it. The value now
+* reaches the emitter as a value rather than as a side effect, and a shadow literal shared across
+* two shapes comes back untouched.
+* @param shadow - the caller's shadow options
+* @returns a fresh normalized bag, or `undefined` when the caller stated no shadow object
+*/
+function normalizeShadowOptions(shadow) {
+	if (!shadow || typeof shadow !== "object") return;
+	const corrected = { ...shadow };
+	if (corrected.type !== "outer" && corrected.type !== "inner" && corrected.type !== "none") {
+		warn("shadow/invalid-type", "shadow.type options are `outer`, `inner` or `none`.");
+		corrected.type = "outer";
+	}
+	if (corrected.angle !== void 0) corrected.angle = Math.round(clampRangedInput(corrected.angle, 0, 359, "shadow/angle-out-of-range", "shadow.angle", "shadow/angle-non-finite"));
+	if (corrected.transparency !== void 0) corrected._alpha = 1 - clampRangedInput(corrected.transparency, 0, 100, "shadow/transparency-out-of-range", "shadow.transparency") / 100;
+	if (corrected.color) {
+		if (corrected.color.startsWith("#")) {
+			warn("shadow/color-has-hash", "shadow.color should not include hash (#) character, , e.g. \"FF0000\"");
+			corrected.color = stripHash(corrected.color);
+		}
+		const rgba = splitRgbaHex(corrected.color);
+		if (rgba.alpha !== void 0) {
+			if (corrected._alpha === void 0) corrected._alpha = rgba.alpha;
+			corrected.color = rgba.rgb;
+		}
+	}
+	return corrected;
+}
+//#endregion
+//#region src/gen/drawingml/src-rect.ts
+/**
+* ts-pptx: the explicit `<a:srcRect>` source crop
+*
+* A leaf module on purpose. A picture object (`addImage`) and a native picture fill
+* (`fill: { type: 'image' }`) crop a source image the same way, but they live on opposite
+* sides of a bundling boundary: `gen/drawingml/fill.ts` is reached from every shape, table
+* and chart emitter, while `gen/drawingml/image.ts` pulls the image-format sniffing tables
+* in behind it through `media/image-size.ts`. Sharing the crop from here rather than from
+* `image.ts` is what keeps ~24 kB of format headers out of the `read` and `inspect` entry
+* points, which never measure an image.
+*/
+/**
+* The four insets, defaulted and checked. Rejects anything that is not a percentage and
+* any pair that would leave no source area at all — a degenerate `<a:srcRect>` renders as
+* an empty shape rather than as an error, so it has to fail here.
+* @param crop - edge insets in percent; omitted edges default to 0
+* @param label - the option's owner, as an error message names it (`addImage`, `image fill`)
+* @param where - trailing context for an error message, or `''`
+*/
+function normalizeImageCrop(crop, label, where) {
+	const edges = {
+		l: crop.l ?? 0,
+		t: crop.t ?? 0,
+		r: crop.r ?? 0,
+		b: crop.b ?? 0
+	};
+	for (const [name, val] of Object.entries(edges)) if (typeof val !== "number" || !Number.isFinite(val) || val < 0 || val > 100) throw new InvalidOptionError("image/crop-inset-out-of-range", `${label} crop.${name} must be a percentage between 0 and 100 (got ${String(val)})${where}.`);
+	if (edges.l + edges.r >= 100) throw new InvalidOptionError("image/crop-insets-exceed-extent", `${label} crop: left+right insets (${edges.l}%+${edges.r}%) must be < 100%${where}.`);
+	if (edges.t + edges.b >= 100) throw new InvalidOptionError("image/crop-insets-exceed-extent", `${label} crop: top+bottom insets (${edges.t}%+${edges.b}%) must be < 100%${where}.`);
+	return edges;
+}
+/**
+* Build an explicit `<a:srcRect>` crop from percentage edge insets (0–100), emitted verbatim.
+* Each inset is the percent of the *source* image trimmed from that edge; values serialize in
+* 1000ths of a percent (DrawingML `ST_Percentage`, where 100% = 100000). Unlike `sizing: 'crop'`
+* — which derives the rect from displayed inches and the natural pixel size — this maps a
+* sub-region of the source directly, so it works for SVG and other unmeasurable formats.
+* @param crop - edge insets in percent; omitted edges default to 0
+* @param label - the option's owner, as an error message names it
+* @param where - trailing context for an error message, or `''`
+* @returns the `<a:srcRect>` element on its own; the caller supplies the fill directive
+*/
+function genXmlImageCropRect(crop, label, where) {
+	const edges = normalizeImageCrop(crop, label, where);
+	const v = (perc) => Math.round(perc * FIXED_PCT_PER_PERCENT);
+	return voidEl("a:srcRect", {
+		l: v(edges.l),
+		t: v(edges.t),
+		r: v(edges.r),
+		b: v(edges.b)
+	});
+}
+/**
+* `<a:stretch><a:fillRect/></a:stretch>` — the blipFill child that scales the source to the
+* shape's box, which every picture-bearing emitter writes and none parameterizes.
+*
+* After an `<a:srcRect/>`, it completes the canonical picture fill ECMA-376 gives
+* (§L.4.8.4.3). A picture's placement is split across two elements: the source rectangle and
+* this directive, which carry `sizing` and `crop`, sit in `p:blipFill`, while the clip
+* geometry (`shape`, `points`, `rounding`) sits in `p:spPr`.
+*
+* Here rather than in `image.ts` for the same bundling reason the crop is: `fill.ts` reaches
+* it from every shape, table and chart emitter, and must not pull the image-format tables in.
+*/
+const STRETCH_FILL_RECT = el("a:stretch", null, raw(voidEl("a:fillRect")));
+//#endregion
+//#region src/gen/drawingml/fill.ts
+/**
+* ts-pptx: DrawingML fills
+*
+* Emit the fill group a shape, cell, chart element, or line paint can carry:
+* `<a:solidFill>`, `<a:gradFill>`, `<a:pattFill>`, `<a:blipFill>`.
+* {@link genXmlColorSelection} is the dispatch every caller should reach for;
+* the per-kind builders are exported for the few sites that know their fill kind.
+*/
+function normalizeGradientAngle(angle) {
+	const degrees = angle ?? 0;
+	if (typeof degrees !== "number" || !Number.isFinite(degrees)) throw new InvalidOptionError("gradient/angle-non-finite", "Gradient angle must be a finite number.");
+	return convertRotationDegrees((degrees % 360 + 360) % 360);
+}
+function alphaFromTransparency(transparency) {
+	return mapStated(transparency, (value) => alphaEl(transparencyToAlpha(value))) ?? "";
+}
+function normalizeGradientStops(stops) {
+	if (!Array.isArray(stops) || stops.length < 2) throw new InvalidOptionError("gradient/too-few-stops", "Gradient fill requires at least two stops.");
+	return stops.map((stop) => {
+		if (!stop || typeof stop.position !== "number" || !Number.isFinite(stop.position)) throw new InvalidOptionError("gradient/stop-position-non-finite", "Gradient stop position must be a finite number from 0 to 100.");
+		if (stop.position < 0 || stop.position > 100) throw new InvalidOptionError("gradient/stop-position-out-of-range", "Gradient stop position must be from 0 to 100.");
+		return stop;
+	}).sort((a, b) => a.position - b.position);
+}
+/**
+* Create a native DrawingML gradient fill.
+* @param {GradientFillProps} gradient gradient fill options
+* @returns XML string
+*/
+function genXmlGradientFill(gradient) {
+	if (!gradient || gradient.kind !== "linear" && gradient.kind !== "radial") throw new UnsupportedFeatureError("gradient/type-unsupported", "Gradient fill currently supports only linear and radial gradients.");
+	if (typeof gradient.rotateWithShape !== "undefined" && typeof gradient.rotateWithShape !== "boolean") throw new InvalidOptionError("gradient/rotate-with-shape-not-boolean", "Gradient rotateWithShape must be a boolean.");
+	const stops = normalizeGradientStops(gradient.stops);
+	const rotWithShape = gradient.rotateWithShape ?? true;
+	const gsLst = el("a:gsLst", null, stops.map((stop) => raw(el("a:gs", { pos: Math.round(stop.position * FIXED_PCT_PER_PERCENT) }, raw(createColorElement(stop.color, alphaFromTransparency(stop.transparency)))))));
+	let shape;
+	if (gradient.kind === "radial") {
+		const centerPct = (value, axis) => clampRangedInput(value ?? 50, 0, 100, "gradient/center-out-of-range", `gradient.center.${axis}`);
+		const cx = centerPct(gradient.center?.x, "x");
+		const cy = centerPct(gradient.center?.y, "y");
+		shape = el("a:path", { path: "circle" }, raw(voidEl("a:fillToRect", {
+			l: Math.round(cx * FIXED_PCT_PER_PERCENT),
+			t: Math.round(cy * FIXED_PCT_PER_PERCENT),
+			r: Math.round((100 - cx) * FIXED_PCT_PER_PERCENT),
+			b: Math.round((100 - cy) * FIXED_PCT_PER_PERCENT)
+		})));
+	} else {
+		if (typeof gradient.scaled !== "undefined" && typeof gradient.scaled !== "boolean") throw new InvalidOptionError("gradient/scaled-not-boolean", "Gradient scaled must be a boolean.");
+		shape = voidEl("a:lin", {
+			ang: normalizeGradientAngle(gradient.angle),
+			scaled: typeof gradient.scaled === "boolean" ? xsdBool(gradient.scaled) : void 0
+		});
+	}
+	return el("a:gradFill", { rotWithShape: xsdBool(rotWithShape) }, [raw(gsLst), raw(shape)]);
+}
+/**
+* Create a native DrawingML pattern fill.
+* @param {PatternFillProps} pattern pattern fill options
+* @returns XML string
+*/
+function genXmlPatternFill(pattern) {
+	if (!pattern) throw new InvalidOptionError("pattern-fill/missing-pattern", "Pattern fill requires a pattern object.");
+	const fgColor = namedColorOr(pattern.fgColor, "000000", "pattern.fgColor");
+	const bgColor = namedColorOr(pattern.bgColor, "FFFFFF", "pattern.bgColor");
+	return el("a:pattFill", { prst: pattern.preset }, [raw(el("a:fgClr", null, raw(createColorElement(fgColor)))), raw(el("a:bgClr", null, raw(createColorElement(bgColor))))]);
+}
+/**
+* Create a native DrawingML picture (image) fill.
+* The media relationship is registered when the object is added; this only emits
+* the `<a:blipFill>` referencing the pre-resolved rId.
+* @param props fill props (must carry a resolved `_imgRid`)
+* @returns XML string
+*/
+function genXmlImageFill(props) {
+	if (!props || typeof props._imgRid !== "number") {
+		warn("image-fill/unresolved-media", "image fill is missing its resolved media reference; falling back to no fill. Provide `image: { path }` or `image: { data }`.");
+		return voidEl("a:noFill");
+	}
+	const alpha = props.transparency;
+	const blipInner = alpha ? voidEl("a:alphaModFix", { amt: transparencyToAlpha(alpha) }) : "";
+	const srcRect = props.image?.crop ? genXmlImageCropRect(props.image.crop, "image fill", "") : voidEl("a:srcRect");
+	return el("a:blipFill", {
+		dpi: 0,
+		rotWithShape: 1
+	}, [
+		raw(el("a:blip", { "r:embed": `rId${props._imgRid}` }, raw(blipInner))),
+		raw(srcRect),
+		raw(STRETCH_FILL_RECT)
+	]);
+}
+/**
+* Resolve which fill kind a set of fill or line props asks for.
+*
+* **An explicit `type` always wins**, even against a sub-object that disagrees:
+* `{ type: 'solid', gradient }` is a solid fill whose gradient is ignored. That is the rule
+* `type: 'none'` needs in order to mean anything (`{ type: 'none', color }` must stay
+* transparent), so it is the rule everywhere rather than one kind's exception.
+*
+* With no `type`, the first sub-object present selects the kind, in declaration order —
+* `gradient`, then `pattern`, then `image`. Setting two without a `type` is already a
+* contradiction; the order exists so the answer is stated rather than emergent.
+*
+* Everything else is `'solid'`, which is what `type` documents as its default.
+*
+* This is the one answer. It used to be given in four places: the stroke emitter inferred
+* `gradient` only, the shared dispatcher inferred nothing at all (so `fill: { gradient }`
+* painted a black `<a:solidFill>` and blamed the caller's colours for it), and three
+* `define/` modules each carried their own copy of the image half.
+*/
+function resolveFillKind(props) {
+	if (!props || typeof props === "string") return "solid";
+	if (props.type) return props.type;
+	if (props.gradient) return "gradient";
+	if (props.pattern) return "pattern";
+	if ("image" in props && props.image) return "image";
+	return "solid";
+}
+/**
+* {@link resolveFillKind} for a stroke, which has one kind fewer.
+*
+* `<a:ln>`'s paint child is `EG_LineFillProperties` — `a:noFill`, `a:solidFill`, `a:gradFill`,
+* `a:pattFill` — with no `a:blipFill` among them, so a picture stroke has no OOXML expression
+* and `ShapeLineProps` subtracts `image` from the fill props it inherits. This is where the
+* subtraction is enforced at run time, for the JS caller TypeScript cannot stop: the request
+* is refused rather than painted as nothing, because emitting a blipFill inside `a:ln` is a
+* package PowerPoint reports as needing repair, and emitting nothing is a stroke the caller
+* asked to be a picture and got in the theme colour without being told.
+*
+* Every stroke site resolves through here — the two `define/` rebuilds and the emitter — so
+* the refusal names the call the caller made rather than surfacing at serialization time.
+*/
+function resolveLineKind(props) {
+	const kind = resolveFillKind(props);
+	if (kind === "image") throw new UnsupportedFeatureError("line/image-fill-unsupported", "A picture stroke is not expressible in OOXML: `a:ln` accepts noFill/solidFill/gradFill/pattFill only. Use `fill: { image }` for a picture interior, or give the line a solid, gradient or pattern paint.");
+	return kind;
+}
+/**
+* Does this fill or line props object name a paint at all?
+*
+* The question every *optional* paint site has to answer before dispatching: an outline, a
+* slide background and a table cell each inherit when the caller said nothing, so emitting
+* a fill child for an empty props object would paint them default black.
+*
+* "Said nothing" is narrower than "is empty". `'inherit'` is the explicit spelling of the
+* same silence and is false here. `'none'` is a statement — `<a:noFill/>` — and is true.
+* A `'solid'` kind needs a `color` to be saying anything; every other kind carries its
+* payload in its own sub-object, so its presence is the statement.
+*
+* An empty `color` string answers false as well, but is reported on the way out
+* ({@link rejectEmptyColor}): it is the caller's own missing value rather than a third
+* spelling of silence, and it used to reach here from sites that painted it black.
+*/
+function fillNamesPaint(props) {
+	if (!props) return false;
+	if (typeof props === "string") return !rejectEmptyColor(props, "color") && props.length > 0;
+	const kind = resolveFillKind(props);
+	if (kind === "inherit") return false;
+	if (kind === "solid") return !rejectEmptyColor(props.color, "color") && Boolean(props.color);
+	return true;
+}
+/**
+* Reject the empty-colour spelling of a missing value, in either shape a fill can wear.
+*
+* `''` and `{ color: '' }` say the same thing — the caller had no colour — and only the
+* second used to reach {@link createColorElement} and paint black. Both fold back onto
+* *absence* here, which is not the same as "emit nothing": what an absent fill means is the
+* surface's own rule, and a text box's absent fill is `<a:noFill/>`. So a site whose absence
+* rule is anything other than silence calls this before it branches, rather than letting
+* {@link genXmlColorSelection} answer for it.
+* @param props - the caller's fill or line props, in any shape the option accepts
+* @param option - the option's name, for the message
+* @returns true when the props carried the empty colour string
+*/
+function rejectEmptyFill(props, option) {
+	if (props === void 0 || typeof props === "string") return rejectEmptyColor(props, option);
+	return resolveFillKind(props) === "solid" && rejectEmptyColor(props.color, option);
+}
+/**
+* A solid paint for {@link genXmlColorSelection}, carrying `transparency` only when one was set.
+*
+* Every caller assembles this out of an optional source — `border.transparency`,
+* `opts.transparency` — and writing the key with an `undefined` in it would be a second spelling
+* of "no transparency": one that reads the same here, but not in a bag that is spread over
+* another. So the key is simply absent, which is this codebase's one spelling of unset.
+* @param color - the colour to paint, already resolved against whatever default applies
+* @param transparency - percent transparency, or `undefined` for none
+*/
+function solidPaint(color, transparency) {
+	return transparency === void 0 ? { color } : {
+		color,
+		transparency
+	};
+}
+/**
+* Emit the fill group a set of fill/line props asks for, dispatching on
+* {@link resolveFillKind}. Returns '' for props that name nothing to paint, so a caller
+* with an optional paint can hand this whatever it has — including `undefined`.
+* @param {Color | ShapeFillProps | ShapeLineProps | undefined} props fill props
+* @returns XML string
+*/
+function genXmlColorSelection(props) {
+	let colorVal = "";
+	let internalElements = "";
+	let outText = "";
+	if (rejectEmptyFill(props, "color")) return "";
+	if (props) {
+		const fillType = resolveFillKind(props);
+		if (typeof props === "string") colorVal = props;
+		else {
+			if (props.color) colorVal = props.color;
+			internalElements += alphaFromTransparency(props.transparency);
+		}
+		switch (fillType) {
+			case "none":
+				outText += voidEl("a:noFill");
+				break;
+			case "inherit":
+				outText += "";
+				break;
+			case "solid":
+				outText += el("a:solidFill", null, raw(createColorElement(colorVal, internalElements)));
+				break;
+			case "gradient":
+				outText += genXmlGradientFill(typeof props === "string" ? void 0 : props.gradient);
+				break;
+			case "pattern":
+				outText += genXmlPatternFill(typeof props === "string" ? void 0 : props.pattern);
+				break;
+			case "image":
+				outText += genXmlImageFill(typeof props === "string" ? void 0 : props);
+				break;
+			default: outText += "";
+		}
+	}
+	return outText;
+}
+//#endregion
+//#region src/gen/drawingml/line.ts
+/**
+* Every key `BorderProps` defines.
+*
+* Derived from the interface rather than transcribed from it: the `satisfies` makes a key added
+* to `BorderProps` and not to this list a compile error, where the old `readonly string[]` and a
+* "keep in step" comment made it a silent omission.
+*/
+const BORDER_KEYS = Object.keys({
+	type: 0,
+	dashType: 0,
+	color: 0,
+	width: 0,
+	transparency: 0,
+	cap: 0
+});
+/**
+* Resolve an `a:prstDash/@val`, falling back when the caller named nothing or named something
+* outside `ST_PresetLineDashVal`.
+*
+* Nine sites in the emitters reach that attribute and five of them wrote the caller's value
+* straight through, so the SAME type on the SAME attribute got two answers: a table border's
+* `dashType: 'bogusDash'` warned and fell back to solid, a shape line's went into the part. A
+* value outside the union makes the part schema-invalid, which PowerPoint reports as a corrupt
+* file rather than as a mis-set option.
+* @param value - the caller's dash, if any
+* @param fallback - what to emit when the caller named none, or named one outside the union
+* @param label - how the diagnostic names the option, e.g. `'border: dashType'`
+* @returns a value legal for `a:prstDash/@val`
+*/
+function resolveDash(value, fallback, label) {
+	return checkEnumOrWarn(value, PRESET_LINE_DASHES, "border/invalid-dash-type", label) ?? fallback;
+}
+/**
+* Resolve the `a:prstDash/@val` a {@link StrokeProps} should emit.
+*
+* `type` is a three-way switch, so on its own it can only say "dashed" and every dashed
+* stroke collapses onto `sysDash`. `dashType` names the preset directly and therefore wins
+* when both are given; `type: 'none'` never reaches here, being decided by the caller before
+* any dash is chosen.
+* @param stroke - the caller's stroke properties
+* @param label - how the diagnostic names the option, e.g. `'border: dashType'`
+* @returns a value legal for `a:prstDash/@val`
+*/
+function strokeDash(stroke, label) {
+	return resolveDash(stroke.dashType, stroke.type === "dash" ? "sysDash" : "solid", label);
+}
+/**
+* {@link strokeDash} under the name the table and chart-area borders call it by.
+* @param {BorderProps} border - the caller's border properties
+* @returns {string} a value legal for `a:prstDash/@val`
+*/
+function resolveBorderDash(border) {
+	return strokeDash(border, "border: dashType");
+}
+/**
+* The `<a:solidFill>` (or `<a:noFill/>`) a {@link StrokeProps} paints with.
+*
+* `type: 'none'` is the one state that is not a colour, and it is decided here rather than at
+* each of the four chart call sites that used to spell it as a separate `*Show: false` flag or
+* as a `style: 'none'` sentinel.
+* @param stroke - the caller's stroke properties
+* @param defaultColor - the colour to paint when the caller named none
+* @returns the paint element
+*/
+function strokePaint(stroke, defaultColor) {
+	if (stroke.type === "none") return voidEl("a:noFill");
+	return genXmlColorSelection(solidPaint(namedColorOr(stroke.color, defaultColor, "line.color"), stroke.transparency));
+}
+/**
+* Resolve an arrowhead type for `a:headEnd/@type` / `a:tailEnd/@type`, or `null` when the caller
+* named none -- the attribute is then not written and that end of the stroke stays plain.
+*
+* `ST_LineEndType` had no runtime tuple at all, so the two options were emitted verbatim and an
+* untyped caller could reach the attribute with anything.
+* @param value - the caller's arrow type, if any
+* @param label - how the diagnostic names the option, e.g. `'line: beginArrowType'`
+* @returns a value legal for the attribute, or `null` to omit it
+*/
+function resolveLineEnd(value, label) {
+	return checkEnumOrWarn(value, LINE_END_TYPES, "line/invalid-arrow-type", label);
+}
+/**
+* One arrowhead element (`<a:headEnd>` / `<a:tailEnd>`), or `''` when the caller named no arrow
+* or named one outside `ST_LineEndType`.
+* @param tag - `a:headEnd` or `a:tailEnd`
+* @param value - the caller's arrow type, if any
+* @param label - how the diagnostic names the option
+* @returns the element, or `''`
+*/
+function lineEndEl(tag, value, label) {
+	const type = resolveLineEnd(value, label);
+	return type === null ? "" : voidEl(tag, { type });
+}
+/**
+* Report an authored key that is not part of `BorderProps`, which the library would
+* otherwise drop without a sound.
+*
+* TypeScript's excess-property check already rejects a stray key on a border written
+* *inline* at the call site. It deliberately does not fire when the border is built as
+* a variable first (`const b = {...}; addTable(rows, { border: b })`) — a variable may
+* legitimately be a supertype. That exemption covers precisely the reuse pattern a
+* shared grid style encourages, so the mistake reaches here typed as valid and the
+* wrong-named value is discarded during generation. A `.pptx` gives no other signal:
+* nothing throws, the deck opens, and the border simply renders at its default weight.
+* @param border - the caller's border properties
+*/
+function warnUnknownBorderKeys(border) {
+	for (const key in border) {
+		if (!Object.hasOwn(border, key) || BORDER_KEYS.includes(key)) continue;
+		warnOnce("border/unknown-key", `border: unknown option \`${key}\` is ignored — valid keys are ${BORDER_KEYS.join(", ")}. Line thickness is \`width\`, in points.`, {
+			received: key,
+			valid: BORDER_KEYS
+		});
+	}
+}
+/**
+* Resolve a border's line width in points, falling back to `defaultPt` when `width`
+* is not a number.
+*
+* A number that is not finite is not a missing width, so it goes on to the converter rather
+* than taking the default: `lineWidthToEmu` refuses `NaN` and clamps `Infinity` to the top of
+* `ST_LineWidth`, as it does for every other line width.
+*
+* Every `BorderProps` the library reads — table cell borders, table-style regions, and
+* every chart border — resolves its width through here, so this doubles as the one
+* place that can vet a border's shape for all of them ({@link warnUnknownBorderKeys}).
+* @param {BorderProps} border - border properties (may carry `width`)
+* @param {number} defaultPt - width to use when `width` is not a number
+* @returns {number} resolved width in points
+*/
+function resolveBorderWidth(border, defaultPt) {
+	warnUnknownBorderKeys(border);
+	const val = border.width;
+	return typeof val === "number" ? val : defaultPt;
+}
+/**
+* A shape outline with its defaults applied: the kind `resolveLineKind` answers, no transparency, a
+* 1pt width, a solid dash, and on a solid stroke the default colour.
+*
+* Shapes, line-shaped text boxes and connectors each merged these themselves, and the connector
+* disagreed about zero: `line.width: 0` took the 1pt default on a shape and a text box, and wrote no
+* width at all on a connector. `0` means "not stated" for a line width, as it does for every option
+* `mapStated` guards, so all three take the default.
+*
+* The caller's line is spread first and only the defaulted keys are written over it. Listing the
+* carried keys instead is what once dropped `pattern`, `gradient` and `cap`: each was added to
+* `ShapeLineProps` without being added to the list, so the emitter read a key normalization had
+* already dropped. Only the solid arm writes `color`. The spread already carried whatever colour
+* another kind stated, and re-writing it would turn an unstated one into a present `undefined`.
+* @param line - the caller's line
+* @param colorLabel - how the caller's colour option is named in a colour warning
+* @returns the line with its defaults applied
+*/
+function withLineDefaults(line, colorLabel) {
+	const kind = resolveLineKind(line);
+	const resolved = {
+		...line,
+		type: kind,
+		transparency: mapStated(line.transparency, (transparency) => transparency) ?? 0,
+		width: mapStated(line.width, (width) => width) ?? 1,
+		dashType: line.dashType || "solid"
+	};
+	if (kind === "solid") resolved.color = namedColorOr(line.color, DEF_SHAPE_LINE_COLOR, colorLabel);
+	return resolved;
+}
+/**
+* Map a friendly `LineCap` value to the OOXML `cap` attribute value (`flat`/`sq`/`rnd`).
+* @param {LineCap} [lineCap] - line cap style (defaults to `flat`)
+* @returns {string} value for the `cap` attribute on `<a:ln>`
+*/
+function createLineCap(lineCap) {
+	if (!lineCap) return "flat";
+	const token = lineCapToken(lineCap);
+	if (token === void 0) throw new InvalidOptionError("line/invalid-cap", `Invalid line cap: ${String(lineCap)}`);
+	return token;
+}
+/**
+* Emit the paint child of an `<a:ln>` stroke.
+*
+* `<a:ln>` takes almost the same fill group as a shape interior, so a stroke can be a gradient
+* or a pattern as well as a solid color. Which one is asked for is {@link resolveLineKind}'s
+* answer, shared with the shape interior — the stroke side used to infer `gradient` from its
+* sub-object while the interior inferred nothing, so the same `{ gradient }` spelling painted a
+* gradient outline and a black fill. "Almost" is the picture fill: `EG_LineFillProperties` has
+* no `a:blipFill`, and `resolveLineKind` is where that is refused.
+*
+* Returns '' when the line names no paint at all ({@link fillNamesPaint}), so the caller emits
+* no fill child and the stroke inherits its color from the theme or placeholder. `type: 'none'`
+* is not that case: it is an explicit *no stroke*, and a shape authored with it grew the theme's
+* border back when the two were conflated.
+* @param {ShapeLineProps} line line options
+* @returns XML string
+*/
+function genXmlLineFill(line) {
+	if (!fillNamesPaint(line)) return "";
+	resolveLineKind(line);
+	return genXmlColorSelection(line);
+}
+/**
+* The `<a:ln>`-shaped stroke a {@link BorderProps} paints, in the one place every border
+* emitter now derives it.
+*
+* Four builders used to turn a `BorderProps` into a line element, each with its own
+* defaults, and the differences between them were only visible by reading all four: a
+* chart data point's outline, a chart-area or plot-area border, the `<c:spPr>` line the
+* plot and chart space share, and a table cell's six edges. They agree on the shape —
+* `w` and `cap` on the element, a solid paint from `color`/`transparency`, then an
+* optional dash and whatever the schema allows after it — and disagree only on what fills
+* those slots. Those are this function's parameters, so each caller is now a named
+* argument set rather than a re-derivation.
+*
+* Two things are deliberately *not* parameters. A stroke that paints nothing is spelled
+* differently by each caller (a bare `<a:ln><a:noFill/></a:ln>` for a chart, an
+* attribute-carrying `w="0"` rule for a table cell, and nothing at all for a data point,
+* whose caller decides whether to emit it) — see {@link noStrokeLine} for the shared
+* spelling of the first. And the colour default is taken on `||`, not `??`, so an empty
+* `color` reads as *unstated* rather than reaching the colour validator as a bad value:
+* three of the four callers used to hand `''` straight through, which warns
+* `color/invalid-value` and paints `DEF_FONT_COLOR` — black — instead of the border
+* default they had named a line earlier. The chart-border builder already read it this way,
+* and `dataBorder` is the only one of the other three a caller can actually reach with an
+* empty string; the rest resolve their colour in the definition step first.
+*
+* @param name - the element's qualified name (`a:ln`, or `a:lnL`/`a:lnTlToBr`/… for a table cell)
+* @param border - the caller's border properties
+* @param spec - `defaultWidth`/`defaultColor` are used when the border states neither;
+*   `cap` is the `cap` attribute value, already resolved; `extraAttrs` follows it in
+*   document order; `dash` is the `a:prstDash/@val` to write, or `null` to omit the
+*   element; `tail` is the already-built children that follow the dash (`a:round`, and a
+*   table cell's head/tail ends), in schema order.
+* @returns the border element XML
+*/
+function borderLine(name, border, spec) {
+	return el(name, {
+		w: lineWidthToEmu(resolveBorderWidth(border, spec.defaultWidth), "border.width"),
+		cap: spec.cap,
+		...spec.extraAttrs
+	}, [
+		genXmlColorSelection(solidPaint(namedColorOr(border.color, spec.defaultColor, "border.color"), border.transparency)),
+		...spec.dash === null ? [] : [voidEl("a:prstDash", { val: spec.dash })],
+		...spec.tail
+	].map(raw));
+}
+/**
+* The `<a:ln>` that paints no stroke at all: an explicit `<a:noFill/>` on a bare element.
+*
+* This is the chart side's spelling of "no line" and is a different statement from a
+* {@link borderLine} whose paint is absent — an omitted `a:ln` inherits the theme's
+* `a:lnRef`, where this overrides it. A table cell spells the same intent with the
+* attributes still on the element and `w="0"`, which is why that one is not this.
+* @returns the `<a:ln><a:noFill/></a:ln>` element XML
+*/
+function noStrokeLine() {
+	return el("a:ln", null, raw(voidEl("a:noFill")));
+}
+//#endregion
+//#region src/gen/define/hyperlinks.ts
+/**
+* The relationship record one hyperlink serializes to.
+*
+* `data` distinguishes the two targets a hyperlink rel can have — `'slide'` for an internal
+* slide-to-slide link, `'dummy'` for an external URL — and `Target` is stored RAW, because
+* every emitter escapes it on the way out (see the note on `SlideRel.Target`).
+*
+* Four sites built this record by hand: the two below, `addImage`'s own hyperlink, and the
+* notes-part rels, which allocate from their own reserved id space and so cannot share the
+* registration below but can share this.
+* @param rId - the relationship id already allocated for this hyperlink
+* @param hyperlink - the caller's hyperlink; only `url`/`slide` are read
+*/
+function hyperlinkRel(rId, hyperlink) {
+	return {
+		type: "hyperlink",
+		data: hyperlink.url ? "dummy" : "slide",
+		rId,
+		Target: hyperlink.url ? hyperlink.url : String(hyperlink.slide)
+	};
+}
+/**
+* Refuse a hyperlink the writer cannot express, the same way wherever one is authored.
+*
+* A hyperlink names exactly one destination: a `url`, a `slide`, or a slide-show `action`. The image
+* definer and the run emitter each checked their own subset, and the shape path checked nothing. An
+* image refused an action-only link that a shape accepted, and nothing refused `url` together with
+* `slide`: that wrote two `<a:hlinkClick>` into one `<p:cNvPr>`, which allows one, over a slide-typed
+* relationship whose target was built from the URL.
+*
+* A `slide` has to be a 1-based slide number. `-1` and `1.5` were written as the targets
+* `slide-1.xml` and `slide1.5.xml`, parts no deck has. Whether the numbered slide exists is only
+* known once the deck is complete, so a number past the last slide is refused when the deck is
+* written (`requireSlideLinksInDeck`).
+* @param hyperlink - the caller's `hyperlink` option
+* @param call - the method or option the link was authored through, opening the message
+*/
+function validateHyperlink(hyperlink, call) {
+	if (typeof hyperlink !== "object" || hyperlink === null) throw new InvalidOptionError("hyperlink/not-an-object", `${call}: \`hyperlink\` option should be an object. Ex: \`hyperlink:{url:'https://github.com'}\``);
+	const { url, slide, action } = hyperlink;
+	if (url && slide) throw new InvalidOptionError("hyperlink/conflicting-targets", `${call}: \`hyperlink\` takes one destination but states both \`url\` and \`slide\`.`);
+	if (slide != null && !(Number.isInteger(slide) && slide >= 1)) throw new InvalidOptionError("hyperlink/invalid-slide", `${call}: \`hyperlink.slide\` is a 1-based slide number, got ${typeof slide === "string" ? JSON.stringify(slide) : String(slide)}.`);
+	if (!url && !slide && !action) throw new InvalidOptionError("hyperlink/missing-target", `${call}: \`hyperlink\` requires either \`url\`, \`slide\`, or \`action\``);
+}
+/**
+* Mint a fresh rel id for `hyperlink`, register it on `target`, and stamp the id back onto
+* the hyperlink so the emitter can write `r:id`.
+*
+* The id comes from {@link getNewRelId}, which skips every id already held on the slide.
+* `addImage` used to increment the image's own id instead, which is how an SVG picture — a
+* pair that already consumes two ids — ended up sharing the second of them with its
+* hyperlink and emitting a duplicate `Relationship Id`.
+* @returns the allocated relationship id
+*/
+function registerHyperlinkRel(target, hyperlink) {
+	const relId = getNewRelId(target);
+	target._rels.push(hyperlinkRel(relId, hyperlink));
+	hyperlink._rId = relId;
+	return relId;
+}
+/** The objects one level of a text or table-cell tree holds: a table row is itself an array. */
+function hyperlinkTreeLevel(text) {
+	if (typeof text === "string" || typeof text === "number") return [];
+	if (Array.isArray(text)) return text;
+	return typeof text === "object" ? [text] : [];
+}
+/**
+* Parses text/text-objects from `addText()` and `addTable()` methods; creates 'hyperlink'-type Slide Rels for each hyperlink found
+*
+* Every link in the tree is checked before any is registered, by the same rules as an image's. A
+* refused link on a second run used to throw after the first run's relationship was already on
+* the slide, left pointing at a shape that was never added.
+* @param {PresSlideInternal} target - slide object that any hyperlinks will be be added to
+* @param {number | string | TextProps | TextProps[] | TableCellInternal[][]} text - text to parse
+* @param call - the method the objects were authored through, for a refused hyperlink's message
+*/
+function createHyperlinkRels(target, text, call = "addText") {
+	validateHyperlinkTree(text, call);
+	registerHyperlinkTree(target, text);
+}
+/** Refuse the first hyperlink in the tree the writer cannot express, before anything is registered. */
+function validateHyperlinkTree(text, call) {
+	for (const item of hyperlinkTreeLevel(text)) {
+		if (Array.isArray(item)) {
+			validateHyperlinkTree(item, call);
+			continue;
+		}
+		if (item.options?.hyperlink) validateHyperlink(item.options.hyperlink, call);
+		if (Array.isArray(item.text)) validateHyperlinkTree(item.text, call);
+	}
+}
+/** Register a relationship for every hyperlink in an already-validated tree. */
+function registerHyperlinkTree(target, tree) {
+	hyperlinkTreeLevel(tree).forEach((text) => {
+		if (Array.isArray(text)) {
+			registerHyperlinkTree(target, text);
+			return;
+		}
+		if (Array.isArray(text.text)) registerHyperlinkTree(target, text.text);
+		const options = text.options;
+		const hyperlink = options?.hyperlink;
+		if (!options || !hyperlink) return;
+		if (!hyperlink._rId) {
+			if (hyperlink.url || hyperlink.slide) registerHyperlinkRel(target, hyperlink);
+			return;
+		}
+		const hyperlinkRelId = hyperlink._rId;
+		const wanted = hyperlinkRel(hyperlinkRelId, hyperlink);
+		if (target._rels.some((rel) => rel.rId === hyperlinkRelId && rel.type === wanted.type && rel.data === wanted.data && rel.Target === wanted.Target)) return;
+		if (!heldRelIds(target).has(hyperlinkRelId)) target._rels.push(wanted);
+		else {
+			const own = { ...hyperlink };
+			delete own._rId;
+			options.hyperlink = own;
+			registerHyperlinkRel(target, own);
+		}
+	});
+}
+//#endregion
+//#region src/gen/drawingml/bullet.ts
+/** A bullet `characterCode`: four hex digits naming a code point. */
+const CHARACTER_CODE = /^[0-9A-Fa-f]{4}$/;
+/** `ST_TextBulletStartAtNum`'s range. */
+const START_AT_MIN = 1;
+const START_AT_MAX = 32767;
+/**
+* `<a:buChar>`: the glyph a caller's `characterCode` names, or `glyph` when the caller named none.
+*
+* A template rather than `voidEl`, because `char` carries a pre-escaped numeric character reference
+* (`&#x2022;`, see `BulletType`) and the builder would escape its `&` a second time, rendering the
+* reference as literal text. That is why the code is checked before it gets near the attribute: one
+* that is not four hex digits warns and becomes {@link BulletType.DEFAULT}.
+* @param characterCode - the caller's `characterCode`, if they gave one
+* @param glyph - the glyph when they gave none; a library constant, already safe in an attribute
+* @param label - the option the code came from, opening the warning
+*/
+function buCharEl(characterCode, glyph, label) {
+	let char = glyph;
+	if (characterCode) {
+		if (CHARACTER_CODE.test(characterCode)) char = `&#x${characterCode};`;
+		else {
+			warn("bullet/invalid-character-code", `${label} \`characterCode\` should be a 4-digit unicode character (ex: 22AB), got ${JSON.stringify(characterCode)}; using the default bullet`);
+			char = "&#x2022;";
+		}
+	}
+	return `<a:buChar char="${char}"/>`;
+}
+/**
+* `<a:buAutoNum>` for an auto-number scheme, starting at `startAt` when one is stated.
+*
+* `type` is required on the element, so a scheme `ST_TextAutonumberScheme` does not have warns and
+* the list counts in `arabicPeriod`, the scheme a numbered bullet takes when none is stated.
+* `startAt` is an `ST_TextBulletStartAtNum`, a whole number from 1 to 32767: a fractional one rounds,
+* one outside the range clamps with a warning, and one that is not a number throws.
+* @param type - the `ST_TextAutonumberScheme` token
+* @param startAt - the number the list starts at; omitted from the element when `undefined`
+* @param label - the option the value came from, opening the warning
+*/
+function buAutoNumEl(type, startAt, label) {
+	return voidEl("a:buAutoNum", {
+		type: checkEnumOrWarn(type, TEXT_AUTONUM_SCHEMES, "bullet/invalid-number-type", `${label} \`numberType\``) ?? "arabicPeriod",
+		startAt: startAt === void 0 ? null : clampRangedInput(Math.round(startAt), START_AT_MIN, START_AT_MAX, "bullet/start-at-out-of-range", `${label} \`numberStartAt\``, "bullet/start-at-not-a-number")
+	});
+}
+//#endregion
+//#region src/gen/drawingml/clamp.ts
+/**
+* ts-pptx: DrawingML value clamps
+*
+* Clamp font/character/line spacing values into their ST_* schema ranges and convert to the
+* units the attributes expect — hundredths of a point for most of them, thousandths of a
+* percent for the one measure the caller states as a multiple rather than a size.
+* Out-of-range values make PowerPoint report the package as needing repair.
+*/
+/**
+* Clamp a caller's value into its schema range, warn once if it did not already fit, and convert
+* it to the attribute's unit.
+*
+* The range is applied in the caller's own unit, through {@link clampRangedInput}: `Infinity`
+* clamps to the bound and warns, and `NaN` throws naming the option. Converting first left a
+* non-finite value to whatever the converter did with it, so `fontSize: Infinity` threw without
+* naming the option while `transparency: Infinity` clamped and warned. A value within half a unit
+* of a bound that used to round into range now also warns, though it writes the same bytes.
+*
+* The measures below differ only in the fields of {@link ClampSpec}. The warning is deduped on its
+* code plus its message, so the wording is part of the contract, not decoration.
+*/
+function clampWithWarn(value, spec, label = spec.label) {
+	const clamped = clampRangedInput(value, spec.min / spec.perUnit, spec.max / spec.perUnit, spec.code, label, spec.nonFiniteCode, {
+		once: true,
+		range: spec.range
+	});
+	return spec.convert(clamped);
+}
+const FONT_SIZE = {
+	code: "font/size-out-of-range",
+	nonFiniteCode: "coord/non-finite",
+	label: "fontSize",
+	range: `1-${MAX_FONT_SIZE_PT}pt`,
+	convert: ptToHundredths,
+	perUnit: 100,
+	min: 100,
+	max: MAX_FONT_SIZE_PT * 100
+};
+const CHAR_SPACING = {
+	code: "text/char-spacing-out-of-range",
+	nonFiniteCode: "coord/non-finite",
+	label: "charSpacing",
+	range: "-4000..4000pt",
+	convert: ptToHundredths,
+	perUnit: 100,
+	min: -4e5,
+	max: 4e5
+};
+const PARA_MARGIN = {
+	code: "text/paragraph-margin-out-of-range",
+	nonFiniteCode: "coord/non-finite",
+	label: "paraMarginLeft",
+	range: "0-4032pt",
+	convert: ptsToEmuLenient,
+	perUnit: EMU_PER_POINT,
+	min: 0,
+	max: 51206400
+};
+const PARA_INDENT = {
+	code: "text/paragraph-indent-out-of-range",
+	nonFiniteCode: "coord/non-finite",
+	label: "paraIndent",
+	range: "-4032..4032pt",
+	convert: ptsToEmuLenient,
+	perUnit: EMU_PER_POINT,
+	min: -51206400,
+	max: 51206400
+};
+/** {@link PARA_MARGIN}, for the callers that state the measure in inches. 4032pt is 56in. */
+const PARA_MARGIN_INCHES = {
+	...PARA_MARGIN,
+	range: "0-56in",
+	convert: inch2Emu,
+	perUnit: EMU_PER_INCH
+};
+/** {@link PARA_INDENT}, for the callers that state the measure in inches. */
+const PARA_INDENT_INCHES = {
+	...PARA_INDENT,
+	range: "-56..56in",
+	convert: inch2Emu,
+	perUnit: EMU_PER_INCH
+};
+const LINE_SPACING = {
+	code: "text/line-spacing-out-of-range",
+	nonFiniteCode: "coord/non-finite",
+	label: "lineSpacing",
+	range: "0-1584pt",
+	convert: ptToHundredths,
+	perUnit: 100,
+	min: 0,
+	max: 158400
+};
+const LINE_SPACING_MULTIPLE = {
+	code: "text/line-spacing-out-of-range",
+	nonFiniteCode: "percent/non-finite",
+	label: "lineSpacingMultiple",
+	range: "0-132",
+	convert: (multiple) => Math.round(multiple * PERCENT_SCALE),
+	perUnit: PERCENT_SCALE,
+	min: 0,
+	max: 132e5
+};
+/**
+* Clamp a font size (points) into ST_TextFontSize (1-4000pt) and return it in
+* hundredths of a point for the `sz` attribute. Out-of-range sizes make
+* PowerPoint report the package as needing repair (e.g. `sz` > 400000 or < 100).
+*
+* Every `sz` in the package goes through here, and the nine options that reach it are spelled
+* nine different ways -- `fontSize` on a run, `legendFontSize` and six siblings on a chart.
+* `label` is what the warning quotes back, so a caller who set `catAxisLabelFontSize` is not
+* told about `fontSize`.
+* @param fontSizePts - the caller's size in points
+* @param label - option name as the caller spells it
+*/
+function clampFontSizeSz(fontSizePts, label) {
+	return clampWithWarn(fontSizePts, FONT_SIZE, label);
+}
+/** Clamp character spacing (points) into ST_TextPoint (-4000..4000pt); returns hundredths for the `spc` attribute. */
+function clampCharSpacingSpc(charSpacingPts) {
+	return clampWithWarn(charSpacingPts, CHAR_SPACING);
+}
+/**
+* Clamp a paragraph's left margin (points) into ST_TextMargin (0..4032pt, i.e. 0..51206400 EMU);
+* returns EMU for `a:pPr/@marL`. The type is unsigned — a negative margin is not a narrower one,
+* it is a value PowerPoint reports as needing repair.
+*/
+function clampParaMarginEmu(marginPts) {
+	return clampWithWarn(marginPts, PARA_MARGIN);
+}
+/**
+* Clamp a first-line indent (points) into ST_TextIndent (-4032..4032pt); returns EMU for
+* `a:pPr/@indent`. Unlike the margin this one is signed: a negative indent is the hanging
+* indent every bulleted paragraph uses.
+*/
+function clampParaIndentEmu(indentPts) {
+	return clampWithWarn(indentPts, PARA_INDENT);
+}
+/**
+* Clamp a left margin the caller stated in INCHES into ST_TextMargin, returning EMU for
+* `a:pPr/@marL`.
+*
+* A master's text styles state their measures in inches where a run's paragraph properties
+* state them in points. The schema bound is the same one either way, so the two spellings
+* share {@link PARA_MARGIN}'s range and differ only in the unit the warning quotes back.
+* @param marginInches - the caller's margin in inches
+* @param label - option name as the caller spells it
+*/
+function clampParaMarginInchesEmu(marginInches, label) {
+	return clampWithWarn(marginInches, PARA_MARGIN_INCHES, label);
+}
+/**
+* Clamp a first-line indent the caller stated in INCHES into ST_TextIndent, returning EMU for
+* `a:pPr/@indent`. The inch-stated half of {@link clampParaIndentEmu}; see
+* {@link clampParaMarginInchesEmu} for why there are two.
+* @param indentInches - the caller's indent in inches
+* @param label - option name as the caller spells it
+*/
+function clampParaIndentInchesEmu(indentInches, label) {
+	return clampWithWarn(indentInches, PARA_INDENT_INCHES, label);
+}
+/** Clamp line spacing (points) into ST_TextSpacingPoint (0..1584pt); returns hundredths for `<a:spcPts val>`. */
+function clampLineSpacingPts(lineSpacingPts) {
+	return clampWithWarn(lineSpacingPts, LINE_SPACING);
+}
+/**
+* Clamp a line-spacing multiple into ST_TextSpacingPercentOrPercentString (0..13200000, i.e. a
+* multiple of 0..132); returns thousandths of a percent for `<a:spcPct val>`. The bound is the
+* schema's, not the `0.0-9.99` the option documents: a multiple of 12 is unusual, not invalid,
+* and only the values PowerPoint reports as needing repair are worth moving.
+*/
+function clampLineSpacingMultiplePct(multiple) {
+	return clampWithWarn(multiple, LINE_SPACING_MULTIPLE);
+}
+//#endregion
+//#region src/gen/drawingml/math.ts
+/**
+* ts-pptx: DrawingML native equations (OMML)
+*
+* Wrap raw OMML markup into the `<a14:m>` marker PowerPoint uses for editable
+* equations — as a standalone display paragraph (`genXmlMathParagraph`) or as an
+* inline run that flows between the surrounding `<a:r>` runs (`genXmlInlineMath`).
+*/
+/** The `<a14:m>` marker, carrying both namespace declarations so the supplied OMML needs none. */
+function a14Math(mathXml) {
+	return el("a14:m", {
+		"xmlns:a14": OOXML_NS.a14,
+		"xmlns:m": OOXML_NS.m
+	}, raw(mathXml));
+}
+/**
+* Build a native-equation paragraph (`<a:p>`) from raw OMML.
+*
+* PowerPoint stores an editable equation inside a text body as an `<a14:m>` marker wrapping
+* `<m:oMathPara><m:oMath>…`. We declare both the `a14` (drawing-2010) and `m` (math) namespaces
+* on the `<a14:m>` element so the supplied OMML needs no namespace declarations of its own, then
+* accept three input shapes: a full `<m:oMathPara>`, a full `<m:oMath>`, or the inner OMML
+* (children of `<m:oMath>`). A trailing `<a:endParaRPr>` matches what PowerPoint authors.
+*
+* @param {string} omml - raw OMML markup for the equation
+* @returns {string} an `<a:p>` math paragraph
+*/
+function genXmlMathParagraph(omml) {
+	const trimmed = (omml || "").trim();
+	const paraPr = el("m:oMathParaPr", null, raw(voidEl("m:jc", { "m:val": "centerGroup" })));
+	return el("a:p", null, [a14Math(trimmed.startsWith("<m:oMathPara") ? trimmed : trimmed.includes("<m:oMath") ? el("m:oMathPara", null, [paraPr, trimmed].map(raw)) : el("m:oMathPara", null, [paraPr, el("m:oMath", null, raw(trimmed))].map(raw))), voidEl("a:endParaRPr", { lang: "en-US" })].map(raw));
+}
+/**
+* Build an INLINE native-equation run (dn-inline-math) from raw OMML.
+*
+* Unlike the display form ({@link genXmlMathParagraph}), an inline equation is *not* its own
+* paragraph: PowerPoint authors an `<a14:m>` marker wrapping a bare `<m:oMath>` (no `<m:oMathPara>`,
+* no `<m:oMathParaPr>`/`<m:jc>`) that flows between the surrounding `<a:r>` runs in one `<a:p>` —
+* pinned by the `math-omml-inline.pptx` oracle. The `mc:AlternateContent` envelope stays at the
+* shape level (see `objectHasMath`), so nothing wraps the run itself. We declare the `a14` and `m`
+* namespaces on the `<a14:m>` element so the supplied OMML needs none of its own, and accept the
+* same three input shapes as the display helper: a full `<m:oMathPara>` (its inner `<m:oMath>` is
+* unwrapped, since a paragraph block cannot flow inline), a full `<m:oMath>`, or the inner OMML.
+*
+* @param {string} omml - raw OMML markup for the equation
+* @returns {string} an `<a14:m>` inline equation run
+*/
+function genXmlInlineMath(omml) {
+	const trimmed = (omml || "").trim();
+	const oMathMatch = trimmed.match(/<m:oMath[\s>][\s\S]*<\/m:oMath>/);
+	return a14Math(oMathMatch ? oMathMatch[0] : el("m:oMath", null, raw(trimmed)));
+}
+//#endregion
+//#region src/gen/drawingml/text-run.ts
+/**
+* `<a:extLst>` marking a hyperlink whose color should follow the text color rather than the
+* theme's hyperlink color. The leading spaces are byte-significant: this block was authored as
+* indented string concatenation and that indentation reaches the file, so it is described here
+* with `openPrefix`/`closePrefix` rather than being tidied away.
+*/
+const HLINK_TEXT_COLOR_EXT = el("a:extLst", null, raw(el("a:ext", { uri: "{A12FA001-AC4F-418D-AE19-62706E023703}" }, raw(voidEl("ahyp:hlinkClr", {
+	"xmlns:ahyp": "http://schemas.microsoft.com/office/drawing/2018/hyperlinkcolor",
+	val: "tx"
+}, { openPrefix: "   " })), {
+	openPrefix: "  ",
+	closePrefix: "  "
+})), {
+	openPrefix: " ",
+	closePrefix: " "
+});
+/**
+* Whether a `bullet` value makes the paragraph DRAW a bullet (a glyph, a number or a picture).
+*
+* Two call sites downstream of the emitter act on "this paragraph has a bullet" rather than on
+* "this paragraph says something about its bullet", and both were plain truthiness tests until
+* `'inherit'` — a truthy string that draws nothing — joined the union. Left as truthiness they
+* would have broken the line grouping (every run starting its own paragraph) and eaten a real
+* leading `•` from text that emits no `a:buChar` to duplicate it.
+* @param {TextPropsOptions['bullet']} bullet - the option value
+* @return {boolean} true when bullet markup is emitted
+*/
+function emitsBulletMarkup(bullet) {
+	return !!bullet && bullet !== "inherit";
+}
+/**
+* One paragraph margin attribute's value in EMU, or `null` when the attribute is not written.
+*
+* Three inputs, because the option has three states and so does the attribute: an explicit
+* number is clamped and written, `'inherit'` writes nothing, and an absent option falls back to
+* whatever the `bullet` arm decided — which is also `null` for `bullet: 'inherit'`, the one arm
+* that states nothing on its own.
+*
+* BOTH arms go through the clamp. The fallback used to be returned verbatim on the grounds that
+* the emitter computed it, but the emitter computes it from the caller's `bullet.indent` and
+* `indentLevel`, so it is caller input one multiplication later — and it reached `@marL` at
+* ~6700x the `ST_TextMargin` ceiling. The fallback arrives in EMU rather than points because the
+* bullet arms do their arithmetic there; the round trip through the clamp's own unit is exact
+* for any value in range, so a paragraph that was already legal emits the same bytes.
+* @param {number|'inherit'|undefined} option - `paraMarginLeft` / `paraIndent` as given
+* @param {number|null} fallbackEmu - the bullet arm's default, `null` for no attribute
+* @param {Function} clamp - the attribute's ST_* range clamp (points in, EMU out)
+* @return {number|null} the EMU value to write, or null to omit the attribute
+*/
+function resolveParagraphMargin(option, fallbackEmu, clamp) {
+	if (option === "inherit") return null;
+	if (option !== void 0) return clamp(option);
+	return fallbackEmu === null ? null : clamp(fallbackEmu / EMU_PER_POINT);
+}
+/**
+* The paragraph's outline level, or `0` when the caller named none or named one `a:p/@lvl`
+* cannot hold.
+*
+* Resolved once because the level is read twice — for the attribute, and as the multiplier on
+* the bullet arms' default `@marL`. Validating it for one use and multiplying a margin by it in
+* the other is how `indentLevel: 1e6` reached `marL="342900342900"` under a warning that said
+* the value was being ignored.
+* @param {number|undefined} level - `indentLevel` as given
+* @return {number} a level `ST_TextIndentLevelType` accepts
+*/
+function resolveIndentLevel(level) {
+	if (!level) return 0;
+	if (Number.isInteger(level) && level > 0 && level <= 8) return level;
+	warn("text/invalid-indent-level", `indentLevel ${String(level)} must be a whole number from 0 to 8; ignoring it.`);
+	return 0;
+}
+/**
+* The `@marL` a bulleted paragraph defaults to: the bullet's own hang, plus one more of it for
+* every outline level. Two arms of the bullet chain write it — `bullet: {…}` and `bullet: true`
+* — and each had the expression spelled out, which is how one of them would have been fixed
+* and the other left behind.
+* @param {number} bulletMarLEmu - the hang one level is worth, in EMU
+* @param {number} indentLevel - the resolved outline level
+* @return {number} `a:pPr/@marL` in EMU
+*/
+function bulletHangMarL(bulletMarLEmu, indentLevel) {
+	return bulletMarLEmu + bulletMarLEmu * indentLevel;
+}
+/**
+* Generate XML Paragraph Properties
+* @param {SlideObject|TextProps} textObj - text object
+* @param {boolean} isDefault - array of default relations
+* @return {string} XML
+*/
+function genXmlParagraphProperties(textObj, isDefault) {
+	const opts = textObj.options ?? {};
+	let strXmlBullet = "";
+	let strXmlBulletColor = "";
+	let strXmlLnSpc = "";
+	let strXmlParaSpc = "";
+	let strXmlTabStops = "";
+	const tag = isDefault ? "a:lvl1pPr" : "a:pPr";
+	let bulletMarL = ptsToEmuLenient(27);
+	let defaultMarL = null;
+	let defaultIndent = null;
+	let indentBeforeMarL = false;
+	let paragraphPropXml = `<${tag}${opts.rtlMode ? " rtl=\"1\" " : ""}`;
+	{
+		const algn = opts.align ? textAlignToken(opts.align) : void 0;
+		if (algn) paragraphPropXml += ` algn="${algn}"`;
+		const spacingPts = mapStated(opts.lineSpacing, clampLineSpacingPts);
+		const spacingPct = spacingPts === void 0 ? mapStated(opts.lineSpacingMultiple, clampLineSpacingMultiplePct) : void 0;
+		if (spacingPts !== void 0) strXmlLnSpc = el("a:lnSpc", null, raw(voidEl("a:spcPts", { val: spacingPts })));
+		else if (spacingPct !== void 0) strXmlLnSpc = el("a:lnSpc", null, raw(voidEl("a:spcPct", { val: spacingPct })));
+		const indentLevel = resolveIndentLevel(opts.indentLevel);
+		if (indentLevel) paragraphPropXml += ` lvl="${indentLevel}"`;
+		if (emitsParagraphSpacing(opts.paraSpaceBefore)) strXmlParaSpc += el("a:spcBef", null, raw(voidEl("a:spcPts", { val: ptToHundredths(opts.paraSpaceBefore) })));
+		if (emitsParagraphSpacing(opts.paraSpaceAfter)) strXmlParaSpc += el("a:spcAft", null, raw(voidEl("a:spcPts", { val: ptToHundredths(opts.paraSpaceAfter) })));
+		if (typeof opts.bullet === "object") {
+			const bullet = opts.bullet;
+			const bulletImage = bullet.image;
+			const isPictureBullet = !!(bulletImage && (bulletImage.path || bulletImage.data));
+			if (opts.bullet?.indent) bulletMarL = ptsToEmuLenient(opts.bullet.indent);
+			defaultMarL = bulletHangMarL(bulletMarL, indentLevel);
+			defaultIndent = -bulletMarL;
+			rejectEmptyColor(opts.bullet.color, "bullet.color");
+			if (opts.bullet.color && !isPictureBullet) strXmlBulletColor = el("a:buClr", null, raw(createColorElement(opts.bullet.color)));
+			const bulletSizePct = opts.bullet.size === void 0 ? void 0 : percentToFixedPercent(opts.bullet.size, "bullet/size-out-of-range", "bullet.size", 25, 400);
+			const strXmlBulletSize = bulletSizePct === void 0 ? "" : voidEl("a:buSzPct", { val: bulletSizePct });
+			const strXmlBulletFont = opts.bullet.fontFace ? voidEl("a:buFont", { typeface: opts.bullet.fontFace }) : "";
+			if (isPictureBullet) {
+				if (bullet._rId) {
+					const svgExt = bullet._rIdSvg ? el("a:extLst", null, raw(el("a:ext", { uri: "{96DAC541-7B7A-43D3-8B79-37D633B846F1}" }, raw(voidEl("asvg:svgBlip", {
+						"xmlns:asvg": OOXML_NS.asvg,
+						"r:embed": `rId${bullet._rIdSvg}`
+					}))))) : "";
+					strXmlBullet = strXmlBulletSize + el("a:buBlip", null, raw(elOrVoid("a:blip", { "r:embed": `rId${bullet._rId}` }, svgExt)));
+				} else {
+					warn("bullet/image-embed-failed", "picture `bullet.image` could not be embedded; using a default bullet glyph");
+					strXmlBullet = strXmlBulletSize + strXmlBulletFont + buCharEl(void 0, "&#x2022;", "bullet");
+				}
+			} else if (opts.bullet.type && opts.bullet.type.toString().toLowerCase() === "number") strXmlBullet = strXmlBulletSize + (strXmlBulletFont || voidEl("a:buFont", { typeface: "+mj-lt" })) + buAutoNumEl(opts.bullet.numberType || "arabicPeriod", opts.bullet.numberStartAt || 1, "bullet");
+			else strXmlBullet = strXmlBulletSize + strXmlBulletFont + buCharEl(opts.bullet.characterCode, "&#x2022;", "bullet");
+		} else if (opts.bullet === "inherit") {} else if (opts.bullet) {
+			defaultMarL = bulletHangMarL(bulletMarL, indentLevel);
+			defaultIndent = -bulletMarL;
+			strXmlBullet = buCharEl(void 0, "&#x2022;", "bullet");
+		} else if (!opts.bullet) {
+			defaultMarL = 0;
+			defaultIndent = 0;
+			indentBeforeMarL = true;
+			strXmlBullet = voidEl("a:buNone");
+		}
+		const marLEmu = resolveParagraphMargin(opts.paraMarginLeft, defaultMarL, clampParaMarginEmu);
+		const indentEmu = resolveParagraphMargin(opts.paraIndent, defaultIndent, clampParaIndentEmu);
+		const marLAttr = marLEmu === null ? "" : ` marL="${marLEmu}"`;
+		const indentAttr = indentEmu === null ? "" : ` indent="${indentEmu}"`;
+		paragraphPropXml += indentBeforeMarL ? indentAttr + marLAttr : marLAttr + indentAttr;
+		if (opts.tabStops && Array.isArray(opts.tabStops)) strXmlTabStops = el("a:tabLst", null, raw(opts.tabStops.map((stop) => voidEl("a:tab", {
+			pos: inch2Emu(mapStated(stop.position, (position) => position) ?? 1),
+			algn: stop.alignment ? checkEnumOrWarn(stop.alignment, TEXT_TAB_ALIGN_TYPES, "text/invalid-tab-alignment", "tab stop `alignment`") : "l"
+		})).join("")));
+		paragraphPropXml += ">" + strXmlLnSpc + strXmlParaSpc + strXmlBulletColor + strXmlBullet + strXmlTabStops;
+		if (isDefault) paragraphPropXml += genXmlTextRunProperties(opts, true);
+		paragraphPropXml += "</" + tag + ">";
+	}
+	return paragraphPropXml;
+}
+/**
+* Generate XML Text Run Properties (`a:rPr`)
+* @param {ObjectOptions|TextPropsOptions} opts - text options
+* @param {boolean} isDefault - whether these are the default text run properties
+* @return {string} XML
+*/
+function genXmlTextRunProperties(opts, isDefault) {
+	let runProps = "";
+	const runPropsTag = isDefault ? "a:defRPr" : "a:rPr";
+	const underline = typeof opts.underline === "object" && opts.underline?.style ? checkEnumOrWarn(opts.underline.style, TEXT_UNDERLINE_TYPES, "text/invalid-underline", "text `underline.style`") : opts.hyperlink ? "sng" : null;
+	const baseline = opts.baseline ? Math.round(opts.baseline * 50) : opts.subscript ? -4e4 : opts.superscript ? 3e4 : null;
+	const attrs = {
+		lang: opts.lang ? opts.lang : "en-US",
+		altLang: opts.lang ? "en-US" : null,
+		sz: mapStated(opts.fontSize, clampFontSizeSz) ?? null,
+		b: xsdBoolIfTrue(opts?.bold),
+		i: xsdBoolIfTrue(opts?.italic),
+		strike: opts?.strike ? typeof opts.strike === "string" ? checkEnumOrWarn(opts.strike, TEXT_STRIKE_TYPES, "text/invalid-strike", "text `strike`") : "sngStrike" : null,
+		cap: opts?.caps ? checkEnumOrWarn(opts.caps, TEXT_CAPS_TYPES, "text/invalid-caps", "text `caps`") : null,
+		u: underline,
+		baseline,
+		spc: mapStated(opts.charSpacing, clampCharSpacingSpc) ?? null,
+		kern: opts.charSpacing ? 0 : null,
+		dirty: "0"
+	};
+	const hasShadow = !!opts.shadow && opts.shadow.type !== "none";
+	if (opts.color || opts.fontFace || opts.outline || opts.glow || hasShadow || typeof opts.underline === "object" && opts.underline.color) {
+		if (opts.outline && typeof opts.outline === "object") runProps += el("a:ln", { w: lineWidthToEmu(mapStated(opts.outline.size, (size) => size) ?? .75, "outline.size") }, raw(genXmlColorSelection(namedColorOr(opts.outline.color, "FFFFFF", "outline.color"))));
+		rejectEmptyColor(opts.color, "color");
+		if (opts.color) runProps += genXmlColorSelection(solidPaint(opts.color, opts.transparency));
+		if (opts.glow || hasShadow) runProps += el("a:effectLst", null, [opts.glow ? raw(createGlowElement(opts.glow, DEF_TEXT_GLOW)) : null, hasShadow ? raw(createShadowElement(opts.shadow, DEF_TEXT_SHADOW)) : null]);
+		rejectEmptyColor(opts.highlight, "highlight");
+		if (opts.highlight) runProps += el("a:highlight", null, raw(createColorElement(opts.highlight)));
+		if (typeof opts.underline === "object") rejectEmptyColor(opts.underline.color, "underline.color");
+		if (typeof opts.underline === "object" && opts.underline.color) runProps += el("a:uFill", null, raw(genXmlColorSelection(opts.underline.color)));
+		if (opts.fontFace) {
+			runProps += voidEl("a:latin", {
+				typeface: opts.fontFace,
+				pitchFamily: "34",
+				charset: "0"
+			});
+			if (opts.fontFaceEA) runProps += voidEl("a:ea", { typeface: opts.fontFaceEA });
+			runProps += voidEl("a:cs", { typeface: opts.fontFace });
+		}
+	}
+	if (opts.hyperlink) {
+		try {
+			validateHyperlink(opts.hyperlink, "text");
+		} catch (err) {
+			throw new InternalError("hyperlink/not-validated", `A run reached the emitter with a hyperlink its definer should have refused: ${err.message}`);
+		}
+		if (opts.hyperlink.url || opts.hyperlink.slide) {
+			const link = opts.hyperlink;
+			const linkAttrs = opts.hyperlink.url ? {
+				"r:id": `rId${link._rId}`,
+				invalidUrl: "",
+				action: "",
+				tgtFrame: "",
+				tooltip: opts.hyperlink.tooltip ?? "",
+				history: "1",
+				highlightClick: "0",
+				endSnd: "0"
+			} : {
+				"r:id": `rId${link._rId}`,
+				action: "ppaction://hlinksldjump",
+				tooltip: opts.hyperlink.tooltip ?? ""
+			};
+			runProps += elOrVoid("a:hlinkClick", linkAttrs, opts.color ? HLINK_TEXT_COLOR_EXT : "");
+		}
+	}
+	return el(runPropsTag, attrs, raw(runProps));
+}
+/**
+* Build textBody text runs [`<a:r></a:r>`] for paragraphs [`<a:p>`]
+* @param {TextProps} textObj - Text object
+* @return {string} XML string
+*/
+function genXmlTextRun(textObj) {
+	if (textObj.text === void 0 || textObj.text === null) return "";
+	return el("a:r", null, [raw(genXmlTextRunProperties(textObj.options ?? {}, false)), raw(el("a:t", null, String(textObj.text)))]);
+}
+/**
+* Builds `<a:normAutofit>` with explicit fontScale/lnSpcReduction for "shrink text on overflow"
+* @param {TextFitShrinkProps} fit - shrink fit options
+* @return {string} XML string (`<a:normAutofit .../>`)
+* @see ECMA-376 CT_TextNormAutofit (attributes in 1000ths of a percent)
+*/
+function genXmlNormAutofit(fit) {
+	const pct = (val, name) => val === void 0 || val === null ? null : percentToFixedPercent(val, "text/invalid-fit-percentage", `fit.${name}`);
+	return voidEl("a:normAutofit", {
+		fontScale: pct(fit.fontScale, "fontScale"),
+		lnSpcReduction: pct(fit.lnSpcReduction, "lnSpcReduction")
+	});
+}
+/**
+* Group the flat run list into paragraphs (lines): a new line starts on a display-math run,
+* an alignment change, or a bullet, and closes after a breakLine. Returns the per-line run arrays.
+*/
+function groupRunsIntoLines(arrTextObjects, opts) {
+	const arrLines = [];
+	let arrTexts = [];
+	arrTextObjects.forEach((textObj, idx) => {
+		if (textObj.math && !textObj.inline) {
+			if (arrTexts.length > 0) {
+				arrLines.push(arrTexts);
+				arrTexts = [];
+			}
+			arrLines.push([textObj]);
+			return;
+		}
+		if (arrTexts.length > 0 && (textObj.options.align || opts.align)) {
+			if (textObj.options.align !== arrTextObjects[idx - 1]?.options.align) {
+				arrLines.push(arrTexts);
+				arrTexts = [];
+			}
+		} else if (arrTexts.length > 0 && emitsBulletMarkup(textObj.options.bullet)) {
+			arrLines.push(arrTexts);
+			arrTexts = [];
+			textObj.options.breakLine = false;
+		}
+		arrTexts.push(textObj);
+		if (arrTexts.length > 0 && textObj.options.breakLine) {
+			if (idx + 1 < arrTextObjects.length) {
+				arrLines.push(arrTexts);
+				arrTexts = [];
+			}
+		}
+		if (idx + 1 === arrTextObjects.length) arrLines.push(arrTexts);
+	});
+	return arrLines;
+}
+/**
+* The options a run inherits from its shape — exactly the keys `genXmlTextRunProperties`
+* reads off a run's bag, in the order it reads them.
+*
+* This used to be `Object.entries(opts)` filtered on `!textOptions[key]`, which had two
+* consequences beyond copying keys (`x`, `w`, …) that mean nothing to an `<a:rPr>`. The
+* falsy test made an explicit `false`/`0` on the run indistinguishable from silence, so
+* `addText([{ text: 'a', options: { bold: false } }], { bold: true })` emitted `b="1"` and a
+* run's `transparency: 0` took the shape's; and because it copied *whatever* was on the
+* shape's bag, the font-size write-back in step E below leaked one run's size onto every
+* later run. Naming the keys fixes the first and confines the second.
+*
+* Paragraph-level options (`align`, `lineSpacing`, the two margins, …) are inherited
+* separately in step B, before the `<a:pPr>` is emitted; they are deliberately not here.
+*/
+const RUN_INHERITABLE_OPTIONS = [
+	"lang",
+	"fontSize",
+	"bold",
+	"italic",
+	"strike",
+	"caps",
+	"underline",
+	"baseline",
+	"subscript",
+	"superscript",
+	"charSpacing",
+	"color",
+	"transparency",
+	"fontFace",
+	"fontFaceEA",
+	"outline",
+	"glow",
+	"highlight",
+	"hyperlink"
+];
+/**
+* The paragraph-level options a run inherits from its shape -- exactly the keys
+* `genXmlParagraphProperties` reads off a run's bag, which is where the `<a:pPr>` for the
+* paragraph that run opens is built.
+*
+* A list rather than eight hand-written `setOrClear` calls because it has to be *complete*:
+* `rtlMode` and `tabStops` were read there and inherited nowhere, and reached a run only because
+* the bare-string form of `addText` handed the shape's own options object to its run. Once that
+* stopped, an unlisted key stopped arriving at all -- so the list is now the statement of what a
+* paragraph inherits, and the place to add to when `genXmlParagraphProperties` learns a new key.
+*
+* `bullet` is deliberately not here. It is inherited in STEP 4 of `text-body.ts`, onto the FIRST
+* text object only, before the line split copies each line's bag -- a rule about which paragraph
+* gets the shape's bullet, not about whether a paragraph inherits at all.
+*/
+const PARAGRAPH_INHERITABLE_OPTIONS = ["rtlMode", "tabStops"];
+/**
+* Of those, the ones whose zero is a value the caller meant. `paraMarginLeft: 0` is flush with the
+* frame (and the override that suppresses a bullet's hanging indent) and `paraIndent: 0` likewise,
+* where `align`/`lineSpacing`/`indentLevel`/the paragraph spacings have no zero worth stating. A
+* falsy test would silently swap a run's explicit `0` for the shape's value.
+*/
+const PARAGRAPH_ZERO_IS_STATED = ["paraMarginLeft", "paraIndent"];
+/**
+* Whether a value is a number the caller stated and no clamp can use -- `NaN` or `±Infinity`.
+*
+* It exists to keep such a value out of {@link PARAGRAPH_FALSY_IS_UNSTATED}'s inheritance. `NaN`
+* is falsy, so it read as "the caller said nothing" and took the shape's value instead of reaching
+* the clamp, whose `nonFiniteCode` is the whole point of naming a bad input rather than guessing at
+* one.
+*/
+const isUnusableNumber = (value) => typeof value === "number" && !Number.isFinite(value);
+/**
+* Whether `<a:spcBef>`/`<a:spcAft>` is written for a paragraph spacing value.
+*
+* `0` and a negative value are dropped, as they always were: the schema's `a:spcPts@val` is
+* unsigned, and `0` is how a caller says "none". A non-finite value is *not* dropped -- it is
+* passed on so {@link ptToHundredths} refuses it by name, which is what the old guard's comment
+* claimed to do while `NaN &&` short-circuited it into silence.
+*/
+const emitsParagraphSpacing = (value) => value !== void 0 && (isUnusableNumber(value) || value > 0);
+const PARAGRAPH_FALSY_IS_UNSTATED = [
+	"align",
+	"lineSpacing",
+	"lineSpacingMultiple",
+	"indentLevel",
+	"paraSpaceBefore",
+	"paraSpaceAfter"
+];
+/**
+* Render each grouped line to an `<a:p>` paragraph: paragraph props, inherited run options,
+* text runs (and inline/display math), and the closing endParaRPr.
+*/
+function renderTextParagraphsXml(arrLines, slideObj, opts) {
+	let strSlideXml = "";
+	arrLines.forEach((line) => {
+		const firstRun = line[0];
+		if (line.length === 1 && firstRun?.math && !firstRun.inline) {
+			strSlideXml += genXmlMathParagraph(firstRun.math);
+			return;
+		}
+		let reqsClosingFontSize = false;
+		let closingFontSize = opts.fontSize;
+		let paraXml = "";
+		let paragraphPropEmitted = false;
+		line.forEach((textObj, idx) => {
+			textObj.options._lineIdx = idx;
+			if (idx > 0 && textObj.options.softBreakBefore) paraXml += voidEl("a:br");
+			const paraOptions = textObj.options;
+			const paraShapeOptions = opts;
+			for (const key of PARAGRAPH_FALSY_IS_UNSTATED) {
+				const stated = paraOptions[key];
+				setOrClear(paraOptions, key, isUnusableNumber(stated) ? stated : stated || paraShapeOptions[key]);
+			}
+			for (const key of [...PARAGRAPH_ZERO_IS_STATED, ...PARAGRAPH_INHERITABLE_OPTIONS]) setOrClear(paraOptions, key, paraOptions[key] ?? paraShapeOptions[key]);
+			if (!paragraphPropEmitted) {
+				paragraphPropEmitted = true;
+				paraXml += genXmlParagraphProperties(textObj, false).replace("<a:pPr></a:pPr>", "");
+			}
+			const textOptions = textObj.options;
+			const shapeOptions = opts;
+			RUN_INHERITABLE_OPTIONS.forEach((key) => {
+				if (key === "color" && textObj.options.hyperlink) return;
+				setOrClear(textOptions, key, textOptions[key] ?? shapeOptions[key]);
+			});
+			let _textRunObj = textObj;
+			if (idx === 0 && emitsBulletMarkup(line[0]?.options.bullet) && typeof textObj.text === "string") {
+				const _stripped = textObj.text.replace(/^[\u2022\u25E6\u25AA\u25AB\u25CF\u25CB\u2023\u2043\u2219]\s*/, "");
+				if (_stripped !== textObj.text) _textRunObj = {
+					text: _stripped,
+					options: textObj.options
+				};
+			}
+			const isEmptyBreakArtifact = _textRunObj.text === "" && line.length > 1;
+			if (_textRunObj.math) paraXml += genXmlInlineMath(_textRunObj.math);
+			else if (!isEmptyBreakArtifact) paraXml += genXmlTextRun(_textRunObj);
+			if (!textObj.text && opts.fontSize || textObj.options.fontSize) {
+				reqsClosingFontSize = true;
+				closingFontSize = closingFontSize ?? textObj.options.fontSize;
+			}
+		});
+		const sizedAttrs = () => ({
+			lang: opts.lang || "en-US",
+			sz: closingFontSize ? clampFontSizeSz(closingFontSize) : null,
+			dirty: "0"
+		});
+		if (slideObj._type === "tablecell" && (closingFontSize || opts.fontFace)) {
+			if (opts.fontFace) paraXml += el("a:endParaRPr", sizedAttrs(), [
+				raw(voidEl("a:latin", {
+					typeface: opts.fontFace,
+					charset: "0"
+				})),
+				opts.fontFaceEA ? raw(voidEl("a:ea", { typeface: opts.fontFaceEA })) : null,
+				raw(voidEl("a:cs", { typeface: opts.fontFace }))
+			]);
+			else paraXml += voidEl("a:endParaRPr", sizedAttrs());
+		} else if (reqsClosingFontSize) paraXml += voidEl("a:endParaRPr", sizedAttrs());
+		else paraXml += voidEl("a:endParaRPr", {
+			lang: opts.lang || "en-US",
+			dirty: "0"
+		});
+		strSlideXml += el("a:p", null, raw(paraXml));
+	});
+	return strSlideXml;
+}
+//#endregion
+//#region src/gen/drawingml/geometry.ts
+/**
+* ts-pptx: DrawingML geometry
+*
+* Emit `<a:prstGeom>` (preset shapes with their adjustment guides) and
+* `<a:custGeom>` (freeform paths built from the `points` DSL). Shared by the
+* shape and image code paths so path/preset emission stays in one place.
+*/
+/**
+* Several `<a:custGeom>` children are emitted as `<a:avLst />` — with a space before the
+* slash — where the rest of the tree writes `<a:avLst/>`. Byte-significant, so it stays.
+*/
+const SPACE_BEFORE_SLASH = { closePrefix: " " };
+/**
+* The path nodes inside `<a:cubicBezTo>`/`<a:quadBezTo>` are newline-and-tab separated,
+* an artifact of the source indentation these were originally written with. It reaches
+* the emitted bytes, so it is described here rather than left to leak from a literal.
+*/
+const BEZ_INDENT = {
+	childPrefix: "\n					",
+	closePrefix: "\n					"
+};
+/**
+* The 17 guide-formula operations ECMA-376 Part 1 §20.1.9.11 (`a:gd/@fmla`) defines.
+* The set is closed — the spec enumerates every operation with its arity — so an
+* unrecognized leading token is always a caller mistake, not a newer dialect.
+*
+* Only the operation is checked. The operands are deliberately left uninterpreted:
+* they may be literals, adjust names, or other guide names resolved in declaration
+* order, and validating them would mean re-implementing the geometry engine — which
+* is exactly what this passthrough exists to avoid.
+*/
+const GEOM_GUIDE_OPS = /* @__PURE__ */ new Set([
+	"*/",
+	"+-",
+	"+/",
+	"?:",
+	"abs",
+	"at2",
+	"cat2",
+	"cos",
+	"max",
+	"min",
+	"mod",
+	"pin",
+	"sat2",
+	"sin",
+	"sqrt",
+	"tan",
+	"val"
+]);
+/**
+* Emit an `<a:prstGeom>` for a preset shape, including any adjust values (`<a:avLst>`).
+* Shared by the shape and image code paths so that geometry + adjust handling stays in one place.
+* @param {string} shapeName - preset geometry name (e.g. `rect`, `ellipse`, `roundRect`, `hexagon`)
+* @param {ObjectOptions} options - object options carrying optional `rectRadius`/`angleRange`/`arcThicknessRatio`
+* @param {number} cx - shape width (EMU), used to scale `rectRadius`
+* @param {number} cy - shape height (EMU), used to scale `rectRadius`
+* @return {string} `<a:prstGeom>` XML
+*/
+const RECT_RADIUS_ADJ1_SHAPES = /* @__PURE__ */ new Set(["round2SameRect", "round2DiagRect"]);
+/**
+* Reject a preset PowerPoint can't parse.
+*
+* An unknown `prst` value corrupts the package: PowerPoint shows the "needs
+* repair" dialog and drops the shape. So this is the safety net for every
+* `prstGeom` emitter — `addShape`, and the `shape` option on `addText`/`addImage`
+* — and it is also called during `addShape` normalization, so the caller sees
+* their own typo at the API boundary rather than at serialization time.
+* @param {string} shapeName - the resolved preset geometry name
+* @throws {InvalidOptionError} `shape/unknown-preset` when the name is not a preset
+*/
+function assertKnownPreset(shapeName) {
+	if (VALID_SHAPE_PRESETS.has(shapeName)) return;
+	throw new InvalidOptionError("shape/unknown-preset", `Invalid shape "${String(shapeName)}"! Use a value from \`ShapeType.*\` (e.g. \`ShapeType.rect\`). PowerPoint can't render unknown preset geometries and will drop the shape during repair.`);
+}
+/**
+* A finite adjustment guide is emitted verbatim, however far outside the preset's own handle range
+* it falls. This is a decision, not an omission.
+*
+* Each preset defines its handle's bounds in its own geometry definition (the `ahXY`/`ahPolar`
+* min/max formulas of [MS-ODRAWXML]'s preset shape definitions), and nothing in ECMA-376 states
+* them -- `a:gd/@fmla` is `xsd:string`, so no schema check can see an out-of-range value either.
+* Clamping would therefore mean carrying an invented table, and many of those bounds are formulas
+* over the shape's own width and height rather than constants.
+*
+* It would also buy nothing. Desktop PowerPoint stores an out-of-range guide verbatim -- it neither
+* repairs the package on open nor rewrites the value on re-save -- and the preset's own formula
+* pins it at render time, so the shape it paints is the shape it paints at the bound. Verified by
+* exporting the slides to PNG and comparing pixels: `roundRect` at `adj` 50000, 60000 and 266667
+* rasterize identically, as do `blockArc` at `adj3` 50000 and 5000000, while two *in*-range values
+* of the same guide do not. `pnpm run test:com` carries that as a standing case.
+*
+* What IS refused is a guide PowerPoint cannot evaluate at all: a non-finite value, and a
+* `rectRadius` with no side to divide by. Those write `val NaN` / `val Infinity`, which is a token
+* outside the formula grammar rather than a number outside a range.
+*/
+function genXmlPresetGeom(shapeName, options, cx, cy) {
+	assertKnownPreset(shapeName);
+	let avLst = "";
+	const emittedAdjNames = /* @__PURE__ */ new Set();
+	const emitGuide = (name, fmlaVal) => {
+		avLst += voidEl("a:gd", {
+			name,
+			fmla: `val ${fmlaVal}`
+		});
+		emittedAdjNames.add(name);
+	};
+	if (options.rectRadius !== void 0) {
+		const shorterSideEmu = Math.min(cx, cy);
+		if (!Number.isFinite(options.rectRadius)) warn("geometry/invalid-shape-adjust", `rectRadius ${String(options.rectRadius)} is not a finite number and was ignored.`);
+		else if (!(shorterSideEmu > 0)) warn("shape/degenerate-extent", `rectRadius cannot be resolved against a ${cx}x${cy} EMU extent (the shape has no size on one axis); the preset's own corner radius is kept.`);
+		else {
+			const adjVal = Math.round(options.rectRadius * EMU_PER_INCH * PERCENT_SCALE / shorterSideEmu);
+			if (RECT_RADIUS_ADJ1_SHAPES.has(shapeName)) {
+				emitGuide("adj1", adjVal);
+				emitGuide("adj2", 0);
+			} else emitGuide("adj", adjVal);
+		}
+	} else if (options.angleRange !== void 0) {
+		for (let i = 0; i < 2; i++) {
+			const angle = options.angleRange[i] ?? 0;
+			emitGuide(`adj${i + 1}`, convertAngleUnits(angle, `angleRange[${i}]`));
+		}
+		if (options.arcThicknessRatio !== void 0) {
+			if (Number.isFinite(options.arcThicknessRatio)) emitGuide("adj3", Math.round(options.arcThicknessRatio * (PERCENT_SCALE / 2)));
+			else warn("geometry/invalid-shape-adjust", `arcThicknessRatio ${String(options.arcThicknessRatio)} is not a finite number and was ignored.`);
+		}
+	}
+	if (options.shapeAdjust) (Array.isArray(options.shapeAdjust) ? options.shapeAdjust : [options.shapeAdjust]).forEach((adj) => {
+		if (!adj || typeof adj.name !== "string" || adj.name.length === 0 || typeof adj.value !== "number" || !Number.isFinite(adj.value)) {
+			warn("geometry/invalid-shape-adjust", `shapeAdjust entry ${JSON.stringify(adj)} is invalid (needs { name:string, value:number }) and was ignored.`);
+			return;
+		}
+		if (emittedAdjNames.has(adj.name)) {
+			warn("geometry/shape-adjust-overridden", `shapeAdjust "${adj.name}" was ignored because rectRadius/angleRange already set that handle.`);
+			return;
+		}
+		emitGuide(adj.name, Math.round(adj.value * PERCENT_SCALE));
+	});
+	return el("a:prstGeom", { prst: shapeName }, raw(el("a:avLst", null, raw(avLst))));
+}
+/**
+* Narrow a freeform path node to an arc segment. An arc is the one curve node with no end
+* point, so it must be split off before the remaining curve nodes can be read for x/y.
+*/
+function isArcPoint(point) {
+	return "curve" in point && point.curve.type === "arc";
+}
+/**
+* Emit an `<a:custGeom>` for a freeform path built from `points`, plus any caller-supplied
+* connection sites (`connectionSites` → `<a:cxnLst>`), adjust handles (`adjustHandles` →
+* `<a:ahLst>`) and guide formulas (`guides` → `<a:gdLst>`) that make the shape connectable and
+* editable. Shared by the shape and image code paths so that path emission stays in one place.
+* Points and connection-site/handle positions are authored in the object's own inch/EMU space
+* (0..cx, 0..cy) — not slide-relative and not normalized; a bare non-`Coord` string is passed
+* through verbatim as a guide-name reference (matching `ST_AdjCoordinate`'s number-or-name union).
+* @param {ObjectOptions} options - object options carrying `points`/`guides`/`connectionSites`/`adjustHandles`
+* @param {number} cx - object width (EMU), used as the path viewport width
+* @param {number} cy - object height (EMU), used as the path viewport height
+* @param {PresLayout} layout - presentation layout used to resolve point coordinates to EMU
+* @return {string} `<a:custGeom>` XML
+*/
+function genXmlCustGeom(options, cx, cy, layout) {
+	const points = options.points;
+	/**
+	* Resolve an `ST_AdjCoordinate` value: a number / unit-suffixed `Coord` → EMU (like `points`),
+	* but a token that starts with a letter/underscore is a guide-name reference emitted verbatim.
+	* `undefined` → `undefined`, so `el`/`voidEl` drop the (optional) attribute entirely.
+	*/
+	const adjCoord = (v, axis) => {
+		if (v === void 0 || v === null) return void 0;
+		if (typeof v === "string" && /^[A-Za-z_]/.test(v.trim())) return v;
+		return String(getSmartParseNumber(v, axis, layout));
+	};
+	/** `<a:pt>` in the object's own EMU space. */
+	const pt = (x, y) => voidEl("a:pt", {
+		x: getSmartParseNumber(x, "X", layout),
+		y: getSmartParseNumber(y, "Y", layout)
+	}, SPACE_BEFORE_SLASH);
+	const nodes = [];
+	points?.forEach((point, i) => {
+		if (isArcPoint(point)) {
+			if ("x" in point || "y" in point) warn("geometry/arc-node-point-ignored", "freeform arc node: x/y are ignored — an arcTo end point is computed from stAng/swAng and the radii.");
+			nodes.push(voidEl("a:arcTo", {
+				hR: getSmartParseNumber(point.curve.hR, "Y", layout),
+				wR: getSmartParseNumber(point.curve.wR, "X", layout),
+				stAng: convertArcAngle(point.curve.stAng, "stAng"),
+				swAng: convertArcAngle(point.curve.swAng, "swAng")
+			}, SPACE_BEFORE_SLASH));
+		} else if ("curve" in point) switch (point.curve.type) {
+			case "cubic":
+				nodes.push(el("a:cubicBezTo", null, [
+					pt(point.curve.x1, point.curve.y1),
+					pt(point.curve.x2, point.curve.y2),
+					pt(point.x, point.y)
+				].map(raw), BEZ_INDENT));
+				break;
+			case "quadratic": nodes.push(el("a:quadBezTo", null, [pt(point.curve.x1, point.curve.y1), pt(point.x, point.y)].map(raw), BEZ_INDENT));
+		}
+		else if ("close" in point) nodes.push(voidEl("a:close", null, SPACE_BEFORE_SLASH));
+		else if (point.moveTo || i === 0) nodes.push(el("a:moveTo", null, raw(pt(point.x, point.y))));
+		else nodes.push(el("a:lnTo", null, raw(pt(point.x, point.y))));
+	});
+	let gdLst = el("a:gdLst");
+	if (options.guides?.length) {
+		const guideEls = [];
+		options.guides.forEach((g) => {
+			if (!g || typeof g.name !== "string" || g.name.length === 0 || typeof g.formula !== "string" || g.formula.length === 0) {
+				warn("geometry/invalid-guide", `guide entry ${JSON.stringify(g)} is invalid (needs { name:string, formula:string }) and was ignored.`);
+				return;
+			}
+			const op = g.formula.trimStart().split(/\s+/)[0] ?? "";
+			if (!GEOM_GUIDE_OPS.has(op)) {
+				warn("geometry/unknown-guide-operation", `guide "${g.name}" formula ${JSON.stringify(g.formula)} starts with an unknown operation "${op}" (expected one of ${[...GEOM_GUIDE_OPS].join(" ")}) and was ignored.`);
+				return;
+			}
+			guideEls.push(voidEl("a:gd", {
+				name: g.name,
+				fmla: g.formula
+			}));
+		});
+		if (guideEls.length) gdLst = el("a:gdLst", null, guideEls.map(raw));
+	}
+	let cxnLst = el("a:cxnLst");
+	if (options.connectionSites?.length) {
+		const cxnEls = [];
+		options.connectionSites.forEach((c) => {
+			if (!c || typeof c.ang !== "number" || !Number.isFinite(c.ang)) {
+				warn("geometry/invalid-connection-site", `connectionSite entry ${JSON.stringify(c)} is invalid (needs a finite \`ang\` in degrees) and was ignored.`);
+				return;
+			}
+			const pos = voidEl("a:pos", {
+				x: adjCoord(c.x, "X"),
+				y: adjCoord(c.y, "Y")
+			});
+			cxnEls.push(el("a:cxn", { ang: convertAngleUnits(c.ang, "connectionSite ang") }, raw(pos)));
+		});
+		if (cxnEls.length) cxnLst = el("a:cxnLst", null, cxnEls.map(raw));
+	}
+	let ahLst = voidEl("a:ahLst", null, SPACE_BEFORE_SLASH);
+	if (options.adjustHandles?.length) ahLst = el("a:ahLst", null, options.adjustHandles.map((h) => {
+		const pos = raw(voidEl("a:pos", {
+			x: adjCoord(h.x, "X"),
+			y: adjCoord(h.y, "Y")
+		}));
+		if ("gdRefR" in h || "minR" in h || "maxR" in h || "gdRefAng" in h || "minAng" in h || "maxAng" in h) return el("a:ahPolar", {
+			gdRefR: h.gdRefR,
+			minR: adjCoord(h.minR, "X"),
+			maxR: adjCoord(h.maxR, "X"),
+			gdRefAng: h.gdRefAng,
+			minAng: h.minAng == null ? void 0 : convertAngleUnits(h.minAng, "adjustHandle minAng"),
+			maxAng: h.maxAng == null ? void 0 : convertAngleUnits(h.maxAng, "adjustHandle maxAng")
+		}, pos);
+		const xy = h;
+		return el("a:ahXY", {
+			gdRefX: xy.gdRefX,
+			minX: adjCoord(xy.minX, "X"),
+			maxX: adjCoord(xy.maxX, "X"),
+			gdRefY: xy.gdRefY,
+			minY: adjCoord(xy.minY, "Y"),
+			maxY: adjCoord(xy.maxY, "Y")
+		}, pos);
+	}).map(raw));
+	return el("a:custGeom", null, [
+		voidEl("a:avLst", null, SPACE_BEFORE_SLASH),
+		gdLst,
+		ahLst,
+		cxnLst,
+		voidEl("a:rect", {
+			l: "l",
+			t: "t",
+			r: "r",
+			b: "b"
+		}, SPACE_BEFORE_SLASH),
+		el("a:pathLst", null, raw(el("a:path", {
+			w: cx,
+			h: cy
+		}, nodes.map(raw))))
+	].map(raw));
+}
+/**
+* `<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>` — the unadjusted rectangle every emitter
+* that draws a plain box writes, seven of them by hand.
+*
+* `fmt` carries the caller's `openPrefix`, because indentation before this element is
+* byte-significant on two of those paths.
+*/
+function prstGeomRect(fmt) {
+	return el("a:prstGeom", { prst: "rect" }, raw(voidEl("a:avLst")), fmt);
+}
+//#endregion
+//#region src/gen/slide/objects/shared.ts
+/**
+* The `<p:cNvPr>` every shape renderer writes: self-closing for most shape kinds, paired around a
+* hyperlink or media-action child for the others.
+*
+* Both `name` and `descr` are escaped by the element builder and nowhere before it: a slide object
+* stores its `objectName` as the caller wrote it, so lookups by name and `slide.objects` compare and
+* report the caller's own spelling. Each caller used to append its own `/>` or `>`, child and close
+* tag to an open tag this module returned.
+* @param id - the shape's `<p:cNvPr>` id, unique slide-wide
+* @param name - the object's `objectName`, raw
+* @param descr - alt text, raw
+* @param children - already-serialized children; absent means self-closing, `''` means paired and empty
+* @param fmt - byte-significant whitespace around the element
+*/
+function cNvPrEl(id, name, descr, children, fmt) {
+	const attrs = {
+		id,
+		name: name ?? "",
+		descr
+	};
+	return children === void 0 ? voidEl("p:cNvPr", attrs, fmt) : el("p:cNvPr", attrs, raw(children), fmt);
+}
+/**
+* The `<a:hlinkClick>` child of a shape's `<p:cNvPr>`: a URL link, a jump to another slide, or a
+* slide-show action. Shared by the text and image renderers, which emitted identical copies.
+*
+* `<p:cNvPr>` holds at most one, so one destination is written, in that order of precedence. The
+* three used to be concatenated, which put two in one element for a link stating both `url` and
+* `slide`; `validateHyperlink` now refuses that link before it gets here.
+*
+* NOTE: the tooltip is passed through UNESCAPED and escaped once by the element builder. Escaping
+* it here as well would emit `&amp;amp;` for a tooltip containing `&`.
+* @param link - the shape's hyperlink, if any
+* @returns zero or one `<a:hlinkClick>` element
+*/
+function cNvPrHyperlink(link) {
+	if (!link) return "";
+	const tooltip = link.tooltip ?? "";
+	if (link.url) return voidEl("a:hlinkClick", {
+		"r:id": `rId${link._rId}`,
+		tooltip
+	});
+	if (link.slide) return voidEl("a:hlinkClick", {
+		"r:id": `rId${link._rId}`,
+		tooltip,
+		action: "ppaction://hlinksldjump"
+	});
+	if (link.action) return voidEl("a:hlinkClick", {
+		"r:id": "",
+		tooltip,
+		action: `ppaction://hlinkshowjump?jump=${link.action}`
+	});
+	return "";
+}
+/**
+* A shape outline: `<a:ln>` with its fill, dash pattern and arrow ends.
+*
+* The text, connector and image renderers each carried a byte-identical copy of this block; they
+* now share one. Attribute and child order are byte-significant and preserved as written.
+*
+* FUTURE: arrow-size support via the `w`/`len` attrs on headEnd/tailEnd
+* (e.g. `<a:headEnd type="arrow" w="lg" len="lg"/>`; each is 'sm'|'med'|'lg', a 3x3 grid)
+* @param ln - the shape's line properties
+* @returns the `<a:ln>` element
+*/
+function genXmlShapeLine(ln) {
+	return el("a:ln", {
+		w: mapStated(ln.width, (width) => lineWidthToEmu(width, "line: width")) ?? null,
+		cap: ln.cap ? createLineCap(ln.cap) : null
+	}, [
+		raw(genXmlLineFill(ln)),
+		ln.dashType ? raw(voidEl("a:prstDash", { val: resolveDash(ln.dashType, "solid", "line: dashType") })) : null,
+		raw(lineEndEl("a:headEnd", ln.beginArrowType, "line: beginArrowType")),
+		raw(lineEndEl("a:tailEnd", ln.endArrowType, "line: endArrowType"))
+	]);
+}
+/**
+* An `<a:off>`/`<a:ext>` transform, under whichever wrapper the context calls for: `p:xfrm` on a
+* `<p:graphicFrame>`, `a:xfrm` inside a `<p:spPr>`. Fourteen sites across the shape, chart,
+* connector, image, media, notes-master, text and zoom emitters wrote the same six-line pair;
+* `attrs` is what the last of them needed (a shape's `rot`/`flipH`/`flipV` ride on the `a:xfrm`
+* itself, not on its children).
+* @param tag - `p:xfrm` or `a:xfrm`
+* @param frame - the box, in EMU
+* @param attrs - attributes on the transform element itself, e.g. rotation and flips
+* @param fmt - byte-significant layout, where the caller's part indents
+*/
+function xfrmEl(tag, frame, attrs = null, fmt) {
+	return el(tag, attrs, [raw(voidEl("a:off", {
+		x: frame.x,
+		y: frame.y
+	})), raw(voidEl("a:ext", {
+		cx: frame.cx,
+		cy: frame.cy
+	}))], fmt);
+}
+/**
+* A group's `<a:xfrm>`: the box, then an IDENTITY child coordinate space (`chOff`/`chExt` equal
+* to `off`/`ext`).
+*
+* The identity is the contract `docs/groups.md` and the measured-fit solver both rest on — a
+* group never scales its children, so a grouped shape's authored size is its rendered size.
+* Three group emitters spelled the four-child block out.
+* @param frame - the box, in EMU
+* @param attrs - attributes on the `a:xfrm` itself
+*/
+function grpXfrmEl(frame, attrs = null) {
+	return el("a:xfrm", attrs, [
+		raw(voidEl("a:off", {
+			x: frame.x,
+			y: frame.y
+		})),
+		raw(voidEl("a:ext", {
+			cx: frame.cx,
+			cy: frame.cy
+		})),
+		raw(voidEl("a:chOff", {
+			x: frame.x,
+			y: frame.y
+		})),
+		raw(voidEl("a:chExt", {
+			cx: frame.cx,
+			cy: frame.cy
+		}))
+	]);
+}
+/**
+* A part's `<p:spTree>`: the implicit top-level group's non-visual properties (the reserved
+* `cNvPr id="1"`) and an identity group transform, zeroed, then the shapes.
+*
+* This is the part's built-in root group, not a user-authored `addGroup`, hence the zeroed frame.
+* Every slide, layout, master, notes slide and notes master opens its tree with exactly these
+* bytes, and the slide emitter and the notes emitter each used to write them out.
+* @param children - the shapes, already serialized, in document order
+*/
+function spTreeEl(children) {
+	return el("p:spTree", null, [
+		raw(el("p:nvGrpSpPr", null, [
+			raw(voidEl("p:cNvPr", {
+				id: 1,
+				name: ""
+			})),
+			raw(voidEl("p:cNvGrpSpPr")),
+			raw(voidEl("p:nvPr"))
+		])),
+		raw(el("p:grpSpPr", null, raw(grpXfrmEl({
+			x: 0,
+			y: 0,
+			cx: 0,
+			cy: 0
+		})))),
+		...children.map((child) => raw(child))
+	]);
+}
+/**
+* A `<p:graphicFrame>`: its non-visual properties, its transform, and the `<a:graphic>` /
+* `<a:graphicData>` envelope around a payload.
+*
+* The child order is the point. `CT_GraphicalObjectFrame` sequences
+* `nvGraphicFramePr` → `xfrm` → `graphic`, and PowerPoint reports a frame that gets it wrong as
+* a corrupt file (0x80070570) rather than as a bad element — a failure the five emitters that
+* build one (chart, table, OLE, zoom, 3D model) each had to be right about separately.
+*
+* `nvGraphicFramePr` stays the caller's to build and is *not* folded in here. The five differ in
+* every part of it — an empty `<p:cNvGraphicFramePr>` for a chart against four different
+* `<a:graphicFrameLocks>` default sets, a `<p:nvPr>` that is empty for three and carries a
+* placeholder (and, for a table, a `p14:modId` extension) for the other two — and each of those
+* differences is deliberate and documented where it is made.
+*
+* @param opts.nvGraphicFramePr - the already-serialized `<p:nvGraphicFramePr>`
+* @param opts.frame - the frame's slide-absolute box, in EMU
+* @param opts.uri - the `<a:graphicData>` payload namespace
+* @param opts.payload - the already-serialized `<a:graphicData>` content
+* @param opts.fmt - per-element byte layout; `graphicAttrs` adds attributes to `<a:graphic>`
+*   (the chart frame alone redeclares `xmlns:a` there, as PowerPoint writes it)
+*/
+function graphicFrameEl(opts) {
+	const { nvGraphicFramePr, frame, uri, payload, fmt } = opts;
+	return el("p:graphicFrame", null, [
+		raw(nvGraphicFramePr),
+		raw(xfrmEl("p:xfrm", frame, null, fmt?.xfrm)),
+		raw(el("a:graphic", fmt?.graphicAttrs ?? null, raw(el("a:graphicData", { uri }, raw(payload), fmt?.graphicData)), fmt?.graphic))
+	]);
+}
+/**
+* The `<a:picLocks>` set PowerPoint fixes on an `mc:Fallback` preview picture.
+*
+* Fixed rather than taken from the caller's `objectLock`, and that is true of every construct
+* that emits one: the fallback picture is what a consumer *without* the feature draws, while the
+* caller's locks belong on the `mc:Choice` frame — the object PowerPoint itself manipulates. The
+* two element types also accept different flags, so folding a `graphicFrameLocks` set onto a
+* `picLocks` would warn about every flag they do not share. Routed through `genXmlObjectLock` so
+* attribute order comes from `PICTURE_LOCK_ATTRS` (`gen/drawingml/locks.ts`) rather than from a literal, and a flag
+* added to the table lands in the right place.
+*
+* A 3D model spreads `noCrop` on top: it is reframed by its camera, never by cropping the cached
+* raster.
+*/
+const FALLBACK_PICTURE_LOCKS = Object.freeze({
+	noGrp: true,
+	noRot: true,
+	noChangeAspect: true,
+	noMove: true,
+	noResize: true,
+	noEditPoints: true,
+	noAdjustHandles: true,
+	noChangeArrowheads: true,
+	noChangeShapeType: true
+});
+function previewPicBody(previewRid, frame, outline = false, prefix = { ns: "p" }) {
+	const attrs = prefix.nsUri === void 0 ? null : { [`xmlns:${prefix.ns}`]: prefix.nsUri };
+	return el(`${prefix.ns}:blipFill`, attrs, [raw(voidEl("a:blip", { "r:embed": `rId${previewRid}` })), raw(STRETCH_FILL_RECT)]) + el(`${prefix.ns}:spPr`, attrs, [
+		raw(xfrmEl("a:xfrm", frame)),
+		raw(prstGeomRect()),
+		outline ? raw(el("a:ln", { w: "3175" }, raw(el("a:solidFill", null, raw(voidEl("a:prstClr", { val: "ltGray" })))))) : null
+	]);
+}
+//#endregion
+//#region src/gen/opc/part-paths.ts
+/**
+* Where the parts of a written package live.
+*
+* Every part is named at least three times: the assembler writes it, `[Content_Types].xml`
+* declares an `Override` for it, and one or more `.rels` parts target it. Each of those was
+* its own template literal in its own module, and the three spellings differ — a zip entry
+* name, a leading-slash part name, a relationship target resolved against the part that
+* states it — so nothing tied them together. A part written but not declared is a
+* PowerPoint repair, and so is a relationship pointing at a part nobody wrote.
+*
+* The canonical spelling here is the zip entry name: `ppt/slides/slide1.xml`, no leading
+* slash, which is what {@link ZipWriter.add} takes. The other two are derivations —
+* {@link overrideName} for the content-types declaration, {@link targetFromPresentation} and
+* {@link targetFromPptSubpart} for a relationship target — so a path can only be spelled once
+* and then transformed, never re-typed in a second dialect.
+*
+* Indices are 1-based throughout, matching the OPC naming rather than the arrays that drive it.
+*/
+/** `ppt/presentation.xml`, the package's root presentation part. */
+const PRESENTATION_PATH = "ppt/presentation.xml";
+/** `ppt/slideMasters/slideMaster1.xml`. Exactly one master part is written. */
+const SLIDE_MASTER_PATH = "ppt/slideMasters/slideMaster1.xml";
+/** `ppt/notesMasters/notesMaster1.xml`. Exactly one notes-master part is written. */
+const NOTES_MASTER_PATH = "ppt/notesMasters/notesMaster1.xml";
+/** The `n`-th slide part. */
+function slidePath(n) {
+	return `ppt/slides/slide${n}.xml`;
+}
+/** The `n`-th slide-layout part. */
+function slideLayoutPath(n) {
+	return `ppt/slideLayouts/slideLayout${n}.xml`;
+}
+/**
+* The `n`-th notes-slide part. One is written for every slide, empty notes included, so the
+* index is the slide's own — see the assembler, which keeps the two enumerations in step.
+*/
+function notesSlidePath(n) {
+	return `ppt/notesSlides/notesSlide${n}.xml`;
+}
+/**
+* The comment part for the `n`-th slide. Written only for slides that carry comments, so the
+* index is a slide number with gaps in it rather than a running count of comment parts.
+*/
+function commentPath(n) {
+	return `ppt/comments/comment${n}.xml`;
+}
+/** The `n`-th embedded-font part, holding one whole face's raw bytes. */
+function fontPath(n) {
+	return `ppt/fonts/font${n}.${FONT_DATA_EXTENSION}`;
+}
+/**
+* The `.rels` part that carries `path`'s relationships: `ppt/slides/_rels/slide1.xml.rels`.
+* A part with no relationships has no such part; this only says where one would go.
+*/
+function relsPath(path) {
+	const cut = path.lastIndexOf("/");
+	return `${path.slice(0, cut)}/_rels/${path.slice(cut + 1)}.rels`;
+}
+/**
+* `path` as `[Content_Types].xml` spells it in an `Override/@PartName`: the same path with the
+* leading slash ECMA-376 Part 2 requires of a part name.
+*/
+function overrideName(path) {
+	return `/${path}`;
+}
+/**
+* `path` as a relationship target stated by a part directly under `ppt/` — presentation.xml,
+* whose rels reach `slides/slide1.xml` with no traversal at all.
+*/
+function targetFromPresentation(path) {
+	return path.slice(4);
+}
+/**
+* `path` as a relationship target stated by a part one level below `ppt/` — a slide, a layout,
+* a notes slide, the master: `../slides/slide1.xml`.
+*/
+function targetFromPptSubpart(path) {
+	return `../${targetFromPresentation(path)}`;
+}
+/**
+* `path` as a relationship target stated by the part at `fromPath`, where both live one level
+* below `ppt/`.
+*
+* Two parts in the same directory name each other bare, and anything else traverses. That is
+* PowerPoint's own convention: in an authored deck a slide's rels reach another slide as
+* `slide3.xml` and its layout as `../slideLayouts/slideLayout7.xml`.
+*
+* It exists because the slide-link target used to be spelled `slide${n}.xml` unconditionally, by
+* a function that also serves layouts and the master. A relationship target resolves against the
+* part that states it, so from `ppt/slideLayouts/` that named `ppt/slideLayouts/slide1.xml` — a
+* part no package has. Deriving the target from the emitting part's own path means the question
+* is asked once, by the only code that can answer it.
+*/
+function targetBetweenPptSubparts(fromPath, path) {
+	const dir = fromPath.slice(0, fromPath.lastIndexOf("/") + 1);
+	return path.startsWith(dir) ? path.slice(dir.length) : targetFromPptSubpart(path);
+}
+//#endregion
+//#region src/gen/opc/rels.ts
+/**
+* ts-pptx: shared `Relationship` writers.
+*
+* A `.rels` part is mostly one-off entries, written where the part that needs
+* them is built. This module holds the ones **more than one part** writes, so
+* that the attribute set stays a single fact — a `Relationship` whose `Type` and
+* `TargetMode` disagree between two writers does not throw, it produces a link
+* PowerPoint silently drops.
+*/
+/**
+* One `Relationship` entry.
+*
+* Three private copies of this used to sit in `gen/opc/root-rels.ts`, `gen/pres/
+* presentation-rels.ts` and `gen/chart/embed-xlsx.ts`, identical but for whether the caller
+* passed `rId3` or `3`, with seven more written inline in `gen/slide/`. The attribute set and
+* its order are byte-significant, so one writer is the only way they stay one fact.
+*
+* `target` is passed **unescaped** — `voidEl` escapes it on the way out. `gen/slide/object.ts`
+* depends on that: it computes the escaped form separately to compare a rel against the bytes
+* already emitted, and the two escapers must not drift.
+* @param {string | number} id - the relationship id; a number gets the `rId` prefix
+* @param {string} type - the relationship type URI
+* @param {string} target - the target, unescaped (a partname, or a URL with `targetMode`)
+* @param {object} [opts] - `targetMode` for an external target; `fmt` for byte-layout prefixes
+* @returns {string} the `Relationship` element
+*/
+function relationshipEl(id, type, target, opts) {
+	return voidEl("Relationship", {
+		Id: typeof id === "number" ? `rId${id}` : id,
+		Type: type,
+		Target: target,
+		TargetMode: opts?.targetMode
+	}, opts?.fmt);
+}
+/**
+* The `<Relationships>` wrapper around already-serialized entries.
+*
+* Only the tag name and its namespace are fixed here; `fmt` is passed straight through, because
+* the six `.rels` writers each indent differently and every one of those differences is in the
+* emitted bytes. Normalizing them would be a rewrite of five parts disguised as a cleanup.
+*/
+function relationshipsEl(rels, fmt) {
+	return el("Relationships", { xmlns: PACKAGE_REL_NS }, rels.map(raw), fmt);
+}
+/**
+* A complete `.rels` part: the XML declaration, a CRLF, then {@link relationshipsEl}.
+*
+* The embedded workbook's parts are the exception and use {@link relationshipsEl} directly —
+* they follow the declaration with nothing, and two of them end with a bare newline.
+*/
+function relationshipsPart(rels, fmt) {
+	return XML_DECL + "\r\n" + relationshipsEl(rels, fmt);
+}
+/**
+* A `Relationship` to a URL outside the package: the shape of every external
+* hyperlink, whether it hangs off a slide (`gen/slide/object.ts`) or off a notes
+* slide (`gen/slide/notes.ts`). `TargetMode="External"` is what makes the target
+* a URI rather than a partname, so it is not optional.
+* @param {number} rId - the relationship id, without its `rId` prefix
+* @param {string} target - the URL, unescaped; `voidEl` escapes it for the attribute
+* @returns {string} the `Relationship` element
+*/
+function externalHyperlinkRel(rId, target) {
+	return relationshipEl(rId, HYPERLINK_REL, target, { targetMode: "External" });
+}
+//#endregion
+//#region src/gen/drawingml/list-style.ts
+/**
+* ts-pptx: the `<a:lvlNpPr>` list-style level and the theme-font `<a:defRPr>` inside it.
+*
+* A deck states its text defaults in four places — the presentation's `p:defaultTextStyle`, the
+* notesMaster's `p:notesStyle`, and the slide master's built-in and configured `p:txStyles` —
+* and all four write the same level element around the same run-property block: a `solidFill`
+* over one colour, then the `latin`/`ea`/`cs` triple pointing at one theme font family. They
+* differed in the size, in whether `b`/`i` were carried, and in whether the colour and the
+* Latin face were overridable, which is what the parameters here are.
+*/
+/**
+* The `<a:defRPr>` a list-style level carries: `attrs` (the size, and `b`/`i`/`kern` where the
+* caller states them), then the fill and the three typeface slots.
+*
+* @param font - the theme font family the three slots point at (`mj` = major/heading, `mn` = minor/body)
+* @param attrs - the run-property attributes, in emission order; `null` values are omitted
+* @param colorXml - the colour element inside `<a:solidFill>`; defaults to `<a:schemeClr val="tx1"/>`
+* @param latinXml - the `<a:latin>` element; defaults to the `font` family's own `+xx-lt` token
+*/
+function themeFontDefRPr(font, attrs, colorXml, latinXml) {
+	return el("a:defRPr", attrs, [
+		raw(el("a:solidFill", null, raw(colorXml ?? voidEl("a:schemeClr", { val: "tx1" })))),
+		raw(latinXml ?? voidEl("a:latin", { typeface: `+${font}-lt` })),
+		raw(voidEl("a:ea", { typeface: `+${font}-ea` })),
+		raw(voidEl("a:cs", { typeface: `+${font}-cs` }))
+	]);
+}
+/**
+* One `<a:lvlNpPr>`, with {@link LEVEL_PPR_TAIL} appended to the caller's attributes.
+*
+* The tail is the fixed `defTabSz`/`rtl`/`eaLnBrk`/`latinLnBrk`/`hangingPunct` run every level
+* in the deck carries; it sits last because attribute order is byte-significant.
+* @param level - the 1-based list level (`1` emits `a:lvl1pPr`)
+* @param attrs - the level's own attributes, ahead of the tail
+* @param children - the level's children, in schema order
+*/
+function lvlPPr(level, attrs, children) {
+	return el(`a:lvl${level}pPr`, {
+		...attrs,
+		...LEVEL_PPR_TAIL
+	}, children);
+}
+//#endregion
+//#region src/gen/slide/notes.ts
+/**
+* Collect the speaker-notes runs for a slide (flattened across any number of `addNotes()` calls).
+* @param {PresSlideInternal} slide - the slide object
+* @return {TextProps[]} notes text runs in document order
+*/
+function getNotesRuns(slide) {
+	const runs = [];
+	slide._slideObjects.forEach((obj) => {
+		if (obj._type === "notes" && obj.text) runs.push(...obj.text);
+	});
+	return runs;
+}
+/**
+* Resolve a slide's notes runs against the notes part's own relationship ids.
+*
+* Notes rels use their own namespace, independent of `slide._rels` (which serialize to
+* `slideN.xml.rels`). The notes part always reserves rId1=notesMaster and rId2=slide, so
+* hyperlink rels are allocated starting at rId3.
+*
+* Pure. The ids go on copies of the runs, never on the caller's run or hyperlink objects: the same
+* hyperlink object can also sit on a slide run, whose id lives in the slide's namespace, and a deck
+* can be written twice or gain notes between writes. Each notes-part writer computes this once and
+* hands the result to both the body and the rels file, which is what keeps the two in agreement.
+*
+* Only external `url` hyperlinks are supported; any other target is left off the copy, and a
+* `slide` target says so.
+* @param {PresSlideInternal} slide - the slide object
+* @return {NotesSlideContent} the notes hyperlink relationships and the runs referencing them
+*/
+function buildNotesSlideRels(slide) {
+	const NOTES_REL_RESERVED = 2;
+	const rels = [];
+	let lastRid = NOTES_REL_RESERVED;
+	return {
+		rels,
+		runs: getNotesRuns(slide).map((run) => {
+			const hyperlink = run.options?.hyperlink;
+			if (!hyperlink || !run.options) return run;
+			if (!hyperlink.url) {
+				if (hyperlink.slide) warn("notes/hyperlink-slide-unsupported", "notes hyperlinks support `url` only (ignoring `slide` target)");
+				const { hyperlink: _unsupported, ...options } = run.options;
+				return {
+					...run,
+					options
+				};
+			}
+			lastRid++;
+			rels.push(hyperlinkRel(lastRid, hyperlink));
+			const linked = {
+				...hyperlink,
+				_rId: lastRid
+			};
+			return {
+				...run,
+				options: {
+					...run.options,
+					hyperlink: linked
+				}
+			};
+		})
+	};
+}
+/**
+* Build the `<p:txBody>` paragraphs for the notes placeholder.
+* Runs are split into `<a:p>` paragraphs on newlines; each run is serialized with the standard
+* text-run generator so inline formatting and `<a:hlinkClick>` markup are emitted consistently.
+* @param {TextProps[]} runs - the notes runs, as {@link buildNotesSlideRels} resolved them
+* @return {string} XML string of `<a:p>` paragraphs
+*/
+function genXmlNotesParagraphs(runs) {
+	const paragraphs = [[]];
+	runs.forEach((run) => {
+		String(run.text ?? "").split("\n").forEach((segment, idx) => {
+			if (idx > 0) paragraphs.push([]);
+			const text = segment.replace(/\r/g, "");
+			if (text !== "") paragraphs[paragraphs.length - 1]?.push({
+				text,
+				options: run.options || {}
+			});
+		});
+	});
+	return paragraphs.map((runs) => el("a:p", null, [raw(runs.map((run) => genXmlTextRun(run)).join("")), raw(voidEl("a:endParaRPr", {
+		lang: "en-US",
+		dirty: 0
+	}))])).join("");
+}
+/**
+* PowerPoint's creation-id extension, on the `p:cSld` of both notes parts.
+*
+* The value is a fixed literal, and that is the point of naming it: it looks like data — a
+* per-deck identifier PowerPoint would vary — so left inline in two places, someone eventually
+* changes one of them. It is deliberately constant, which is what keeps the two notes parts
+* byte-identical across builds.
+*/
+const NOTES_CREATION_ID = 1024086991;
+/** The `p:extLst` carrying {@link NOTES_CREATION_ID}, identical on the notes master and notes slide. */
+function notesExtLst() {
+	return el("p:extLst", null, raw(el("p:ext", { uri: "{BB962C8B-B14F-4D97-AF65-F5344CB8AC3E}" }, raw(voidEl("p14:creationId", {
+		"xmlns:p14": OOXML_NS.p14,
+		val: NOTES_CREATION_ID
+	})))));
+}
+/**
+* Generate XML for Notes Master (notesMaster1.xml)
+* @returns {string} XML
+*/
+function makeXmlNotesMaster() {
+	const xfrmOffExt = (x, y, cx, cy) => xfrmEl("a:xfrm", {
+		x,
+		y,
+		cx,
+		cy
+	});
+	const rectGeom = prstGeomRect();
+	const spLocks = (attrs) => el("p:cNvSpPr", null, raw(voidEl("a:spLocks", attrs)));
+	const nvPr = (phAttrs) => el("p:nvPr", null, raw(voidEl("p:ph", phAttrs)));
+	const bodyPr = (attrs) => voidEl("a:bodyPr", attrs);
+	const lstStyleLvl1 = (algn) => el("a:lstStyle", null, raw(el("a:lvl1pPr", { algn }, raw(voidEl("a:defRPr", { sz: 1200 })))));
+	const emptyPara = el("a:p", null, raw(voidEl("a:endParaRPr", { lang: "en-US" })));
+	const spTree = spTreeEl([
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 2,
+					name: "Header Placeholder 1"
+				})),
+				raw(spLocks({ noGrp: 1 })),
+				raw(nvPr({
+					type: "hdr",
+					sz: "quarter"
+				}))
+			])),
+			raw(el("p:spPr", null, [raw(xfrmOffExt(0, 0, 2971800, 458788)), raw(rectGeom)])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0
+				})),
+				raw(lstStyleLvl1("l")),
+				raw(emptyPara)
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 3,
+					name: "Date Placeholder 2"
+				})),
+				raw(spLocks({ noGrp: 1 })),
+				raw(nvPr({
+					type: "dt",
+					idx: 1
+				}))
+			])),
+			raw(el("p:spPr", null, [raw(xfrmOffExt(3884613, 0, 2971800, 458788)), raw(rectGeom)])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0
+				})),
+				raw(lstStyleLvl1("r")),
+				raw(el("a:p", null, [raw(el("a:fld", {
+					id: "{5282F153-3F37-0F45-9E97-73ACFA13230C}",
+					type: "datetimeFigureOut"
+				}, [raw(voidEl("a:rPr", { lang: "en-US" })), raw(el("a:t", null, "7/23/19"))])), raw(voidEl("a:endParaRPr", { lang: "en-US" }))]))
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 4,
+					name: "Slide Image Placeholder 3"
+				})),
+				raw(spLocks({
+					noGrp: 1,
+					noRot: 1,
+					noChangeAspect: 1
+				})),
+				raw(nvPr({
+					type: "sldImg",
+					idx: 2
+				}))
+			])),
+			raw(el("p:spPr", null, [
+				raw(xfrmOffExt(685800, 1143e3, 5486400, 3086100)),
+				raw(rectGeom),
+				raw(voidEl("a:noFill")),
+				raw(el("a:ln", { w: 12700 }, raw(el("a:solidFill", null, raw(voidEl("a:prstClr", { val: "black" }))))))
+			])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0,
+					anchor: "ctr"
+				})),
+				raw(voidEl("a:lstStyle")),
+				raw(emptyPara)
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 5,
+					name: "Notes Placeholder 4"
+				})),
+				raw(spLocks({ noGrp: 1 })),
+				raw(nvPr({
+					type: "body",
+					sz: "quarter",
+					idx: 3
+				}))
+			])),
+			raw(el("p:spPr", null, [raw(xfrmOffExt(685800, 4400550, 5486400, 3600450)), raw(rectGeom)])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0
+				})),
+				raw(voidEl("a:lstStyle")),
+				raw([
+					"Click to edit Master text styles",
+					"Second level",
+					"Third level",
+					"Fourth level",
+					"Fifth level"
+				].map((text, lvl) => el("a:p", null, [raw(voidEl("a:pPr", { lvl })), raw(el("a:r", null, [raw(voidEl("a:rPr", { lang: "en-US" })), raw(el("a:t", null, text))]))])).join(""))
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 6,
+					name: "Footer Placeholder 5"
+				})),
+				raw(spLocks({ noGrp: 1 })),
+				raw(nvPr({
+					type: "ftr",
+					sz: "quarter",
+					idx: 4
+				}))
+			])),
+			raw(el("p:spPr", null, [raw(xfrmOffExt(0, 8685213, 2971800, 458787)), raw(rectGeom)])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0,
+					anchor: "b"
+				})),
+				raw(lstStyleLvl1("l")),
+				raw(emptyPara)
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 7,
+					name: "Slide Number Placeholder 6"
+				})),
+				raw(spLocks({ noGrp: 1 })),
+				raw(nvPr({
+					type: "sldNum",
+					sz: "quarter",
+					idx: 5
+				}))
+			])),
+			raw(el("p:spPr", null, [raw(xfrmOffExt(3884613, 8685213, 2971800, 458787)), raw(rectGeom)])),
+			raw(el("p:txBody", null, [
+				raw(bodyPr({
+					vert: "horz",
+					lIns: 91440,
+					tIns: 45720,
+					rIns: 91440,
+					bIns: 45720,
+					rtlCol: 0,
+					anchor: "b"
+				})),
+				raw(lstStyleLvl1("r")),
+				raw(el("a:p", null, [raw(el("a:fld", {
+					id: "{CE5E9CC1-C706-0F49-92D6-E571CC5EEA8F}",
+					type: "slidenum"
+				}, [raw(voidEl("a:rPr", { lang: "en-US" })), raw(el("a:t", null, "‹#›"))])), raw(voidEl("a:endParaRPr", { lang: "en-US" }))]))
+			]))
+		])
+	]);
+	const extLst = notesExtLst();
+	const cSld = el("p:cSld", null, [
+		raw(el("p:bg", null, raw(el("p:bgRef", { idx: 1001 }, raw(voidEl("a:schemeClr", { val: "bg1" })))))),
+		raw(spTree),
+		raw(extLst)
+	]);
+	const clrMap = voidEl("p:clrMap", DEFAULT_COLOR_MAP);
+	const notesStyleLevel = (n, marL) => lvlPPr(n, {
+		marL,
+		algn: "l"
+	}, [raw(themeFontDefRPr("mn", {
+		sz: 1200,
+		kern: 1200
+	}))]);
+	const notesStyle = el("p:notesStyle", null, raw(LEVEL_MARGINS_EMU.map((marL, i) => notesStyleLevel(i + 1, marL)).join("")));
+	return XML_DECL + "\r\n" + el("p:notesMaster", { ...PML_ROOT_NS }, [
+		raw(cSld),
+		raw(clrMap),
+		raw(notesStyle)
+	]);
+}
+/**
+* Creates Notes Slide (`ppt/notesSlides/notesSlide1.xml`)
+* @param {PresSlideInternal} slide - the slide object to transform into XML
+* @param {NotesSlideContent} notes - the slide's notes, from {@link buildNotesSlideRels}; the same
+*   value has to reach {@link makeXmlNotesSlideRel}
+* @return {string} XML
+*/
+function makeXmlNotesSlide(slide, notes) {
+	return makeXmlNotesSlideSkeleton(genXmlNotesParagraphs(notes.runs), slide._slideNum);
+}
+/**
+* The notes slide's fixed frame, with the only two slide-dependent strings passed in.
+*
+* A notes slide is the same three placeholders every time — the thumbnail (`sldImg`),
+* the notes body, and the slide-number field — so everything except the body's
+* paragraphs and the cached slide number is a constant. It is a parameter of its own
+* because the read model authors notes onto a *loaded* deck (`Slide.addNotes`), where
+* there is no `PresSlideInternal` to serialize but the part must come out identical:
+* a second private copy of this frame is exactly the drift `src/ooxml/` exists to
+* prevent (see docs/contributing/architecture.md).
+* @param {string} bodyParagraphsXml - `a:p` children of the body placeholder's `p:txBody`
+* @param {number} slideNum - cached value of the slide-number `a:fld`
+* @return {string} XML
+*/
+function makeXmlNotesSlideSkeleton(bodyParagraphsXml, slideNum) {
+	const spTree = spTreeEl([
+		el("p:sp", null, [raw(el("p:nvSpPr", null, [
+			raw(voidEl("p:cNvPr", {
+				id: 2,
+				name: "Slide Image Placeholder 1"
+			})),
+			raw(el("p:cNvSpPr", null, raw(voidEl("a:spLocks", {
+				noGrp: 1,
+				noRot: 1,
+				noChangeAspect: 1
+			})))),
+			raw(el("p:nvPr", null, raw(voidEl("p:ph", { type: "sldImg" }))))
+		])), raw(voidEl("p:spPr"))]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 3,
+					name: "Notes Placeholder 2"
+				})),
+				raw(el("p:cNvSpPr", null, raw(voidEl("a:spLocks", { noGrp: 1 })))),
+				raw(el("p:nvPr", null, raw(voidEl("p:ph", {
+					type: "body",
+					idx: 1
+				}))))
+			])),
+			raw(voidEl("p:spPr")),
+			raw(el("p:txBody", null, [
+				raw(voidEl("a:bodyPr")),
+				raw(voidEl("a:lstStyle")),
+				raw(bodyParagraphsXml)
+			]))
+		]),
+		el("p:sp", null, [
+			raw(el("p:nvSpPr", null, [
+				raw(voidEl("p:cNvPr", {
+					id: 4,
+					name: "Slide Number Placeholder 3"
+				})),
+				raw(el("p:cNvSpPr", null, raw(voidEl("a:spLocks", { noGrp: 1 })))),
+				raw(el("p:nvPr", null, raw(voidEl("p:ph", {
+					type: "sldNum",
+					sz: "quarter",
+					idx: 10
+				}))))
+			])),
+			raw(voidEl("p:spPr")),
+			raw(el("p:txBody", null, [
+				raw(voidEl("a:bodyPr")),
+				raw(voidEl("a:lstStyle")),
+				raw(el("a:p", null, [raw(el("a:fld", {
+					id: SLDNUMFLDID,
+					type: "slidenum"
+				}, [raw(voidEl("a:rPr", { lang: "en-US" })), raw(el("a:t", null, slideNum))])), raw(voidEl("a:endParaRPr", { lang: "en-US" }))]))
+			]))
+		])
+	]);
+	const extLst = notesExtLst();
+	const cSld = el("p:cSld", null, [raw(spTree), raw(extLst)]);
+	return XML_DECL + "\r\n" + el("p:notes", { ...PML_ROOT_NS }, [raw(cSld), raw(el("p:clrMapOvr", null, raw(voidEl("a:masterClrMapping"))))]);
+}
+/**
+* Generates XML string for a notes-slide relation file (`ppt/notesSlides/_rels/notesSlideN.xml.rels`).
+* rId1=notesMaster and rId2=slide are always reserved; any notes hyperlink rels follow (rId3+).
+* @param {NotesSlideContent} notes - the slide's notes, the value {@link makeXmlNotesSlide} was given
+* @param {number} slideNumber - 1-indexed slide number the notes part belongs to
+* @return {string} XML
+*/
+function makeXmlNotesSlideRel(notes, slideNumber) {
+	const hlinkRels = notes.rels.map((rel) => externalHyperlinkRel(rel.rId, rel.Target)).join("");
+	return XML_DECL + relationshipsEl([
+		relationshipEl(1, NOTES_MASTER_REL, targetFromPptSubpart(NOTES_MASTER_PATH)),
+		relationshipEl(2, SLIDE_REL, targetFromPptSubpart(slidePath(slideNumber))),
+		hlinkRels
+	], {
+		openPrefix: "\n		",
+		childPrefix: "\n			",
+		closePrefix: ""
+	});
+}
+/**
+* Creates `ppt/notesMasters/_rels/notesMaster1.xml.rels`
+* @return {string} XML
+*/
+function makeXmlNotesMasterRel() {
+	return relationshipsPart([relationshipEl(1, THEME_REL, "../theme/theme2.xml")], {
+		childPrefix: "\n		",
+		closePrefix: "\n		"
+	});
+}
+//#endregion
+export { noStrokeLine as $, graphicFrameEl as A, getDuplicateObjectNames as At, genXmlParagraphProperties as B, targetBetweenPptSubparts as C, FONT_DATA_CONTENT_TYPE as Ct, cNvPrEl as D, serializeEmbeddedFontLst as Dt, FALLBACK_PICTURE_LOCKS as E, flattenEmbeddedFaces as Et, assertKnownPreset as F, nextMediaTarget as Ft, clampParaMarginInchesEmu as G, renderTextParagraphsXml as H, genXmlCustGeom as I, preencodedPath as It, createHyperlinkRels as J, buAutoNumEl as K, genXmlPresetGeom as L, validateObjectName as Lt, previewPicBody as M, getUuid as Mt, spTreeEl as N, isHyperlinkRel as Nt, cNvPrHyperlink as O, XML_DECL as Ot, xfrmEl as P, isPreencodedPath as Pt, createLineCap as Q, prstGeomRect as R, encodeXmlAttrValue as Rt, slidePath as S, voidEl as St, targetFromPresentation as T, FONT_REL_TYPE as Tt, clampFontSizeSz as U, groupRunsIntoLines as V, clampParaIndentInchesEmu as W, validateHyperlink as X, registerHyperlinkRel as Y, borderLine as Z, fontPath as _, namedColorOr as _t, makeXmlNotesSlideRel as a, fillNamesPaint as at, relsPath as b, elOrVoid as bt, themeFontDefRPr as c, rejectEmptyFill as ct, relationshipsEl as d, genXmlImageCropRect as dt, resolveBorderDash as et, relationshipsPart as f, createShadowEffectLst as ft, commentPath as g, isColorValue as gt, SLIDE_MASTER_PATH as h, createColorElement as ht, makeXmlNotesSlide as i, withLineDefaults as it, grpXfrmEl as j, getNewRelId as jt, genXmlShapeLine as k, bracedGuid as kt, externalHyperlinkRel as l, resolveFillKind as lt, PRESENTATION_PATH as m, alphaEl as mt, makeXmlNotesMaster as n, strokeDash as nt, makeXmlNotesSlideSkeleton as o, genXmlColorSelection as ot, NOTES_MASTER_PATH as p, normalizeShadowOptions as pt, buCharEl as q, makeXmlNotesMasterRel as r, strokePaint as rt, lvlPPr as s, genXmlPatternFill as st, buildNotesSlideRels as t, resolveDash as tt, relationshipEl as u, STRETCH_FILL_RECT as ut, notesSlidePath as v, rejectEmptyColor as vt, targetFromPptSubpart as w, FONT_DATA_EXTENSION as wt, slideLayoutPath as x, raw as xt, overrideName as y, el as yt, genXmlNormAutofit as z };
+
+//# sourceMappingURL=notes-Dh12JAbn.js.map