officeparser 7.0.1 → 7.0.3

package/README.md

@@ -1,6 +1,10 @@
-# officeParser 📄🚀 - The Most Versatile Office Parser & Generator
+# officeParser — Universal Office Document Parser & Generator
 
-A robust, strictly-typed Node.js and Browser library for parsing and generating office files. It not only extracts content from [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML), [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML), [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML), [`odt`](https://en.wikipedia.org/wiki/OpenDocument), [`odp`](https://en.wikipedia.org/wiki/OpenDocument), [`ods`](https://en.wikipedia.org/wiki/OpenDocument), [`pdf`](https://en.wikipedia.org/wiki/PDF), [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format), [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values), [`md`](https://en.wikipedia.org/wiki/Markdown), and [`html`](https://en.wikipedia.org/wiki/HTML) into a rich Abstract Syntax Tree (AST), but also provides a powerful generation engine to convert that AST into formats like **Markdown**, **HTML**, **CSV**, **RTF**, **Text**, **PDF**, and **JSON**, including native **RAG-focused chunking** support.
+A robust, strictly-typed **Node.js and Browser** library for parsing office files into a rich **Abstract Syntax Tree (AST)** and generating high-fidelity output in multiple formats.
+
+**Parses:** [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`odt`](https://en.wikipedia.org/wiki/OpenDocument) · [`odp`](https://en.wikipedia.org/wiki/OpenDocument) · [`ods`](https://en.wikipedia.org/wiki/OpenDocument) · [`pdf`](https://en.wikipedia.org/wiki/PDF) · [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format) · [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values) · [`md`](https://en.wikipedia.org/wiki/Markdown) · [`html`](https://en.wikipedia.org/wiki/HTML)
+
+**Generates:** `Markdown` · `HTML` · `CSV` · `RTF` · `PDF` · `Plain Text` · `RAG Chunks`
 
 [![npm version](https://badge.fury.io/js/officeparser.svg)](https://badge.fury.io/js/officeparser)
 [![Total Downloads](https://img.shields.io/npm/dt/officeparser.svg)](https://www.npmjs.com/package/officeparser)
@@ -10,45 +14,53 @@ A robust, strictly-typed Node.js and Browser library for parsing and generating
 ---
 
 ### 🌟 [Live Interactive AST Visualizer & Documentation](https://harshankur.github.io/officeParser/) 🌟
-*Test any office file in your browser and see the extracted AST, text, and preview in real-time which is rebuilt from the AST!*
-
-**What you can do there:**
-- **AST Visualizer**: Upload any office file and inspect the hierarchical AST structure, metadata, and raw content.
-- **Config Configurator**: Tweak parsing options (like `ignoreNotes`, `ocr`, `newlineDelimiter`) and see the results instantly.
-- **Debugging**: Use the visualizer to debug parsing issues by inspecting exactly how nodes are interpreted.
-- **Format Specs**: Read detailed specifications for the AST structure and configuration options.
-
----
+*Upload any office file in your browser — inspect the AST, tweak config, and preview generated output in real-time.*
 
+- **AST Visualizer**: Inspect the hierarchical node tree, metadata, and raw content
+- **Config Configurator**: Tweak options (`ignoreNotes`, `ocr`, `newlineDelimiter`) and see results instantly
+- **Debugging**: Identify exactly how nodes are interpreted
+- **Format Specs**: Read detailed specs for the AST structure and all config options
 
 ---
 
 ### 📝 [Changelog](CHANGELOG.md)
-*Detailed release notes and the full history of updates are available in the project changelog.*
 
 ---
 
 ## Table of Contents
-- [Install via npm](#install-via-npm)
+- [Install](#install-via-npm)
 - [Command Line Usage](#command-line-usage)
-- [Library Usage](#library-usage)
-- [Using the OfficeGenerator](#using-the-officegenerator)
-- [The New "One-Step" API: OfficeConverter](#the-new-one-step-api-officeconverter)
+- [Quick Decision Guide](#quick-decision-guide)
+- [Library Usage: Parsing](#library-usage-parsing)
+  - [Async/Await](#asyncawait)
+  - [Callback (Backward Compat)](#callback-backward-compat)
+  - [File Buffers & ArrayBuffers](#file-buffers--arraybuffers)
+  - [`ast.to()` — Generate from AST](#astto--generate-from-ast)
+  - [`ast.toText()` — Quick Text Extraction](#asttotext--quick-text-extraction)
+- [OfficeGenerator](#officegenerator)
+- [OfficeConverter — One-Step API](#officeconverter--one-step-api)
 - [Native RAG Chunking](#native-rag-chunking)
 - [The AST Structure](#the-ast-structure)
 - [Deep Dive: Document Components](#deep-dive-document-components)
-- [Performance & Fidelity Highlights (v7.0.0)](#performance--fidelity-highlights-v700)
+- [Performance Highlights](#performance-highlights)
 - [Advanced AST Usage](#advanced-ast-usage)
-- [Configuration Object: OfficeParserConfig](#configuration-object-officeparserconfig)
-- [Generator Configuration: GeneratorConfig](#generator-configuration-generatorconfig)
-- [Format-Specific Generator Configuration](#format-specific-generator-configuration)
-- [One-Step Conversion: OfficeConverterConfig](#one-step-conversion-officeconverterconfig)
-- [Chunking Configuration: ChunkingConfig](#chunking-configuration-chunkingconfig)
+- [Configuration Reference](#configuration-reference)
+  - [OfficeParserConfig](#officeparserconfig)
+  - [GeneratorConfig (Common)](#generatorconfig-common)
+  - [onNode Callback](#onnode-callback--advanced-node-manipulation)
+  - [styleMap — Semantic Style Mapping](#stylemap--semantic-style-mapping)
+  - [HtmlGeneratorConfig](#htmlgeneratorconfig)
+  - [MdGeneratorConfig](#mdgeneratorconfig)
+  - [PdfGeneratorConfig](#pdfgeneratorconfig)
+  - [CsvGeneratorConfig](#csvgeneratorconfig)
+  - [TextGeneratorConfig](#textgeneratorconfig)
+  - [OfficeConverterConfig](#officeconverterconfig)
+  - [ChunkingConfig](#chunkingconfig)
 - [OCR Scheduler & Resource Management](#ocr-scheduler--resource-management)
-- [Examples](#examples)
 - [Browser Usage](#browser-usage)
 - [Troubleshooting & Common Issues](#troubleshooting--common-issues)
 - [Known Limitations](#known-limitations)
+- [Contributing](#contributing)
 
 ---
 
@@ -58,748 +70,807 @@ A robust, strictly-typed Node.js and Browser library for parsing and generating
 npm i officeparser
 ```
 
-## Command Line usage
-You can use `officeparser` directly from the terminal to extract content as JSON AST, plain text, or generate new formats like Markdown and HTML.
+---
+
+## Command Line Usage
 
 ```bash
-# Get full AST as JSON (default)
-npx officeparser /path/to/officeFile.docx
+# Full AST as JSON (default)
+npx officeparser /path/to/file.docx
 
-# Get plain text only
-npx officeparser /path/to/officeFile.docx --toText=true
+# Plain text output
+npx officeparser /path/to/file.docx --format=text
 
-# Generate Markdown file
+# Convert DOCX to Markdown and save
 npx officeparser report.docx --format=md --output=report.md
 
-# Generate HTML file with specific output
+# Convert PPTX to HTML
 npx officeparser presentation.pptx --format=html --output=preview.html
 
-# Convert spreadsheet to CSV
+# Convert XLSX to CSV
 npx officeparser data.xlsx --format=csv
+
+# Generate RAG chunks
+npx officeparser document.pdf --format=chunks
 ```
 
-### Config Options:
-- `--format=[json|text|md|html|csv|rtf|pdf|chunks]` The output format. Default is `json`.
-- `--output=[path]`                    Optional file path to write the output to.
-- `--toText=[true|false]`              Legacy flag to output only plain text. Use `--format=text` instead.
-- `--ignoreNotes=[true|false]`          Flag to ignore notes from files like PowerPoint. Default is false.
-- `--newlineDelimiter=[delimiter]`      The delimiter to use for new lines. Default is `\n`.
-- `--putNotesAtLast=[true|false]`       Flag to collect notes at the end of files like PowerPoint. Default is false.
-- `--outputErrorToConsole=[true|false]` **(Deprecated)** Flag to output errors to the console. Use `onWarning` callback in library usage.
-- `--extractAttachments=[true|false]`   Flag to extract images/charts as Base64. Default is false.
-- `--ocr=[true|false]`                  Flag to enable OCR for extracted images. Default is false.
-- `--includeRawContent=[true|false]`    Flag to include raw XML/RTF content in nodes. Default is false.
-- `--includeBreakNodes=[true|false]`    Flag to include break nodes. Currently only available for DOCX documents.
-- `--verbose=[true|false]`              Show full error stack traces.
+### CLI Options
 
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--format` | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | Output format |
+| `--output` | path | — | Write output to a file |
+| `--toText` | `true\|false` | `false` | **Deprecated.** Use `--format=text` |
+| `--ignoreNotes` | `true\|false` | `false` | Ignore speaker notes (PPTX/ODP) |
+| `--putNotesAtLast` | `true\|false` | `false` | Collect notes at end of output |
+| `--newlineDelimiter` | string | `\n` | Delimiter between lines |
+| `--extractAttachments` | `true\|false` | `false` | Extract images/charts as Base64 |
+| `--ocr` | `true\|false` | `false` | Enable OCR for images |
+| `--includeRawContent` | `true\|false` | `false` | Include raw XML/RTF in nodes |
+| `--includeBreakNodes` | `true\|false` | `false` | Include break nodes (DOCX only) |
+| `--outputErrorToConsole` | `true\|false` | `false` | **Deprecated.** Use `onWarning` callback |
+| `--verbose` | `true\|false` | `false` | Show full error stack traces |
 
-## Library Usage
-In **v7.0.0**, the library has evolved into a dual-purpose **Parser** and **Generator**. You can first parse any office file into a structured AST and then use the `OfficeGenerator` to transform that AST into various formats or chunks.
+---
+
+## Quick Decision Guide
+
+| Goal | API to use |
+|------|-----------|
+| Extract text / AST from a file | `OfficeParser.parseOffice(file)` |
+| Convert directly to another format | `OfficeConverter.convert(file, 'md')` |
+| Parse first, then generate | `parseOffice()` → `OfficeGenerator.generate(ast, 'html')` |
+| Convert on the AST itself (shorthand) | `ast.to('md')` |
+| RAG pipeline chunking | `OfficeConverter.convert(file, 'chunks', {...})` |
+
+---
+
+## Library Usage: Parsing
+
+### Async/Await
 
-### Getting Started (Async/Await)
 ```js
 const officeParser = require('officeparser');
 
-async function parseMyFile() {
-    try {
-        // parseOffice returns an OfficeParserAST object
-        const ast = await officeParser.parseOffice("/path/to/officeFile.docx");
-        
-        // Use the built-in helper to get plain text (similar to old behavior)
-        const text = ast.toText();
-        console.log(text);
-
-        // Access structured content
-        console.log(ast.content);  // Array of hierarchical nodes (paragraphs, tables, etc.)
-        console.log(ast.metadata); // Document properties (author, title, etc.)
-    } catch (err) {
-        console.error(err);
-    }
-}
+const ast = await officeParser.parseOffice('/path/to/file.docx');
+
+console.log(ast.type);       // 'docx'
+console.log(ast.metadata);   // { author, title, created, ... }
+console.log(ast.content);    // Array of hierarchical nodes
+console.log(ast.attachments);// Images/charts (if extractAttachments: true)
+console.log(ast.warnings);   // Non-fatal issues from parsing phase
 ```
 
-### Helper Function for Text Extraction (Modern simple way)
-If you only need the text and want to maintain a simple one-liner, you can use this pattern:
+**TypeScript (named import):**
+```ts
+import { OfficeParser } from 'officeparser';
+
+const ast = await OfficeParser.parseOffice('report.docx', {
+    extractAttachments: true,
+    ocr: true,
+});
+```
+
+### Callback (Backward Compat)
+
 ```js
-// Simple helper to get text directly
-const getText = async (file, config) => (await officeParser.parseOffice(file, config)).toText();
+officeParser.parseOffice('/path/to/file.docx', function(ast, err) {
+    if (err) { console.error(err); return; }
+    console.log(ast.toText());
+});
+```
+
+### File Buffers & ArrayBuffers
 
-// usage
-const text = await getText("/path/to/officeFile.docx");
-console.log(text);
+Pass a `Buffer`, `ArrayBuffer`, or `Uint8Array` instead of a file path:
+
+```js
+const fs = require('fs');
+const buffer = fs.readFileSync('/path/to/file.pdf');
+const ast = await officeParser.parseOffice(buffer);
+```
+
+> [!IMPORTANT]
+> **Text-based formats from buffers need a `fileType` hint.**
+> Formats like `md`, `html`, and `csv` have no magic bytes, so the parser cannot
+> auto-detect them from a buffer. You **must** provide `fileType` in that case:
+> ```js
+> const ast = await officeParser.parseOffice(markdownBuffer, { fileType: 'md' });
+> ```
+
+### `ast.to()` — Generate from AST
+
+The preferred way to convert a parsed AST to another format. Returns a `ConversionResult`.
+
+```ts
+// ConversionResult shape:
+// { value: string | Uint8Array | OfficeChunk[], messages: OfficeIssue[] }
+
+const { value: markdown, messages } = await ast.to('md');
+const { value: html }               = await ast.to('html', { includeFormatting: false });
+const { value: chunks }             = await ast.to('chunks', { strategy: 'fixed-size', chunkSize: 800 });
+const { value: pdfBytes }           = await ast.to('pdf'); // Uint8Array
+```
+
+### `ast.toText()` — Quick Text Extraction
+
+> [!NOTE]
+> `toText()` is **synchronous** and deprecated in favour of the async `ast.to('text')`.
+> It remains available for backward compatibility.
+
+```js
+const text = ast.toText(); // synchronous, returns plain string
 ```
 
-## Using the OfficeGenerator
-The `OfficeGenerator` is a powerful tool to convert your AST into human-readable formats or structured data.
+---
+
+## OfficeGenerator
+
+Use `OfficeGenerator.generate(ast, format, config?)` when you need to produce output from an already-parsed AST:
 
-```typescript
+```ts
 import { OfficeParser, OfficeGenerator } from 'officeparser';
 
 const ast = await OfficeParser.parseOffice('report.docx');
 
-// 1. Convert to Markdown
-const md = await OfficeGenerator.generate(ast, 'md');
-console.log(md.value);
+// Convert to Markdown
+const { value: md } = await OfficeGenerator.generate(ast, 'md');
 
-// 2. Convert to HTML with structured style mapping (Recommended)
-const html = await OfficeGenerator.generate(ast, 'html', {
+// Convert to HTML with style mapping
+const { value: html } = await OfficeGenerator.generate(ast, 'html', {
     includeFormatting: true,
     styleMap: [
-        { 
-            selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } }, 
-            output: { tag: 'h1', classes: ['main-title'] } 
+        {
+            selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } },
+            output: { tag: 'h1', classes: ['main-title'] }
         }
     ]
 });
-console.log(html.value);
 
-// 3. Convert to CSV (for spreadsheets)
-const csv = await OfficeGenerator.generate(ast, 'csv');
-console.log(csv.value);
+// Convert to CSV (spreadsheets)
+const { value: csv } = await OfficeGenerator.generate(ast, 'csv');
 ```
 
-## The New "One-Step" API: `OfficeConverter`
-In **v7.0.0**, we introduced the `OfficeConverter.convert` method. This is the new high-level API designed for one-step transformations where you don't need to manually interact with the AST. It automatically handles parser and generator configuration synchronization.
+**Supported destinations:** `'text'` · `'md'` · `'html'` · `'csv'` · `'rtf'` · `'pdf'` · `'chunks'`
+
+> [!NOTE]
+> **PDF generation** requires the optional `puppeteer` peer dependency:
+> ```bash
+> npm install puppeteer
+> ```
 
-```typescript
+---
+
+## OfficeConverter — One-Step API
+
+`OfficeConverter.convert()` combines parsing and generation in a single call. It automatically syncs parser options from generator config (e.g., enables `extractAttachments` when images are requested).
+
+```ts
 import { OfficeConverter } from 'officeparser';
 
-// One-step conversion from DOCX to Markdown
-const result = await OfficeConverter.convert('report.docx', 'md');
-console.log(result.value); // The generated Markdown string
-console.log(result.messages); // Array of warnings/info (e.g., "Skipped unsupported drawing")
+// Minimal usage
+const { value: markdown } = await OfficeConverter.convert('report.docx', 'md');
 
-// Complex conversion with nested configuration
-const htmlResult = await OfficeConverter.convert('data.xlsx', 'html', {
-    parseConfig: { 
-        ignoreNotes: true 
+// With config
+const { value: html, messages } = await OfficeConverter.convert('data.xlsx', 'html', {
+    parseConfig: {
+        ignoreNotes: true,
+        newlineDelimiter: '\n\n',
     },
     generatorConfig: {
         includeFormatting: true,
         styleMap: [
-            { 
-                selector: { attributes: { style: { value: 'Header', operator: '~=' } } }, 
-                output: { tag: 'h2', classes: ['data-header'] } 
+            {
+                selector: { attributes: { style: { value: 'Header', operator: '~=' } } },
+                output: { tag: 'h2', classes: ['data-header'] }
             }
         ]
     },
-    onWarning: (msg) => console.warn("Conversion Warning:", msg)
+    onWarning: (issue) => console.warn(`[${issue.code}] ${issue.message}`)
 });
 ```
 
+> [!IMPORTANT]
+> The `OfficeConverterConfig` shape uses **nested** `parseConfig` and `generatorConfig` sub-objects.
+> Do **not** put parser or generator options at the top level — only `onWarning` lives there.
+
+---
+
 ## Native RAG Chunking
-`officeParser` provides native support for document chunking, specifically designed for Retrieval-Augmented Generation (RAG) workflows. It offers three distinct strategies to split your documents while maintaining context and metadata.
-
-### 1. Fixed-Size Strategy (Recursive)
-Splits text into chunks based on character count with a specified overlap. It uses smart boundary detection to avoid cutting in the middle of sentences or paragraphs.
-
-### 2. Document Structure Strategy
-Splits the document at natural structural boundaries like pages (PDF/Word), slides (PPTX), or high-level headings. This preserves the logical flow of the document.
-
-### 3. Semantic Strategy
-Uses cosine similarity between sentence embeddings to identify coherent topic boundaries. This ensures that each chunk contains semantically related content (requires an embedding function).
-
-### The `OfficeChunk` Interface
-Every chunk produced contains not just text, but rich metadata to help your RAG pipeline:
-```typescript
-{
-  text: string;           // The chunk content
-  metadata: {
-    sourceType: string;   // e.g., "docx", "pdf"
-    pageNumber?: number;  // Current page
-    slideNumber?: number; // Current slide
-    closestHeading?: string; // The heading this chunk belongs to
-    chunkIndex: number;   // Sequential index
-  }
-}
+
+`officeParser` provides native document chunking for Retrieval-Augmented Generation (RAG) pipelines with three strategies:
+
+### Strategy 1: Document Structure (Default)
+Splits at natural AST boundaries (paragraphs, headings, pages, slides, sheets). Preserves logical flow.
+
+```ts
+const { value: chunks } = await OfficeConverter.convert('report.docx', 'chunks', {
+    generatorConfig: {
+        chunksConfig: {
+            strategy: 'document-structure',
+            splitBy: 'heading',    // 'paragraph' | 'heading' | 'page' | 'slide' | 'sheet'
+            maxChunkSize: 1500,
+            tableSplitStrategy: 'row', // repeats header row in every chunk — ideal for RAG
+        }
+    }
+});
 ```
 
-#### Example: Generating Chunks
-```typescript
-const chunks = await OfficeGenerator.generate(ast, 'chunks', {
-    strategy: 'fixed-size',
-    maxChunkSize: 1000,
-    chunkOverlap: 200
+### Strategy 2: Fixed-Size (Recursive)
+Splits by character count with overlap. Equivalent to LangChain's `RecursiveCharacterTextSplitter`.
+
+```ts
+const { value: chunks } = await OfficeConverter.convert('report.docx', 'chunks', {
+    generatorConfig: {
+        chunksConfig: {
+            strategy: 'fixed-size',
+            chunkSize: 1000,
+            chunkOverlap: 200,
+        }
+    }
 });
-console.log(`Generated ${chunks.value.length} chunks`);
+console.log(`Generated ${chunks.length} chunks`);
 ```
 
-### Using Callbacks (Backward Compatibility Support)
-Callbacks are still supported for those preferred, but the data returned is now the AST object.
-```js
-const officeParser = require('officeparser');
+### Strategy 3: Semantic
+Uses cosine similarity between sentence embeddings to find topic boundaries. Requires you to provide an `embeddingFunction`.
 
-officeParser.parseOffice("/path/to/officeFile.docx", function(ast, err) {
-    if (err) {
-        console.error(err);
-        return;
+```ts
+import OpenAI from 'openai';
+const openai = new OpenAI();
+
+const { value: chunks } = await OfficeConverter.convert('report.docx', 'chunks', {
+    generatorConfig: {
+        chunksConfig: {
+            strategy: 'semantic',
+            embeddingFunction: async (text) => {
+                const res = await openai.embeddings.create({
+                    input: text, model: 'text-embedding-3-small'
+                });
+                return res.data[0].embedding;
+            },
+            similarityThreshold: 0.8,
+            maxChunkSize: 2000,
+        }
     }
-    // Get text from AST
-    console.log(ast.toText());
 });
 ```
 
-### Using File Buffers or ArrayBuffers
-You can pass a file path string, a Node.js `Buffer`, or an `ArrayBuffer`.
-```js
-const fs = require('fs');
-const officeParser = require('officeparser');
-const buffer = fs.readFileSync("/path/to/officeFile.pdf");
+### The `OfficeChunk` Object
 
-officeParser.parseOffice(buffer)
-    .then(ast => console.log(ast.toText()))
-    .catch(console.error);
+Every chunk contains text and rich metadata for citations and filtered retrieval:
+
+```ts
+interface OfficeChunk {
+    text: string;
+    /** Rich metadata for filtered retrieval */
+    metadata: {
+        sourceType: string;       // e.g., 'docx', 'pdf'
+        pageNumber?: number;      // (PDF only)
+        slideNumber?: number;     // (PPTX only)
+        sheetName?: string;       // (XLSX only)
+        closestHeading?: string;  // Nearest heading above this chunk
+        isTableChunk?: boolean;   // True if part of a split table
+    };
+    startIndex?: number;          // Character offset (if addStartIndex: true)
+    endIndex?: number;            // End character offset (if addStartIndex: true)
+}
 ```
 
+---
+
 ## The AST Structure
-The `OfficeParserAST` provides a format-agnostic representation of your document, allowing you to traverse and manipulate content as a tree.
 
-### Visualizing the AST
-The `OfficeParserAST` provides a format-agnostic representation of your document. Below is a simplified visualization of how the tree is structured:
+`OfficeParserAST` is a format-agnostic document representation:
 
 ```text
 OfficeParserAST
-├── type: "docx" | "pdf" | "xlsx" | "csv" | "md" | ... (11 formats supported)
-├── metadata: { author, title, created, modified, ..., customProperties }
+├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | ...  (11 formats)
+├── metadata: { author, title, created, modified, customProperties, styleMap, ... }
 ├── content: [ OfficeContentNode ]
-│   ├── type: "paragraph" | "heading" | "table" | "list" | ...
-│   ├── text: "Concatenated text of this node and all children"
-│   ├── children: [ OfficeContentNode ] (recursive)
-│   ├── formatting: { bold, italic, color, size, font, ... }
-│   ├── metadata: { level, listId, paragraphIndentation, row, col, ... }
-│   └── rawContent: "<xml>...</xml>" (if enabled)
-├── attachments: [ OfficeAttachment ]
-│   ├── type: "image" | "chart"
-│   ├── name: "image1.png"
-│   ├── data: "base64..."
-│   ├── ocrText: "Text extracted via OCR"
-│   └── chartData: { title, dataSets, labels, ... }
-└── toText(): Function -> returns full plain text
-```
-
-#### Representative JSON Snippet
-```json
-{
-  "type": "docx",
-  "metadata": { "author": "John Doe", "title": "Annual Report", "customProperties": { "Department": "Finance" } },
-  "content": [
-    {
-      "type": "heading",
-      "text": "Introduction",
-      "metadata": { "level": 1 },
-      "children": [
-        { "type": "text", "text": "Introduction", "formatting": { "bold": true } }
-      ]
-    },
-    {
-      "type": "paragraph",
-      "text": "This is a report with an image.",
-      "children": [
-        { "type": "text", "text": "This is a report with an " },
-        { "type": "image", "metadata": { "attachmentName": "img1.png" } }
-      ]
-    }
-  ],
-  "attachments": [
-    { "name": "img1.png", "type": "image", "data": "iVBOR...", "ocrText": "Extracted Text" }
-  ]
+│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | ...
+│   ├── text: string  (concatenated text of node + all descendants)
+│   ├── children: [ OfficeContentNode ]  (recursive)
+│   ├── formatting: { bold, italic, underline, color, size, font, alignment, ... }
+│   └── metadata: { level, listId, row, col, rowSpan, colSpan, style, ... }
+├── attachments: [ OfficeAttachment ]  (populated when extractAttachments: true)
+│   ├── type: 'image' | 'chart'
+│   ├── name: string
+│   ├── mimeType: string
+│   ├── data: string  (Base64)
+│   ├── ocrText?: string  (if ocr: true)
+│   └── chartData?: { title, dataSets, labels }
+├── warnings: OfficeIssue[]  (non-fatal issues from the parsing phase)
+├── to(format, config?)  (format: 'html'|'md'|'text'|'csv'|'rtf'|'pdf'|'chunks', returns { value, messages })
+└── toText()             (Deprecated: use .to('text') instead)
+```
+
+### `OfficeIssue` — Warning / Error Object
+
+All warnings and errors (from both parsing and generation) use this shape:
+
+```ts
+interface OfficeIssue {
+    type: 'warning' | 'info' | 'error';
+    code: OfficeWarningType | OfficeErrorType;  // typed enum, e.g. 'OCR_FAILED'
+    message: string;
+    node?: OfficeContentNode;  // the node that triggered the issue, if any
+    details?: any;             // original error or extra context
 }
 ```
 
+---
+
 ## Deep Dive: Document Components
 
-### 1. Working with Lists
-Lists are represented as sequential `list` nodes. To reconstruct or track a list, use the `metadata` fields:
+### 1. Lists
 
 ```text
 List Node
-├── type: "list"
-├── metadata: { 
-    listId: "1", 
-    listType: "ordered", 
-    indentation: 0, 
-    paragraphIndentation: { left: 720, hanging: 360 },
-    itemIndex: 0 
-}
-└── children: [ Text Content... ]
+├── type: 'list'
+├── metadata: {
+│       listId: '1',          // items with the same listId belong to one logical list
+│       listType: 'ordered' | 'unordered',
+│       indentation: 0,       // nesting level (0-based)
+│       itemIndex: 0,         // sequential position within the list level
+│       paragraphIndentation: { left, hanging, right, firstLine }
+│   }
+└── children: [ Text content ]
 ```
 
-- **`listId`**: A unique identifier for the list definition. Multiple items with the same `listId` belong to the same logical list.
-- **`indentation`**: The structural nesting level (0-based).
-- **`paragraphIndentation`**: The physical indentation formatting in twentieths of a point (twips) (e.g., `left`, `right`, `firstLine`, `hanging`).
-- **`itemIndex`**: The sequential position within that list level.
-- **`listType`**: Either `ordered` (numbered) or `unordered` (bulleted).
-
 > [!TIP]
-> Even if a list is interrupted by a regular paragraph, the `itemIndex` will continue to increment for the same `listId`, allowing you to maintain correct numbering.
+> Even if a list is interrupted by a regular paragraph, `itemIndex` keeps incrementing for the same `listId`, so numbering stays correct.
 
-### 2. Navigating Tables
-Tables follow a strict hierarchy: `table` -> `row` -> `cell`.
+### 2. Tables
+
+Tables follow a strict `table → row → cell` hierarchy:
 
 ```text
-Table Node
-├── type: "table"
-└── children: [ Row Node ]
-    ├── type: "row"
-    └── children: [ Cell Node ]
-        ├── type: "cell"
-        ├── metadata: { row, col, rowSpan, colSpan }
-        └── children: [ Paragraph/List/etc. ]
+Table Node (type: 'table')
+└── children: Row Nodes (type: 'row')
+    └── children: Cell Nodes (type: 'cell')
+        ├── metadata: { row, col, rowSpan?, colSpan? }
+        └── children: [ Paragraph | List | Table | ... ]
 ```
 
-- **`row` / `col`**: Zero-based indices for grid positioning.
-- **`rowSpan` / `colSpan`** (Optional): Integer values indicating merged cells (primarily in ODF formats). If absent, the cell is not merged.
-- **Recursive Content**: Cells contain their own `children` array, which can include paragraphs, lists, or even other nested tables.
+- `row` / `col`: zero-based grid position
+- `rowSpan` / `colSpan`: merged cells (primarily ODF formats)
+- Cells can contain nested tables
 
-### 3. Charts & Data
-When a chart is discovered, it's added as a `chart` node in the content and a corresponding `OfficeAttachment`.
+### 3. Images & OCR
 
 ```text
-Chart Node
-├── type: "chart"
-├── metadata: { attachmentName: "chart1.xml" }
-└── Attachment (Linked)
-    └── chartData: { title, dataSets: [...], labels: [...] }
+Image Node (type: 'image')
+├── metadata: { attachmentName: 'img1.png', altText: '...' }
+└── → Attachment: { data: 'base64...', ocrText: '...' }
 ```
 
-- **`attachmentName`**: Links the content node to the `attachments` array.
-- **`chartData`**: A structured object containing titles, axis labels, and category/series data.
+- Set `extractAttachments: true` to populate `attachment.data`
+- Set `ocr: true` (requires `extractAttachments: true`) to populate `ocrText`
 
-### 4. Images, OCR & Alt Text
-Images are linked via `attachmentName` and can contain valuable metadata:
+### 4. Charts
 
 ```text
-Image Node
-├── type: "image"
-├── metadata: { attachmentName: "img1.png", altText: "..." }
-└── Attachment (Linked)
-    ├── data: "base64..."
-    └── ocrText: "Extracted via OCR"
+Chart Node (type: 'chart')
+├── metadata: { attachmentName: 'chart1.xml' }
+└── → Attachment: { chartData: { title, dataSets, labels } }
 ```
 
-- **OCR Text**: If `ocr: true` is set in config, `ocrText` will contain the text found within the image.
-- **Alt Text**: Extracted from the document's internal image descriptions.
-- **Formatting**: `OfficeContentNode` images may also have parent alignment metadata.
-
 ### 5. Text Formatting
-Each `OfficeContentNode` can have a `formatting` object that defines how the text should be styled.
 
-```text
-Text Node
-└── formatting: {
-    bold: boolean,
-    italic: boolean,
-    underline: boolean,
-    strikethrough: boolean,
-    color: "#hex",
-    backgroundColor: "#hex",
-    size: "12pt",
-    font: "Arial",
-    subscript: boolean,
-    superscript: boolean,
-    alignment: "left" | "center" | "right" | "justify"
+```ts
+formatting: {
+    bold?: boolean
+    italic?: boolean
+    underline?: boolean
+    strikethrough?: boolean
+    color?: string          // '#RRGGBB'
+    backgroundColor?: string
+    size?: string           // e.g. '12pt'
+    font?: string
+    subscript?: boolean
+    superscript?: boolean
+    alignment?: 'left' | 'center' | 'right' | 'justify'
 }
 ```
 
-Formatting can be found at two levels:
-1.  **Node Level**: Applied directly to a text run or paragraph.
-2.  **Document Level**: Found in `ast.metadata.formatting` (defaults) or `ast.metadata.styleMap` (named styles).
+### 6. Break Nodes (DOCX only)
 
-### 6. Breaks
-Breaks are currently only supported when parsing DOCX-documents. Breaks are added as a node of type `break` and carry metadata of the type `BreakMetadata`. When `includeRawContent` is enabled, they also include the `rawContent` string from the original XML.
+When `includeBreakNodes: true`, break elements appear as nodes:
 
 ```text
-Break Node
-├── type: "break"
+Break Node (type: 'break')
 └── metadata: {
-        breakType: "textWrapping" | "page" | "column" | "lastRenderedPage" | "carriageReturn",
-        clear?: "all" | "left" | "none" | "right"
+        breakType: 'textWrapping' | 'page' | 'column' | 'lastRenderedPage' | 'carriageReturn',
+        clear?: 'all' | 'left' | 'none' | 'right'
     }
 ```
 
-- `breakType`: Type of break. `textWrapping` (default) is a standard line break, `page` is a page break, `column` is a break to the next column, `lastRenderedPage` is a soft break inserted by Word, and `carriageReturn` is an explicit carriage return (`w:cr`).
-- `clear`: Relevant for `textWrapping`. Indicates if text should wrap around floating objects.
-
 > [!NOTE]
-> Even though break nodes don't have a `text` property, the `ast.toText()` method will automatically convert them to newlines (`\n`) or the configured delimiter in the final string output.
-
-### 7. Advanced Metadata
-The `ast.metadata` object provides document-wide context:
-- **`styleMap`**: A dictionary of style names to their `TextFormatting` definitions found in the document.
-- **`formatting`**: Document-wide default settings (e.g., default font or font size).
-- **`customProperties`**: A dictionary of user-defined metadata embedded in the document (OOXML `custom.xml`, ODF `meta:user-defined`, or PDF Info dictionary).
-
-### 8. Custom Properties
-You can access custom user-defined metadata that might be embedded in the document:
-
-```javascript
-const ast = await officeParser.parseOffice("contract.docx");
-console.log("Custom Metadata:", ast.metadata.customProperties);
-// Output: { "ProjectID": "ABC-123", "InternalReview": true }
-```
-
-## Performance & Fidelity Highlights (v7.0.0)
-The v7.0.0 release brings significant internal optimizations and fidelity improvements:
-- **OpenOffice Speedups**: Up to **23x faster** parsing for ODP presentations thanks to optimized XML caching.
-- **Excel Memory Efficiency**: Resolved $O(n)$ memory overhead issues for large spreadsheets (#91) by switching to iterative stream-based parsing.
-- **RTF Performance**: Rewritten core loop to resolve $O(n^2)$ bottlenecks during string accumulation.
-- **Advanced Table Fidelity**: Native support for **vertical cell merging** (`vMerge`) and **horizontal spanning** (`gridSpan`) in DOCX, ensuring complex tables look exactly as they do in Word.
-- **Parser Extensions**: You can now parse `CSV`, `Markdown`, and `HTML` files *into* the unified Office AST, allowing you to use the `OfficeGenerator` on them just like any other format.
-
-### Advanced AST Usage
-Beyond using `ast.toText()`, you can interact with the structural data directly:
-
-#### 1. Extract all images and their OCR text
-```javascript
-const ast = await officeParser.parseOffice("report.docx", { ocr: true });
-const images = ast.attachments.filter(a => a.mimeType.startsWith('image/'));
-images.forEach(img => {
-    console.log(`Image: ${img.name} (OCR: ${img.ocrText || 'N/A'})`);
-});
+> Break nodes have no `text` property, but `ast.toText()` and `ast.to('text')` automatically convert them to the configured newline delimiter.
+
+### 7. Document Metadata
+
+```ts
+ast.metadata = {
+    author?: string
+    title?: string
+    created?: Date
+    modified?: Date
+    description?: string
+    customProperties?: Record<string, any>  // user-defined metadata from the document
+    styleMap?: Record<string, TextFormatting>  // named styles → formatting definitions
+    formatting?: TextFormatting              // document-wide defaults
+}
 ```
 
-#### 2. Find specific headings
-```javascript
-const headings = ast.content.filter(node => node.type === 'heading' && node.metadata?.level === 1);
-console.log("Main Chapters:", headings.map(h => h.text));
+**Accessing custom properties:**
+```js
+const ast = await officeParser.parseOffice('contract.docx');
+console.log(ast.metadata.customProperties);
+// { "ProjectID": "ABC-123", "InternalReview": true }
 ```
 
-#### 3. Custom output (e.g., Simple Markdown conversion)
-```javascript
-const toMarkdown = (nodes) => {
-    return nodes.map(node => {
-        if (node.type === 'heading') return `${'#'.repeat(node.metadata?.level || 1)} ${node.text}`;
-        if (node.type === 'list') return `- ${node.text}`;
-        if (node.type === 'table') return "[Table Data]"; // expand children for actual table
-        return node.text;
-    }).join('\n\n');
-};
-console.log(toMarkdown(ast.content));
+---
+
+## Performance Highlights
+
+Key internal optimizations shipped in recent versions:
+
+- **OpenOffice (ODP)**: Up to **23× faster** parsing via optimized XML pre-parsing and style caching
+- **Excel Memory**: Resolved O(n) memory overhead on large sparse spreadsheets using iterative stream-based parsing
+- **RTF Parser**: Rewrote string accumulation loop to eliminate O(n²) bottleneck in large files
+- **Table Fidelity (DOCX)**: Native support for vertical cell merging (`vMerge`) and horizontal spanning (`gridSpan`)
+
+---
+
+## Advanced AST Usage
+
+### Extract all headings
+```js
+const headings = ast.content.filter(n => n.type === 'heading' && n.metadata?.level === 1);
+console.log(headings.map(h => h.text));
 ```
 
-#### 4. Extracting Tables to CSV
-Iterate through table nodes and their children (rows -> cells) to build a CSV string.
-```javascript
-const tables = ast.content.filter(node => node.type === 'table');
-tables.forEach((table, index) => {
+### Extract images with OCR text
+```js
+const ast = await officeParser.parseOffice('report.docx', { extractAttachments: true, ocr: true });
+ast.attachments.filter(a => a.mimeType?.startsWith('image/')).forEach(img => {
+    console.log(`${img.name}: ${img.ocrText ?? 'no OCR'}`);
+});
+```
+
+### Extract tables to CSV manually
+```js
+ast.content.filter(n => n.type === 'table').forEach((table, i) => {
     const csv = table.children
-        .filter(row => row.type === 'row')
-        .map(row => 
-            row.children
-                .filter(cell => cell.type === 'cell')
-                .map(cell => `"${cell.text.replace(/"/g, '""')}"`) // Escape quotes
-                .join(',')
-        )
+        .filter(r => r.type === 'row')
+        .map(r => r.children.filter(c => c.type === 'cell')
+            .map(c => `"${c.text.replace(/"/g, '""')}"`)
+            .join(','))
         .join('\n');
-    console.log(`Table ${index + 1} CSV:\n${csv}`);
+    console.log(`Table ${i + 1}:\n${csv}`);
 });
 ```
 
-#### 5. Filtering by Formatting (e.g., Bold Text)
-Find all text nodes that have specific formatting applied.
-```javascript
-function findBoldText(nodes) {
-    let results = [];
-    nodes.forEach(node => {
-        if (node.type === 'text' && node.formatting?.bold) {
-            results.push(node.text);
-        }
-        if (node.children) {
-            results = results.concat(findBoldText(node.children));
-        }
-    });
-    return results;
+### Find all bold text runs
+```js
+function findBold(nodes) {
+    return nodes.flatMap(n => [
+        ...(n.type === 'text' && n.formatting?.bold ? [n.text] : []),
+        ...(n.children ? findBold(n.children) : [])
+    ]);
 }
-
-const boldStrings = findBoldText(ast.content);
-console.log("Bold Text Found:", boldStrings);
+console.log(findBold(ast.content));
 ```
 
-#### 6. Processing Footnotes/Endnotes
-If you kept notes inline (default behavior), you can extract them into a separate list for processing.
-```javascript
+### Extract footnotes / endnotes
+```js
 function extractNotes(nodes) {
-    let notes = [];
-    nodes.forEach(node => {
-        if (node.type === 'note') {
-            notes.push({ id: node.metadata.noteId, text: node.text, type: node.metadata.noteType });
-        }
-        if (node.children) {
-            notes = notes.concat(extractNotes(node.children));
-        }
-    });
-    return notes;
+    return nodes.flatMap(n => [
+        ...(n.type === 'note' ? [{ id: n.metadata.noteId, text: n.text, type: n.metadata.noteType }] : []),
+        ...(n.children ? extractNotes(n.children) : [])
+    ]);
 }
+console.log(extractNotes(ast.content));
+```
+
+### Search for a term (TypeScript)
+```ts
+import { OfficeParser } from 'officeparser';
+
+async function contains(filePath: string, term: string): Promise<boolean> {
+    const ast = await OfficeParser.parseOffice(filePath);
+    return (await ast.to('text')).value.includes(term);
+}
+```
+
+---
+
+## Configuration Reference
+
+### OfficeParserConfig
+
+Pass as the second argument to `parseOffice(file, config)`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `newlineDelimiter` | `string` | `'\n'` | Delimiter inserted between lines in text output |
+| `ignoreNotes` | `boolean` | `false` | Ignore speaker notes (PPTX/ODP) |
+| `putNotesAtLast` | `boolean` | `false` | Collect all notes at the end instead of inline |
+| `extractAttachments` | `boolean` | `false` | Populate `ast.attachments` with Base64 images/charts |
+| `ocr` | `boolean` | `false` | Run Tesseract OCR on images (requires `extractAttachments: true`) |
+| `ocrConfig` | `OcrConfig` | `{}` | OCR worker pool settings — see [OCR section](#ocr-scheduler--resource-management) |
+| `includeRawContent` | `boolean` | `false` | Attach raw XML/RTF source to each node |
+| `serializeRawContent` | `boolean` | `true` | Re-serialize XML to clean strings (only if `includeRawContent: true`) |
+| `preserveXmlWhitespace` | `boolean` | `false` | Preserve original XML whitespace during serialization |
+| `includeBreakNodes` | `boolean` | `false` | Include `w:br` / `w:cr` as typed break nodes (DOCX only) |
+| `ignoreInternalLinks` | `boolean` | `false` | Strip bookmarks and internal cross-references from AST |
+| `fileType` | `SupportedFileType \| null` | `null` | **Required for text-based binary data** (`'md'`, `'html'`, `'csv'`) as these lack magic bytes. |
+| `csvDelimiter` | `string` | `','` | Input delimiter when parsing CSV files |
+| `pdfWorkerSrc` | `string` | CDN (jsDelivr) | Path/URL to `pdf.worker.min.mjs` (required in browser) |
+| `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal parsing issues |
+| `outputErrorToConsole` | `boolean` | `false` | **Deprecated.** Use `onWarning` instead |
+
+---
+
+### GeneratorConfig (Common)
+
+Options shared by all generator formats. Pass to `OfficeGenerator.generate(ast, format, config)` or `ast.to(format, config)`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `includeFormatting` | `boolean` | `true` | Include bold/italic/colors/sizes in output |
+| `generateIds` | `boolean` | `true` | Add slug-based `id` attributes to headings |
+| `renderMetadata` | `boolean` | `false` | Render title/author as visible header block |
+| `includeImages` | `boolean` | `true` | Include image nodes in output |
+| `includeCharts` | `boolean` | `true` | Include interactive charts (HTML only) |
+| `ignoreInternalLinks` | `boolean` | `false` | Strip bookmarks and internal anchors from output |
+| `ignoreDefaultStyleMap` | `boolean` | `false` | Disable built-in style mappings (e.g., "Heading 1" → h1) |
+| `styleMap` | `string[] \| StructuredStyleMapping[]` | `[]` | Custom semantic style mappings |
+| `onNode` | `(node) => string \| false \| void` | — | Per-node callback for filtering, overriding, or mutating |
+| `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal generation issues |
+
+---
+
+### `onNode` Callback — Advanced Node Manipulation
+
+Called for **every node** in the AST during generation. Can be `async`.
 
-const allNotes = extractNotes(ast.content);
-console.log("Document Notes:", allNotes);
-```
-
-## Configuration Object: OfficeParserConfig
-Pass an optional config object as the second argument to `parseOffice`.
-
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `outputErrorToConsole` | boolean | `false` | **Deprecated**: Use `onWarning` instead. Show logs to console in case of an error. |
-| `newlineDelimiter` | string | `\n` | Delimiter for new lines in text output. |
-| `ignoreNotes` | boolean | `false` | Ignore notes in files like PowerPoint/ODP. |
-| `putNotesAtLast` | boolean | `false` | Put notes text at the end of the document. |
-| `extractAttachments` | boolean | `false` | Extract images and charts as Base64. |
-| `includeRawContent` | boolean | `false` | Include raw XML/RTF markup in the nodes. |
-| `serializeRawContent` | boolean | `true` | Re-serializes raw XML to clean strings. |
-| `preserveXmlWhitespace` | boolean | `false` | Preserves original XML whitespace. |
-| `ocr` | boolean | `false` | Enable OCR for images (requires `extractAttachments: true`). |
-| `pdfWorkerSrc` | string | `(see below)` | Path to PDF.js worker. |
-| `ocrConfig` | object | `{}` | OCR Scheduler configuration. |
-| `includeBreakNodes` | boolean | `false` | Include `w:br`, `w:cr` nodes (DOCX only).|
-| `ignoreInternalLinks` | boolean | `false` | Remove all bookmarks and internal jumps. |
-| `csvDelimiter` | string | `,` | Custom delimiter for parsing CSV files. |
-| `fileType` | string | `null` | Manual format override (authoritative). |
-
-## Generator Configuration: GeneratorConfig
-Configuration options for `OfficeGenerator.generate`.
-
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `includeFormatting` | boolean | `true` | Whether to include semantic styles (bold, italic, colors, sizes) in output. |
-| `generateIds` | boolean | `true` | Automatically generates unique slug-based IDs for heading nodes. |
-| `renderMetadata` | boolean | `false` | Renders document metadata (Title, Author) as a visible header block. |
-| `includeImages` | boolean | `true` | Whether to include image nodes in the generated output. |
-| `includeCharts` | boolean | `true` | Whether to include interactive charts (HTML only). |
-| `ignoreInternalLinks`| boolean | `false` | Suppresses all internal bookmarks and anchor references. |
-| `ignoreDefaultStyleMap`| boolean | `false` | Ignore the library's default style mappings. |
-| `styleMap` | string[] \| array | `[]` | Array of style mappings (DSL strings or structured objects). |
-| `onNode` | function | `undefined` | Callback to filter, override, or mutate any node during generation. |
-| `onWarning` | function | `undefined` | Callback for generation-phase warnings. |
-| `htmlConfig` | object | `{}` | Format-specific settings for HTML generation. |
-| `mdConfig` | object | `{}` | Format-specific settings for Markdown generation. |
-| `pdfConfig` | object | `{}` | Format-specific settings for PDF generation. |
-| `csvConfig` | object | `{}` | Format-specific settings for CSV generation. |
-| `textConfig` | object | `{}` | Format-specific settings for Plain Text generation. |
-| `rtfConfig` | object | `{}` | Format-specific settings for RTF generation. |
-| `chunksConfig` | object | `(doc-struct)` | Settings for RAG chunking strategies. |
-
-### 🛠️ Advanced Node Manipulation (Pro Users)
-The `onNode` callback is a powerful tool that gives you complete control over the generation process. It is called for **every single node** in the AST before it is rendered.
-
-#### Callback Capabilities:
-1.  **Filter/Remove Nodes**: Return `false` to skip a node and all its children.
-2.  **Override Rendering**: Return a `string` to use that exact text as the output, bypassing default logic and recursion.
-3.  **Mutate Nodes**: Modify the `node` object directly (e.g., changing `node.text`) and return `void` to let the generator proceed with your changes.
-4.  **Async Support**: The callback can be `async`, allowing you to fetch external data or perform complex logic during generation.
-
-#### Pro Example:
-```typescript
-const result = await ast.to('md', {
+| Return value | Effect |
+|---|---|
+| `false` | Skip this node and all its children |
+| `string` | Use this string as the output for this node, skip default logic |
+| `void` | Proceed with default rendering (mutations to `node` are applied) |
+
+```ts
+const { value: md } = await ast.to('md', {
     onNode: async (node) => {
-        // 1. Skip all images
+        // Skip all images
         if (node.type === 'image') return false;
 
-        // 2. Redact sensitive info by mutating the node
+        // Redact secrets (mutate then proceed)
         if (node.text?.includes('SECRET_KEY')) {
             node.text = node.text.replace(/SECRET_KEY: \w+/, 'SECRET_KEY: [REDACTED]');
         }
 
-        // 3. Custom rendering for specific styles
+        // Custom rendering for a specific style
         if (node.metadata?.style === 'Callout') {
             return `> [!INFO]\n> ${node.text}`;
         }
-
-        // 4. Proceed with default rendering (implicitly returns void)
     }
 });
 ```
 
-### Advanced Style Mapping (Semantic Translation)
-The `styleMap` configuration is the primary way to define the "semantic meaning" of document styles. We recommend using **Structured Style Mappings** for full type safety and power.
+---
+
+### `styleMap` — Semantic Style Mapping
+
+Maps document style names to semantic output elements. Two formats supported:
 
-#### 1. Structured Style Mappings (Recommended)
-Use structured objects to match nodes based on type and attributes, and specify detailed output properties like classes and custom attributes.
+#### Structured Objects (Recommended)
 
-```typescript
+```ts
 styleMap: [
-    { 
-        selector: { 
-            nodeType: 'paragraph', 
-            attributes: { style: 'Heading 1' } 
-        }, 
-        output: { 
-            tag: 'h1', 
-            classes: ['main-title'], 
-            attributes: { id: 'top' } 
-        } 
+    {
+        selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } },
+        output: { tag: 'h1', classes: ['main-title'], attributes: { id: 'top' } }
     },
     {
-        // Use operators like '~=' for partial matches
+        // '~=' operator matches if the word 'Quote' appears anywhere in the style name
         selector: { attributes: { style: { value: 'Quote', operator: '~=' } } },
-        output: { tag: 'blockquote' }
+        output: { tag: 'blockquote', fresh: true }
     }
 ]
 ```
 
-#### 2. Legacy String DSL
-The library also maintains support for a simple string-based DSL, highly compatible with `mammoth.js`.
-
-- **Literal Matching**: `"p[style-name='Heading 1'] => h1"`
-- **Regex-like Matching**: `"p[style~='Title'] => h2"`
-- **Attribute Filters**: `"p[style-name='Quote'][lang='en'] => blockquote"`
-
-## Format-Specific Generator Configuration
-Each destination format has its own specialized sub-configuration object nested within the main `GeneratorConfig`.
-
-### 1. HtmlGeneratorConfig (`htmlConfig`)
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `standalone` | boolean | `true` | Wraps output in a full `<html>` document with CSS and metadata. |
-| `chartJsSrc` | string | `(CDN)` | URL for the Chart.js library used for interactive charts. |
-
-### 2. MdGeneratorConfig (`mdConfig`)
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `fallbackToHtml` | boolean | `true` | Uses HTML tags for features not supported by Markdown (underlines, complex tables). |
-
-### 3. PdfGeneratorConfig (`pdfConfig`)
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `format` | string | `'A4'` | Paper format (e.g., 'Letter', 'A4', 'Legal'). |
-| `landscape` | boolean | `false` | Page orientation. |
-| `margin` | object | `{0,0,0,0}` | Top, right, bottom, left margins. |
-| `displayHeaderFooter`| boolean | `false` | Whether to display print headers and footers. |
-| `headerTemplate` | string | `''` | HTML template for the print header. |
-| `footerTemplate` | string | `''` | HTML template for the print footer. |
-
-### 4. CsvGeneratorConfig (`csvConfig`)
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `sheets` | string | `''` | Range of sheets to export (e.g., "1", "1-3", "1,3"). |
-| `mergeSheets` | boolean | `true` | Merges all sheets into one CSV string. If false, returns a ZIP. |
-| `columnDelimiter` | string | `','` | Custom delimiter for the CSV output. |
-
-### 5. TextGeneratorConfig (`textConfig`)
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `newlineDelimiter` | string | `\n` | String inserted between structural blocks. |
-| `preserveLayout` | boolean | `false` | Attempts to maintain table structures using whitespace. |
-
-## One-Step Conversion: OfficeConverterConfig
-Configuration for the `OfficeConverter.convert()` API.
-
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `parseConfig` | object | `{}` | Settings for the `OfficeParser` phase. |
-| `generatorConfig` | object | `{}` | Settings for the `OfficeGenerator` phase. |
-| `onWarning` | function | `undefined` | Global callback for issues in either phase. Overrides phase-specific callbacks. |
-
-## Chunking Configuration: ChunkingConfig
-Specific options when using `format: 'chunks'`.
-
-| Flag | DataType | Default | Explanation |
-|------|----------|---------|-------------|
-| `strategy` | string | `'fixed-size'`| The chunking strategy (`fixed-size`, `document-structure`, `semantic`). |
-| `maxChunkSize` | number | `1000` | Maximum characters per chunk. |
-| `chunkOverlap` | number | `200` | Overlap between consecutive chunks. |
-| `similarityThreshold`| number | `0.5` | Threshold for semantic splitting (0.0 to 1.0). |
-| `embedBatchSize` | number | `50` | Batch size for embedding requests. |
-
-### OCR Scheduler & Resource Management
-If your application uses OCR, `officeParser` utilizes an intelligent **Smart Worker Pool** to maintain a background worker pool and optimize repeated parse requests.
-
-- **Dynamic Affinity**: Workers in the pool persist with their last used language affinity. 
-- **LRU Re-allocation**: If a new language is requested and the pool is full, the manager identifies the **Least Recently Used (LRU)** idle worker and re-initializes it for the new language. This avoids the overhead of destroying and recreating workers.
-- **Auto-Termination**: Workers are automatically cleaned up after 10 seconds of inactivity (configurable via `ocrConfig.autoTerminateTimeout`).
-
-#### `OfficeParser.terminateOcr()`
-If you have used OCR (`{ ocr: true }`) in a short-lived script (like CLI tools or one-off automation), we recommend explicitly calling `terminateOcr()` after your processing is finished. This bypasses the 10-second idle timer and allows the process to return to the terminal prompt immediately.
+`fresh: true` prevents the generator from merging adjacent nodes of the same tag into one block.
 
-> [!NOTE]
-> If OCR was not used, this function is a no-op and does not need to be called.
+#### Legacy String DSL
+
+Compatible with `mammoth.js` style maps:
 
 ```js
-const officeParser = require('officeparser');
+styleMap: [
+    "p[style-name='Heading 1'] => h1",
+    "p[style~='Title'] => h2",
+    "p[style-name='Quote'][lang='en'] => blockquote"
+]
+```
+
+---
 
-async function runCleaner() {
-    await officeParser.parseOffice("file.pdf", { ocr: true });
-    // ... process results ...
+### HtmlGeneratorConfig
 
-    // Manually kill OCR workers for an immediate exit
-    await officeParser.terminateOcr();
-}
-```
+Pass as `htmlConfig` inside `GeneratorConfig`.
 
-> [!TIP]
-> This is handled automatically in the built-in CLI (`npx officeparser ...`). You only need to call this manually if you are using the library in your own custom script and want a snappy exit.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `standalone` | `boolean` | `true` | Wrap output in a full `<html>` document with CSS |
+| `chartJsSrc` | `string` | jsDelivr CDN | URL for the Chart.js library |
 
-```js
-const config = {
-    newlineDelimiter: "\n\n",
-    extractAttachments: true,
-    ocr: true,
-    ocrLanguage: 'eng+fra+esp' // Supports English, French, and Spanish simultaneously
-};
+### MdGeneratorConfig
 
-const ast = await officeParser.parseOffice("report.docx", config);
-console.log(`Extracted ${ast.attachments.length} images`);
-```
+Pass as `mdConfig` inside `GeneratorConfig`.
 
-## Examples
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `fallbackToHtml` | `boolean` | `true` | Use HTML tags for features Markdown cannot represent (underlines, merged table cells, etc.) |
 
-**Search for a term in a document (TypeScript)**
-```ts
-import { OfficeParser } from 'officeparser';
+### PdfGeneratorConfig
 
-async function hasSearchTerm(filePath: string, term: string): Promise<boolean> {
-    const ast = await OfficeParser.parseOffice(filePath);
-    return ast.toText().includes(term);
-}
-```
+Pass as `pdfConfig` inside `GeneratorConfig`. Requires the optional `puppeteer` peer dependency.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `format` | `string` | `'A4'` | Paper format (`'A4'`, `'Letter'`, `'Legal'`, etc.) |
+| `landscape` | `boolean` | `false` | Landscape page orientation |
+| `printBackground` | `boolean` | `true` | Print background graphics |
+| `margin` | `object` | `{0,0,0,0}` | Page margins (`top`, `right`, `bottom`, `left`) |
+| `displayHeaderFooter` | `boolean` | `false` | Show print header/footer |
+| `headerTemplate` | `string` | `''` | HTML template for the print header |
+| `footerTemplate` | `string` | `''` | HTML template for the print footer |
+| `scale` | `number` | `1` | Rendering scale factor |
+| `launchOptions` | `object` | headless defaults | Puppeteer launch options (e.g., `executablePath`) |
+
+### CsvGeneratorConfig
+
+Pass as `csvConfig` inside `GeneratorConfig`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sheets` | `string` | `''` | Sheet range to export: `'1'`, `'1-3'`, `'1,3'` (1-based). Empty = all sheets |
+| `mergeSheets` | `boolean` | `true` | Merge all sheets into one CSV. If `false`, returns a ZIP archive |
+| `columnDelimiter` | `string` | `','` | Output column delimiter |
+
+### TextGeneratorConfig
+
+Pass as `textConfig` inside `GeneratorConfig`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `newlineDelimiter` | `string` | `'\n'` | String inserted between structural blocks |
+| `preserveLayout` | `boolean` | `false` | Render tables with aligned columns using whitespace |
+
+---
+
+### OfficeConverterConfig
+
+Configuration for `OfficeConverter.convert(file, format, config)`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `parseConfig` | `OfficeParserConfig` | Settings for the parsing phase |
+| `generatorConfig` | `GeneratorConfig` | Settings for the generation phase |
+| `onWarning` | `(issue: OfficeIssue) => void` | Global warning callback (overrides phase-specific ones) |
+
+---
+
+### ChunkingConfig
+
+`ChunkingConfig` is a **discriminated union** — the available options depend on the `strategy` field.
+
+#### Common Options (all strategies)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strategy` | `string` | `'document-structure'` | Chunking strategy |
+| `stripWhitespace` | `boolean` | `true` | Trim leading/trailing whitespace from each chunk |
+| `includeMetadata` | `boolean` | `true` | Include page/slide/heading metadata in each chunk |
+| `addStartIndex` | `boolean` | `false` | Add `startIndex` character offset to chunk metadata |
+| `lengthFunction` | `(text) => number` | `text.length` | Custom size measurer (e.g., token counter) |
+| `sentenceBoundaryRegex` | `string \| RegExp` | `/[.!?。！？]/` | Custom regex for sentence boundary detection |
+| `abbreviations` | `string[]` | common list | Abbreviations to skip when splitting on `.` |
+
+#### `strategy: 'fixed-size'`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `chunkSize` | `number` | `1000` | Maximum characters per chunk |
+| `chunkOverlap` | `number` | `200` | Character overlap between consecutive chunks |
+| `separators` | `string[]` | `['\n\n','\n',' ','']` | Ordered list of separators to try |
+
+#### `strategy: 'document-structure'`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `splitBy` | `string` | `'paragraph'` | `'paragraph'` · `'heading'` · `'page'` · `'slide'` · `'sheet'` |
+| `maxChunkSize` | `number` | `1000` | Max characters per chunk (oversized units are split recursively) |
+| `tableSplitStrategy` | `string` | `'row'` | `'row'` (repeats header in each chunk) or `'flatten'` |
+
+#### `strategy: 'semantic'`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `embeddingFunction` | `(text) => Promise<number[]>` | **required** | Async embedding function |
+| `similarityThreshold` | `number` | `0.8` | Cosine similarity threshold; lower = fewer boundaries |
+| `maxChunkSize` | `number` | `2000` | Max characters even if similarity stays high |
+| `bufferSize` | `number` | `1` | Surrounding sentences used when computing similarity |
+| `embeddingBatchSize` | `number` | `50` | Sentences per embedding API batch |
+
+---
+
+## OCR Scheduler & Resource Management
+
+When `ocr: true` is set, `officeParser` maintains an intelligent **Smart Worker Pool** backed by Tesseract.js:
+
+- **Dynamic Affinity**: Workers persist with their last-used language, avoiding re-initialization overhead.
+- **LRU Re-allocation**: When a new language is requested and the pool is full, the Least Recently Used idle worker is re-initialized.
+- **Auto-Termination**: Workers shut down after 10 seconds of inactivity (configurable via `ocrConfig.autoTerminateTimeout`).
+
+### OCR Config (`ocrConfig`)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `language` | `string` | `'eng'` | Tesseract language code(s), e.g. `'eng+fra'` |
+| `workerPath` | `string` | `''` | Custom path to Tesseract worker script |
+| `corePath` | `string` | `''` | Custom path to Tesseract core script |
+| `langPath` | `string` | `''` | Custom path for language data files |
+| `autoTerminateTimeout` | `number` | `10000` | Inactivity timeout in ms before auto-teardown (0 = disabled) |
+
+See all language codes at [tesseract-ocr.github.io](https://tesseract-ocr.github.io/tessdoc/Data-Files).
+
+### `OfficeParser.terminateOcr()`
+
+In **short-lived scripts** (CLI tools, one-off automation), call `terminateOcr()` after processing to bypass the idle timer and exit immediately:
 
-**Extracting Images and their OCR text**
 ```js
 const officeParser = require('officeparser');
 
-const config = { extractAttachments: true, ocr: true };
-officeParser.parseOffice("presentation.pptx", config).then(ast => {
-    ast.attachments.forEach(attachment => {
-        if (attachment.type === 'image') {
-            console.log(`Image: ${attachment.name}`);
-            console.log(`OCR Text: ${attachment.ocrText}`);
-            fs.writeFileSync(attachment.name, Buffer.from(attachment.data, 'base64'));
-        }
-    });
-});
+const ast = await officeParser.parseOffice('file.pdf', { ocr: true });
+// ... process results ...
+await officeParser.terminateOcr(); // immediate exit
 ```
 
+> [!TIP]
+> The built-in CLI (`npx officeparser ...`) handles this automatically.
+> Only call it manually in your own scripts.
+
+---
+
 ## Browser Usage
-The library provides two types of browser bundles in the `dist/` directory:
-1. **`officeparser.browser.iife.js`**: Standard IIFE bundle for direct `<script>` tag usage. Exposes the global `officeParser` namespace.
-2. **`officeparser.browser.mjs`**: Modern ESM bundle for use with `import` statements or modern bundlers.
 
-### Usage (ESM)
-If you are using a modern bundler like **Vite**, **Webpack**, or **Next.js**:
+Two bundles are available in the `dist/` directory:
+
+| Bundle | Usage |
+|--------|-------|
+| `officeparser.browser.mjs` | ESM — use with `import` statements or modern bundlers (Vite, Webpack, Next.js) |
+| `officeparser.browser.iife.js` | IIFE — use with a `<script>` tag; exposes the global `officeParser` object |
 
-```javascript
+### ESM (Vite / Webpack / Next.js)
+
+```js
 import { OfficeParser } from 'officeparser';
 
 const handleFile = async (event) => {
     const file = event.target.files[0];
     const buffer = await file.arrayBuffer();
-    
-    try {
-        // Pass the Buffer or Uint8Array directly
-        const ast = await OfficeParser.parseOffice(new Uint8Array(buffer));
-        console.log(ast.toText());
-    } catch (err) {
-        console.error(err);
-    }
+    const ast = await OfficeParser.parseOffice(new Uint8Array(buffer));
+    console.log(ast.toText());
 };
 ```
 
-> [!NOTE] 
-> **Why `fs` fails in the browser**: Browsers do not have a built-in file system. If you try to pass a file path string in the browser, `officeParser` will throw a descriptive "Fail-Fast" error instead of crashing mysteriously: 
-> `[officeparser] Node.js 'fs' module is not available in the browser. Please pass a Buffer or Uint8Array instead.`
-
-### Usage (Script Tag)
-Include the IIFE bundle available in the release assets or your `dist/` folder. This exposes the global `officeParser` object.
+### Script Tag
 
 ```html
 <script src="dist/officeparser.browser.iife.js"></script>
@@ -807,60 +878,78 @@ Include the IIFE bundle available in the release assets or your `dist/` folder.
     async function handleFile(event) {
         const file = event.target.files[0];
         const buffer = await file.arrayBuffer();
-        
-        try {
-            // Reconstruct as Uint8Array for the parser
-            const ast = await officeParser.parseOffice(new Uint8Array(buffer));
-            console.log(ast.toText());
-        } catch (error) {
-            console.error("Parsing failed:", error);
-        }
+        const ast = await officeParser.parseOffice(new Uint8Array(buffer));
+        console.log(ast.toText());
     }
 </script>
 ```
 
-### PDF Worker Configuration in Browser
-When using `officeparser` in a browser environment to parse PDF files, you may provide the `pdfWorkerSrc` configuration option. If not provided, it defaults to a CDN link for `pdfjs-dist@5.6.205`.
+> [!NOTE]
+> **File paths don't work in the browser.** Always pass a `Buffer`, `ArrayBuffer`, or `Uint8Array`.
+> Passing a path string will throw a descriptive `FEATURE_NOT_SUPPORTED_IN_BROWSER` error.
+
+### PDF Worker Configuration
 
-```javascript
-const file = ...; // File object or ArrayBuffer
+When parsing PDFs in the browser, a Web Worker is required. If `pdfWorkerSrc` is omitted, a jsDelivr CDN link is used automatically:
 
-// It will use the default CDN worker if pdfWorkerSrc is omitted
-const ast = await officeParser.parseOffice(file);
+```js
+// Uses default CDN worker:
+const ast = await officeParser.parseOffice(pdfArrayBuffer);
 
-// Or override it with your own path or a different version:
-const ast2 = await officeParser.parseOffice(file, {
-    pdfWorkerSrc: "https://cdn.jsdelivr.net/npm/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs"
+// Or specify your own:
+const ast = await officeParser.parseOffice(pdfArrayBuffer, {
+    pdfWorkerSrc: 'https://cdn.jsdelivr.net/npm/pdfjs-dist@5.6.205/build/pdf.worker.min.mjs'
 });
 ```
 
-> **Note:** The version of `pdfjs-dist` in the worker source should match the version used by `officeparser` (currently `5.6.205`).
+> [!NOTE]
+> The `pdfjs-dist` worker version must match the version bundled with `officeparser` (currently **5.6.205**).
+
+---
 
 ## Troubleshooting & Common Issues
 
-- **Node.js process stays alive after finishing**: If using OCR, the worker pool stays warm for 10s by default. Use `await terminateOcr()` at the end of your script for a snappy exit.
-- **"Worker not found" in Browser**: Ensure `pdfWorkerSrc` is correctly pointed to the `pdf.worker.min.mjs` file matching version `5.6.205`.
-- **OCR accuracy is low**: Verify your `ocrConfig.language` matches the document content. Note that OCR quality depends on image resolution.
-- **Out of memory on large files**: For massive spreadsheets, consider using `ast.toText()` early and allowing the full AST object to be garbage-collected.
+| Symptom | Fix |
+|---------|-----|
+| Node.js process stays alive after finishing | Call `await officeParser.terminateOcr()` at end of script when OCR was used |
+| `"Worker not found"` in browser for PDF | Verify `pdfWorkerSrc` points to `pdf.worker.min.mjs` matching version `5.6.205` |
+| Low OCR accuracy | Verify `ocrConfig.language` matches the document language; quality depends on image resolution |
+| Out of memory on large Excel files | Call `ast.toText()` early and discard the AST object to allow garbage collection |
+| `md`/`html`/`csv` buffer not detected | Add `fileType: 'md'` (or `'html'`, `'csv'`) to config — these formats have no magic bytes |
+| `IMPROPER_BUFFERS` error | Usually means no file extension and no `fileType` hint was provided for a buffer input |
+| PDF generation fails | Install the optional peer dependency: `npm install puppeteer` |
 
-For a comprehensive guide, visit our [Debugging & Troubleshooting Documentation](https://harshankur.github.io/officeParser/#spec/debugging).
+For a full debugging guide, visit the [Live Documentation](https://harshankur.github.io/officeParser/#spec/debugging).
 
+---
 
 ## Known Limitations
-1. **ODT/ODS Charts**: Extraction may occasionally show inaccurate data when referencing external cell ranges or complex layout-based data.
-2. **PDF Images**: PDF images are extracted as BMP files in the browser for compatibility. This conversion happens automatically.
-3. **RTF Footnotes**: The `putNotesAtLast` configuration is currently not supported for RTF files; footnotes and endnotes are always collected and appended to the end of the content.
 
-----------
+1. **ODT/ODS Charts**: May show inaccurate data when the chart references external cell ranges or uses complex layout-based data.
+2. **PDF Images (Browser)**: Extracted as BMP files for cross-platform compatibility. Conversion is automatic.
+3. **RTF Notes**: `putNotesAtLast` has no effect for RTF files; footnotes and endnotes are always appended at the end.
+
+---
 
 **npm**: [https://npmjs.com/package/officeparser](https://npmjs.com/package/officeparser)
 
 **github**: [https://github.com/harshankur/officeParser](https://github.com/harshankur/officeParser)
 
+## Support the Project
+
+If `officeParser` has helped you save time, consider supporting its continued development. Your sponsorship helps maintain the project, add new features, and keep it robust for everyone.
+
+<a href="https://github.com/sponsors/harshankur">
+  <img src="https://img.shields.io/badge/Sponsor-GitHub-ea4aaa?style=for-the-badge&logo=github-sponsors" height="36">
+</a>
+<a href="https://www.buymeacoffee.com/harshankur">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" height="36" alt="Buy Me A Coffee">
+</a>
+
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.