officeparser 7.2.3 → 7.4.0

package/dist/generators/BaseGenerator.d.ts

@@ -1,4 +1,4 @@
-import { OfficeIssue, ConversionResult, FullGeneratorConfig, GeneratorConfig, OfficeContentNode, OfficeParserAST, OfficeWarningType, UniversalGeneratorFormat } from '../types.js';
+import { OfficeIssue, ConversionResult, FullGeneratorConfig, GeneratorConfig, OfficeContentNode, OfficeMetadata, OfficeParserAST, OfficeWarningType, UniversalGeneratorFormat } from '../types.js';
 import { StyleMapper } from '../utils/styleMapper.js';
 /**
  * Base class for all document generators.
@@ -12,6 +12,28 @@ export declare abstract class BaseGenerator<D extends UniversalGeneratorFormat =
     protected styleMapper: StyleMapper;
     protected collectedNotes: OfficeContentNode[];
     constructor(destination: D, ast: OfficeParserAST, config?: GeneratorConfig<D> | FullGeneratorConfig);
+    /**
+     * The document metadata a generator should write out: `ast.metadata` with
+     * `config.metadataOverrides` applied on top, per field.
+     *
+     * Every generator must read metadata through here rather than touching `this.ast.metadata`
+     * directly, so an override reaches all of them uniformly instead of one format at a time.
+     *
+     * Merged rather than replaced, so overriding one field doesn't blank the rest, and computed
+     * fresh rather than cached on the AST: overrides are an output concern, and mutating
+     * `ast.metadata` would leak one generation's settings into the next use of the same AST.
+     * `custom` merges into `customProperties` so callers see one bucket regardless of origin.
+     */
+    protected get effectiveMetadata(): OfficeMetadata;
+    /**
+     * Reports caller-supplied `metadataOverrides.custom` entries that the destination format has
+     * no way to represent (EPUB's OPF and RTF's `\info` both have fixed vocabularies).
+     *
+     * Warning rather than dropping silently: a caller who sets metadata and never sees it in the
+     * output otherwise has no way to find out. Only `custom` keys are reported - the named fields
+     * map onto something in every format that carries metadata at all.
+     */
+    protected warnUnrepresentableCustomMetadata(format: string): void;
     /**
      * Retrieves the semantic mapping for a node, respecting the includeFormatting flag.
      * Per design requirements: Style mapping is bypassed if formatting is disabled.
@@ -48,6 +70,17 @@ export declare abstract class BaseGenerator<D extends UniversalGeneratorFormat =
      * Helper to generate a unique ID (slug) from text.
      */
     protected slugify(text: string): string;
+    private noteFootnoteKeys;
+    private usedFootnoteKeys;
+    private footnoteKeyCounter;
+    /**
+     * Assigns a stable, unique reference key to a footnote/endnote node, reused for both
+     * its inline reference marker and its collected definition. Source ids aren't reliably
+     * unique across a document - DOCX/ODT number footnotes and endnotes in separate
+     * sequences, so both can carry noteId "1" - so a source id is only reused when it
+     * hasn't already been claimed; otherwise a sequential counter guarantees uniqueness.
+     */
+    protected getFootnoteKey(note: OfficeContentNode): string;
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/BaseGenerator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseGenerator = void 0;
+const types_js_1 = require("../types.js");
 const configUtils_js_1 = require("../utils/configUtils.js");
 const errorUtils_js_1 = require("../utils/errorUtils.js");
 const styleMapper_js_1 = require("../utils/styleMapper.js");
@@ -21,6 +22,60 @@ class BaseGenerator {
         this.ast = ast;
         this.styleMapper = new styleMapper_js_1.StyleMapper(this.config.styleMap, this.config.ignoreDefaultStyleMap);
     }
+    /**
+     * The document metadata a generator should write out: `ast.metadata` with
+     * `config.metadataOverrides` applied on top, per field.
+     *
+     * Every generator must read metadata through here rather than touching `this.ast.metadata`
+     * directly, so an override reaches all of them uniformly instead of one format at a time.
+     *
+     * Merged rather than replaced, so overriding one field doesn't blank the rest, and computed
+     * fresh rather than cached on the AST: overrides are an output concern, and mutating
+     * `ast.metadata` would leak one generation's settings into the next use of the same AST.
+     * `custom` merges into `customProperties` so callers see one bucket regardless of origin.
+     */
+    get effectiveMetadata() {
+        const base = this.ast.metadata || {};
+        const overrides = this.config.metadataOverrides;
+        if (!overrides)
+            return base;
+        const { custom, language, ...named } = overrides;
+        const merged = { ...base };
+        // Assign only the fields actually supplied - spreading `named` wholesale would write
+        // `undefined` over parsed values for every field the caller left out.
+        for (const [key, value] of Object.entries(named)) {
+            if (value !== undefined)
+                merged[key] = value;
+        }
+        // `language` has no slot on OfficeMetadata; parsers already surface it through
+        // nativeProperties, so an override belongs in the same place rather than widening the
+        // parser-side type for a generator concern. Generators reading `nativeProperties.language`
+        // then pick it up with no change.
+        if (language !== undefined) {
+            merged.nativeProperties = { ...(base.nativeProperties || {}), language };
+        }
+        if (custom && Object.keys(custom).length > 0) {
+            merged.customProperties = { ...(base.customProperties || {}), ...custom };
+        }
+        return merged;
+    }
+    /**
+     * Reports caller-supplied `metadataOverrides.custom` entries that the destination format has
+     * no way to represent (EPUB's OPF and RTF's `\info` both have fixed vocabularies).
+     *
+     * Warning rather than dropping silently: a caller who sets metadata and never sees it in the
+     * output otherwise has no way to find out. Only `custom` keys are reported - the named fields
+     * map onto something in every format that carries metadata at all.
+     */
+    warnUnrepresentableCustomMetadata(format) {
+        const custom = this.config.metadataOverrides?.custom;
+        if (!custom)
+            return;
+        const keys = Object.keys(custom);
+        if (keys.length === 0)
+            return;
+        this.warn(types_js_1.OfficeWarningType.METADATA_NOT_REPRESENTABLE, { keys, format });
+    }
     /**
      * Retrieves the semantic mapping for a node, respecting the includeFormatting flag.
      * Per design requirements: Style mapping is bypassed if formatting is disabled.
@@ -55,6 +110,13 @@ class BaseGenerator {
      * @returns The generated string for this node and its subtree.
      */
     async processNodeRecursive(node, processor) {
+        // Every text-based generator funnels its whole traversal through here, so one check
+        // makes `abortSignal` effective for all of them. Previously the signal was read once
+        // before generation began and never again, which meant it could decline to start work
+        // but could not stop work already underway - not much use against a document large
+        // enough to be worth aborting. The check is a property read on an optional signal, so
+        // the per-node cost is negligible.
+        (0, errorUtils_js_1.checkAbortSignal)(this.config.abortSignal);
         const override = await this.handleOnNode(node);
         if (override === false)
             return '';
@@ -89,6 +151,42 @@ class BaseGenerator {
             .replace(/[\s_-]+/g, '-')
             .replace(/^-+|-+$/g, '');
     }
+    noteFootnoteKeys = new Map();
+    usedFootnoteKeys = new Set();
+    footnoteKeyCounter = 0;
+    /**
+     * Assigns a stable, unique reference key to a footnote/endnote node, reused for both
+     * its inline reference marker and its collected definition. Source ids aren't reliably
+     * unique across a document - DOCX/ODT number footnotes and endnotes in separate
+     * sequences, so both can carry noteId "1" - so a source id is only reused when it
+     * hasn't already been claimed; otherwise a sequential counter guarantees uniqueness.
+     */
+    getFootnoteKey(note) {
+        const cached = this.noteFootnoteKeys.get(note);
+        if (cached)
+            return cached;
+        const preferred = note.metadata?.noteId;
+        // The id is document-supplied and lands inside `[^...]` in Markdown, where the parser's
+        // own recognizer accepts everything but `]` - so a note id carrying markup round-tripped
+        // into the output verbatim. Accept it only when it looks like a label; otherwise fall
+        // through to the sequential counter, which is always safe. Real ids are numeric (DOCX),
+        // `ftn1`-shaped (ODT) or short slugs (`fn1`), and a Markdown label like `[^my note]`
+        // still qualifies, so the fallback fires only for genuinely hostile input.
+        const isLabelLike = typeof preferred === 'string' && /^[A-Za-z0-9_.:-][A-Za-z0-9 _.:-]*$/.test(preferred);
+        let key;
+        if (preferred && isLabelLike && !this.usedFootnoteKeys.has(preferred)) {
+            key = preferred;
+        }
+        else {
+            do {
+                this.footnoteKeyCounter++;
+                key = String(this.footnoteKeyCounter);
+            } while (this.usedFootnoteKeys.has(key));
+        }
+        this.usedFootnoteKeys.add(key);
+        this.noteFootnoteKeys.set(note, key);
+        return key;
+    }
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/CsvGenerator.d.ts

@@ -20,9 +20,17 @@ export declare class CsvGenerator extends BaseGenerator<'csv'> {
      */
     private renderNodeToRows;
     /**
-     * Escapes a value for CSV formatting.
+     * Escapes a value for CSV formatting: RFC 4180 quoting plus a spreadsheet
+     * formula-injection guard (see csvSafeCell in ../utils/sanitize.js).
      */
     private escapeCsvValue;
+    /** Sanitizes a value for a `#` comment line (document metadata or sheet name).
+     *  Comment lines are free text prefixed with `#`, not RFC-4180 cells, so they
+     *  can't be quoted; instead we (a) collapse newlines so the value can't break out
+     *  and inject a new row, and (b) replace the column delimiter with a space so a
+     *  value like `x,=1+1` can't split into a second cell that a spreadsheet would
+     *  evaluate as a formula (CSV formula/DDE injection). */
+    private sanitizeComment;
     /**
      * Renders metadata as comments.
      */

package/dist/generators/CsvGenerator.js

@@ -4,6 +4,7 @@ exports.CsvGenerator = void 0;
 const fflate_1 = require("fflate");
 const types_js_1 = require("../types.js");
 const sheetUtils_js_1 = require("../utils/sheetUtils.js");
+const sanitize_js_1 = require("../utils/sanitize.js");
 const BaseGenerator_js_1 = require("./BaseGenerator.js");
 /**
  * Generates CSV files from an AST.
@@ -26,7 +27,7 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
         if (sheetNodes.length === 0) {
             return { value: '', messages: this.messages };
         }
-        const metadataHeader = this.config.renderMetadata ? this.renderMetadata(this.ast) : '';
+        const metadataHeader = this.config.renderMetadata ? this.renderMetadata(this.ast, delimiter) : '';
         // 2. Filter sheets based on range
         let selectedNodes = sheetNodes;
         if (csvConfig.sheets) {
@@ -59,7 +60,7 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
                 mergedLines.push(metadataHeader.trim());
             for (const sheet of sheetData) {
                 if (sheetData.length > 1)
-                    mergedLines.push(`# Sheet: ${sheet.name}`);
+                    mergedLines.push(`# Sheet: ${this.sanitizeComment(sheet.name, delimiter)}`);
                 for (const row of sheet.rows) {
                     const paddedRow = [...row];
                     // Don't pad comments
@@ -197,34 +198,45 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
         return rows;
     }
     /**
-     * Escapes a value for CSV formatting.
+     * Escapes a value for CSV formatting: RFC 4180 quoting plus a spreadsheet
+     * formula-injection guard (see csvSafeCell in ../utils/sanitize.js).
      */
     escapeCsvValue(val, delimiter) {
-        const needsQuotes = val.includes(delimiter) || val.includes('"') || val.includes('\n') || val.includes('\r');
-        if (!needsQuotes)
-            return val;
-        // Double up existing quotes and wrap in quotes
-        return `"${val.replace(/"/g, '""')}"`;
+        return (0, sanitize_js_1.csvSafeCell)(val, delimiter);
+    }
+    /** Sanitizes a value for a `#` comment line (document metadata or sheet name).
+     *  Comment lines are free text prefixed with `#`, not RFC-4180 cells, so they
+     *  can't be quoted; instead we (a) collapse newlines so the value can't break out
+     *  and inject a new row, and (b) replace the column delimiter with a space so a
+     *  value like `x,=1+1` can't split into a second cell that a spreadsheet would
+     *  evaluate as a formula (CSV formula/DDE injection). */
+    sanitizeComment(val, delimiter) {
+        let s = String(val ?? '').replace(/[\r\n]+/g, ' ');
+        if (delimiter)
+            s = s.split(delimiter).join(' ');
+        return s;
     }
     /**
      * Renders metadata as comments.
      */
-    renderMetadata(ast) {
-        if (!ast.metadata)
+    renderMetadata(_ast, delimiter) {
+        // Via effectiveMetadata rather than the passed AST so `metadataOverrides` applies here
+        // as it does in every other generator.
+        const m = this.effectiveMetadata;
+        if (!m || Object.keys(m).length === 0)
             return '';
-        const m = ast.metadata;
         let output = '';
         if (m.title)
-            output += `# Title: ${m.title}\n`;
+            output += `# Title: ${this.sanitizeComment(m.title, delimiter)}\n`;
         if (m.author)
-            output += `# Author: ${m.author}\n`;
+            output += `# Author: ${this.sanitizeComment(m.author, delimiter)}\n`;
         if (m.created)
-            output += `# Created: ${new Date(m.created).toLocaleString()}\n`;
+            output += `# Created: ${this.sanitizeComment(new Date(m.created).toLocaleString(), delimiter)}\n`;
         if (m.modified)
-            output += `# Modified: ${new Date(m.modified).toLocaleString()}\n`;
+            output += `# Modified: ${this.sanitizeComment(new Date(m.modified).toLocaleString(), delimiter)}\n`;
         if (m.customProperties) {
             for (const [k, v] of Object.entries(m.customProperties)) {
-                output += `# ${k}: ${v}\n`;
+                output += `# ${this.sanitizeComment(k, delimiter)}: ${this.sanitizeComment(String(v), delimiter)}\n`;
             }
         }
         return output ? output + '\n' : '';

package/dist/generators/EpubGenerator.d.ts

@@ -0,0 +1,43 @@
+import { ConversionResult, GeneratorConfig, OfficeParserAST } from '../types.js';
+import { BaseGenerator } from './BaseGenerator.js';
+/**
+ * Generates a minimal, valid EPUB 3 file from an AST.
+ *
+ * Every AST node is rendered as a single XHTML content document (reusing `HtmlGenerator`
+ * for the actual markup, since EPUB content documents are XHTML) and packaged with the
+ * required `mimetype`, `META-INF/container.xml`, OPF manifest, and navigation document.
+ *
+ * `HtmlGenerator` embeds images as base64 `data:` URIs, but EPUB reading systems do not
+ * render `data:` URIs - images must be packaged as separate resources referenced by a
+ * relative path. So each data-URI image is extracted into `OEBPS/images/`, declared in
+ * the manifest, and its `<img src>` rewritten to point at the packaged file.
+ */
+export declare class EpubGenerator extends BaseGenerator<'epub'> {
+    constructor(ast: OfficeParserAST, config?: GeneratorConfig<'epub'>);
+    /**
+     * Resolves the modification instant used for both the EPUB 3 `dcterms:modified` property
+     * (which the specification requires) and every zip entry's mtime.
+     *
+     * Takes the value from `effectiveMetadata`, i.e. `metadataOverrides.modified` if the caller
+     * set one, otherwise the source document's own `metadata.modified`, and only falls back to
+     * the current time when neither exists. That last fallback is the sole non-reproducible
+     * option, so it is the last resort rather than the default.
+     *
+     * **Both outputs matter for reproducibility.** `dcterms:modified` is the visible one, but
+     * `zipSync` defaults each entry's mtime to `Date.now()`, so pinning only the OPF still
+     * yields archives that differ byte-for-byte on every run. That second source is easy to
+     * miss because DOS zip timestamps have two-second granularity - back-to-back generation
+     * looks stable and only a gap longer than that reveals it.
+     *
+     * `iso` is `YYYY-MM-DDThh:mm:ssZ` (UTC, whole seconds) as EPUB requires; `toISOString()`
+     * emits milliseconds, so they are stripped.
+     */
+    private resolveModified;
+    /**
+     * Zip's DOS timestamp field cannot represent dates outside 1980-2099, and fflate throws
+     * rather than clamping. A document legitimately carrying a date outside that window (an
+     * unset/epoch-zero mtime is the common case) must not take EPUB generation down with it.
+     */
+    private clampToZipRange;
+    generate(): Promise<ConversionResult<'epub'>>;
+}

package/dist/generators/EpubGenerator.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EpubGenerator = void 0;
+const fflate_1 = require("fflate");
+const BaseGenerator_js_1 = require("./BaseGenerator.js");
+const HtmlGenerator_js_1 = require("./HtmlGenerator.js");
+const sanitize_js_1 = require("../utils/sanitize.js");
+const VOID_TAGS = ['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'];
+/** Block-level tags whose HTML5 content model does not permit them inside a <p>. */
+const BLOCK_TAGS_INVALID_IN_P = ['div', 'table', 'ul', 'ol', 'dl', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'section', 'figure'];
+/**
+ * HTML5's content model forbids block elements inside <p> (a <p> can only hold "phrasing
+ * content"), but browsers silently fix this via the HTML5 parsing algorithm's
+ * auto-closing rule: seeing a block start tag implicitly closes the open <p> first.
+ * XML parsers have no such rule - they just build the tree exactly as written. Since
+ * HtmlGenerator always wraps images in `<div class="image-container">`, a paragraph
+ * whose only child is an image becomes `<p><div>...</div></p>`: well-formed XML, but
+ * many EPUB rendering engines refuse to lay out a block box found inside a paragraph and
+ * simply drop it - silently, with no parse error, which is why the image vanishes.
+ *
+ * Fixes this by promoting any `<p ...>` that contains a nested block tag to a `<div ...>`
+ * instead, matching what a browser's auto-correction effectively produces. Paragraphs
+ * don't nest, so the first `</p>` after each `<p>` is always its match.
+ */
+const promoteParagraphsWithBlockContent = (html) => {
+    const blockTagPattern = new RegExp(`<(?:${BLOCK_TAGS_INVALID_IN_P.join('|')})\\b`, 'i');
+    let result = '';
+    let cursor = 0;
+    const pOpenRegex = /<p(\s[^>]*)?>/gi;
+    let match;
+    while ((match = pOpenRegex.exec(html)) !== null) {
+        if (match.index < cursor)
+            continue; // inside content already emitted by a prior promotion
+        result += html.slice(cursor, match.index);
+        const contentStart = match.index + match[0].length;
+        const closeMatch = /<\/p>/i.exec(html.slice(contentStart));
+        if (!closeMatch) {
+            // No closing tag found (shouldn't happen with well-formed generator output) -
+            // leave as-is rather than risk corrupting the rest of the document.
+            result += match[0];
+            cursor = contentStart;
+            pOpenRegex.lastIndex = cursor;
+            continue;
+        }
+        const inner = html.slice(contentStart, contentStart + closeMatch.index);
+        const attrs = match[1] || '';
+        result += blockTagPattern.test(inner) ? `<div${attrs}>${inner}</div>` : `<p${attrs}>${inner}</p>`;
+        cursor = contentStart + closeMatch.index + closeMatch[0].length;
+        pOpenRegex.lastIndex = cursor;
+    }
+    result += html.slice(cursor);
+    return result;
+};
+/**
+ * Converts HtmlGenerator's HTML output into well-formed XHTML, which EPUB reading
+ * systems parse as strict XML (unlike browsers, which tolerate HTML's looseness).
+ *
+ * This is more than cosmetic: a single raw `&` or unclosed tag makes the whole content
+ * document fail to open. The conversion:
+ *  - strips `<script>` blocks — EpubGenerator renders through HtmlGenerator with
+ *    `standalone: false`, which already omits the envelope-level stylesheet and Chart.js/
+ *    spreadsheet scripts entirely, but a chart *node* still emits its own inline
+ *    `<script>` (chart-init JS) regardless of that flag, since it's content, not envelope.
+ *    A reading system can't execute it anyway, and its JS operators can contain raw `&`/`<`
+ *    that are illegal as XML character data, so it's stripped here;
+ *  - promotes `<p>` tags that contain nested block content (see
+ *    promoteParagraphsWithBlockContent above) to `<div>`, since XML readers don't apply
+ *    HTML5's auto-closing correction that hides this in a browser;
+ *  - normalises HTML named entities (`&nbsp;`) to numeric references, since XML predefines
+ *    only `&amp;`/`&lt;`/`&gt;`/`&quot;`/`&apos;`;
+ *  - escapes stray ampersands (e.g. in `href` query strings) not already part of a valid
+ *    reference;
+ *  - gives HTML boolean attributes an explicit value (`checked` -> `checked="checked"`);
+ *  - self-closes void elements (`<br>` -> `<br/>`).
+ */
+const toXhtml = (html) => {
+    let out = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+    out = promoteParagraphsWithBlockContent(out);
+    // Named -> numeric entities (nbsp is the only named entity HtmlGenerator emits).
+    out = out.replace(/&nbsp;/g, '&#160;');
+    // Escape ampersands that don't already open a valid XML entity reference.
+    out = out.replace(/&(?!(?:amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);)/g, '&amp;');
+    // Give bare boolean attributes an explicit value. Scoped to the specific tags that
+    // emit them (checkbox task-list items, media iframes) so body text like "the selected
+    // option" is never rewritten.
+    out = out.replace(/<input\b([^>]*?)\schecked(\s*\/?>)/gi, '<input$1 checked="checked"$2');
+    out = out.replace(/<(iframe|video|audio)\b([^>]*?)\s(allowfullscreen|autoplay|controls|loop|muted)(\s*\/?>|\s)/gi, '<$1$2 $3="$3"$4');
+    // Self-close void elements (non-greedy attr capture so an already-present trailing `/`
+    // isn't duplicated, e.g. `<meta .../>` must not become `<meta ...//>`).
+    const voidTagPattern = new RegExp(`<(${VOID_TAGS.join('|')})((?:\\s[^>]*?)?)\\s*/?>`, 'gi');
+    out = out.replace(voidTagPattern, (_m, tag, attrs) => `<${tag}${attrs}/>`);
+    return out;
+};
+/**
+ * Minimal, book-friendly CSS injected into every EPUB content document. Kept static and
+ * free of `&`/`<` so it is XML-safe inline; the reading system supplies typography, so
+ * this only covers structural essentials the stripped page-chrome would otherwise lose.
+ */
+const EPUB_STYLESHEET = `img { max-width: 100%; height: auto; }
+table { border-collapse: collapse; margin: 1em 0; }
+td, th { border: 1px solid #ccc; padding: 4px 8px; }`;
+/** Maps an image MIME type to a file extension for the packaged resource. */
+const MIME_EXT = {
+    'image/jpeg': 'jpg', 'image/jpg': 'jpg', 'image/png': 'png', 'image/gif': 'gif',
+    'image/svg+xml': 'svg', 'image/webp': 'webp', 'image/bmp': 'bmp', 'image/tiff': 'tiff'
+};
+/** Decodes a base64 string to raw bytes, cross-env (atob exists in Node 16+ and browsers). */
+const decodeBase64 = (b64) => {
+    const bin = atob(b64);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return bytes;
+};
+/**
+ * Generates a minimal, valid EPUB 3 file from an AST.
+ *
+ * Every AST node is rendered as a single XHTML content document (reusing `HtmlGenerator`
+ * for the actual markup, since EPUB content documents are XHTML) and packaged with the
+ * required `mimetype`, `META-INF/container.xml`, OPF manifest, and navigation document.
+ *
+ * `HtmlGenerator` embeds images as base64 `data:` URIs, but EPUB reading systems do not
+ * render `data:` URIs - images must be packaged as separate resources referenced by a
+ * relative path. So each data-URI image is extracted into `OEBPS/images/`, declared in
+ * the manifest, and its `<img src>` rewritten to point at the packaged file.
+ */
+class EpubGenerator extends BaseGenerator_js_1.BaseGenerator {
+    constructor(ast, config) {
+        super('epub', ast, config);
+    }
+    /**
+     * Resolves the modification instant used for both the EPUB 3 `dcterms:modified` property
+     * (which the specification requires) and every zip entry's mtime.
+     *
+     * Takes the value from `effectiveMetadata`, i.e. `metadataOverrides.modified` if the caller
+     * set one, otherwise the source document's own `metadata.modified`, and only falls back to
+     * the current time when neither exists. That last fallback is the sole non-reproducible
+     * option, so it is the last resort rather than the default.
+     *
+     * **Both outputs matter for reproducibility.** `dcterms:modified` is the visible one, but
+     * `zipSync` defaults each entry's mtime to `Date.now()`, so pinning only the OPF still
+     * yields archives that differ byte-for-byte on every run. That second source is easy to
+     * miss because DOS zip timestamps have two-second granularity - back-to-back generation
+     * looks stable and only a gap longer than that reveals it.
+     *
+     * `iso` is `YYYY-MM-DDThh:mm:ssZ` (UTC, whole seconds) as EPUB requires; `toISOString()`
+     * emits milliseconds, so they are stripped.
+     */
+    resolveModified() {
+        const raw = this.effectiveMetadata.modified;
+        let resolved = null;
+        if (raw instanceof Date && !isNaN(raw.getTime())) {
+            resolved = raw;
+        }
+        else if (typeof raw === 'string' && raw !== '') {
+            // A parser may hand back a date-like string rather than a Date.
+            const parsed = new Date(raw);
+            if (!isNaN(parsed.getTime()))
+                resolved = parsed;
+        }
+        resolved ??= new Date();
+        return {
+            iso: resolved.toISOString().replace(/\.\d+Z$/, 'Z'),
+            mtime: this.clampToZipRange(resolved),
+        };
+    }
+    /**
+     * Zip's DOS timestamp field cannot represent dates outside 1980-2099, and fflate throws
+     * rather than clamping. A document legitimately carrying a date outside that window (an
+     * unset/epoch-zero mtime is the common case) must not take EPUB generation down with it.
+     */
+    clampToZipRange(date) {
+        const MIN = Date.UTC(1980, 0, 1);
+        const MAX = Date.UTC(2099, 11, 31, 23, 59, 59);
+        const t = date.getTime();
+        if (t < MIN)
+            return new Date(MIN);
+        if (t > MAX)
+            return new Date(MAX);
+        return date;
+    }
+    async generate() {
+        const htmlGenerator = new HtmlGenerator_js_1.HtmlGenerator(this.ast, {
+            ...this.config,
+            htmlConfig: { ...this.config.htmlConfig, standalone: false },
+        });
+        const htmlResult = await htmlGenerator.generate();
+        let bodyHtml = typeof htmlResult.value === 'string' ? htmlResult.value : '';
+        // Extract base64 data-URI images into packaged files (EPUB readers don't render
+        // `data:` URIs). Each distinct image becomes one OEBPS/images/imageN.ext resource,
+        // a manifest <item>, and a rewritten relative `src`. Deduped so a repeated image
+        // is packaged once.
+        const imageResources = {};
+        const imageManifestItems = [];
+        const dataUriToHref = new Map();
+        let imageCounter = 0;
+        bodyHtml = bodyHtml.replace(/(<img\b[^>]*\bsrc=")(data:(image\/[a-zA-Z0-9.+-]+);base64,([^"]+))(")/gi, (_full, pre, dataUri, mime, b64, post) => {
+            let href = dataUriToHref.get(dataUri);
+            if (!href) {
+                imageCounter++;
+                const ext = MIME_EXT[mime.toLowerCase()] || 'img';
+                href = `images/image${imageCounter}.${ext}`;
+                dataUriToHref.set(dataUri, href);
+                try {
+                    imageResources[`OEBPS/${href}`] = decodeBase64(b64);
+                    imageManifestItems.push(`<item id="img${imageCounter}" href="${href}" media-type="${mime}"/>`);
+                }
+                catch {
+                    // Undecodable data - leave the original src untouched rather than
+                    // emit a manifest entry for a resource we couldn't write.
+                    dataUriToHref.delete(dataUri);
+                    return `${pre}${dataUri}${post}`;
+                }
+            }
+            return `${pre}${href}${post}`;
+        });
+        const xhtmlBody = toXhtml(bodyHtml);
+        // Via effectiveMetadata so `metadataOverrides` applies here as it does everywhere else.
+        const meta = this.effectiveMetadata;
+        const title = meta.title || 'Untitled';
+        const author = meta.author;
+        const description = meta.description;
+        // dc:subject is the OPF's only vocabulary slot for either of these; both are repeatable.
+        const subject = meta.subject;
+        const keywords = meta.keywords;
+        const nativeProps = (meta.nativeProperties || {});
+        const language = nativeProps.language || 'en';
+        // OPF metadata is a closed Dublin Core vocabulary: a caller-defined key has no valid
+        // element to live in, and inventing one risks failing EPUB validation outright.
+        this.warnUnrepresentableCustomMetadata('EPUB');
+        const identifier = nativeProps.identifier || `urn:x-officeparser:${this.slugify(title)}-${xhtmlBody.length}`;
+        const { iso: modified, mtime } = this.resolveModified();
+        const chapterXhtml = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="${(0, sanitize_js_1.escapeXml)(language)}">
+<head>
+<meta charset="utf-8"/>
+<title>${(0, sanitize_js_1.escapeXml)(title)}</title>
+<style type="text/css">
+${EPUB_STYLESHEET}
+</style>
+</head>
+<body>
+${xhtmlBody}
+</body>
+</html>`;
+        // Built as a list rather than inline ternaries so an absent field contributes nothing at
+        // all. Inline `${x ? ... : ''}` leaves the surrounding indentation and newline behind, so
+        // every optional field the document lacks used to emit a stray blank line into the OPF.
+        const optionalDcElements = [
+            author ? `<dc:creator>${(0, sanitize_js_1.escapeXml)(author)}</dc:creator>` : '',
+            description ? `<dc:description>${(0, sanitize_js_1.escapeXml)(description)}</dc:description>` : '',
+            // dc:subject is repeatable and is the OPF's only slot for either of these.
+            subject ? `<dc:subject>${(0, sanitize_js_1.escapeXml)(subject)}</dc:subject>` : '',
+            keywords ? `<dc:subject>${(0, sanitize_js_1.escapeXml)(keywords)}</dc:subject>` : '',
+        ].filter(Boolean).map(el => `    ${el}`).join('\n');
+        const opf = `<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="pub-id">${(0, sanitize_js_1.escapeXml)(identifier)}</dc:identifier>
+    <dc:title>${(0, sanitize_js_1.escapeXml)(title)}</dc:title>
+${optionalDcElements}
+    <dc:language>${(0, sanitize_js_1.escapeXml)(language)}</dc:language>
+    <meta property="dcterms:modified">${modified}</meta>
+  </metadata>
+  <manifest>
+    <item id="chapter1" href="chapter1.xhtml" media-type="application/xhtml+xml"/>
+    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>${imageManifestItems.length ? '\n    ' + imageManifestItems.join('\n    ') : ''}
+  </manifest>
+  <spine>
+    <itemref idref="chapter1"/>
+  </spine>
+</package>`;
+        const navXhtml = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
+<head><meta charset="utf-8"/><title>Navigation</title></head>
+<body>
+<nav epub:type="toc" id="toc">
+<h1>${(0, sanitize_js_1.escapeXml)(title)}</h1>
+<ol>
+<li><a href="chapter1.xhtml">${(0, sanitize_js_1.escapeXml)(title)}</a></li>
+</ol>
+</nav>
+</body>
+</html>`;
+        const containerXml = `<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles>
+    <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
+  </rootfiles>
+</container>`;
+        const encoder = new TextEncoder();
+        // EPUB requires the mimetype entry to be the first file in the archive, stored
+        // uncompressed (level 0) - readers use it to sniff the format before parsing any XML.
+        const zipFiles = {
+            mimetype: [encoder.encode('application/epub+zip'), { level: 0 }],
+            'META-INF/container.xml': encoder.encode(containerXml),
+            'OEBPS/content.opf': encoder.encode(opf),
+            'OEBPS/nav.xhtml': encoder.encode(navXhtml),
+            'OEBPS/chapter1.xhtml': encoder.encode(chapterXhtml),
+            ...imageResources,
+        };
+        return {
+            // An explicit mtime is what makes the archive reproducible; fflate would otherwise
+            // stamp every entry with Date.now(). See resolveModified().
+            value: (0, fflate_1.zipSync)(zipFiles, { mtime }),
+            messages: this.messages,
+        };
+    }
+}
+exports.EpubGenerator = EpubGenerator;

package/dist/generators/HtmlGenerator.d.ts

@@ -32,7 +32,19 @@ export declare class HtmlGenerator extends BaseGenerator<'html'> {
     private formatText;
     private getInlineStyles;
     private getPremiumStyles;
+    /**
+     * Same as `getPremiumStyles()`, but wrapped in a CSS `@scope` block anchored to the
+     * `.op-html-scope` wrapper so the rules only apply within the generated fragment - they
+     * cannot leak onto a host page's own elements. `:root` and `body` selectors specifically
+     * target the real page root/body, so they're remapped to `:scope` (the scope root, i.e. the
+     * `.op-html-scope` wrapper) first; every other selector is naturally confined by `@scope`
+     * without needing per-selector rewriting. `customCss` is included in this scoping too.
+     */
+    private getScopedPremiumStyles;
     protected slugify(text: string): string;
     private getColumnLetter;
     private escape;
+    /** Converts a document-supplied date to an ISO string, or '' if it is invalid
+     *  (a malformed date would otherwise throw a RangeError and abort generation). */
+    private toIsoDate;
 }