officeparser 7.0.3 → 7.2.0

package/dist/types.d.ts

@@ -28,7 +28,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.
@@ -66,7 +68,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.
@@ -102,11 +168,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.
@@ -135,10 +223,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;
     /**
@@ -173,6 +274,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.
@@ -254,9 +369,10 @@ export interface OfficeIssue {
 /**
  * The result of a document conversion operation.
  */
-export interface ConversionResult<D extends string = UniversalGeneratorFormat> {
+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[];
 }
@@ -366,23 +482,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;
-}
+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.
  *
@@ -393,9 +529,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.
@@ -440,10 +574,28 @@ export type DeepRequired<T> = T extends Function | Date | Buffer | RegExp ? T :
  * it is a discriminated union whose members cannot be uniformly deep-required.
  */
 export type FullGeneratorConfig = DeepRequired<CommonGeneratorConfig & {
-    [K in keyof Omit<GeneratorSubConfigMap, 'chunks'> as `${K}Config`]: GeneratorSubConfigMap[K];
+    htmlConfig: HtmlGeneratorConfig;
+    mdConfig: MdGeneratorConfig;
+    pdfConfig: PdfGeneratorConfig;
+    csvConfig: CsvGeneratorConfig;
+    textConfig: TextGeneratorConfig;
+    rtfConfig: RtfGeneratorConfig;
 }> & {
     chunksConfig: ChunkingConfig;
 };
+/**
+ * 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.
  */
@@ -458,6 +610,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.
@@ -494,6 +665,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.
@@ -527,7 +704,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.
          *
@@ -593,7 +770,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;
     /**
@@ -799,6 +976,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.
@@ -847,11 +1029,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.).
@@ -925,7 +1112,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.
@@ -975,7 +1162,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. */
@@ -988,7 +1175,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. */
@@ -1016,7 +1203,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.
@@ -1066,6 +1253,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.
@@ -1153,6 +1349,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.
@@ -1188,10 +1386,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.
@@ -1218,13 +1431,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.
@@ -1242,6 +1452,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.
@@ -1249,16 +1469,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
@@ -1270,6 +1480,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.
  */
@@ -1409,14 +1706,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
@@ -1466,6 +1789,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.
@@ -1509,5 +1838,6 @@ 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>>;
 }
+export {};

package/dist/types.js

@@ -33,6 +33,8 @@ var OfficeErrorType;
     OfficeErrorType["INVALID_OUTPUT_MAPPING"] = "INVALID_OUTPUT_MAPPING";
     /** Semantic chunking strategy is selected but no embedding function is provided */
     OfficeErrorType["MISSING_EMBEDDING_FUNCTION"] = "MISSING_EMBEDDING_FUNCTION";
+    /** The operation was aborted */
+    OfficeErrorType["OPERATION_ABORTED"] = "OPERATION_ABORTED";
 })(OfficeErrorType || (exports.OfficeErrorType = OfficeErrorType = {}));
 /**
  * Standard warning types for OfficeParser.
@@ -72,4 +74,6 @@ var OfficeWarningType;
     OfficeWarningType["EMPTY_CHUNK_GENERATED"] = "EMPTY_CHUNK_GENERATED";
     /** A node was skipped because it only contained whitespace */
     OfficeWarningType["WHITESPACE_NODE_SKIPPED"] = "WHITESPACE_NODE_SKIPPED";
+    /** The HTML generator containerWidth option is invalid */
+    OfficeWarningType["INVALID_CONTAINER_WIDTH"] = "INVALID_CONTAINER_WIDTH";
 })(OfficeWarningType || (exports.OfficeWarningType = OfficeWarningType = {}));

package/dist/utils/astUtils.d.ts

@@ -1,4 +1,4 @@
-import { OfficeParserAST, OfficeContentNode, OfficeMetadata, OfficeAttachment, SupportedFileType, OfficeParserConfig } from '../types.js';
+import { OfficeAttachment, OfficeAuxiliaryContent, OfficeContentNode, OfficeMetadata, OfficeParserAST, OfficeParserConfig, SupportedFileType } from '../types.js';
 /**
  * Creates a fully-featured OfficeParserAST object with conversion methods.
  *
@@ -13,4 +13,4 @@ import { OfficeParserAST, OfficeContentNode, OfficeMetadata, OfficeAttachment, S
  * @param toTextSync - Synchronous text extraction logic (for backward compatibility)
  * @returns An object conforming to OfficeParserAST
  */
-export declare function createAST(type: SupportedFileType, metadata: OfficeMetadata, content: OfficeContentNode[], attachments: OfficeAttachment[], config: OfficeParserConfig, toTextSync: () => string): OfficeParserAST;
+export declare function createAST(type: SupportedFileType, metadata: OfficeMetadata, content: OfficeContentNode[], attachments: OfficeAttachment[], config: OfficeParserConfig, auxiliary: OfficeAuxiliaryContent | undefined, toTextSync: () => string): OfficeParserAST;