@shbernal/ts-pptx 3.3.0 → 3.5.0

package/dist/{shapes-BXVgsk0F.js → shapes-Kt51vry6.js}

@@ -1,6 +1,6 @@
-import { n as warn } from "./diagnostics-H1QzgRSw.js";
+import { r as warn } from "./diagnostics-CPVADSL1.js";
 import { i as PackageReadError, n as InvalidOptionError, o as UnsupportedFeatureError, t as InternalError } from "./errors-Bvln0H-7.js";
-import { C as getImageSizeFromBytes, _ as SLIDE_LAYOUT_REL, b as THEME_REL, c as TEXT_VERTICAL, d as IMAGE_REL, f as NOTES_MASTER_REL, l as checkEnumOrThrow, m as OFFICE_DOCUMENT_REL, o as TEXT_ANCHORS, s as TEXT_HORZ_OVERFLOW, v as SLIDE_MASTER_REL, x as fitSrcRectPercents } from "./st-enums-bVnezkMJ.js";
+import { M as TEXT_HORZ_OVERFLOW, N as TEXT_VERTICAL, P as checkEnumOrThrow, a as NOTES_MASTER_REL, c as OFFICE_DOCUMENT_REL, h as SLIDE_MASTER_REL, j as TEXT_ANCHORS, p as SLIDE_LAYOUT_REL, r as IMAGE_REL, t as OOXML_NS, v as THEME_REL, x as getImageSizeFromBytes, y as fitSrcRectPercents } from "./namespaces-CcKuzeuE.js";
 import { DOMParser, MIME_TYPE, XMLSerializer, onErrorStopParsing } from "@xmldom/xmldom";
 /** Parse an XML string strictly: any well-formedness error throws. */
 function parseXml(xml) {
@@ -14,24 +14,6 @@ function parseXml(xml) {
 function serializeXml(doc) {
 	return new XMLSerializer().serializeToString(doc);
 }
-/** Canonical OOXML prefix → namespace URI registry. */
-const OOXML_NS = Object.freeze({
-	a: "http://schemas.openxmlformats.org/drawingml/2006/main",
-	c: "http://schemas.openxmlformats.org/drawingml/2006/chart",
-	cp: "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
-	ct: "http://schemas.openxmlformats.org/package/2006/content-types",
-	cx: "http://schemas.microsoft.com/office/drawing/2014/chartex",
-	dc: "http://purl.org/dc/elements/1.1/",
-	dcterms: "http://purl.org/dc/terms/",
-	dgm: "http://schemas.openxmlformats.org/drawingml/2006/diagram",
-	ep: "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties",
-	mc: "http://schemas.openxmlformats.org/markup-compatibility/2006",
-	p: "http://schemas.openxmlformats.org/presentationml/2006/main",
-	p14: "http://schemas.microsoft.com/office/powerpoint/2010/main",
-	p188: "http://schemas.microsoft.com/office/powerpoint/2018/8/main",
-	pr: "http://schemas.openxmlformats.org/package/2006/relationships",
-	r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
-});
 function splitQName(qname) {
 	const colon = qname.indexOf(":");
 	if (colon < 0) throw new InvalidOptionError("oxml/invalid-qname", `Expected a prefixed qname like "p:sld", got: ${qname}`);
@@ -686,6 +668,94 @@ function intAttr(el, name) {
 	return Number.isFinite(n) ? n : null;
 }
 //#endregion
+//#region src/read/oxml/slide-dom.ts
+/**
+* The `p:cSld` of a slide/layout/master/notes part root.
+*
+* Takes a nullable root and returns a nullable element so a caller can chain from
+* `part?.dom.documentElement` without a guard of its own — which is what a dozen callers were
+* writing by hand, each in a slightly different spelling (`root && …`, `root ? … : null`).
+*/
+function cSldOf(root) {
+	return root ? firstChild(root, "p:cSld") : null;
+}
+/** The `p:spTree` of a slide/layout/master/notes part root, through its `p:cSld`. */
+function spTreeOf(root) {
+	const cSld = cSldOf(root);
+	return cSld ? firstChild(cSld, "p:spTree") : null;
+}
+/**
+* The `p:nvPr` of a shape, whichever `*nvPr` wrapper its kind uses.
+*
+* The wrapper's name varies by shape kind — `p:nvSpPr` on a `p:sp`, `p:nvPicPr` on a `p:pic`,
+* `p:nvGraphicFramePr`, `p:nvCxnSpPr`, `p:nvGrpSpPr` — but it is always the shape's first child
+* element, and `p:nvPr` is always inside it. Taking the first child element rather than naming
+* the wrapper is what lets one helper serve every kind; the callers that named `p:nvSpPr`
+* silently returned null on a picture.
+*/
+function nvPrOf(shape) {
+	const nv = firstChildElement(shape);
+	return nv ? firstChild(nv, "p:nvPr") : null;
+}
+/** The `p:cSld@name` of a slide/layout/master part (`''` when absent). */
+function cSldName(part) {
+	const cSld = cSldOf(part?.dom.documentElement);
+	return (cSld && attr(cSld, "name")) ?? "";
+}
+/** Whether `el` is a `p:spTree`'s own group properties (`p:nvGrpSpPr`/`p:grpSpPr`), not a shape. */
+function isSpTreeProperty(el) {
+	return el.namespaceURI === OOXML_NS.p && (el.localName === "nvGrpSpPr" || el.localName === "grpSpPr");
+}
+/** Whether a `p:spTree` child is a placeholder shape (its `*nvPr` carries a `p:ph`). */
+function isPlaceholderShape(shape) {
+	const nvPr = nvPrOf(shape);
+	return !!(nvPr && firstChild(nvPr, "p:ph"));
+}
+/** The decorative shapes on a layout/master `p:spTree`: every shape child except placeholders. */
+function carriedDecorations(root) {
+	const spTree = spTreeOf(root);
+	if (!spTree) return [];
+	const out = [];
+	for (let node = spTree.firstChild; node; node = node.nextSibling) {
+		if (node.nodeType !== 1) continue;
+		const el = node;
+		if (isSpTreeProperty(el) || isPlaceholderShape(el)) continue;
+		out.push(el);
+	}
+	return out;
+}
+/**
+* The `n`-th shape child of a `p:spTree` in document (z-)order, skipping the
+* tree's own `nvGrpSpPr`/`grpSpPr` and any trailing `p:extLst`. Returns `null`
+* when `n` is past the last shape (the caller then appends).
+*/
+function nthShapeChild(spTree, n) {
+	let i = 0;
+	for (let node = spTree.firstChild; node; node = node.nextSibling) {
+		if (node.nodeType !== 1) continue;
+		const el = node;
+		if (isSpTreeProperty(el)) continue;
+		if (el.namespaceURI === OOXML_NS.p && el.localName === "extLst") continue;
+		if (i === n) return el;
+		i++;
+	}
+	return null;
+}
+/** The first shape child of a `p:spTree` (skipping `nvGrpSpPr`/`grpSpPr`), or `null`. */
+function firstShapeChild(spTree) {
+	for (let node = spTree.firstChild; node; node = node.nextSibling) {
+		if (node.nodeType !== 1) continue;
+		const el = node;
+		if (!isSpTreeProperty(el)) return el;
+	}
+	return null;
+}
+/** Collect `node` and all its descendant elements (document order) into `out`. */
+function collectElements(node, out) {
+	out.push(node);
+	for (let child = node.firstChild; child; child = child.nextSibling) if (child.nodeType === 1) collectElements(child, out);
+}
+//#endregion
 //#region src/read/oxml/placeholder-inherit.ts
 /**
 * Resolving what a placeholder shape *inherits* from its source layout/master chain.
@@ -733,8 +803,7 @@ const RUN_PROP_NAMES = [
 ];
 /** The `p:ph` element of a shape (`p:sp/p:nvSpPr/p:nvPr/p:ph`), or `null`. */
 function placeholderOf(sp) {
-	const nvSpPr = firstChild(sp, "p:nvSpPr");
-	const nvPr = nvSpPr && firstChild(nvSpPr, "p:nvPr");
+	const nvPr = nvPrOf(sp);
 	return nvPr ? firstChild(nvPr, "p:ph") : null;
 }
 /**
@@ -2460,6 +2529,16 @@ var Paragraph = class {
 		}
 		return out;
 	}
+	/**
+	* Replace **this paragraph's** content with a single run, preserving the character
+	* formatting (`a:rPr`) of its first existing run and leaving its `a:pPr` (level,
+	* alignment, bullet) alone. Sibling paragraphs are untouched — the difference from
+	* {@link TextFrame.text}, which collapses the whole body to one paragraph.
+	*/
+	set text(value) {
+		setParagraphText(this.element, value);
+		this.part.markDirty();
+	}
 	/** Escape hatch: the underlying `a:p` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
 	get element_() {
 		return this.element;
@@ -2603,8 +2682,6 @@ function setTextBodyText(txBody, value) {
 	const doc = txBody.ownerDocument;
 	if (!doc) throw new InternalError("oxml/node-has-no-document", "Cannot set text: text body has no owner document");
 	const paragraphs = getElements(txBody, "a:p");
-	const firstRun = paragraphs[0] && firstChild(paragraphs[0], "a:r");
-	const rPrTemplate = firstRun && firstChild(firstRun, "a:rPr");
 	for (let i = paragraphs.length - 1; i >= 1; i--) {
 		const extra = paragraphs[i];
 		if (extra) txBody.removeChild(extra);
@@ -2614,6 +2691,21 @@ function setTextBodyText(txBody, value) {
 		p = createElement(doc, "a:p");
 		txBody.appendChild(p);
 	}
+	setParagraphText(p, value);
+}
+/**
+* Replace **one paragraph's** content with a single run, preserving the `a:rPr` of that
+* paragraph's first existing run and leaving its `a:pPr` (level, alignment, bullet) alone.
+* Sibling paragraphs are untouched, which is the whole difference from
+* {@link setTextBodyText} and the reason this exists: a SmartArt drawing cache packs several
+* nodes' text into one `dsp:txBody`, so collapsing the body there would delete the other
+* nodes' strings. Does **not** mark any part dirty — the caller owns the `Part`.
+*/
+function setParagraphText(p, value) {
+	const doc = p.ownerDocument;
+	if (!doc) throw new InternalError("oxml/node-has-no-document", "Cannot set text: paragraph has no owner document");
+	const firstRun = firstChild(p, "a:r");
+	const rPrTemplate = firstRun && firstChild(firstRun, "a:rPr");
 	for (const child of childElements(p)) if (child.localName === "r" || child.localName === "br" || child.localName === "fld") p.removeChild(child);
 	const run = createElement(doc, "a:r");
 	if (rPrTemplate) run.appendChild(rPrTemplate.cloneNode(true));
@@ -2649,6 +2741,21 @@ var Shape = class {
 		this.host = host;
 	}
 	/**
+	* The transform element carrying this shape's geometry, or `null` if inherited.
+	*
+	* Defaults to `p:spPr/a:xfrm`, which is where three of the four shape kinds keep it
+	* (`p:sp`, `p:pic`, `p:cxnSp`). {@link GraphicFrame} overrides it: a `p:graphicFrame`
+	* has no `p:spPr` and carries a `p:xfrm` of its own directly.
+	*/
+	xfrm() {
+		const spPr = firstChild(this.element, "p:spPr");
+		return spPr ? firstChild(spPr, "a:xfrm") : null;
+	}
+	/** The transform element, creating it (and its container) in document order if absent. */
+	getOrAddXfrm() {
+		return getOrAddSpPrXfrm(this.element);
+	}
+	/**
 	* Mark the owning host's part dirty so `save()` reserializes it. Public
 	* because {@link element_} hands out the live DOM node: the hatch and the
 	* obligation that comes with it belong on the same object.
@@ -3366,13 +3473,6 @@ var Shape = class {
 /** An auto shape, text box, or placeholder (`p:sp`). The only kind that holds text. */
 var AutoShape = class extends Shape {
 	shapeType = "autoShape";
-	xfrm() {
-		const spPr = firstChild(this.element, "p:spPr");
-		return spPr ? firstChild(spPr, "a:xfrm") : null;
-	}
-	getOrAddXfrm() {
-		return getOrAddSpPrXfrm(this.element);
-	}
 	get hasTextFrame() {
 		return firstChild(this.element, "p:txBody") !== null;
 	}
@@ -3394,8 +3494,7 @@ var AutoShape = class extends Shape {
 	* PowerPoint does. Use {@link Slide.placeholder} to find a placeholder by type.
 	*/
 	get placeholder() {
-		const nvSpPr = firstChild(this.element, "p:nvSpPr");
-		const nvPr = nvSpPr && firstChild(nvSpPr, "p:nvPr");
+		const nvPr = nvPrOf(this.element);
 		const ph = nvPr && firstChild(nvPr, "p:ph");
 		return ph ? {
 			type: attr(ph, "type"),
@@ -3470,13 +3569,6 @@ function recolorColorOf(color) {
 /** A picture (`p:pic`). */
 var Picture = class extends Shape {
 	shapeType = "picture";
-	xfrm() {
-		const spPr = firstChild(this.element, "p:spPr");
-		return spPr ? firstChild(spPr, "a:xfrm") : null;
-	}
-	getOrAddXfrm() {
-		return getOrAddSpPrXfrm(this.element);
-	}
 	get supportsFill() {
 		return false;
 	}
@@ -3719,13 +3811,6 @@ var Picture = class extends Shape {
 /** A connector / line (`p:cxnSp`). */
 var Connector = class extends Shape {
 	shapeType = "connector";
-	xfrm() {
-		const spPr = firstChild(this.element, "p:spPr");
-		return spPr ? firstChild(spPr, "a:xfrm") : null;
-	}
-	getOrAddXfrm() {
-		return getOrAddSpPrXfrm(this.element);
-	}
 	/**
 	* The connector's **start**-point shape binding (`p:nvCxnSpPr/p:cNvCxnSpPr/a:stCxn`),
 	* or `null` when the start point is unbound (a bare `p:cNvCxnSpPr`, i.e. a
@@ -4405,6 +4490,548 @@ function floatValue(value) {
 	return Number.isFinite(number) ? number : null;
 }
 //#endregion
+//#region src/read/api/diagram.ts
+/**
+* Read proxies for a SmartArt diagram (`dgm:dataModel`) hosted in a `p:graphicFrame`.
+*
+* SmartArt is a four-part construct, and the frame itself holds none of it: the
+* `a:graphicData` carries only a `dgm:relIds` with four relationship ids pointing at the
+* data, layout, quick-style and colours parts under `/ppt/diagrams/`. The **data** part is
+* the one with content in it — a flat `dgm:ptLst` of points plus a `dgm:cxnLst` of
+* connections that give the points their tree — and it is what this surface decodes. The
+* other three are generated presets (`urn:microsoft.com/office/officeart/…`) describing how
+* PowerPoint *draws* the graph rather than what it says; they surface as parts, not getters.
+*
+* The text is ordinary DrawingML: `dgm:pt/dgm:t` is an `a:CT_TextBody`, the same type a
+* shape's `p:txBody` is, so a point's text reads back through the same
+* {@link TextFrame}/`Paragraph`/`Run` proxies as any other text on the slide, run formatting
+* included.
+*
+* **Not every point is content.** A saved data model interleaves the user's nodes with
+* points the layout engine generated (`pres`), the diagram root (`doc`), and the transition
+* points sitting on each edge (`parTrans`/`sibTrans`, which carry text only where a layout
+* labels its arrows). {@link Diagram.text} applies exactly that filter; {@link Diagram.points}
+* applies none, so a consumer that needs the raw graph gets it.
+*
+* **The structure is in the connections, and {@link Diagram.nodes} is the view of it.** A
+* `parOf` edge names the parent in `@srcId`, the child in `@destId` and the child's sibling
+* position in `@srcOrd`; `points` order is document order and says nothing about depth. Three
+* decisions that tree makes, each of which could defensibly have gone the other way:
+*
+* - **`asst` points are in it.** An assistant is user content, and an org chart merely draws
+*   it off the main branch rather than under it. {@link DiagramPoint.type} carries the
+*   distinction, so folding it silently in with `node` would hide something a consumer can
+*   act on while omitting it would lose authored text.
+* - **Transition points are not.** A `parTrans`/`sibTrans` labels an *edge*, not a node, and
+*   reaches its edge through {@link DiagramConnection.parentTransitionId} /
+*   `siblingTransitionId`. Hanging one off `children` would make the tree disagree with what
+*   PowerPoint's own text pane shows.
+* - **A cycle in `parOf` throws.** It is a corrupt model rather than a shape the format can
+*   express, and the walk would not terminate; see `diagram/parent-edge-cycle`.
+*
+* **A point's text is stored twice.** The data model is what PowerPoint reads, but a deck
+* also carries a *drawing* part (`dsp:drawing`) holding a copy of every drawn string, and
+* every renderer without a SmartArt layout engine — LibreOffice, Google Slides, thumbnailers
+* — paints that copy and nothing else. {@link DiagramPoint.drawnShape} is the link between
+* the two, and {@link DiagramPoint.text}'s setter is what keeps them in step.
+*
+* Authoring a SmartArt graphic from nothing is out of scope: the layout part is a
+* constraint-solver program PowerPoint executes, and the presentation tree it generates is
+* not derivable from the user's content. Editing the text of one that already exists is
+* supported — see {@link DiagramPoint.text}.
+*/
+const POINT_TYPES = [
+	"node",
+	"asst",
+	"doc",
+	"pres",
+	"parTrans",
+	"sibTrans"
+];
+const CONNECTION_TYPES = [
+	"parOf",
+	"presOf",
+	"presParOf",
+	"unknownRelationship"
+];
+/** The MS extension (`dgm:extLst/a:ext`) whose `@relId` names the fallback drawing part. */
+const DRAWING_EXT_URI = "http://schemas.microsoft.com/office/drawing/2008/diagram";
+/**
+* The node → drawn-shape index of one diagram: the `presOf` edges of the data model and the
+* `dsp:sp` elements of the drawing part, both keyed for lookup.
+*
+* Built once per {@link Diagram}, and only when a point is actually asked what draws it — the
+* drawing part is a second XML DOM and a consumer reading node text should not pay to parse
+* it. The consequence of that memo: a consumer who *adds* or *removes* shapes in the drawing
+* part through the escape hatches must re-reach the diagram to see them here.
+*/
+var DrawingIndex = class {
+	drawingPart;
+	themeContext;
+	/** `presOf` arms out of each source point, in `@srcOrd` order. */
+	#arms = /* @__PURE__ */ new Map();
+	/** Each `dsp:sp` by the `pres` modelId it draws. */
+	#shapes = /* @__PURE__ */ new Map();
+	constructor(root, drawingPart, themeContext) {
+		this.drawingPart = drawingPart;
+		this.themeContext = themeContext;
+		const cxnLst = root && firstChild(root, "dgm:cxnLst");
+		for (const cxn of cxnLst ? getElements(cxnLst, "dgm:cxn") : []) {
+			if (attr(cxn, "type") !== "presOf") continue;
+			const srcId = attr(cxn, "srcId");
+			const destId = attr(cxn, "destId");
+			if (!srcId || !destId) continue;
+			const arm = {
+				destId,
+				destinationOrder: intValue(attr(cxn, "destOrd")) ?? 0,
+				sourceOrder: intValue(attr(cxn, "srcOrd")) ?? 0
+			};
+			const list = this.#arms.get(srcId);
+			if (list) list.push(arm);
+			else this.#arms.set(srcId, [arm]);
+		}
+		for (const list of this.#arms.values()) list.sort((a, b) => a.sourceOrder - b.sourceOrder);
+		const drawingRoot = drawingPart?.dom.documentElement ?? null;
+		for (const sp of drawingRoot ? descendantsByTag(drawingRoot, OOXML_NS.dsp, "sp") : []) {
+			const modelId = attr(sp, "modelId");
+			if (modelId !== null && !this.#shapes.has(modelId)) this.#shapes.set(modelId, sp);
+		}
+	}
+	/**
+	* Resolve one authored point to the `pres` point that presents it and to the drawn
+	* paragraph carrying its text.
+	*
+	* A point commonly has **several** `presOf` arms — an org-chart node's box and the
+	* connector beneath it are two presentations of one node — so the arm is chosen by what it
+	* reaches rather than by its `@srcOrd`: the first, in `@srcOrd` order, whose `pres` point
+	* draws a `dsp:sp` that has a `dsp:txBody`. That selector produced a unique hit for all 90
+	* authored points measured across five layout families, and it degrades to "no arm" rather
+	* than to "the wrong arm" on a layout that was not.
+	*/
+	resolve(modelId) {
+		const arms = (modelId === null ? void 0 : this.#arms.get(modelId)) ?? [];
+		const first = arms[0];
+		if (!first) return {
+			presentationId: null,
+			drawnShape: null
+		};
+		for (const arm of arms) {
+			const sp = this.#shapes.get(arm.destId);
+			const txBody = sp && firstChild(sp, "dsp:txBody");
+			if (!sp || !txBody || !this.drawingPart) continue;
+			const paragraph = getElements(txBody, "a:p")[arm.destinationOrder];
+			return {
+				presentationId: arm.destId,
+				drawnShape: paragraph ? {
+					part: this.drawingPart,
+					modelId: arm.destId,
+					paragraphIndex: arm.destinationOrder,
+					textFrame: new TextFrame(txBody, this.drawingPart, this.themeContext),
+					element_: sp
+				} : null
+			};
+		}
+		return {
+			presentationId: first.destId,
+			drawnShape: null
+		};
+	}
+};
+/** One point (`dgm:pt`) of a diagram's data model. */
+var DiagramPoint = class {
+	pt;
+	part;
+	themeContext;
+	relationships;
+	drawing;
+	constructor(pt, part, themeContext, relationships, drawing) {
+		this.pt = pt;
+		this.part = part;
+		this.themeContext = themeContext;
+		this.relationships = relationships;
+		this.drawing = drawing;
+	}
+	/** This point's id (`@modelId`), which connections reference. */
+	get modelId() {
+		return attr(this.pt, "modelId");
+	}
+	/** What kind of point this is (`@type`); `node` when absent, its schema default. */
+	get type() {
+		const raw = attr(this.pt, "type");
+		return raw !== null && POINT_TYPES.includes(raw) ? raw : "node";
+	}
+	/**
+	* For a transition point, the edge it labels (`@cxnId`), or `null`. The schema's default
+	* is the literal `0`, which means "none" rather than naming a point, so it reads `null`.
+	*/
+	get connectionId() {
+		return idAttr(this.pt, "cxnId");
+	}
+	/**
+	* Whether this point is an unfilled prompt (`dgm:prSet/@phldr`) — a node PowerPoint draws
+	* with a grey placeholder string and treats as empty. Excluded from {@link Diagram.text}:
+	* a layout that stores its prompt in `dgm:t` would otherwise extract as content.
+	*/
+	get isPlaceholder() {
+		const prSet = this.#prSet();
+		return prSet ? boolValue(attr(prSet, "phldr")) === true : false;
+	}
+	/** The prompt string a placeholder point displays (`dgm:prSet/@phldrT`), or `null`. */
+	get placeholderText() {
+		const prSet = this.#prSet();
+		return prSet ? attr(prSet, "phldrT") : null;
+	}
+	/**
+	* This point's text body (`dgm:t`) as a {@link TextFrame}, or `null` when the point
+	* carries none. It is an `a:CT_TextBody` like any other, so `paragraphs`, `runs` and the
+	* `resolved*` getters all apply.
+	*
+	* **Writing through this edits the data model only**, and leaves the drawing cache
+	* holding the old string — which is what PowerPoint-less renderers draw. It is the escape
+	* hatch for run-level formatting, so it does exactly what it is told and nothing more;
+	* {@link text}'s setter is the path that mirrors.
+	*/
+	get textFrame() {
+		const t = firstChild(this.pt, "dgm:t");
+		return t ? new TextFrame(t, this.part, this.themeContext, void 0, this.relationships) : null;
+	}
+	/**
+	* The generated `pres` point that presents this one (`dgm:cxn[@type="presOf"]/@destId`),
+	* or `null` when nothing presents it — the normal state of an unlabelled transition point.
+	*
+	* Where a point has several `presOf` arms the one named here is the arm that draws text;
+	* see {@link drawnShape}, which resolves both.
+	*/
+	get presentationId() {
+		return this.drawing?.().resolve(this.modelId).presentationId ?? null;
+	}
+	/**
+	* The paragraph of the fallback drawing part (`dsp:drawing`) that carries this point's
+	* text, or `null` when nothing draws it.
+	*
+	* The mapping runs through the `pres` point rather than directly: a `dsp:sp/@modelId` is
+	* always a `pres` point's id, so a lookup keyed on the authored point's own id finds
+	* nothing at all. It is many-to-one in both directions — one shape draws several points
+	* (`@destOrd` says which paragraph is whose, and it can contradict document order), and
+	* one point has several presentations, of which at most one holds text.
+	*
+	* `null` is a defined outcome, not a failure, and covers four real cases: the package
+	* carries no drawing part; the point has no `presOf` edge (every unlabelled
+	* `parTrans`/`sibTrans`); the `pres` point draws no `dsp:sp`; and the shape it draws has
+	* no `dsp:txBody` (a connector, or a picture node's filled rectangle).
+	*/
+	get drawnShape() {
+		return this.drawing?.().resolve(this.modelId).drawnShape ?? null;
+	}
+	/** This point's text, paragraphs joined by `\n`; `''` when it carries none. */
+	get text() {
+		return this.textFrame?.text ?? "";
+	}
+	/**
+	* Replace this point's text, in the data model **and** in the drawing cache.
+	*
+	* A diagram stores every string twice. `dgm:t` is what PowerPoint reads, and it recomputes
+	* the drawing from the data model on open; the `dsp:drawing` part is what every other
+	* renderer paints, and none of them recompute anything. Writing only the first is an edit
+	* that is invisible in LibreOffice, Google Slides, thumbnailers and web previews until
+	* someone opens the deck in PowerPoint and saves it.
+	*
+	* The data-model write always happens. The mirror is best-effort: when the point resolves
+	* to no drawn paragraph (see {@link drawnShape} for the four ways that occurs) the cache
+	* keeps the old string and a `diagram/drawing-cache-not-updated` diagnostic says so.
+	* Throwing instead would make the common case unusable in order to report the rare one,
+	* and returning a status would be a shape no other text setter here has.
+	*
+	* Two things it deliberately does not do. It does **not** recompute geometry: the drawn
+	* shape keeps its cached position and size, so a much longer string overflows its box in
+	* those same renderers until PowerPoint re-lays the diagram out. And it does not *create*
+	* a place to draw text — a transition point whose layout has no label slot has no
+	* `dsp:sp`, and PowerPoint strips text put on one, so the honest outcome is the
+	* diagnostic. Like every other `text` setter here it collapses the point to one run,
+	* keeping the first run's `a:rPr`; use {@link textFrame} for run-level work.
+	*/
+	set text(value) {
+		const frame = this.textFrame;
+		if (!frame) {
+			warn("diagram/point-has-no-text-body", `SmartArt point ${this.#label()} (type ${this.type}) has no dgm:t, so it is not a point text can be written to; nothing was changed`);
+			return;
+		}
+		frame.text = value;
+		const drawn = this.drawnShape;
+		const paragraph = drawn?.textFrame.paragraphs[drawn.paragraphIndex];
+		if (!drawn || !paragraph) {
+			warn("diagram/drawing-cache-not-updated", `SmartArt point ${this.#label()} resolves to no drawn paragraph, so ${this.part.partName} now holds the new text but the drawing cache still holds the old one; PowerPoint redraws it on open, other renderers do not`);
+			return;
+		}
+		setParagraphText(paragraph.element_, value);
+		drawn.part.markDirty();
+	}
+	/** Escape hatch: the underlying `dgm:pt` element. After mutating it call {@link Diagram.markDirty}. */
+	get element_() {
+		return this.pt;
+	}
+	#prSet() {
+		return firstChild(this.pt, "dgm:prSet");
+	}
+	/** How a diagnostic names this point: its `@modelId`, which is all a corrupt point may have. */
+	#label() {
+		return this.modelId ?? "(no modelId)";
+	}
+};
+/**
+* One user-authored point in its place in the diagram's tree — a `node` or an `asst`, never a
+* generated `pres` point or a transition label. See {@link Diagram.nodes}.
+*/
+var DiagramNode = class {
+	point;
+	parent;
+	level;
+	/** Child nodes, ordered by their `parOf` edge's `@srcOrd`. Empty for a leaf. */
+	children = [];
+	constructor(point, parent, level) {
+		this.point = point;
+		this.parent = parent;
+		this.level = level;
+	}
+};
+/** Sort key for a root with no `parOf` edge at all, so it lands after the ordered ones. */
+const MAX_ORDER = Number.MAX_SAFE_INTEGER;
+/** A SmartArt graphic frame's diagram, backed by its `dgm:dataModel` part. */
+var Diagram = class {
+	part;
+	relIds;
+	opc;
+	frameRelationships;
+	themeContext;
+	#relationships;
+	#docPrSetCache;
+	#drawing;
+	constructor(part, relIds, opc, frameRelationships, themeContext) {
+		this.part = part;
+		this.relIds = relIds;
+		this.opc = opc;
+		this.frameRelationships = frameRelationships;
+		this.themeContext = themeContext;
+	}
+	/** Partname of the diagram data part. */
+	get partName() {
+		return this.part.partName;
+	}
+	/**
+	* Every point (`dgm:ptLst/dgm:pt`) in document order, unfiltered — generated `pres`
+	* points and the `doc` root included. Filter on {@link DiagramPoint.type} for the user's
+	* nodes; {@link text} is the shortcut for the common case, {@link nodes} the structured one.
+	*
+	* Built per access like every other read proxy (`docs/reference/pptx-read.md`, "Object
+	* model"), so `points[0] !== points[0]` while both wrap the same `dgm:pt`. Key a `Map`
+	* on {@link DiagramPoint.modelId}, not on the point.
+	*/
+	get points() {
+		const root = this.#root();
+		const ptLst = root && firstChild(root, "dgm:ptLst");
+		if (!ptLst) return [];
+		const relationships = this.#relationships ??= this.opc.relationshipsFor(this.part.partName);
+		const drawing = () => this.#drawingIndex();
+		return getElements(ptLst, "dgm:pt").map((pt) => new DiagramPoint(pt, this.part, this.themeContext, relationships, drawing));
+	}
+	/**
+	* The authored tree — every `node` and `asst` point in its place, roots in `@srcOrd`
+	* order — as a view over {@link points} and {@link connections} rather than a replacement
+	* for either.
+	*
+	* A root is a content point whose `parOf` parent is not itself content, which in a
+	* PowerPoint-authored model means the `doc` point. Transition points are not members; see
+	* this module's header for that decision and the two beside it.
+	*
+	* @throws PackageReadError `diagram/parent-edge-cycle` when the `parOf` edges make a
+	* point its own ancestor, which is a corrupt model rather than a diagram shape.
+	*/
+	get nodes() {
+		const content = /* @__PURE__ */ new Map();
+		for (const point of this.points) {
+			const modelId = point.modelId;
+			if (modelId !== null && (point.type === "node" || point.type === "asst")) content.set(modelId, point);
+		}
+		const childrenOf = /* @__PURE__ */ new Map();
+		const edgeTo = /* @__PURE__ */ new Map();
+		for (const connection of this.connections) {
+			const { sourceId, destinationId } = connection;
+			if (connection.type !== "parOf" || sourceId === null || destinationId === null) continue;
+			if (!content.has(destinationId)) continue;
+			const edge = {
+				parentId: sourceId,
+				childId: destinationId,
+				order: connection.sourceOrder ?? 0
+			};
+			const list = childrenOf.get(sourceId);
+			if (list) list.push(edge);
+			else childrenOf.set(sourceId, [edge]);
+			edgeTo.set(destinationId, edge);
+		}
+		for (const list of childrenOf.values()) list.sort((a, b) => a.order - b.order);
+		const roots = [...content].filter(([modelId]) => {
+			const parentId = edgeTo.get(modelId)?.parentId;
+			return parentId === void 0 || !content.has(parentId);
+		});
+		roots.sort(([a], [b]) => (edgeTo.get(a)?.order ?? MAX_ORDER) - (edgeTo.get(b)?.order ?? MAX_ORDER));
+		const placed = /* @__PURE__ */ new Set();
+		const build = (point, parent, level, path) => {
+			const modelId = point.modelId;
+			if (modelId !== null && path.has(modelId)) throw this.#cycleError(modelId);
+			const node = new DiagramNode(point, parent, level);
+			if (modelId === null) return node;
+			placed.add(modelId);
+			path.add(modelId);
+			for (const edge of childrenOf.get(modelId) ?? []) {
+				const child = content.get(edge.childId);
+				if (child) node.children.push(build(child, node, level + 1, path));
+			}
+			path.delete(modelId);
+			return node;
+		};
+		const tree = roots.map(([, point]) => build(point, null, 0, /* @__PURE__ */ new Set()));
+		if (placed.size !== content.size) {
+			const orphan = [...content.keys()].find((modelId) => !placed.has(modelId));
+			throw this.#cycleError(orphan ?? "(unidentified)");
+		}
+		return tree;
+	}
+	/**
+	* The point with this `@modelId`, or `null` — the lookup every connection getter implies,
+	* since a `DiagramConnection` names its ends by id and nothing else resolves them.
+	*/
+	point(modelId) {
+		return this.points.find((candidate) => candidate.modelId === modelId) ?? null;
+	}
+	/** Every edge (`dgm:cxnLst/dgm:cxn`) in document order. */
+	get connections() {
+		const root = this.#root();
+		const cxnLst = root && firstChild(root, "dgm:cxnLst");
+		if (!cxnLst) return [];
+		return getElements(cxnLst, "dgm:cxn").map((cxn) => {
+			const rawType = attr(cxn, "type");
+			return {
+				modelId: attr(cxn, "modelId"),
+				type: rawType !== null && CONNECTION_TYPES.includes(rawType) ? rawType : "parOf",
+				sourceId: attr(cxn, "srcId"),
+				destinationId: attr(cxn, "destId"),
+				sourceOrder: intValue(attr(cxn, "srcOrd")),
+				destinationOrder: intValue(attr(cxn, "destOrd")),
+				parentTransitionId: idAttr(cxn, "parTransId"),
+				siblingTransitionId: idAttr(cxn, "sibTransId"),
+				presentationId: attr(cxn, "presId") || null
+			};
+		});
+	}
+	/**
+	* The diagram's text in document order, blocks joined by `\n` — the counterpart to
+	* `TextFrame.text` for a construct that has no single text body.
+	*
+	* Contributing points are the ones a user can type into: everything except the generated
+	* `pres` points, the `doc` root, and any point flagged as an unfilled placeholder. A
+	* point with no text contributes no blank line. Transition labels (`parTrans`/`sibTrans`)
+	* are included where a layout has them, which is why this is not simply the node list.
+	*/
+	get text() {
+		return this.points.filter((point) => point.type !== "pres" && point.type !== "doc" && !point.isPlaceholder).map((point) => point.text).filter((text) => text.length > 0).join("\n");
+	}
+	/**
+	* The layout preset the diagram is drawn with (the `doc` point's `dgm:prSet/@loTypeId`),
+	* e.g. `urn:microsoft.com/office/officeart/2005/8/layout/hList1`. This is what names the
+	* SmartArt *kind*; {@link layoutPart} is that preset's definition.
+	*/
+	get layoutTypeId() {
+		return this.#docPrSetAttr("loTypeId");
+	}
+	/** The quick-style preset (the `doc` point's `dgm:prSet/@qsTypeId`). */
+	get quickStyleTypeId() {
+		return this.#docPrSetAttr("qsTypeId");
+	}
+	/** The colour preset (the `doc` point's `dgm:prSet/@csTypeId`). */
+	get colorsTypeId() {
+		return this.#docPrSetAttr("csTypeId");
+	}
+	/** The layout definition part (`dgm:relIds/@r:lo`), or `null` when missing from the package. */
+	get layoutPart() {
+		return this.#relPart("r:lo");
+	}
+	/** The quick-style part (`dgm:relIds/@r:qs`), or `null` when missing from the package. */
+	get quickStylePart() {
+		return this.#relPart("r:qs");
+	}
+	/** The colours part (`dgm:relIds/@r:cs`), or `null` when missing from the package. */
+	get colorsPart() {
+		return this.#relPart("r:cs");
+	}
+	/**
+	* The fallback drawing part (`dsp:drawing`) that renders the diagram for a consumer with
+	* no SmartArt layout engine, or `null` when the deck carries none. It is named by an MS
+	* extension on the data model rather than by `dgm:relIds`, so a slide holding two
+	* diagrams still resolves each to its own drawing.
+	*/
+	get drawingPart() {
+		const root = this.#root();
+		const extLst = root && firstChild(root, "dgm:extLst");
+		if (!extLst) return null;
+		for (const ext of getElements(extLst, "a:ext")) {
+			if (attr(ext, "uri") !== DRAWING_EXT_URI) continue;
+			const dataModelExt = firstChildElement(ext);
+			if (!dataModelExt || dataModelExt.localName !== "dataModelExt") continue;
+			return this.#partForRelId(attr(dataModelExt, "relId"));
+		}
+		return null;
+	}
+	/** Escape hatch: the underlying `dgm:dataModel` element. After mutating it call {@link markDirty}, or `save()` writes the original bytes. */
+	get element_() {
+		return this.part.dom.documentElement;
+	}
+	/** Mark the diagram data part dirty so `save()` reserializes it. Call after mutating {@link element_}. */
+	markDirty() {
+		this.part.markDirty();
+	}
+	#root() {
+		return this.part.dom.documentElement;
+	}
+	#cycleError(modelId) {
+		return new PackageReadError("diagram/parent-edge-cycle", `Diagram ${this.part.partName} has a parOf cycle reaching point ${modelId}, so its points do not form a tree`);
+	}
+	/**
+	* The `doc` point's `dgm:prSet`, which carries all three preset ids — resolved once
+	* rather than once per getter, since each lookup is a scan of the whole `ptLst`.
+	* `undefined` means "not looked up yet"; `null` means "looked up, not there".
+	*/
+	#docPrSet() {
+		if (this.#docPrSetCache !== void 0) return this.#docPrSetCache;
+		const root = this.#root();
+		const ptLst = root && firstChild(root, "dgm:ptLst");
+		const doc = ptLst && getElements(ptLst, "dgm:pt").find((pt) => attr(pt, "type") === "doc");
+		return this.#docPrSetCache = doc && firstChild(doc, "dgm:prSet") || null;
+	}
+	#docPrSetAttr(name) {
+		const prSet = this.#docPrSet();
+		return prSet ? attr(prSet, name) : null;
+	}
+	/**
+	* The drawing index, built on first use and kept — see {@link DrawingIndex} for what that
+	* memo costs a consumer who mutates the drawing part's shape tree by hand.
+	*/
+	#drawingIndex() {
+		return this.#drawing ??= new DrawingIndex(this.#root(), this.drawingPart, this.themeContext);
+	}
+	#relPart(qname) {
+		return this.#partForRelId(attr(this.relIds, qname));
+	}
+	#partForRelId(relId) {
+		if (!relId) return null;
+		return this.opc.part(this.frameRelationships.resolveTarget(relId)) ?? null;
+	}
+};
+/** An `ST_ModelId` attribute whose schema default `0` means "unset" rather than naming a point. */
+function idAttr(element, name) {
+	const raw = attr(element, name);
+	return raw === null || raw === "" || raw === "0" ? null : raw;
+}
+//#endregion
 //#region src/read/api/table-edit.ts
 /**
 * Ordered mutation of a table cell's `a:tcPr`, and the cell-scoped schema facts every such
@@ -5675,16 +6302,20 @@ var TableCell = class {
 //#endregion
 //#region src/read/api/shapes/graphic-frame.ts
 /**
-* A graphic frame (`p:graphicFrame`) — the host element for a table, a chart, or a chartEx chart.
+* A graphic frame (`p:graphicFrame`) — the host element for a table, a chart, a chartEx
+* chart, or a SmartArt diagram.
 *
-* Which one it holds is told by the `a:graphicData/@uri`, so the accessors below each check that
-* URI before wrapping the payload; `graphicDataUri` is there for the frames this library does not
-* model (SmartArt, OLE, ink), which read as a frame with no table and no chart.
+* Which one it holds is told by the `a:graphicData/@uri`, so the accessors below each check
+* that URI before wrapping the payload. {@link GraphicFrame.graphicDataUri} reports it raw,
+* which is the only signal for the frames this library still does not model (OLE, ink):
+* without it a consumer cannot tell "this frame holds content I cannot reach" from "this
+* frame holds a chart with nothing in it", since every predicate answers `false` for both.
 */
 const A_TABLE_URI = "http://schemas.openxmlformats.org/drawingml/2006/table";
 const A_CHART_URI = "http://schemas.openxmlformats.org/drawingml/2006/chart";
 const A_CHARTEX_URI = "http://schemas.microsoft.com/office/drawing/2014/chartex";
-/** A graphic frame (`p:graphicFrame`) — host for tables and charts. */
+const A_DIAGRAM_URI = "http://schemas.openxmlformats.org/drawingml/2006/diagram";
+/** A graphic frame (`p:graphicFrame`) — host for tables, charts and SmartArt diagrams. */
 var GraphicFrame = class extends Shape {
 	shapeType = "graphicFrame";
 	xfrm() {
@@ -5708,6 +6339,22 @@ var GraphicFrame = class extends Shape {
 	get hasChartEx() {
 		return this.#graphicDataUri() === A_CHARTEX_URI;
 	}
+	/** Whether this frame hosts a SmartArt diagram (`a:graphicData/@uri` is the diagram URI). */
+	get hasDiagram() {
+		return this.#graphicDataUri() === A_DIAGRAM_URI;
+	}
+	/**
+	* The `a:graphicData/@uri` verbatim — the namespace naming what this frame hosts, or
+	* `null` when the frame carries no `a:graphicData`.
+	*
+	* Every `has*` predicate is a comparison against this, so a frame whose URI matches none
+	* of them is one the read model does not decode (an OLE object, an ink `p:contentPart`).
+	* Reading the URI is what lets a consumer say *which* construct it could not reach
+	* instead of inferring loss from four `false`s.
+	*/
+	get graphicDataUri() {
+		return this.#graphicDataUri();
+	}
 	/** The hosted table, or `null` when this frame is not a table. */
 	get table() {
 		if (!this.hasTable) return null;
@@ -5742,6 +6389,22 @@ var GraphicFrame = class extends Shape {
 		const part = this.host.opc.part(partName);
 		return part ? new ChartEx(part) : null;
 	}
+	/**
+	* The hosted SmartArt diagram, or `null` when this frame is not a diagram or its data
+	* part is missing. The payload child is `dgm:relIds`, which names four parts by
+	* relationship id; the `@r:dm` one is the data model this resolves.
+	*/
+	get diagram() {
+		if (!this.hasDiagram) return null;
+		const graphicData = this.#graphicData();
+		const relIds = graphicData && firstChild(graphicData, "dgm:relIds");
+		if (!relIds) return null;
+		const relId = attr(relIds, "r:dm");
+		if (!relId) return null;
+		const partName = this.host.relationships.resolveTarget(relId);
+		const part = this.host.opc.part(partName);
+		return part ? new Diagram(part, relIds, this.host.opc, this.host.relationships, this.host.themeContext()) : null;
+	}
 	#graphicData() {
 		const graphic = firstChild(this.element, "a:graphic");
 		return graphic ? firstChild(graphic, "a:graphicData") : null;
@@ -5923,6 +6586,6 @@ function findShapeByIdDeep(shapes, id) {
 	}
 }
 //#endregion
-export { parseClrScheme as $, readGradientFill as A, getElements as At, placeholderInheritedAnchor as B, setAttr as Bt, Shape as C, boolValue as Ct, spPrXfrmEmu as D, escapeXmlAttribute as Dt, TextFrame as E, descendantsByTag as Et, resolveSlideColorContext as F, parseXml as Ft, placeholderOf as G, placeholderInheritedListStyles as H, resolveSlideThemeParts as I, removeAttr as It, SCHEME_SLOTS as J, slideDefinesColor as K, applyColorTransforms as L, removeChildrenByQName as Lt, resolveLayoutColorContext as M, insertInOrder as Mt, resolveMasterColorContext as N, intValue as Nt, readPatternFill as O, firstChild as Ot, resolveNotesColorContext as P, ownerDocumentOf as Pt, parseClrMap as Q, LST_STYLE_LEVELS as R, replaceInParent as Rt, AutoShape as S, attr as St, Run as T, createElement as Tt, placeholderInheritedRunProps as U, placeholderInheritedColor as V, placeholderInheritedXfrm as W, intAttr as X, fmtEntry as Y, isA as Z, Chart as _, relsPartNameFor as _t, isConnector as a, FILL_CHOICES as at, Connector as b, zipPathToPartName as bt, isPicture as c, SPPR_AFTER_XFRM as ct, Table as d, SPPR_LN_AFTER as dt, resolveColor as et, TableCell as f, SPPR_SCENE3D_AFTER as ft, ChartExSeries as g, relativePartName as gt, ChartExAxis as h, partNameToZipPath as ht, isAutoShape as i, substitutePhClr as it, resolveColorElement as j, getOrAddChild as jt, readPictureFill as k, firstChildElement as kt, wrapShapeElement as l, SPPR_EFFECT_AFTER as lt, ChartEx as m, partNameExtension as mt, buildShapes as n, styleRefFill as nt, isGraphicFrame as o, RPR_FILL_AFTER as ot, TableRow as p, SPPR_SP3D_AFTER as pt, slideDefinesProp as q, findShapeByIdDeep as r, styleRefLine as rt, isGroupShape as s, SHAPE_AFTER_SPPR as st, GroupShape as t, resolveSchemeToken as tt, GraphicFrame as u, SPPR_FILL_AFTER as ut, ChartAxis as v, resolveRelativePartName as vt, Paragraph as w, childElements as wt, Picture as x, OOXML_NS as xt, ChartSeries as y, resolveSingleRel as yt, RUN_PROP_NAMES as z, serializeXml as zt };
+export { carriedDecorations as $, spPrXfrmEmu as A, resolveSingleRel as At, applyColorTransforms as B, getElements as Bt, Connector as C, SPPR_SCENE3D_AFTER as Ct, Paragraph as D, relativePartName as Dt, Shape as E, partNameToZipPath as Et, resolveLayoutColorContext as F, createElement as Ft, placeholderInheritedListStyles as G, parseXml as Gt, RUN_PROP_NAMES as H, insertInOrder as Ht, resolveMasterColorContext as I, descendantsByTag as It, placeholderOf as J, replaceInParent as Jt, placeholderInheritedRunProps as K, removeAttr as Kt, resolveNotesColorContext as L, escapeXmlAttribute as Lt, readPictureFill as M, attr as Mt, readGradientFill as N, boolValue as Nt, Run as O, relsPartNameFor as Ot, resolveColorElement as P, childElements as Pt, cSldOf as Q, resolveSlideColorContext as R, firstChild as Rt, ChartSeries as S, SPPR_LN_AFTER as St, AutoShape as T, partNameExtension as Tt, placeholderInheritedAnchor as U, intValue as Ut, LST_STYLE_LEVELS as V, getOrAddChild as Vt, placeholderInheritedColor as W, ownerDocumentOf as Wt, slideDefinesProp as X, setAttr as Xt, slideDefinesColor as Y, serializeXml as Yt, cSldName as Z, ChartEx as _, RPR_FILL_AFTER as _t, isConnector as a, SCHEME_SLOTS as at, Chart as b, SPPR_EFFECT_AFTER as bt, isPicture as c, isA as ct, Table as d, resolveColor as dt, collectElements as et, TableCell as f, resolveSchemeToken as ft, DiagramPoint as g, FILL_CHOICES as gt, DiagramNode as h, substitutePhClr as ht, isAutoShape as i, spTreeOf as it, readPatternFill as j, zipPathToPartName as jt, TextFrame as k, resolveRelativePartName as kt, wrapShapeElement as l, parseClrMap as lt, Diagram as m, styleRefLine as mt, buildShapes as n, nthShapeChild as nt, isGraphicFrame as o, fmtEntry as ot, TableRow as p, styleRefFill as pt, placeholderInheritedXfrm as q, removeChildrenByQName as qt, findShapeByIdDeep as r, nvPrOf as rt, isGroupShape as s, intAttr as st, GroupShape as t, firstShapeChild as tt, GraphicFrame as u, parseClrScheme as ut, ChartExAxis as v, SHAPE_AFTER_SPPR as vt, Picture as w, SPPR_SP3D_AFTER as wt, ChartAxis as x, SPPR_FILL_AFTER as xt, ChartExSeries as y, SPPR_AFTER_XFRM as yt, resolveSlideThemeParts as z, firstChildElement as zt };
 
-//# sourceMappingURL=shapes-BXVgsk0F.js.map
+//# sourceMappingURL=shapes-Kt51vry6.js.map