officeparser 7.0.3 → 7.2.0

package/dist/officeparser.browser.d.ts

@@ -30,7 +30,9 @@ export declare enum OfficeErrorType {
 	/** Output mapping in style mapping is invalid */
 	INVALID_OUTPUT_MAPPING = "INVALID_OUTPUT_MAPPING",
 	/** Semantic chunking strategy is selected but no embedding function is provided */
-	MISSING_EMBEDDING_FUNCTION = "MISSING_EMBEDDING_FUNCTION"
+	MISSING_EMBEDDING_FUNCTION = "MISSING_EMBEDDING_FUNCTION",
+	/** The operation was aborted */
+	OPERATION_ABORTED = "OPERATION_ABORTED"
 }
 /**
  * Standard warning types for OfficeParser.
@@ -68,7 +70,71 @@ 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.
+ * Preferred over the individual flat timeout properties on {@link OcrConfig},
+ * which are now deprecated.
+ *
+ * If a key is present here, it takes priority over the corresponding deprecated
+ * flat property (e.g. `timeout.autoTerminate` wins over `autoTerminateTimeout`).
+ * Set any value to `0` to disable that specific timeout.
+ */
+export interface OcrTimeoutConfig {
+	/**
+	 * Timeout in milliseconds of inactivity before the OCR worker pool is
+	 * automatically terminated and freed.
+	 *
+	 * The timer resets every time a new OCR job is enqueued.  When the last
+	 * job completes and this duration passes without a new one, the entire
+	 * worker pool is torn down so that no background threads keep the Node.js
+	 * process alive unnecessarily.
+	 *
+	 * Set to `0` to keep workers alive indefinitely (useful when you want to
+	 * call {@link terminateOcr} manually at shutdown time).
+	 * Default is 10,000 ms (10 seconds).
+	 */
+	autoTerminate?: number;
+	/**
+	 * Timeout in milliseconds for initializing a Tesseract worker
+	 * (loading the JS runtime, downloading or loading the `.traineddata`
+	 * language file) or for re-initializing an existing worker with a
+	 * different language.
+	 *
+	 * Multi-language combinations (e.g. `'por+eng+spa'`) must download a
+	 * separate `.traineddata` file for each language and are therefore
+	 * particularly susceptible to slow networks.  Tune this value upward if
+	 * your OCR environment has high network latency or if you are loading
+	 * languages from disk in a large container image.
+	 *
+	 * When the timeout fires, the failed job is rejected with a non-fatal
+	 * {@link OfficeWarningType.OCR_FAILED} warning and parsing continues
+	 * without OCR output for that image.  The stalled worker is terminated
+	 * and removed from the pool to prevent thread leaks.
+	 *
+	 * Set to `0` to wait indefinitely (not recommended for production; a hung
+	 * network request will block the entire OCR queue for that language).
+	 * Default is 60,000 ms (60 seconds).
+	 */
+	workerLoad?: number;
+	/**
+	 * Timeout in milliseconds for the actual OCR text-recognition call
+	 * (`worker.recognize(image)`) on an already-initialized Tesseract worker.
+	 *
+	 * Recognition time scales with image resolution and the number of active
+	 * languages.  Very high-resolution scans or unusual character sets can
+	 * exceed the default.  If this timeout fires, the job is rejected with a
+	 * non-fatal {@link OfficeWarningType.OCR_FAILED} warning; the worker is
+	 * terminated and evicted from the pool because its internal state after a
+	 * mid-recognition timeout is undefined.
+	 *
+	 * Set to `0` to wait indefinitely.
+	 * Default is 30,000 ms (30 seconds).
+	 */
+	recognition?: number;
 }
 /**
  * Configuration options for OCR.
@@ -104,11 +170,33 @@ export interface OcrConfig {
 	 */
 	langPath?: string;
 	/**
+	 * Consolidated timeout settings for all OCR operations.
+	 *
+	 * Prefer this over the deprecated flat timeout properties.
+	 * If `timeout.autoTerminate` is set, it takes priority over the deprecated `autoTerminateTimeout`.
+	 */
+	timeout?: OcrTimeoutConfig;
+	/**
+	 * @deprecated Use `timeout.autoTerminate` instead.
+	 *
 	 * Timeout in milliseconds of inactivity before the OCR worker pool is automatically terminated.
 	 * Set to 0 to disable auto-termination.
 	 * Default is 10,000 (10 seconds).
+	 *
+	 * If `timeout.autoTerminate` is also set, that value takes priority over this one.
 	 */
 	autoTerminateTimeout?: number;
+	/**
+	 * An optional AbortSignal propagated from the main parser configuration to abort active OCR jobs.
+	 * If the signal is aborted:
+	 * 1. Any pending OCR jobs in the scheduler queue are rejected immediately.
+	 * 2. Any active OCR job running on a Tesseract worker will reject, the worker will be
+	 *    terminated, and it will be removed from the pool to avoid hanging worker threads.
+	 *
+	 * Developers should prefer passing this at the top level of `parseOffice` (as `config.abortSignal`),
+	 * which automatically propagates here.
+	 */
+	abortSignal?: AbortSignal | null;
 }
 /**
  * Configuration options for the OfficeParser.
@@ -137,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;
 	/**
@@ -175,6 +276,20 @@ export interface OfficeParserConfig {
 	 * If provided, `ocrLanguage` will be ignored in favor of `ocrConfig.language`.
 	 */
 	ocrConfig?: OcrConfig;
+	/**
+	 * An optional AbortSignal to cancel the parsing operation.
+	 * When aborted, the parser immediately rejects with a standard AbortError (DOMException).
+	 *
+	 * ### Format-Specific Abort Behavior:
+	 * - **PDF**: Checked between page loads and before individual image OCR operations.
+	 * - **RTF**: Checked before parsing/traversal and before running OCR on image attachments.
+	 * - **DOCX/XLSX/PPTX/ODF**: Checked during zip decompression before loading and parsing XML files.
+	 * - **CSV/MD/HTML**: Checked at the start of the parsing phase.
+	 *
+	 * Note: If an OCR operation is currently running on a Tesseract worker when aborted,
+	 * the worker will be terminated and removed from the worker pool automatically to prevent leaks.
+	 */
+	abortSignal?: AbortSignal | null;
 	/**
 	 * Flag to serialize raw content (XML) as clean, formatted strings.
 	 * Only relevant when `includeRawContent` is true.
@@ -251,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[];
 }
@@ -363,23 +479,43 @@ export interface CommonGeneratorConfig {
 	 * Defaults to false.
 	 */
 	ignoreInternalLinks?: boolean;
+	/**
+	 * An optional AbortSignal to cancel the generation operation.
+	 * When aborted, the generator immediately rejects with a standard AbortError.
+	 * Currently supported by PdfGenerator and ChunkingGenerator.
+	 */
+	abortSignal?: AbortSignal | null;
 }
 /**
  * Destination-aware generator configuration.
  * 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.
  *
@@ -390,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.
@@ -424,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.
  */
@@ -438,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.
@@ -474,6 +640,12 @@ export interface PdfGeneratorConfig {
 	 * Useful for setting custom executable paths or args in CI/CD.
 	 */
 	launchOptions?: any;
+	/**
+	 * Timeout in milliseconds for PDF generation.
+	 * Limits the time spent waiting for Puppeteer to launch, load content, and render PDF.
+	 * Defaults to 30000 ms (30 seconds). Set to 0 to disable.
+	 */
+	timeout?: number;
 }
 /**
  * Structured style mapping definition for the StyleMapper.
@@ -507,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.
 		 *
@@ -573,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;
 	/**
@@ -779,6 +951,11 @@ export interface SemanticChunkingConfig extends BaseChunkingConfig {
 	 * Default is 50.
 	 */
 	embeddingBatchSize?: number;
+	/**
+	 * Timeout in milliseconds for individual embedding API calls.
+	 * Defaults to 10000 ms (10 seconds). Set to 0 to disable.
+	 */
+	timeout?: number;
 }
 /**
  * Discriminated union of all chunking strategy configurations.
@@ -827,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.).
@@ -905,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.
@@ -955,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. */
@@ -968,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. */
@@ -996,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.
@@ -1046,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.
@@ -1133,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.
@@ -1168,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.
@@ -1198,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.
@@ -1222,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.
@@ -1229,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
@@ -1250,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.
  */
@@ -1389,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()`.
  *
- * 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.
+ * 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).
+ *
+ * ### 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
@@ -1446,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.
@@ -1489,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.
@@ -1573,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.