officeparser 7.5.1 → 7.6.2

package/README.md

@@ -188,9 +188,9 @@ officeParser.parseOffice('/path/to/file.docx', function(ast, err) {
 });
 ```
 
-### File Buffers & ArrayBuffers
+### File Buffers, ArrayBuffers & Blobs
 
-Pass a `Buffer`, `ArrayBuffer`, or `Uint8Array` instead of a file path:
+Pass a `Buffer`, `ArrayBuffer`, `Uint8Array`, or a web `Blob`/`File` instead of a file path:
 
 ```js
 const fs = require('fs');
@@ -198,6 +198,15 @@ const buffer = fs.readFileSync('/path/to/file.pdf');
 const ast = await officeParser.parseOffice(buffer);
 ```
 
+In the browser you can hand a `File`/`Blob` straight from an `<input type="file">` — no need to
+read it into a buffer first. A `File`'s name drives type detection, so no `fileType` hint is
+needed when the name has a recognizable extension:
+
+```js
+// input.files[0] is a File (e.g. "report.docx")
+const ast = await officeParser.parseOffice(input.files[0]);
+```
+
 > [!IMPORTANT]
 > **Text-based formats from buffers need a `fileType` hint.**
 > Formats like `md`, `html`, and `csv` have no magic bytes, so the parser cannot
@@ -475,6 +484,8 @@ const { value: chunks } = await OfficeConverter.convert('report.docx', 'chunks',
 
 ### The `OfficeChunk` Object
 
+`generate(ast, 'chunks')` (and `ast.to('chunks')`) resolves to a real `OfficeChunk[]` **array**, not a JSON string - serialize it to JSON/JSONL yourself if your pipeline needs that.
+
 Every chunk contains text and rich metadata for citations and filtered retrieval:
 
 ```ts
@@ -738,7 +749,7 @@ Admonition Node (type: 'admonition')
 └── children: [ Paragraph | List | ... ]   (block content)
 
 Embed Node (type: 'embed')
-└── metadata: { embedType: 'youtube', videoId: string, url?: string, width?: string, align?: string }
+└── metadata: { embedType: 'youtube' | 'iframe', videoId?: string, url?: string, width?: string, height?: string, align?: string }
 
 Definition List Node (type: 'definitionList')
 └── children:
@@ -973,7 +984,8 @@ Pass as the second argument to `parseOffice(file, config)`.
 | `ignoreInternalLinks` | `boolean` | `false` | Strip bookmarks and internal cross-references from AST |
 | `fileType` | `SupportedFileType \| null` | `null` | **Required for text-based binary data** (`'md'`, `'html'`, `'csv'`) as these lack magic bytes. |
 | `csvDelimiter` | `string` | `','` | Input delimiter when parsing CSV files |
-| `decompressionLimits` | `DecompressionLimits` | `{ maxUncompressedBytes: 512MB, maxZipEntries: 10000 }` | **New**: Limits applied during ZIP extraction to protect against excessive memory and resource usage |
+| `decompressionLimits` | `DecompressionLimits` | `{ maxUncompressedBytes: 512MB, maxZipEntries: 10000, maxTableCells: 1000000 }` | **New**: Limits applied during ZIP extraction (and ODF cell expansion) to protect against excessive memory and resource usage |
+| `htmlParserConfig` | `HtmlParserConfig` | `{}` | HTML/XHTML/EPUB parsing options. `preserveAttributes` (`boolean`, default `false`): keep generic source attributes no typed field consumed on `node.htmlAttributes`. `preserveIframes` (`boolean \| string[]`, default `false`): preserve non-YouTube `<iframe>` embeds (otherwise dropped) as `embed` nodes — `true` for any, or a hostname allowlist; the src is scheme-checked on generation |
 | `pdfWorkerSrc` | `string` | CDN (jsDelivr) | Path/URL to `pdf.worker.min.mjs` (required in browser) |
 | `onWarning` | `(issue: OfficeIssue) => void` | — | Callback for non-fatal parsing issues |
 | `abortSignal` | `AbortSignal \| null` | `null` | Optional signal to cancel parsing (rejects with AbortError) |
@@ -988,7 +1000,7 @@ Options shared by all generator formats. Pass to `OfficeGenerator.generate(ast,
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `includeFormatting` | `boolean` | `true` | Include bold/italic/colors/sizes in output |
-| `generateIds` | `boolean` | `true` | Add slug-based `id` attributes to headings |
+| `generateIds` | `boolean` | `true` | Slug-based heading anchors: `id` attributes on HTML headings, and a `{#slug}` suffix on Markdown headings (`# Title {#title}`, kramdown/Pandoc). Set `false` to omit both — useful when the Markdown is rendered by GFM/CommonMark, which show `{#slug}` as literal text. Applies to all generator formats (it is a top-level option, not under `mdConfig`/`htmlConfig`). |
 | `renderMetadata` | `boolean` | `false` | Render title/author as visible header block |
 | `metadataOverrides` | `MetadataOverrides` | `{}` | Override the metadata embedded in the output, merged per field over `ast.metadata` |
 | `includeImages` | `boolean` | `true` | Include image nodes in output |
@@ -1083,6 +1095,7 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 | `injections.headEnd` | `string` | `''` | Raw HTML injected before `</head>` |
 | `injections.bodyStart` | `string` | `''` | Raw HTML injected after `<body>` |
 | `injections.bodyEnd` | `string` | `''` | Raw HTML injected before `</body>` |
+| `sourceAttributes` | `boolean` | `false` | Carry each rich node's raw source in a `data-*` attribute (undelimited text), so attribute-driven consumers can rehydrate it: `data-wikilink`/`data-target`/`data-alias` on wikilinks, a `<span class="citation" data-key>` for citations, the LaTeX in `data-math`, and a `<div class="mermaid" data-mermaid>` for mermaid. Off = byte-identical to before; the parser reads every shape it emits. Forced off for PDF/EPUB |
 
 #### `standalone`: granular envelope control
 
@@ -1133,7 +1146,7 @@ Pass as `mdConfig` inside `GeneratorConfig`.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `fallbackToHtml` | `boolean` | `true` | Use HTML tags for features Markdown cannot represent (underlines, merged table cells, etc.) |
+| `fallbackToHtml` | `boolean \| FallbackToHtmlConfig` | `true` | Use HTML tags for features Markdown cannot represent (underlines, merged table cells, embeds, etc.). Pass an object for per-feature control. `inlineFormatting` (default `false`, opt-in even when the boolean is `true`) additionally round-trips inline color/highlight/font-size as `<span style="...">` runs. |
 
 ### PdfGeneratorConfig
 

package/dist/OfficeConverter.d.ts

@@ -1,4 +1,4 @@
-import { ConversionResult, OfficeConverterConfig, SupportedDestination, SupportedFileType } from './types.js';
+import { BlobLike, ConversionResult, OfficeConverterConfig, SupportedDestination, SupportedFileType } from './types.js';
 /**
  * Utility type to infer the file type from a file path string literal.
  */
@@ -42,6 +42,6 @@ export declare class OfficeConverter {
      * });
      * ```
      */
-    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>>;
+    static convert<F extends string | Buffer | ArrayBuffer | Uint8Array | BlobLike, T extends SupportedFileType = InferFileTypeFromPath<F>, D extends SupportedDestination<T> = SupportedDestination<T>>(file: F, destination: D, config?: OfficeConverterConfig<D, T>): Promise<ConversionResult<D>>;
 }
 export {};

package/dist/OfficeParser.d.ts

@@ -36,7 +36,7 @@
  *
  * @module OfficeParser
  */
-import { OfficeParserAST, OfficeParserConfig } from './types.js';
+import { BlobLike, OfficeParserAST, OfficeParserConfig } from './types.js';
 /**
  * Main parser class providing office document parsing functionality.
  *
@@ -93,7 +93,7 @@ export declare class OfficeParser {
      * const text = ast.toText();
      * ```
      */
-    static parseOffice(file: string | Buffer | ArrayBuffer | Uint8Array, configOrCallback?: OfficeParserConfig | ((ast: OfficeParserAST, err?: any) => void), config?: OfficeParserConfig): Promise<OfficeParserAST>;
+    static parseOffice(file: string | Buffer | ArrayBuffer | Uint8Array | BlobLike, configOrCallback?: OfficeParserConfig | ((ast: OfficeParserAST, err?: any) => void), config?: OfficeParserConfig): Promise<OfficeParserAST>;
     /**
      * Terminates all active OCR workers and cleans up resources.
      *

package/dist/OfficeParser.js

@@ -187,6 +187,16 @@ class OfficeParser {
                 buffer = fs.readFileSync(file);
                 ext = ext || file.split('.').pop() || '';
             }
+            else if (file && typeof file.arrayBuffer === 'function') {
+                // Web Blob/File (or any BlobLike). Read its bytes; if it carries a filename, use
+                // the extension for type detection - never as a filesystem path. A nameless blob
+                // still resolves through the magic-byte sniffing below.
+                buffer = Buffer.from(await file.arrayBuffer());
+                const name = file.name;
+                if (!ext && typeof name === 'string' && name.includes('.')) {
+                    ext = name.split('.').pop() || '';
+                }
+            }
             else {
                 throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.INVALID_INPUT, internalConfig);
             }

package/dist/cli.js

@@ -351,17 +351,20 @@ else {
     console.log('  --verbose                                   Show full error stack traces and warning logs');
     console.log('  --newlineDelimiter=string                   Delimiter string between blocks/lines (default: \\n)');
     console.log('  --csvDelimiter=char                         Custom CSV delimiter (default: ,)');
+    console.log('  --htmlParserConfig.preserveIframes          Keep non-YouTube <iframe> embeds (dropped by default)');
     console.log('');
     console.log('High-Value Generator Options:');
     console.log('  --includeFormatting                         Include font formatting like bold/italic (default: true)');
     console.log('  --renderMetadata                            Render metadata in output content (default: false)');
     console.log('  --htmlConfig.containerWidth=value           HTML container width (auto | px | % | vw etc., default: auto)');
+    console.log('  --htmlConfig.sourceAttributes               Carry each rich node\'s source in a data-* attribute (default: false)');
     console.log('');
     console.log('Advanced Nested Config Examples:');
     console.log('  --pdfConfig.format=Letter                   Configure Puppeteer PDF format (A4 | Letter | Legal etc.)');
     console.log('  --chunksConfig.strategy=fixed-size          Chunking strategy (fixed-size | document-structure | semantic)');
     console.log('  --mdConfig.dialect=github                   Markdown dialect (extended | github | gitlab | obsidian | pandoc | commonmark)');
     console.log('  --mdConfig.fallbackToHtml=false              Disable HTML fallback for unsupported Markdown features (default: true)');
+    console.log('  --mdConfig.fallbackToHtml.inlineFormatting   Round-trip inline color/highlight/font-size as <span style> (opt-in, default: false)');
     console.log('');
     console.log('Format Syntax:');
     console.log('  Flags can be written as --flag (presence implies true), --no-flag (negation),');

package/dist/defaults.js

@@ -40,6 +40,7 @@ const DEFAULT_OCR_CONFIG = {
  */
 const DEFAULT_HTML_PARSER_CONFIG = {
     preserveAttributes: false,
+    preserveIframes: false,
 };
 /**
  * Default configuration for the OfficeParser.
@@ -86,7 +87,8 @@ const DEFAULT_HTML_GENERATOR_CONFIG = {
         headEnd: '',
         bodyStart: '',
         bodyEnd: '',
-    }
+    },
+    sourceAttributes: false,
 };
 /**
  * Default configuration for PDF generation.

package/dist/generators/ChunkingGenerator.d.ts

@@ -16,7 +16,8 @@ export declare class ChunkingGenerator extends BaseGenerator<'chunks'> {
     private resolveChunkingConfig;
     /**
      * Main entry point. Routes to the correct strategy implementation.
-     * Note: ConversionResult.value is a JSON string of OfficeChunk[] for the 'chunks' destination.
+     * Note: ConversionResult.value is a real OfficeChunk[] array for the 'chunks' destination, not
+     * a JSON string. Consumers serialize it to JSON/JSONL themselves.
      */
     generate(): Promise<ConversionResult<'chunks'>>;
     /**

package/dist/generators/ChunkingGenerator.js

@@ -5,6 +5,72 @@ const defaults_js_1 = require("../defaults.js");
 const types_js_1 = require("../types.js");
 const errorUtils_js_1 = require("../utils/errorUtils.js");
 const BaseGenerator_js_1 = require("./BaseGenerator.js");
+/** Node types whose text is block-level, so a boundary between two of them is a real break. */
+const BLOCK_NODE_TYPES = new Set([
+    'paragraph', 'heading', 'list', 'table', 'row', 'cell', 'code', 'note', 'admonition',
+    'definitionList', 'definitionTerm', 'definitionDescription', 'sheet', 'slide', 'page', 'embed',
+]);
+/**
+ * The visible text of a content node: its own `.text` when set, otherwise its descendants' text,
+ * plus any footnote/endnote bodies hanging off `node.notes`.
+ * HTML- and Markdown-origin parsers build paragraphs as `{ children: [...] }` with no `.text`, so
+ * reading `node.text` alone dropped their content from every chunk. Block-level children are joined
+ * with a newline so words don't merge across paragraphs/list items (matching the text generator);
+ * inline runs join with no separator. Notes live on `node.notes`, off the children tree, and a
+ * content node is emitted as a chunk without recursing into them - so their text was silently
+ * absent from the RAG index. Fold them in here (joined as block content) so a footnote's body is
+ * searchable alongside the paragraph that references it.
+ */
+function collectNodeText(node) {
+    let out = '';
+    if (typeof node.text === 'string' && node.text.length > 0) {
+        out = node.text;
+        // The `.text` fast-path above skips the children walk, but DOCX/ODT/RTF set `.text` on the
+        // paragraph while the footnote hangs off a nested text child - so its body would be missed.
+        // Fold in descendant note bodies (visible text already covered by `.text`, not re-added).
+        const descendantNotes = collectDescendantNoteText(node);
+        if (descendantNotes)
+            out += '\n' + descendantNotes;
+    }
+    else if (node.children && node.children.length > 0) {
+        for (const child of node.children) {
+            if (out && BLOCK_NODE_TYPES.has(child.type))
+                out += '\n';
+            out += collectNodeText(child);
+        }
+    }
+    if (node.notes && node.notes.length > 0) {
+        for (const note of node.notes) {
+            const noteText = collectNodeText(note);
+            if (noteText)
+                out += (out ? '\n' : '') + noteText;
+        }
+    }
+    return out;
+}
+/**
+ * Footnote/endnote bodies hanging off a node's descendants, without the descendants' own visible
+ * text (the caller already has that via `.text`). Only reached from the `.text` fast-path above, to
+ * recover notes that office-origin parsers attach to a nested text child of a `.text`-bearing node.
+ */
+function collectDescendantNoteText(node) {
+    if (!node.children || node.children.length === 0)
+        return '';
+    let out = '';
+    for (const child of node.children) {
+        if (child.notes) {
+            for (const note of child.notes) {
+                const t = collectNodeText(note);
+                if (t)
+                    out += (out ? '\n' : '') + t;
+            }
+        }
+        const deeper = collectDescendantNoteText(child);
+        if (deeper)
+            out += (out ? '\n' : '') + deeper;
+    }
+    return out;
+}
 /**
  * Generates a list of OfficeChunk objects from an AST for use in RAG pipelines.
  * Supports three strategies: 'fixed-size', 'document-structure', and 'semantic'.
@@ -36,7 +102,8 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
     }
     /**
      * Main entry point. Routes to the correct strategy implementation.
-     * Note: ConversionResult.value is a JSON string of OfficeChunk[] for the 'chunks' destination.
+     * Note: ConversionResult.value is a real OfficeChunk[] array for the 'chunks' destination, not
+     * a JSON string. Consumers serialize it to JSON/JSONL themselves.
      */
     async generate() {
         (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
@@ -241,7 +308,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
         }
         const isContentNode = node.type === 'paragraph' || node.type === 'heading' || node.type === 'list' || node.type === 'code' || node.type === 'cell' || (node.text && (!node.children || node.children.length === 0));
         if (isStructuralBoundary || isContentNode) {
-            const text = typeof override === 'string' ? override : (node.text ?? '');
+            const text = typeof override === 'string' ? override : collectNodeText(node);
             const isWhitespaceOnly = !text.trim() && !text.includes('\u00A0');
             if (isWhitespaceOnly && text.length > 0) {
                 // Log skipped empty nodes if debugging
@@ -302,8 +369,8 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
     async processTableNode(node, config, maxChunkSize, measure, chunks, contextStack) {
         const strategy = config.tableSplitStrategy;
         if (strategy === 'flatten' || !node.children || node.children.length === 0) {
-            // Flatten: treat as plain text
-            const text = node.text ?? '';
+            // Flatten: treat as plain text (collect from children for HTML/MD-origin tables).
+            const text = collectNodeText(node);
             if (!text.trim())
                 return;
             chunks.push({
@@ -514,7 +581,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
                 currentSheet = node.metadata?.sheetName;
             const isContentNode = node.type === 'paragraph' || node.type === 'heading' || node.type === 'list' || node.type === 'cell' || (node.text && (!node.children || node.children.length === 0));
             if (isContentNode) {
-                const text = (typeof override === 'string' ? override : (node.text ?? '')).trim();
+                const text = (typeof override === 'string' ? override : collectNodeText(node)).trim();
                 if (!text)
                     return;
                 // Split paragraph text into individual sentences for finer-grained similarity
@@ -573,7 +640,7 @@ class ChunkingGenerator extends BaseGenerator_js_1.BaseGenerator {
                 currentSheet = node.metadata?.sheetName;
             const isContentNode = node.type === 'paragraph' || node.type === 'heading' || node.type === 'list' || node.type === 'code' || node.type === 'cell' || (node.text && (!node.children || node.children.length === 0));
             if (isContentNode) {
-                const nodeText = typeof override === 'string' ? override : (node.text || '');
+                const nodeText = typeof override === 'string' ? override : collectNodeText(node);
                 const txt = nodeText + '\n';
                 nodeMap.push({ offset, heading: currentHeading, slideNumber: currentSlide, pageNumber: currentPage, sheetName: currentSheet });
                 parts.push(txt);

package/dist/generators/EpubGenerator.js

@@ -182,7 +182,10 @@ class EpubGenerator extends BaseGenerator_js_1.BaseGenerator {
     async generate() {
         const htmlGenerator = new HtmlGenerator_js_1.HtmlGenerator(this.ast, {
             ...this.config,
-            htmlConfig: { ...this.config.htmlConfig, standalone: false },
+            // Force sourceAttributes off: those data-* attributes are wire-format plumbing for
+            // structured consumers and change the mermaid shape's rendered appearance, neither of
+            // which belongs in a packaged EPUB.
+            htmlConfig: { ...this.config.htmlConfig, standalone: false, sourceAttributes: false },
         });
         const htmlResult = await htmlGenerator.generate();
         let bodyHtml = typeof htmlResult.value === 'string' ? htmlResult.value : '';

package/dist/generators/HtmlGenerator.js

@@ -117,14 +117,20 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             containerClass = 'pdf-container';
         let bodyContent = await this.processNodeArray(this.ast.content);
         if (this.collectedNotes.length > 0) {
+            // De-duplicate by node identity first. A table row with sparse column metadata
+            // re-processes its cells in `case 'row'` after they were already processed for
+            // `childrenOutput`, so a footnote referenced inside a cell gets pushed here twice -
+            // the same object reference both times, which a Set collapses back to one. Genuinely
+            // distinct notes (even two references to the same id) are different objects and stay.
+            const collectedNotes = [...new Set(this.collectedNotes)];
             // Footnotes/endnotes get their own <section data-footnotes> (the agreed
-            // contract with inscript-editor's footnote node); other note types (e.g.
+            // contract with attribute-driven editors' footnote nodes); other note types (e.g.
             // slide speaker notes) keep the existing generic notes wrapper.
-            const footnotes = this.collectedNotes.filter(n => {
+            const footnotes = collectedNotes.filter(n => {
                 const t = n.metadata?.noteType;
                 return t === 'footnote' || t === 'endnote';
             });
-            const otherNotes = this.collectedNotes.filter(n => !footnotes.includes(n));
+            const otherNotes = collectedNotes.filter(n => !footnotes.includes(n));
             if (footnotes.length > 0) {
                 let footnotesHtml = '';
                 for (const note of footnotes) {
@@ -460,6 +466,23 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             if (override === false) {
                 continue;
             }
+            // A top-level footnote/endnote note is an orphan definition (the MarkdownParser
+            // recovers unreferenced `[^id]: ...` defs as trailing note nodes). Route it into the
+            // collected footnotes so it renders inside `<section data-footnotes>` - where HtmlParser
+            // reads it back on import - instead of inline outside the section with a dead back-link.
+            const orphanMeta = node.metadata;
+            const orphanNoteType = orphanMeta?.noteType;
+            if (node.type === 'note' && orphanMeta?.unreferenced && (orphanNoteType === 'footnote' || orphanNoteType === 'endnote')) {
+                // Only an unreferenced (orphan) definition is hoisted into <section data-footnotes>.
+                // The `unreferenced` guard also keeps the generators in agreement at depth: this
+                // routing runs in every processNodeArray call, so without it a `note` sitting as a
+                // CHILD of a container (a consumer-built AST; no shipped parser emits this) would be
+                // hoisted here and then given an `<a href="#footnote-ref-N">` back-link with no
+                // anchor - the exact dangling link the orphan handling removes. MarkdownGenerator's
+                // equivalent routing is top-level only, so gating on the flag matches it.
+                this.collectedNotes.push(node);
+                continue;
+            }
             if (node.type === 'list') {
                 const meta = node.metadata;
                 const type = meta?.listType === 'ordered' ? 'ordered' : 'unordered';
@@ -772,19 +795,40 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 }
                 return '';
             }
-            case 'break':
-                return node.metadata?.breakType === 'page' ? '<hr class="page-break">' : '<br>';
+            case 'break': {
+                const breakType = node.metadata?.breakType;
+                if (breakType === 'page')
+                    return '<hr class="page-break">';
+                // A thematic break is a plain rule; the parser reads a bare <hr> back as one.
+                if (breakType === 'thematic')
+                    return '<hr>';
+                return '<br>';
+            }
             case 'code': {
                 const meta = node.metadata;
                 if (meta?.math) {
-                    // No pinned editor contract yet (inscript-editor's math node is v1.2,
-                    // not built) - this is the proposed shape: data-math signals the
-                    // display mode, and the visible text keeps its $ delimiters so the
-                    // raw LaTeX degrades gracefully without a KaTeX renderer.
-                    const delimited = meta.math === 'block' ? `$$${node.text || ''}$$` : `$${node.text || ''}$`;
                     const tag = meta.math === 'block' ? 'div' : 'span';
+                    if (this.config.htmlConfig.sourceAttributes) {
+                        // Attribute-driven emission: the raw (undelimited) LaTeX lives in both
+                        // data-math and the text content, and the class token carries the mode.
+                        // The widened HtmlParser reads this back (a data-math value other than
+                        // inline/block is treated as LaTeX).
+                        const latex = node.text || '';
+                        return `${extraAnchors}<${tag} class="math math-${this.escape(meta.math)}" data-math="${this.escape(latex)}"${idAttr}${mappedAttrs}${styleAttr}>${this.escape(latex)}</${tag}>`;
+                    }
+                    // Default emission: data-math names the display mode, and the visible text
+                    // keeps its $ delimiters so the raw LaTeX degrades gracefully without a
+                    // KaTeX renderer.
+                    const delimited = meta.math === 'block' ? `$$${node.text || ''}$$` : `$${node.text || ''}$`;
                     return `${extraAnchors}<${tag} class="math math-${this.escape(meta.math)}" data-math="${this.escape(meta.math)}"${idAttr}${mappedAttrs}${styleAttr}>${this.escape(delimited)}</${tag}>`;
                 }
+                if (this.config.htmlConfig.sourceAttributes && meta?.language === 'mermaid') {
+                    // Attribute-driven emission: a <div class="mermaid" data-mermaid> the widened
+                    // parser maps back to a mermaid code node. escape() encodes '>' so diagram
+                    // arrows (-->), plus newlines and quotes, stay inside the tag and attribute.
+                    const code = node.text || '';
+                    return `${extraAnchors}<div class="mermaid" data-mermaid="${this.escape(code)}"${idAttr}${mappedAttrs}${styleAttr}>${this.escape(code)}</div>`;
+                }
                 const lang = meta?.language ? ` class="language-${this.escape(meta.language)}"` : '';
                 const codeHtml = `<code${lang}>${this.escape(node.text || '')}</code>`;
                 if (node.text && node.text.includes('\n')) {
@@ -820,9 +864,13 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                     const isHeaderStyle = firstRow.metadata?.style?.toLowerCase().includes('header');
                     const allBold = firstRowCells.length > 0 && firstRowCells.every(c => c.children?.every(child => child.formatting?.bold === true));
                     if (isHeaderStyle || allBold) {
-                        // Re-process children with <thead> wrap for the first row
+                        // Re-process the first row as header cells, wrapped in a <tr>. Without the
+                        // <tr>, the header cells sit directly under <thead> (`<thead><th>…`), which
+                        // is invalid HTML that HtmlParser does not read back as a table row - so a
+                        // md -> HTML -> md round trip lost the header content. `<thead><tr><th>…` is
+                        // valid and self-idempotent.
                         const headOutput = await this.processNodeRecursive(firstRow, async (n, children) => {
-                            return children.replace(/<td/g, '<th').replace(/<\/td>/g, '</th>');
+                            return `<tr>${children.replace(/<td/g, '<th').replace(/<\/td>/g, '</th>')}</tr>`;
                         });
                         const bodyRows = rows.slice(1);
                         const bodyOutput = await this.processNodeArray(bodyRows);
@@ -1048,15 +1096,34 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 const meta = node.metadata;
                 if (meta?.noteType === 'footnote' || meta?.noteType === 'endnote') {
                     const key = this.escape(this.getFootnoteKey(node));
-                    return `<p id="footnote-${key}" data-footnote-id="${key}">${childrenOutput} <a href="#footnote-ref-${key}">↩</a></p>`;
+                    // A <div> wrapper, not <p>: childrenOutput is block content, so a <p> wrapper
+                    // nests <p> inside <p> (every DOM parser splits it, leaving the wrapper empty),
+                    // and attribute-driven editors match `div[data-footnote-id]`. This changes the
+                    // default footnote-definition markup, which was broken-by-construction before.
+                    // An unreferenced (orphan) note has no citation anchor, so the back-link would
+                    // dangle - omit it.
+                    const backLink = meta?.unreferenced ? '' : ` <a href="#footnote-ref-${key}">↩</a>`;
+                    return `<div id="footnote-${key}" data-footnote-id="${key}">${childrenOutput}${backLink}</div>`;
                 }
                 const noteClass = meta?.noteType ? ` note-${this.escape(meta.noteType)}` : '';
                 return `${extraAnchors}<div class="slide-note${noteClass}"${idAttr}${className}${mappedAttrs}${styleAttr}>${childrenOutput}</div>`;
             }
             case 'embed': {
-                // Match the Youtube extension's exact wrapper shape so a loaded embed
-                // re-hydrates the editor's Youtube node.
                 const meta = node.metadata;
+                if (meta?.embedType === 'iframe') {
+                    // Generic preserved iframe. sanitizeUrl scheme-checks the src (only http/https
+                    // and the other non-executing schemes survive), so a javascript:/data: src is
+                    // dropped even with preservation on. The node only exists via opt-in parsing or
+                    // a programmatic AST, so this guard is unconditional.
+                    const src = (0, sanitize_js_1.sanitizeUrl)(meta?.url || '');
+                    if (!src)
+                        return '';
+                    const w = meta?.width ? ` width="${this.escape(meta.width)}"` : '';
+                    const h = meta?.height ? ` height="${this.escape(meta.height)}"` : '';
+                    return `${extraAnchors}<iframe src="${src}"${w}${h}${idAttr}${mappedAttrs}${styleAttr}></iframe>`;
+                }
+                // Match the attribute-driven Youtube wrapper shape so a loaded embed re-hydrates
+                // an editor's Youtube node.
                 const id = meta?.videoId || '';
                 const width = meta?.width || '100%';
                 const align = meta?.align || 'center';
@@ -1068,8 +1135,8 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
                 return `${extraAnchors}<div data-youtube-video="${this.escape(id)}" data-width="${this.escape(width)}" data-align="${this.escape(align)}" class="youtube-embed"${idAttr}${mappedAttrs} style="width: ${(0, sanitize_js_1.sanitizeCssValue)(width)}; margin-left: ${ml}; margin-right: ${mr};">${iframe}</div>`;
             }
             case 'admonition': {
-                // Match inscript-editor's Admonition node wrapper so a loaded admonition
-                // reaches the editor as that node instead of a plain blockquote.
+                // Match the attribute-driven admonition wrapper so a loaded admonition
+                // reaches an editor as that node instead of a plain blockquote.
                 const meta = node.metadata;
                 const admonitionType = this.escape(meta?.admonitionType || 'note');
                 return `${extraAnchors}<div class="admonition admonition-${admonitionType}" data-type="${admonitionType}"${idAttr}${mappedAttrs}${styleAttr}>${childrenOutput}</div>`;
@@ -1117,19 +1184,37 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             if (f.superscript)
                 result = `<sup>${result}</sup>`;
             const styles = this.headingUniformSize
-                ? this.getInlineStyles(node, { skipFontSize: true })
-                : this.getInlineStyles(node);
+                ? this.getInlineStyles(node, { skipFontSize: true, skipBackgroundColor: true })
+                : this.getInlineStyles(node, { skipBackgroundColor: true });
             if (styles) {
                 result = `<span style="${styles}">${result}</span>`;
             }
+            // Highlight -> <mark>, not a <span style="background-color">. Tiptap's Highlight
+            // extension parseHTML matches exactly `mark`, so an editor round trip only rehydrates
+            // the highlight from a <mark>; a bare span comes back as unhighlighted text. Kept
+            // outside the colour/size span above so a run carrying both still rehydrates both. The
+            // widened HtmlParser reads this shape back (style wins over data-color). Behaviour
+            // change (was a span), noted in the changelog.
+            if (f.backgroundColor) {
+                const safeBg = (0, sanitize_js_1.sanitizeCssValue)(f.backgroundColor);
+                if (safeBg) {
+                    result = `<mark data-color="${this.escape(safeBg)}" style="background-color: ${safeBg}">${result}</mark>`;
+                }
+            }
         }
         const meta = node.metadata;
         if (meta?.wikilink) {
-            // No pinned editor contract yet for wikilinks - data-wikilink-page preserves the
-            // exact page name separately from the display text/alias and from href (which
-            // the host app's resolver may rewrite to a real URL).
+            // data-wikilink-page preserves the exact page name separately from the display
+            // text/alias and from href (which a host resolver may rewrite to a real URL).
             if (!this.config.ignoreInternalLinks) {
-                result = `<a href="#${this.escape(this.slugify(meta.link || ''))}" data-wikilink-page="${this.escape(meta.link || '')}">${result}</a>`;
+                // Attribute-driven emission adds data-wikilink/data-target (and data-alias when the
+                // display text differs from the page) alongside the default attributes. It is a
+                // superset - the widened parser still resolves via data-wikilink-page first.
+                const extra = this.config.htmlConfig.sourceAttributes
+                    ? ` data-wikilink="true" data-target="${this.escape(meta.link || '')}"`
+                        + (node.text && node.text !== meta.link ? ` data-alias="${this.escape(node.text)}"` : '')
+                    : '';
+                result = `<a href="#${this.escape(this.slugify(meta.link || ''))}" data-wikilink-page="${this.escape(meta.link || '')}"${extra}>${result}</a>`;
             }
         }
         else if (meta?.link) {
@@ -1142,11 +1227,12 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             result = `<abbr title="${this.escape(meta.abbreviationTitle)}">${result}</abbr>`;
         }
         if (meta?.citationKey) {
-            // No pinned editor contract yet for citations (unlike footnotes/admonitions) -
-            // this is the proposed shape: a <cite> carrying the bare key, matching Pandoc's
-            // [@citekey] on the Markdown side. Keep in sync if inscript-editor's citation
-            // node lands with a different attribute name.
-            result = `<cite data-citation-key="${this.escape(meta.citationKey)}">[@${this.escape(meta.citationKey)}]</cite>`;
+            result = this.config.htmlConfig.sourceAttributes
+                // Attribute-driven emission: a <span class="citation"> carrying data-key, which the
+                // widened parser reads back (the default <cite> shape is not attribute-keyed).
+                ? `<span class="citation" data-key="${this.escape(meta.citationKey)}">[@${this.escape(meta.citationKey)}]</span>`
+                // Default emission: a <cite> carrying the bare key, matching Pandoc's [@citekey].
+                : `<cite data-citation-key="${this.escape(meta.citationKey)}">[@${this.escape(meta.citationKey)}]</cite>`;
         }
         return result;
     }
@@ -1182,7 +1268,9 @@ class HtmlGenerator extends BaseGenerator_js_1.BaseGenerator {
             const f = node.formatting;
             if (f.color)
                 pushSafe('color', f.color);
-            if (f.backgroundColor)
+            // Highlights are emitted as <mark> by formatText (see there); when that path owns the
+            // background it passes skipBackgroundColor so the colour is not also duplicated here.
+            if (f.backgroundColor && !options.skipBackgroundColor)
                 pushSafe('background-color', f.backgroundColor);
             if (f.size && !options.skipFontSize)
                 pushSafe('font-size', f.size);