officeparser 7.1.0 → 7.2.1

package/README.md

@@ -1,4 +1,4 @@
-# officeParser — Universal Office Document Parser & Generator
+# officeParser: Universal Office Document Parser & Generator
 
 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.
 
@@ -14,7 +14,7 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
 ---
 
 ### 🌟 [Live Interactive AST Visualizer & Documentation](https://harshankur.github.io/officeParser/) 🌟
-*Upload any office file in your browser — inspect the AST, tweak config, and preview generated output in real-time.*
+*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
@@ -35,10 +35,10 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
   - [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)
+  - [`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)
+- [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)
@@ -47,8 +47,8 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
 - [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)
+  - [onNode Callback](#onnode-callback-advanced-node-manipulation)
+  - [styleMap: Semantic Style Mapping](#stylemap-semantic-style-mapping)
   - [HtmlGeneratorConfig](#htmlgeneratorconfig)
   - [MdGeneratorConfig](#mdgeneratorconfig)
   - [PdfGeneratorConfig](#pdfgeneratorconfig)
@@ -79,37 +79,58 @@ npm i officeparser
 npx officeparser /path/to/file.docx
 
 # Plain text output
-npx officeparser /path/to/file.docx --format=text
+npx officeparser /path/to/file.docx --to=text
 
 # Convert DOCX to Markdown and save
-npx officeparser report.docx --format=md --output=report.md
+npx officeparser report.docx --to=md --output=report.md
 
-# Convert PPTX to HTML
-npx officeparser presentation.pptx --format=html --output=preview.html
+# Convert PPTX to HTML (using a bare flag for ocr)
+npx officeparser presentation.pptx --to=html --output=preview.html --ocr
 
-# Convert XLSX to CSV
-npx officeparser data.xlsx --format=csv
+# Convert XLSX to CSV with a custom delimiter
+npx officeparser data.xlsx --to=csv --csvDelimiter=";"
 
 # Generate RAG chunks
-npx officeparser document.pdf --format=chunks
+npx officeparser document.pdf --to=chunks
+
+# Overriding file extension mapping
+npx officeparser my_document --fileType=docx --to=json
 ```
 
+### CLI Syntax
+- **Values:** Flags can be passed as `--flag=value` or `--flag value`.
+- **Booleans:** Bare flags imply `true` (e.g. `--ocr` is equivalent to `--ocr=true`). Negation flags start with `no-` (e.g. `--no-ocr` is equivalent to `--ocr=false`).
+- **Nested Objects:** You can pass nested properties directly using JSON dot-notation (e.g. `--ocrConfig.language=fra` or `--htmlConfig.containerWidth=900px`).
+
 ### CLI Options
 
 | Flag | Values | Default | Description |
 |------|--------|---------|-------------|
-| `--format` | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | Output format |
+| `--to` | `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 |
+| `--fileType` | `docx\|xlsx\|pptx\|odt\|odp\|ods\|pdf\|rtf\|csv\|md\|html` | — | Explicitly override input file type detection |
+| `--ocr` | boolean | `false` | Enable OCR for images |
+| `--extractAttachments` | boolean | `false` | Extract images/charts as Base64 |
+| `--ignoreNotes` | boolean | `false` | Ignore footnotes/endnotes/speaker notes |
+| `--ignoreComments` | boolean | `false` | Ignore inline comments |
+| `--ignoreHeadersAndFooters` | boolean | `false` | Ignore headers and footers |
+| `--ignoreSlideMasters` | boolean | `false` | Ignore slide masters |
+| `--ignoreInternalLinks` | boolean | `false` | Ignore internal links |
+| `--newlineDelimiter` | string | `\n` | Delimiter between lines/blocks in plaintext outputs |
+| `--csvDelimiter` | string | `,` | Custom delimiter for CSV files |
+| `--includeRawContent` | boolean | `false` | Include raw XML/RTF in nodes |
+| `--serializeRawContent` | boolean | `true` | Include stringified XML in metadata |
+| `--preserveXmlWhitespace` | boolean | `false` | Keep raw formatting space |
+| `--includeBreakNodes` | boolean | `false` | Include break nodes (DOCX only) |
+| `--verbose` | boolean | `false` | Show full error stack traces and warning logs |
+| `--includeFormatting` | boolean | `true` | Include formatting style map matching |
+| `--renderMetadata` | boolean | `false` | Render metadata as visible content in the generated output |
+| `--htmlConfig.containerWidth` | string \| number | `auto` | HTML output container width (e.g. `900px`, `100%`) |
+| ~~`--format`~~ | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | **Deprecated.** Use `--to` |
+| ~~`--toText`~~ | `true\|false` | `false` | **Deprecated.** Use `--to=text` |
+| ~~`--ocrLanguage`~~ | string | `eng` | **Deprecated.** Use `--ocrConfig.language` |
+| ~~`--putNotesAtLast`~~ | `true\|false` | `false` | **Deprecated and ignored.** Notes are attached structurally to their nodes. |
+| ~~`--outputErrorToConsole`~~ | `true\|false` | `false` | **Deprecated.** Use `--verbose` |
 
 ---
 
@@ -232,7 +253,7 @@ const ast = await officeParser.parseOffice('scanned_document.pdf', {
 > **Non-Fatal Timeout Recovery**
 > If `workerLoad` or `recognition` timeouts are exceeded, the parser will log a warning in `ast.warnings` and **continue parsing the rest of the document**. The overall promise resolves successfully with the text extracted from the document layers (rather than failing the entire parse).
 
-### `ast.to()` — Generate from AST
+### `ast.to()`: Generate from AST
 
 The preferred way to convert a parsed AST to another format. Returns a `ConversionResult`.
 
@@ -246,7 +267,7 @@ const { value: chunks }             = await ast.to('chunks', { strategy: 'fixed-
 const { value: pdfBytes }           = await ast.to('pdf'); // Uint8Array
 ```
 
-### `ast.toText()` — Quick Text Extraction
+### `ast.toText()`: Quick Text Extraction
 
 > [!NOTE]
 > `toText()` is **synchronous** and deprecated in favour of the async `ast.to('text')`.
@@ -295,7 +316,7 @@ const { value: csv } = await OfficeGenerator.generate(ast, 'csv');
 
 ---
 
-## OfficeConverter — One-Step API
+## 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).
 
@@ -326,7 +347,7 @@ const { value: html, messages } = await OfficeConverter.convert('data.xlsx', 'ht
 
 > [!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.
+> Do **not** put parser or generator options at the top level; only `onWarning` lives there.
 
 ---
 
@@ -344,7 +365,7 @@ const { value: chunks } = await OfficeConverter.convert('report.docx', 'chunks',
             strategy: 'document-structure',
             splitBy: 'heading',    // 'paragraph' | 'heading' | 'page' | 'slide' | 'sheet'
             maxChunkSize: 1500,
-            tableSplitStrategy: 'row', // repeats header row in every chunk — ideal for RAG
+            tableSplitStrategy: 'row', // repeats header row in every chunk, ideal for RAG
         }
     }
 });
@@ -420,13 +441,19 @@ interface OfficeChunk {
 ```text
 OfficeParserAST
 ├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | ...  (11 formats)
-├── metadata: { author, title, created, modified, customProperties, styleMap, ... }
+├── metadata: { author, title, created, modified, keywords, customProperties, nativeProperties, styleMap, ... }
 ├── content: [ OfficeContentNode ]
-│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | ...
+│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | 'comment' | ...
 │   ├── text: string  (concatenated text of node + all descendants)
-│   ├── children: [ OfficeContentNode ]  (recursive)
+│   ├── children: [ OfficeContentNode ]  (recursive structural children)
+│   ├── notes: [ OfficeContentNode ]     (footnotes/endnotes/slide notes attached to this node)
+│   ├── comments: [ OfficeContentNode ] (inline comments attached to this node)
 │   ├── formatting: { bold, italic, underline, color, size, font, alignment, ... }
-│   └── metadata: { level, listId, row, col, rowSpan, colSpan, style, ... }
+│   └── metadata: { level, listId, row, col, rowSpan, colSpan, backgroundColor, style, ... }
+├── auxiliary?: OfficeAuxiliaryContent   (out-of-band layout elements)
+│   ├── headers?: OfficeContentNode[]   (DOCX headers)
+│   ├── footers?: OfficeContentNode[]   (DOCX footers)
+│   └── slideMasters?: OfficeContentNode[] (PPTX slide masters)
 ├── attachments: [ OfficeAttachment ]  (populated when extractAttachments: true)
 │   ├── type: 'image' | 'chart'
 │   ├── name: string
@@ -436,10 +463,10 @@ OfficeParserAST
 │   └── 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)
+└── ~~toText()~~             (Deprecated: use .to('text') instead)
 ```
 
-### `OfficeIssue` — Warning / Error Object
+### `OfficeIssue`: Warning / Error Object
 
 All warnings and errors (from both parsing and generation) use this shape:
 
@@ -552,17 +579,21 @@ ast.metadata = {
     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
+    keywords?: string                            // NEW: Keywords from document properties
+    customProperties?: Record<string, any>       // User-defined metadata from the document
+    nativeProperties?: Record<string, any>       // NEW: All format-specific raw metadata
+    styleMap?: Record<string, TextFormatting>    // Named styles → formatting definitions
+    formatting?: TextFormatting                  // Document-wide defaults
 }
 ```
 
-**Accessing custom properties:**
+**Accessing native properties (format-specific metadata):**
 ```js
 const ast = await officeParser.parseOffice('contract.docx');
-console.log(ast.metadata.customProperties);
-// { "ProjectID": "ABC-123", "InternalReview": true }
+console.log(ast.metadata.nativeProperties);
+// DOCX: { Pages: 5, Application: 'Microsoft Word' }
+// HTML: { description: 'My page', 'og:title': 'Title' }
+// PDF:  { Title: 'Report', XMP: { ... } }
 ```
 
 ---
@@ -586,6 +617,61 @@ const headings = ast.content.filter(n => n.type === 'heading' && n.metadata?.lev
 console.log(headings.map(h => h.text));
 ```
 
+### Extract comments
+```ts
+// Comments can be attached to any nested node, so we must traverse recursively
+const printComments = (nodes: OfficeContentNode[]) => {
+    nodes.forEach(node => {
+        if (node.comments) {
+            node.comments.forEach(c => {
+                console.log(`Comment by ${c.metadata?.author}: ${c.text}`);
+            });
+        }
+        if (node.children) {
+            printComments(node.children);
+        }
+    });
+};
+
+printComments(ast.content);
+```
+
+Set `ignoreComments: true` to skip extraction.
+
+### Extract footnotes, endnotes & slide notes
+```ts
+// Slide speaker notes (PPTX) live on the slide node itself
+const slide = ast.content.find(n => n.type === 'slide');
+console.log(slide?.notes?.map(n => n.text));
+
+// Footnotes and endnotes (DOCX/RTF) can be deeply nested, so we traverse recursively:
+const printNotes = (nodes: OfficeContentNode[]) => {
+    nodes.forEach(node => {
+        if (node.notes) {
+            node.notes.forEach(note => console.log(note.text));
+        }
+        if (node.children) {
+            printNotes(node.children);
+        }
+    });
+};
+
+printNotes(ast.content);
+```
+
+> [!IMPORTANT]
+> `putNotesAtLast` is **deprecated**. Notes are always attached via `node.notes`; this flag has no effect and will be removed in a future major version.
+
+### Access headers, footers & slide masters
+```ts
+// These are NOT in ast.content; use ast.auxiliary
+console.log(ast.auxiliary?.headers?.map(h => h.text));   // DOCX headers
+console.log(ast.auxiliary?.footers?.map(f => f.text));   // DOCX footers
+console.log(ast.auxiliary?.slideMasters?.length);         // PPTX slide masters
+```
+
+Set `ignoreHeadersAndFooters: true` or `ignoreSlideMasters: true` to skip extraction.
+
 ### Extract images with OCR text
 ```js
 const ast = await officeParser.parseOffice('report.docx', { extractAttachments: true, ocr: true });
@@ -650,11 +736,14 @@ 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 |
+| `ignoreNotes` | `boolean` | `false` | Ignore footnotes/endnotes (DOCX, RTF) and speaker notes (PPTX/ODP) |
+| `ignoreComments` | `boolean` | `false` | **New**: Ignore inline comments/annotations (DOCX, XLSX, PPTX), attached by default via `node.comments[]` |
+| `ignoreHeadersAndFooters` | `boolean` | `false` | **New**: Skip DOCX headers & footers (populated in `ast.auxiliary.headers/footers` by default) |
+| `ignoreSlideMasters` | `boolean` | `false` | **New**: Skip PPTX slide masters (populated in `ast.auxiliary.slideMasters` by default) |
+| ~~`putNotesAtLast`~~ | `boolean` | `false` | **Deprecated**: Notes are now attached via `node.notes[]`. This flag has no effect |
 | `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) |
+| `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 |
@@ -665,7 +754,7 @@ Pass as the second argument to `parseOffice(file, config)`.
 | `pdfWorkerSrc` | `string` | CDN (jsDelivr) | Path/URL to `pdf.worker.min.mjs` (required in browser) |
 | `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal parsing issues |
 | `abortSignal` | `AbortSignal \| null` | `null` | Optional signal to cancel parsing (rejects with AbortError) |
-| `outputErrorToConsole` | `boolean` | `false` | **Deprecated.** Use `onWarning` instead |
+| ~~`outputErrorToConsole`~~ | `boolean` | `false` | **Deprecated.** Use `onWarning` instead |
 
 ---
 
@@ -689,7 +778,7 @@ Options shared by all generator formats. Pass to `OfficeGenerator.generate(ast,
 
 ---
 
-### `onNode` Callback — Advanced Node Manipulation
+### `onNode` Callback: Advanced Node Manipulation
 
 Called for **every node** in the AST during generation. Can be `async`.
 
@@ -720,7 +809,7 @@ const { value: md } = await ast.to('md', {
 
 ---
 
-### `styleMap` — Semantic Style Mapping
+### `styleMap`: Semantic Style Mapping
 
 Maps document style names to semantic output elements. Two formats supported:
 
@@ -764,6 +853,12 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 |--------|------|---------|-------------|
 | `standalone` | `boolean` | `true` | Wrap output in a full `<html>` document with CSS |
 | `chartJsSrc` | `string` | jsDelivr CDN | URL for the Chart.js library |
+| `containerWidth` | `string \| number` | `'auto'` | Max width of the content container. Positive number (px), CSS length string (`'900px'`, `'100%'`, `'60vw'`), or `'auto'`. Invalid values fall back to `'auto'` with an `INVALID_CONTAINER_WIDTH` warning |
+| `customCss` | `string` | `''` | Raw CSS injected into the `<style>` block; use this to override built-in styles |
+| `injections.headStart` | `string` | `''` | Raw HTML injected after `<head>` |
+| `injections.headEnd` | `string` | `''` | Raw HTML injected before `</head>` |
+| `injections.bodyStart` | `string` | `''` | Raw HTML injected after `<body>` |
+| `injections.bodyEnd` | `string` | `''` | Raw HTML injected before `</body>` |
 
 ### MdGeneratorConfig
 
@@ -780,6 +875,8 @@ Pass as `pdfConfig` inside `GeneratorConfig`. Requires the optional `puppeteer`
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `format` | `string` | `'A4'` | Paper format (`'A4'`, `'Letter'`, `'Legal'`, etc.) |
+| `width` | `string \| number` | `''` | Paper width (e.g., `'5in'`, `'3cm'`) or pixels |
+| `height` | `string \| number` | `''` | Paper height (e.g., `'5in'`, `'3cm'`) or pixels |
 | `landscape` | `boolean` | `false` | Landscape page orientation |
 | `printBackground` | `boolean` | `true` | Print background graphics |
 | `margin` | `object` | `{0,0,0,0}` | Page margins (`top`, `right`, `bottom`, `left`) |
@@ -807,7 +904,7 @@ 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 |
+| `preserveLayout` | `boolean` | `true` | Render tables with aligned columns using whitespace |
 
 ---
 
@@ -825,7 +922,7 @@ Configuration for `OfficeConverter.convert(file, format, config)`.
 
 ### ChunkingConfig
 
-`ChunkingConfig` is a **discriminated union** — the available options depend on the `strategy` field.
+`ChunkingConfig` is a **discriminated union**: the available options depend on the `strategy` field.
 
 #### Common Options (all strategies)
 
@@ -885,7 +982,7 @@ When `ocr: true` is set, `officeParser` maintains an intelligent **Smart Worker
 | `corePath` | `string` | `''` | Custom path to Tesseract core script |
 | `langPath` | `string` | `''` | Custom path for language data files |
 | `timeout` | `OcrTimeoutConfig` | `{}` | Consolidated timeouts: `autoTerminate`, `workerLoad`, `recognition` |
-| `autoTerminateTimeout` | `number` | `10000` | **Deprecated.** Use `timeout.autoTerminate` instead |
+| ~~`autoTerminateTimeout`~~ | `number` | `10000` | **Deprecated.** Use `timeout.autoTerminate` instead |
 
 See all language codes at [tesseract-ocr.github.io](https://tesseract-ocr.github.io/tessdoc/Data-Files).
 
@@ -913,8 +1010,8 @@ 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 |
+| `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 |
 
 ### ESM (Vite / Webpack / Next.js)
 
@@ -974,7 +1071,7 @@ const ast = await officeParser.parseOffice(pdfArrayBuffer, {
 | `"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 |
+| `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` |
 
@@ -986,7 +1083,6 @@ For a full debugging guide, visit the [Live Documentation](https://harshankur.gi
 
 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.
 
 ---
 
@@ -1011,4 +1107,4 @@ Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for det
 
 ## 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.

package/dist/OfficeGenerator.d.ts

@@ -1,8 +1,12 @@
-import { ConversionResult, GeneratorConfig, OfficeParserAST, SupportedDestination, SupportedFileType } from './types.js';
+import { ConversionResult, GeneratorConfig, OfficeParserAST, SupportedDestination, SupportedFileType, UniversalGeneratorFormat } from './types.js';
 /**
  * Main generator class providing document conversion functionality.
  */
 export declare class OfficeGenerator {
+    /**
+     * Normalizes format aliases (e.g., 'txt' to 'text', 'markdown' to 'md') to standard internal formats.
+     */
+    static normalizeDestination(dest: string): UniversalGeneratorFormat;
     /**
      * Generates a file of the specified type from an AST.
      * This is the single source of truth for generation logic.
@@ -15,5 +19,5 @@ export declare class OfficeGenerator {
      */
     static generate<T extends SupportedFileType, D extends SupportedDestination<T>>(ast: OfficeParserAST & {
         type: T;
-    }, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult>;
+    }, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult<D>>;
 }

package/dist/OfficeGenerator.js

@@ -14,6 +14,17 @@ const errorUtils_js_1 = require("./utils/errorUtils.js");
  * Main generator class providing document conversion functionality.
  */
 class OfficeGenerator {
+    /**
+     * Normalizes format aliases (e.g., 'txt' to 'text', 'markdown' to 'md') to standard internal formats.
+     */
+    static normalizeDestination(dest) {
+        const d = dest?.toLowerCase();
+        if (d === 'txt')
+            return 'text';
+        if (d === 'markdown')
+            return 'md';
+        return d;
+    }
     /**
      * Generates a file of the specified type from an AST.
      * This is the single source of truth for generation logic.
@@ -25,24 +36,34 @@ class OfficeGenerator {
      * @throws {Error} If the destination format is unsupported
      */
     static async generate(ast, destination, config) {
-        switch (destination.toLowerCase()) {
+        let generator;
+        const normalizedDestination = OfficeGenerator.normalizeDestination(destination);
+        switch (normalizedDestination) {
             case 'text':
-                return new TextGenerator_js_1.TextGenerator(ast, config).generate();
+                generator = new TextGenerator_js_1.TextGenerator(ast, config);
+                break;
             case 'md':
-                return new MarkdownGenerator_js_1.MarkdownGenerator(ast, config).generate();
+                generator = new MarkdownGenerator_js_1.MarkdownGenerator(ast, config);
+                break;
             case 'html':
-                return new HtmlGenerator_js_1.HtmlGenerator(ast, config).generate();
+                generator = new HtmlGenerator_js_1.HtmlGenerator(ast, config);
+                break;
             case 'pdf':
-                return new PdfGenerator_js_1.PdfGenerator(ast, config).generate();
+                generator = new PdfGenerator_js_1.PdfGenerator(ast, config);
+                break;
             case 'csv':
-                return new CsvGenerator_js_1.CsvGenerator(ast, config).generate();
+                generator = new CsvGenerator_js_1.CsvGenerator(ast, config);
+                break;
             case 'rtf':
-                return new RtfGenerator_js_1.RtfGenerator(ast, config).generate();
+                generator = new RtfGenerator_js_1.RtfGenerator(ast, config);
+                break;
             case 'chunks':
-                return new ChunkingGenerator_js_1.ChunkingGenerator(ast, config).generate();
+                generator = new ChunkingGenerator_js_1.ChunkingGenerator(ast, config);
+                break;
             default:
-                throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.EXTENSION_UNSUPPORTED, undefined, destination);
+                throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.FORMAT_UNSUPPORTED, undefined, destination);
         }
+        return generator.generate();
     }
 }
 exports.OfficeGenerator = OfficeGenerator;

package/dist/OfficeParser.d.ts

@@ -81,7 +81,7 @@ export declare class OfficeParser {
      * });
      *
      * // Parse a Buffer with OCR enabled
-     * const buffer = await fetch('document.pdf').then(r => r.arrayBuffer());
+     * const buffer = await retrieveData('document.pdf').then(r => r.arrayBuffer());
      * const ast = await OfficeParser.parseOffice(buffer, {
      *   ocr: true,
      *   ocrLanguage: 'eng+fra'

package/dist/OfficeParser.js

@@ -98,7 +98,7 @@ class OfficeParser {
      * });
      *
      * // Parse a Buffer with OCR enabled
-     * const buffer = await fetch('document.pdf').then(r => r.arrayBuffer());
+     * const buffer = await retrieveData('document.pdf').then(r => r.arrayBuffer());
      * const ast = await OfficeParser.parseOffice(buffer, {
      *   ocr: true,
      *   ocrLanguage: 'eng+fra'

package/dist/cli.d.ts

@@ -4,19 +4,25 @@
  *
  * Allows running officeparser from the command line:
  *   npx officeparser file.docx
- *   officeparser file.docx --toText=true
- *   officeparser file.docx --ocr=true --extractAttachments=true
+ *   officeparser file.docx --to=text
+ *   officeparser file.docx --ocr --extractAttachments
  *
- * Options (--key=value):
- *   --format=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format
+ * Options (--key=value, --key value, or bare flags):
+ *   --to=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format (default: json)
  *   --output=path             Save result to a file
- *   --toText=true             Legacy flag for plain text output
- *   --ocr=true                Enable OCR for images
- *   --ocrLanguage=eng         OCR language (default: eng)
- *   --extractAttachments=true Extract embedded attachments
- *   --ignoreNotes=true        Ignore footnotes/endnotes
- *   --putNotesAtLast=true     Move notes to end of document
- *   --includeRawContent=true  Include raw content in AST
- *   --outputErrorToConsole=true  Log errors to console
+ *   --fileType=docx|xlsx|...  Override file type detection
+ *   --ocr                     Enable OCR for images (default: false)
+ *   --ocrConfig.language=eng  OCR language (default: eng)
+ *   --extractAttachments      Extract embedded attachments (default: false)
+ *   --ignoreNotes             Ignore footnotes/endnotes/speaker notes (default: false)
+ *   --ignoreComments          Ignore inline comments (default: false)
+ *   --ignoreHeadersAndFooters Ignore headers and footers (default: false)
+ *   --ignoreSlideMasters      Ignore slide masters (default: false)
+ *   --ignoreInternalLinks     Ignore internal links (default: false)
+ *   --includeRawContent       Include raw content in AST (default: false)
+ *   --serializeRawContent     Include stringified XML in metadata (default: true)
+ *   --preserveXmlWhitespace   Keep raw formatting space (default: false)
+ *   --includeBreakNodes       Include break nodes (DOCX only, default: false)
+ *   --verbose                 Show full error stack traces and warning logs
  */
 export {};