node-pptx-templater 1.0.0

package/src/managers/TableManager.js

@@ -0,0 +1,416 @@
+/**
+ * @fileoverview TableManager - Updates table data in PPTX slides.
+ *
+ * Tables in OpenXML PPTX:
+ * ─────────────────────────────────────────────────────────────────
+ * Tables are stored as a:tbl inside a p:graphicFrame shape.
+ *
+ *   <p:graphicFrame>
+ *     <p:nvGraphicFramePr>
+ *       <p:cNvPr id="6" name="employees-table"/>   ← table name
+ *     </p:nvGraphicFramePr>
+ *     <a:graphic>
+ *       <a:graphicData uri="...table">
+ *         <a:tbl>
+ *           <a:tblGrid>
+ *             <a:gridCol w="2286000"/>    ← column widths
+ *           </a:tblGrid>
+ *           <a:tr h="370840">             ← row (height in EMUs)
+ *             <a:tc>                      ← table cell
+ *               <a:txBody>
+ *                 <a:p>
+ *                   <a:r><a:t>Cell text</a:t></a:r>
+ *                 </a:p>
+ *               </a:txBody>
+ *               <a:tcPr/>                 ← cell properties (borders, fills)
+ *             </a:tc>
+ *           </a:tr>
+ *         </a:tbl>
+ *       </a:graphicData>
+ *     </a:graphic>
+ *   </p:graphicFrame>
+ *
+ * EMU (English Metric Units):
+ *  - 1 inch = 914400 EMU
+ *  - 1 pt = 12700 EMU
+ *  - 1 cm = 360000 EMU
+ *
+ * Key challenge: Preserving cell formatting while replacing text.
+ * We ONLY modify the <a:t> text nodes, keeping all <a:tcPr>, <a:rPr>, etc.
+ *
+ * Merged cells use:
+ *  - <a:tc gridSpan="2"> → horizontal merge (spans 2 columns)
+ *  - <a:tc rowSpan="2"> → vertical merge (spans 2 rows)
+ *  - <a:tc hMerge="1"> → continuation of horizontal merge
+ *  - <a:tc vMerge="1"> → continuation of vertical merge
+ */
+
+import { createLogger } from '../utils/logger.js';
+import { TableNotFoundError } from '../utils/errors.js';
+
+const logger = createLogger('TableManager');
+
+/**
+ * @class TableManager
+ * @description Handles table data replacement in PPTX slides.
+ *
+ * The key design principle is "preserve formatting, replace content".
+ * We never touch table styles, borders, or fonts — only the text.
+ */
+export class TableManager {
+  /** @private @type {XMLParser} */
+  #xmlParser;
+
+  /**
+   * @param {XMLParser} xmlParser
+   */
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser;
+  }
+
+  /**
+   * Updates a table with new row data.
+   * Finds the table by name/ID and replaces its row content.
+   * Preserves all formatting properties.
+   *
+   * @param {number} slideIndex - 1-based slide index.
+   * @param {string} tableId - Table name (from shape's cNvPr name attribute).
+   * @param {string[][]} rows - 2D array of cell values [row][col].
+   * @param {SlideManager} slideManager
+   * @throws {TableNotFoundError} If the table is not found.
+   */
+  updateTable(slideIndex, tableId, rows, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex);
+    const updatedXml = this.#updateTableInXml(slideXml, tableId, rows);
+
+    if (updatedXml === null) {
+      throw new TableNotFoundError(`Table "${tableId}" not found in slide ${slideIndex}`);
+    }
+
+    slideManager.setSlideXml(slideIndex, updatedXml);
+    logger.debug(`Updated table "${tableId}" with ${rows.length} rows`);
+  }
+
+  /**
+   * Updates a table within raw XML.
+   * Returns null if the table was not found.
+   *
+   * @private
+   * @param {string} slideXml - Slide XML content.
+   * @param {string} tableId - Table name to find.
+   * @param {string[][]} rows - New row data.
+   * @returns {string|null} Updated XML or null if not found.
+   */
+  #updateTableInXml(slideXml, tableId, rows) {
+    // Step 1: Find the graphicFrame containing our table
+    // We look for the cNvPr name attribute matching tableId
+    const framePattern = new RegExp(
+      `(<p:graphicFrame>(?:(?!<\\/p:graphicFrame>)[\\s\\S])*?<p:cNvPr[^>]*name="${this.#escapeRegex(tableId)}"[^>]*>[\\s\\S]*?<\\/p:graphicFrame>)`,
+      'g'
+    );
+
+    // Alternative: more robust approach — find graphicFrames with table data
+    let found = false;
+    let updatedXml = slideXml;
+
+    // Strategy 1: Find by name attribute
+    const namePattern = new RegExp(`name="${this.#escapeRegex(tableId)}"`, 'g');
+    const nameMatch = namePattern.exec(slideXml);
+
+    if (nameMatch) {
+      // Find the graphicFrame containing this name
+      const frameStart = slideXml.lastIndexOf('<p:graphicFrame>', nameMatch.index);
+      const frameEnd = this.#findClosingTag(slideXml, '</p:graphicFrame>', nameMatch.index);
+
+      if (frameStart !== -1 && frameEnd !== -1) {
+        const frameXml = slideXml.substring(frameStart, frameEnd + '</p:graphicFrame>'.length);
+        const updatedFrame = this.#updateTableRows(frameXml, rows);
+
+        updatedXml = slideXml.substring(0, frameStart) + updatedFrame +
+          slideXml.substring(frameEnd + '</p:graphicFrame>'.length);
+        found = true;
+      }
+    }
+
+    // Strategy 2: Find by shape ID (tableId is numeric)
+    if (!found && /^\d+$/.test(tableId)) {
+      const idPattern = new RegExp(`id="${tableId}"`, 'g');
+      const idMatch = idPattern.exec(slideXml);
+      if (idMatch) {
+        const frameStart = slideXml.lastIndexOf('<p:graphicFrame>', idMatch.index);
+        const frameEnd = this.#findClosingTag(slideXml, '</p:graphicFrame>', idMatch.index);
+
+        if (frameStart !== -1 && frameEnd !== -1) {
+          const frameXml = slideXml.substring(frameStart, frameEnd + '</p:graphicFrame>'.length);
+          const updatedFrame = this.#updateTableRows(frameXml, rows);
+          updatedXml = slideXml.substring(0, frameStart) + updatedFrame +
+            slideXml.substring(frameEnd + '</p:graphicFrame>'.length);
+          found = true;
+        }
+      }
+    }
+
+    // Strategy 3: Find first table in slide
+    if (!found && tableId === 'first') {
+      const tableStart = slideXml.indexOf('<a:tbl>');
+      const frameStart = slideXml.lastIndexOf('<p:graphicFrame>', tableStart);
+      const frameEnd = this.#findClosingTag(slideXml, '</p:graphicFrame>', tableStart);
+
+      if (frameStart !== -1 && frameEnd !== -1) {
+        const frameXml = slideXml.substring(frameStart, frameEnd + '</p:graphicFrame>'.length);
+        const updatedFrame = this.#updateTableRows(frameXml, rows);
+        updatedXml = slideXml.substring(0, frameStart) + updatedFrame +
+          slideXml.substring(frameEnd + '</p:graphicFrame>'.length);
+        found = true;
+      }
+    }
+
+    return found ? updatedXml : null;
+  }
+
+  /**
+   * Replaces the table rows within a graphicFrame XML snippet.
+   * Preserves the first row's styling as a template for new rows.
+   *
+   * @private
+   * @param {string} frameXml - XML of the graphicFrame containing the table.
+   * @param {string[][]} rows - New data rows.
+   * @returns {string} Updated frame XML.
+   */
+  #updateTableRows(frameXml, rows) {
+    // Extract all existing rows
+    const existingRows = this.#extractAllRows(frameXml);
+
+    if (existingRows.length === 0) {
+      logger.warn('No rows found in table');
+      return frameXml;
+    }
+
+    // Use first row as header template, second as data row template (if available)
+    const headerTemplate = existingRows[0];
+    const dataTemplate = existingRows[1] || existingRows[0];
+
+    // Build new rows
+    const newRowsXml = rows.map((rowData, rowIdx) => {
+      const template = rowIdx === 0 ? headerTemplate : dataTemplate;
+      return this.#buildRow(template, rowData);
+    }).join('');
+
+    // Replace all existing rows with new rows
+    const tblStart = frameXml.indexOf('<a:tbl>');
+    const tblEnd = frameXml.lastIndexOf('</a:tbl>') + '</a:tbl>'.length;
+    const tblXml = frameXml.substring(tblStart, tblEnd);
+
+    // Find where rows begin (after tblGrid) and end (before </a:tbl>)
+    const firstRowStart = tblXml.indexOf('<a:tr ') !== -1
+      ? tblXml.indexOf('<a:tr ')
+      : tblXml.indexOf('<a:tr>');
+    const lastRowEnd = tblXml.lastIndexOf('</a:tr>') + '</a:tr>'.length;
+
+    if (firstRowStart === -1 || lastRowEnd === -1) {
+      return frameXml;
+    }
+
+    const newTblXml =
+      tblXml.substring(0, firstRowStart) +
+      newRowsXml +
+      tblXml.substring(lastRowEnd);
+
+    return frameXml.substring(0, tblStart) + newTblXml + frameXml.substring(tblEnd);
+  }
+
+  /**
+   * Extracts all <a:tr> row XML strings from a table.
+   * @private
+   * @param {string} tableXml
+   * @returns {string[]}
+   */
+  #extractAllRows(tableXml) {
+    const rows = [];
+    let searchFrom = 0;
+
+    while (true) {
+      const rowStart = tableXml.indexOf('<a:tr', searchFrom);
+      if (rowStart === -1) break;
+
+      const rowEnd = tableXml.indexOf('</a:tr>', rowStart);
+      if (rowEnd === -1) break;
+
+      rows.push(tableXml.substring(rowStart, rowEnd + '</a:tr>'.length));
+      searchFrom = rowEnd + '</a:tr>'.length;
+    }
+
+    return rows;
+  }
+
+  /**
+   * Builds a new row XML by cloning a template row and replacing cell text.
+   *
+   * @private
+   * @param {string} templateRow - Template row XML to clone.
+   * @param {string[]} cellValues - Text values for each cell.
+   * @returns {string} New row XML.
+   */
+  #buildRow(templateRow, cellValues) {
+    // Extract template cells
+    const cells = this.#extractCells(templateRow);
+
+    // Build new cells by replacing text in templates
+    const newCells = cellValues.map((value, colIdx) => {
+      const template = cells[colIdx] || cells[cells.length - 1] || '<a:tc><a:txBody><a:p><a:r><a:t/></a:r></a:p></a:txBody><a:tcPr/></a:tc>';
+      return this.#setCellText(template, value);
+    });
+
+    // Replace cells in template row
+    const firstCellStart = templateRow.indexOf('<a:tc>') !== -1
+      ? templateRow.indexOf('<a:tc>')
+      : templateRow.indexOf('<a:tc ');
+    const lastCellEnd = templateRow.lastIndexOf('</a:tc>') + '</a:tc>'.length;
+
+    if (firstCellStart === -1 || lastCellEnd === -1) {
+      return templateRow;
+    }
+
+    return (
+      templateRow.substring(0, firstCellStart) +
+      newCells.join('') +
+      templateRow.substring(lastCellEnd)
+    );
+  }
+
+  /**
+   * Extracts all <a:tc> cell XML strings from a row.
+   * @private
+   * @param {string} rowXml
+   * @returns {string[]}
+   */
+  #extractCells(rowXml) {
+    const cells = [];
+    let searchFrom = 0;
+
+    while (true) {
+      let cellStart = rowXml.indexOf('<a:tc>', searchFrom);
+      if (cellStart === -1) {
+        cellStart = rowXml.indexOf('<a:tc ', searchFrom);
+      }
+      if (cellStart === -1) break;
+
+      const cellEnd = rowXml.indexOf('</a:tc>', cellStart);
+      if (cellEnd === -1) break;
+
+      cells.push(rowXml.substring(cellStart, cellEnd + '</a:tc>'.length));
+      searchFrom = cellEnd + '</a:tc>'.length;
+    }
+
+    return cells;
+  }
+
+  /**
+   * Replaces the text content of a table cell.
+   * Preserves all formatting (borders, colors, fonts) and only changes <a:t> content.
+   *
+   * @private
+   * @param {string} cellXml - Cell XML template.
+   * @param {string} text - New text content.
+   * @returns {string} Updated cell XML.
+   */
+  #setCellText(cellXml, text) {
+    const escapedText = this.#escapeXml(String(text));
+
+    // If there's an existing <a:t> element, replace its content
+    const tPattern = /(<a:t>)(.*?)(<\/a:t>)/;
+    if (tPattern.test(cellXml)) {
+      // Only replace the first <a:t> to avoid touching other text runs
+      return cellXml.replace(tPattern, `$1${escapedText}$3`);
+    }
+
+    // If no <a:t> exists, inject one inside the first text run
+    const rPattern = /(<a:r[^>]*>)([\s\S]*?)(<\/a:r>)/;
+    if (rPattern.test(cellXml)) {
+      return cellXml.replace(rPattern, `$1$2<a:t>${escapedText}</a:t>$3`);
+    }
+
+    // Fallback: inject a basic text paragraph
+    const txBodyPattern = /(<a:txBody>)([\s\S]*?)(<\/a:txBody>)/;
+    if (txBodyPattern.test(cellXml)) {
+      return cellXml.replace(
+        txBodyPattern,
+        `$1<a:p><a:r><a:t>${escapedText}</a:t></a:r></a:p>$3`
+      );
+    }
+
+    return cellXml;
+  }
+
+  /**
+   * Finds the position of the closing tag that matches an opening at searchFrom.
+   * @private
+   * @param {string} xml
+   * @param {string} closingTag
+   * @param {number} searchFrom
+   * @returns {number} Index of closing tag or -1.
+   */
+  #findClosingTag(xml, closingTag, searchFrom) {
+    return xml.indexOf(closingTag, searchFrom);
+  }
+
+  /**
+   * Escapes regex special characters.
+   * @private
+   * @param {string} str
+   * @returns {string}
+   */
+  #escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Escapes XML special characters.
+   * @private
+   * @param {string} str
+   * @returns {string}
+   */
+  #escapeXml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  /**
+   * Inspects a slide's table structure (for debugging).
+   *
+   * @param {number} slideIndex
+   * @param {SlideManager} slideManager
+   * @returns {Array<{name: string, id: string, rows: number, cols: number}>}
+   */
+  inspectTables(slideIndex, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex);
+    const tables = [];
+
+    // Find all graphicFrames with table data
+    const framePattern = /<p:graphicFrame>([\s\S]*?)<\/p:graphicFrame>/g;
+    let match;
+
+    while ((match = framePattern.exec(slideXml)) !== null) {
+      const frameXml = match[1];
+      if (!frameXml.includes('<a:tbl>')) continue;
+
+      const nameMatch = /name="([^"]*)"/.exec(frameXml);
+      const idMatch = /id="([^"]*)"/.exec(frameXml);
+      const rows = this.#extractAllRows(frameXml);
+      const cols = rows[0] ? this.#extractCells(rows[0]).length : 0;
+
+      tables.push({
+        name: nameMatch ? nameMatch[1] : 'unnamed',
+        id: idMatch ? idMatch[1] : 'unknown',
+        rows: rows.length,
+        cols,
+      });
+    }
+
+    return tables;
+  }
+}

package/src/managers/ZipManager.js

@@ -0,0 +1,298 @@
+/**
+ * @fileoverview ZipManager - Handles PPTX ZIP archive operations.
+ *
+ * A PPTX file is a ZIP archive following the Open Packaging Convention (OPC).
+ * This manager wraps JSZip to provide:
+ *  - Loading and parsing PPTX ZIP archives
+ *  - Reading individual XML parts
+ *  - Writing/replacing individual XML parts
+ *  - Re-packaging the modified archive
+ *  - Media file deduplication
+ *
+ * ZipManager is the lowest layer — all other managers use it to read/write
+ * raw file content within the ZIP.
+ */
+
+import JSZip from 'jszip';
+import fsExtra from 'fs-extra';
+import { createLogger } from '../utils/logger.js';
+import { PPTXError } from '../utils/errors.js';
+import { BLANK_PPTX_BASE64 } from '../templates/blankPptx.js';
+
+const logger = createLogger('ZipManager');
+
+/**
+ * @class ZipManager
+ * @description Manages the PPTX ZIP archive — reading, modifying, and re-packaging it.
+ *
+ * All file paths within the ZIP use forward slashes (e.g., 'ppt/slides/slide1.xml').
+ */
+export class ZipManager {
+  /**
+   * @private
+   * @type {JSZip}
+   */
+  #zip = null;
+
+  /**
+   * @private
+   * @type {Map<string, string>} Cache of decoded XML strings for fast repeated access.
+   */
+  #xmlCache = new Map();
+
+  /**
+   * @private
+   * @type {Map<string, string>} Dirty (modified) files that need to be re-written.
+   */
+  #dirtyFiles = new Map();
+
+  /**
+   * @private
+   * @type {Map<string, string>} Core properties (dc:title, dc:creator, etc.)
+   */
+  #coreProperties = new Map();
+
+  /**
+   * Loads a PPTX file from a path or Buffer.
+   *
+   * @param {string|Buffer} source - File path or Buffer.
+   * @returns {Promise<void>}
+   * @throws {PPTXError} If the file cannot be read or parsed as a ZIP.
+   */
+  async load(source) {
+    try {
+      let data;
+      if (typeof source === 'string') {
+        logger.debug(`Reading file: ${source}`);
+        data = await fsExtra.readFile(source);
+      } else if (Buffer.isBuffer(source) || source instanceof Uint8Array) {
+        data = source;
+      } else {
+        throw new PPTXError(`Invalid source type: ${typeof source}. Expected string path or Buffer.`);
+      }
+
+      this.#zip = await JSZip.loadAsync(data);
+      await this.#loadCoreProperties();
+      logger.debug(`ZIP loaded successfully. Files: ${Object.keys(this.#zip.files).length}`);
+    } catch (err) {
+      if (err instanceof PPTXError) throw err;
+      throw new PPTXError(`Failed to load PPTX: ${err.message}`, err);
+    }
+  }
+
+  /**
+   * Creates a blank PPTX structure from the embedded minimal template.
+   * @returns {Promise<void>}
+   */
+  async createBlank() {
+    const buffer = Buffer.from(BLANK_PPTX_BASE64, 'base64');
+    this.#zip = await JSZip.loadAsync(buffer);
+    await this.#loadCoreProperties();
+    logger.debug('Created blank PPTX structure');
+  }
+
+  /**
+   * Reads and caches a text file from the ZIP archive.
+   *
+   * @param {string} zipPath - Path within the ZIP (e.g., 'ppt/slides/slide1.xml').
+   * @returns {Promise<string|null>} File content as UTF-8 string, or null if not found.
+   */
+  async readFile(zipPath) {
+    // Normalize path separators
+    const normalPath = zipPath.replace(/\\/g, '/');
+
+    // Return cached version if available and not dirty
+    if (this.#xmlCache.has(normalPath) && !this.#dirtyFiles.has(normalPath)) {
+      return this.#xmlCache.get(normalPath);
+    }
+
+    // Check dirty files (pending writes)
+    if (this.#dirtyFiles.has(normalPath)) {
+      return this.#dirtyFiles.get(normalPath);
+    }
+
+    const file = this.#zip.file(normalPath);
+    if (!file) {
+      logger.debug(`File not found in ZIP: ${normalPath}`);
+      return null;
+    }
+
+    const content = await file.async('text');
+    this.#xmlCache.set(normalPath, content);
+    return content;
+  }
+
+  /**
+   * Reads a binary file from the ZIP archive.
+   *
+   * @param {string} zipPath - Path within the ZIP.
+   * @returns {Promise<Uint8Array|null>} Binary content or null if not found.
+   */
+  async readBinaryFile(zipPath) {
+    const normalPath = zipPath.replace(/\\/g, '/');
+    const file = this.#zip.file(normalPath);
+    if (!file) return null;
+    return file.async('uint8array');
+  }
+
+  /**
+   * Writes (or overwrites) a text file in the ZIP archive.
+   * Changes are buffered and applied when generating the output ZIP.
+   *
+   * @param {string} zipPath - Path within the ZIP.
+   * @param {string} content - UTF-8 string content.
+   */
+  writeFile(zipPath, content) {
+    const normalPath = zipPath.replace(/\\/g, '/');
+    this.#dirtyFiles.set(normalPath, content);
+    this.#xmlCache.set(normalPath, content);
+    // Also write to the underlying JSZip object
+    this.#zip.file(normalPath, content);
+    logger.debug(`Queued write: ${normalPath}`);
+  }
+
+  /**
+   * Writes a binary file to the ZIP archive.
+   *
+   * @param {string} zipPath - Path within the ZIP.
+   * @param {Buffer|Uint8Array} data - Binary data.
+   */
+  writeBinaryFile(zipPath, data) {
+    const normalPath = zipPath.replace(/\\/g, '/');
+    this.#zip.file(normalPath, data);
+    logger.debug(`Queued binary write: ${normalPath}`);
+  }
+
+  /**
+   * @private
+   * @type {Promise[]}
+   */
+  #pendingPromises = [];
+
+  /**
+   * Adds a promise to the pending queue to be awaited before saving.
+   * @param {Promise} promise
+   */
+  addPendingPromise(promise) {
+    this.#pendingPromises.push(promise);
+  }
+
+  /**
+   * Waits for all pending asynchronous operations (like async ZIP reads/writes) to complete.
+   * @returns {Promise<void>}
+   */
+  async waitForPendingWrites() {
+    if (this.#pendingPromises.length > 0) {
+      await Promise.all(this.#pendingPromises);
+      this.#pendingPromises = [];
+    }
+  }
+
+  /**
+   * Removes a file from the ZIP archive.
+   *
+   * @param {string} zipPath - Path to remove.
+   */
+  removeFile(zipPath) {
+    const normalPath = zipPath.replace(/\\/g, '/');
+    this.#zip.remove(normalPath);
+    this.#xmlCache.delete(normalPath);
+    this.#dirtyFiles.delete(normalPath);
+  }
+
+  /**
+   * Checks if a file exists in the ZIP archive.
+   *
+   * @param {string} zipPath - Path to check.
+   * @returns {boolean}
+   */
+  hasFile(zipPath) {
+    const normalPath = zipPath.replace(/\\/g, '/');
+    return this.#zip.file(normalPath) !== null;
+  }
+
+  /**
+   * Lists all files in the ZIP archive matching an optional prefix.
+   *
+   * @param {string} [prefix] - Optional path prefix filter.
+   * @returns {string[]} Array of matching file paths.
+   */
+  listFiles(prefix = '') {
+    return Object.keys(this.#zip.files).filter(
+      f => !this.#zip.files[f].dir && f.startsWith(prefix)
+    );
+  }
+
+  /**
+   * Generates the final ZIP archive as a Buffer.
+   * All pending changes are applied before compressing.
+   *
+   * @returns {Promise<Buffer>} Compressed PPTX as a Buffer.
+   */
+  async toBuffer() {
+    return this.#zip.generateAsync({
+      type: 'nodebuffer',
+      compression: 'DEFLATE',
+      compressionOptions: { level: 6 },
+    });
+  }
+
+  /**
+   * Generates the final ZIP archive as a readable Stream.
+   *
+   * @returns {Promise<NodeJS.ReadableStream>}
+   */
+  async toStream() {
+    return this.#zip.generateNodeStream({
+      type: 'nodebuffer',
+      compression: 'DEFLATE',
+      compressionOptions: { level: 6 },
+      streamFiles: true,
+    });
+  }
+
+  /**
+   * Returns a core document property (from docProps/core.xml).
+   *
+   * @param {string} key - Property key (e.g., 'dc:title', 'dc:creator').
+   * @returns {string|undefined}
+   */
+  getCoreProperty(key) {
+    return this.#coreProperties.get(key);
+  }
+
+  /**
+   * Sets a core document property.
+   * Updates docProps/core.xml in the ZIP.
+   *
+   * @param {string} key - Property key.
+   * @param {string} value - Property value.
+   */
+  setCoreProperty(key, value) {
+    this.#coreProperties.set(key, value);
+  }
+
+  /**
+   * Parses and loads core properties from docProps/core.xml.
+   * @private
+   */
+  async #loadCoreProperties() {
+    const coreXml = await this.readFile('docProps/core.xml');
+    if (!coreXml) return;
+
+    // Simple regex extraction for core properties (lightweight vs full parse)
+    const propPattern = /<(dc:[a-zA-Z]+|dcterms:[a-zA-Z]+)[^>]*>([^<]*)<\/\1>/g;
+    let match;
+    while ((match = propPattern.exec(coreXml)) !== null) {
+      this.#coreProperties.set(match[1], match[2]);
+    }
+  }
+
+  /**
+   * Returns the raw JSZip instance (for advanced use cases).
+   * @returns {JSZip}
+   */
+  get rawZip() {
+    return this.#zip;
+  }
+}