@gmickel/gno 1.45.1 → 2.0.0

package/vendor/converters/officeparser/dist/officeparser.browser.d.ts

@@ -0,0 +1,2621 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * Standard error types for OfficeParser.
+ * Use these to identify the kind of error being reported.
+ */
+export declare enum OfficeErrorType {
+	/** Unsupported file extension */
+	EXTENSION_UNSUPPORTED = "EXTENSION_UNSUPPORTED",
+	/** Unsupported output generator format */
+	FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED",
+	/** File appears to be corrupted or malformed */
+	FILE_CORRUPTED = "FILE_CORRUPTED",
+	/** File could not be found at the specified path */
+	FILE_DOES_NOT_EXIST = "FILE_DOES_NOT_EXIST",
+	/** Specified location/directory is not reachable or is a directory */
+	LOCATION_NOT_FOUND = "LOCATION_NOT_FOUND",
+	/** Arguments passed to the function are missing or invalid */
+	IMPROPER_ARGUMENTS = "IMPROPER_ARGUMENTS",
+	/** Error occurred while reading or processing file buffers */
+	IMPROPER_BUFFERS = "IMPROPER_BUFFERS",
+	/** Input type is not a supported type (string, Buffer, ArrayBuffer, Uint8Array) */
+	INVALID_INPUT = "INVALID_INPUT",
+	/** PDF worker source is missing (required in browser) */
+	PDF_WORKER_MISSING = "PDF_WORKER_MISSING",
+	/** Attempted to use Node.js-only features in a browser environment */
+	FEATURE_NOT_SUPPORTED_IN_BROWSER = "FEATURE_NOT_SUPPORTED_IN_BROWSER",
+	/** Style mapping string is malformed */
+	INVALID_STYLE_MAPPING = "INVALID_STYLE_MAPPING",
+	/** Selector in style mapping is invalid */
+	INVALID_SELECTOR = "INVALID_SELECTOR",
+	/** 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",
+	/** The operation was aborted */
+	OPERATION_ABORTED = "OPERATION_ABORTED",
+	/** ZIP entry count exceeds limit */
+	ZIP_ENTRY_COUNT_LIMIT_EXCEEDED = "ZIP_ENTRY_COUNT_LIMIT_EXCEEDED",
+	/** ZIP entry missing a valid declared size */
+	ZIP_ENTRY_INVALID_SIZE = "ZIP_ENTRY_INVALID_SIZE",
+	/** ZIP uncompressed size limit exceeded */
+	ZIP_SIZE_LIMIT_EXCEEDED = "ZIP_SIZE_LIMIT_EXCEEDED",
+	/** ZIP data yielded no readable entries (corrupt, truncated, or not a ZIP archive) */
+	ZIP_NO_ENTRIES_FOUND = "ZIP_NO_ENTRIES_FOUND",
+	/** ZIP data is truncated: the End of Central Directory record is absent */
+	ZIP_TRUNCATED = "ZIP_TRUNCATED",
+	/** A readable ZIP archive is missing the part its document format requires */
+	REQUIRED_PART_MISSING = "REQUIRED_PART_MISSING",
+	/** Document element/structure nesting exceeded the safe recursion depth */
+	MAX_NESTING_DEPTH_EXCEEDED = "MAX_NESTING_DEPTH_EXCEEDED",
+	/** Embedding call timed out */
+	EMBEDDING_TIMEOUT = "EMBEDDING_TIMEOUT"
+}
+/**
+ * Standard warning types for OfficeParser.
+ * Use these for reporting non-fatal issues or performance tips.
+ */
+export declare enum OfficeWarningType {
+	/** Performance advice (e.g., Rosetta translation on Mac) */
+	PERFORMANCE_TIP = "PERFORMANCE_TIP",
+	/** OCR processing failed for an attachment */
+	OCR_FAILED = "OCR_FAILED",
+	/** Extraction of structured chart data failed */
+	CHART_DATA_EXTRACTION_FAILED = "CHART_DATA_EXTRACTION_FAILED",
+	/** Automatic worker path failed, falling back to CDN */
+	PDF_WORKER_FALLBACK = "PDF_WORKER_FALLBACK",
+	/** General attachment extraction failure */
+	ATTACHMENT_EXTRACTION_FAILED = "ATTACHMENT_EXTRACTION_FAILED",
+	/** Failed to load a specific page in a multi-page document */
+	PAGE_LOAD_FAILED = "PAGE_LOAD_FAILED",
+	/** Failed to load a required dynamic dependency */
+	DEPENDENCY_LOAD_FAILED = "DEPENDENCY_LOAD_FAILED",
+	/** Failed to extract images from a source */
+	IMAGE_EXTRACTION_FAILED = "IMAGE_EXTRACTION_FAILED",
+	/** Failed to extract annotations from a document */
+	ANNOTATION_EXTRACTION_FAILED = "ANNOTATION_EXTRACTION_FAILED",
+	/** Failed to process an extracted image bitmap */
+	IMAGE_PROCESSING_FAILED = "IMAGE_PROCESSING_FAILED",
+	/** Warning about limitations of browser-based generation */
+	BROWSER_GENERATION_LIMITATION = "BROWSER_GENERATION_LIMITATION",
+	/** Specified sheet range in Excel/ODS export was not found */
+	SHEET_RANGE_NOT_FOUND = "SHEET_RANGE_NOT_FOUND",
+	/** Buffer content type does not match the provided or expected file extension */
+	BUFFER_TYPE_MISMATCH = "BUFFER_TYPE_MISMATCH",
+	/** Failed to detect file type from buffer due to library error or incompatibility */
+	FILE_TYPE_DETECTION_FAILED = "FILE_TYPE_DETECTION_FAILED",
+	/** 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",
+	/** The HTML generator containerWidth option is invalid */
+	INVALID_CONTAINER_WIDTH = "INVALID_CONTAINER_WIDTH",
+	/** A document's repeated-cell expansion hit the configured cell limit and was truncated */
+	TABLE_CELL_LIMIT_EXCEEDED = "TABLE_CELL_LIMIT_EXCEEDED",
+	/** A metadata override could not be represented in the destination format's vocabulary */
+	METADATA_NOT_REPRESENTABLE = "METADATA_NOT_REPRESENTABLE",
+	/** A styleMap output.tag was not an allowed element name and was ignored */
+	INVALID_STYLE_MAP_TAG = "INVALID_STYLE_MAP_TAG",
+	/** A workbook archive contains no worksheet parts (chartsheet-only workbooks are legitimate) */
+	NO_WORKSHEETS_FOUND = "NO_WORKSHEETS_FOUND",
+	/** A presentation archive contains no slides (a zero-slide presentation is legitimate) */
+	NO_SLIDES_FOUND = "NO_SLIDES_FOUND"
+}
+/**
+ * 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.
+ */
+export interface OcrConfig {
+	/**
+	 * Language for OCR.
+	 * Default is 'eng'.
+	 *
+	 * You can provide multiple languages separated by a `+` sign (e.g., 'eng+fra' for English and French).
+	 * The OCR engine will then attempt to recognize text in any of the specified languages.
+	 *
+	 * See the list of supported languages and their codes here:
+	 * https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016
+	 */
+	language?: string;
+	/**
+	 * Path to the Tesseract worker script.
+	 * Primarily used for offline/air-gapped environments.
+	 * Default is ''.
+	 */
+	workerPath?: string;
+	/**
+	 * Path to the Tesseract core script.
+	 * Primarily used for offline/air-gapped environments.
+	 * Default is ''.
+	 */
+	corePath?: string;
+	/**
+	 * Path for Tesseract language files (traineddata).
+	 * Primarily used for offline/air-gapped environments.
+	 * Default is ''.
+	 */
+	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 shared across every input format.
+ */
+export interface CommonOfficeParserConfig {
+	/**
+	 * @deprecated Use `onWarning` instead.
+	 * Flag to show all the logs to console in case of an error irrespective of your own handling.
+	 * Default is false.
+	 */
+	outputErrorToConsole?: boolean;
+	/**
+	 * Callback for warnings or non-fatal errors encountered during parsing.
+	 * Allows you to capture issues like OCR failures or attachment extraction errors
+	 * without stopping the parsing process.
+	 */
+	onWarning?: (issue: OfficeIssue) => void;
+	/**
+	 * The delimiter used for every new line in places that allow multiline text like word.
+	 * Default is \n.
+	 */
+	newlineDelimiter?: string;
+	/**
+	 * Flag to ignore notes from parsing in files like powerpoint.
+	 * Default is false. It includes notes in the parsed text by default.
+	 */
+	ignoreNotes?: boolean;
+	/**
+	 * 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;
+	/**
+	 * Flag to extract attachments like images, charts, etc.
+	 * Default is false.
+	 */
+	extractAttachments?: boolean;
+	/**
+	 * Flag to include raw content (XML for XML-based formats, RTF for RTF) in the AST.
+	 * Default is false.
+	 */
+	includeRawContent?: boolean;
+	/**
+	 * Flag to enable OCR for images.
+	 * Default is false.
+	 */
+	ocr?: boolean;
+	/**
+	 * @deprecated Use `ocrConfig.language` instead.
+	 * Language for OCR.
+	 * Default is 'eng'.
+	 *
+	 * You can provide multiple languages separated by a `+` sign (e.g., 'eng+fra' for English and French).
+	 * The OCR engine will then attempt to recognize text in any of the specified languages.
+	 *
+	 * See the list of supported languages and their codes here:
+	 * https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016
+	 */
+	ocrLanguage?: string;
+	/**
+	 * Shared OCR configuration for worker pooling and offline support.
+	 * 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.
+	 * Default is true.
+	 *
+	 * If false, the parser will attempt to extract the original raw substring from the
+	 * source document instead of re-serializing the DOM node.
+	 */
+	serializeRawContent?: boolean;
+	/**
+	 * Flag to preserve original XML whitespace and line endings when serializing.
+	 * Only relevant when `includeRawContent` is true and `serializeRawContent` is true.
+	 * Default is false.
+	 */
+	preserveXmlWhitespace?: boolean;
+	/**
+	 * The URL/path to the PDF.js worker script.
+	 *
+	 * **Mandatory** when using PDF parsing in browser environments to avoid worker configuration errors.
+	 * If not provided, it defaults to `https://cdn.jsdelivr.net/npm/pdfjs-dist@6.1.200/build/pdf.worker.min.mjs`.
+	 * You can override this with your own local path or a different CDN link.
+	 */
+	pdfWorkerSrc?: string;
+	/**
+	 * Flag to include break nodes in the AST.
+	 * This is currently only supported for Word documents. (w:br nodes)
+	 *
+	 * Default is false
+	 */
+	includeBreakNodes?: boolean;
+	/**
+	 * Flag to ignore all internal (anchor) links during parsing.
+	 * When true, all bookmarks, cross-references, and internal document jumps are stripped
+	 * from the AST. Only external URLs will be preserved.
+	 *
+	 * Use this if you want a "flat" document without any internal interactivity.
+	 *
+	 * Default is false.
+	 */
+	ignoreInternalLinks?: boolean;
+	/**
+	 * Optional hint for the file format.
+	 * When a Buffer or ArrayBuffer is passed, the parser relies on magic bytes to detect the file type.
+	 * Text-based formats like 'md', 'html', and 'csv' lack reliable magic bytes.
+	 * If you are parsing these formats from a Buffer, you must provide this fileType hint.
+	 *
+	 * This is authoritative and is used to determine the file type, so it should be accurate.
+	 * If provided, this bypasses the magic bytes detection and the file extension-based detection either way.
+	 *
+	 * Default is null.
+	 */
+	fileType?: SupportedFileType | null;
+	/**
+	 * Custom delimiter for CSV files.
+	 * Defaults to ',' but can be overridden (e.g., ';', '\t').
+	 */
+	csvDelimiter?: string;
+	/**
+	 * Limits and checks applied during ZIP extraction to protect against excessive
+	 * memory and resource usage.
+	 */
+	decompressionLimits?: DecompressionLimits;
+}
+/**
+ * Format-specific options for HTML (and XHTML/EPUB, which parse through the same code path).
+ *
+ * Note there is deliberately no `MdParserConfig`: the Markdown parser populates its
+ * dialect-provenance metadata (e.g. `AdmonitionMetadata.sourceSyntax`) unconditionally because
+ * doing so costs nothing and changes no existing field's value, so it has nothing to configure.
+ * An empty placeholder interface would be worse than useless here - `interface X {}` accepts any
+ * non-nullish value in TypeScript, so `mdParserConfig: 5` would type-check.
+ */
+export interface HtmlParserConfig {
+	/**
+	 * Preserve source HTML attributes that no typed metadata field consumed, on
+	 * `OfficeContentNode.htmlAttributes`, so they can be replayed on generation.
+	 *
+	 * Off by default: with it off nothing is populated, so the AST is byte-identical to previous
+	 * releases, and the attribute-replay surface stays something a consumer opts into rather than
+	 * something switched on for every existing caller. Captured values are sanitized on the way in
+	 * *and* on the way out - see `BaseContentNode.htmlAttributes`.
+	 *
+	 * Defaults to false.
+	 */
+	preserveAttributes?: boolean;
+	/**
+	 * Preserve `<iframe>` embeds that aren't recognized as a known provider (YouTube is always
+	 * recognized). By default every non-YouTube iframe is dropped, which is a deliberate security
+	 * posture other consumers rely on; set this to opt back in. `true` preserves any iframe; an
+	 * array is a hostname allowlist (an entry matches the src's host exactly or as a `.`-suffix,
+	 * so `"vimeo.com"` also matches `player.vimeo.com`). Preserved iframes become `embed` nodes
+	 * with `embedType: 'iframe'`; on generation the `src` is still scheme-checked (only http/https
+	 * survive). This also governs a raw `<iframe>` block encountered in Markdown input.
+	 *
+	 * Defaults to false.
+	 */
+	preserveIframes?: boolean | string[];
+	/**
+	 * Import ambiguous "folk" embed forms in Markdown as embeds: a standalone Obsidian-style image
+	 * whose URL is a YouTube link (`![](https://youtube.com/watch?v=ID)`), and the clickable
+	 * thumbnail-link (`[![alt](https://img.youtube.com/vi/ID/…)](watch-url)`). Both become a
+	 * `embedType: 'youtube'` embed (rendered from the validated id, so it is safe). Off by default:
+	 * auto-upgrading an image/link to an embed is a heuristic that could mangle a genuinely-intended
+	 * image link, so a consumer opts in. The unambiguous forms (`<div data-youtube-video>`, a bare
+	 * YouTube `<iframe>`, the `::youtube` directive) are always recognized, independent of this flag.
+	 *
+	 * Defaults to false.
+	 */
+	embedFolkForms?: boolean;
+}
+/**
+ * Maps an input format string to its corresponding format-specific parser configuration, mirroring
+ * `GeneratorSpecificConfig<D>` on the generator side. Unlike the generator side, the input format is
+ * usually runtime-detected rather than known statically at the `parseOffice()` call site, so this
+ * mainly exists for internal typing/extensibility rather than compile-time narrowing per call.
+ */
+export type ParserSpecificConfig<F extends string> = F extends "html" | "epub" ? {
+	htmlParserConfig?: HtmlParserConfig;
+} : Partial<{
+	htmlParserConfig: HtmlParserConfig;
+}>;
+/**
+ * Configuration options for the OfficeParser.
+ */
+export type OfficeParserConfig<F extends string = string> = CommonOfficeParserConfig & ParserSpecificConfig<F>;
+/**
+ * Limits applied to ZIP archive decompression.
+ */
+export interface DecompressionLimits {
+	/**
+	 * Maximum allowed total uncompressed size (in bytes) of files extracted from a ZIP archive.
+	 * Applies to OOXML (DOCX, XLSX, PPTX) and ODF (ODT, ODP, ODS) formats.
+	 * Default is 536870912 (512 MB).
+	 */
+	maxUncompressedBytes?: number;
+	/**
+	 * Maximum allowed number of entries (files and directories) in a ZIP archive.
+	 * Applies to OOXML (DOCX, XLSX, PPTX) and ODF (ODT, ODP, ODS) formats.
+	 * Default is 10000.
+	 */
+	maxZipEntries?: number;
+	/**
+	 * Maximum number of table cells materialized from a single document.
+	 *
+	 * ODF encodes runs of identical cells and rows with `table:number-columns-repeated` and
+	 * `table:number-rows-repeated` rather than repeating the markup, so a few hundred bytes of XML
+	 * can ask the parser to build an arbitrary number of nodes - and because the two multiply, a
+	 * row repeat times a column repeat compounds it. The ZIP limits above cannot catch this: the
+	 * XML is tiny before decompression and the expansion happens afterwards, while building the
+	 * AST.
+	 *
+	 * Real documents are nowhere near this. The repeat counts LibreOffice writes are large
+	 * (`number-rows-repeated="1048566"` is routine) but they sit on *empty* trailing runs, which
+	 * are skipped for spreadsheets; the bundled fixtures top out around 350 cells.
+	 *
+	 * On reaching the limit the parser stops materializing further cells, emits a
+	 * `TABLE_CELL_LIMIT_EXCEEDED` warning, and returns what it has rather than throwing, so a
+	 * genuinely enormous sheet still yields usable output. Raise it if you routinely process
+	 * spreadsheets larger than this; note the memory cost scales with it.
+	 *
+	 * Default is 1000000.
+	 */
+	maxTableCells?: number;
+}
+/**
+ * Represents a single issue (warning, error, or info) generated during document processing.
+ */
+export interface OfficeIssue {
+	/** The severity of the issue. */
+	type: "warning" | "info" | "error";
+	/** Human-readable message text. */
+	message: string;
+	/** The specific AST node that triggered this issue, if applicable. */
+	node?: OfficeContentNode;
+	/** A unique error code for programmatic handling. */
+	code: OfficeWarningType | OfficeErrorType;
+	/** Optional additional context or original error object. */
+	details?: any;
+}
+/**
+ * An Error thrown by OfficeParser, carrying the structured issue that produced it.
+ *
+ * Catching code can branch on `error.officeIssue.code`, the same stable enum used for warnings,
+ * instead of matching against message text. Errors that originate outside the library (and
+ * `AbortError`, which is deliberately re-thrown untouched so cancellation stays detectable via
+ * `error.name`) do not carry this property, hence the optional marker.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     await parseOffice(buffer, { fileType: 'docx' });
+ * } catch (err) {
+ *     if ((err as OfficeError).officeIssue?.code === OfficeErrorType.REQUIRED_PART_MISSING) {
+ *         // the archive is readable, but it is not a docx
+ *     }
+ * }
+ * ```
+ */
+export interface OfficeError extends Error {
+	/** The structured issue this error was created from. */
+	officeIssue?: OfficeIssue;
+}
+/**
+ * The result of a document conversion operation.
+ */
+export type ConversionValue<D extends UniversalGeneratorFormat> = D extends "pdf" ? Uint8Array | string : D extends "chunks" ? OfficeChunk[] : D extends "csv" ? string | Uint8Array : D extends "epub" ? Uint8Array : string;
+export interface ConversionResult<D extends UniversalGeneratorFormat> {
+	/** The actual generated content (HTML, Markdown, Text, OfficeChunk[], etc.). */
+	value: ConversionValue<D>;
+	/** A collection of issues (warnings/infos) generated during the process. */
+	messages: OfficeIssue[];
+}
+/**
+ * Universal formats supported by all source types for generation.
+ */
+export type UniversalGeneratorFormat = "text" | "md" | "html" | "pdf" | "csv" | "rtf" | "chunks" | "epub";
+/**
+ * Allowed destination formats for a given source type.
+ * Currently, all generators are universal across all source formats.
+ */
+export type SupportedDestination<_T extends SupportedFileType = SupportedFileType> = UniversalGeneratorFormat;
+/**
+ * Configuration options for the OfficeGenerator.
+ */
+/**
+ * Common configuration options for all generators.
+ */
+/**
+ * Per-field overrides for the metadata written into generated output.
+ *
+ * Field names mirror `OfficeMetadata` so the same vocabulary describes what was parsed and what
+ * gets written. Only the fields generators can actually represent are listed; arbitrary
+ * caller-defined entries go in `custom`.
+ *
+ * **Not every format can represent every field.** HTML (`<meta>`) and Markdown (YAML frontmatter)
+ * accept anything; EPUB's OPF is a closed Dublin Core vocabulary and RTF's `\info` group has a
+ * fixed set of control words, so a `custom` entry has nowhere to go in those. Rather than
+ * silently dropping it, generators report the loss through `onWarning`
+ * (`OfficeWarningType.MetadataNotRepresentable`) and continue.
+ */
+export interface MetadataOverrides {
+	/** Document title. */
+	title?: string;
+	/** Document author. */
+	author?: string;
+	/** Description/comments. */
+	description?: string;
+	/** Subject/topic. */
+	subject?: string;
+	/** Keywords. */
+	keywords?: string;
+	/** User who last modified the document. */
+	lastModifiedBy?: string;
+	/** Creation date. */
+	created?: Date;
+	/**
+	 * Last modification date.
+	 *
+	 * EPUB writes it as the required `dcterms:modified` property and as the mtime on every zip
+	 * entry. When unset, the source document's own `metadata.modified` is used, falling back to
+	 * the current time only if the document has none.
+	 */
+	modified?: Date;
+	/**
+	 * Language tag (e.g. `'en'`, `'de-DE'`). Written as EPUB `dc:language` and HTML `lang`.
+	 */
+	language?: string;
+	/**
+	 * Arbitrary caller-defined key/value pairs, kept in their own bucket rather than mixed in
+	 * beside the named fields above: with a bare index signature a typo like `titel` would
+	 * silently become a custom entry instead of a compile error.
+	 *
+	 * Written where the format allows it (HTML `<meta name="custom:KEY">`, Markdown frontmatter);
+	 * reported via `onWarning` where it does not (EPUB, RTF).
+	 */
+	custom?: Record<string, string | number | boolean | Date>;
+}
+export interface CommonGeneratorConfig {
+	/**
+	 * Callback called for every node during generation.
+	 * Allows users to modify nodes before processing, completely override rendering, or filter them out.
+	 *
+	 * #### Callback Capabilities:
+	 * 1. **Filter/Remove Nodes**: Return `false` to skip a node and all its children.
+	 * 2. **Override Rendering**: Return a `string` to use that exact text as the output, bypassing default logic and recursion.
+	 * 3. **Mutate Nodes**: Modify the `node` object directly (e.g., changing `node.text`) and return `void` to let the generator proceed with your changes.
+	 * 4. **Async Support**: The callback can be `async`, allowing you to load external data or perform complex logic during generation.
+	 */
+	onNode?: (node: OfficeContentNode) => string | false | Promise<string | false | void> | void;
+	/**
+	 * Callback for warnings, non-fatal errors, or issues encountered during generation.
+	 * Allows the process to continue while reporting skipping or approximation of content.
+	 */
+	onWarning?: (issue: OfficeIssue) => void;
+	/**
+	 * Map document styles (e.g., 'Heading 1', 'Intense Quote') to specific semantic elements.
+	 *
+	 * DESIGN PHILOSOPHY:
+	 * This is the primary way to customize how the library interprets the visual
+	 * structure of your source documents.
+	 *
+	 * To disable all semantic translation and use raw AST types only,
+	 * set `ignoreDefaultStyleMap: true` and leave `styleMap` empty.
+	 *
+	 * It supports two formats:
+	 *
+	 * 1. LEGACY STRING DSL:
+	 * Simple "selector => output" syntax. Highly compatible with mammoth.js style maps.
+	 * @example ["p[style-name='Heading 1'] => h1"]
+	 * @example ["p[style='Quote'] => blockquote"]
+	 *
+	 * 2. STRUCTURED OBJECTS (Recommended):
+	 * More powerful and strictly typed. Ideal for complex logic or when you
+	 * need to apply specific classes/attributes for the HTML generator.
+	 * @example
+	 * [
+	 *   {
+	 *     selector: { nodeType: 'paragraph', attributes: { style: 'Heading 1' } },
+	 *     output: { tag: 'h1', classes: ['main-title'], attributes: { id: 'top' } }
+	 *   }
+	 * ]
+	 *
+	 * Note: This property works in conjunction with `ignoreDefaultStyleMap`.
+	 * Defaults to a robust built-in map that covers common standard Office styles.
+	 */
+	styleMap?: string[] | StructuredStyleMapping[];
+	/**
+	 * Whether to include visual formatting like font size, font family, and colors in the output.
+	 * Set to false for clean, semantic output.
+	 * Defaults to true.
+	 */
+	includeFormatting?: boolean;
+	/**
+	 * Whether to automatically generate unique slug-based IDs for headings.
+	 * Useful for table-of-contents and anchor links.
+	 * Defaults to true.
+	 */
+	generateIds?: boolean;
+	/**
+	 * Whether to render document metadata (title, author, etc.) as visible content
+	 * in the generated output (e.g., a header block in HTML or plain text).
+	 * Structural metadata (HTML <meta> tags, Markdown YAML frontmatter) is always included.
+	 * Defaults to false.
+	 */
+	renderMetadata?: boolean;
+	/**
+	 * Overrides for the document metadata written into the generated output, applied on top of
+	 * `ast.metadata`.
+	 *
+	 * Merged **per field**, so setting only `modified` leaves the parsed title, author, and
+	 * everything else intact. Every field is optional; an omitted field keeps the source
+	 * document's value.
+	 *
+	 * These are output overrides only - `ast.metadata` itself is never mutated, so the same AST
+	 * can be generated repeatedly with different metadata.
+	 *
+	 * @example Set the modification date written into the output
+	 * ```typescript
+	 * await ast.to('epub', { metadataOverrides: { modified: new Date('2024-01-01T00:00:00Z') } });
+	 * ```
+	 * @example Rebrand the output without touching the parsed document
+	 * ```typescript
+	 * await ast.to('html', {
+	 *     metadataOverrides: { title: 'Q4 Report', author: 'Acme Inc', custom: { department: 'Finance' } },
+	 * });
+	 * ```
+	 */
+	metadataOverrides?: MetadataOverrides;
+	/**
+	 * Whether to ignore the built-in default style mappings (e.g. "Heading 1" -> h1).
+	 * Set to true if you want full control over style mapping.
+	 * Defaults to false.
+	 */
+	ignoreDefaultStyleMap?: boolean;
+	/**
+	 * Whether to include images in the generated output.
+	 * Defaults to true.
+	 */
+	includeImages?: boolean;
+	/**
+	 * Whether to include interactive charts in the generated output (HTML only).
+	 * Defaults to true.
+	 */
+	includeCharts?: boolean;
+	/**
+	 * Whether to ignore all internal (anchor) links and anchor IDs during generation.
+	 * When true, all bookmarks, cross-references, and internal document jumps are stripped.
+	 * Specifically for Markdown, this removes the {#id} block from headings.
+	 * 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.
+ */
+/**
+ * Maps a destination format string to its corresponding specific configuration object type.
+ */
+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.
+ *
+ * This interface is designed to be format-aware. When you specify a destination format
+ * (e.g., `OfficeGenerator.generate(ast, 'html', config)`), the generic parameter `D`
+ * ensures that only the relevant sub-configuration (e.g., `htmlConfig`) is available
+ * for type checking.
+ *
+ * @template D The destination format string. Defaults to `string` for a general configuration.
+ */
+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.
+ *
+ * @template D The destination format string.
+ */
+/**
+ * Configuration options for the OfficeConverter.
+ * Combines general generator settings with a specific subset of parser settings.
+ *
+ * @template D The destination format string.
+ * @template T The source file type.
+ */
+export type OfficeConverterConfig<D extends string = string, T extends SupportedFileType = SupportedFileType> = {
+	/**
+	 * Specific configuration for the source parsing phase.
+	 */
+	parseConfig?: OfficeParserConfig & {
+		fileType?: T;
+	};
+	/**
+	 * Specific configuration for the destination generation phase.
+	 */
+	generatorConfig?: GeneratorConfig<D>;
+	/**
+	 * Callback for warnings or non-fatal errors encountered during the entire conversion process.
+	 * This is passed to both the parser and the generator.
+	 * If provided, this takes precedence over callbacks inside parseConfig or generatorConfig.
+	 */
+	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;
+}
+/**
+ * Granular control over which parts of the full HTML "document envelope" are emitted.
+ * Shorthand: `standalone: true` == every part on (a complete document); `standalone: false` ==
+ * every part off (a bare content fragment). When an object is passed, any field you omit
+ * defaults to its "on" (standalone) value.
+ */
+export interface StandaloneConfig {
+	/**
+	 * Wrap the output in `<!DOCTYPE html><html><head>…</head><body>…</body></html>`.
+	 * When false, only the inner content fragment is emitted. Defaults to true.
+	 */
+	document?: boolean;
+	/**
+	 * Emit `<title>` and `<meta>` tags (author, description, dates, custom properties) in the head.
+	 * Only meaningful when `document` is true. Defaults to true.
+	 */
+	metaTags?: boolean;
+	/**
+	 * How the library's built-in CSS is delivered:
+	 * - `'full'` — the complete premium stylesheet using global selectors (`body`, `h1`, `table`, …).
+	 *   This is what `standalone: true` has always emitted.
+	 * - `'scoped'` — the same styling, scoped under the fragment's container via CSS `@scope` so it
+	 *   cannot leak into a host page's own styles. Requires a modern browser engine (Chrome 118+,
+	 *   Safari 17.4+, Firefox 128+).
+	 * - `'none'` — no stylesheet is emitted; the host page (or EPUB reader, or rich-text editor)
+	 *   supplies its own styling.
+	 * The boolean shorthand for `standalone` maps `true` → `'full'`, `false` → `'none'`.
+	 * Defaults to `'full'`.
+	 */
+	styles?: "full" | "scoped" | "none";
+	/**
+	 * Emit injected `<script>` tags: the Chart.js loader (when `includeCharts` is true and charts
+	 * are present) and the spreadsheet interactivity script. Defaults to true.
+	 */
+	scripts?: boolean;
+	/**
+	 * Apply `injections.headStart` / `injections.headEnd`. Only meaningful when `document` is true
+	 * (there is no `<head>` to inject into otherwise). Defaults to true.
+	 */
+	headInjections?: boolean;
+	/**
+	 * Apply `injections.bodyStart` / `injections.bodyEnd`. Applies even when generating a bare
+	 * fragment (`document: false`), since these wrap body *content*, not the document shell.
+	 * Defaults to true.
+	 */
+	bodyInjections?: boolean;
+}
+/**
+ * Configuration options for HTML generation.
+ */
+export interface HtmlGeneratorConfig {
+	/**
+	 * Whether to wrap the output in a full HTML document structure (e.g., <html>, <head>, etc.).
+	 * Pass an object instead of a boolean for granular control over individual parts of the
+	 * envelope (document shell, meta tags, styles, scripts, injections) - see `StandaloneConfig`.
+	 * Defaults to true.
+	 */
+	standalone?: boolean | StandaloneConfig;
+	/**
+	 * URL for the Chart.js library to use when 'includeCharts' is true.
+	 * 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;
+	/**
+	 * Carry each rich node's raw source in a `data-*` attribute, with undelimited text content,
+	 * so attribute-driven structured consumers (rich-text editors, custom viewers) can rehydrate
+	 * the node from the markup rather than re-parsing the display text. Affects wikilinks
+	 * (adds `data-wikilink`/`data-target`/`data-alias`), citations (a `<span class="citation">`
+	 * carrying `data-key` instead of `<cite>`), math (the LaTeX in `data-math`, undelimited) and
+	 * mermaid (a `<div class="mermaid" data-mermaid>` instead of `<pre><code>`).
+	 *
+	 * Off by default; the default output is byte-identical to previous releases. The widened
+	 * `HtmlParser` reads every shape this emits, so output stays self-round-trippable.
+	 */
+	sourceAttributes?: boolean;
+	/**
+	 * Emit a generic (non-YouTube) iframe embed as a gated placeholder,
+	 * `<div data-embed-gated data-embed-src="…" …>`, instead of a live `<iframe>`. The gated shape
+	 * never auto-loads its src: an editor renders a click-to-load placeholder from it, and
+	 * `HtmlParser` reads it back to the same `embed` node. The src is scheme-checked (`sanitizeUrl`)
+	 * on emit. Off by default; the default output (a live `<iframe>`) is unchanged. YouTube embeds
+	 * are unaffected (they already render from a validated id).
+	 */
+	gatedEmbeds?: boolean;
+}
+/**
+ * Configuration options for PDF generation.
+ * Maps closely to Puppeteer's PDF options.
+ */
+export interface PdfGeneratorConfig {
+	/** Paper format. Defaults to 'A4'. */
+	format?: "letter" | "legal" | "tabloid" | "ledger" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "a6" | "Letter" | "Legal" | "Tabloid" | "Ledger" | "A0" | "A1" | "A2" | "A3" | "A4" | "A5" | "A6";
+	/** Paper width, accepts values labeled with units (e.g., '5in', '3cm') or numbers (in pixels). */
+	width?: string | number;
+	/** Paper height, accepts values labeled with units (e.g., '5in', '3cm') or numbers (in pixels). */
+	height?: string | number;
+	/** Whether to print in landscape orientation. Defaults to false. */
+	landscape?: boolean;
+	/** Whether to print background graphics. Defaults to true. */
+	printBackground?: boolean;
+	/** Scale of the webpage rendering. Defaults to 1. */
+	scale?: number;
+	/** Paper margins. */
+	margin?: {
+		top?: string | number;
+		right?: string | number;
+		bottom?: string | number;
+		left?: string | number;
+	};
+	/** Whether to display header and footer. Defaults to false. */
+	displayHeaderFooter?: boolean;
+	/** HTML template for the print header. */
+	headerTemplate?: string;
+	/** HTML template for the print footer. */
+	footerTemplate?: string;
+	/**
+	 * Optional Puppeteer launch options for Node.js environment.
+	 * 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.
+ *
+ * DESIGN PHILOSOPHY: "Semantic Translation"
+ * -----------------------------------------
+ * Office documents (Word, RTF, PPTX) often use custom or localized style names
+ * (e.g., "Heading 1" in English vs "Titre 1" in French, or "MyCompany-Quote").
+ *
+ * This interface allows you to create a "semantic bridge" between these arbitrary
+ * source styles and a universal vocabulary of document elements.
+ *
+ * WHY USE HTML TAGS FOR NON-HTML OUTPUT?
+ * --------------------------------------
+ * We use HTML tags (`h1`, `blockquote`, `code`, `pre`) as a "Universal Intermediate
+ * Language". By mapping a custom Word style to `blockquote`, you are defining its
+ * SEMANTIC MEANING rather than its physical appearance.
+ *
+ * Each generator then interprets this meaning natively:
+ * - HTML Generator: Directly renders the `<blockquote>` tag with your classes.
+ * - Markdown Generator: Sees 'blockquote' and renders the standard `> ` prefix.
+ * - Text Generator: Sees 'blockquote' and applies appropriate structural indentation.
+ */
+export interface StructuredStyleMapping {
+	/**
+	 * The criteria used to identify which AST nodes should be transformed.
+	 * Think of this as the "Source Filter".
+	 */
+	selector: {
+		/**
+		 * 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?: OfficeContentNodeType;
+		/**
+		 * A dictionary of attributes to match on the node.
+		 *
+		 * The most common use case is matching the 'style' attribute from
+		 * Word documents (e.g., { style: 'Intense Quote' }).
+		 *
+		 * Matchers:
+		 * - Literal: `style: 'Heading 1'` matches exactly.
+		 * - Operator: `{ value: 'Title', operator: '~=' }` matches if the word 'Title'
+		 *   is found within the style name.
+		 */
+		attributes?: Record<string, string | number | boolean | {
+			value: string | number | boolean;
+			operator: "=" | "~=";
+		}>;
+	};
+	/**
+	 * The target representation for the matched node.
+	 * Think of this as the "Semantic Meaning" you want to assign to the match.
+	 */
+	output: {
+		/**
+		 * The universal semantic tag (e.g., 'h1', 'h2', 'blockquote', 'code', 'pre', 'u').
+		 * All generators use this tag to decide their native output syntax.
+		 */
+		tag: string;
+		/**
+		 * CSS classes to apply to the output.
+		 * This is utilized by the HTML generator to allow for downstream CSS styling.
+		 */
+		classes?: string[];
+		/**
+		 * Key-value pair of HTML attributes (like 'id', 'data-*', or 'style') to apply.
+		 * Primarily used by the HTML generator for high-fidelity conversion.
+		 */
+		attributes?: Record<string, string>;
+		/**
+		 * If true, prevents the generator from collapsing this element into
+		 * adjacent elements of the same type.
+		 *
+		 * For example, multiple paragraphs mapped to 'blockquote' normally merge into
+		 * one big blockquote. Setting `fresh: true` forces them to be separate blocks.
+		 */
+		fresh?: boolean;
+	};
+}
+/**
+ * Configuration options for RTF generation.
+ */
+export interface RtfGeneratorConfig {
+}
+/**
+ * Configuration options for CSV generation.
+ */
+export interface CsvGeneratorConfig {
+	/**
+	 * Range of sheets to export.
+	 * Supports formats like "1", "1-3", "1,2", "1,3-5,7".
+	 * 1-based indexing.
+	 * Default is '' (all sheets).
+	 */
+	sheets?: string;
+	/**
+	 * Whether to merge all selected sheets into a single CSV.
+	 * If false, returns a ZIP archive containing individual CSV files.
+	 * Defaults to true.
+	 */
+	mergeSheets?: boolean;
+	/**
+	 * Custom delimiter for CSV files.
+	 * Defaults to ','.
+	 */
+	columnDelimiter?: string;
+}
+/**
+ * Named Markdown dialect presets for `MarkdownDialectConfig`/`MdGeneratorConfig.dialect`.
+ * `'extended'` is officeParser's own kitchen-sink default and reproduces this library's
+ * historical output exactly (every feature on, GitHub-style admonitions).
+ */
+export type MarkdownDialectPreset = "extended" | "github" | "gitlab" | "obsidian" | "pandoc" | "commonmark";
+/** Admonition syntax: `'blockquote'` = GitHub `> [!NOTE]`, `'fence'` = GitLab `:::note`,
+ *  `'fence-attribute'` = Pandoc `::: {.note}`, `'none'` = plain bold-labeled blockquote. */
+export type AdmonitionSyntax = "blockquote" | "fence" | "fence-attribute" | "none";
+/** `==text==` highlight (`'equals'`), or `'none'` to disable. */
+export type HighlightSyntax = "equals" | "none";
+/** GFM `~~text~~` strikethrough (`'tilde'`), or `'none'`. */
+export type StrikethroughSyntax = "tilde" | "none";
+/** `Term`/`: Description` definition lists (`'colon'`), or `'none'`. */
+export type DefinitionListSyntax = "colon" | "none";
+/** `[^id]` footnotes (`'caret'`), or `'none'`. */
+export type FootnoteSyntax = "caret" | "none";
+/** `[@citekey]` citations (`'at'`), or `'none'`. */
+export type CitationSyntax = "at" | "none";
+/** `[[Page]]` wikilinks (`'double-bracket'`), or `'none'`. */
+export type WikilinkSyntax = "double-bracket" | "none";
+/** `{width=50%}` attribute lists (`'brace'`), or `'none'`. */
+export type AttributeListSyntax = "brace" | "none";
+/**
+ * How an `embed` node is written to Markdown:
+ * - `'html'` (default): the single-line `<div data-youtube-video="ID">` / `<iframe src=...>` block
+ *   this library has always emitted. Round-trips through officeParser, but renders as an invisible
+ *   empty box on GitHub.
+ * - `'directive'`: a remark-directive leaf, `::youtube[Label]{id=... width=... align=...}` /
+ *   `::embed[Label]{src=... width=... height=... align=...}`. Round-trips within an editor that
+ *   understands it; renders verbatim (not just the label) on GitHub, so it is an editor format, not
+ *   a GitHub-interop one.
+ * - `'link'`: a plain `[YouTube](url)` / `[Embed](url)`.
+ * - `'thumbnail'`: a YouTube-only clickable thumbnail `[![Label](.../vi/ID/hqdefault.jpg)](watch)`,
+ *   the best GitHub degrade; a non-YouTube embed falls back to `'link'`.
+ */
+export type EmbedSyntax = "html" | "directive" | "link" | "thumbnail";
+/**
+ * @deprecated Legacy flavor names for `MarkdownDialectConfig.admonitions`. Use the syntax names
+ * instead: `'github'` -> `'blockquote'`, `'gitlab'` -> `'fence'`, `'pandoc'` -> `'fence-attribute'`.
+ * These aliases still resolve to the same output and will be removed in the next major version.
+ */
+export type DeprecatedAdmonitionFlavor = "github" | "gitlab" | "pandoc";
+/**
+ * @deprecated Boolean toggles for dialect capability fields are deprecated in favor of the
+ * syntax-name unions: `true` maps to that field's on-value (e.g. `'tilde'`), `false` maps to
+ * `'none'`. Booleans keep working via coercion and will be removed in the next major version.
+ */
+export type DeprecatedDialectToggle = boolean;
+/**
+ * Granular control over which native Markdown syntax the generator emits for constructs that
+ * differ across real-world dialects (e.g. GitHub's `> [!NOTE]` vs GitLab's `:::note` vs Pandoc's
+ * `::: {.note}` admonitions). Shorthand: pass a `MarkdownDialectPreset` string for a named target;
+ * pass an object for granular control. Any field you omit from the object form falls back to the
+ * preset named by `extends` (default `'extended'`) - **not** to whatever preset may have been
+ * ambient before, since config merging replaces the whole field rather than layering on top of it.
+ */
+export interface MarkdownDialectConfig {
+	/** Base preset any omitted field inherits from. Defaults to 'extended'. */
+	extends?: MarkdownDialectPreset;
+	/**
+	 * Admonition syntax: `'blockquote'` = GitHub `> [!NOTE]`, `'fence'` = GitLab `:::note`,
+	 * `'fence-attribute'` = Pandoc `::: {.note}`, `'none'` = a plain bold-labeled blockquote with no
+	 * special marker. Omit to inherit from the `extends` preset. The legacy flavor names
+	 * `'github'`/`'gitlab'`/`'pandoc'` are accepted as deprecated aliases (see
+	 * `DeprecatedAdmonitionFlavor`) and will be removed in the next major version.
+	 */
+	admonitions?: AdmonitionSyntax | DeprecatedAdmonitionFlavor;
+	/**
+	 * Markdown Extra/Pandoc-style `Term`/`: Description` definition lists (`'colon'`), or `'none'`
+	 * to render terms and descriptions as plain paragraphs. Omit to inherit from `extends`. Passing
+	 * a boolean is deprecated: `true` = `'colon'`, `false` = `'none'` (removed next major).
+	 */
+	definitionLists?: DefinitionListSyntax | DeprecatedDialectToggle;
+	/**
+	 * `[^id]` footnote references/definitions (`'caret'`), or `'none'` to inline note content as a
+	 * parenthetical right at the reference point. Omit to inherit from `extends`. Passing a boolean
+	 * is deprecated: `true` = `'caret'`, `false` = `'none'` (removed next major).
+	 */
+	footnotes?: FootnoteSyntax | DeprecatedDialectToggle;
+	/**
+	 * Pandoc-style `[@citekey]` citations (`'at'`), or `'none'` to emit `[citekey]` (brackets, no
+	 * `@`). Omit to inherit from `extends`. Passing a boolean is deprecated: `true` = `'at'`,
+	 * `false` = `'none'` (removed next major).
+	 */
+	citations?: CitationSyntax | DeprecatedDialectToggle;
+	/**
+	 * Obsidian-style `[[Page]]`/`[[Page|Alias]]` wikilinks (`'double-bracket'`), or `'none'` to fall
+	 * back to a plain `[text](url)` link using the same target. Omit to inherit from `extends`.
+	 * Passing a boolean is deprecated: `true` = `'double-bracket'`, `false` = `'none'` (removed next major).
+	 */
+	wikilinks?: WikilinkSyntax | DeprecatedDialectToggle;
+	/** Inline `$...$`/block `$$...$$` math delimiters (`'dollar'`), or `'none'` for bare LaTeX text. */
+	math?: "dollar" | "none";
+	/**
+	 * Pandoc-style `{width=50% .centered}` attribute lists after images/tables (`'brace'`), or
+	 * `'none'`. Omit to inherit from `extends`. Passing a boolean is deprecated: `true` = `'brace'`,
+	 * `false` = `'none'` (removed next major).
+	 */
+	attributeLists?: AttributeListSyntax | DeprecatedDialectToggle;
+	/**
+	 * GFM `~~text~~` strikethrough (`'tilde'`; not part of base CommonMark), or `'none'`. Omit to
+	 * inherit from `extends`. Passing a boolean is deprecated: `true` = `'tilde'`, `false` = `'none'`
+	 * (removed next major).
+	 */
+	strikethrough?: StrikethroughSyntax | DeprecatedDialectToggle;
+	/**
+	 * `==text==` highlight (`'equals'`; Obsidian/extended flavors, NOT GFM or CommonMark where `==`
+	 * is literal text), or `'none'`. When `'equals'`, a highlighted run round-trips as `==text==`
+	 * and `==text==` is read back as a highlight; when `'none'`, a highlight falls back to an HTML
+	 * `<mark>`/`<span>` per `fallbackToHtml.inlineFormatting`, and `==text==` stays literal on parse.
+	 * Omit to inherit from `extends`.
+	 */
+	highlight?: HighlightSyntax;
+	/** Unordered list bullet character. */
+	bulletListMarker?: "-" | "*" | "+";
+	/** Ordered list marker punctuation. */
+	orderedListMarker?: "." | ")";
+	/** Emphasis delimiter style for bold/italic. */
+	emphasisMarker?: "asterisk" | "underscore";
+	/** Table syntax: native GFM pipe tables, or forced HTML `<table>` (required for strict
+	 *  CommonMark, which has no table syntax of its own). */
+	tables?: "native" | "html";
+	/**
+	 * How an `embed` node is written to Markdown (`'html'` | `'directive'` | `'link'` |
+	 * `'thumbnail'`; see `EmbedSyntax`). This is the authority for embed form. When omitted, the
+	 * deprecated `fallbackToHtml.embeds` boolean is honored (`true`/unset maps to `'html'`, `false`
+	 * to `'link'`), then the default `'html'`.
+	 */
+	embeds?: EmbedSyntax;
+}
+/**
+ * Granular control over when the Markdown generator falls back to raw HTML tags for features
+ * standard Markdown can't express natively. Shorthand: `true`/`false` (via
+ * `MdGeneratorConfig.fallbackToHtml`) turns every part on/off at once; pass an object instead to
+ * control them independently. Omitted object fields default to on, matching the boolean shorthand.
+ */
+export interface FallbackToHtmlConfig {
+	/** Underline/subscript/superscript via `<u>`/`<sub>`/`<sup>`. */
+	textFormatting?: boolean;
+	/** Heading/paragraph text alignment via `<div style="text-align:...">`. */
+	alignment?: boolean;
+	/** Internal-link/heading `<a id>`/`<a name>` anchor tags. */
+	anchors?: boolean;
+	/** Nested-table and merged-cell (colspan/rowspan) HTML `<table>` fallback. */
+	tables?: boolean;
+	/**
+	 * YouTube embed `<div data-youtube-video>` vs. a plain link.
+	 * @deprecated Use `mdConfig.dialect.embeds` (`EmbedSyntax`) instead, which also selects the
+	 * `'directive'` and `'thumbnail'` forms. When `dialect.embeds` is unset this boolean is still
+	 * honored (`true` maps to `'html'`, `false` to `'link'`); it will be removed in the next major.
+	 */
+	embeds?: boolean;
+	/** Multi-line table cell content joined with `<br>` instead of a space. */
+	cellLineBreaks?: boolean;
+	/**
+	 * Multi-paragraph list-item content (an HTML `<li>` with several `<p>` children) joined with
+	 * `<br>` instead of a space, so it stays on the item's single Markdown line. Block children of
+	 * an item (a code fence or table inside `<li>`) degrade under this join, the same way they do
+	 * inside a table cell under `cellLineBreaks`.
+	 */
+	itemLineBreaks?: boolean;
+	/**
+	 * Inline text color, highlight, and font size via a `<span style="color:...;background-color:...;
+	 * font-size:...">` run, which the Markdown parser reads back. These have no Markdown syntax and
+	 * are silently lost otherwise. Unlike the other fields this is **off by default even when
+	 * `fallbackToHtml` is `true`**, because it changes default output; enable it explicitly with
+	 * `fallbackToHtml: { inlineFormatting: true }`.
+	 */
+	inlineFormatting?: boolean;
+}
+/**
+ * Configuration options for Markdown generation.
+ */
+export interface MdGeneratorConfig {
+	/**
+	 * Whether to fallback to HTML tags for features not supported by standard Markdown.
+	 * Pass an object instead of a boolean for granular control over individual parts (text
+	 * formatting, alignment, anchors, tables, embeds, cell line breaks) - see
+	 * `FallbackToHtmlConfig`. Omitted object fields default to on, matching `true`.
+	 *
+	 * Markdown has limited support for complex document structures. This flag controls how
+	 * the generator handles features that cannot be represented in pure Markdown:
+	 *
+	 * 1. If a feature is NOT supported natively by Markdown (e.g., nested tables, text alignment,
+	 *    underline, subscript/superscript):
+	 *    - If true: The generator will use HTML tags (<u>, <sub>, <div>, <table>, etc.) to
+	 *      maintain high fidelity.
+	 *    - If false: The generator will skip or simplify the feature (e.g., ignoring alignment,
+	 *      skipping underline, or hoisting nested tables out of their cells).
+	 *
+	 * 2. If a feature IS supported by Markdown but a higher quality version is possible
+	 *    via HTML (e.g., tables with merged cells):
+	 *    - If true: Use HTML for better fidelity.
+	 *    - If false: Use native Markdown syntax (e.g., a standard GFM table grid).
+	 *
+	 * Defaults to true.
+	 */
+	fallbackToHtml?: boolean | FallbackToHtmlConfig;
+	/**
+	 * Target Markdown dialect for generation - which native syntax to emit for constructs that
+	 * differ across real-world targets (GitHub/GitLab/Obsidian/Pandoc/strict CommonMark). See
+	 * `MarkdownDialectConfig` for the full per-feature field list. Defaults to `'extended'`
+	 * (officeParser's own historical kitchen-sink behavior, unchanged from prior versions).
+	 */
+	dialect?: MarkdownDialectPreset | MarkdownDialectConfig;
+}
+/**
+ * Configuration options for plain text generation.
+ */
+export interface TextGeneratorConfig {
+	/**
+	 * The delimiter used for every new line.
+	 * Defaults to '\n'.
+	 */
+	newlineDelimiter?: string;
+	/**
+	 * Whether to attempt to preserve the original document layout.
+	 * If true, tables are rendered with separators and aligned columns, and list items get their
+	 * markers and indentation.
+	 * If false, output is a flat stream of text nodes (cells are tab-separated).
+	 * Defaults to **true**.
+	 */
+	preserveLayout?: boolean;
+	/**
+	 * Whether to append the collected footnotes/endnotes as a trailing `--- Notes ---` section.
+	 * Set false to omit it when you want only the document body; the notes are still parsed and
+	 * remain available on the AST, they are simply not rendered into the text output.
+	 *
+	 * Note this differs from the parser's `ignoreNotes`, which discards notes at parse time so they
+	 * never reach the AST at all. Use this when you want the AST to keep them but the text output
+	 * to leave them out.
+	 *
+	 * Defaults to true.
+	 */
+	renderNotes?: boolean;
+}
+/**
+ * The strategy used for chunking a document for RAG pipelines.
+ * - 'fixed-size': Traditional character/token count based splitting.
+ * - 'document-structure': Leverages the AST to split at natural document boundaries.
+ * - 'semantic': Uses embedding similarity to find natural topic breakpoints.
+ */
+export type ChunkingStrategy = "fixed-size" | "document-structure" | "semantic";
+/**
+ * Base configuration applicable to all chunking strategies.
+ */
+export interface BaseChunkingConfig {
+	/**
+	 * The strategy used for chunking.
+	 * Default is 'document-structure'.
+	 */
+	strategy?: ChunkingStrategy;
+	/**
+	 * A function that measures the size of a text string.
+	 * Defaults to character count: `(text) => text.length`.
+	 * Override with a token counter (e.g., `tiktoken`) for strict LLM context window adherence.
+	 */
+	lengthFunction?: (text: string) => number;
+	/**
+	 * Whether to strip leading/trailing whitespace from each chunk.
+	 * Default is true.
+	 */
+	stripWhitespace?: boolean;
+	/**
+	 * Whether to include rich AST metadata (page number, slide number, heading, etc.)
+	 * in the generated chunk objects.
+	 * Default is true.
+	 */
+	includeMetadata?: boolean;
+	/**
+	 * Whether to include the starting character index of each chunk
+	 * relative to the whole document. Useful for UI text highlighting.
+	 * Default is false.
+	 */
+	addStartIndex?: boolean;
+	/**
+	 * Optional custom regex (as string or RegExp object) to identify sentence boundaries.
+	 * Use this for languages or specific document types that require custom splitting logic.
+	 * If provided, it overrides or augments the default segmenter.
+	 * @example /[。？！]/
+	 */
+	sentenceBoundaryRegex?: string | RegExp;
+	/**
+	 * Optional list of abbreviations to ignore when splitting text into sentences.
+	 * These words, if followed by a period, will not be treated as sentence boundaries.
+	 * Use this to handle language-specific or domain-specific abbreviations.
+	 * @example ["Inc", "Ltd", "approx"]
+	 */
+	abbreviations?: string[];
+}
+/**
+ * Configuration for Fixed-Size Chunking.
+ * Cuts text based on a maximum size limit with an optional overlap.
+ * This is equivalent to LangChain's `RecursiveCharacterTextSplitter`.
+ */
+export interface FixedSizeChunkingConfig extends BaseChunkingConfig {
+	strategy: "fixed-size";
+	/**
+	 * Maximum size of the chunk, measured by `lengthFunction`.
+	 * Default is 1000 characters.
+	 */
+	chunkSize?: number;
+	/**
+	 * Number of characters/tokens to overlap between consecutive chunks
+	 * to avoid losing context at boundaries.
+	 * Rule of thumb: ~10–20% of `chunkSize`.
+	 * Default is 200.
+	 */
+	chunkOverlap?: number;
+	/**
+	 * Ordered list of separators to try when splitting.
+	 * The chunker tries each in order; if a split would exceed `chunkSize`,
+	 * it tries the next separator.
+	 * Default is ['\n\n', '\n', ' ', ''].
+	 */
+	separators?: string[];
+}
+/**
+ * Configuration for Document-Structure Chunking.
+ * Uses the officeParser AST to split at natural document boundaries like
+ * headings, paragraphs, slides, or pages. This is the recommended strategy
+ * as it preserves semantic context from the document's own structure.
+ */
+export interface DocumentStructureChunkingConfig extends BaseChunkingConfig {
+	strategy: "document-structure";
+	/**
+	 * The primary structural element at which to force a chunk boundary.
+	 * - 'paragraph': Never cross a paragraph boundary (finest-grained, most precise).
+	 * - 'heading': Split at every heading change.
+	 * - 'page': Chunks never span multiple pages (PDF only).
+	 * - 'slide': Chunks never span multiple slides (PPTX/ODP only).
+	 * - 'sheet': Chunks never span multiple sheets (XLSX/ODS only).
+	 * Default is 'paragraph'.
+	 */
+	splitBy?: "page" | "slide" | "sheet" | "heading" | "paragraph";
+	/**
+	 * Maximum size of a chunk (measured by `lengthFunction`).
+	 * If a single structural unit (e.g., one paragraph) exceeds this limit,
+	 * it will be further split using a recursive character splitter.
+	 * Default is 1000 characters.
+	 */
+	maxChunkSize?: number;
+	/**
+	 * How to handle table nodes when splitting.
+	 * - 'row': Split by rows, REPEATING the header row in every chunk so the LLM
+	 *   always understands what the columns mean. (Highly recommended for RAG)
+	 * - 'flatten': Convert the table to plain text and split like a regular block.
+	 * Default is 'row'.
+	 */
+	tableSplitStrategy?: "row" | "flatten";
+}
+/**
+ * Configuration for Semantic Chunking.
+ * Uses an embedding model to detect topic shifts and create boundaries
+ * where content meaning naturally changes. Computationally expensive but
+ * produces the highest quality chunks.
+ */
+export interface SemanticChunkingConfig extends BaseChunkingConfig {
+	strategy: "semantic";
+	/**
+	 * A user-provided async function to generate vector embeddings for a text string.
+	 * Required. Example: a wrapper around OpenAI's `text-embedding-3-small`.
+	 * @example async (text) => await openai.embeddings.create({ input: text, model: 'text-embedding-3-small' }).then(r => r.data[0].embedding)
+	 */
+	embeddingFunction: (text: string) => Promise<number[]>;
+	/**
+	 * The cosine similarity threshold below which a chunk boundary is created.
+	 * When the similarity between two adjacent sentences drops below this value,
+	 * a new chunk starts. Higher = more splits, smaller chunks.
+	 * Default is 0.8.
+	 */
+	similarityThreshold?: number;
+	/**
+	 * Maximum size of a chunk even if semantic similarity remains high.
+	 * Prevents runaway chunks when an entire document is on one topic.
+	 * Default is 2000 characters.
+	 */
+	maxChunkSize?: number;
+	/**
+	 * Number of surrounding sentences to include when computing similarity
+	 * for a sentence. A larger window reduces noise from single odd sentences.
+	 * Default is 1.
+	 */
+	bufferSize?: number;
+	/**
+	 * Number of sentences to process in a single batch when calling the embedding function.
+	 * Higher values are faster but may trigger API rate limits.
+	 * 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.
+ */
+export type ChunkingConfig = FixedSizeChunkingConfig | DocumentStructureChunkingConfig | SemanticChunkingConfig;
+/**
+ * Represents a single document chunk ready for a RAG (Retrieval-Augmented Generation) pipeline.
+ *
+ * Chunks are the result of splitting a document into smaller, semantically coherent
+ * pieces that fit within the context window of an LLM. Each chunk includes the
+ * extracted text and rich AST-derived metadata for citations and filtered retrieval.
+ */
+export interface OfficeChunk {
+	/** The text content of this chunk. This is what gets embedded. */
+	text: string;
+	/**
+	 * Rich contextual metadata extracted from the AST.
+	 * Use this to populate vector DB metadata fields for filtered retrieval
+	 * and for LLM citations.
+	 */
+	metadata: {
+		/** The source file format (e.g., 'docx', 'pptx', 'pdf'). */
+		sourceType: SupportedFileType;
+		/** Page number (1-based), if available (PDF). */
+		pageNumber?: number;
+		/** Slide number (1-based), if available (PPTX/ODP). */
+		slideNumber?: number;
+		/** Sheet name, if available (XLSX/ODS). */
+		sheetName?: string;
+		/** The text of the nearest heading above this chunk in the document. */
+		closestHeading?: string;
+		/** True if this chunk is part of a table split. */
+		isTableChunk?: boolean;
+		/** Extensible for user-defined metadata. */
+		[key: string]: any;
+	};
+	/** The start character index of this chunk in the full document text. Only set when `addStartIndex` is true. */
+	startIndex?: number;
+	/** The end character index of this chunk in the full document text. Only set when `addStartIndex` is true. */
+	endIndex?: number;
+}
+/**
+ * Supported file types for parsing.
+ */
+export type SupportedFileType = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "pdf" | "rtf" | "md" | "html" | "csv" | "epub";
+/**
+ * A structural stand-in for the web `Blob`/`File` so `parseOffice`/`convert` accept them in the
+ * browser without pulling the DOM lib into this package's types. Any object with an
+ * `arrayBuffer()` method qualifies. When `name` is present (as on a `File`) it is used only for
+ * extension-based type detection, never as a filesystem path.
+ */
+export interface BlobLike {
+	arrayBuffer(): Promise<ArrayBuffer>;
+	name?: string;
+}
+/**
+ * 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" | "header" | "footer" | "slideMaster" | "embed" | "admonition" | "definitionList" | "definitionTerm" | "definitionDescription";
+/**
+ * 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.).
+ * All properties are optional and only present when the formatting is explicitly applied.
+ */
+export interface TextFormatting {
+	/**
+	 * Whether the text is bold.
+	 * Corresponds to `<w:b/>` in OOXML, `\b` in RTF.
+	 * @example true for **bold text**, false or undefined for normal weight
+	 */
+	bold?: boolean;
+	/**
+	 * Whether the text is italic.
+	 * Corresponds to `<w:i/>` in OOXML, `\i` in RTF.
+	 * @example true for *italic text*, false or undefined for normal style
+	 */
+	italic?: boolean;
+	/**
+	 * Whether the text is underlined.
+	 * Corresponds to `<w:u/>` in OOXML, `\ul` in RTF.
+	 * @example true for underlined text, false or undefined for no underline
+	 */
+	underline?: boolean;
+	/**
+	 * Whether the text has a strikethrough.
+	 * Corresponds to `<w:strike/>` in OOXML, `\strike` in RTF.
+	 * @example true for ~~struck through~~ text
+	 */
+	strikethrough?: boolean;
+	/**
+	 * Text color in hex format (#RRGGBB).
+	 * Extracted from color tables in RTF or XML color attributes in OOXML.
+	 * @example "#ff0000" for red, "#00ff00" for green, "#0000ff" for blue
+	 */
+	color?: string;
+	/**
+	 * Background/highlight color in hex format (#RRGGBB).
+	 * Represents the background color or text highlighting.
+	 * @example "#ffff00" for yellow highlight, "#d3d3d3" for light gray
+	 */
+	backgroundColor?: string;
+	/**
+	 * Font size with units.
+	 * Most parsers append 'pt' (points), but ODF may use other units like 'in' (inches) or 'cm'.
+	 * @example "12pt" for 12pt, "14pt" for 14pt, "0.5in" for 0.5 inches
+	 */
+	size?: string;
+	/**
+	 * Font family/typeface name.
+	 * Extracted from font tables in RTF or font definitions in OOXML.
+	 * @example "Arial", "Times New Roman", "Calibri", "Ubuntu Mono"
+	 */
+	font?: string;
+	/**
+	 * Whether the text is subscript (e.g., H₂O).
+	 * Corresponds to `\sub` in RTF, `<w:vertAlign w:val="subscript"/>` in OOXML.
+	 * Mutually exclusive with superscript.
+	 * @example true for subscript text like H₂O
+	 */
+	subscript?: boolean;
+	/**
+	 * Whether the text is superscript (e.g., E=mc²).
+	 * Corresponds to `\super` in RTF, `<w:vertAlign w:val="superscript"/>` in OOXML.
+	 * Mutually exclusive with subscript.
+	 * @example true for superscript text like x²
+	 */
+	superscript?: boolean;
+	/**
+	 * The alignment of the text.
+	 * Common in spreadsheet cells or paragraph styles.
+	 * @example "center", "right"
+	 */
+	alignment?: TextAlignment;
+}
+/**
+ * Metadata for a slide in PowerPoint.
+ */
+export interface SlideMetadata {
+	/** The slide number (1-based). */
+	slideNumber: number;
+	/**
+	 * The unique ID of the note associated with this slide (if any).
+	 * @example "slide-note-1"
+	 */
+	noteId?: string;
+	/** The style of the slide. */
+	style?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+}
+/**
+ * Metadata for a sheet in Excel.
+ */
+export interface SheetMetadata {
+	/** The name of the sheet. */
+	sheetName: string;
+	/** The style of the sheet. */
+	style?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+}
+/**
+ * Detailed indentation information for paragraphs and headings.
+ * Values are typically in twentieths of a point (twips) in OOXML.
+ */
+export interface IndentationMetadata {
+	/** Left indentation. */
+	left?: number;
+	/** Right indentation. */
+	right?: number;
+	/** First line indentation. */
+	firstLine?: number;
+	/** Hanging indentation. */
+	hanging?: number;
+}
+/**
+ * Metadata for a heading.
+ */
+export interface HeadingMetadata {
+	/** The heading level (e.g., 1 for H1). */
+	level: number;
+	/** The alignment of the heading. */
+	alignment?: TextAlignment;
+	/** The style of the heading. */
+	style?: string;
+	/** Detailed indentation information. */
+	paragraphIndentation?: IndentationMetadata;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+}
+/**
+ * Metadata for a paragraph.
+ */
+export interface ParagraphMetadata {
+	/** The alignment of the paragraph. */
+	alignment?: TextAlignment;
+	/** The style of the paragraph. */
+	style?: string;
+	/** Detailed indentation information. */
+	paragraphIndentation?: IndentationMetadata;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+}
+/**
+ * Metadata for a list item.
+ */
+export interface ListMetadata {
+	/**
+	 * The type of list: 'ordered' (numbered) or 'unordered' (bulleted).
+	 * @example 'ordered' for numbered lists, 'unordered' for bulleted lists
+	 */
+	listType: "ordered" | "unordered";
+	/**
+	 * The nesting level (indent level) of the list item, starting from 0.
+	 * @example 0 for top-level items, 1 for first nested level
+	 */
+	indentation: number;
+	/** Detailed indentation information. */
+	paragraphIndentation?: IndentationMetadata;
+	/**
+	 * Text alignment of the list item.
+	 * @example '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.
+	 * @example '1', '2' for different list definitions
+	 */
+	listId: string;
+	/**
+	 * The zero-based index of this item within its list.
+	 * Continues incrementing even across paragraph interruptions for the same listId.
+	 * @example 0, 1, 2, 3 for sequential list items
+	 */
+	itemIndex: number;
+	/**
+	 * The style name of the list item.
+	 * @example "ListParagraph"
+	 */
+	style?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+	/** True when this list item is a GFM task-list item (checkbox), regardless of checked state. */
+	isTask?: boolean;
+	/** Checked state for a task-list item. Only meaningful when isTask is true. */
+	checked?: boolean;
+}
+/**
+ * Metadata for a table cell (primarily used in Excel/spreadsheet parsing).
+ * Contains positional information about where the cell appears in the table.
+ */
+export interface CellMetadata {
+	/**
+	 * The row index of the cell (0-based).
+	 * @example 0 for the first row, 1 for the second row, etc.
+	 */
+	row: number;
+	/**
+	 * The column index of the cell (0-based).
+	 * @example 0 for column A, 1 for column B, etc.
+	 */
+	col: number;
+	/**
+	 * Text alignment for this cell's column, from the GFM pipe-table separator row
+	 * (`:---` left, `:---:` center, `---:` right). All cells in a column carry the same value;
+	 * the Markdown generator reads it from the header row to emit the separator.
+	 */
+	align?: "left" | "center" | "right";
+	/**
+	 * The number of rows this cell spans (merges).
+	 * @example 2 if the cell is merged with the one below it.
+	 */
+	rowSpan?: number;
+	/**
+	 * The number of columns this cell spans (merges).
+	 * @example 2 if the cell is merged with the one to its right.
+	 */
+	colSpan?: number;
+	/** The style of the cell. */
+	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[];
+	/**
+	 * Layout alignment of the table on the page (e.g. an editor's custom table node).
+	 * @example 'center'
+	 */
+	align?: "left" | "center" | "right";
+}
+/**
+ * Metadata for a chart node in the document.
+ * Links the chart node to its corresponding attachment in the attachments array.
+ */
+export interface ChartMetadata {
+	/**
+	 * The name of the attachment that contains the actual chart data.
+	 * Use this to look up the full chart data from the attachments array.
+	 * @example "chart1.xml"
+	 */
+	attachmentName: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+}
+/**
+ * Metadata for an image node in the document.
+ * Links the image node to its corresponding attachment in the attachments array.
+ */
+export interface ImageMetadata {
+	/**
+	 * The name of the attachment that contains the actual image data.
+	 * Use this to look up the full image data from the attachments array.
+	 * @example "image1.png"
+	 */
+	attachmentName: string;
+	/**
+	 * Alt text (alternative text) describing the image.
+	 * Extracted from image properties in the document.
+	 * @example "Company logo"
+	 */
+	altText?: string;
+	/**
+	 * URL of the image if it is an external link.
+	 * Typical for HTML or Markdown images that point to remote servers.
+	 * @example "https://example.com/image.png"
+	 */
+	url?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+	/**
+	 * Display width of the image (e.g. an editor's custom image node), as a CSS length or percentage.
+	 * @example "50%"
+	 */
+	width?: string;
+	/**
+	 * Layout alignment of the image (e.g. an editor's custom image node).
+	 * @example 'center'
+	 */
+	align?: "left" | "center" | "right";
+	/** Advisory image title (Markdown `![alt](url "title")`, HTML `<img title>`), if any. */
+	title?: string;
+}
+/**
+ * Metadata for an embedded external media node (e.g. a YouTube video).
+ * Markdown has no native syntax for this - see `MarkdownGenerator`'s `embed` case.
+ */
+export interface EmbedMetadata {
+	/**
+	 * The kind of embed. 'youtube' is recognized from a `data-youtube-video` wrapper or a YouTube
+	 * iframe; 'iframe' is a generic preserved iframe (opt-in via `HtmlParserConfig.preserveIframes`).
+	 */
+	embedType: "youtube" | "iframe";
+	/** The provider-specific video ID (e.g. the 11-character YouTube video ID). Absent for generic iframes. */
+	videoId?: string;
+	/** The original/canonical URL of the embedded media, if known. For a generic iframe, its `src`. */
+	url?: string;
+	/** Display width, as a CSS length or percentage. */
+	width?: string;
+	/** Display height, as a CSS length or percentage. */
+	height?: string;
+	/** Layout alignment of the embed. */
+	align?: "left" | "center" | "right";
+	/** Human-readable label for the embed (e.g. the `[Label]` of a `::youtube[Label]{...}` leaf
+	 *  directive, or a gated embed's caption). Purely descriptive; never a trust or render input. */
+	label?: string;
+}
+/**
+ * Metadata for an admonition/alert node (e.g. GitHub's `> [!NOTE]` or GLFM's `:::note`).
+ * `MarkdownParser` accepts both syntaxes (and generates either, plus Pandoc's `::: {.note}`,
+ * depending on `MdGeneratorConfig.dialect`). Children are block content (paragraphs) wrapped by
+ * the admonition.
+ */
+export interface AdmonitionMetadata {
+	admonitionType: "note" | "tip" | "important" | "warning" | "caution";
+	/** Optional custom title; falls back to the type label. */
+	title?: string;
+	/** Which concrete input syntax produced this node. Always populated by the parser. */
+	sourceSyntax?: "github" | "gitlab";
+}
+/**
+ * Metadata for PDF page nodes.
+ * Indicates which page of the PDF this content came from.
+ */
+export interface PageMetadata {
+	/**
+	 * The page number (1-based) from the PDF document.
+	 * @example 1 for the first page, 2 for the second page, etc.
+	 */
+	pageNumber: number;
+}
+/**
+ * Metadata for text nodes that contain hyperlinks.
+ * Used to track hyperlinks in text runs.
+ */
+export interface TextMetadata {
+	/** Style name of the text */
+	style?: string;
+	/**
+	 * The hyperlink URL (for external links) or anchor reference (for internal links).
+	 * @example "https://example.com" or "#_Toc123456"
+	 */
+	link?: string;
+	/**
+	 * Type of hyperlink.
+	 * - 'internal': Link to a bookmark/anchor within the same document
+	 * - 'external': Link to an external URL
+	 */
+	linkType?: "internal" | "external";
+	/**
+	 * When set, this text is an abbreviation and this is its full-form expansion,
+	 * rendered as `<abbr title="...">`. Populated from Markdown Extra's
+	 * `*[HTML]: Hypertext Markup Language` syntax or an HTML `<abbr>` tag.
+	 */
+	abbreviationTitle?: string;
+	/**
+	 * When set, this text is a Pandoc/MultiMarkdown-style citation reference
+	 * (`[@citekey]`), and this is the bare citekey (e.g. "smith2024"). Bibliography
+	 * resolution (author/year display, .bib management) is left to the consuming app.
+	 */
+	citationKey?: string;
+	/**
+	 * True when this is an Obsidian-style wikilink (`[[page]]` / `[[page|alias]]`).
+	 * `link` holds the bare page name and `linkType` is always 'internal'; the
+	 * per-workspace enable/disable toggle lives in markdownwriter, not here -
+	 * officeParser always parses/generates the syntax.
+	 */
+	wikilink?: boolean;
+	/** Advisory link title (Markdown `[text](url "title")`, HTML `<a title>`), if any. */
+	title?: string;
+}
+/**
+ * Metadata for note nodes (footnotes/endnotes).
+ * Used in ODT and DOCX files to track notes.
+ */
+export interface NoteMetadata {
+	/**
+	 * Type of note: 'footnote' or 'endnote'.
+	 */
+	noteType?: "footnote" | "endnote";
+	/**
+	 * The unique ID of the note from the source document.
+	 * @example "1", "2"
+	 */
+	noteId?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+	/** The slide number this note is associated with (used in PowerPoint). */
+	slideNumber?: number;
+	/**
+	 * True for a footnote/endnote definition that no reference points at (an "orphan").
+	 * The Markdown parser sets this when it recovers a `[^id]: ...` definition with no matching
+	 * `[^id]` reference so the definition is preserved rather than dropped. Generators route such
+	 * notes into their footnotes section without a citation marker, and the HTML generator omits
+	 * the (otherwise dangling) back-link.
+	 */
+	unreferenced?: boolean;
+}
+/**
+ * Metadata for break nodes.
+ * Used in DOCX files to track line and page breaks.
+ */
+export interface BreakMetadata {
+	/**
+	 * Type of break. The break type determines the next location where
+	 * text shall be placed.
+	 * - 'column': The next text will be placed in the next column.
+	 * - 'page': The next text will be placed on the next page.
+	 * - 'lastRenderedPage': The editing application has inserted a soft break on the last save.
+	 * - 'textWrapping' (default, assumed when not specified): The next text will be placed on the next line.
+	 * - 'carriageReturn': An explicit carriage return (w:cr) equivalent to a hard line break.
+	 * - 'thematic': A thematic break (Markdown `---`/`***`/`___`, HTML `<hr>`) - a horizontal
+	 *   rule separating sections, distinct from a page break. Emitted as `---` in Markdown and
+	 *   `<hr>` in HTML.
+	 */
+	breakType: "column" | "page" | "lastRenderedPage" | "textWrapping" | "carriageReturn" | "thematic";
+	/**
+	 * Specifies the location which shall be used as the next available line when breakType
+	 * has a value of 'textWrapping'. Should be ignored for other break types.
+	 * - 'all': text wrapping break shall advance the text to the next line which spans the full width of the line
+	 * - 'left': text wrapping break shall restart in next text region unblocked on the left
+	 * - 'none': text wrapping break shall advance the text to the next line regardless of any floating objects
+	 * - 'right': text wrapping break shall restart in next text region unblocked on the right
+	 */
+	clear?: "all" | "left" | "none" | "right";
+}
+/**
+ * Metadata for a code block.
+ */
+export interface CodeMetadata {
+	/** The programming language of the code block (e.g., 'typescript', 'python') */
+	language?: string;
+	/** Unique anchor IDs for internal linking. */
+	anchorIds?: string[];
+	/**
+	 * When set, this node is a LaTeX math expression rather than a code block. `node.text`
+	 * holds the bare LaTeX (delimiters excluded); 'inline' round-trips as `$...$`,
+	 * 'block' as `$$...$$`. Matches attribute-driven editors' math nodes.
+	 */
+	math?: "inline" | "block";
+}
+/**
+ * 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 | CommentMetadata | HeaderFooterMetadata | TableMetadata | EmbedMetadata | AdmonitionMetadata | undefined;
+/**
+ * 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: [...]
+ * }
+ */
+/**
+ * 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.
+	 * For leaf nodes (text), this is the actual text content.
+	 * @example "Hello world" for a paragraph containing "Hello " and "world"
+	 */
+	text?: string;
+	/**
+	 * Child nodes that make up this node's content.
+	 * Used for hierarchical structures:
+	 * - Paragraphs contain text runs with different formatting
+	 * - Tables contain rows
+	 * - Rows contain cells
+	 * - Cells contain paragraphs
+	 * @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.
+	 * For container nodes like paragraphs, formatting typically appears on child text nodes.
+	 * @example { bold: true, size: "12", font: "Arial" }
+	 */
+	formatting?: TextFormatting;
+	/**
+	 * The raw source content for this node.
+	 * - For XML-based formats (DOCX, XLSX, PPTX): contains the raw XML
+	 * - For RTF: contains the raw RTF markup
+	 * - For PDF: typically not available
+	 * Only populated when `config.includeRawContent` is true.
+	 * Useful for debugging or when you need access to format-specific features.
+	 * @example "<w:p><w:r><w:t>Hello</w:t></w:r></w:p>" for DOCX
+	 */
+	rawContent?: string;
+	/**
+	 * Source HTML attributes that no typed metadata field consumed, preserved for round-trip
+	 * fidelity (e.g. a `data-*` attribute an editor round-trips through officeParser).
+	 *
+	 * Only populated by the HTML/XHTML parser, only for elements it recognises, and only when
+	 * `htmlParserConfig.preserveAttributes` is enabled - so by default this is always absent.
+	 *
+	 * Sanitized on both legs, since an AST can also be constructed programmatically rather than
+	 * parsed: event handlers (`on*`) and `srcdoc` are never carried, URL-bearing attributes go
+	 * through the same URL sanitizer as typed fields, and every value is escaped on output. A
+	 * typed field always wins over a same-named entry here.
+	 *
+	 * Ignored by the non-HTML generators (Markdown, RTF, CSV, text, chunking) by design - these
+	 * are HTML attributes and have no meaning in those targets.
+	 * @example { 'data-tracking-id': 'abc123', 'class': 'lead' }
+	 */
+	htmlAttributes?: Record<string, 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;
+} | {
+	type: "embed";
+	metadata?: EmbedMetadata;
+} | {
+	type: "admonition";
+	metadata?: AdmonitionMetadata;
+} | {
+	type: "definitionList";
+	metadata?: undefined;
+} | {
+	type: "definitionTerm";
+	metadata?: undefined;
+} | {
+	type: "definitionDescription";
+	metadata?: undefined;
+});
+/**
+ * Structured information extracted from a chart.
+ */
+export interface ChartData {
+	/** Chart title (if any) */
+	title?: string;
+	/** X-axis title (for continuous or categorical axes) */
+	xAxisTitle?: string;
+	/** Y-axis title (for value or continuous axes) */
+	yAxisTitle?: string;
+	/**
+	 * Collections of data points.
+	 * For bar/line charts, each dataset is one 'line' or group of bars.
+	 * For pie charts, there is typically only one dataset.
+	 */
+	dataSets: {
+		/** Name of this data group (e.g., 'Sales 2023') */
+		name?: string;
+		/** Actual numeric or string values for this group */
+		values: string[];
+		/** Specific labels for each point in this dataset (if defined per point) */
+		pointLabels: string[];
+	}[];
+	/**
+	 * Labels for the chart facets (e.g., 'Jan', 'Feb', 'Mar' on X-axis).
+	 * These typically correspond to the data points in each dataSet.
+	 */
+	labels: string[];
+	/** Every text node discovered in the chart XML (for keyword search/raw extraction) */
+	rawTexts: string[];
+}
+/**
+ * Represents an attachment extracted from the document (image, chart, etc.).
+ * Attachments are binary resources embedded in the document.
+ * Only populated when `config.extractAttachments` is true.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'image',
+ *   mimeType: 'image/png',
+ *   data: 'iVBORw0KGgoAAAANSUhEUgAA...',  // Base64
+ *   name: 'chart1.png',
+ *   extension: 'png',
+ *   ocrText: 'Sales Chart Q4 2024'  // If OCR was enabled
+ * }
+ * ```
+ */
+export interface OfficeAttachment {
+	/**
+	 * The category of the attachment.
+	 * Helps identify what kind of content this represents.
+	 * @example 'image' for photos and diagrams, 'chart' for embedded charts
+	 */
+	type: "image" | "chart";
+	/**
+	 * The MIME type of the attachment data.
+	 * Indicates the file format and how the data should be interpreted.
+	 * @example 'image/png', 'image/jpeg', 'image/svg+xml'
+	 */
+	mimeType: OfficeMimeType;
+	/**
+	 * The attachment content encoded as Base64.
+	 * This is the actual binary data of the image/chart/etc. encoded for text transmission.
+	 * Can be used directly in HTML img tags with data URIs or decoded to binary.
+	 * @example "iVBORw0KGgoAAAANSUhEUgAA..." (truncated)
+	 */
+	data: string;
+	/**
+	 * A unique name for this attachment file.
+	 * May be derived from the source file or auto-generated.
+	 * Used to link `ImageMetadata` nodes to their corresponding attachments.
+	 * @example "image1.png", "chart2.emf", "picture3.jpg"
+	 */
+	name: string;
+	/**
+	 * The file extension (without the dot).
+	 * Derived from the MIME type or original filename.
+	 * @example "png", "jpg", "svg"
+	 */
+	extension: string;
+	/**
+	 * Text extracted from the image using Optical Character Recognition (OCR).
+	 * Only present when:
+	 * - `config.ocr` is true
+	 * - `config.extractAttachments` is true
+	 * - The attachment is an image containing text
+	 * Uses Tesseract.js with the language specified in `config.ocrLanguage`.
+	 * @example "Annual Revenue: $1.2M"
+	 */
+	ocrText?: string;
+	/**
+	 * Alt text or description associated with the image in the document.
+	 * Extracted from the document markup (e.g., wp:docPr descr attribute in DOCX).
+	 * @example "A chart showing sales growth"
+	 */
+	altText?: string;
+	/**
+	 * Structured data extracted from a chart attachment.
+	 * Only present if the attachment is a chart and data extraction was successful.
+	 * Contains series names, values, labels, and titles.
+	 * @example { title: "Sales Chart", series: [...], categories: [...] }
+	 */
+	chartData?: ChartData;
+}
+/**
+ * Metadata for the parsed file.
+ */
+export interface OfficeMetadata {
+	/** The title of the document. */
+	title?: string;
+	/** The author of the document. */
+	author?: string;
+	/** User who last modified the document. */
+	lastModifiedBy?: string;
+	/** Creation date. */
+	created?: Date;
+	/** Last modification date. */
+	modified?: Date;
+	/** Description/Comments. */
+	description?: string;
+	/** Subject/Topic. */
+	subject?: string;
+	/** Number of pages (if available). */
+	pages?: number;
+	/** Document-wide default formatting settings (font, size, color). */
+	formatting?: Partial<TextFormatting>;
+	/** Style map for styles in the document. */
+	styleMap?: Record<string, Partial<TextFormatting>>;
+	/**
+	 * User-defined custom properties embedded in the document.
+	 * Sources by format:
+	 * - DOCX/XLSX/PPTX: `docProps/custom.xml` (Office custom document properties)
+	 * - ODT/ODP/ODS: `meta:user-defined` elements in `meta.xml`
+	 * - PDF: non-standard entries in the PDF Info dictionary
+	 * RTF does not support custom properties; the `\info` group is not extracted.
+	 * 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 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).
+ *
+ * ### 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
+ * const ast = await OfficeParser.parseOffice('document.docx', {
+ *   extractAttachments: true,
+ *   includeRawContent: false
+ * });
+ *
+ * console.log(ast.type); // 'docx'
+ * console.log(ast.metadata.author); // 'John Doe'
+ * console.log(ast.content.length); // Number of top-level content nodes
+ * console.log(ast.toText()); // Plain text representation
+ * console.log((await ast.to('md')).value); // Markdown representation
+ * console.log((await ast.to('html')).value); // HTML representation
+ * console.log((await ast.to('rtf')).value); // RTF representation
+ * console.log((await ast.to('csv')).value); // CSV representation
+ * console.log((await ast.to('chunks')).value); // Chunks representation
+ * ```
+ */
+export interface OfficeParserAST {
+	/**
+	 * The original configuration used to parse this document.
+	 * This includes options like OCR settings, delimiter choices, and filtering flags.
+	 */
+	config: OfficeParserConfig;
+	/**
+	 * The type of the parsed file.
+	 * Indicates which parser was used and what format the input was in.
+	 * @example 'docx', 'xlsx', 'pptx', 'rtf', 'pdf', 'odt', 'odp', 'ods'
+	 */
+	type: SupportedFileType;
+	/**
+	 * Document metadata extracted from the file properties.
+	 * Includes information like author, title, creation date, etc.
+	 * Availability depends on the file format and whether metadata was present in the source.
+	 * @example { author: 'John Smith', title: 'Annual Report', created: new Date('2024-01-01') }
+	 */
+	metadata: OfficeMetadata;
+	/**
+	 * The hierarchical content structure of the document.
+	 * This is an array of top-level content nodes. Each node can have children, creating a tree.
+	 * For different file types:
+	 * - DOCX: Array of paragraphs, headings, tables, etc.
+	 * - XLSX: Array of sheets, each containing rows
+	 * - PPTX: Array of slides, each containing content nodes
+	 * - PDF: Array of pages, each containing paragraphs
+	 * @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.
+	 * Each attachment includes:
+	 * - Base64-encoded data
+	 * - MIME type
+	 * - Optional OCR text (if `config.ocr` is true)
+	 * @example [{ type: 'image', mimeType: 'image/png', data: 'base64...', name: 'image1.png' }]
+	 */
+	attachments: OfficeAttachment[];
+	/** Any warnings or non-fatal issues encountered during parsing. */
+	warnings: OfficeIssue[];
+	/**
+	 * @deprecated Use `.to('text')` instead. This method is the older renderer and takes no
+	 * configuration; `.to('text')` produces the same content and lets you configure the rest.
+	 *
+	 * Converts the entire AST to plain text, flattening the document structure and stripping all
+	 * formatting, metadata, and structure. Text is joined using `config.newlineDelimiter`
+	 * (default: `'\n'`).
+	 *
+	 * **Migrating.** `.to('text')` is asynchronous and configurable. At its defaults it emits
+	 * everything this method emits, verified across every bundled fixture in all 12 supported
+	 * formats in both layout modes: no word produced here is missing there. It also renders merged
+	 * table cells correctly, where this method glues them (`OneThree` vs `One Three`).
+	 *
+	 * Where the two differ is configuration, not capability. Notes and image placeholders are
+	 * emitted by default but are switchable; this method emits neither and offers no way to ask
+	 * for them. Layout is likewise a knob rather than a fixed behavior:
+	 *
+	 * ```typescript
+	 * // Default: aligned table grids, list markers, notes, image placeholders.
+	 * const { value } = await ast.to('text');
+	 *
+	 * // Deliberate opt-out - closest to this method's shape.
+	 * const { value } = await ast.to('text', {
+	 *     includeImages: false,
+	 *     textConfig: { preserveLayout: false, renderNotes: false },
+	 * });
+	 * ```
+	 *
+	 * Spreadsheets (CSV/ODS/XLSX) are unaffected by `preserveLayout`, since it governs
+	 * `table`/`list` nodes rather than `sheet`/`row`/`cell`; there the default aligned grid is the
+	 * most faithful rendering.
+	 *
+	 * @returns A plain text representation of the document
+	 * @example
+	 * ```typescript
+	 * const text = ast.toText();
+	 * console.log(text); // "Hello world\nChapter 1\n..."
+	 * ```
+	 */
+	toText(): string;
+	/**
+	 * Converts this AST to the specified destination format.
+	 * This is the recommended way to convert the AST to different formats.
+	 *
+	 * @param destination The target format (e.g., 'text', 'md', 'html', 'pdf').
+	 * @param config Optional configuration for the generator.
+	 * @returns A promise resolving to the generated content (string or Buffer).
+	 * @example
+	 * ```typescript
+	 * const html = await ast.to('html', { includeFormatting: false });
+	 * const md = await ast.to('md');
+	 * ```
+	 */
+	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.
+ *
+ * This class contains a single static method `parseOffice` that serves as the
+ * universal entry point for parsing any supported office document format.
+ */
+export declare class OfficeParser {
+	/**
+	 * Parses an office document and returns a structured AST.
+	 *
+	 * This method:
+	 * 1. Accepts a file path, Buffer, or ArrayBuffer
+	 * 2. Detects the file type (from extension or content)
+	 * 3. Routes to the appropriate format-specific parser
+	 * 4. Returns a unified AST structure
+	 *
+	 * **File Type Detection:**
+	 * - If a file path is provided, uses the file extension
+	 * - If a Buffer is provided, uses magic bytes detection (file-type library)
+	 *
+	 * **Supported Formats and Routes:**
+	 * - `.docx` → WordParser (OOXML)
+	 * - `.xlsx` → ExcelParser (OOXML)
+	 * - `.pptx` → PowerPointParser (OOXML)
+	 * - `.odt`, `.odp`, `.ods` → OpenOfficeParser (ODF)
+	 * - `.pdf` → PdfParser (PDF.js)
+	 * - `.rtf` → RtfParser (custom RTF parser)
+	 * - `.csv` → CsvParser
+	 * - `.md` → MarkdownParser
+	 * - `.html` → HtmlParser
+	 * - `.epub` → EpubParser
+	 *
+	 * @param file - File path (string), Buffer, or ArrayBuffer containing the document
+	 * @param config - Optional configuration object (defaults applied for all omitted options)
+	 * @returns A promise resolving to the parsed OfficeParserAST
+	 * @throws {Error} If file doesn't exist, format is unsupported, or parsing fails
+	 *
+	 * @example
+	 * ```typescript
+	 * // Parse a DOCX file
+	 * const ast = await OfficeParser.parseOffice('report.docx', {
+	 *   extractAttachments: true,
+	 *   includeRawContent: false
+	 * });
+	 *
+	 * // Parse a Buffer with OCR enabled
+	 * const buffer = await retrieveData('document.pdf').then(r => r.arrayBuffer());
+	 * const ast = await OfficeParser.parseOffice(buffer, {
+	 *   ocr: true,
+	 *   ocrLanguage: 'eng+fra'
+	 * });
+	 *
+	 * // Extract text
+	 * const text = ast.toText();
+	 * ```
+	 */
+	static parseOffice(file: string | Buffer | ArrayBuffer | Uint8Array | BlobLike, configOrCallback?: OfficeParserConfig | ((ast: OfficeParserAST, err?: any) => void), config?: OfficeParserConfig): Promise<OfficeParserAST>;
+	/**
+	 * Terminates all active OCR workers and cleans up resources.
+	 *
+	 * This should be called when the application is shutting down or when OCR
+	 * is no longer needed to prevent memory leaks and orphaned worker processes.
+	 *
+	 * @returns A promise that resolves when all workers have been terminated
+	 */
+	static terminateOcr(): Promise<void>;
+}
+/**
+ * Main generator class providing document conversion functionality.
+ */
+export declare class OfficeGenerator {
+	/**
+	 * Normalizes format aliases (e.g., 'txt' to 'text', 'markdown' to 'md') to standard internal formats.
+	 */
+	static normalizeDestination(dest: string): UniversalGeneratorFormat;
+	/**
+	 * Generates a file of the specified type from an AST.
+	 * This is the single source of truth for generation logic.
+	 *
+	 * @param ast - The OfficeParserAST to generate from
+	 * @param destination - The target format (e.g., 'text', 'md', 'html', 'pdf')
+	 * @param config - Optional configuration for the generator
+	 * @returns A promise resolving to the ConversionResult containing the value and messages
+	 * @throws {Error} If the destination format is unsupported
+	 */
+	static generate<T extends SupportedFileType, D extends SupportedDestination<T>>(ast: OfficeParserAST & {
+		type: T;
+	}, destination: D, config?: GeneratorConfig<D>): Promise<ConversionResult<D>>;
+}
+/**
+ * Utility type to infer the file type from a file path string literal.
+ */
+export type InferFileTypeFromPath<T> = T extends `${string}.${infer E}` ? (Lowercase<E> extends SupportedFileType ? Lowercase<E> : SupportedFileType) : SupportedFileType;
+/**
+ * Main converter class providing a streamlined one-step API for document conversion.
+ *
+ * This class coordinates the `OfficeParser` and `OfficeGenerator` to transform
+ * documents from one format to another (e.g., DOCX to Markdown, PDF to HTML).
+ */
+export declare class OfficeConverter {
+	/**
+	 * Converts an office document from its source format to a specified destination format.
+	 *
+	 * This method:
+	 * 1. Detects the source file type and parses it into a unified AST using `OfficeParser`.
+	 * 2. Automatically configures the parser based on the generator requirements (e.g., enabling
+	 *    attachment extraction if images are requested in the output).
+	 * 3. Generates the destination document from the AST using `OfficeGenerator`.
+	 *
+	 * @template F The inferred type of the input file (path string or buffer).
+	 * @template T The authoritative source file type (inferred from path or config).
+	 *
+	 * @param file - File path (string), Buffer, or ArrayBuffer containing the source document.
+	 * @param destination - The target format (e.g., 'md', 'html', 'pdf', 'text', 'chunks').
+	 * @param config - Optional unified configuration for both the parser and generator phases.
+	 *
+	 * @returns A promise resolving to the ConversionResult containing the value and messages.
+	 * @throws {Error} If the source format is unsupported or parsing/generation fails.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Convert Word to Markdown with a single call
+	 * const { value: markdown } = await OfficeConverter.convert('report.docx', 'md');
+	 *
+	 * // Convert PDF to HTML (Note: OCR is disabled in this one-step API)
+	 * const { value: html } = await OfficeConverter.convert(buffer, 'html', {
+	 *   generatorConfig: {
+	 *     includeImages: true
+	 *   }
+	 * });
+	 * ```
+	 */
+	static convert<F extends string | Buffer | ArrayBuffer | Uint8Array | BlobLike, T extends SupportedFileType = InferFileTypeFromPath<F>, D extends SupportedDestination<T> = SupportedDestination<T>>(file: F, destination: D, config?: OfficeConverterConfig<D, T>): Promise<ConversionResult<D>>;
+}
+export declare const parseOffice: typeof OfficeParser.parseOffice;
+export declare const terminateOcr: typeof OfficeParser.terminateOcr;
+export declare const convert: typeof OfficeConverter.convert;
+export declare const generate: typeof OfficeGenerator.generate;
+
+export {
+	OfficeParser as default,
+};
+
+export {};