node-pptx-templater 1.0.1 → 1.0.3

package/README.md

@@ -7,25 +7,18 @@
 [![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)
 
 ---
 
 ## ✨ 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 PPTX Library Dependencies**: Operates entirely via low-level XML/ZIP manipulation.
+- 🔁 **Advanced Text Replacement**: Handles fragmented runs seamlessly (`{{placeholders}}`).
+- 📊 **Comprehensive Chart Support**: Bar, Column, Line, Pie, Doughnut, Area, Scatter—preserves original themes.
+- 📋 **Safe Table Updates**: Fully manages row insertion, deletion, merging, resizing, and cell formatting while maintaining PowerPoint integrity (prevents repair warnings by generating unique row IDs).
+- 🎨 **Shape & Image Manipulation**: Update text, clone, position, replace, or delete slide components.
+- 🎯 **Slide Operations**: Duplicate, reorder, insert, or delete slide parts on the fly.
+- 🔍 **Deep Integrity Validation**: Live validation of relationships, XML schema consistency, table columns, and duplicates prior to saving.
 
 ---
 
@@ -35,372 +28,434 @@
 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');
+const { PPTXTemplater } = require('node-pptx-templater');
+
+async function run() {
+  // Load presentation template
+  const ppt = await PPTXTemplater.load('template.pptx');
+  
+  // Use Slide 1 and replace text placeholders
+  ppt.useSlide(1)
+     .replaceTextByTag('title', 'Annual Sales Report')
+     .replaceMultiple({ company: 'Google DeepMind', year: '2026' });
+
+  // Update chart data on Slide 2
+  ppt.useSlide(2)
+     .updateChartData('sales-chart', {
+       categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+       series: [{ name: 'Revenue', values: [100, 150, 180, 220] }]
+     });
+
+  // Save the result (validates structural integrity automatically)
+  await ppt.saveToFile('output.pptx');
+}
+run();
+```
 
-// Select slide(s) to work on (omit to work on all)
-ppt.useSlide(1);
+---
 
-// Replace {{placeholder}} text
-ppt.replaceText({
-  '{{title}}':    'Quarterly Report',
-  '{{year}}':     '2026',
-  '{{company}}':  'Acme Corp',
-});
+## 🏗️ Architecture & OpenXML Internals
 
-// Update chart data
-ppt.updateChart('sales-chart', {
-  categories: ['Jan', 'Feb', 'Mar'],
-  series: [{ name: 'Revenue', values: [120, 150, 180] }],
-});
+A PPTX file is an OPC (Open Packaging Convention) ZIP containing XML parts:
 
-// Update table rows
-ppt.updateTable('employees-table', [
-  ['Name',  'Role',       'Department'],
-  ['Alice', 'Engineer',   'Platform'],
-  ['Bob',   'Designer',   'Product'],
-]);
+- `/ppt/presentation.xml` – The slides inventory (`sldIdLst`) and masters.
+- `/ppt/slides/slideN.xml` – Slide elements (shapes, images, tables).
+- `/ppt/slides/_rels/slideN.xml.rels` – Relationship links (`rId`).
+- `[Content_Types].xml` – Declares MIME types for slide parts, charts, and media.
 
-// Save output
-await ppt.saveToFile('./output/report.pptx');
-
-// Or get a Buffer (for HTTP responses, emails, etc.)
-const buffer = await ppt.toBuffer();
-```
+### The rowId Table Corruption Bug
+Microsoft PowerPoint assigns an `<a16:rowId>` identifier to each row to facilitate collaborative editing. Duplicate row IDs trigger the PowerPoint **Repair Mode**, causing slide elements and styles to break.
+`node-pptx-templater` generates unique 32-bit unsigned integers for `<a16:rowId>` whenever a table row is cloned, appended, or inserted, ensuring output documents open flawlessly in MS PowerPoint, Google Slides, and LibreOffice.
 
 ---
 
 ## 📚 API Reference
 
-### `PPTXTemplater`
+Here is the complete reference of all public APIs.
 
-#### Static Methods
+### Slide Features
 
-| Method | Description |
-|---|---|
-| `PPTXTemplater.load(source)` | Load from file path or Buffer |
-| `PPTXTemplater.create()` | Create a blank presentation |
+#### `duplicateSlide(slideIndex, atPosition)`
+Duplicates a slide.
+```js
+ppt.duplicateSlide(1, 2); // Duplicate Slide 1 and insert it as Slide 2
+```
 
-#### Slide Selection
+#### `deleteSlide(slideIndex)`
+Deletes a slide from the deck.
+```js
+ppt.deleteSlide(3); // Delete Slide 3
+```
 
-| 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 |
+#### `moveSlide(fromIndex, toIndex)`
+Moves a slide to a new position.
+```js
+ppt.moveSlide(1, 3); // Move Slide 1 to position 3
+```
 
-#### Content Manipulation
+#### `insertSlide(slideIndex, options)`
+Inserts a new blank slide at a specific position.
+```js
+ppt.insertSlide(2, { title: 'New Layout Slide' });
+```
 
-| 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 |
+#### `getSlides()`
+Returns metadata about all slides in the deck.
+```js
+const slides = ppt.getSlides();
+console.log(slides);
+```
 
-#### Slide Management
+---
 
-| 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 |
+### Table Features
 
-#### Output
+#### `addTableRow(tableId, rowData)`
+Appends a new row to the table.
+```js
+ppt.addTableRow('sales-table', ['Q4', '150', '210', '190', '250']);
+```
 
-| Method | Description |
-|---|---|
-| `.saveToFile(path)` | Write PPTX to disk |
-| `.toBuffer()` | Get PPTX as Node.js Buffer |
-| `.toStream()` | Get PPTX as readable stream |
+#### `removeTableRow(tableId, rowIndex)`
+Removes a table row.
+```js
+ppt.removeTableRow('sales-table', 1); // Delete 2nd row (0-based)
+```
 
-#### Utilities
+#### `insertTableRow(tableId, rowIndex, rowData)`
+Inserts a row at a specific index.
+```js
+ppt.insertTableRow('sales-table', 2, ['Q3', '100', '120', '140', '160']);
+```
 
-| Method | Description |
-|---|---|
-| `.getInfo()` | Presentation metadata |
-| `.validate()` | Structure validation |
-| `.slideCount` | Total slide count (getter) |
+#### `cloneTableRow(tableId, sourceRowIndex, targetRowIndex)`
+Clones a row style/data and inserts it.
+```js
+ppt.cloneTableRow('sales-table', 1, 3);
+```
 
----
+#### `updateCell(tableId, rowIndex, colIndex, value, options)`
+Updates a specific cell value and styling.
+```js
+ppt.updateCell('sales-table', 1, 0, 'New Product Name', {
+  fill: 'FF0000',     // HEX background color
+  align: 'ctr',       // Text alignment: 'l', 'ctr', 'r', 'just'
+  fontSize: 14        // Font size in points
+});
+```
 
-## 🏗️ Architecture
+#### `mergeCells(options)` or `mergeCells(tableId, startRow, startCol, endRow, endCol)`
+Merges a rectangular range of cells. Supports horizontal, vertical, and block merges, moving cell texts to the origin cell (concatenated with newlines) and setting correct OpenXML `gridSpan` and `rowSpan` attributes.
+```js
+// Config object signature (Recommended)
+ppt.mergeCells({
+  slide: 3,
+  tableId: 'sales-table',
+  startRow: 1,
+  startCol: 1,
+  endRow: 3,
+  endCol: 3
+});
 
+// Legacy positional signature
+ppt.mergeCells('sales-table', 1, 1, 3, 3);
 ```
-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
-```
-
-### OpenXML PPTX Structure
 
-A `.pptx` file is a ZIP archive (Open Packaging Convention) containing XML files:
+#### `unmergeCells(options)` or `unmergeCells(tableId, startRow, startCol, endRow, endCol)`
+Unmerges cells, restoring original XML cell structures.
+```js
+// Cell-coordinate coordinate signature (Recommended)
+ppt.unmergeCells({
+  slide: 3,
+  tableId: 'sales-table',
+  row: 2,
+  col: 2
+});
 
-```
-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
+// Legacy positional signature
+ppt.unmergeCells('sales-table', 1, 1, 3, 3);
 ```
 
-### Relationship Flow
+#### `getMergedCells(tableId)`
+Scans the slide table and returns all active merged regions.
+```js
+const merges = ppt.getMergedCells('sales-table');
+// Output: [ { startRow: 1, startCol: 1, endRow: 3, endCol: 3 } ]
+```
 
+#### `validateMergeRegion(tableId, startRow, startCol, endRow, endCol)`
+Checks bounds and overlaps, returning detailed validation errors.
+```js
+const report = ppt.validateMergeRegion('sales-table', 1, 1, 3, 3);
+console.log(report.valid); // true or false
+console.log(report.errors); // Array of error strings
 ```
-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)
+
+#### `isMergedCell(tableId, row, col)`
+Returns `true` if the cell at `(row, col)` is part of any merged region.
+```js
+const merged = ppt.isMergedCell('sales-table', 2, 2);
 ```
 
-### Text Fragmentation Problem & Solution
+#### `getMergeParent(tableId, row, col)`
+Returns the coordinates `{ row, col }` of the top-left origin cell of the merge region containing `(row, col)`.
+```js
+const parent = ppt.getMergeParent('sales-table', 2, 2); // { row: 1, col: 1 }
+```
 
-PowerPoint sometimes splits `{{placeholder}}` across multiple XML text runs:
+#### `getMergeRegion(tableId, row, col)`
+Returns the merged region object `{ startRow, startCol, endRow, endCol }` containing `(row, col)`.
+```js
+const region = ppt.getMergeRegion('sales-table', 2, 2);
+```
 
-```xml
-<!-- What you write in PowerPoint: -->
-{{title}}
+#### `splitMergedRegion(tableId, row, col)`
+Splits the merged region containing cell `(row, col)`.
+```js
+ppt.splitMergedRegion('sales-table', 2, 2);
+```
 
-<!-- What the XML actually contains: -->
-<a:r><a:t>{{ti</a:t></a:r>
-<a:r><a:t>tle}}</a:t></a:r>
+#### `cloneMergedRegion(tableId, row, col, targetRow, targetCol)`
+Clones a merged region to another starting position, preserving cell text and formatting.
+```js
+ppt.cloneMergedRegion('sales-table', 1, 1, 4, 1);
 ```
 
-**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
+#### Template-driven cell merges
+Support cell merging inside template updates dynamically via `colSpan`/`rowSpan` or `merge` arrays:
+```js
+ppt.updateTable('sales-table', {
+  rows: [
+    ['Header 1', 'Header 2', 'Header 3'],
+    ['Row 1 Col 1', { value: 'Spanned Cell', colSpan: 2 }],
+    ['Row 2 Col 1', 'Row 2 Col 2', { value: 'Spanned V', rowSpan: 2 }]
+  ],
+  merge: [
+    { startRow: 0, startCol: 0, endRow: 0, endCol: 2 }
+  ]
+});
+```
 
----
+#### `autoFitTable(tableId)`
+Resizes columns to fit text width.
+```js
+ppt.autoFitTable('sales-table');
+```
 
-## 🖥️ CLI Usage
+#### `resizeTable(tableId, width, height)`
+Resizes the bounding frame of the table. Width/height can be in EMUs or inches.
+```js
+ppt.resizeTable('sales-table', 8.5, 4.2); // Dimensions in inches
+```
 
-```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
-```
-
-### 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"]
-    ]
-  }
-}
+#### `getTables()`
+Lists tables in the current slide.
+```js
+const tables = ppt.getTables();
 ```
 
 ---
 
-## 📊 Supported Chart Types
+### Chart Features
 
-| 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 |
+#### `updateChartData(chartId, data)`
+Updates a chart's categories, series, values, and embedded Excel workbook.
+```js
+ppt.updateChartData('sales-chart', {
+  categories: ['Q1', 'Q2', 'Q3'],
+  series: [{ name: 'Sales', values: [100, 120, 150] }]
+});
+```
 
----
+#### `replaceChartSeries(chartId, seriesIndex, newSeriesData)`
+Replaces values and name of a single series.
+```js
+ppt.replaceChartSeries('sales-chart', 0, {
+  name: 'Updated Series Name',
+  values: [80, 95, 110]
+});
+```
 
-## ⚡ Performance
+#### `updateChartTitle(chartId, title)`
+Updates the chart's title.
+```js
+ppt.updateChartTitle('sales-chart', 'Quarterly Revenue Performance');
+```
 
-| Operation | Benchmark (avg) |
-|---|---|
-| Load 50-slide PPTX | ~120ms |
-| Text replacement (20 placeholders) | ~2ms |
-| Buffer generation | ~80ms |
-| Chart update | ~5ms |
-| Table update | ~3ms |
+#### `updateChartCategories(chartId, categories)`
+Updates the chart categories.
+```js
+ppt.updateChartCategories('sales-chart', ['Jan', 'Feb', 'Mar']);
+```
 
-> Run your own: `npm run benchmark`
+#### `getCharts()`
+Returns chart metadata from the slide.
+```js
+const charts = ppt.getCharts();
+```
 
 ---
 
-## 🐛 Troubleshooting
-
-### Placeholders not being replaced
+### Text Features
 
-If `{{placeholder}}` is not replaced, the text is likely fragmented across runs.
-Use the `PPTX_LOG_LEVEL=debug` environment variable to see detailed logs:
+#### `replaceTextByTag(tag, value, options)`
+Replaces placeholders with custom values.
+```js
+ppt.replaceTextByTag('username', 'Alice Cooper');
+```
 
-```bash
-PPTX_LOG_LEVEL=debug node your-script.js
+#### `replaceMultiple(replacements, options)`
+Performs multiple text tag replacements.
+```js
+ppt.replaceMultiple({
+  'date': '2026-06-02',
+  'location': 'New York'
+});
 ```
 
-Extract the slide XML to inspect:
-```bash
-node-pptx-templater extract template.pptx --slide 1 --out slide1.xml
+#### `findText(text)`
+Searches for text in slide shape runs.
+```js
+const matches = ppt.findText('DeepMind');
 ```
 
-Look for `<a:t>` elements and check if the placeholder is split.
+#### `getTextElements()`
+Gets all raw text segments in the selected slide.
+```js
+const elements = ppt.getTextElements();
+```
 
-### Chart not updating
+---
 
-Chart names must match the shape's `cNvPr name` attribute exactly.
-Use `--inspect --charts` to see all chart names:
+### Shape Features
 
-```bash
-node-pptx-templater inspect template.pptx --charts
+#### `updateShapeText(shapeId, text)`
+Updates text inside a shapes run.
+```js
+ppt.updateShapeText('HeaderShape', 'Updated Slide Header');
 ```
 
-### Generated PPTX fails to open
+#### `cloneShape(shapeId, newShapeId, options)`
+Clones a shape and places it with offsets.
+```js
+ppt.cloneShape('HeaderShape', 'HeaderShapeCopy', {
+  offsetX: 1.0,  // Offset X in inches
+  offsetY: 0.5,  // Offset Y in inches
+  width: 5.0,    // Resize width
+  height: 2.0    // Resize height
+});
+```
 
-Run the debug command to check for structural issues:
+#### `deleteShape(shapeId)`
+Deletes a shape.
+```js
+ppt.deleteShape('HeaderShapeCopy');
+```
 
-```bash
-node-pptx-templater debug output.pptx
+#### `getShapes()`
+Lists shapes on the slide.
+```js
+const shapes = ppt.getShapes();
 ```
 
-Common causes:
-- Missing content type entries for new slides
-- Broken relationship IDs
-- Invalid XML characters in replacement values
+---
+
+### Image Features
 
-### File is corrupted
+#### `replaceImage(imageIdOrName, sourcePathOrBuffer)`
+Replaces an image file binary, keeping the layout.
+```js
+await ppt.replaceImage('LogoImage', 'path/to/new-logo.png');
+```
 
-```bash
-node-pptx-templater debug corrupted.pptx --fix --out repaired.pptx
+#### `addImage(sourcePathOrBuffer, options)`
+Embeds a new image with layout options.
+```js
+await ppt.addImage('path/to/badge.png', {
+  x: 2.0,       // Position X (inches)
+  y: 1.5,       // Position Y (inches)
+  width: 3.0,   // Width (inches)
+  height: 3.0   // Height (inches)
+});
+```
+
+#### `removeImage(imageIdOrName)`
+Deletes an image.
+```js
+ppt.removeImage('Picture 1002');
 ```
 
-The debug command attempts:
-- Removing invalid XML control characters
-- Fixing unescaped `&` in text content
-- Repairing broken relationship IDs
+#### `getImages()`
+Lists images inside the slide.
+```js
+const images = ppt.getImages();
+```
 
 ---
 
-## 🔌 Plugin System
+### Validation System
 
-Extend the engine by subclassing `PPTXTemplater`:
+#### `validatePresentation()`
+Audits the complete presentation.
+```js
+const report = await ppt.validatePresentation();
+console.log('Errors:', report.errors);
+console.log('Warnings:', report.warnings);
+```
 
+#### `validateSlide(slideIndex)`
+Validates slide XML structure.
 ```js
-import { PPTXTemplater } from 'pptx-templater';
+const report = await ppt.validateSlide(1);
+```
 
-class MyEngine extends PPTXTemplater {
-  /**
-   * Custom method: fills a slide from a data object.
-   */
-  async fillFromData(slideNum, data) {
-    this.useSlide(slideNum);
+#### `validateTable(tableId)`
+Audits columns and duplicate rowIds in a table.
+```js
+const report = await ppt.validateTable('sales-table');
+```
 
-    const textReplacements = {};
-    for (const [key, val] of Object.entries(data.text || {})) {
-      textReplacements[`{{${key}}}`] = String(val);
-    }
+#### `validateRelationships(partPath)`
+Audits `.rels` relationship references.
+```js
+const report = ppt.validateRelationships('ppt/slides/slide1.xml');
+```
 
-    this.replaceText(textReplacements);
+---
 
-    if (data.chart) {
-      this.updateChart(data.chart.id, data.chart);
-    }
+## ⚡ Performance Benchmarks
 
-    return this;
-  }
-}
+Tested on a 50-slide presentation template:
 
-// 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');
-```
+| Operation | Average Duration |
+|---|---|
+| Load presentation | ~120ms |
+| Replace 20 text tags | ~2ms |
+| Audit presentation structure | ~15ms |
+| Update table rows (10 rows) | ~3ms |
+| Rebuild ZIP and Save | ~80ms |
 
 ---
 
-## 🛣️ Roadmap
+## ❓ FAQ
+
+#### Why use this over libraries like pptxgenjs or officegen?
+Those libraries generate presentations from scratch in code. `node-pptx-templater` is a **templating** engine. You create a beautiful template inside MS PowerPoint (applying themes, layout grids, animations, or styling), and then use this library to dynamically populate slides, update tables, and refresh chart values while preserving the design.
 
-- [ ] 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)
+#### How is chart styling preserved?
+We update only the `<c:cat>` (categories), `<c:val>` (values) XML nodes, and the underlying data sheet inside the embedded Excel workbook. PowerPoint reads these updated values and uses the template's pre-configured colors, font layouts, labels, and axes.
 
 ---
 
 ## 🤝 Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-Quick steps:
 ```bash
 git clone https://github.com/jsuyog2/node-pptx-templater.git
 cd node-pptx-templater
@@ -412,4 +467,4 @@ npm test
 
 ## 📄 License
 
-MIT — see [LICENSE](./LICENSE)
+MIT © [node-pptx-templater contributors](./LICENSE)