officeparser 7.1.0 → 7.2.0

package/dist/types.d.ts

@@ -68,7 +68,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.
@@ -221,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;
     /**
@@ -354,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[];
 }
@@ -478,17 +494,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;
-}
+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.
  *
@@ -499,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.
@@ -546,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.
  */
@@ -564,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.
@@ -639,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.
          *
@@ -705,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;
     /**
@@ -964,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.).
@@ -1042,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.
@@ -1092,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. */
@@ -1105,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. */
@@ -1133,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.
@@ -1183,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.
@@ -1270,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.
@@ -1305,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.
@@ -1335,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.
@@ -1359,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.
@@ -1366,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
@@ -1387,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.
  */
@@ -1526,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()`.
+ *
+ * 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
@@ -1583,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.
@@ -1626,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

@@ -74,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;

package/dist/utils/astUtils.js

@@ -16,13 +16,14 @@ const OfficeGenerator_js_1 = require("../OfficeGenerator.js");
  * @param toTextSync - Synchronous text extraction logic (for backward compatibility)
  * @returns An object conforming to OfficeParserAST
  */
-function createAST(type, metadata, content, attachments, config, toTextSync) {
+function createAST(type, metadata, content, attachments, config, auxiliary, toTextSync) {
     return {
         config,
         type,
         metadata,
         content,
         attachments,
+        auxiliary,
         warnings: [],
         toText: toTextSync,
         async to(destination, genConfig) {

package/dist/utils/configUtils.d.ts

@@ -24,3 +24,8 @@ export declare function resolveParserConfig(userConfig?: OfficeParserConfig | Fu
  * @returns A fully populated configuration object
  */
 export declare function resolveGeneratorConfig<D extends string>(destination: D, astConfig?: OfficeParserConfig, userConfig?: GeneratorConfig<D> | FullGeneratorConfig): FullGeneratorConfig;
+/**
+ * Validates the containerWidth option for HTML generation.
+ * Can be 'auto', a positive number, or a positive CSS length/percentage string.
+ */
+export declare function isValidContainerWidth(width: any): boolean;

package/dist/utils/configUtils.js

@@ -4,7 +4,10 @@ exports.isFullGeneratorConfig = isFullGeneratorConfig;
 exports.isFullParserConfig = isFullParserConfig;
 exports.resolveParserConfig = resolveParserConfig;
 exports.resolveGeneratorConfig = resolveGeneratorConfig;
+exports.isValidContainerWidth = isValidContainerWidth;
 const defaults_js_1 = require("../defaults.js");
+const types_js_1 = require("../types.js");
+const errorUtils_js_1 = require("./errorUtils.js");
 /**
  * Deep clones an object, specifically handling arrays and plain objects.
  */
@@ -100,6 +103,7 @@ function resolveGeneratorConfig(destination, astConfig, userConfig) {
     // If it's already a full config and we don't need to merge AST config, return it as is.
     // We assume FullGeneratorConfig is already "safe" (references resolved).
     if (isFullGeneratorConfig(userConfig) && !astConfig) {
+        validateHtmlConfigWidth(userConfig.htmlConfig, userConfig);
         return userConfig;
     }
     // 1. Start with full defaults (deep cloned to avoid reference sharing)
@@ -115,7 +119,22 @@ function resolveGeneratorConfig(destination, astConfig, userConfig) {
                 return;
             for (const key in source) {
                 if (source[key] !== undefined) {
-                    target[key] = source[key];
+                    // Deep merge plain objects (like injections or margin)
+                    if (typeof source[key] === 'object' &&
+                        source[key] !== null &&
+                        !Array.isArray(source[key]) &&
+                        !(source[key] instanceof Function) &&
+                        !(source[key] instanceof Date) &&
+                        !(source[key] instanceof RegExp) &&
+                        !(source[key] instanceof Buffer)) {
+                        if (!target[key] || typeof target[key] !== 'object') {
+                            target[key] = {};
+                        }
+                        mergeSubConfig(target[key], source[key]);
+                    }
+                    else {
+                        target[key] = source[key];
+                    }
                 }
             }
         };
@@ -149,5 +168,40 @@ function resolveGeneratorConfig(destination, astConfig, userConfig) {
             // Since FullGeneratorConfig doesn't have an 'mdConfig', we rely on the generator implementation.
         }
     }
+    validateHtmlConfigWidth(config.htmlConfig, config);
     return config;
 }
+/**
+ * Validates the containerWidth option for HTML generation.
+ * Can be 'auto', a positive number, or a positive CSS length/percentage string.
+ */
+function isValidContainerWidth(width) {
+    if (width === 'auto')
+        return true;
+    if (typeof width === 'number') {
+        return Number.isFinite(width) && width > 0;
+    }
+    if (typeof width === 'string') {
+        const val = width.trim().toLowerCase();
+        if (val === 'auto')
+            return true;
+        const match = val.match(/^((?:\d*\.)?\d+)(px|%|em|rem|vw|vh|vmin|vmax|ch|in|cm|mm|pt|pc)?$/);
+        if (!match)
+            return false;
+        const numericValue = parseFloat(match[1]);
+        return numericValue > 0;
+    }
+    return false;
+}
+/**
+ * Emits a warning and falls back to 'auto' if the HTML containerWidth is invalid.
+ */
+function validateHtmlConfigWidth(htmlConfig, config) {
+    if (htmlConfig?.containerWidth !== undefined) {
+        const width = htmlConfig.containerWidth;
+        if (!isValidContainerWidth(width)) {
+            (0, errorUtils_js_1.logWarning)(types_js_1.OfficeWarningType.INVALID_CONTAINER_WIDTH, config, width);
+            htmlConfig.containerWidth = 'auto';
+        }
+    }
+}

package/dist/utils/errorUtils.js

@@ -50,7 +50,8 @@ const WARNING_MESSAGES = {
     [types_js_1.OfficeWarningType.BUFFER_TYPE_MISMATCH]: (info) => `File content type mismatch: Detected '${info.detected}' but expected/provided '${info.expected}'. Parsing will proceed with '${info.expected}' as requested.`,
     [types_js_1.OfficeWarningType.FILE_TYPE_DETECTION_FAILED]: `Auto-detection of file type failed. This can happen on older Node.js versions with modern file-type versions. Please provide the 'fileType' hint in the configuration if parsing fails.`,
     [types_js_1.OfficeWarningType.EMPTY_CHUNK_GENERATED]: (strategy) => `No chunks generated for document. Check if the document content is compatible with the '${strategy}' strategy.`,
-    [types_js_1.OfficeWarningType.WHITESPACE_NODE_SKIPPED]: (nodeType) => `Skipped whitespace-only node of type: ${nodeType}`
+    [types_js_1.OfficeWarningType.WHITESPACE_NODE_SKIPPED]: (nodeType) => `Skipped whitespace-only node of type: ${nodeType}`,
+    [types_js_1.OfficeWarningType.INVALID_CONTAINER_WIDTH]: (val) => `Invalid HTML containerWidth: ${JSON.stringify(val)}. Falling back to "auto". Width must be a positive number, a valid CSS length string (e.g., "900px", "100%", "50vw"), or "auto".`
 };
 /**
  * Creates a formatted warning message for a specific warning type.

package/dist/utils/xmlUtils.d.ts

@@ -144,6 +144,15 @@ export declare const parseOfficeMetadata: (xmlContent: string) => OfficeMetadata
  * ```
  */
 export declare const parseOOXMLCustomProperties: (xmlContent: string) => Record<string, string | number | boolean | Date>;
+/**
+ * Parses OOXML application properties from `docProps/app.xml`.
+ *
+ * Application properties contain document statistics and application settings.
+ *
+ * @param xmlContent - Raw XML string from `docProps/app.xml`
+ * @returns A record of property name -> typed value
+ */
+export declare const parseOOXMLAppProperties: (xmlContent: string) => Record<string, string | number | boolean>;
 /**
  * Decodes XML entities (standard named entities, decimal, and hexadecimal entities) in a string.
  * Useful when parsing content with regular expressions instead of a full DOM parser.