officeparser 7.2.3 → 7.4.0

package/dist/types.d.ts

@@ -39,6 +39,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"
 }
@@ -80,7 +82,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.
@@ -207,9 +215,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.
@@ -361,6 +369,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.
+ */
+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.
  */
@@ -377,6 +423,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;
 }
 /**
  * A fully-populated parser configuration containing all options.
@@ -401,7 +469,7 @@ export interface OfficeIssue {
 /**
  * The result of a document conversion operation.
  */
-type ConversionValue<D extends UniversalGeneratorFormat> = D extends 'pdf' ? Uint8Array | string : D extends 'chunks' ? OfficeChunk[] : D extends 'csv' ? string | Uint8Array : string;
+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>;
@@ -411,7 +479,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.
@@ -423,6 +491,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.
@@ -491,6 +609,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.
@@ -605,7 +746,7 @@ export type DeepRequired<T> = T extends Function | Date | Buffer | RegExp ? T :
  * `chunksConfig` is typed as `ChunkingConfig` directly (not DeepRequired) because
  * it is a discriminated union whose members cannot be uniformly deep-required.
  */
-export type FullGeneratorConfig = DeepRequired<CommonGeneratorConfig & {
+export type FullGeneratorConfig = DeepRequired<Omit<CommonGeneratorConfig, 'metadataOverrides'> & {
     htmlConfig: HtmlGeneratorConfig;
     mdConfig: MdGeneratorConfig;
     pdfConfig: PdfGeneratorConfig;
@@ -614,6 +755,7 @@ export type FullGeneratorConfig = DeepRequired<CommonGeneratorConfig & {
     rtfConfig: RtfGeneratorConfig;
 }> & {
     chunksConfig: ChunkingConfig;
+    metadataOverrides: MetadataOverrides;
 };
 /**
  * Configuration options for granular raw HTML injections.
@@ -628,15 +770,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'.
@@ -811,12 +1002,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:
@@ -835,7 +1095,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.
@@ -848,11 +1115,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.
@@ -1057,11 +1337,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.
  */
@@ -1255,6 +1535,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).
@@ -1294,6 +1578,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.
@@ -1334,6 +1623,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.
@@ -1364,6 +1692,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).
@@ -1417,6 +1764,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.
@@ -1436,7 +1789,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.
@@ -1511,6 +1864,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.
@@ -1598,6 +1968,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.
@@ -1840,14 +2225,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, 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:
      *
-     * 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.
+     * ```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

package/dist/types.js

@@ -43,6 +43,8 @@ var OfficeErrorType;
     OfficeErrorType["ZIP_ENTRY_INVALID_SIZE"] = "ZIP_ENTRY_INVALID_SIZE";
     /** ZIP uncompressed size limit exceeded */
     OfficeErrorType["ZIP_SIZE_LIMIT_EXCEEDED"] = "ZIP_SIZE_LIMIT_EXCEEDED";
+    /** Document element/structure nesting exceeded the safe recursion depth */
+    OfficeErrorType["MAX_NESTING_DEPTH_EXCEEDED"] = "MAX_NESTING_DEPTH_EXCEEDED";
     /** Embedding call timed out */
     OfficeErrorType["EMBEDDING_TIMEOUT"] = "EMBEDDING_TIMEOUT";
 })(OfficeErrorType || (exports.OfficeErrorType = OfficeErrorType = {}));
@@ -86,4 +88,10 @@ var OfficeWarningType;
     OfficeWarningType["WHITESPACE_NODE_SKIPPED"] = "WHITESPACE_NODE_SKIPPED";
     /** The HTML generator containerWidth option is invalid */
     OfficeWarningType["INVALID_CONTAINER_WIDTH"] = "INVALID_CONTAINER_WIDTH";
+    /** A document's repeated-cell expansion hit the configured cell limit and was truncated */
+    OfficeWarningType["TABLE_CELL_LIMIT_EXCEEDED"] = "TABLE_CELL_LIMIT_EXCEEDED";
+    /** A metadata override could not be represented in the destination format's vocabulary */
+    OfficeWarningType["METADATA_NOT_REPRESENTABLE"] = "METADATA_NOT_REPRESENTABLE";
+    /** A styleMap output.tag was not an allowed element name and was ignored */
+    OfficeWarningType["INVALID_STYLE_MAP_TAG"] = "INVALID_STYLE_MAP_TAG";
 })(OfficeWarningType || (exports.OfficeWarningType = OfficeWarningType = {}));