pptxtojson-pro 0.1.0

package/src/model/Slide.ts

@@ -0,0 +1,386 @@
+/**
+ * Slide parser — converts a slide XML into a structured SlideData
+ * with typed node objects for each shape on the slide.
+ */
+
+import { SafeXmlNode, parseXml } from '../parser/XmlParser';
+import { RelEntry, resolveRelTarget } from '../parser/RelParser';
+import { emuToPx } from '../parser/units';
+import { parseBaseProps } from './nodes/BaseNode';
+import { ShapeNodeData, parseShapeNode } from './nodes/ShapeNode';
+import { PicNodeData, parsePicNode } from './nodes/PicNode';
+import { TableNodeData, parseTableNode } from './nodes/TableNode';
+import { GroupNodeData, parseGroupNode } from './nodes/GroupNode';
+import { ChartNodeData, parseChartNode } from './nodes/ChartNode';
+
+export type SlideNode = ShapeNodeData | PicNodeData | TableNodeData | GroupNodeData | ChartNodeData;
+
+export interface SlideData {
+  index: number;
+  nodes: SlideNode[];
+  background?: SafeXmlNode;
+  layoutIndex: string;
+  rels: Map<string, RelEntry>;
+  /** Full path to the slide file (e.g. "ppt/slides/slide3.xml"). */
+  slidePath: string;
+  /** When false, shapes from the layout and master should NOT be rendered on this slide. */
+  showMasterSp: boolean;
+}
+
+/**
+ * Check whether a graphicFrame contains a table (`a:tbl`).
+ */
+function isTableFrame(node: SafeXmlNode): boolean {
+  const graphic = node.child('graphic');
+  const graphicData = graphic.child('graphicData');
+  return graphicData.child('tbl').exists();
+}
+
+/**
+ * Check whether a graphicFrame contains a chart.
+ */
+function isChartFrame(node: SafeXmlNode): boolean {
+  const graphic = node.child('graphic');
+  const graphicData = graphic.child('graphicData');
+  const uri = graphicData.attr('uri') || '';
+  return uri.includes('chart');
+}
+
+/**
+ * Find p:pic inside OLE graphicData (mc:AlternateContent > mc:Fallback or mc:Choice > p:oleObj > p:pic).
+ * Returns the pic node if it has blipFill with embed (so we can render the preview image).
+ */
+function findOleFallbackPic(graphicFrame: SafeXmlNode): SafeXmlNode | null {
+  const graphic = graphicFrame.child('graphic');
+  const graphicData = graphic.child('graphicData');
+  const uri = graphicData.attr('uri') || '';
+  if (!uri.includes('ole')) return null;
+
+  const altContent = graphicData.child('AlternateContent');
+  if (!altContent.exists()) return null;
+
+  for (const branch of ['Fallback', 'Choice'] as const) {
+    const oleObj = altContent.child(branch).child('oleObj');
+    if (!oleObj.exists()) continue;
+    const pic = oleObj.child('pic');
+    if (!pic.exists()) continue;
+    const blipFill = pic.child('blipFill');
+    const blip = blipFill.child('blip');
+    const embed = blip.attr('embed') ?? blip.attr('r:embed');
+    if (embed) return pic;
+  }
+  return null;
+}
+
+/**
+ * Parse a graphicFrame that contains an OLE object with a fallback picture (preview image).
+ * Uses the frame's position/size and the inner pic's blip embed.
+ * Exported for use in GroupRenderer when parsing group children.
+ */
+export function parseOleFrameAsPicture(graphicFrame: SafeXmlNode): PicNodeData | undefined {
+  const pic = findOleFallbackPic(graphicFrame);
+  if (!pic) return undefined;
+
+  const base = parseBaseProps(graphicFrame);
+  const blipFill = pic.child('blipFill');
+  const blip = blipFill.child('blip');
+  const blipEmbed = blip.attr('embed') ?? blip.attr('r:embed');
+  const blipLink = blip.attr('link') ?? blip.attr('r:link');
+  if (!blipEmbed) return undefined;
+
+  return {
+    ...base,
+    nodeType: 'picture',
+    blipEmbed,
+    blipLink,
+    source: graphicFrame,
+  };
+}
+
+/**
+ * Check whether a graphicFrame contains a SmartArt diagram.
+ */
+function isDiagramFrame(node: SafeXmlNode): boolean {
+  const graphic = node.child('graphic');
+  const graphicData = graphic.child('graphicData');
+  const uri = graphicData.attr('uri') || '';
+  return uri.includes('diagram');
+}
+
+/**
+ * Parse a SmartArt diagram graphicFrame by resolving the diagram drawing fallback XML.
+ * The drawing XML contains pre-rendered shapes in a spTree that we can display as a group.
+ */
+function parseDiagramFrame(
+  graphicFrame: SafeXmlNode,
+  rels: Map<string, RelEntry>,
+  slidePath: string,
+  diagramDrawings: Map<string, string>,
+): GroupNodeData | undefined {
+  const base = parseBaseProps(graphicFrame);
+  const slideDir = slidePath.substring(0, slidePath.lastIndexOf('/'));
+  const drawingCandidates = Array.from(rels.values())
+    .filter(
+      (entry) => entry.type.includes('diagramDrawing') || entry.target.includes('diagrams/drawing'),
+    )
+    .map((entry) => {
+      const target = entry.target;
+      const match = target.match(/drawing(\d+)/);
+      return {
+        target,
+        num: match ? Number.parseInt(match[1], 10) : undefined,
+      };
+    });
+
+  // Extract the diagram data rId from the relIds element to identify which diagram this is
+  const graphic = graphicFrame.child('graphic');
+  const graphicData = graphic.child('graphicData');
+  const relIds = graphicData.child('relIds');
+
+  // Strategy 1: Match data file number to drawing file number
+  // e.g. data3.xml → drawing3.xml
+  if (relIds.exists()) {
+    const dmRId = relIds.attr('r:dm') ?? relIds.attr('dm');
+    if (dmRId) {
+      const dmRel = rels.get(dmRId);
+      if (dmRel) {
+        // Extract the number from the data target (e.g. "data3" → "3")
+        const numMatch = dmRel.target.match(/data(\d+)/);
+        if (numMatch) {
+          const drawingNum = Number.parseInt(numMatch[1], 10);
+          // Prefer exact drawingN; if absent, use the nearest numbered drawing relation.
+          const ordered = drawingCandidates.slice().sort((a, b) => {
+            const da =
+              a.num === undefined ? Number.POSITIVE_INFINITY : Math.abs(a.num - drawingNum);
+            const db =
+              b.num === undefined ? Number.POSITIVE_INFINITY : Math.abs(b.num - drawingNum);
+            return da - db;
+          });
+          for (const candidate of ordered) {
+            const drawingPath = resolveRelTarget(slideDir, candidate.target);
+            const drawingXml = diagramDrawings.get(drawingPath);
+            if (drawingXml) {
+              return buildDiagramGroup(base, drawingXml);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Strategy 2: Fallback - find any diagramDrawing relationship
+  for (const candidate of drawingCandidates) {
+    const drawingPath = resolveRelTarget(slideDir, candidate.target);
+    const drawingXml = diagramDrawings.get(drawingPath);
+    if (drawingXml) {
+      return buildDiagramGroup(base, drawingXml);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Read xfrm off/ext from a shape-like node (dsp:sp uses dsp:spPr > a:xfrm).
+ */
+function readShapeBounds(node: SafeXmlNode): { x: number; y: number; w: number; h: number } | null {
+  const spPr = node.child('spPr');
+  if (!spPr.exists()) return null;
+  const xfrm = spPr.child('xfrm');
+  if (!xfrm.exists()) return null;
+  const off = xfrm.child('off');
+  const ext = xfrm.child('ext');
+  const x = emuToPx(off.numAttr('x') ?? 0);
+  const y = emuToPx(off.numAttr('y') ?? 0);
+  const w = emuToPx(ext.numAttr('cx') ?? 0);
+  const h = emuToPx(ext.numAttr('cy') ?? 0);
+  return { x, y, w, h };
+}
+
+/**
+ * Build a GroupNodeData from a diagram drawing XML string.
+ * Diagram drawings use dsp: namespace (drawingml 2008); structure is dsp:drawing > dsp:spTree > dsp:sp.
+ * Diagram shapes use their own coordinate space; we compute childOffset/childExtent from
+ * the actual bounding box of all shapes so remapping preserves layout and spacing.
+ */
+function buildDiagramGroup(
+  base: ReturnType<typeof parseBaseProps>,
+  drawingXml: string,
+): GroupNodeData {
+  const drawingRoot = parseXml(drawingXml);
+  const spTree = drawingRoot.child('spTree');
+  if (!spTree.exists()) {
+    return {
+      ...base,
+      nodeType: 'group',
+      childOffset: { x: 0, y: 0 },
+      childExtent: { w: base.size.w, h: base.size.h },
+      children: [],
+    };
+  }
+
+  const CHILD_TAGS = new Set(['sp', 'pic', 'grpSp', 'graphicFrame', 'cxnSp']);
+  // Circular presets need isotropic scaling; tree/org-chart style diagrams should keep native axis scaling.
+  const CIRCULAR_PRESETS = new Set(['pie', 'arc', 'blockArc', 'donut', 'circularArrow']);
+  const children: SafeXmlNode[] = [];
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxRight = -Infinity;
+  let maxBottom = -Infinity;
+  let hasCircularPreset = false;
+
+  for (const child of spTree.allChildren()) {
+    if (CHILD_TAGS.has(child.localName)) {
+      children.push(child);
+      const prst = child.child('spPr').child('prstGeom').attr('prst');
+      if (prst && CIRCULAR_PRESETS.has(prst)) hasCircularPreset = true;
+      const b = readShapeBounds(child);
+      if (b) {
+        minX = Math.min(minX, b.x);
+        minY = Math.min(minY, b.y);
+        maxRight = Math.max(maxRight, b.x + b.w);
+        maxBottom = Math.max(maxBottom, b.y + b.h);
+      }
+    }
+  }
+
+  const hasBounds =
+    minX !== Infinity && minY !== Infinity && maxRight !== -Infinity && maxBottom !== -Infinity;
+
+  // Check if shapes extend significantly beyond the diagram frame (negative offsets or huge extents).
+  // When decorative shapes (e.g. blockArc) have large negative coordinates, including them in
+  // the bounding box distorts the layout. Fall back to frame-based coordinates in that case.
+  const bboxSpansNegative = hasBounds && (minX < 0 || minY < 0);
+  const bboxMuchLargerThanFrame =
+    hasBounds && (maxRight - minX > base.size.w * 2 || maxBottom - minY > base.size.h * 2);
+  const useFrameCoords = bboxSpansNegative || bboxMuchLargerThanFrame;
+
+  // Use the graphicFrame's own dimensions as the child coordinate space.
+  // Diagram shapes are positioned in the frame's coordinate space (EMU converted to px).
+  // Using frame dimensions gives a 1:1 scale, preserving original positions and sizes.
+  // This avoids enlarging shapes when the bounding box is smaller than the frame.
+  let extentW = Math.max(1, base.size.w);
+  let extentH = Math.max(1, base.size.h);
+  let offX = 0;
+  let offY = 0;
+
+  if (!hasBounds) {
+    extentW = Math.max(1, base.size.w);
+    extentH = Math.max(1, base.size.h);
+    offX = 0;
+    offY = 0;
+  }
+
+  return {
+    ...base,
+    nodeType: 'group',
+    childOffset: { x: offX, y: offY },
+    childExtent: { w: extentW, h: extentH },
+    children,
+  };
+}
+
+/**
+ * Parse a single child node from spTree, dispatching to the appropriate parser.
+ */
+export function parseChildNode(
+  child: SafeXmlNode,
+  rels: Map<string, RelEntry>,
+  slidePath: string,
+  diagramDrawings?: Map<string, string>,
+): SlideNode | undefined {
+  const tag = child.localName;
+
+  switch (tag) {
+    case 'sp':
+    case 'cxnSp':
+      return parseShapeNode(child);
+    case 'pic':
+      return parsePicNode(child);
+    case 'grpSp':
+      return parseGroupNode(child);
+    case 'graphicFrame':
+      if (isTableFrame(child)) {
+        return parseTableNode(child);
+      }
+      if (isChartFrame(child)) {
+        return parseChartNode(child, rels, slidePath);
+      }
+      // SmartArt diagram with drawing fallback
+      if (isDiagramFrame(child) && diagramDrawings) {
+        return parseDiagramFrame(child, rels, slidePath, diagramDrawings);
+      }
+      // OLE object with fallback picture (e.g. embedded PDF preview on slide 34)
+      {
+        const olePic = parseOleFrameAsPicture(child);
+        if (olePic) return olePic;
+      }
+      // Non-table/chart/ole graphic frames — skip
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Find the layout relationship target from a slide's rels map.
+ * The relationship type URI for slide layouts ends with "slideLayout".
+ */
+function findLayoutRel(rels: Map<string, RelEntry>): string {
+  for (const [, entry] of rels) {
+    if (entry.type.includes('slideLayout')) {
+      return entry.target;
+    }
+  }
+  return '';
+}
+
+/**
+ * Parse a slide XML root (`p:sld`) into SlideData.
+ *
+ * @param root      Parsed XML root of the slide
+ * @param index     Zero-based slide index
+ * @param rels      Relationship entries for this slide
+ * @param slidePath Full path to the slide file (e.g. "ppt/slides/slide1.xml")
+ */
+export function parseSlide(
+  root: SafeXmlNode,
+  index: number,
+  rels: Map<string, RelEntry>,
+  slidePath: string = '',
+  diagramDrawings?: Map<string, string>,
+): SlideData {
+  const cSld = root.child('cSld');
+
+  // --- Background ---
+  const bg = cSld.child('bg');
+  const background = bg.exists() ? bg : undefined;
+
+  // --- Parse shape tree children ---
+  const spTree = cSld.child('spTree');
+  const nodes: SlideNode[] = [];
+
+  for (const child of spTree.allChildren()) {
+    const node = parseChildNode(child, rels, slidePath, diagramDrawings);
+    if (node) {
+      nodes.push(node);
+    }
+  }
+
+  // --- Layout relationship ---
+  const layoutIndex = findLayoutRel(rels);
+
+  // --- showMasterSp: if "0", layout/master shapes should not be rendered on this slide ---
+  const showMasterSpAttr = root.attr('showMasterSp');
+  const showMasterSp = showMasterSpAttr !== '0';
+
+  return {
+    index,
+    nodes,
+    background,
+    layoutIndex,
+    rels,
+    slidePath,
+    showMasterSp,
+  };
+}

package/src/model/Theme.ts

@@ -0,0 +1,95 @@
+/**
+ * Theme parser — extracts color scheme and font definitions from a:theme XML.
+ */
+
+import { SafeXmlNode } from '../parser/XmlParser';
+
+export interface ThemeData {
+  colorScheme: Map<string, string>;
+  majorFont: { latin: string; ea: string; cs: string };
+  minorFont: { latin: string; ea: string; cs: string };
+  fillStyles: SafeXmlNode[]; // from a:fillStyleLst children (indexed 1-based)
+  lineStyles: SafeXmlNode[]; // from a:lnStyleLst children (indexed 1-based)
+  effectStyles: SafeXmlNode[]; // from a:effectStyleLst children (indexed 1-based)
+}
+
+/** Known color scheme slot names in a:clrScheme. */
+const COLOR_SLOTS = [
+  'dk1',
+  'dk2',
+  'lt1',
+  'lt2',
+  'accent1',
+  'accent2',
+  'accent3',
+  'accent4',
+  'accent5',
+  'accent6',
+  'hlink',
+  'folHlink',
+] as const;
+
+/**
+ * Extract a hex color value from a color definition node.
+ * Handles both `a:srgbClr@val` and `a:sysClr@lastClr`.
+ */
+function extractColor(node: SafeXmlNode): string | undefined {
+  const srgb = node.child('srgbClr');
+  if (srgb.exists()) {
+    return srgb.attr('val');
+  }
+  const sys = node.child('sysClr');
+  if (sys.exists()) {
+    return sys.attr('lastClr') ?? sys.attr('val');
+  }
+  return undefined;
+}
+
+/**
+ * Parse font info from a majorFont or minorFont node.
+ * Extracts typeface attributes from latin, ea, and cs child elements.
+ */
+function parseFontInfo(fontNode: SafeXmlNode): { latin: string; ea: string; cs: string } {
+  return {
+    latin: fontNode.child('latin').attr('typeface') ?? '',
+    ea: fontNode.child('ea').attr('typeface') ?? '',
+    cs: fontNode.child('cs').attr('typeface') ?? '',
+  };
+}
+
+/**
+ * Parse a theme XML root (`a:theme`) into ThemeData.
+ */
+export function parseTheme(root: SafeXmlNode): ThemeData {
+  const themeElements = root.child('themeElements');
+
+  // --- Color scheme ---
+  const clrScheme = themeElements.child('clrScheme');
+  const colorScheme = new Map<string, string>();
+
+  for (const slot of COLOR_SLOTS) {
+    const slotNode = clrScheme.child(slot);
+    if (slotNode.exists()) {
+      const hex = extractColor(slotNode);
+      if (hex !== undefined) {
+        colorScheme.set(slot, hex);
+      }
+    }
+  }
+
+  // --- Font scheme ---
+  const fontScheme = themeElements.child('fontScheme');
+  const majorFont = parseFontInfo(fontScheme.child('majorFont'));
+  const minorFont = parseFontInfo(fontScheme.child('minorFont'));
+
+  // --- Format scheme ---
+  const fmtScheme = themeElements.child('fmtScheme');
+  const fillStyleLst = fmtScheme.child('fillStyleLst');
+  const fillStyles: SafeXmlNode[] = fillStyleLst.allChildren();
+  const lnStyleLst = fmtScheme.child('lnStyleLst');
+  const lineStyles: SafeXmlNode[] = lnStyleLst.allChildren();
+  const effectStyleLst = fmtScheme.child('effectStyleLst');
+  const effectStyles: SafeXmlNode[] = effectStyleLst.allChildren();
+
+  return { colorScheme, majorFont, minorFont, fillStyles, lineStyles, effectStyles };
+}

package/src/model/nodes/BaseNode.ts

@@ -0,0 +1,169 @@
+/**
+ * Base node types and property parser shared by all slide node kinds.
+ */
+
+import { SafeXmlNode } from '../../parser/XmlParser';
+import { emuToPx, angleToDeg } from '../../parser/units';
+
+export type NodeType = 'shape' | 'picture' | 'table' | 'group' | 'chart' | 'unknown';
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  w: number;
+  h: number;
+}
+
+export interface PlaceholderInfo {
+  type?: string;
+  idx?: number;
+}
+
+/** Shape-level hyperlink click action (from cNvPr > a:hlinkClick). */
+export interface HlinkAction {
+  /** Action URI, e.g. "ppaction://hlinksldjump", "ppaction://hlinkpres", or empty for URL links. */
+  action?: string;
+  /** Relationship ID for the target (slide, URL, etc.). */
+  rId?: string;
+  /** Optional tooltip text. */
+  tooltip?: string;
+}
+
+export interface BaseNodeData {
+  id: string;
+  name: string;
+  nodeType: NodeType;
+  position: Position;
+  size: Size;
+  rotation: number;
+  flipH: boolean;
+  flipV: boolean;
+  placeholder?: PlaceholderInfo;
+  /** Shape-level hyperlink/click action (action buttons, clickable shapes). */
+  hlinkClick?: HlinkAction;
+  /** @internal Raw XML node — opaque to consumers. Use serializePresentation() for JSON-safe data. */
+  source: SafeXmlNode;
+}
+
+/**
+ * Try to find the non-visual properties container in the given node.
+ * PPTX uses different wrapper names depending on the shape kind:
+ *   p:nvSpPr (shapes/connectors), p:nvPicPr (pictures),
+ *   p:nvGrpSpPr (groups), p:nvGraphicFramePr (tables/charts).
+ */
+function findNvProps(node: SafeXmlNode): { cNvPr: SafeXmlNode; nvPr: SafeXmlNode } {
+  const wrappers = ['nvSpPr', 'nvPicPr', 'nvGrpSpPr', 'nvGraphicFramePr', 'nvCxnSpPr'];
+  for (const name of wrappers) {
+    const wrapper = node.child(name);
+    if (wrapper.exists()) {
+      return {
+        cNvPr: wrapper.child('cNvPr'),
+        nvPr: wrapper.child('nvPr'),
+      };
+    }
+  }
+  return {
+    cNvPr: node.child('cNvPr'),
+    nvPr: node.child('nvPr'),
+  };
+}
+
+/**
+ * Find the transform (xfrm) node. Shapes use `p:spPr > a:xfrm`,
+ * groups use `p:grpSpPr > a:xfrm`, graphic frames use `p:xfrm`.
+ */
+function findXfrm(node: SafeXmlNode): SafeXmlNode {
+  // Try spPr first (most shapes)
+  const spPr = node.child('spPr');
+  if (spPr.exists()) {
+    const xfrm = spPr.child('xfrm');
+    if (xfrm.exists()) return xfrm;
+  }
+
+  // Try grpSpPr (groups)
+  const grpSpPr = node.child('grpSpPr');
+  if (grpSpPr.exists()) {
+    const xfrm = grpSpPr.child('xfrm');
+    if (xfrm.exists()) return xfrm;
+  }
+
+  // Try direct xfrm (graphic frames)
+  const directXfrm = node.child('xfrm');
+  if (directXfrm.exists()) return directXfrm;
+
+  // Return empty node — all reads will return defaults
+  return node.child('__nonexistent__');
+}
+
+/**
+ * Parse placeholder info from nvPr > p:ph.
+ */
+function parsePlaceholder(nvPr: SafeXmlNode): PlaceholderInfo | undefined {
+  const ph = nvPr.child('ph');
+  if (!ph.exists()) return undefined;
+
+  const type = ph.attr('type');
+  const idx = ph.numAttr('idx');
+
+  return { type, idx };
+}
+
+/**
+ * Parse the base properties common to all node types from a shape-like XML node.
+ * Returns everything except `nodeType`, which the caller must set.
+ */
+export function parseBaseProps(spNode: SafeXmlNode): Omit<BaseNodeData, 'nodeType'> {
+  const { cNvPr, nvPr } = findNvProps(spNode);
+
+  const id = cNvPr.attr('id') ?? '';
+  const name = cNvPr.attr('name') ?? '';
+
+  // --- Transform ---
+  const xfrm = findXfrm(spNode);
+  const off = xfrm.child('off');
+  const ext = xfrm.child('ext');
+
+  const position: Position = {
+    x: emuToPx(off.numAttr('x') ?? 0),
+    y: emuToPx(off.numAttr('y') ?? 0),
+  };
+
+  const size: Size = {
+    w: emuToPx(ext.numAttr('cx') ?? 0),
+    h: emuToPx(ext.numAttr('cy') ?? 0),
+  };
+
+  const rotation = angleToDeg(xfrm.numAttr('rot') ?? 0);
+  const flipH = xfrm.attr('flipH') === '1' || xfrm.attr('flipH') === 'true';
+  const flipV = xfrm.attr('flipV') === '1' || xfrm.attr('flipV') === 'true';
+
+  // --- Placeholder ---
+  const placeholder = parsePlaceholder(nvPr);
+
+  // --- Shape-level hyperlink action (cNvPr > a:hlinkClick) ---
+  let hlinkClick: HlinkAction | undefined;
+  const hlinkNode = cNvPr.child('hlinkClick');
+  if (hlinkNode.exists()) {
+    hlinkClick = {
+      action: hlinkNode.attr('action') ?? undefined,
+      rId: hlinkNode.attr('id') ?? hlinkNode.attr('r:id') ?? undefined,
+      tooltip: hlinkNode.attr('tooltip') ?? undefined,
+    };
+  }
+
+  return {
+    id,
+    name,
+    position,
+    size,
+    rotation,
+    flipH,
+    flipV,
+    placeholder,
+    hlinkClick,
+    source: spNode,
+  };
+}

package/src/model/nodes/ChartNode.ts

@@ -0,0 +1,55 @@
+/**
+ * Chart node — represents a chart embedded in a graphicFrame element.
+ */
+
+import { SafeXmlNode } from '../../parser/XmlParser';
+import { RelEntry, resolveRelTarget } from '../../parser/RelParser';
+import { BaseNodeData, parseBaseProps } from './BaseNode';
+
+export interface ChartNodeData extends BaseNodeData {
+  nodeType: 'chart';
+  chartPath: string; // e.g. "ppt/charts/chart1.xml"
+}
+
+/**
+ * Parse a graphicFrame containing a chart reference into a ChartNodeData.
+ *
+ * @param graphicFrame  The graphicFrame XML node
+ * @param slideRels     Relationship entries for the containing slide
+ * @param slidePath     Full path of the slide (e.g. "ppt/slides/slide1.xml")
+ */
+export function parseChartNode(
+  graphicFrame: SafeXmlNode,
+  slideRels: Map<string, RelEntry>,
+  slidePath: string,
+): ChartNodeData | undefined {
+  const base = parseBaseProps(graphicFrame);
+
+  // Find chart relationship
+  const graphic = graphicFrame.child('graphic');
+  const graphicData = graphic.child('graphicData');
+
+  // Find the chart reference - look for c:chart element with r:id
+  let chartRId: string | undefined;
+  for (const child of graphicData.allChildren()) {
+    if (child.localName === 'chart') {
+      chartRId = child.attr('r:id') || child.attr('id');
+      break;
+    }
+  }
+
+  if (!chartRId) return undefined;
+
+  const rel = slideRels.get(chartRId);
+  if (!rel) return undefined;
+
+  // Resolve chart path relative to slide
+  const slideDir = slidePath.substring(0, slidePath.lastIndexOf('/'));
+  const chartPath = resolveRelTarget(slideDir, rel.target);
+
+  return {
+    ...base,
+    nodeType: 'chart' as const,
+    chartPath,
+  };
+}