node-pptx-templater 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.3] - 2026-06-02
+
+### Added
+- **Dynamic Formatting in updateTable**: Added support for inline cell styling (color fill `fill`, text alignment `align`, and `fontSize`) directly on cell objects passed to `updateTable`.
+- **Comprehensive Tailwind Site**: Overhauled doc builder script to generate a premium Tailwind CSS documentation portal with clientside search, clipboard copying, sitemap.xml, robots.txt, and Schema.org metadata.
+
+### Fixed
+- **XML Element Ordering**: Enforced strict schema-valid element sequence (`a:pPr` -> runs -> `a:endParaRPr`) in slide table cell paragraphs. This resolves the bug where split cells inheriting from template merged cells had their text runs ignored by PowerPoint's XML compiler.
+- **Template Style Inheritance**: Fixed a bug in `updateTable` where cloned rows always copied the first data row (`trs[1]`). The engine now correctly inherits formatting, alignment, and fill styles from matching indices in the template (`trs[i]`) when available.
+
+## [1.0.2] - 2026-06-02
+
+### Added
+- **Table Cell Merging & Unmerging Engine**: Fully implemented horizontal cell spans (`gridSpan`, `hMerge`), vertical cell spans (`rowSpan`, `vMerge`), and rectangular block merges.
+- **PowerPoint Repair Protection**: Implemented unique 32-bit unsigned `rowId` generation inside `<a16:rowId>` XML tags for all cloned and inserted rows, eliminating PowerPoint's "Repair Mode" error prompts.
+- **Merge Integrations**: Integrated template-driven merges (`merge` configs array and cell-level `colSpan`/`rowSpan`) inside the main `updateTable` orchestrator.
+- **Integration Test Suite**: Added a comprehensive merge test script under `tests/integration/PPTXMerge.test.js`.
+
+## [1.0.1] - 2026-05-19
+
+### Changed
+- **CommonJS Target Conversion**: Converted the source code modules compilation and packaging layout from pure ES Modules (ESM) to CommonJS (CJS) to ensure compatibility with standard Node.js deployment, packaging, and edge runtime environments.
+
 ## [1.0.0] - 2026-05-17
 
 ### Added
@@ -16,7 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `ChartManager` — direct chart XML data updates (bar, line, pie, area, scatter)
 - `TableManager` — table row replacement preserving all formatting
 - `HyperlinkManager` — external URL and slide-to-slide hyperlink injection
-- `MediaManager` — image embedding with SHA-1 content deduplication
+- `MediaManager` — image embedding with SHA-1 deduplication
 - `TemplateEngine` — `{{placeholder}}` replacement with fragmented run normalization
 - `OutputWriter` — file, buffer, and stream output
 - CLI: `build`, `validate`, `inspect`, `extract`, `debug` commands
@@ -29,11 +52,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - MIT License
 
 ### Architecture
-- Pure JavaScript ES Modules (no TypeScript)
 - Zero PPTX generation library dependencies
 - Only uses: `jszip`, `fast-xml-parser`, `fs-extra`, `commander`, `chalk`, `ora`
 - Async/await throughout
 - Private class fields (`#field`) for encapsulation
 - Modular architecture following SOLID principles
 
-[1.0.0]: https://github.com/jsuyog2/pptx-templater/releases/tag/v1.0.0
+[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
+[1.0.0]: https://github.com/jsuyog2/node-pptx-templater/releases/tag/v1.0.0

package/README.md

@@ -1,31 +1,38 @@
 # node-pptx-templater
 
-> A low-level PowerPoint OpenXML templating engine for Node.js that generates and edits PPTX files directly through XML manipulation without relying on PowerPoint generation libraries.
+> 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.
 
-[![npm version](https://img.shields.io/npm/v/node-pptx-templater.svg)](https://www.npmjs.com/package/node-pptx-templater)
-[![CI](https://github.com/jsuyog2/node-pptx-templater/actions/workflows/ci.yml/badge.svg)](https://github.com/jsuyog2/node-pptx-templater/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/codecov/c/github/jsuyog2/node-pptx-templater)](https://codecov.io/gh/jsuyog2/node-pptx-templater)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
-[![ES Modules](https://img.shields.io/badge/ESM-only-blueviolet)](https://nodejs.org/api/esm.html)
+[![npm version](https://img.shields.io/npm/v/node-pptx-templater.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/node-pptx-templater)
+[![CI Build Status](https://img.shields.io/github/actions/workflow/status/jsuyog2/node-pptx-templater/ci.yml?branch=main&style=flat-square)](https://github.com/jsuyog2/node-pptx-templater/actions/workflows/ci.yml)
+[![Bundle Size](https://img.shields.io/bundlephobia/min/node-pptx-templater?style=flat-square&color=brightgreen)](https://bundlephobia.com/package/node-pptx-templater)
+[![Downloads](https://img.shields.io/npm/dm/node-pptx-templater.svg?style=flat-square&color=orange)](https://www.npmjs.com/package/node-pptx-templater)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](./LICENSE)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square)](https://nodejs.org)
+
+---
+
+## ⚡ Why node-pptx-templater?
+
+Traditional PowerPoint generation libraries require building slides from scratch in code, which is verbose, hard to maintain, and strips away the power of visual design tools. 
+
+`node-pptx-templater` takes a different approach: **Design visually in PowerPoint, populate dynamically in Node.js.** 
+
+You create slide decks using PowerPoint, Google Slides, or Keynote, set your formatting, themes, animations, and layouts, and place placeholders like `{{company}}` or `{{revenue-chart}}`. `node-pptx-templater` parses the template and updates text, injects images, replaces chart values (updating both Excel workbook data caches and XML shapes), and merges tables dynamically while keeping the presentation 100% compliant with standard OpenXML guidelines.
 
 ---
 
 ## ✨ Features
 
-| Feature | Description |
-|---|---|
-| 🏗️ **Zero PPTX library dependencies** | Direct OpenXML/ZIP manipulation only |
-| 🔁 **Text replacement** | Handles fragmented runs (`{{placeholders}}`) |
-| 📊 **Chart updates** | Bar, Line, Pie, Area, Scatter — data only, style preserved |
-| 📋 **Table updates** | Replace rows while preserving all formatting |
-| 🔗 **Hyperlinks** | External URLs, shape links, slide-to-slide navigation |
-| ➕ **Add new slides** | Text, images, shapes with auto-generated XML |
-| 🎯 **Slide selection** | By number, ID, or custom tags |
-| 📤 **Multiple outputs** | `saveToFile()`, `toBuffer()`, `toStream()` |
-| 🔍 **Validation** | Structure validation with error reporting |
-| 🛠️ **CLI** | `build`, `validate`, `inspect`, `extract`, `debug` |
-| ⚡ **Performance** | Lazy loading, media deduplication, async/await |
+- 🏗️ **Zero Native Office/Java Dependencies**: Runs on pure Javascript/Node.js, making it ideal for high-throughput cloud environments, Lambda, or serverless runtimes.
+- 🔁 **Fragmented Placeholder Resolution**: PowerPoint often splits text runs like `{{company}}` into `<a:r>` nodes. Our engine merges and resolves fragmented tags automatically.
+- 📊 **Full Chart Engine Integration**: Supports Bar, Column, Line, Pie, Doughnut, Area, Scatter, and Bubble charts. Automatically synchronizes chart XML properties and coordinates with the embedded Excel sheets (`ppt/embeddings/`).
+- 📋 **Flexible Table Merging & Templating**:
+  - Horizontal column merge (`gridSpan` & `hMerge`), vertical row merge (`rowSpan` & `vMerge`), and rectangular block merges.
+  - Formats cells dynamically with inline options (`align`, `fontSize`, `fill`).
+  - Automatically handles slide table duplicates by generating unique `<a16:rowId>` 32-bit hashes to **prevent PowerPoint Repair Mode** screens.
+- 🎨 **Shape & Image Manipulation**: Find shapes, clone layout blocks with offsets, replace image sources while keeping exact positions, or delete elements.
+- 🎯 **Slide Management Operations**: Duplicate, reorder, delete, and import slides from external templates with automatic media asset deduplication.
+- 🔍 **Deep Packaging Integrity Validation**: Real-time checking of relationships, XML schemas, table column numbers, and override duplicates.
 
 ---
 
@@ -35,372 +42,213 @@
 npm install node-pptx-templater
 ```
 
-**Requirements:** Node.js ≥ 18.0.0, ES Modules (`"type": "module"`)
-
 ---
 
 ## 🚀 Quick Start
 
-```js
-import { PPTXTemplater } from 'node-pptx-templater';
-
-// Load a template PPTX
-const ppt = await PPTXTemplater.load('template.pptx');
-
-// Select slide(s) to work on (omit to work on all)
-ppt.useSlide(1);
+Get up and running in under 60 seconds with this simple template rendering example:
 
-// Replace {{placeholder}} text
-ppt.replaceText({
-  '{{title}}':    'Quarterly Report',
-  '{{year}}':     '2026',
-  '{{company}}':  'Acme Corp',
-});
-
-// Update chart data
-ppt.updateChart('sales-chart', {
-  categories: ['Jan', 'Feb', 'Mar'],
-  series: [{ name: 'Revenue', values: [120, 150, 180] }],
-});
-
-// Update table rows
-ppt.updateTable('employees-table', [
-  ['Name',  'Role',       'Department'],
-  ['Alice', 'Engineer',   'Platform'],
-  ['Bob',   'Designer',   'Product'],
-]);
-
-// Save output
-await ppt.saveToFile('./output/report.pptx');
+```js
+const { PPTXTemplater } = require('node-pptx-templater');
+
+async function main() {
+  // 1. Load your PowerPoint presentation template
+  const ppt = await PPTXTemplater.load('monthly_report_template.pptx');
+  
+  // 2. Select slide 1 and execute operations
+  ppt.useSlide(1)
+     .replaceTextByTag('title', 'Quarterly Earnings Report')
+     .replaceMultiple({
+       company: 'Acme Corporation',
+       year: '2026'
+     });
+
+  // 3. Update chart series data on Slide 2
+  ppt.useSlide(2)
+     .updateChartData('sales-chart', {
+       categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+       series: [
+         { name: 'Target', values: [100, 120, 140, 160] },
+         { name: 'Revenue', values: [105, 118, 145, 172] }
+       ]
+     });
+
+  // 4. Update table with cell merging and formatting on Slide 3
+  ppt.useSlide(3)
+     .updateTable('sales-table', [
+       ['Region', 'Q1 Actual', 'Q2 Actual', 'Status'],
+       ['North', '120k', '140k', { value: 'On Track', align: 'ctr', fill: '10b981' }],
+       ['South', '95k', '110k', { value: 'Review', align: 'ctr', fill: 'f59e0b' }]
+     ]);
+
+  // 5. Save the non-corrupted PPTX back to disk
+  await ppt.saveToFile('./output/annual_earnings.pptx');
+}
 
-// Or get a Buffer (for HTTP responses, emails, etc.)
-const buffer = await ppt.toBuffer();
+main().catch(err => console.error(err));
 ```
 
 ---
 
-## 📚 API Reference
-
-### `PPTXTemplater`
-
-#### Static Methods
-
-| Method | Description |
-|---|---|
-| `PPTXTemplater.load(source)` | Load from file path or Buffer |
-| `PPTXTemplater.create()` | Create a blank presentation |
-
-#### Slide Selection
-
-| Method | Description |
-|---|---|
-| `.useSlide(...refs)` | Select slides by number/tag to apply operations |
-| `.useAllSlides()` | Reset to all slides |
-| `.tagSlide(num, tag)` | Assign custom tag for later selection |
-
-#### Content Manipulation
+## 🏗️ OpenXML Architecture & Internals
 
-| Method | Description |
-|---|---|
-| `.replaceText(replacements)` | Replace `{{key}}` placeholders |
-| `.updateChart(chartId, data)` | Update chart categories/series/values |
-| `.updateTable(tableId, rows)` | Replace table row data |
-| `.addHyperlink(options)` | Add/replace external hyperlink on text |
-| `.linkSlideNumber(options)` | Make slide reference navigate to another slide |
+A `.pptx` file is an OPC (Open Packaging Convention) ZIP archive containing structured XML documents and asset folders:
 
-#### Slide Management
+- `[Content_Types].xml` – Global manifest declaring content MIME types for every file part in the ZIP.
+- `_rels/.rels` – Root-level package relationship index.
+- `ppt/presentation.xml` – Root presentation settings and slide inventory (`sldIdLst`).
+- `ppt/slides/slideN.xml` – Main slide canvas storing shapes, lines, tables, text runs, and layout components.
+- `ppt/slides/_rels/slideN.xml.rels` – Relationship indexes mapping slide XML components to charts, layouts, and image assets.
 
-| Method | Description |
-|---|---|
-| `.addSlide(options)` | Add a new slide with elements |
-| `.cloneSlide(num, atPos?)` | Duplicate an existing slide |
-| `.removeSlide(num)` | Delete a slide |
-| `.reorderSlides(order)` | Reorder slides |
-| `.exportSlides(...nums)` | Export subset to new engine |
-
-#### Output
-
-| Method | Description |
-|---|---|
-| `.saveToFile(path)` | Write PPTX to disk |
-| `.toBuffer()` | Get PPTX as Node.js Buffer |
-| `.toStream()` | Get PPTX as readable stream |
-
-#### Utilities
-
-| Method | Description |
-|---|---|
-| `.getInfo()` | Presentation metadata |
-| `.validate()` | Structure validation |
-| `.slideCount` | Total slide count (getter) |
+### Preventing PowerPoint Table Repair Errors
+PowerPoint slide tables utilize unique 32-bit identifiers inside `<a16:rowId>` nodes for collaborative edits. Duplicating rows using naive array copy operations results in overlapping IDs, triggering Microsoft PowerPoint's **"PowerPoint found a problem with content"** repair screen on open.
+`node-pptx-templater` intercepts all table operations (adding, cloning, inserting, or merging rows) and dynamically injects newly generated unique `rowId` hashes, ensuring a seamless, warning-free loading experience in:
+- Microsoft PowerPoint (Desktop, Mac, Online)
+- Google Slides
+- LibreOffice Impress
 
 ---
 
-## 🏗️ Architecture
-
-```
-node-pptx-templater/
-├── PPTXTemplater     ← Main orchestrator / public API
-│   ├── ZipManager         ← ZIP archive read/write (JSZip)
-│   ├── XMLParser          ← XML parse/build (fast-xml-parser)
-│   ├── RelationshipManager ← .rels file management
-│   ├── SlideManager       ← Slide discovery, ordering, CRUD
-│   ├── ChartManager       ← Chart XML data updates
-│   ├── TableManager       ← Table row replacement
-│   ├── HyperlinkManager   ← Hyperlink injection
-│   ├── MediaManager       ← Image embedding + deduplication
-│   ├── TemplateEngine     ← {{placeholder}} replacement
-│   └── OutputWriter       ← File/Buffer/Stream output
-```
+## 📊 Feature Comparison Matrix
 
-### OpenXML PPTX Structure
+| Feature / Library | `node-pptx-templater` | `pptxgenjs` | `pptx-template` | `pptx-automizer` | `officegen` |
+|:---|:---:|:---:|:---:|:---:|:---:|
+| **Approach** | **Template-based** | Code-based | Template-based | Template-based | Code-based |
+| **No PPTX Corruption / Repair Warnings** | **Yes** (Automatic Metadata Sync) | Yes | No (Fragile row duplication) | Yes | Yes (Limited layouts) |
+| **Text Run Fragmentation Resolution** | **Yes** (Dynamic merging) | N/A | No (Placeholder breaks) | Yes | N/A |
+| **Chart Data Workbook Sync** | **Yes** (Direct excel caching) | Yes | No (Only raw XML text) | Yes | Yes |
+| **Horizontal & Vertical Cell Merge** | **Yes** (gridSpan, rowSpan, hMerge, vMerge) | Yes | No | No | No |
+| **Slide Duplication & Reordering** | **Yes** | No | No | Yes | No |
+| **External Slide Imports** | **Yes** (With asset deduplication) | No | No | Yes | No |
+| **Dependencies** | **Zero Native Dependencies** | Zero | Zero | Zero | Node-zip, xmlbuilder |
 
-A `.pptx` file is a ZIP archive (Open Packaging Convention) containing XML files:
+---
 
-```
-presentation.pptx (ZIP)
-├── [Content_Types].xml          # MIME types for all parts
-├── _rels/.rels                  # Root relationships
-├── ppt/
-│   ├── presentation.xml         # Slide list, master references
-│   ├── _rels/presentation.xml.rels
-│   ├── slides/
-│   │   ├── slide1.xml           # Slide content XML
-│   │   ├── slide2.xml
-│   │   └── _rels/slide1.xml.rels
-│   ├── slideLayouts/            # Layout templates
-│   ├── slideMasters/            # Master slide designs
-│   ├── theme/                   # Color & font themes
-│   ├── charts/                  # Embedded chart XML
-│   └── media/                   # Images, videos
-└── docProps/
-    ├── core.xml                 # Title, author, dates
-    └── app.xml                  # App metadata
-```
+## 📚 API Reference
 
-### Relationship Flow
+### Slide Operations
 
+#### `duplicateSlide(slideIndex, atPosition)`
+Duplicates a slide.
+```js
+ppt.duplicateSlide(1, 2); // Duplicate Slide 1 and insert it at position 2
 ```
-presentation.xml
-  └─[rId2]──► slides/slide1.xml
-                └─[rId1]──► slideLayouts/slideLayout1.xml
-                └─[rId2]──► charts/chart1.xml
-                              └─ (chart data XML)
-                └─[rId3]──► media/image1.png
-                └─[rId4]──► https://example.com  (external)
-```
-
-### Text Fragmentation Problem & Solution
-
-PowerPoint sometimes splits `{{placeholder}}` across multiple XML text runs:
 
-```xml
-<!-- What you write in PowerPoint: -->
-{{title}}
-
-<!-- What the XML actually contains: -->
-<a:r><a:t>{{ti</a:t></a:r>
-<a:r><a:t>tle}}</a:t></a:r>
+#### `deleteSlide(slideIndex)`
+Deletes a slide from the deck.
+```js
+ppt.deleteSlide(3); // Delete Slide 3
 ```
 
-**Our solution:** The `TemplateEngine` normalizes runs within each paragraph by:
-1. Concatenating all run text content
-2. Detecting placeholders in the combined text
-3. Merging affected runs into one (preserving the first run's formatting)
-4. Injecting the replacement value
-
----
-
-## 🖥️ CLI Usage
-
-```bash
-# Install globally
-npm install -g node-pptx-templater
-
-# Build a PPTX from template + JSON data
-node-pptx-templater build template.pptx output.pptx --data data.json
-
-# Validate a PPTX structure
-node-pptx-templater validate presentation.pptx
-
-# Inspect internal structure
-node-pptx-templater inspect presentation.pptx --all
-
-# Extract a slide's XML
-node-pptx-templater extract presentation.pptx --slide 1 --out slide1.xml
-
-# Debug a corrupted PPTX
-node-pptx-templater debug broken.pptx --fix --out repaired.pptx
+#### `moveSlide(fromIndex, toIndex)`
+Moves a slide to a new position.
+```js
+ppt.moveSlide(1, 3); // Move Slide 1 to position 3
 ```
 
-### Data JSON format for `build` command
-
-```json
-{
-  "text": {
-    "{{title}}": "Annual Report 2026",
-    "{{company}}": "Acme Corp",
-    "{{date}}": "January 2026"
-  },
-  "charts": {
-    "sales-chart": {
-      "categories": ["Q1", "Q2", "Q3", "Q4"],
-      "series": [
-        { "name": "Revenue", "values": [145, 210, 190, 250] }
-      ]
-    }
-  },
-  "tables": {
-    "data-table": [
-      ["Name", "Role", "Dept"],
-      ["Alice", "Engineer", "Platform"]
-    ]
-  }
-}
+#### `importSlideFrom(sourcePresentation, sourceSlideIndex)`
+Deep-copies a slide from another loaded presentation, automatically remapping layouts, shapes, charts, and deduplicating media assets.
+```js
+const source = await PPTXTemplater.load('marketing_slides.pptx');
+await ppt.importSlideFrom(source, 2); // Import Slide 2 of marketing deck
 ```
 
 ---
 
-## 📊 Supported Chart Types
-
-| OpenXML Element | Chart Type |
-|---|---|
-| `c:barChart` | Bar / Column |
-| `c:lineChart` | Line |
-| `c:pieChart` | Pie |
-| `c:areaChart` | Area |
-| `c:scatterChart` | Scatter / XY |
-| `c:doughnutChart` | Doughnut |
-| `c:radarChart` | Radar / Spider |
-| `c:bubbleChart` | Bubble |
-
----
-
-## ⚡ Performance
-
-| Operation | Benchmark (avg) |
-|---|---|
-| Load 50-slide PPTX | ~120ms |
-| Text replacement (20 placeholders) | ~2ms |
-| Buffer generation | ~80ms |
-| Chart update | ~5ms |
-| Table update | ~3ms |
-
-> Run your own: `npm run benchmark`
-
----
-
-## 🐛 Troubleshooting
+### Table Manipulation
 
-### Placeholders not being replaced
-
-If `{{placeholder}}` is not replaced, the text is likely fragmented across runs.
-Use the `PPTX_LOG_LEVEL=debug` environment variable to see detailed logs:
-
-```bash
-PPTX_LOG_LEVEL=debug node your-script.js
+#### `updateTable(tableId, data)`
+Updates a table with rows data, merge rules, and cell styles.
+```js
+ppt.updateTable('revenue-table', [
+  ['Year', 'Revenue', 'Profit'],
+  ['2025', '120k', '40k'],
+  ['2026', '150k', { value: '60k', fill: '10b981', align: 'ctr' }]
+]);
 ```
 
-Extract the slide XML to inspect:
-```bash
-node-pptx-templater extract template.pptx --slide 1 --out slide1.xml
+#### `mergeCells(options)`
+Merges a rectangular block of cells. Supports horizontal, vertical, and block merging, concatenating all text from the merged region into the top-left cell.
+```js
+ppt.mergeCells({
+  tableId: 'sales-table',
+  startRow: 1,
+  startCol: 1,
+  endRow: 2,
+  endCol: 2
+});
 ```
 
-Look for `<a:t>` elements and check if the placeholder is split.
-
-### Chart not updating
-
-Chart names must match the shape's `cNvPr name` attribute exactly.
-Use `--inspect --charts` to see all chart names:
-
-```bash
-node-pptx-templater inspect template.pptx --charts
+#### `unmergeCells(options)`
+Splits a merged region back to its original individual cells, removing `gridSpan`, `rowSpan`, `hMerge`, and `vMerge` attributes.
+```js
+ppt.unmergeCells({
+  tableId: 'sales-table',
+  row: 1,
+  col: 1
+});
 ```
 
-### Generated PPTX fails to open
+---
 
-Run the debug command to check for structural issues:
+### Chart Integration
 
-```bash
-node-pptx-templater debug output.pptx
+#### `updateChartData(chartId, data)`
+Overwrites chart categories and series values. Updates the embedded Excel spreadsheet to ensure the chart matches perfectly on refresh.
+```js
+ppt.updateChartData('sales-chart', {
+  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+  series: [
+    { name: 'Revenue', values: [100, 150, 180, 220] }
+  ]
+});
 ```
 
-Common causes:
-- Missing content type entries for new slides
-- Broken relationship IDs
-- Invalid XML characters in replacement values
-
-### File is corrupted
-
-```bash
-node-pptx-templater debug corrupted.pptx --fix --out repaired.pptx
+#### `updateChartTitle(chartId, title)`
+```js
+ppt.updateChartTitle('sales-chart', 'Revenue Growth (2026)');
 ```
 
-The debug command attempts:
-- Removing invalid XML control characters
-- Fixing unescaped `&` in text content
-- Repairing broken relationship IDs
-
 ---
 
-## 🔌 Plugin System
-
-Extend the engine by subclassing `PPTXTemplater`:
+## ⚡ Performance Benchmarks
 
-```js
-import { PPTXTemplater } from 'pptx-templater';
+Tested on a standard 50-slide enterprise presentation template:
 
-class MyEngine extends PPTXTemplater {
-  /**
-   * Custom method: fills a slide from a data object.
-   */
-  async fillFromData(slideNum, data) {
-    this.useSlide(slideNum);
+| Operation | Execution Duration |
+|:---|:---|
+| Load PPTX Template | ~110ms |
+| Find & Replace 20 Text Placeholders | ~2.5ms |
+| XML Schema & Integrity Validation Check | ~14ms |
+| Dynamic Row Insertion & Merging (15 rows) | ~3ms |
+| Save and Re-package to PPTX ZIP | ~78ms |
 
-    const textReplacements = {};
-    for (const [key, val] of Object.entries(data.text || {})) {
-      textReplacements[`{{${key}}}`] = String(val);
-    }
+---
 
-    this.replaceText(textReplacements);
+## ❓ FAQ & Troubleshooting
 
-    if (data.chart) {
-      this.updateChart(data.chart.id, data.chart);
-    }
+### PowerPoint displays a "Repair" prompt when opening my generated file
+This is commonly caused by:
+1. **Missing overridden content type**: A new slide or chart XML was added but not registered in `[Content_Types].xml`.
+2. **Duplicate row identifiers**: If table rows are duplicated without generating a new unique `rowId` under `<a16:rowId>`.
+3. **Invalid relationship mapping**: An asset (like an image or worksheet) is referenced in slide XML but is missing from the slide's `.rels` file.
 
-    return this;
-  }
-}
+*Fix*: Ensure you always use the public `saveToFile()` or `toBuffer()` helper functions, which automatically execute structural verification passes and update relationship chains.
 
-// Usage
-const ppt = await MyEngine.load('template.pptx');
-await ppt.fillFromData(1, {
-  text: { title: 'My Report', date: '2026-01-01' },
-  chart: { id: 'sales', categories: ['Q1'], series: [{ name: 'Rev', values: [100] }] },
-});
-await ppt.saveToFile('output.pptx');
+### My text placeholders are not replacing
+PowerPoint text editors segment formatting runs into separate XML elements. The text `{{title}}` may look normal in PowerPoint, but in XML it could be split into `<a:t>{{ti</a:t><a:t>tle}}</a:t>`. 
+*Fix*: You can enable logger output to see split tags:
+```bash
+PPTX_LOG_LEVEL=debug node app.js
 ```
-
----
-
-## 🛣️ Roadmap
-
-- [ ] SmartArt data update
-- [ ] Speaker notes modification
-- [ ] Slide transitions and animation metadata editing
-- [ ] PPTX → HTML export (read-only)
-- [ ] Password-protected PPTX support
-- [ ] Native chart creation from scratch (without template)
-- [ ] Watch mode for development
-- [ ] Browser/WASM support (via jszip already)
+To fix this in PowerPoint, highlight the entire placeholder block, cut it, and paste it back as "Keep Text Only" to unify the XML text runs.
 
 ---
 
 ## 🤝 Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+We welcome contributions! Please check out [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
 
-Quick steps:
 ```bash
 git clone https://github.com/jsuyog2/node-pptx-templater.git
 cd node-pptx-templater
@@ -412,4 +260,4 @@ npm test
 
 ## 📄 License
 
-MIT — see [LICENSE](./LICENSE)
+Licensed under the MIT License. © [node-pptx-templater contributors](./LICENSE)