node-pptx-templater 1.0.3 → 1.0.5

package/src/managers/ZOrderManager.js

@@ -0,0 +1,434 @@
+/**
+ * @fileoverview ZOrderManager - Handles slide element Z-order (layer stacking) operations.
+ */
+
+const { createLogger } = require('../utils/logger.js')
+const { PPTXError } = require('../utils/errors.js')
+const { Z_ORDER_SYMBOL } = require('../parsers/XMLParser.js')
+
+const logger = createLogger('ZOrderManager')
+
+const drawingTags = new Set(['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp'])
+
+function detectElementType(tag, item) {
+  if (tag === 'p:sp') {
+    const isTxBox =
+      item?.['p:nvSpPr']?.['p:cNvSpPr']?.['@_txBox'] === '1' ||
+      item?.['p:nvSpPr']?.['p:cNvSpPr']?.['@_txBox'] === true
+    const phType = item?.['p:nvSpPr']?.['p:nvPr']?.['p:ph']?.['@_type']
+    if (isTxBox || phType === 'title' || phType === 'body' || item?.['p:txBody']) {
+      return 'text'
+    }
+    return 'shape'
+  }
+  if (tag === 'p:pic') {
+    return 'image'
+  }
+  if (tag === 'p:graphicFrame') {
+    const uri = item?.['a:graphic']?.['a:graphicData']?.['@_uri'] || ''
+    if (uri.includes('chart')) return 'chart'
+    if (uri.includes('table')) return 'table'
+    if (uri.includes('diagram')) return 'smartart'
+    return 'graphicFrame'
+  }
+  if (tag === 'p:grpSp') {
+    return 'group'
+  }
+  if (tag === 'p:cxnSp') {
+    return 'connector'
+  }
+  return 'unknown'
+}
+
+/**
+ * @class ZOrderManager
+ * @description Manages stacking layers and z-index of shapes on slides.
+ */
+class ZOrderManager {
+  /** @private @type {XMLParser} */
+  #xmlParser
+
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser
+  }
+
+  /**
+   * Helper to parse Z-order array for a container or initialize it if missing.
+   */
+  getOrInitZOrder(container) {
+    if (!container[Z_ORDER_SYMBOL]) {
+      const list = []
+      for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+        let items = container[tag] || []
+        if (!Array.isArray(items)) items = [items]
+        for (const item of items) {
+          let id = null
+          if (tag === 'p:sp') id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+          else if (tag === 'p:pic') id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+          else if (tag === 'p:graphicFrame')
+            id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+          else if (tag === 'p:grpSp') id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+          else if (tag === 'p:cxnSp') id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+
+          if (id !== undefined && id !== null) {
+            list.push(String(id))
+          }
+        }
+      }
+      container[Z_ORDER_SYMBOL] = list
+    }
+    return container[Z_ORDER_SYMBOL]
+  }
+
+  /**
+   * Helper to find drawing element and its parent container.
+   */
+  findObjectByIdOrName(container, targetId) {
+    if (!container) return null
+
+    for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+      let items = container[tag] || []
+      if (!Array.isArray(items)) items = [items]
+      for (const item of items) {
+        let id = null
+        let name = null
+        if (tag === 'p:sp') {
+          id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:pic') {
+          id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:graphicFrame') {
+          id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:grpSp') {
+          id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:cxnSp') {
+          id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_name']
+        }
+
+        if (String(id) === String(targetId) || name === targetId) {
+          return { tag, obj: item, id: String(id), name, parent: container }
+        }
+
+        if (tag === 'p:grpSp') {
+          const res = this.findObjectByIdOrName(item, targetId)
+          if (res) return res
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Retrieves the Z-order sequence of objects on a slide.
+   *
+   * @param {number} slideIndex
+   * @param {SlideManager} slideManager
+   * @returns {Array<Object>} List of object metadata in stacking order.
+   */
+  getObjectOrder(slideIndex, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return []
+
+    const zOrder = this.getOrInitZOrder(spTree)
+
+    const drawingElements = new Map()
+    for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+      let items = spTree[tag] || []
+      if (!Array.isArray(items)) items = [items]
+      for (const item of items) {
+        let id = null
+        let name = null
+        if (tag === 'p:sp') {
+          id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:pic') {
+          id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:graphicFrame') {
+          id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:grpSp') {
+          id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_name']
+        } else if (tag === 'p:cxnSp') {
+          id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+          name = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_name']
+        }
+
+        if (id !== undefined && id !== null) {
+          drawingElements.set(String(id), { tag, obj: item, name })
+        }
+      }
+    }
+
+    const fullZOrder = [...zOrder]
+    for (const id of drawingElements.keys()) {
+      if (!fullZOrder.includes(id)) {
+        fullZOrder.push(id)
+      }
+    }
+
+    const result = []
+    let zIndex = 1
+    for (const id of fullZOrder) {
+      const el = drawingElements.get(id)
+      if (!el) continue
+
+      result.push({
+        id: el.name || id,
+        type: detectElementType(el.tag, el.obj),
+        zIndex: zIndex++,
+      })
+    }
+
+    return result
+  }
+
+  /**
+   * Core reordering orchestrator.
+   * Runs the reorder callback on the correct container and saves the slide XML.
+   */
+  #modifyZOrder(slideIndex, objectId, slideManager, callback) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) {
+      throw new PPTXError(`Invalid slide structure for slide ${slideIndex}`)
+    }
+
+    const res = this.findObjectByIdOrName(spTree, objectId)
+    if (!res) {
+      throw new PPTXError(`Object "${objectId}" not found on slide ${slideIndex}`)
+    }
+
+    const container = res.parent
+    const zOrder = this.getOrInitZOrder(container)
+
+    callback(zOrder, res.id, spTree)
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+  }
+
+  bringForward(slideIndex, objectId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId) => {
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1 && idx < zOrder.length - 1) {
+        zOrder[idx] = zOrder[idx + 1]
+        zOrder[idx + 1] = elementId
+      }
+    })
+  }
+
+  sendBackward(slideIndex, objectId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId) => {
+      const idx = zOrder.indexOf(elementId)
+      if (idx > 0) {
+        zOrder[idx] = zOrder[idx - 1]
+        zOrder[idx - 1] = elementId
+      }
+    })
+  }
+
+  bringToFront(slideIndex, objectId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId) => {
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1) {
+        zOrder.splice(idx, 1)
+        zOrder.push(elementId)
+      }
+    })
+  }
+
+  sendToBack(slideIndex, objectId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId) => {
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1) {
+        zOrder.splice(idx, 1)
+        zOrder.unshift(elementId)
+      }
+    })
+  }
+
+  setZIndex(slideIndex, objectId, zIndex, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId) => {
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1) {
+        zOrder.splice(idx, 1)
+        const targetIdx = Math.max(0, Math.min(zIndex - 1, zOrder.length))
+        zOrder.splice(targetIdx, 0, elementId)
+      }
+    })
+  }
+
+  moveObjectBefore(slideIndex, objectId, targetId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId, spTree) => {
+      const targetRes = this.findObjectByIdOrName(spTree, targetId)
+      if (!targetRes) {
+        throw new PPTXError(`Target object "${targetId}" not found on slide ${slideIndex}`)
+      }
+      if (targetRes.parent !== targetRes.parent) {
+        throw new PPTXError('Cannot move elements across different group containers')
+      }
+
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1) {
+        zOrder.splice(idx, 1)
+      }
+      const targetIdx = zOrder.indexOf(targetRes.id)
+      if (targetIdx !== -1) {
+        zOrder.splice(targetIdx, 0, elementId)
+      } else {
+        zOrder.push(elementId)
+      }
+    })
+  }
+
+  moveObjectAfter(slideIndex, objectId, targetId, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId, slideManager, (zOrder, elementId, spTree) => {
+      const targetRes = this.findObjectByIdOrName(spTree, targetId)
+      if (!targetRes) {
+        throw new PPTXError(`Target object "${targetId}" not found on slide ${slideIndex}`)
+      }
+
+      const idx = zOrder.indexOf(elementId)
+      if (idx !== -1) {
+        zOrder.splice(idx, 1)
+      }
+      const targetIdx = zOrder.indexOf(targetRes.id)
+      if (targetIdx !== -1) {
+        zOrder.splice(targetIdx + 1, 0, elementId)
+      } else {
+        zOrder.push(elementId)
+      }
+    })
+  }
+
+  reorderObjects(slideIndex, order, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return
+
+    const zOrder = this.getOrInitZOrder(spTree)
+
+    // Resolve ordered names/IDs to existing drawing IDs
+    const resolvedIds = []
+    for (const item of order) {
+      const res = this.findObjectByIdOrName(spTree, item)
+      if (res && res.parent === spTree) {
+        resolvedIds.push(res.id)
+      }
+    }
+
+    // Keep track of unspecified IDs
+    const unspecifiedIds = zOrder.filter(id => !resolvedIds.includes(id))
+
+    // Reconstruct the z-order: unspecified bottom, specified top
+    spTree[Z_ORDER_SYMBOL] = [...unspecifiedIds, ...resolvedIds]
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+  }
+
+  applyZOrder(slideIndex, configs, slideManager) {
+    if (!Array.isArray(configs)) return
+
+    for (const config of configs) {
+      if (!config.id) continue
+
+      if (config.bringToFront) {
+        this.bringToFront(slideIndex, config.id, slideManager)
+      } else if (config.sendToBack) {
+        this.sendToBack(slideIndex, config.id, slideManager)
+      } else if (config.bringForward) {
+        this.bringForward(slideIndex, config.id, slideManager)
+      } else if (config.sendBackward) {
+        this.sendBackward(slideIndex, config.id, slideManager)
+      } else if (config.zIndex !== undefined) {
+        this.setZIndex(slideIndex, config.id, config.zIndex, slideManager)
+      }
+    }
+  }
+
+  // Layer Utilities
+  getTopMostObject(slideIndex, slideManager) {
+    const order = this.getObjectOrder(slideIndex, slideManager)
+    return order.length > 0 ? order[order.length - 1] : null
+  }
+
+  getBottomMostObject(slideIndex, slideManager) {
+    const order = this.getObjectOrder(slideIndex, slideManager)
+    return order.length > 0 ? order[0] : null
+  }
+
+  swapObjects(slideIndex, objectId1, objectId2, slideManager) {
+    this.#modifyZOrder(slideIndex, objectId1, slideManager, (zOrder, elementId1, spTree) => {
+      const res2 = this.findObjectByIdOrName(spTree, objectId2)
+      if (!res2) {
+        throw new PPTXError(`Object "${objectId2}" not found on slide ${slideIndex}`)
+      }
+      const elementId2 = res2.id
+      const idx1 = zOrder.indexOf(elementId1)
+      const idx2 = zOrder.indexOf(elementId2)
+      if (idx1 !== -1 && idx2 !== -1) {
+        zOrder[idx1] = elementId2
+        zOrder[idx2] = elementId1
+      }
+    })
+  }
+
+  sortObjects(slideIndex, compareFn, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return
+
+    const zOrder = this.getOrInitZOrder(spTree)
+
+    // Build complete info list
+    const order = this.getObjectOrder(slideIndex, slideManager)
+
+    // Sort order using compareFn
+    order.sort(compareFn)
+
+    // Map sorted IDs back
+    const sortedIds = []
+    for (const item of order) {
+      // Find ID by name or matching ID in container
+      const res = this.findObjectByIdOrName(spTree, item.id)
+      if (res && res.parent === spTree) {
+        sortedIds.push(res.id)
+      }
+    }
+
+    // Preserve unspecified ones at bottom
+    const unspecifiedIds = zOrder.filter(id => !sortedIds.includes(id))
+    spTree[Z_ORDER_SYMBOL] = [...unspecifiedIds, ...sortedIds]
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+  }
+
+  normalizeZOrder(slideIndex, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return
+
+    // Re-initialize and clean up
+    delete spTree[Z_ORDER_SYMBOL]
+    this.getOrInitZOrder(spTree)
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+  }
+}
+
+module.exports = { ZOrderManager }

package/src/parsers/XMLParser.js

@@ -23,6 +23,107 @@
 const { XMLParser: FastXMLParser, XMLBuilder } = require('fast-xml-parser')
 const { PPTXError } = require('../utils/errors.js')
 
+const Z_ORDER_SYMBOL = Symbol('zOrder')
+
+const drawingTags = new Set(['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp'])
+
+function findcNvPr(node) {
+  const tagName = Object.keys(node).find(k => k !== ':@')
+  if (!tagName) return null
+  const children = node[tagName]
+  if (!Array.isArray(children)) return null
+
+  const nvPrNode = children.find(child => {
+    const k = Object.keys(child).find(key => key !== ':@')
+    return (
+      k &&
+      (k === 'p:nvSpPr' ||
+        k === 'p:nvPicPr' ||
+        k === 'p:nvGraphicFramePr' ||
+        k === 'p:nvGrpSpPr' ||
+        k === 'p:nvCxnSpPr')
+    )
+  })
+
+  if (nvPrNode) {
+    const nvPrTagName = Object.keys(nvPrNode).find(k => k !== ':@')
+    const nvPrChildren = nvPrNode[nvPrTagName]
+    if (Array.isArray(nvPrChildren)) {
+      const cNvPrNode = nvPrChildren.find(child => Object.keys(child).includes('p:cNvPr'))
+      if (cNvPrNode) {
+        return cNvPrNode[':@']
+      }
+    }
+  }
+  return null
+}
+
+function buildZOrderMap(orderedNode, containerMap = new Map()) {
+  if (!orderedNode) return containerMap
+  const tagName = Object.keys(orderedNode).find(k => k !== ':@')
+  if (!tagName) return containerMap
+  const children = orderedNode[tagName]
+  if (!Array.isArray(children)) return containerMap
+
+  if (tagName === 'p:spTree') {
+    const order = []
+    for (const child of children) {
+      const childTagName = Object.keys(child).find(k => k !== ':@')
+      if (drawingTags.has(childTagName)) {
+        const attrs = findcNvPr(child)
+        if (attrs && attrs['@_id']) {
+          order.push(String(attrs['@_id']))
+        }
+        buildZOrderMap(child, containerMap)
+      }
+    }
+    containerMap.set('root', order)
+  } else if (tagName === 'p:grpSp') {
+    const attrs = findcNvPr(orderedNode)
+    const grpId = attrs ? String(attrs['@_id']) : null
+    const order = []
+    for (const child of children) {
+      const childTagName = Object.keys(child).find(k => k !== ':@')
+      if (drawingTags.has(childTagName)) {
+        const attrs = findcNvPr(child)
+        if (attrs && attrs['@_id']) {
+          order.push(String(attrs['@_id']))
+        }
+        buildZOrderMap(child, containerMap)
+      }
+    }
+    if (grpId) {
+      containerMap.set(grpId, order)
+    }
+  } else {
+    for (const child of children) {
+      buildZOrderMap(child, containerMap)
+    }
+  }
+
+  return containerMap
+}
+
+function attachZOrder(normalContainer, containerId, containerMap) {
+  if (!normalContainer) return
+
+  const order = containerMap.get(containerId)
+  if (order) {
+    normalContainer[Z_ORDER_SYMBOL] = order
+  }
+
+  let grpSps = normalContainer['p:grpSp'] || []
+  if (!Array.isArray(grpSps)) grpSps = [grpSps]
+
+  for (const grpSp of grpSps) {
+    const cNvPr = grpSp?.['p:nvGrpSpPr']?.['p:cNvPr']
+    const grpId = cNvPr ? String(cNvPr['@_id']) : null
+    if (grpId) {
+      attachZOrder(grpSp, grpId, containerMap)
+    }
+  }
+}
+
 /**
  * Parser configuration for fast-xml-parser.
  * These settings ensure lossless round-trip XML parsing.
@@ -101,9 +202,22 @@ class XMLParser {
    */
   #builder
 
+  /**
+   * @private
+   * @type {FastXMLParser}
+   */
+  #orderedParser
+
   constructor() {
     this.#parser = new FastXMLParser(PARSER_OPTIONS)
     this.#builder = new XMLBuilder(BUILDER_OPTIONS)
+    this.#orderedParser = new FastXMLParser({
+      ignoreAttributes: false,
+      preserveOrder: true,
+      attributeNamePrefix: '@_',
+      parseAttributeValue: false,
+      parseTagValue: false,
+    })
   }
 
   /**
@@ -124,7 +238,31 @@ class XMLParser {
     }
 
     try {
-      return this.#parser.parse(xmlString)
+      const normalObj = this.#parser.parse(xmlString)
+
+      // Automatically inspect for spTree to build and attach Z-order
+      const spTree =
+        normalObj?.['p:sld']?.['p:cSld']?.['p:spTree'] ||
+        normalObj?.['p:sldLayout']?.['p:cSld']?.['p:spTree'] ||
+        normalObj?.['p:sldMaster']?.['p:cSld']?.['p:spTree']
+
+      if (spTree) {
+        try {
+          const orderedObj = this.#orderedParser.parse(xmlString)
+          const orderedRootNode = orderedObj.find(n => {
+            const keys = Object.keys(n)
+            return (
+              keys.includes('p:sld') || keys.includes('p:sldLayout') || keys.includes('p:sldMaster')
+            )
+          })
+          const containerMap = buildZOrderMap(orderedRootNode)
+          attachZOrder(spTree, 'root', containerMap)
+        } catch (err) {
+          // Fallback gracefully if ordered parsing fails
+        }
+      }
+
+      return normalObj
     } catch (err) {
       throw new PPTXError(`XML parse error${context ? ` in ${context}` : ''}: ${err.message}`, err)
     }
@@ -142,13 +280,101 @@ class XMLParser {
    */
   build(obj, xmlDeclaration = '') {
     try {
-      const xml = this.#builder.build(obj)
+      const spTreeObj =
+        obj?.['p:sld']?.['p:cSld']?.['p:spTree'] ||
+        obj?.['p:sldLayout']?.['p:cSld']?.['p:spTree'] ||
+        obj?.['p:sldMaster']?.['p:cSld']?.['p:spTree']
+
+      let xml = this.#builder.build(obj)
+
+      if (spTreeObj) {
+        const correctSpTreeXml = this.serializeContainer(spTreeObj, 'p:spTree')
+        if (xml.includes('<p:spTree/>')) {
+          xml = xml.replace('<p:spTree/>', correctSpTreeXml)
+        } else {
+          xml = xml.replace(/<p:spTree>[\s\S]*<\/p:spTree>/, correctSpTreeXml)
+        }
+      }
+
       return xmlDeclaration ? `${xmlDeclaration}\n${xml}` : xml
     } catch (err) {
       throw new PPTXError(`XML build error: ${err.message}`, err)
     }
   }
 
+  /**
+   * Helper to serialize drawing containers (p:spTree, p:grpSp) recursively in Z-order.
+   */
+  serializeContainer(container, containerTagName) {
+    const zOrder = container[Z_ORDER_SYMBOL] || []
+
+    let headerXml = ''
+    if (container['p:nvGrpSpPr']) {
+      headerXml += this.#builder.build({ 'p:nvGrpSpPr': container['p:nvGrpSpPr'] })
+    }
+    if (container['p:grpSpPr']) {
+      headerXml += this.#builder.build({ 'p:grpSpPr': container['p:grpSpPr'] })
+    }
+
+    // Gather drawing children
+    const drawingElements = new Map()
+    for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+      let items = container[tag] || []
+      if (!Array.isArray(items)) items = [items]
+      for (const item of items) {
+        let id = null
+        if (tag === 'p:sp') id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:pic') id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:graphicFrame') id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:grpSp') id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+        else if (tag === 'p:cxnSp') id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+
+        if (id !== undefined && id !== null) {
+          drawingElements.set(String(id), { tag, obj: item })
+        }
+      }
+    }
+
+    // Append items not in the explicit Z-order list
+    const fullZOrder = [...zOrder]
+    for (const id of drawingElements.keys()) {
+      if (!fullZOrder.includes(id)) {
+        fullZOrder.push(id)
+      }
+    }
+
+    // Build children in Z-order
+    let childrenXml = ''
+    for (const id of fullZOrder) {
+      const el = drawingElements.get(id)
+      if (!el) continue
+
+      if (el.tag === 'p:grpSp') {
+        childrenXml += this.serializeContainer(el.obj, 'p:grpSp')
+      } else {
+        childrenXml += this.#builder.build({ [el.tag]: el.obj })
+      }
+    }
+
+    // Container attributes
+    let attrsStr = ''
+    const attrs = {}
+    for (const k in container) {
+      if (k.startsWith('@_')) {
+        attrs[k] = container[k]
+      }
+    }
+    if (Object.keys(attrs).length > 0) {
+      const attrXml = this.#builder.build({ [containerTagName]: { ...attrs } })
+      const match = attrXml.match(/<[^>]+>/)
+      if (match) {
+        attrsStr = match[0].slice(containerTagName.length + 1, -1)
+      }
+    }
+
+    return `<${containerTagName}${attrsStr}>${headerXml}${childrenXml}</${containerTagName}>`
+  }
+
   /**
    * Extracts the XML declaration line from an XML string.
    *
@@ -289,4 +515,5 @@ class XMLParser {
 
 module.exports = {
   XMLParser,
+  Z_ORDER_SYMBOL,
 }