@beyondwork/docx-react-component 1.0.55 → 1.0.57

package/src/io/ooxml/parse-main-document.ts

@@ -14,6 +14,7 @@ import type {
   TableIndent,
   TableLook,
   TableWidth,
+  FootnoteProperties,
   SectionProperties,
   PageSize,
   PageMargins,
@@ -24,6 +25,8 @@ import type {
   SectionDocumentGrid,
   SectionLineNumbering,
   SectionPageBorders,
+  DrawingFrameNode,
+  UnknownPropertyChild,
 } from "../../model/canonical-document.ts";
 import type { OpcRelationship } from "./part-manifest.ts";
 import { SCOPE_MARKER_BOOKMARK_PREFIX } from "./parse-scope-markers.ts";
@@ -34,6 +37,7 @@ import {
 import { toCanonicalNumberingInstanceId } from "./parse-numbering.ts";
 import { parseComplexContentXml, type ChartPartLookup } from "./parse-complex-content.ts";
 import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
+import { parseDrawingFrame } from "./parse-drawing.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
 import {
@@ -83,7 +87,9 @@ import {
 const SECT_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
   "cols",
   "docGrid",
+  "endnotePr",
   "footerReference",
+  "footnotePr",
   "headerReference",
   "lnNumType",
   "pgBorders",
@@ -99,6 +105,111 @@ const SECT_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
   modelledChildAttributes: new Map(),
 };
 
+// Phase 7 Slice A — typed grab-bag descriptors for tblPr / trPr / tcPr.
+// Mirrors what table-properties-xml.ts's TABLE/ROW/CELL_PROPERTY_STRIP_SPEC
+// declared as "modelled" elements on the serializer side. Anything outside
+// this set is captured as `unknownPropertyChildren` and re-emitted verbatim.
+const TBL_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "tblStyle", "tblW", "jc", "tblBorders", "tblCellMar",
+  "tblLook", "tblInd", "tblLayout", "tblCellSpacing",
+  "tblCaption", "tblDescription", "bidiVisual", "tblpPr", "tblOverlap",
+]);
+const TR_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "gridBefore", "wBefore", "gridAfter", "wAfter",
+  "trHeight", "tblHeader", "cantSplit", "jc", "cnfStyle",
+]);
+const TC_PR_MODELLED_CHILDREN: ReadonlySet<string> = new Set([
+  "tcW", "gridSpan", "vMerge", "tcBorders", "tcMar", "shd",
+  "vAlign", "textDirection", "noWrap", "tcFitText", "cnfStyle",
+]);
+// Slice B — modelled attributes per modelled table-container child.
+const TABLE_WIDTH_ATTRS = new Set(["w:w", "w:type"]);
+// TABLE_BORDER_ATTRS: the per-side attrs for tblBorders/tcBorders children
+// ("w:val", "w:sz", "w:space", "w:color", "w:themeColor", ...) would populate
+// the tblPr/tcPr descriptors if nested-side capture were in scope.
+// Deferred: nested-side descriptors need a separate pass; see B.5 lane doc.
+const TABLE_SHD_ATTRS = new Set([
+  "w:val", "w:fill", "w:color",
+  "w:themeColor", "w:themeFill", "w:themeShade", "w:themeTint",
+  "w:themeFillShade", "w:themeFillTint",
+]);
+const TBL_PR_MODELLED_CHILD_ATTRIBUTES = new Map<string, ReadonlySet<string>>([
+  ["tblStyle", new Set(["w:val"])],
+  ["tblW", TABLE_WIDTH_ATTRS],
+  ["jc", new Set(["w:val"])],
+  ["tblLook", new Set([
+    "w:val", "w:firstRow", "w:lastRow", "w:firstColumn",
+    "w:lastColumn", "w:noHBand", "w:noVBand",
+  ])],
+  ["tblInd", TABLE_WIDTH_ATTRS],
+  ["tblLayout", new Set(["w:type"])],
+  ["tblCellSpacing", TABLE_WIDTH_ATTRS],
+  ["tblCaption", new Set(["w:val"])],
+  ["tblDescription", new Set(["w:val"])],
+  ["bidiVisual", new Set(["w:val"])],
+  ["tblpPr", new Set([
+    "w:leftFromText", "w:rightFromText", "w:topFromText", "w:bottomFromText",
+    "w:vertAnchor", "w:horzAnchor",
+    "w:tblpX", "w:tblpXSpec", "w:tblpY", "w:tblpYSpec",
+  ])],
+  ["tblOverlap", new Set(["w:val"])],
+]);
+const TR_PR_MODELLED_CHILD_ATTRIBUTES = new Map<string, ReadonlySet<string>>([
+  ["gridBefore", new Set(["w:val"])],
+  ["gridAfter", new Set(["w:val"])],
+  ["wBefore", TABLE_WIDTH_ATTRS],
+  ["wAfter", TABLE_WIDTH_ATTRS],
+  ["trHeight", new Set(["w:val", "w:hRule"])],
+  ["tblHeader", new Set(["w:val"])],
+  ["cantSplit", new Set(["w:val"])],
+  ["jc", new Set(["w:val"])],
+  ["cnfStyle", new Set([
+    "w:val", "w:firstRow", "w:lastRow", "w:firstColumn", "w:lastColumn",
+    "w:oddVBand", "w:evenVBand", "w:oddHBand", "w:evenHBand",
+    "w:firstRowFirstColumn", "w:firstRowLastColumn",
+    "w:lastRowFirstColumn", "w:lastRowLastColumn",
+  ])],
+]);
+const TC_PR_MODELLED_CHILD_ATTRIBUTES = new Map<string, ReadonlySet<string>>([
+  ["tcW", TABLE_WIDTH_ATTRS],
+  ["gridSpan", new Set(["w:val"])],
+  ["vMerge", new Set(["w:val"])],
+  ["shd", TABLE_SHD_ATTRS],
+  ["vAlign", new Set(["w:val"])],
+  ["textDirection", new Set(["w:val"])],
+  ["noWrap", new Set(["w:val"])],
+  ["tcFitText", new Set(["w:val"])],
+  ["cnfStyle", TR_PR_MODELLED_CHILD_ATTRIBUTES.get("cnfStyle")!],
+  // Border-side container w:tcBorders has nested side children (top/bottom/...);
+  // those each carry TABLE_BORDER_ATTRS but nested-attr capture is out of B
+  // scope (would require a separate descriptor).
+]);
+
+const TBL_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: TBL_PR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
+const TR_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: TR_PR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
+const TC_PR_GRAB_BAG_DESCRIPTOR: PropertyGrabBagDescriptor = {
+  modelledChildNames: TC_PR_MODELLED_CHILDREN,
+  modelledChildAttributes: new Map(),
+};
+
+// Returns only the children slot (back-compat); table parsers that want both
+// slots call captureGrabBagFullFromContainer instead.
+function captureGrabBagFromContainer(
+  container: XmlElementNode,
+  descriptor: PropertyGrabBagDescriptor,
+) {
+  const sourceChildren = container.children
+    .filter((child): child is XmlElementNode => child.type === "element")
+    .map((child) => buildGrabBagSourceChildFromParsed(child));
+  return capturePropertyGrabBag(sourceChildren, descriptor);
+}
+
 export interface ParsedMainDocument {
   blocks: ParsedBlockNode[];
   finalSectionProperties?: SectionProperties;
@@ -171,7 +282,8 @@ export type ParsedInlineNode =
   | ParsedFootnoteRefInlineNode
   | ParsedFieldInlineNode
   | ParsedPermStartInlineNode
-  | ParsedPermEndInlineNode;
+  | ParsedPermEndInlineNode
+  | DrawingFrameNode;
 
 export interface ParsedTextNode {
   type: "text";
@@ -382,6 +494,7 @@ export interface ParsedTableBlockNode {
   styleId?: string;
   tblLook?: TableLook;
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   gridColumns: number[];
   rows: ParsedTableRowNode[];
   width?: TableWidth;
@@ -401,6 +514,7 @@ export interface ParsedTableBlockNode {
 export interface ParsedTableRowNode {
   type: "table_row";
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   cells: ParsedTableCellNode[];
   gridBefore?: number;
   widthBefore?: TableWidth;
@@ -418,6 +532,7 @@ export interface ParsedTableRowNode {
 export interface ParsedTableCellNode {
   type: "table_cell";
   propertiesXml?: string;
+  unknownPropertyChildren?: UnknownPropertyChild[];
   gridSpan?: number;
   verticalMerge?: "restart" | "continue";
   children: ParsedBlockNode[];
@@ -604,6 +719,42 @@ function rewriteScopeMarkerBookmarks(blocks: ParsedBlockNode[]): void {
   rewriteInPlace(blocks as unknown as { [key: string]: unknown }[]);
 }
 
+/**
+ * CO4 F3.3 — parse a `w:txbxContent` (or any body-child stream) XML slice into
+ * ParsedBlockNode[]. Thin wrapper around the internal `parseBodyChild` for
+ * `parse-drawing.ts` to recursively parse shape text-box content.
+ *
+ * Input XML must be a root element whose children are body-child elements
+ * (w:p, w:tbl, w:sdt, etc.) — matches the structure of `w:txbxContent`.
+ */
+export function parseBlockStreamFromXml(
+  xml: string,
+  ctx: {
+    relationships: readonly OpcRelationship[];
+    mediaParts: ReadonlyMap<string, InlineMediaPart>;
+    sourcePartPath: string;
+  },
+): ParsedBlockNode[] {
+  const root = parseXml(xml);
+  const relationshipMap = new Map(
+    ctx.relationships.map((r) => [r.id, r] as const),
+  );
+  const wrapper =
+    root.children.find((c): c is XmlElementNode => c.type === "element") ?? root;
+  return wrapper.children
+    .filter((n): n is XmlElementNode => n.type === "element")
+    .map((n) =>
+      parseBodyChild(
+        n,
+        xml,
+        relationshipMap,
+        ctx.relationships,
+        ctx.mediaParts,
+        ctx.sourcePartPath,
+      ),
+    );
+}
+
 function parseBodyChild(
   node: XmlElementNode,
   sourceXml: string,
@@ -1032,6 +1183,7 @@ function parseTableElement(
   let styleId: string | undefined;
   let tblLook: TableLook | undefined;
   let propertiesXml: string | undefined;
+  let unknownPropertyChildren: UnknownPropertyChild[] | undefined;
   let gridColumns: number[] = [];
   let width: TableWidth | undefined;
   let alignment: ParsedTableBlockNode["alignment"];
@@ -1052,6 +1204,7 @@ function parseTableElement(
     switch (localName(child.name)) {
       case "tblPr": {
         propertiesXml = sourceXml.slice(child.start, child.end);
+        unknownPropertyChildren = captureGrabBagFromContainer(child, TBL_PR_GRAB_BAG_DESCRIPTOR);
         styleId = readTableStyleId(child);
         tblLook = readTableLook(child);
         width = readTableWidth(child);
@@ -1083,6 +1236,7 @@ function parseTableElement(
     ...(styleId ? { styleId } : {}),
     ...(tblLook ? { tblLook } : {}),
     ...(propertiesXml ? { propertiesXml } : {}),
+    ...(unknownPropertyChildren ? { unknownPropertyChildren } : {}),
     gridColumns,
     rows,
     ...(width ? { width } : {}),
@@ -1109,6 +1263,7 @@ function parseTableRowElement(
   sourcePartPath: string,
 ): ParsedTableRowNode {
   let propertiesXml: string | undefined;
+  let unknownPropertyChildren: UnknownPropertyChild[] | undefined;
   let gridBefore: number | undefined;
   let widthBefore: TableWidth | undefined;
   let gridAfter: number | undefined;
@@ -1127,6 +1282,7 @@ function parseTableRowElement(
     switch (localName(child.name)) {
       case "trPr":
         propertiesXml = sourceXml.slice(child.start, child.end);
+        unknownPropertyChildren = captureGrabBagFromContainer(child, TR_PR_GRAB_BAG_DESCRIPTOR);
         gridBefore = readTableRowGridPosition(child, "gridBefore");
         widthBefore = readTableRowWidth(child, "wBefore");
         gridAfter = readTableRowGridPosition(child, "gridAfter");
@@ -1147,6 +1303,7 @@ function parseTableRowElement(
   return {
     type: "table_row",
     ...(propertiesXml ? { propertiesXml } : {}),
+    ...(unknownPropertyChildren ? { unknownPropertyChildren } : {}),
     ...(gridBefore !== undefined ? { gridBefore } : {}),
     ...(widthBefore ? { widthBefore } : {}),
     ...(gridAfter !== undefined ? { gridAfter } : {}),
@@ -1171,6 +1328,7 @@ function parseTableCellElement(
   sourcePartPath: string,
 ): ParsedTableCellNode {
   let propertiesXml: string | undefined;
+  let unknownPropertyChildren: UnknownPropertyChild[] | undefined;
   let gridSpan: number | undefined;
   let verticalMerge: "restart" | "continue" | undefined;
   let width: TableWidth | undefined;
@@ -1190,6 +1348,7 @@ function parseTableCellElement(
     switch (localName(child.name)) {
       case "tcPr": {
         propertiesXml = sourceXml.slice(child.start, child.end);
+        unknownPropertyChildren = captureGrabBagFromContainer(child, TC_PR_GRAB_BAG_DESCRIPTOR);
         gridSpan = readCellGridSpan(child);
         verticalMerge = readCellVerticalMerge(child);
         width = readCellWidth(child);
@@ -1214,6 +1373,7 @@ function parseTableCellElement(
   return {
     type: "table_cell",
     ...(propertiesXml ? { propertiesXml } : {}),
+    ...(unknownPropertyChildren ? { unknownPropertyChildren } : {}),
     ...(gridSpan ? { gridSpan } : {}),
     ...(verticalMerge ? { verticalMerge } : {}),
     children,
@@ -2048,6 +2208,28 @@ function parseRun(
       case "drawing": {
         const drawingXml = sourceXml.slice(child.start, child.end);
 
+        // CO4: canonical DrawingFrame path — normalize all w:drawing under one intermediate
+        try {
+          const frame = parseDrawingFrame(drawingXml, {
+            relationships,
+            mediaParts,
+            sourcePartPath,
+            chartPartLookup: activeChartPartLookup,
+            // F3.3: recursive block parser for w:txbxContent inside shape content.
+            // ParsedBlockNode is structurally compatible with TxbxBlockParser's
+            // `{ type: string; ... }` contract — each ParsedBlockNode variant
+            // has a discriminant `type` field (paragraph | table | sdt | ...).
+            blockParser: (xml) =>
+              parseBlockStreamFromXml(xml, { relationships, mediaParts, sourcePartPath }) as unknown as ReadonlyArray<{ type: string; [key: string]: unknown }>,
+          });
+          if (frame) {
+            result.push(frame);
+            break;
+          }
+        } catch {
+          // fall through to legacy chain
+        }
+
         // Try complex content (charts / SmartArt) first
         try {
           const complexContent = parseComplexContentXml(
@@ -3198,6 +3380,16 @@ export function parseSectionPropertiesFromElement(
         props.titlePage = val !== "false" && val !== "0";
         break;
       }
+      case "footnotePr": {
+        const parsed = readFootnoteLikeProperties(child);
+        if (parsed) props.footnotePr = parsed;
+        break;
+      }
+      case "endnotePr": {
+        const parsed = readFootnoteLikeProperties(child);
+        if (parsed) props.endnotePr = parsed;
+        break;
+      }
     }
   }
 
@@ -3220,6 +3412,54 @@ function safeParseInt(value: string | undefined): number | undefined {
   return Number.isFinite(n) ? n : undefined;
 }
 
+/**
+ * Read the child-element shape shared by `<w:footnotePr>` and
+ * `<w:endnotePr>` into a typed `FootnoteProperties` / `EndnoteProperties`.
+ * Both elements carry the same four children (`w:pos`, `w:numFmt`,
+ * `w:numStart`, `w:numRestart`) per ECMA-376 §17.11.11–.18.
+ *
+ * Returns `undefined` when none of the recognized children are present so
+ * callers never stamp an empty `{}` onto `SectionProperties`.
+ */
+function readFootnoteLikeProperties(
+  node: XmlElementNode,
+): FootnoteProperties | undefined {
+  const result: FootnoteProperties = {};
+
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    const name = localName(child.name);
+    const val = child.attributes["w:val"];
+
+    if (name === "pos") {
+      if (val === "pageBottom" || val === "beneathText" || val === "sectEnd" || val === "docEnd") {
+        result.pos = val;
+      }
+    } else if (name === "numFmt") {
+      if (
+        val === "decimal" ||
+        val === "upperRoman" ||
+        val === "lowerRoman" ||
+        val === "upperLetter" ||
+        val === "lowerLetter" ||
+        val === "chicago" ||
+        val === "none"
+      ) {
+        result.numFmt = val;
+      }
+    } else if (name === "numStart") {
+      const n = safeParseInt(val);
+      if (n !== undefined) result.numStart = n;
+    } else if (name === "numRestart") {
+      if (val === "continuous" || val === "eachSect" || val === "eachPage") {
+        result.numRestart = val;
+      }
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 function parseBorderSpec(node: XmlElementNode): BorderSpec | undefined {
   const border: BorderSpec = {};
   const value = node.attributes["w:val"];

package/src/io/ooxml/parse-numbering.ts

@@ -4,6 +4,7 @@ import type {
   NumberingLevelParagraphGeometry,
   NumberingLevelOverride,
   NumberingLevelOverrideDefinition,
+  NumPicBullet,
   ParagraphSpacing,
   ParagraphIndentation,
   TabStop,
@@ -35,12 +36,26 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
   const numberingElement = findChildElement(root, "numbering");
   const abstractDefinitions: NumberingCatalog["abstractDefinitions"] = {};
   const instances: NumberingCatalog["instances"] = {};
+  const numPicBullets: NonNullable<NumberingCatalog["numPicBullets"]> = {};
 
   for (const child of numberingElement.children) {
     if (child.type !== "element") {
       continue;
     }
 
+    // ECMA-376 §17.9.19 — <w:numPicBullet w:numPicBulletId="N"> is a sibling
+    // of <w:abstractNum> / <w:num> at the top of the numbering part. Captured
+    // as a catalog entry keyed by numPicBulletId; raw XML is preserved for
+    // byte-identical round-trip.
+    if (localName(child.name) === "numPicBullet") {
+      const rawId =
+        child.attributes["w:numPicBulletId"] ?? child.attributes.numPicBulletId;
+      if (rawId) {
+        numPicBullets[rawId] = readNumPicBullet(child, rawId);
+      }
+      continue;
+    }
+
     switch (localName(child.name)) {
       case "abstractNum": {
         const rawId = child.attributes["w:abstractNumId"] ?? child.attributes.abstractNumId;
@@ -102,9 +117,86 @@ export function parseNumberingXml(xml: string): NumberingCatalog {
   return {
     abstractDefinitions,
     instances,
+    ...(Object.keys(numPicBullets).length > 0 ? { numPicBullets } : {}),
   };
 }
 
+/**
+ * Read a `<w:numPicBullet>` element into a catalog entry. Extracts the
+ * inner `wp:extent` when present (drawingML path); the raw XML is
+ * preserved verbatim so the export round-trips byte-for-byte regardless
+ * of whether the bullet uses drawing or VML markup.
+ */
+function readNumPicBullet(
+  node: XmlElementNode,
+  numPicBulletId: string,
+): NumPicBullet {
+  let widthEmu: number | undefined;
+  let heightEmu: number | undefined;
+
+  // Walk drawing → inline/anchor → extent for the EMU dimensions. VML
+  // paths skip this branch; rendering will fall back to a default size.
+  const drawing = findChildElementOptional(node, "drawing");
+  if (drawing) {
+    const inline = findChildElementOptional(drawing, "inline");
+    const anchor = findChildElementOptional(drawing, "anchor");
+    const envelope = inline ?? anchor;
+    if (envelope) {
+      const extent = findChildElementOptional(envelope, "extent");
+      if (extent) {
+        const cx = parseInteger(extent.attributes.cx ?? "");
+        const cy = parseInteger(extent.attributes.cy ?? "");
+        if (cx !== undefined) widthEmu = cx;
+        if (cy !== undefined) heightEmu = cy;
+      }
+    }
+  }
+
+  return {
+    numPicBulletId,
+    rawXml: reconstructElementXml(node),
+    ...(widthEmu !== undefined ? { widthEmu } : {}),
+    ...(heightEmu !== undefined ? { heightEmu } : {}),
+  };
+}
+
+/**
+ * Best-effort reconstruction of the source XML for a `<w:numPicBullet>`.
+ * Mirrors `buildGrabBagSourceChildFromParsed` in property-grab-bag.ts —
+ * attribute/element semantic content round-trips, whitespace between
+ * elements + quote styles normalize. For the Lane 3b scope this is the
+ * right trade-off: picture-bullet catalog entries usually round-trip
+ * once-per-document and their mediaId lookup is what matters.
+ */
+function reconstructElementXml(node: XmlElementNode): string {
+  const attrs = Object.entries(node.attributes)
+    .map(([name, value]) => ` ${name}="${escapeAttr(value)}"`)
+    .join("");
+  if (node.children.length === 0) {
+    return `<${node.name}${attrs}/>`;
+  }
+  const body = node.children
+    .map((child) => {
+      if (child.type === "text") return escapeText(child.text);
+      if (child.type === "element") return reconstructElementXml(child);
+      return "";
+    })
+    .join("");
+  return `<${node.name}${attrs}>${body}</${node.name}>`;
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/gu, "&amp;")
+    .replace(/</gu, "&lt;")
+    .replace(/>/gu, "&gt;")
+    .replace(/"/gu, "&quot;");
+}
+
+function escapeText(value: string): string {
+  return value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+}
+
 export function parseParagraphNumberingReferences(
   documentXml: string,
 ): ParsedParagraphNumberingReference[] {
@@ -248,6 +340,9 @@ function readLevelDefinition(
   const restartAfterLevel = rawRestart !== undefined ? parseInteger(rawRestart) : undefined;
   const rPrNode = findChildElementOptional(levelNode, "rPr");
   const runProperties = readRunProperties(rPrNode);
+  const lvlPicBulletNode = findChildElementOptional(levelNode, "lvlPicBulletId");
+  const picBulletId =
+    lvlPicBulletNode?.attributes["w:val"] ?? lvlPicBulletNode?.attributes.val;
 
   return {
     level,
@@ -260,6 +355,7 @@ function readLevelDefinition(
     ...(paragraphGeometry ? { paragraphGeometry } : {}),
     ...(runProperties ? { runProperties } : {}),
     ...(restartAfterLevel !== undefined ? { restartAfterLevel } : {}),
+    ...(picBulletId ? { picBulletId } : {}),
   };
 }
 

package/src/io/ooxml/parse-picture.ts

@@ -0,0 +1,107 @@
+import type { PictureContent } from "../../model/canonical-document.ts";
+
+interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: XmlNode[];
+}
+
+interface XmlTextNode {
+  type: "text";
+  text: string;
+}
+
+type XmlNode = XmlElementNode | XmlTextNode;
+
+/**
+ * Parse a pic:pic element (child of a:graphicData) into PictureContent.
+ *
+ * srcRect values are 0..100000 = 0..100% of the source bitmap dimension.
+ * rotation is in 60000ths of a degree (same unit as EMU-based angle fields).
+ * LO reference: oox/source/drawingml/shape.cxx for xfrm + srcRect scaling.
+ */
+export function parsePicture(graphicDataEl: XmlElementNode): PictureContent | null {
+  const pic = findFirstDescendant(graphicDataEl, "pic");
+  if (!pic) return null;
+
+  // blipFill/blip r:embed
+  const blipFill = findFirstChild(pic, "blipFill");
+  if (!blipFill) return null;
+  const blip = findFirstChild(blipFill, "blip");
+  if (!blip) return null;
+  const blipRef = blip.attributes["r:embed"] ?? blip.attributes.embed ?? "";
+  if (!blipRef) return null;
+
+  // srcRect (percentage crop: 0..100000 = 0..100%)
+  const srcRectEl = findFirstChild(blipFill, "srcRect");
+  const srcRect = srcRectEl
+    ? {
+        top: readPercentAttr(srcRectEl, "t"),
+        bottom: readPercentAttr(srcRectEl, "b"),
+        left: readPercentAttr(srcRectEl, "l"),
+        right: readPercentAttr(srcRectEl, "r"),
+      }
+    : undefined;
+
+  // stretch
+  const stretchEl = findFirstChild(blipFill, "stretch");
+  const stretch = stretchEl ? true : undefined;
+
+  // spPr/xfrm — rotation and flip
+  const spPr = findFirstChild(pic, "spPr");
+  const xfrm = spPr ? findFirstChild(spPr, "xfrm") : undefined;
+  const rotRaw = xfrm?.attributes.rot;
+  const rotation = rotRaw !== undefined ? parseInt(rotRaw, 10) || undefined : undefined;
+  const flipH = xfrm ? readBoolAttr(xfrm, "flipH") : undefined;
+  const flipV = xfrm ? readBoolAttr(xfrm, "flipV") : undefined;
+
+  // prstGeom
+  const prstGeom = spPr ? findFirstChild(spPr, "prstGeom") : undefined;
+  const presetGeom = prstGeom?.attributes.prst;
+
+  const result: PictureContent = { type: "picture", blipRef };
+  if (srcRect) result.srcRect = srcRect;
+  if (stretch !== undefined) result.stretch = stretch;
+  if (rotation !== undefined) result.rotation = rotation;
+  if (flipH !== undefined) result.flipH = flipH;
+  if (flipV !== undefined) result.flipV = flipV;
+  if (presetGeom) result.presetGeom = presetGeom;
+  return result;
+}
+
+function readPercentAttr(el: XmlElementNode, name: string): number {
+  const v = el.attributes[name];
+  if (v === undefined) return 0;
+  return parseInt(v, 10) || 0;
+}
+
+function readBoolAttr(el: XmlElementNode, name: string): boolean | undefined {
+  const v = el.attributes[name];
+  if (v === undefined) return undefined;
+  return v !== "0" && v !== "false";
+}
+
+function findFirstChild(node: XmlElementNode, local: string): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type === "element" && localName(child.name) === local) return child;
+  }
+  return undefined;
+}
+
+function findFirstDescendant(node: XmlElementNode, local: string): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type !== "element") continue;
+    if (localName(child.name) === local) return child;
+    const found = findFirstDescendant(child, local);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+function localName(name: string): string {
+  const i = name.indexOf(":");
+  return i >= 0 ? name.slice(i + 1) : name;
+}
+
+export { type XmlElementNode as PictureXmlElement };