officeparser 7.2.3 → 7.4.0

package/dist/officeparser.browser.slim.d.ts

@@ -41,6 +41,8 @@ export declare enum OfficeErrorType {
 	ZIP_ENTRY_INVALID_SIZE = "ZIP_ENTRY_INVALID_SIZE",
 	/** ZIP uncompressed size limit exceeded */
 	ZIP_SIZE_LIMIT_EXCEEDED = "ZIP_SIZE_LIMIT_EXCEEDED",
+	/** 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"
 }
@@ -82,7 +84,13 @@ export declare enum OfficeWarningType {
 	/** 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"
+	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"
 }
 /**
  * Consolidated timeout settings for OCR operations.
@@ -209,9 +217,9 @@ export interface OcrConfig {
 	abortSignal?: AbortSignal | null;
 }
 /**
- * Configuration options for the OfficeParser.
+ * Configuration options shared across every input format.
  */
-export interface OfficeParserConfig {
+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.
@@ -363,6 +371,44 @@ export interface OfficeParserConfig {
 	 */
 	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;
+}
+/**
+ * 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.
  */
@@ -379,6 +425,28 @@ export interface DecompressionLimits {
 	 * 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.
@@ -398,7 +466,7 @@ export interface 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 : string;
+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>;
@@ -408,7 +476,7 @@ export interface ConversionResult<D extends UniversalGeneratorFormat> {
 /**
  * Universal formats supported by all source types for generation.
  */
-export type UniversalGeneratorFormat = "text" | "md" | "html" | "pdf" | "csv" | "rtf" | "chunks";
+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.
@@ -420,6 +488,56 @@ export type SupportedDestination<_T extends SupportedFileType = SupportedFileTyp
 /**
  * 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.
@@ -488,6 +606,29 @@ export interface CommonGeneratorConfig {
 	 * 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.
@@ -603,15 +744,64 @@ export interface HtmlInjectionConfig {
 	/** 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;
+	standalone?: boolean | StandaloneConfig;
 	/**
 	 * URL for the Chart.js library to use when 'includeCharts' is true.
 	 * Defaults to 'https://cdn.jsdelivr.net/npm/chart.js'.
@@ -786,12 +976,81 @@ export interface CsvGeneratorConfig {
 	 */
 	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";
+/**
+ * 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: GitHub `> [!NOTE]`, GitLab `:::note`, Pandoc `::: {.note}`, or `'none'`
+	 *  to degrade to a plain bold-labeled blockquote with no special marker. */
+	admonitions?: "github" | "gitlab" | "pandoc" | "none";
+	/** Markdown Extra/Pandoc-style `Term\n: Description` definition lists. */
+	definitionLists?: boolean;
+	/** `[^id]` footnote references/definitions. When false, note content is inlined as a
+	 *  parenthetical right at the reference point instead of using footnote syntax. */
+	footnotes?: boolean;
+	/** Pandoc-style `[@citekey]` citations. When false, emits `[citekey]` (brackets, no `@`). */
+	citations?: boolean;
+	/** Obsidian-style `[[Page]]`/`[[Page|Alias]]` wikilinks. When false, falls back to a plain
+	 *  `[text](url)` link using the same target. */
+	wikilinks?: boolean;
+	/** Inline `$...$`/block `$$...$$` math delimiters, or `'none'` for bare LaTeX text. */
+	math?: "dollar" | "none";
+	/** Pandoc-style `{width=50% .centered}` attribute lists after images/tables. */
+	attributeLists?: boolean;
+	/** GFM `~~text~~` strikethrough (not part of base CommonMark). */
+	strikethrough?: boolean;
+	/** 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";
+}
+/**
+ * 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. */
+	embeds?: boolean;
+	/** Multi-line table cell content joined with `<br>` instead of a space. */
+	cellLineBreaks?: 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:
@@ -810,7 +1069,14 @@ export interface MdGeneratorConfig {
 	 *
 	 * Defaults to true.
 	 */
-	fallbackToHtml?: boolean;
+	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.
@@ -823,11 +1089,24 @@ export interface TextGeneratorConfig {
 	newlineDelimiter?: string;
 	/**
 	 * Whether to attempt to preserve the original document layout.
-	 * If true, tables will be rendered with separators and aligned columns.
-	 * If false, output will be a flat stream of text nodes.
-	 * Defaults to false.
+	 * 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.
@@ -1032,11 +1311,11 @@ export interface OfficeChunk {
 /**
  * Supported file types for parsing.
  */
-export type SupportedFileType = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "pdf" | "rtf" | "md" | "html" | "csv";
+export type SupportedFileType = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "pdf" | "rtf" | "md" | "html" | "csv" | "epub";
 /**
  * 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";
+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.
  */
@@ -1230,6 +1509,10 @@ export interface ListMetadata {
 	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).
@@ -1269,6 +1552,11 @@ export interface CellMetadata {
 export interface TableMetadata {
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/**
+	 * Layout alignment of the table on the page (e.g. inscript-editor's `CustomTable`).
+	 * @example 'center'
+	 */
+	align?: "left" | "center" | "right";
 }
 /**
  * Metadata for a chart node in the document.
@@ -1309,6 +1597,45 @@ export interface ImageMetadata {
 	url?: string;
 	/** Unique anchor IDs for internal linking. */
 	anchorIds?: string[];
+	/**
+	 * Display width of the image (e.g. inscript-editor's `CustomImage`), as a CSS length or percentage.
+	 * @example "50%"
+	 */
+	width?: string;
+	/**
+	 * Layout alignment of the image (e.g. inscript-editor's `CustomImage`).
+	 * @example 'center'
+	 */
+	align?: "left" | "center" | "right";
+}
+/**
+ * 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. Only 'youtube' is supported today; the shape is generic for future providers. */
+	embedType: "youtube";
+	/** The provider-specific video ID (e.g. the 11-character YouTube video ID). */
+	videoId: string;
+	/** The original/canonical URL of the embedded media, if known. */
+	url?: string;
+	/** Display width, as a CSS length or percentage. */
+	width?: string;
+	/** Layout alignment of the embed. */
+	align?: "left" | "center" | "right";
+}
+/**
+ * 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.
@@ -1339,6 +1666,25 @@ export interface TextMetadata {
 	 * - '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;
 }
 /**
  * Metadata for note nodes (footnotes/endnotes).
@@ -1392,6 +1738,12 @@ export interface CodeMetadata {
 	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 inscript-editor's math node (Roadmap Step 11.5).
+	 */
+	math?: "inline" | "block";
 }
 /**
  * Metadata for a comment/annotation.
@@ -1411,7 +1763,7 @@ export interface HeaderFooterMetadata {
 /**
  * Union type for content metadata.
  */
-export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | BreakMetadata | CodeMetadata | CommentMetadata | HeaderFooterMetadata | TableMetadata | undefined;
+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.
@@ -1486,6 +1838,23 @@ export interface BaseContentNode {
 	 * @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.
@@ -1573,6 +1942,21 @@ export type OfficeContentNode = BaseContentNode & ({
 } | {
 	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.
@@ -1815,14 +2199,36 @@ export interface OfficeParserAST {
 	/** Any warnings or non-fatal issues encountered during parsing. */
 	warnings: OfficeIssue[];
 	/**
-	 * @deprecated Use `.to('text')` instead.
-	 * Note: This method is synchronous, while the new `.to()` method is asynchronous.
+	 * @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.
-	 * This method flattens the document structure and returns just the text content,
-	 * stripping out all formatting, metadata, and structure.
+	 * 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 },
+	 * });
+	 * ```
 	 *
-	 * The text is concatenated using the delimiter specified in `config.newlineDelimiter` (default: '\n').
+	 * 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
@@ -1877,6 +2283,7 @@ export declare class OfficeParser {
 	 * - `.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)
@@ -1978,7 +2385,7 @@ export declare class OfficeConverter {
 	 * });
 	 * ```
 	 */
-	static convert<F extends string | Buffer | ArrayBuffer | Uint8Array, T extends SupportedFileType = InferFileTypeFromPath<F>>(file: F, destination: SupportedDestination<T>, config?: OfficeConverterConfig<SupportedDestination<T>, T>): Promise<ConversionResult<SupportedDestination<T>>>;
+	static convert<F extends string | Buffer | ArrayBuffer | Uint8Array, 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;