officeparser 7.4.0 → 7.5.1

package/dist/utils/configUtils.js

@@ -83,19 +83,33 @@ function isFullParserConfig(config) {
 /**
  * Resolves a full parser configuration by merging defaults and user-provided overrides.
  *
+ * The returned object always belongs solely to the caller of this function. That matters
+ * because a parse installs per-call state on the config it is handed, such as the collector
+ * that gathers warnings for one document's `ast.warnings`. Returning the caller's own object
+ * would attach that state to an object they may reuse, so a second parse would append its
+ * warnings to the first document's already-returned AST, and each parse would retain the
+ * previous one's state for as long as the config lived.
+ *
+ * Only the configuration containers are copied. Callbacks and `abortSignal` keep their
+ * identity, since a copy of an `AbortSignal` would no longer be tied to its controller.
+ *
  * @param userConfig - Optional configuration provided by the user
- * @returns A fully populated configuration object
+ * @returns A fully populated configuration object, owned by the caller
  */
 function resolveParserConfig(userConfig) {
     if (isFullParserConfig(userConfig)) {
-        if (!userConfig.decompressionLimits) {
-            userConfig.decompressionLimits = {
-                maxUncompressedBytes: 512 * 1024 * 1024,
-                maxZipEntries: 10000,
-                maxTableCells: 1000000,
-            };
+        const resolved = { ...userConfig };
+        resolved.ocrConfig = { ...userConfig.ocrConfig };
+        if (userConfig.ocrConfig?.timeout) {
+            resolved.ocrConfig.timeout = { ...userConfig.ocrConfig.timeout };
+        }
+        resolved.decompressionLimits = {
+            ...(userConfig.decompressionLimits ?? defaults_js_1.DEFAULT_OFFICE_PARSER_CONFIG.decompressionLimits)
+        };
+        if (userConfig.htmlParserConfig) {
+            resolved.htmlParserConfig = { ...userConfig.htmlParserConfig };
         }
-        return userConfig;
+        return resolved;
     }
     // 1. Start with full defaults (deep cloned)
     const config = deepClone(defaults_js_1.DEFAULT_OFFICE_PARSER_CONFIG);
@@ -141,21 +155,52 @@ function resolveParserConfig(userConfig) {
     }
     return config;
 }
+/** The per-destination and metadata sub-objects a generator config groups its settings into. */
+const GENERATOR_CONFIG_CONTAINERS = [
+    'metadataOverrides', 'htmlConfig', 'mdConfig', 'pdfConfig',
+    'csvConfig', 'textConfig', 'rtfConfig', 'chunksConfig',
+];
+/**
+ * Copies a generator config's containers so writes during generation cannot reach the caller.
+ *
+ * One level is enough: the containers are what generation writes to. Everything else is copied
+ * by reference on purpose, since callbacks, `styleMap` and `abortSignal` are values whose
+ * identity matters, and a duplicated `AbortSignal` would no longer be tied to its controller.
+ *
+ * @param source - The caller's configuration
+ * @returns An equivalent configuration owned by us
+ */
+function copyGeneratorConfigContainers(source) {
+    const copy = { ...source };
+    for (const key of GENERATOR_CONFIG_CONTAINERS) {
+        const container = source[key];
+        if (container && typeof container === 'object')
+            copy[key] = { ...container };
+    }
+    return copy;
+}
 /**
  * Resolves a full, destination-specific configuration by merging defaults,
  * AST-level settings, and user-provided overrides.
  *
+ * As with {@link resolveParserConfig}, the returned object belongs solely to the caller of this
+ * function, so that per-run normalization cannot edit a config the caller still holds.
+ *
  * @param destination - The target format
  * @param userConfig - Optional configuration provided by the user
  * @param astConfig - Optional configuration from the source AST (for inheritance)
- * @returns A fully populated configuration object
+ * @returns A fully populated configuration object, owned by the caller
  */
 function resolveGeneratorConfig(destination, astConfig, userConfig) {
-    // If it's already a full config and we don't need to merge AST config, return it as is.
-    // We assume FullGeneratorConfig is already "safe" (references resolved).
+    // Already complete, so nothing to merge. Still copied rather than handed straight back, for
+    // the same reason as resolveParserConfig: generation writes to the config it is given. The
+    // width check below normalizes an invalid `containerWidth` to 'auto', and doing that to the
+    // caller's own object both edits a value they still hold and silences the warning on every
+    // later run, so the same config would report a problem once and then appear clean.
     if (isFullGeneratorConfig(userConfig) && !astConfig) {
-        validateHtmlConfigWidth(userConfig.htmlConfig, userConfig);
-        return userConfig;
+        const resolved = copyGeneratorConfigContainers(userConfig);
+        validateHtmlConfigWidth(resolved.htmlConfig, resolved);
+        return resolved;
     }
     // 1. Start with full defaults (deep cloned to avoid reference sharing)
     const config = deepClone(defaults_js_1.DEFAULT_GENERATOR_CONFIG);

package/dist/utils/errorUtils.d.ts

@@ -5,7 +5,7 @@
  * It defines standard error types, messages, and handling logic to ensure
  * consistent error reporting across all parsers and the main entry point.
  */
-import { OfficeErrorType, OfficeParserConfig, OfficeWarningType } from '../types.js';
+import { OfficeError, OfficeErrorType, OfficeParserConfig, OfficeWarningType } from '../types.js';
 /**
  * Creates a formatted warning message for a specific warning type.
  *
@@ -22,11 +22,17 @@ export declare const getWarningMessage: (type: OfficeWarningType, info?: any) =>
  * @param info - Optional additional information
  * @returns The Error object to be thrown
  */
-export declare const getOfficeError: (type: OfficeErrorType, config?: OfficeParserConfig, info?: any) => Error;
+export declare const getOfficeError: (type: OfficeErrorType, config?: OfficeParserConfig, info?: any) => OfficeError;
 /**
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * An error already built by {@link getOfficeError} is returned untouched: it carries an
+ * `officeIssue`, meaning it has been reported once and already bears the `[OfficeParser]: `
+ * header. Re-wrapping it would report the same issue a second time, prepend a second header,
+ * and flatten its specific error code to `FILE_CORRUPTED`. This is a marker check on the error
+ * object rather than a test against its message text, so it stays independent of wording.
+ *
  * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
  * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
  * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.

package/dist/utils/errorUtils.js

@@ -11,6 +11,11 @@ exports.checkAbortSignal = exports.getAbortError = exports.logWarning = exports.
 const types_js_1 = require("../types.js");
 /** Error header prefix for all error messages */
 const ERRORHEADER = "[OfficeParser]: ";
+// `OfficeError` (the public shape callers catch) lives in types.ts alongside `OfficeIssue`.
+// Every error built by getOfficeError is branded with its issue, which serves two purposes:
+// consumers branch on `err.officeIssue.code` instead of matching message text, and
+// getWrappedError recognizes an error it has already reported and prefixed, so it neither
+// reports it twice nor prepends a second header.
 /**
  * Lookup table for error messages.
  * Some entries are functions that take parameters to build dynamic messages.
@@ -34,6 +39,9 @@ const ERROR_MESSAGES = {
     [types_js_1.OfficeErrorType.ZIP_ENTRY_COUNT_LIMIT_EXCEEDED]: (limit) => `ZIP entry count exceeds limit (${limit})`,
     [types_js_1.OfficeErrorType.ZIP_ENTRY_INVALID_SIZE]: `ZIP entry missing a valid declared size`,
     [types_js_1.OfficeErrorType.ZIP_SIZE_LIMIT_EXCEEDED]: (limit) => `ZIP uncompressed size limit exceeded (${limit} bytes)`,
+    [types_js_1.OfficeErrorType.ZIP_NO_ENTRIES_FOUND]: `No readable entries found in ZIP data. The input is corrupt, truncated, or not a ZIP archive: every ZIP-based document format requires at least one entry.`,
+    [types_js_1.OfficeErrorType.ZIP_TRUNCATED]: `Malformed ZIP data: no End of Central Directory record was found at the end of the input. Either the file was cut off during download or transfer, or extra data follows the archive; in both cases the entries recovered from it cannot be trusted to be the whole document.`,
+    [types_js_1.OfficeErrorType.REQUIRED_PART_MISSING]: (info) => `Your ${info.fileType} file is a readable ZIP archive but is missing its required '${info.part}' part, so it cannot be a valid ${info.fileType} document. The file is corrupt, incomplete, or mislabeled. If you are sure it is fine, please create a ticket in Issues on github with the file to reproduce the error.`,
     [types_js_1.OfficeErrorType.MAX_NESTING_DEPTH_EXCEEDED]: `Document nesting depth exceeded the safe limit (possible denial-of-service input)`,
     [types_js_1.OfficeErrorType.EMBEDDING_TIMEOUT]: (timeout) => `Embedding call timed out after ${timeout}ms`
 };
@@ -60,6 +68,8 @@ const WARNING_MESSAGES = {
     [types_js_1.OfficeWarningType.TABLE_CELL_LIMIT_EXCEEDED]: (limit) => `Table cell limit (${limit}) reached while expanding repeated ODF cells/rows; the remaining cells were not materialized. A few hundred bytes of XML can request an unbounded number of cells via table:number-columns-repeated / table:number-rows-repeated, so this is capped. Raise decompressionLimits.maxTableCells if your documents legitimately exceed it.`,
     [types_js_1.OfficeWarningType.INVALID_CONTAINER_WIDTH]: (val) => `Invalid HTML containerWidth: ${JSON.stringify(val)}. Falling back to "auto". Width must be a positive number, a valid CSS length string (e.g., "900px", "100%", "50vw"), or "auto".`,
     [types_js_1.OfficeWarningType.METADATA_NOT_REPRESENTABLE]: (info) => `Custom metadata ${info.keys.map(k => `'${k}'`).join(', ')} could not be written to ${info.format} output: the format has a fixed metadata vocabulary with no place for caller-defined keys. The named metadata fields (title, author, etc.) were still applied.`,
+    [types_js_1.OfficeWarningType.NO_WORKSHEETS_FOUND]: `Workbook contains no worksheet parts (xl/worksheets/). If the workbook holds only chartsheets this is expected and there is simply no cell text to extract; otherwise the file may be incomplete.`,
+    [types_js_1.OfficeWarningType.NO_SLIDES_FOUND]: `Presentation contains no slides (ppt/slides/). A legitimately empty presentation produces this too, but if you expected content the file may be incomplete.`,
     [types_js_1.OfficeWarningType.INVALID_STYLE_MAP_TAG]: (tag) => `styleMap output.tag ${JSON.stringify(tag)} is not an allowed element name and was ignored; the node's default tag was used instead. A tag name is written into both the opening and closing tag, so only a known-safe set of block, heading and inline elements is accepted.`
 };
 /**
@@ -122,13 +132,23 @@ const getOfficeError = (type, config, info) => {
         details: info
     };
     reportIssue(issue, config);
-    return new Error(ERRORHEADER + message);
+    const error = new Error(ERRORHEADER + message);
+    // Brand the error with the issue that produced it so getWrappedError can tell an
+    // already-reported, already-prefixed OfficeParser error from a raw third-party one.
+    error.officeIssue = issue;
+    return error;
 };
 exports.getOfficeError = getOfficeError;
 /**
  * Wraps an existing error with OfficeParser context and performs corruption detection.
  * Optionally logs the error to console.
  *
+ * An error already built by {@link getOfficeError} is returned untouched: it carries an
+ * `officeIssue`, meaning it has been reported once and already bears the `[OfficeParser]: `
+ * header. Re-wrapping it would report the same issue a second time, prepend a second header,
+ * and flatten its specific error code to `FILE_CORRUPTED`. This is a marker check on the error
+ * object rather than a test against its message text, so it stays independent of wording.
+ *
  * **Important**: Do NOT pass AbortErrors to this function. AbortErrors (err.name === 'AbortError')
  * represent deliberate user cancellation and must be re-thrown as-is from the catch block so that
  * callers can reliably detect them via `err.name === 'AbortError'` or `err instanceof DOMException`.
@@ -140,6 +160,8 @@ exports.getOfficeError = getOfficeError;
  * @returns The wrapped Error object to be thrown
  */
 const getWrappedError = (error, config, filePath) => {
+    if (error?.officeIssue)
+        return error;
     let message = error.message || error;
     let code = types_js_1.OfficeErrorType.FILE_CORRUPTED; // Default for wrapped errors
     // Detect file corruption from common library error messages

package/dist/utils/mathUtils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Converts an OMML subtree (`<m:oMath>` or any node within one) to LaTeX.
+ *
+ * Covers the constructs that actually appear in office documents: fractions, sub/superscripts,
+ * delimiters, radicals, n-ary operators, functions, accents, bars, boxes and matrices. Anything
+ * unrecognized falls through to concatenating its children, which is the old behaviour and the
+ * right degradation for a construct that carries no grouping of its own.
+ */
+export declare const ommlToLatex: (node: Node, depth?: number) => string;
+/**
+ * The subset of a parsed element every MathML source here can present.
+ *
+ * MathML reaches this module from two different tree types - the XML DOM (ODF embedded objects)
+ * and `HtmlParser`'s own lightweight node (HTML, and EPUB via its spine items) - so the converter
+ * is written against this shape and each caller adapts into it. That keeps one implementation of
+ * the conversion rather than one per tree type, which is how HTML came to have no MathML support
+ * at all while ODF did.
+ */
+export interface MathNode {
+    /** Tag name, namespace prefix included or not; `undefined` marks a text node. */
+    tagName?: string;
+    attributes?: Record<string, string>;
+    /** Literal text, for text nodes and for leaf tokens. */
+    text?: string;
+    children: MathNode[];
+}
+/**
+ * Converts a MathML subtree to LaTeX.
+ *
+ * When the document carries a TeX annotation (`<annotation encoding="application/x-tex">`), that
+ * is the author's own source and is used verbatim in preference to anything reconstructed here.
+ * ODF's `<annotation encoding="StarMath 5.0">` is deliberately not used - StarMath is not LaTeX,
+ * and emitting it would put a second notation back into the output this module exists to unify.
+ */
+export declare const mathmlTreeToLatex: (node: MathNode, depth?: number) => string;
+/** Converts a MathML subtree held in an XML DOM (ODF embedded objects) to LaTeX. */
+export declare const mathmlToLatex: (node: Node, depth?: number) => string;
+/**
+ * True when a converted equation carries nothing worth emitting, so callers can drop the node
+ * instead of pushing an empty `$$` into the output.
+ */
+export declare const isEmptyMath: (latex: string) => boolean;

package/dist/utils/mathUtils.js

@@ -0,0 +1,385 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEmptyMath = exports.mathmlToLatex = exports.mathmlTreeToLatex = exports.ommlToLatex = void 0;
+const xmlUtils_js_1 = require("./xmlUtils.js");
+/**
+ * Equation markup normalization.
+ *
+ * Office documents ship equations in exactly two markups: OOXML's OMML (`<m:oMath>`, used by
+ * DOCX and PPTX) and MathML (`<math>`, used by ODF embedded objects, HTML, and EPUB3). Neither
+ * is plain text, and neither survives the generic "recurse into unknown elements and concatenate
+ * their text" fallback every parser ends with: `<m:num>1</m:num><m:den>2</m:den>` collapses to
+ * `12`, which still reads as a number, so nothing downstream can tell the value is wrong.
+ *
+ * Both markups are converted to LaTeX here rather than to a per-format ad hoc notation, because
+ * `MarkdownParser` already emits LaTeX for `$...$` / `$$...$$`. Converging on it means one
+ * representation reaches every generator, and a formula survives a docx -> md -> docx round trip
+ * instead of degrading at each hop.
+ *
+ * The output is always emitted as a `code` node carrying `CodeMetadata.math`, matching the
+ * contract `MarkdownParser` established - see `src/types.ts`.
+ */
+/**
+ * Depth cap for the recursive walks below. Equation markup nests (a fraction inside a
+ * superscript inside a fraction), and the nesting is attacker-controlled: a few hundred bytes of
+ * hand-written XML can carry thousands of levels. The walks are recursive, so an unbounded
+ * document would exhaust the stack rather than merely producing odd output. 64 is far past any
+ * real equation - the deepest construct in a typical maths paper is 3 or 4 levels.
+ */
+const MAX_MATH_DEPTH = 64;
+/** Marker substituted for a subtree that exceeded MAX_MATH_DEPTH, so truncation is never silent. */
+const TRUNCATED = '\\ldots';
+/**
+ * LaTeX metacharacters, escaped in any literal run of document text.
+ *
+ * The content of `<m:t>`, `<mi>`, `<mn>` and friends is literal characters, never LaTeX source -
+ * an author who types `%` into an equation means a percent sign, not a comment. Escaping is
+ * therefore lossless, and it also stops document text from injecting control sequences into the
+ * `$...$` span it lands in. Backslash must be replaced first or it would re-escape the
+ * backslashes introduced by the later replacements.
+ */
+const escapeLatex = (text) => text.replace(/\\/g, '\\textbackslash{}')
+    .replace(/([&%$#_{}])/g, '\\$1')
+    .replace(/~/g, '\\textasciitilde{}')
+    .replace(/\^/g, '\\textasciicircum{}');
+/**
+ * Wraps an expression in braces unless it is already a single token.
+ *
+ * `x^{2}` and `x^2` render identically, but `x^{2y}` and `x^2y` do not, so the braces cannot be
+ * dropped whenever the argument is longer than one character. A lone digit or letter is the only
+ * safe case, and it is by far the most common one, so special-casing it keeps ordinary output
+ * readable without risking a mis-grouped exponent.
+ */
+const group = (latex) => /^[0-9a-zA-Z]$/.test(latex) ? latex : `{${latex}}`;
+/** Strips any namespace prefix: `m:oMath` -> `omath`, `mml:mfrac` -> `mfrac`. */
+const localName = (element) => element.tagName.toLowerCase().replace(/^.*:/, '');
+/** Element children only, in document order. */
+const elementChildren = (element) => {
+    const result = [];
+    for (let i = 0; i < (element.childNodes?.length ?? 0); i++) {
+        const child = element.childNodes[i];
+        if ((0, xmlUtils_js_1.isElement)(child))
+            result.push(child);
+    }
+    return result;
+};
+// ─── OMML (OOXML: DOCX, PPTX) ────────────────────────────────────────────────
+/**
+ * Property elements. These carry styling (`m:ctrlPr` even wraps a full `w:rPr`) and never
+ * contribute display text, so they must be skipped rather than descended into - the generic
+ * fallback descending into them is one of the ways stray formatting text reached the output.
+ */
+const OMML_PROPERTY_TAGS = new Set([
+    'fpr', 'rpr', 'ctrlpr', 'ssubpr', 'ssuppr', 'ssubsuppr', 'dpr', 'radpr', 'narypr',
+    'funcpr', 'limlowpr', 'limupppr', 'mpr', 'argpr', 'barpr', 'accpr', 'grouppr',
+    'phantpr', 'boxpr', 'eqarrpr', 'spre', 'sty', 'scr', 'brk', 'aln', 'nor',
+]);
+/**
+ * `m:scr` math alphabets. OOXML encodes `ℝ` as an ASCII `R` plus a script attribute rather than
+ * as the Unicode character ODF uses, so these carry meaning and not merely styling.
+ */
+const OMML_MATH_ALPHABETS = {
+    'double-struck': '\\mathbb',
+    'script': '\\mathcal',
+    'fraktur': '\\mathfrak',
+    'monospace': '\\mathtt',
+    'sans-serif': '\\mathsf',
+    'roman': '\\mathrm',
+};
+/** Named OMML functions that map onto a LaTeX command of the same meaning. */
+const OMML_NARY_OPERATORS = {
+    '∑': '\\sum', '∏': '\\prod', '∫': '\\int', '∬': '\\iint', '∭': '\\iiint',
+    '∮': '\\oint', '⋃': '\\bigcup', '⋂': '\\bigcap', '⋀': '\\bigwedge', '⋁': '\\bigvee',
+};
+/**
+ * Converts an OMML subtree (`<m:oMath>` or any node within one) to LaTeX.
+ *
+ * Covers the constructs that actually appear in office documents: fractions, sub/superscripts,
+ * delimiters, radicals, n-ary operators, functions, accents, bars, boxes and matrices. Anything
+ * unrecognized falls through to concatenating its children, which is the old behaviour and the
+ * right degradation for a construct that carries no grouping of its own.
+ */
+const ommlToLatex = (node, depth = 0) => {
+    if (!node)
+        return '';
+    if (node.nodeType === 3)
+        return escapeLatex(node.textContent || '');
+    if (!(0, xmlUtils_js_1.isElement)(node))
+        return '';
+    if (depth > MAX_MATH_DEPTH)
+        return TRUNCATED;
+    const element = node;
+    const tag = localName(element);
+    if (OMML_PROPERTY_TAGS.has(tag))
+        return '';
+    const kids = elementChildren(element);
+    /** Concatenates every child, used for containers and for unrecognized constructs. */
+    const all = () => kids.map(k => (0, exports.ommlToLatex)(k, depth + 1)).join('');
+    /** The LaTeX for the first `<m:xxx>` child with the given local name, or '' when absent. */
+    const part = (name) => {
+        const found = kids.find(k => localName(k) === name);
+        return found ? (0, exports.ommlToLatex)(found, depth + 1) : '';
+    };
+    switch (tag) {
+        case 'r': {
+            // A run may carry a math alphabet on its own `m:rPr` - `ℝ` is written as a plain `R`
+            // with `<m:scr m:val="double-struck"/>`, so dropping the property loses the meaning
+            // of the symbol, not just its look. Both `m:rPr` and `w:rPr` reduce to the same local
+            // name, so select on content rather than on the prefix.
+            const body = all();
+            const rPr = kids.find(k => localName(k) === 'rpr'
+                && elementChildren(k).some(p => localName(p) === 'scr' || localName(p) === 'sty'));
+            if (!rPr || !body)
+                return body;
+            const valueOf = (name) => {
+                const el = elementChildren(rPr).find(p => localName(p) === name);
+                return el?.getAttribute('m:val') ?? el?.getAttribute('val') ?? '';
+            };
+            const alphabet = OMML_MATH_ALPHABETS[valueOf('scr')]
+                ?? (valueOf('sty') === 'b' ? '\\mathbf' : undefined);
+            return alphabet ? `${alphabet}${group(body)}` : body;
+        }
+        // Containers: an equation, an argument, a base.
+        case 'omath':
+        case 'omathpara':
+        case 'e':
+        case 'num':
+        case 'den':
+        case 'sub':
+        case 'sup':
+        case 'lim':
+        case 'fname':
+            return all();
+        case 't':
+            return escapeLatex(element.textContent || '');
+        case 'f': {
+            // `m:type val="lin"` asks for an inline `a/b` rather than a stacked fraction.
+            const fPr = kids.find(k => localName(k) === 'fpr');
+            const typeEl = fPr ? elementChildren(fPr).find(k => localName(k) === 'type') : undefined;
+            const linear = typeEl?.getAttribute('m:val') === 'lin' || typeEl?.getAttribute('val') === 'lin';
+            const num = part('num');
+            const den = part('den');
+            return linear ? `${group(num)}/${group(den)}` : `\\frac${group(num)}${group(den)}`;
+        }
+        case 'ssup':
+            return `${group(part('e'))}^${group(part('sup'))}`;
+        case 'ssub':
+            return `${group(part('e'))}_${group(part('sub'))}`;
+        case 'ssubsup':
+            return `${group(part('e'))}_${group(part('sub'))}^${group(part('sup'))}`;
+        case 'spre':
+            // Pre-sub/superscript: the scripts precede the base.
+            return `{}_${group(part('sub'))}^${group(part('sup'))}${group(part('e'))}`;
+        case 'd': {
+            // Delimiters. The characters are document-supplied and default to parentheses.
+            // Plain delimiters rather than \left...\right: an unbalanced \left would break the
+            // whole expression, and a document can legitimately open without closing.
+            const dPr = kids.find(k => localName(k) === 'dpr');
+            const chr = (name, fallback) => {
+                const el = dPr ? elementChildren(dPr).find(k => localName(k) === name) : undefined;
+                const raw = el?.getAttribute('m:val') ?? el?.getAttribute('val');
+                return raw ? escapeLatex(raw) : fallback;
+            };
+            const beg = chr('begchr', '(');
+            const end = chr('endchr', ')');
+            const sep = chr('sepchr', ',');
+            const args = kids.filter(k => localName(k) === 'e').map(k => (0, exports.ommlToLatex)(k, depth + 1));
+            return `${beg}${args.join(sep)}${end}`;
+        }
+        case 'rad': {
+            const deg = part('deg');
+            const base = group(part('e'));
+            return deg ? `\\sqrt[${deg}]${base}` : `\\sqrt${base}`;
+        }
+        case 'nary': {
+            // Summation/integral and friends: operator, optional bounds, then the operand.
+            const naryPr = kids.find(k => localName(k) === 'narypr');
+            const chrEl = naryPr ? elementChildren(naryPr).find(k => localName(k) === 'chr') : undefined;
+            const chr = chrEl?.getAttribute('m:val') ?? chrEl?.getAttribute('val') ?? '∫';
+            const op = OMML_NARY_OPERATORS[chr] ?? escapeLatex(chr);
+            const sub = part('sub');
+            const sup = part('sup');
+            return `${op}${sub ? `_${group(sub)}` : ''}${sup ? `^${group(sup)}` : ''}${part('e')}`;
+        }
+        case 'func':
+            // `sin`, `log`, ... - the name is document text, so it cannot become a bare command.
+            return `\\operatorname${group(part('fname'))}${group(part('e'))}`;
+        case 'limlow':
+            return `${part('e')}_${group(part('lim'))}`;
+        case 'limupp':
+            return `${part('e')}^${group(part('lim'))}`;
+        case 'bar': {
+            const barPr = kids.find(k => localName(k) === 'barpr');
+            const posEl = barPr ? elementChildren(barPr).find(k => localName(k) === 'pos') : undefined;
+            const pos = posEl?.getAttribute('m:val') ?? posEl?.getAttribute('val');
+            return `${pos === 'top' ? '\\overline' : '\\underline'}${group(part('e'))}`;
+        }
+        case 'acc': {
+            const accPr = kids.find(k => localName(k) === 'accpr');
+            const chrEl = accPr ? elementChildren(accPr).find(k => localName(k) === 'chr') : undefined;
+            const chr = chrEl?.getAttribute('m:val') ?? chrEl?.getAttribute('val') ?? '̂';
+            const command = chr === '̄' ? '\\bar' : chr === '⃗' ? '\\vec' : chr === '̇' ? '\\dot' : '\\hat';
+            return `${command}${group(part('e'))}`;
+        }
+        case 'box':
+        case 'borderbox':
+        case 'phant':
+        case 'group':
+        case 'groupchr':
+            return part('e') || all();
+        case 'm': {
+            // Matrix: rows of cells. `\begin{matrix}` carries no delimiters of its own, which is
+            // correct - a bracketed matrix wraps the `m:m` in an `m:d` that supplies them.
+            const rows = kids.filter(k => localName(k) === 'mr').map(row => elementChildren(row)
+                .filter(cell => localName(cell) === 'e')
+                .map(cell => (0, exports.ommlToLatex)(cell, depth + 1))
+                .join(' & '));
+            return `\\begin{matrix}${rows.join(' \\\\ ')}\\end{matrix}`;
+        }
+        default:
+            return all();
+    }
+};
+exports.ommlToLatex = ommlToLatex;
+// ─── MathML (ODF embedded objects, HTML, EPUB3) ──────────────────────────────
+/** MathML operators that have a dedicated LaTeX command. */
+const MATHML_OPERATORS = {
+    '∑': '\\sum', '∏': '\\prod', '∫': '\\int', '∮': '\\oint', '√': '\\sqrt',
+    '±': '\\pm', '∓': '\\mp', '×': '\\times', '÷': '\\div', '⋅': '\\cdot',
+    '≤': '\\leq', '≥': '\\geq', '≠': '\\neq', '≈': '\\approx', '≡': '\\equiv',
+    '∈': '\\in', '∉': '\\notin', '⊂': '\\subset', '⊆': '\\subseteq', '∪': '\\cup',
+    '∩': '\\cap', '∞': '\\infty', '→': '\\to', '⇒': '\\Rightarrow', '⇔': '\\Leftrightarrow',
+    '∀': '\\forall', '∃': '\\exists', '∂': '\\partial', '∇': '\\nabla', '…': '\\ldots',
+    'ℝ': '\\mathbb{R}', 'ℕ': '\\mathbb{N}', 'ℤ': '\\mathbb{Z}', 'ℚ': '\\mathbb{Q}', 'ℂ': '\\mathbb{C}',
+};
+/** Maps a literal run through the operator table, falling back to plain escaped text. */
+const mathmlToken = (raw) => {
+    const trimmed = raw.trim();
+    return MATHML_OPERATORS[trimmed] ?? escapeLatex(raw);
+};
+/** Local name of a MathNode: `mml:mfrac` -> `mfrac`, `undefined` for a text node. */
+const mathNodeName = (node) => (node.tagName || '').toLowerCase().replace(/^.*:/, '');
+/** Presents an XML DOM node through the MathNode shape. */
+const fromDom = (node) => {
+    if (node.nodeType === 3 || !(0, xmlUtils_js_1.isElement)(node)) {
+        return { text: node.textContent || '', children: [] };
+    }
+    const element = node;
+    const attributes = {};
+    for (let i = 0; i < (element.attributes?.length ?? 0); i++) {
+        const attr = element.attributes[i];
+        attributes[attr.name] = attr.value;
+    }
+    return {
+        tagName: element.tagName,
+        attributes,
+        text: element.textContent || '',
+        children: elementChildren(element).map(fromDom),
+    };
+};
+/**
+ * Converts a MathML subtree to LaTeX.
+ *
+ * When the document carries a TeX annotation (`<annotation encoding="application/x-tex">`), that
+ * is the author's own source and is used verbatim in preference to anything reconstructed here.
+ * ODF's `<annotation encoding="StarMath 5.0">` is deliberately not used - StarMath is not LaTeX,
+ * and emitting it would put a second notation back into the output this module exists to unify.
+ */
+const mathmlTreeToLatex = (node, depth = 0) => {
+    if (!node)
+        return '';
+    if (!node.tagName)
+        return mathmlToken(node.text || '');
+    if (depth > MAX_MATH_DEPTH)
+        return TRUNCATED;
+    const tag = mathNodeName(node);
+    const kids = node.children ?? [];
+    /**
+     * The literal content of a leaf token. The DOM adapter fills `text` with `textContent`, but
+     * `HtmlParser` keeps an element's text in child text nodes and leaves `text` unset, so fall
+     * back to gathering the children rather than emitting an empty token.
+     */
+    const tokenText = () => node.text || kids.map(k => k.text || '').join('');
+    const all = () => kids.map(k => (0, exports.mathmlTreeToLatex)(k, depth + 1)).join('');
+    const arg = (index) => (kids[index] ? (0, exports.mathmlTreeToLatex)(kids[index], depth + 1) : '');
+    switch (tag) {
+        case 'math':
+        case 'semantics': {
+            const tex = kids.find(k => mathNodeName(k) === 'annotation'
+                && /tex/i.test(k.attributes?.['encoding'] || ''));
+            // Same reason `tokenText` exists below: an element's text is in `text` for the DOM
+            // adapter and in child text nodes for `HtmlParser`, so both have to be consulted.
+            if (tex)
+                return (tex.text || (tex.children ?? []).map(c => c.text || '').join('')).trim();
+            return kids.map(k => (0, exports.mathmlTreeToLatex)(k, depth + 1)).join('');
+        }
+        case 'mrow':
+        case 'mstyle':
+        case 'mpadded':
+        case 'mphantom':
+            return all();
+        case 'mi':
+        case 'mn':
+        case 'mo':
+        case 'mtext':
+        case 'ms':
+            return mathmlToken(tokenText());
+        case 'mfrac':
+            return `\\frac${group(arg(0))}${group(arg(1))}`;
+        case 'msup':
+            return `${group(arg(0))}^${group(arg(1))}`;
+        case 'msub':
+            return `${group(arg(0))}_${group(arg(1))}`;
+        case 'msubsup':
+            return `${group(arg(0))}_${group(arg(1))}^${group(arg(2))}`;
+        case 'munder':
+            return `\\underset${group(arg(1))}${group(arg(0))}`;
+        case 'mover':
+            return `\\overset${group(arg(1))}${group(arg(0))}`;
+        case 'munderover':
+            return `${group(arg(0))}_${group(arg(1))}^${group(arg(2))}`;
+        case 'msqrt':
+            return `\\sqrt${group(all())}`;
+        case 'mroot':
+            return `\\sqrt[${arg(1)}]${group(arg(0))}`;
+        case 'mfenced': {
+            // Deprecated in MathML 3 but still emitted by older producers.
+            const open = escapeLatex(node.attributes?.['open'] ?? '(');
+            const close = escapeLatex(node.attributes?.['close'] ?? ')');
+            const sep = escapeLatex(node.attributes?.['separators'] ?? ',');
+            return `${open}${kids.map(k => (0, exports.mathmlTreeToLatex)(k, depth + 1)).join(sep)}${close}`;
+        }
+        case 'mtable':
+            return `\\begin{matrix}${kids
+                .filter(k => mathNodeName(k) === 'mtr')
+                .map(row => (row.children ?? [])
+                .filter(cell => mathNodeName(cell) === 'mtd')
+                .map(cell => (0, exports.mathmlTreeToLatex)(cell, depth + 1))
+                .join(' & '))
+                .join(' \\\\ ')}\\end{matrix}`;
+        case 'mtr':
+        case 'mtd':
+            return all();
+        case 'mspace':
+            return ' ';
+        // Presentation-only wrappers and the annotations themselves carry nothing renderable:
+        // `annotation-xml` duplicates the presentation tree in Content MathML, and emitting both
+        // would double every formula that has one.
+        case 'annotation':
+        case 'annotation-xml':
+        case 'maction':
+            return '';
+        default:
+            return all();
+    }
+};
+exports.mathmlTreeToLatex = mathmlTreeToLatex;
+/** Converts a MathML subtree held in an XML DOM (ODF embedded objects) to LaTeX. */
+const mathmlToLatex = (node, depth = 0) => (0, exports.mathmlTreeToLatex)(fromDom(node), depth);
+exports.mathmlToLatex = mathmlToLatex;
+/**
+ * True when a converted equation carries nothing worth emitting, so callers can drop the node
+ * instead of pushing an empty `$$` into the output.
+ */
+const isEmptyMath = (latex) => latex.trim().length === 0;
+exports.isEmptyMath = isEmptyMath;