officeparser 7.1.0 → 7.2.0

package/dist/generators/MarkdownGenerator.d.ts

@@ -37,7 +37,7 @@ export declare class MarkdownGenerator extends BaseGenerator<'md'> {
      *
      * @returns A Markdown string
      */
-    generate(): Promise<ConversionResult>;
+    generate(): Promise<ConversionResult<'md'>>;
     /**
      * Recursively processes nodes and builds output.
      * Overridden to provide AST optimization (merging adjacent text nodes).

package/dist/generators/MarkdownGenerator.js

@@ -136,7 +136,9 @@ class MarkdownGenerator extends BaseGenerator_js_1.BaseGenerator {
                     else if (this.config.generateIds) {
                         id = ` {#${this.slugify(this.getNodeText(node))}}`;
                     }
-                    const anchors = remainingAnchors.map(aid => `<a name="${aid}"></a>`).join('');
+                    const anchors = this.config.mdConfig.fallbackToHtml
+                        ? remainingAnchors.map(aid => `<a name="${aid}"></a>`).join('')
+                        : '';
                     let content = `${prefix}${childrenOutput}${id}`;
                     // Alignment fallback via HTML div/p
                     if (this.config.mdConfig.fallbackToHtml && meta?.alignment && meta.alignment !== 'left') {

package/dist/generators/PdfGenerator.d.ts

@@ -9,7 +9,7 @@ import { BaseGenerator } from './BaseGenerator.js';
  */
 export declare class PdfGenerator extends BaseGenerator<'pdf'> {
     constructor(ast: OfficeParserAST, config?: GeneratorConfig<'pdf'>);
-    generate(): Promise<ConversionResult>;
+    generate(): Promise<ConversionResult<'pdf'>>;
     /**
      * Node.js implementation using Puppeteer.
      * Uses dynamic import to avoid bundling puppeteer into the library core.

package/dist/generators/PdfGenerator.js

@@ -23,12 +23,6 @@ class PdfGenerator extends BaseGenerator_js_1.BaseGenerator {
         const htmlGenerator = new HtmlGenerator_js_1.HtmlGenerator(this.ast, {
             ...this.config,
             htmlConfig: { ...this.config.htmlConfig, standalone: true },
-            mdConfig: undefined,
-            chunksConfig: undefined,
-            csvConfig: undefined,
-            textConfig: undefined,
-            pdfConfig: undefined,
-            rtfConfig: undefined,
         });
         const htmlResult = await htmlGenerator.generate();
         const html = typeof htmlResult.value === 'string' ? htmlResult.value : '';

package/dist/generators/RtfGenerator.d.ts

@@ -7,9 +7,10 @@ export declare class RtfGenerator extends BaseGenerator<'rtf'> {
     private colorTable;
     private inTable;
     constructor(ast: OfficeParserAST, config?: GeneratorConfig<'rtf'>);
-    generate(): Promise<ConversionResult>;
+    generate(): Promise<ConversionResult<'rtf'>>;
     protected processNodeRecursive(node: OfficeContentNode, processor: (node: OfficeContentNode, childrenOutput: string) => Promise<string>): Promise<string>;
     private renderBody;
     private getColorIndex;
+    private isLightColor;
     private escapeRtf;
 }

package/dist/generators/RtfGenerator.js

@@ -15,7 +15,7 @@ class RtfGenerator extends BaseGenerator_js_1.BaseGenerator {
         this.colorTable = [];
         // We first process all nodes to collect colors and analyze structure
         const bodyContent = await this.renderBody(this.ast);
-        let output = '{\\rtf1\\ansi\\deff0\n';
+        let output = '{\\rtf1\\ansi\\uc1\\deff0\n';
         // 1. Info Group (Metadata)
         if (this.config.renderMetadata && this.ast.metadata) {
             output += '{\\info';
@@ -100,16 +100,34 @@ class RtfGenerator extends BaseGenerator_js_1.BaseGenerator {
                             suffix = '\\strike0 ' + suffix;
                         }
                         if (f.color) {
-                            const idx = this.getColorIndex(f.color);
-                            prefix += `\\cf${idx + 1} `;
+                            // RTF default background is white. Ensure light text without a dark background remains readable.
+                            const isTextLight = this.isLightColor(f.color);
+                            const isBgLight = !f.backgroundColor || this.isLightColor(f.backgroundColor);
+                            if (!(isTextLight && isBgLight)) {
+                                const idx = this.getColorIndex(f.color);
+                                prefix += `\\cf${idx + 1} `;
+                            }
                         }
                         if (f.backgroundColor) {
                             const idx = this.getColorIndex(f.backgroundColor);
                             prefix += `\\highlight${idx + 1} `;
                         }
                         if (f.size) {
-                            const pt = parseInt(f.size);
-                            prefix += `\\fs${pt * 2} `;
+                            let pt = 12; // default
+                            const val = parseFloat(f.size);
+                            if (!isNaN(val)) {
+                                if (f.size.includes('in'))
+                                    pt = val * 72;
+                                else if (f.size.includes('cm'))
+                                    pt = val * 28.3465;
+                                else if (f.size.includes('mm'))
+                                    pt = val * 2.83465;
+                                else if (f.size.includes('px'))
+                                    pt = val * 0.75;
+                                else
+                                    pt = val;
+                            }
+                            prefix += `\\fs${Math.round(pt * 2)} `;
                         }
                         text = `{\\f0 ${prefix}${text}${suffix}}`;
                     }
@@ -214,13 +232,32 @@ class RtfGenerator extends BaseGenerator_js_1.BaseGenerator {
         }
         return idx;
     }
+    isLightColor(hex) {
+        if (!hex || hex.length !== 7 || !hex.startsWith('#'))
+            return false;
+        const r = parseInt(hex.substring(1, 3), 16);
+        const g = parseInt(hex.substring(3, 5), 16);
+        const b = parseInt(hex.substring(5, 7), 16);
+        if (isNaN(r) || isNaN(g) || isNaN(b))
+            return false;
+        // Simple luminance calculation
+        const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+        return luminance > 0.8;
+    }
     escapeRtf(text) {
         return text
             .replace(/\\/g, '\\\\')
             .replace(/{/g, '\\{')
             .replace(/}/g, '\\}')
             .replace(/[^\x00-\x7F]/g, (match) => {
-            return `\\u${match.charCodeAt(0)}?`;
+            let code = match.charCodeAt(0);
+            if (code < 256) {
+                return `\\'${code.toString(16).padStart(2, '0')}`;
+            }
+            if (code > 32767) {
+                code -= 65536;
+            }
+            return `{\\uc0\\u${code}}`;
         });
     }
 }

package/dist/generators/TextGenerator.d.ts

@@ -8,6 +8,6 @@ export declare class TextGenerator extends BaseGenerator<'text'> {
     /**
      * Generates plain text by concatenating text content from nodes.
      */
-    generate(): Promise<ConversionResult>;
+    generate(): Promise<ConversionResult<'text'>>;
     private renderTable;
 }

package/dist/officeparser.browser.d.ts

@@ -70,7 +70,9 @@ export declare enum OfficeWarningType {
 	/** No chunks were generated for the document given the current strategy */
 	EMPTY_CHUNK_GENERATED = "EMPTY_CHUNK_GENERATED",
 	/** A node was skipped because it only contained whitespace */
-	WHITESPACE_NODE_SKIPPED = "WHITESPACE_NODE_SKIPPED"
+	WHITESPACE_NODE_SKIPPED = "WHITESPACE_NODE_SKIPPED",
+	/** The HTML generator containerWidth option is invalid */
+	INVALID_CONTAINER_WIDTH = "INVALID_CONTAINER_WIDTH"
 }
 /**
  * Consolidated timeout settings for OCR operations.
@@ -223,10 +225,23 @@ export interface OfficeParserConfig {
 	 */
 	ignoreNotes?: boolean;
 	/**
-	 * Flag, if set to true, will collectively put all the parsed text from notes at last in files like powerpoint.
-	 * Default is false. It puts each notes right after its main slide content.
-	 * If ignoreNotes is set to true, this flag is also ignored.
-	 * @note This flag currently does not affect RTF files; RTF footnotes/endnotes are always collected and appended at the end of the content.
+	 * Flag to ignore comments from parsing.
+	 * Default is false.
+	 */
+	ignoreComments?: boolean;
+	/**
+	 * Flag to ignore headers and footers from parsing.
+	 * Default is false.
+	 */
+	ignoreHeadersAndFooters?: boolean;
+	/**
+	 * Flag to ignore slide masters from parsing in PowerPoint.
+	 * Default is false.
+	 */
+	ignoreSlideMasters?: boolean;
+	/**
+	 * @deprecated Notes are now structurally attached to the specific nodes they belong to via `node.notes`.
+	 * This option is now completely ignored by all parsers.
 	 */
 	putNotesAtLast?: boolean;
 	/**
@@ -351,9 +366,10 @@ export interface OfficeIssue {
 /**
  * The result of a document conversion operation.
  */
-export interface ConversionResult<D extends string = UniversalGeneratorFormat> {
+export type ConversionValue<D extends UniversalGeneratorFormat> = D extends "pdf" ? Uint8Array | string : D extends "chunks" ? OfficeChunk[] : D extends "csv" ? string | Uint8Array : string;
+export interface ConversionResult<D extends UniversalGeneratorFormat> {
 	/** The actual generated content (HTML, Markdown, Text, OfficeChunk[], etc.). */
-	value: D extends "pdf" ? Uint8Array : D extends "chunks" ? OfficeChunk[] : D extends "csv" ? string | Uint8Array : D extends UniversalGeneratorFormat ? string : never;
+	value: ConversionValue<D>;
 	/** A collection of issues (warnings/infos) generated during the process. */
 	messages: OfficeIssue[];
 }
@@ -475,17 +491,31 @@ export interface CommonGeneratorConfig {
  * Restricts format-specific configurations to their respective destinations.
  */
 /**
- * Mapping of destination formats to their specific configuration interfaces.
+ * Maps a destination format string to its corresponding specific configuration object type.
  */
-export interface GeneratorSubConfigMap {
-	html: HtmlGeneratorConfig;
-	md: MdGeneratorConfig;
-	pdf: PdfGeneratorConfig;
-	csv: CsvGeneratorConfig;
-	text: TextGeneratorConfig;
-	rtf: RtfGeneratorConfig;
-	chunks: ChunkingConfig;
-}
+export type GeneratorSpecificConfig<D extends string> = D extends "html" ? {
+	htmlConfig?: HtmlGeneratorConfig;
+} : D extends "md" ? {
+	mdConfig?: MdGeneratorConfig;
+} : D extends "pdf" ? {
+	pdfConfig?: PdfGeneratorConfig;
+} : D extends "csv" ? {
+	csvConfig?: CsvGeneratorConfig;
+} : D extends "text" ? {
+	textConfig?: TextGeneratorConfig;
+} : D extends "rtf" ? {
+	rtfConfig?: RtfGeneratorConfig;
+} : D extends "chunks" ? {
+	chunksConfig?: ChunkingConfig;
+} : Partial<{
+	htmlConfig: HtmlGeneratorConfig;
+	mdConfig: MdGeneratorConfig;
+	pdfConfig: PdfGeneratorConfig;
+	csvConfig: CsvGeneratorConfig;
+	textConfig: TextGeneratorConfig;
+	rtfConfig: RtfGeneratorConfig;
+	chunksConfig: ChunkingConfig;
+}>;
 /**
  * Configuration options for document generators.
  *
@@ -496,9 +526,7 @@ export interface GeneratorSubConfigMap {
  *
  * @template D The destination format string. Defaults to `string` for a general configuration.
  */
-export type GeneratorConfig<D extends string = string> = CommonGeneratorConfig & {
-	[K in keyof GeneratorSubConfigMap as `${K & string}Config`]?: string extends D ? GeneratorSubConfigMap[K] : (D extends K ? GeneratorSubConfigMap[K] : never);
-};
+export type GeneratorConfig<D extends string = string> = CommonGeneratorConfig & GeneratorSpecificConfig<D>;
 /**
  * Configuration options for the OfficeConverter.
  * Combines relevant parser and generator settings for a seamless one-step conversion.
@@ -530,6 +558,19 @@ export type OfficeConverterConfig<D extends string = string, T extends Supported
 	 */
 	onWarning?: (issue: OfficeIssue) => void;
 };
+/**
+ * Configuration options for granular raw HTML injections.
+ */
+export interface HtmlInjectionConfig {
+	/** Raw HTML injected immediately after the opening <head> tag */
+	headStart?: string;
+	/** Raw HTML injected immediately before the closing </head> tag */
+	headEnd?: string;
+	/** Raw HTML injected immediately after the opening <body> tag */
+	bodyStart?: string;
+	/** Raw HTML injected immediately before the closing </body> tag */
+	bodyEnd?: string;
+}
 /**
  * Configuration options for HTML generation.
  */
@@ -544,6 +585,25 @@ export interface HtmlGeneratorConfig {
 	 * Defaults to 'https://cdn.jsdelivr.net/npm/chart.js'.
 	 */
 	chartJsSrc?: string;
+	/**
+	 * Custom container width for the generated HTML.
+	 * Can be a number (pixels) or string (e.g., '900px', '100%').
+	 * If not specified or set to 'auto', it defaults based on the content type:
+	 * - Spreadsheet: '100%'
+	 * - Presentation/Slides: '1100px'
+	 * - Standard Document (PDF/DOCX/RTF/etc.): '900px'
+	 */
+	containerWidth?: string | number;
+	/**
+	 * Custom CSS to append to the generated HTML document.
+	 * This CSS will be included in the `<style>` block and can be used to style
+	 * custom classes added during AST manipulation or override default styles.
+	 */
+	customCss?: string;
+	/**
+	 * Granular injection points for custom HTML, scripts, and styles.
+	 */
+	injections?: HtmlInjectionConfig;
 }
 /**
  * Configuration options for PDF generation.
@@ -619,7 +679,7 @@ export interface StructuredStyleMapping {
 		 * The structural type of the node (e.g., 'paragraph', 'heading', 'text').
 		 * Most style mappings target 'paragraph' nodes to convert them into headers or blocks.
 		 */
-		nodeType?: string;
+		nodeType?: OfficeContentNodeType;
 		/**
 		 * A dictionary of attributes to match on the node.
 		 *
@@ -685,7 +745,7 @@ export interface CsvGeneratorConfig {
 	/**
 	 * Whether to merge all selected sheets into a single CSV.
 	 * If false, returns a ZIP archive containing individual CSV files.
-	 * Defaults to false.
+	 * Defaults to true.
 	 */
 	mergeSheets?: boolean;
 	/**
@@ -944,11 +1004,16 @@ export type SupportedFileType = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods"
 /**
  * Types of content nodes in the AST.
  */
-export type OfficeContentNodeType = "paragraph" | "heading" | "table" | "list" | "text" | "image" | "chart" | "drawing" | "slide" | "note" | "sheet" | "row" | "cell" | "page" | "break" | "code" | "comment";
+export type OfficeContentNodeType = "paragraph" | "heading" | "table" | "list" | "text" | "image" | "chart" | "drawing" | "slide" | "note" | "sheet" | "row" | "cell" | "page" | "break" | "code" | "comment" | "header" | "footer" | "slideMaster";
 /**
  * Supported MIME types for attachments.
  */
 export type OfficeMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/bmp" | "image/tiff" | "image/svg+xml" | "application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.oasis.opendocument.chart" | "application/vnd.oasis.opendocument.spreadsheet" | "application/vnd.oasis.opendocument.text" | "application/vnd.oasis.opendocument.presentation" | "application/rtf" | "text/csv" | "text/markdown" | "text/html";
+/**
+ * Text alignment options.
+ * Common in spreadsheet cells, paragraph styles, and text elements.
+ */
+export type TextAlignment = "left" | "center" | "right" | "justify";
 /**
  * Text formatting options available for text content.
  * Represents common formatting attributes found in office documents (DOCX, RTF, PPTX, etc.).
@@ -1022,7 +1087,7 @@ export interface TextFormatting {
 	 * Common in spreadsheet cells or paragraph styles.
 	 * @example "center", "right"
 	 */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 }
 /**
  * Metadata for a slide in PowerPoint.
@@ -1072,7 +1137,7 @@ export interface HeadingMetadata {
 	/** The heading level (e.g., 1 for H1). */
 	level: number;
 	/** The alignment of the heading. */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 	/** The style of the heading. */
 	style?: string;
 	/** Detailed indentation information. */
@@ -1085,7 +1150,7 @@ export interface HeadingMetadata {
  */
 export interface ParagraphMetadata {
 	/** The alignment of the paragraph. */
-	alignment?: "left" | "center" | "right" | "justify";
+	alignment?: TextAlignment;
 	/** The style of the paragraph. */
 	style?: string;
 	/** Detailed indentation information. */
@@ -1113,7 +1178,7 @@ export interface ListMetadata {
 	 * Text alignment of the list item.
 	 * @example 'left', 'center', 'right', 'justify'
 	 */
-	alignment: "left" | "center" | "right" | "justify";
+	alignment: TextAlignment;
 	/**
 	 * The list ID from the Word document's numbering definition.
 	 * Used to identify which list definition this item belongs to.
@@ -1163,6 +1228,15 @@ export interface CellMetadata {
 	style?: string;
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/** Background color for this cell in hex format (e.g. #FFFFFF). */
+	backgroundColor?: string;
+}
+/**
+ * Metadata for a table.
+ */
+export interface TableMetadata {
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
 }
 /**
  * Metadata for a chart node in the document.
@@ -1250,6 +1324,8 @@ export interface NoteMetadata {
 	noteId?: string;
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/** The slide number this note is associated with (used in PowerPoint). */
+	slideNumber?: number;
 }
 /**
  * Metadata for break nodes.
@@ -1285,10 +1361,25 @@ export interface CodeMetadata {
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
 }
+/**
+ * Metadata for a comment/annotation.
+ */
+export interface CommentMetadata {
+	author?: string;
+	initials?: string;
+	date?: string;
+	commentId?: string;
+}
+/**
+ * Metadata for a header or footer.
+ */
+export interface HeaderFooterMetadata {
+	type: "default" | "first" | "even" | string;
+}
 /**
  * Union type for content metadata.
  */
-export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | undefined;
+export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | CommentMetadata | HeaderFooterMetadata | TableMetadata | undefined;
 /**
  * Represents a node in the document content tree.
  * This is the core building block of the parsed document structure.
@@ -1315,13 +1406,10 @@ export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata |
  *   children: [...]
  * }
  */
-export interface OfficeContentNode {
-	/**
-	 * The type of the node.
-	 * Determines how the node should be interpreted and rendered.
-	 * Common types: 'paragraph', 'heading', 'table', 'list', 'text', 'image', etc.
-	 */
-	type: OfficeContentNodeType;
+/**
+ * Shared properties available on all document content nodes.
+ */
+export interface BaseContentNode {
 	/**
 	 * The complete text content of the node and all its children combined.
 	 * For container nodes (paragraph, heading), this is the concatenation of all child text.
@@ -1339,6 +1427,16 @@ export interface OfficeContentNode {
 	 * @example [{ type: 'text', text: 'Hello', formatting: { bold: true } }]
 	 */
 	children?: OfficeContentNode[];
+	/**
+	 * Comments attached to this specific node.
+	 * Keeps annotations completely separate from the actual content flow.
+	 */
+	comments?: OfficeContentNode[];
+	/**
+	 * Notes (like footnotes or slide notes) attached to this specific node.
+	 * Keeps notes separate from the actual structural children.
+	 */
+	notes?: OfficeContentNode[];
 	/**
 	 * Text formatting applied to this node.
 	 * Only applicable to text-containing nodes.
@@ -1346,16 +1444,6 @@ export interface OfficeContentNode {
 	 * @example { bold: true, size: "12", font: "Arial" }
 	 */
 	formatting?: TextFormatting;
-	/**
-	 * Type-specific metadata providing additional context about the node.
-	 * The metadata structure depends on the node type:
-	 * - Headings: { level: 1 }
-	 * - Lists: { listType: 'ordered', indentation: 0 }
-	 * - Cells: { row: 0, col: 0 }
-	 * - Slides: { slideNumber: 1 }
-	 * @example { level: 1 } for a heading
-	 */
-	metadata?: ContentMetadata;
 	/**
 	 * The raw source content for this node.
 	 * - For XML-based formats (DOCX, XLSX, PPTX): contains the raw XML
@@ -1367,6 +1455,93 @@ export interface OfficeContentNode {
 	 */
 	rawContent?: string;
 }
+/**
+ * Represents a node in the document content tree.
+ * This is the core building block of the parsed document structure.
+ * Content nodes can be nested to represent hierarchical document structures
+ * (e.g., paragraphs containing text runs, tables containing rows, rows containing cells).
+ *
+ * @example
+ * // A simple paragraph with formatted text
+ * {
+ *   type: 'paragraph',
+ *   text: 'Hello world',
+ *   children: [
+ *     { type: 'text', text: 'Hello ', formatting: { bold: true } },
+ *     { type: 'text', text: 'world', formatting: { italic: true } }
+ *   ]
+ * }
+ *
+ * @example
+ * // A heading with metadata
+ * {
+ *   type: 'heading',
+ *   text: 'Chapter 1',
+ *   metadata: { level: 1 },
+ *   children: [...]
+ * }
+ */
+export type OfficeContentNode = BaseContentNode & ({
+	type: "slide";
+	metadata?: SlideMetadata;
+} | {
+	type: "sheet";
+	metadata?: SheetMetadata;
+} | {
+	type: "heading";
+	metadata?: HeadingMetadata;
+} | {
+	type: "list";
+	metadata?: ListMetadata;
+} | {
+	type: "cell";
+	metadata?: CellMetadata;
+} | {
+	type: "image";
+	metadata?: ImageMetadata;
+} | {
+	type: "chart";
+	metadata?: ChartMetadata;
+} | {
+	type: "page";
+	metadata?: PageMetadata;
+} | {
+	type: "paragraph";
+	metadata?: ParagraphMetadata;
+} | {
+	type: "text";
+	metadata?: TextMetadata;
+} | {
+	type: "note";
+	metadata?: NoteMetadata;
+} | {
+	type: "break";
+	metadata?: BreakMetadata;
+} | {
+	type: "code";
+	metadata?: CodeMetadata;
+} | {
+	type: "comment";
+	metadata?: CommentMetadata;
+} | {
+	type: "header";
+	metadata?: HeaderFooterMetadata;
+} | {
+	type: "footer";
+	metadata?: HeaderFooterMetadata;
+} | {
+	type: "table";
+	metadata?: TableMetadata;
+} | {
+	type: "row";
+	metadata?: undefined;
+} | {
+	type: "drawing";
+	metadata?: undefined;
+} | {
+	type: "slideMaster";
+	metadata?: SlideMetadata;
+});
 /**
  * Structured information extracted from a chart.
  */
@@ -1506,14 +1681,40 @@ export interface OfficeMetadata {
 	 * Values are typed as string, number, boolean, or Date where the source format provides type information.
 	 */
 	customProperties?: Record<string, string | number | boolean | Date>;
+	/** Keywords associated with the document. */
+	keywords?: string;
+	/**
+	 * Contains all format-specific metadata fields extracted verbatim.
+	 * Consumers can use this to access properties not mapped to the standard OfficeMetadata fields.
+	 * Examples: all <meta> tags in HTML, app.xml properties in DOCX, XMP dicts in PDF.
+	 */
+	nativeProperties?: Record<string, any>;
+}
+/**
+ * Contains out-of-band layout elements and templates that are not part of the main document flow.
+ */
+export interface OfficeAuxiliaryContent {
+	/** Headers extracted from the document. */
+	headers?: OfficeContentNode[];
+	/** Footers extracted from the document. */
+	footers?: OfficeContentNode[];
+	/** Slide Masters extracted from presentations. */
+	slideMasters?: OfficeContentNode[];
 }
 /**
- * The Abstract Syntax Tree (AST) returned by the parser.
- * This is the root data structure representing the entire parsed document.
+ * The Root Abstract Syntax Tree (AST) representing a parsed Office Document.
+ * This is the ultimate output of `OfficeParser.parseOffice()`.
+ *
+ * DESIGN PHILOSOPHY:
+ * The AST is designed to be a universal, format-agnostic representation of document content.
+ * Whether the input was a PDF, DOCX, XLSX, Markdown, or HTML file, the resulting AST
+ * uses the same consistent structure (`OfficeContentNode` trees).
  *
- * The AST provides a format-agnostic representation of the document that can be easily
- * processed, transformed, or converted to other formats. It preserves the document's
- * structure, content, formatting, and metadata while abstracting away format-specific details.
+ * ### Key Top-Level Properties:
+ * - `metadata`: Document-level properties (author, title, stats).
+ * - `content`: The main sequential flow of the document (paragraphs, tables, slides, sheets).
+ * - `attachments`: Extracted binary assets (images, embedded files).
+ * - `auxiliary`: Out-of-band layout/template elements (headers, footers, slide masters).
  *
  * @example
  * ```typescript
@@ -1563,6 +1764,12 @@ export interface OfficeParserAST {
 	 * @example [{ type: 'paragraph', text: 'Hello' }, { type: 'heading', text: 'Chapter 1' }]
 	 */
 	content: OfficeContentNode[];
+	/**
+	 * Out-of-band layout and template elements that are not part of the main text flow.
+	 * Extracted only if the respective `ignore...` config flags are false.
+	 * Contains elements like `headers`, `footers`, and `slideMasters`.
+	 */
+	auxiliary?: OfficeAuxiliaryContent;
 	/**
 	 * Attachments extracted from the document (images, charts, embedded files).
 	 * Only populated when `config.extractAttachments` is true.
@@ -1606,7 +1813,7 @@ export interface OfficeParserAST {
 	 * const md = await ast.to('md');
 	 * ```
 	 */
-	to<T extends this, D extends SupportedDestination<T["type"]>>(this: T, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult>;
+	to<T extends this, D extends SupportedDestination<T["type"]>>(this: T, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult<D>>;
 }
 /**
  * Main parser class providing office document parsing functionality.
@@ -1690,7 +1897,7 @@ 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>>;
 }
 /**
  * Utility type to infer the file type from a file path string literal.