node-pptx-templater 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.5] - 2026-06-02
+
+### Added
+- **Z-Order (Layer Management) System**: Full stacking control for all slide drawing objects — shapes, images, charts, tables, groups, connectors, and SmartArt. Directly manipulates the OpenXML `<p:spTree>` element order, matching PowerPoint's native Bring Forward / Send Backward behavior exactly. New APIs:
+  - `getObjectOrder(slideIndex)` — Returns ordered metadata (id, type, zIndex) for every element on a slide, bottom-to-top.
+  - `bringForward(options)` — Moves an object one layer up in the stack.
+  - `sendBackward(options)` — Moves an object one layer down.
+  - `bringToFront(options)` — Moves an object to the very top of the stack.
+  - `sendToBack(options)` — Moves an object to the very bottom of the stack.
+  - `setZIndex(options)` — Places an object at an exact 1-based stacking position.
+  - `moveObjectBefore(options)` — Positions an object immediately below a named target.
+  - `moveObjectAfter(options)` — Positions an object immediately above a named target.
+  - `reorderObjects(options)` — Full bulk reorder of the slide stack from a given array.
+  - `applyZOrder(slideIndex, configs)` — Applies multiple stacking rules sequentially in one call.
+  - `swapObjects(slideIndex, id1, id2)` — Exchanges two objects' positions.
+  - `sortObjects(slideIndex, compareFn)` — Sorts the stack using a custom comparator.
+  - `getTopMostObject(slideIndex)` / `getBottomMostObject(slideIndex)` — Inspection helpers.
+  - `normalizeZOrder(slideIndex)` — Re-derives and resets internal Z-order state from the current XML.
+- **Z_ORDER_SYMBOL Export**: The `Z_ORDER_SYMBOL` is now exported from `src/index.js` for advanced integrations.
+- **ZOrderManager**: New dedicated manager class (`src/managers/ZOrderManager.js`) encapsulating all layer logic.
+
+### Fixed
+- **`PPTXTemplater.create()` synchronous readiness**: Added `preloadAll()` call to `#initializeBlank()`. Previously, the blank PPTX template's pre-existing slides were registered but their XML was not cached, causing all synchronous operations (including ZOrderManager) to throw `"Slide N XML not pre-loaded"`.
+
+### Changed
+- **`XMLParser` hybrid parsing**: Added a secondary `preserveOrder: true` fast-xml-parser pass that runs during `parse()` whenever a slide `<p:spTree>` is detected. Extracts DOM element order and attaches it via `Z_ORDER_SYMBOL` to each container. The `build()` method uses a new `serializeContainer()` recursive function to serialize containers in Z_ORDER_SYMBOL order, injecting the result back into the output XML.
+- **`ValidationEngine`**: `validate()` now audits the shape tree for duplicate shape IDs, reporting them as errors.
+
+### Tests
+- Added 12 new integration tests in `tests/integration/ZOrder.test.js` covering all Z-order operations.
+- Total test count increased from 96 → 108 (all passing).
+
 ## [1.0.3] - 2026-06-02
 
 ### Added
@@ -58,6 +90,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Private class fields (`#field`) for encapsulation
 - Modular architecture following SOLID principles
 
+[1.0.4]: https://github.com/jsuyog2/node-pptx-templater/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/jsuyog2/node-pptx-templater/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/jsuyog2/node-pptx-templater/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/jsuyog2/node-pptx-templater/compare/v1.0.0...v1.0.1

package/README.md

@@ -211,6 +211,113 @@ ppt.updateChartTitle('sales-chart', 'Revenue Growth (2026)');
 
 ---
 
+### Z-Order (Layer Management)
+
+Control the stacking order of shapes, images, charts, tables, groups, and connectors on any slide — just like PowerPoint's **Bring Forward / Send Backward** panel. The Z-order directly maps to the XML element order inside the slide's `<p:spTree>`, which is what PowerPoint reads when rendering.
+
+All operations accept either an **options object** with a `slide` key or can be chained after `useSlide()`:
+
+```js
+// Option A — explicit slide number
+ppt.bringForward({ slide: 2, objectId: 'logo' });
+
+// Option B — fluent chain
+ppt.useSlide(2).bringForward('logo');
+```
+
+#### `getObjectOrder(slideIndex)`
+Returns a sorted array describing every drawing element on the slide, bottom-to-top.
+```js
+const layers = ppt.getObjectOrder(1);
+// → [{ id: 'Background', type: 'shape', zIndex: 1 }, ...]
+```
+
+#### `bringForward(options)` / `sendBackward(options)`
+Move an object one layer up or down.
+```js
+ppt.bringForward({ slide: 1, objectId: 'logo' });
+ppt.sendBackward({ slide: 1, objectId: 'logo' });
+```
+
+#### `bringToFront(options)` / `sendToBack(options)`
+Move an object to the very top or very bottom of the stack.
+```js
+ppt.bringToFront({ slide: 1, objectId: 'logo' });
+ppt.sendToBack({ slide: 1, objectId: 'background' });
+```
+
+#### `setZIndex(options)`
+Place an object at an exact 1-based stacking position.
+```js
+ppt.setZIndex({ slide: 1, objectId: 'logo', zIndex: 3 });
+```
+
+#### `moveObjectBefore(options)` / `moveObjectAfter(options)`
+Position an object immediately below or above a specific target.
+```js
+ppt.moveObjectBefore({ slide: 1, objectId: 'overlay', targetId: 'chart' });
+ppt.moveObjectAfter({ slide: 1, objectId: 'label', targetId: 'chart' });
+```
+
+#### `reorderObjects(options)`
+Bulk-reorder the entire slide stack by specifying all object names in desired bottom-to-top order.
+```js
+ppt.reorderObjects({
+  slide: 1,
+  order: ['background', 'chart', 'logo', 'title']
+});
+```
+
+#### `applyZOrder(slideIndex, configs)`
+Apply multiple stacking rules in a single call. Operations are executed sequentially.
+```js
+ppt.applyZOrder(1, [
+  { id: 'background', sendToBack: true },
+  { id: 'overlay', zIndex: 2 },
+  { id: 'logo', bringToFront: true },
+]);
+```
+
+#### `swapObjects(slideIndex, objectId1, objectId2)`
+Exchange the stacking positions of two objects.
+```js
+ppt.swapObjects(1, 'logo', 'chart');
+```
+
+#### `sortObjects(slideIndex, compareFn)`
+Sort the layer stack using a custom comparator (receives `{ id, type, zIndex }` objects).
+```js
+// Alphabetical ascending by name
+ppt.sortObjects(1, (a, b) => a.id.localeCompare(b.id));
+```
+
+#### `getTopMostObject(slideIndex)` / `getBottomMostObject(slideIndex)`
+Retrieve metadata for the topmost or bottommost element.
+```js
+const top = ppt.getTopMostObject(1);   // { id: 'logo', type: 'image', zIndex: 5 }
+const bottom = ppt.getBottomMostObject(1); // { id: 'background', type: 'shape', zIndex: 1 }
+```
+
+#### `normalizeZOrder(slideIndex)`
+Re-derives the Z-order directly from the current XML element order. Useful after manual XML edits or imports to reset the internal ordering state.
+```js
+ppt.normalizeZOrder(1);
+```
+
+**Supported element types:**
+
+| PowerPoint Type | XML Tag | `type` Value |
+|:---|:---|:---|
+| Shape / Text Box | `p:sp` | `shape` / `text` |
+| Image | `p:pic` | `image` |
+| Chart | `p:graphicFrame` + chart URI | `chart` |
+| Table | `p:graphicFrame` + table URI | `table` |
+| SmartArt | `p:graphicFrame` + diagram URI | `smartart` |
+| Group | `p:grpSp` | `group` |
+| Connector | `p:cxnSp` | `connector` |
+
+---
+
 ## ⚡ Performance Benchmarks
 
 Tested on a standard 50-slide enterprise presentation template:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "High-performance, low-level PowerPoint (PPTX) OpenXML template engine for Node.js. Dynamically replace text, insert images, update charts (with Excel workbook data caching), and merge table cells without PowerPoint corruption or Repair Mode prompts.",
   "main": "./src/index.js",
   "type": "commonjs",

package/src/core/PPTXTemplater.js

@@ -36,6 +36,7 @@ const { RelationshipManager } = require('../managers/RelationshipManager.js')
 const { ShapeManager } = require('../managers/ShapeManager.js')
 const { ImageManager } = require('../managers/ImageManager.js')
 const { TextManager } = require('../managers/TextManager.js')
+const { ZOrderManager } = require('../managers/ZOrderManager.js')
 const { ValidationEngine } = require('./ValidationEngine.js')
 const { OutputWriter } = require('./OutputWriter.js')
 const { TemplateEngine } = require('./TemplateEngine.js')
@@ -121,6 +122,12 @@ class PPTXTemplater {
    */
   #textManager
 
+  /**
+   * @private
+   * @type {ZOrderManager}
+   */
+  #zOrderManager
+
   /**
    * @private
    * @type {RelationshipManager}
@@ -169,6 +176,7 @@ class PPTXTemplater {
     this.#imageManager = new ImageManager(this.#xmlParser)
     this.#textManager = new TextManager(this.#xmlParser)
     this.#templateEngine = new TemplateEngine(this.#xmlParser)
+    this.#zOrderManager = new ZOrderManager(this.#xmlParser)
     this.#outputWriter = new OutputWriter(this.#zipManager, this.#contentTypesManager)
   }
 
@@ -253,6 +261,8 @@ class PPTXTemplater {
     await this.#contentTypesManager.initialize(this.#zipManager)
     await this.#relationshipManager.initialize(this.#zipManager)
     await this.#slideManager.initialize(this.#zipManager)
+    // Pre-load all slide XML so synchronous operations work on the blank template's existing slides
+    await this.#slideManager.preloadAll()
     await this.#chartManager.initialize(this.#zipManager)
     await this.#mediaManager.initialize(this.#zipManager)
     this.#loaded = true
@@ -1541,6 +1551,266 @@ class PPTXTemplater {
   get mediaManager() {
     return this.#mediaManager
   }
+
+  // Z-Order / Layer Management APIs
+
+  /**
+   * Moves slide element one layer forward.
+   */
+  bringForward(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.bringForward(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element one layer backward.
+   */
+  sendBackward(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.sendBackward(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element above all other objects.
+   */
+  bringToFront(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.bringToFront(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element behind all other objects.
+   */
+  sendToBack(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.sendToBack(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element to the specific 1-based stacking position.
+   */
+  setZIndex(optionsOrId, zIndex) {
+    this.#assertLoaded()
+    let slideIndex, objectId, targetZIndex
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.zIndex !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      targetZIndex = optionsOrId.zIndex
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      targetZIndex = zIndex
+    }
+    this.#zOrderManager.setZIndex(slideIndex, objectId, targetZIndex, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element directly before (below) a target element.
+   */
+  moveObjectBefore(optionsOrId, targetId) {
+    this.#assertLoaded()
+    let slideIndex, objectId, target
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.targetId !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      target = optionsOrId.targetId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      target = targetId
+    }
+    this.#zOrderManager.moveObjectBefore(slideIndex, objectId, target, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element directly after (above) a target element.
+   */
+  moveObjectAfter(optionsOrId, targetId) {
+    this.#assertLoaded()
+    let slideIndex, objectId, target
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.targetId !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      target = optionsOrId.targetId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      target = targetId
+    }
+    this.#zOrderManager.moveObjectAfter(slideIndex, objectId, target, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Reorders slide objects exactly as specified in the array.
+   */
+  reorderObjects(optionsOrOrder) {
+    this.#assertLoaded()
+    let slideIndex, order
+    if (
+      typeof optionsOrOrder === 'object' &&
+      optionsOrOrder !== null &&
+      Array.isArray(optionsOrOrder.order)
+    ) {
+      slideIndex =
+        optionsOrOrder.slide !== undefined
+          ? optionsOrOrder.slide
+          : this.#getTargetSlideIndices()[0] || 1
+      order = optionsOrOrder.order
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      order = optionsOrOrder
+    }
+    this.#zOrderManager.reorderObjects(slideIndex, order, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Gets the ordered metadata of all objects on the slide.
+   */
+  getObjectOrder(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getObjectOrder(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Applies bulk template configurations for slide elements stacking layers.
+   */
+  applyZOrder(slideOrConfigs, configsOption) {
+    this.#assertLoaded()
+    let slideIndex, configs
+    if (Array.isArray(slideOrConfigs)) {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      configs = slideOrConfigs
+    } else {
+      slideIndex = slideOrConfigs
+      configs = configsOption
+    }
+    this.#zOrderManager.applyZOrder(slideIndex, configs, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Retrieves the info of the top-most object on the slide.
+   */
+  getTopMostObject(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getTopMostObject(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Retrieves the info of the bottom-most object on the slide.
+   */
+  getBottomMostObject(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getBottomMostObject(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Swaps stacking positions of two slide objects.
+   */
+  swapObjects(slideIndexOrId1, id1OrId2, id2) {
+    this.#assertLoaded()
+    let slideIndex, objectId1, objectId2
+    if (id2 !== undefined) {
+      slideIndex = slideIndexOrId1
+      objectId1 = id1OrId2
+      objectId2 = id2
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId1 = slideIndexOrId1
+      objectId2 = id1OrId2
+    }
+    this.#zOrderManager.swapObjects(slideIndex, objectId1, objectId2, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Sorts stacking order using a custom comparison function.
+   */
+  sortObjects(slideIndexOrCompareFn, compareFnOption) {
+    this.#assertLoaded()
+    let slideIndex, compareFn
+    if (typeof slideIndexOrCompareFn === 'function') {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      compareFn = slideIndexOrCompareFn
+    } else {
+      slideIndex = slideIndexOrCompareFn
+      compareFn = compareFnOption
+    }
+    this.#zOrderManager.sortObjects(slideIndex, compareFn, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Cleans up and normalizes stacking order consistency.
+   */
+  normalizeZOrder(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    this.#zOrderManager.normalizeZOrder(targetIdx, this.#slideManager)
+    return this
+  }
 }
 
 module.exports = { PPTXTemplater }

package/src/core/ValidationEngine.js

@@ -105,6 +105,11 @@ class ValidationEngine {
           )
         }
       }
+
+      // Verify Z-order and duplicate IDs
+      const zOrderResult = this.validateObjectOrder(ppt, slideIndex)
+      errors.push(...zOrderResult.errors)
+      warnings.push(...zOrderResult.warnings)
     } catch (err) {
       errors.push(`Slide ${slideIndex} validation error: ${err.message}`)
     }
@@ -241,6 +246,78 @@ class ValidationEngine {
       warnings,
     }
   }
+
+  /**
+   * Audits the shape tree structure for duplicate drawing element IDs.
+   */
+  static validateObjectOrder(ppt, slideIndex) {
+    const errors = []
+    const warnings = []
+
+    try {
+      const slideXml = ppt.slideManager.getSlideXml(slideIndex)
+      const slideObj = ppt.xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+      const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+
+      if (!spTree) {
+        errors.push(`Slide ${slideIndex} shape tree not found`)
+        return { valid: false, errors, warnings }
+      }
+
+      const idToTags = new Map()
+
+      const checkIdsRecursive = container => {
+        if (!container) return
+
+        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']
+              checkIdsRecursive(item)
+            } else if (tag === 'p:cxnSp') {
+              id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_name']
+            }
+
+            if (id !== undefined && id !== null) {
+              const strId = String(id)
+              if (idToTags.has(strId)) {
+                errors.push(
+                  `Duplicate drawing object ID "${strId}" found in slide ${slideIndex} (name: "${name}")`
+                )
+              } else {
+                idToTags.set(strId, tag)
+              }
+            }
+          }
+        }
+      }
+
+      checkIdsRecursive(spTree)
+    } catch (err) {
+      errors.push(`Slide ${slideIndex} shape tree validation error: ${err.message}`)
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
 }
 
 module.exports = { ValidationEngine }

package/src/index.js

@@ -26,7 +26,7 @@
 
 const { PPTXTemplater } = require('./core/PPTXTemplater.js')
 const { ZipManager } = require('./managers/ZipManager.js')
-const { XMLParser } = require('./parsers/XMLParser.js')
+const { XMLParser, Z_ORDER_SYMBOL } = require('./parsers/XMLParser.js')
 const { SlideManager } = require('./managers/SlideManager.js')
 const { ChartManager } = require('./managers/ChartManager.js')
 const { TableManager } = require('./managers/TableManager.js')
@@ -55,6 +55,7 @@ module.exports = {
   PPTXTemplater,
   ZipManager,
   XMLParser,
+  Z_ORDER_SYMBOL,
   SlideManager,
   ChartManager,
   TableManager,

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,
 }