@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/text/LinkTargets.d.mts

@@ -0,0 +1,45 @@
+/**
+ * docx4j `LinkTargets`. A target is written as a link when it has no scheme (a relative path, a fragment, a UNC
+ * path), is a Windows drive path (`C:\...`, `C:/...`), or its scheme is `http`, `https`, `ftp`, `mailto`, `file`,
+ * `news` or `tel`, or one the caller adds. docx4j adds them through its JVM-wide property
+ * `docx4j.convert.out.linkSchemes`; this package has no properties file, so they are an argument here and
+ * `MarkdownExportOptions.linkSchemes` on the export, for a deployment whose documents carry `onenote:`, `ms-word:` or
+ * `notes:` links. Added, never removed: a default stays.
+ *
+ * The scheme is read as a browser reads one (WHATWG URL parsing): leading control characters and spaces are ignored,
+ * and tabs and line breaks are dropped anywhere, so ` \u0001java\tscri\npt:` is `javascript:`; the comparison ignores
+ * case. Anything up to the first `:` (where that comes before any `/`, `?` or `#`) is the scheme, so a target whose
+ * scheme a browser would reject as malformed (`java script:`) is refused too, rather than second-guessed.
+ */
+export declare const LinkTargets: {
+    /** The default schemes, frozen. */
+    defaultSchemes(): readonly string[];
+    /**
+     * The schemes a link may use: the defaults plus `extra`, each trimmed and lower-cased, a trailing `:` dropped
+     * and an empty one ignored (docx4j reads its property's comma-separated list so).
+     */
+    schemes(extra?: readonly string[]): readonly string[];
+    /**
+     * Whether an output may write this target as a link: it has no scheme, is a drive path, or its scheme (read as
+     * a browser reads it) is a default one or in `extra`. An undefined or empty target is safe (there is nothing to
+     * write).
+     */
+    isSafe(target: string | undefined, extra?: readonly string[]): boolean;
+    /**
+     * The target with its character references decoded as CommonMark decodes a link destination: a decimal (`:`) or
+     * hex (`:`) reference to its character, U+FFFD for zero, out of range or a surrogate; a named reference that
+     * stands for one ASCII character (`:`, `/`, `	`, ...) to that character. Other named references, and an
+     * `&` that begins no reference, stay as written. Decoded once, as a renderer decodes once. docx4j
+     * `decodeCharacterReferences`.
+     */
+    decodeCharacterReferences(target: string | undefined): string | undefined;
+    /**
+     * The target's scheme, read as a browser reads it, lower-cased; undefined where it has none (a relative path, a
+     * fragment, a UNC path, or nothing at all).
+     */
+    scheme(target: string | undefined): string | undefined;
+    /** A target for a log line: at most 80 characters (UTF-16 units, as docx4j's), control characters shown as spaces. */
+    excerpt(target: string | undefined): string;
+    /** The message the export logs, once per document, when it refuses a target. */
+    refusedMessage(target: string | undefined): string;
+};

package/dist/model/text/LinkTargets.mjs

@@ -0,0 +1,170 @@
+// Which link targets the Markdown export writes as a link (CR-012 section 21, the port of docx4j CR-056 phase 1:
+// `org.docx4j.convert.out.common.writer.LinkTargets`, docx4j 84ee9741c). A document's `w:hyperlink` relationship
+// target or HYPERLINK field target was written as the link's destination as it is, so a crafted
+// `javascript:alert(1)` target ran script in a page that rendered the Markdown as HTML (CWE-79, the defect
+// apache/poi#1455 fixed in POI). The rule is docx4j's allowlist of schemes, read as written and with its character
+// references decoded (docx4j's CR-056 section 14, CR-012 section 21.2 here); a refused target gives the link's text with
+// no link.
+/** docx4j's default schemes (POI's set). */
+const DEFAULT_SCHEMES = Object.freeze(['http', 'https', 'ftp', 'mailto', 'file', 'news', 'tel']);
+/**
+ * The HTML5 named character references that decode to an ASCII character. A scheme is ASCII, so these are the ones that
+ * can build one or end one (`:`, `/`, `#`, `?`, `	`, `
`); any other decodes to a
+ * character no scheme holds, or stays as written, and either way leaves a scheme malformed, which is refused.
+ */
+const ASCII_REFERENCES = Object.freeze({
+    Tab: '\t', NewLine: '\n', excl: '!', quot: '"', QUOT: '"', num: '#', dollar: '$', percnt: '%', amp: '&', AMP: '&',
+    apos: "'", lpar: '(', rpar: ')', ast: '*', midast: '*', plus: '+', comma: ',', period: '.', sol: '/', colon: ':',
+    semi: ';', lt: '<', LT: '<', equals: '=', gt: '>', GT: '>', quest: '?', commat: '@', lsqb: '[', lbrack: '[',
+    bsol: '\\', rsqb: ']', rbrack: ']', Hat: '^', lowbar: '_', UnderBar: '_', grave: '`', DiacriticalGrave: '`',
+    lcub: '{', lbrace: '{', verbar: '|', vert: '|', VerticalLine: '|', rcub: '}', rbrace: '}',
+});
+/** docx4j `isSafeAsWritten`, `isSafe` for one reading of the target: no scheme, a drive path, or an allowed scheme. */
+function safeAsWritten(target, extra) {
+    const scheme = LinkTargets.scheme(target);
+    if (scheme === undefined)
+        return true;
+    if (scheme.length === 1 && /\p{L}/u.test(scheme)) {
+        // a Windows drive path, C:\ or C:/
+        const next = normalise(target).charAt(2);
+        return next === '\\' || next === '/';
+    }
+    return LinkTargets.schemes(extra).includes(scheme);
+}
+/** Leading controls and spaces removed; tabs and line breaks removed anywhere. */
+function normalise(target) {
+    let out = '';
+    for (const c of target) {
+        if (c === '\t' || c === '\n' || c === '\r')
+            continue;
+        if (c <= ' ' && out.length === 0)
+            continue;
+        out += c;
+    }
+    return out;
+}
+/**
+ * docx4j `LinkTargets`. A target is written as a link when it has no scheme (a relative path, a fragment, a UNC
+ * path), is a Windows drive path (`C:\...`, `C:/...`), or its scheme is `http`, `https`, `ftp`, `mailto`, `file`,
+ * `news` or `tel`, or one the caller adds. docx4j adds them through its JVM-wide property
+ * `docx4j.convert.out.linkSchemes`; this package has no properties file, so they are an argument here and
+ * `MarkdownExportOptions.linkSchemes` on the export, for a deployment whose documents carry `onenote:`, `ms-word:` or
+ * `notes:` links. Added, never removed: a default stays.
+ *
+ * The scheme is read as a browser reads one (WHATWG URL parsing): leading control characters and spaces are ignored,
+ * and tabs and line breaks are dropped anywhere, so ` \u0001java\tscri\npt:` is `javascript:`; the comparison ignores
+ * case. Anything up to the first `:` (where that comes before any `/`, `?` or `#`) is the scheme, so a target whose
+ * scheme a browser would reject as malformed (`java script:`) is refused too, rather than second-guessed.
+ */
+export const LinkTargets = {
+    /** The default schemes, frozen. */
+    defaultSchemes() {
+        return DEFAULT_SCHEMES;
+    },
+    /**
+     * The schemes a link may use: the defaults plus `extra`, each trimmed and lower-cased, a trailing `:` dropped
+     * and an empty one ignored (docx4j reads its property's comma-separated list so).
+     */
+    schemes(extra = []) {
+        const set = new Set(DEFAULT_SCHEMES);
+        for (const raw of extra) {
+            let s = raw.trim().toLowerCase();
+            if (s.endsWith(':'))
+                s = s.slice(0, -1);
+            if (s !== '')
+                set.add(s);
+        }
+        return [...set];
+    },
+    /**
+     * Whether an output may write this target as a link: it has no scheme, is a drive path, or its scheme (read as
+     * a browser reads it) is a default one or in `extra`. An undefined or empty target is safe (there is nothing to
+     * write).
+     */
+    isSafe(target, extra = []) {
+        if (target === undefined || target === '')
+            return true;
+        if (!safeAsWritten(target, extra))
+            return false;
+        // as a CommonMark renderer reads a destination, its character references decoded (docx4j CR-056 section 14)
+        const decoded = LinkTargets.decodeCharacterReferences(target);
+        return decoded === target || safeAsWritten(decoded, extra);
+    },
+    /**
+     * The target with its character references decoded as CommonMark decodes a link destination: a decimal (`&#58;`) or
+     * hex (`&#x3A;`) reference to its character, U+FFFD for zero, out of range or a surrogate; a named reference that
+     * stands for one ASCII character (`&colon;`, `&sol;`, `&Tab;`, ...) to that character. Other named references, and an
+     * `&` that begins no reference, stay as written. Decoded once, as a renderer decodes once. docx4j
+     * `decodeCharacterReferences`.
+     */
+    decodeCharacterReferences(target) {
+        if (target === undefined || !target.includes('&'))
+            return target;
+        let out = '';
+        let i = 0;
+        while (i < target.length) {
+            const c = target.charAt(i);
+            if (c !== '&') {
+                out += c;
+                i++;
+                continue;
+            }
+            const semi = target.indexOf(';', i);
+            if (semi < 0 || semi - i > 40) {
+                out += c;
+                i++;
+                continue;
+            }
+            const ref = target.substring(i + 1, semi);
+            let decoded;
+            if (ref.length > 1 && ref.charAt(0) === '#') {
+                const hex = ref.charAt(1) === 'x' || ref.charAt(1) === 'X';
+                const digits = ref.substring(hex ? 2 : 1);
+                if (digits !== '' && digits.length <= (hex ? 6 : 7) && (hex ? /^[0-9A-Fa-f]+$/ : /^[0-9]+$/).test(digits)) {
+                    const cp = parseInt(digits, hex ? 16 : 10);
+                    decoded = cp === 0 || cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff) ? '\ufffd' : String.fromCodePoint(cp);
+                }
+            }
+            else {
+                decoded = Object.prototype.hasOwnProperty.call(ASCII_REFERENCES, ref) ? ASCII_REFERENCES[ref] : undefined;
+            }
+            if (decoded === undefined) {
+                out += c;
+                i++;
+                continue;
+            }
+            out += decoded;
+            i = semi + 1;
+        }
+        return out;
+    },
+    /**
+     * The target's scheme, read as a browser reads it, lower-cased; undefined where it has none (a relative path, a
+     * fragment, a UNC path, or nothing at all).
+     */
+    scheme(target) {
+        if (target === undefined)
+            return undefined;
+        const s = normalise(target);
+        for (let i = 0; i < s.length; i++) {
+            const c = s.charAt(i);
+            if (c === ':')
+                return i === 0 ? undefined : s.slice(0, i).toLowerCase();
+            if (c === '/' || c === '?' || c === '#')
+                return undefined;
+        }
+        return undefined;
+    },
+    /** A target for a log line: at most 80 characters (UTF-16 units, as docx4j's), control characters shown as spaces. */
+    excerpt(target) {
+        if (target === undefined)
+            return 'undefined';
+        const s = target.length > 80 ? target.slice(0, 80) + '...' : target;
+        return s.replace(/[\u0000-\u001f]/g, ' ');
+    },
+    /** The message the export logs, once per document, when it refuses a target. */
+    refusedMessage(target) {
+        return 'Link target refused (scheme not in MarkdownExportOptions.linkSchemes): the text is written without a link: '
+            + LinkTargets.excerpt(target);
+    },
+};

package/dist/model/text/MarkdownExporter.d.mts

@@ -0,0 +1,140 @@
+import type { Part } from '../../parts/Part.mjs';
+import { TextOptions, type TextOptionsInit, type TextModelView } from './TextOptions.mjs';
+import { TextResult, type TextBlock, type TextRun } from './TextResult.mjs';
+import type { TextPackage } from './TextContext.mjs';
+/** A picture's image, for a `MarkdownExportOptions.imageDestination`. */
+export interface MarkdownImage {
+    /** The picture's run in the block model. */
+    readonly run: TextRun;
+    /** The image part. */
+    readonly part: Part;
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+    /** The picture's number among the export's images with an image part, from 1. */
+    readonly index: number;
+    /** docx4j's file name for it, `image1.png`: `image`, the index, and the extension of its content type. */
+    readonly fileName: string;
+}
+/** Where a picture's Markdown image points: a data URI by default, or what a host makes of the image. */
+export type MarkdownImageDestination = (image: MarkdownImage) => string | Promise<string>;
+/** `MarkdownExportOptions.of`'s argument. */
+export interface MarkdownExportOptionsInit {
+    /** The text model's options the export reads a package with; the default is the text model's. */
+    textOptions?: TextOptions | TextOptionsInit;
+    /** The view, which sets `textOptions.view`. */
+    view?: TextModelView;
+    /** Where each picture points; a data URI where unset. */
+    imageDestination?: MarkdownImageDestination;
+    /** Schemes a link may use beyond `LinkTargets`' defaults. */
+    linkSchemes?: readonly string[];
+}
+/**
+ * Options for `MarkdownExporter`. What text is written is the text model's, under its `TextOptions`
+ * (`textOptions`): the view, the stories, hidden text, field codes, metadata as YAML front matter, under the
+ * names of the WD's section 10. The options here are how it is written. docx4j `MarkdownExportOptions`.
+ *
+ * docx4j's `imageDirPath` and `imageTargetUri`, which write each image to a directory, are `imageDestination`
+ * here: nothing outside `./node` writes a file (CR-012 section 16.4). A host that wants the files writes
+ * them in the function, which is given docx4j's file name, and returns the link.
+ */
+export declare class MarkdownExportOptions {
+    /**
+     * The text model's options a package is read with (`MarkdownExporter.export(pkg)`): the default is the
+     * text model's, the `accepted` view, the main story with its text boxes and notes, hidden text left out.
+     * A result is written under the options it was read with.
+     */
+    textOptions: TextOptions;
+    /** Where each picture points; a data URI (`data:image/png;base64,...`) where unset. */
+    imageDestination: MarkdownImageDestination | undefined;
+    /**
+     * Schemes a link may use beyond `LinkTargets`' defaults (`http`, `https`, `ftp`, `mailto`, `file`, `news`, `tel`),
+     * for documents that carry `onenote:` or `ms-word:` links. A link whose target has any other scheme is written as
+     * its text, with no link (docx4j CR-056, CR-012 section 21). docx4j's JVM-wide property
+     * `docx4j.convert.out.linkSchemes`; added to the defaults, never removing one.
+     */
+    linkSchemes: readonly string[];
+    static of(init?: MarkdownExportOptionsInit | MarkdownExportOptions): MarkdownExportOptions;
+    /** The revision view: `accepted` (the default), `original` or `markup`. */
+    get view(): TextModelView;
+    set view(view: TextModelView);
+}
+/** A block's Markdown (`MarkdownExporter.blocks`). */
+export interface MarkdownBlock {
+    readonly block: TextBlock;
+    /**
+     * Its Markdown: the lines from the start of the line its first character is on to the next block's, the
+     * blank line after it included. Empty for a block that writes nothing: an empty paragraph, or a code
+     * paragraph merged into the fence before it.
+     */
+    readonly markdown: string;
+}
+/** A result's Markdown block by block (`MarkdownExporter.blocks`). */
+export interface MarkdownBlocks {
+    /** The YAML front matter, under `metadata: true` (REQ-704); empty otherwise. */
+    readonly frontMatter: string;
+    /** Each block of the result, in its order, with its Markdown. */
+    readonly blocks: readonly MarkdownBlock[];
+    /** The whole: the front matter and the blocks' Markdown joined, what `export` gives. */
+    readonly markdown: string;
+}
+/**
+ * Exports WordprocessingML to Markdown, CommonMark with GFM's tables and strikethrough, footnotes and math
+ * (WD section 7.2). The text is the text model's (`Texts.of`, WD REQ-202): its block model is written as a
+ * Markdown tree, which a port of commonmark-java's Markdown renderer serializes, so the escaping and the list
+ * markers are commonmark-java's, and the Markdown docx4j's byte for byte.
+ *
+ * - a heading from its outline level, not its style's name; a list from its numbering, kept apart from an
+ *   adjacent list and going on at Word's count after a paragraph that interrupts it (REQ-703);
+ * - bold, italic, struck-through and code text where a run adds them to its paragraph's style; a code-styled
+ *   paragraph, or one in a mono paragraph style, a fenced code block;
+ * - links from a `w:hyperlink` or a HYPERLINK field, a target whose scheme isn't allowed (`javascript:`) written
+ *   as its text with no link (`LinkTargets`, `linkSchemes`); pictures with the describer's text, their image a
+ *   data URI unless `imageDestination` says otherwise;
+ * - notes `[^1]` and `[^e1]`, their definitions after the body; GFM tables, the header the `w:tblHeader` rows
+ *   or the first row, a cell's paragraphs `<br>` apart; block quotes from the Quote styles;
+ * - in the `markup` view, CriticMarkup: `{++inserted++}`, `{--deleted--}` and `{>>comment<<}`;
+ * - under `metadata: true`, the document properties as YAML front matter (REQ-704).
+ *
+ * Async because a picture's bytes are read from its part. The package is not changed (REQ-204).
+ * docx4j `MarkdownExporter`.
+ *
+ * ```ts
+ * const md = await new MarkdownExporter().export(pkg);
+ * const result = await Texts.of(pkg, { view: 'markup' });
+ * PlainText.of(result);                     // the plain text and the Markdown of one reading
+ * await MarkdownExporter.export(result, pkg);
+ * ```
+ */
+export declare class MarkdownExporter {
+    readonly options: MarkdownExportOptions;
+    constructor(options?: MarkdownExportOptions | MarkdownExportOptionsInit);
+    /**
+     * The Markdown of a package (the text model's reading of it under `options.textOptions`), or of a result
+     * the text model has made, under the options it was read with: its view, and its metadata as front matter
+     * where it was read with `metadata: true`. A result's block quotes are nested by their indent beyond the
+     * quote style's own where the package it was read from is given, by their indent alone where it isn't.
+     */
+    export(source: TextPackage | TextResult, pkg?: TextPackage): Promise<string>;
+    /**
+     * The Markdown of each block (CR-012 section 4.4, the editor's ask), the front matter apart: a host that
+     * writes something before each block, or stops after some, has the pieces `export` joins.
+     */
+    blocks(source: TextPackage | TextResult, pkg?: TextPackage): Promise<MarkdownBlocks>;
+    /** `new MarkdownExporter().export(...)`. */
+    static export(source: TextPackage | TextResult, pkg?: TextPackage): Promise<string>;
+    /** `new MarkdownExporter().blocks(...)`. */
+    static blocks(source: TextPackage | TextResult, pkg?: TextPackage): Promise<MarkdownBlocks>;
+    /**
+     * The document properties as a YAML front-matter block (WD REQ-704, REQ-515): a mapping for each kind of
+     * property the package has, `core`, `app` and `custom`, in that order, each property by its element's
+     * local name (core, application) or its name (custom), its value a double-quoted string. Empty where the
+     * result's metadata has none.
+     */
+    static frontMatter(result: TextResult): string;
+    /**
+     * A picture's destination: its image part's bytes (an SVG picture's SVG where it has no PNG copy, docx4j
+     * #699) as a data URI or as `imageDestination` says; empty where its image can't be had, so that its alt
+     * text is kept.
+     */
+    private destination;
+}

package/dist/model/text/MarkdownExporter.mjs

@@ -0,0 +1,255 @@
+import { BinaryPart } from '../../parts/BinaryPart.mjs';
+import { DefaultXmlPart } from '../../parts/DefaultXmlPart.mjs';
+import { TextOptions } from './TextOptions.mjs';
+import { TextResult } from './TextResult.mjs';
+import { Texts } from './Texts.mjs';
+import { WmlToMarkdown } from './WmlToMarkdown.mjs';
+import { renderMarkdown } from './commonmark.mjs';
+import { base64Encode } from '../../xml/dom.mjs';
+const SVG = 'image/svg+xml';
+/**
+ * Options for `MarkdownExporter`. What text is written is the text model's, under its `TextOptions`
+ * (`textOptions`): the view, the stories, hidden text, field codes, metadata as YAML front matter, under the
+ * names of the WD's section 10. The options here are how it is written. docx4j `MarkdownExportOptions`.
+ *
+ * docx4j's `imageDirPath` and `imageTargetUri`, which write each image to a directory, are `imageDestination`
+ * here: nothing outside `./node` writes a file (CR-012 section 16.4). A host that wants the files writes
+ * them in the function, which is given docx4j's file name, and returns the link.
+ */
+export class MarkdownExportOptions {
+    constructor() {
+        /**
+         * The text model's options a package is read with (`MarkdownExporter.export(pkg)`): the default is the
+         * text model's, the `accepted` view, the main story with its text boxes and notes, hidden text left out.
+         * A result is written under the options it was read with.
+         */
+        this.textOptions = new TextOptions();
+        /**
+         * Schemes a link may use beyond `LinkTargets`' defaults (`http`, `https`, `ftp`, `mailto`, `file`, `news`, `tel`),
+         * for documents that carry `onenote:` or `ms-word:` links. A link whose target has any other scheme is written as
+         * its text, with no link (docx4j CR-056, CR-012 section 21). docx4j's JVM-wide property
+         * `docx4j.convert.out.linkSchemes`; added to the defaults, never removing one.
+         */
+        this.linkSchemes = [];
+    }
+    static of(init) {
+        if (init instanceof MarkdownExportOptions)
+            return init;
+        const o = new MarkdownExportOptions();
+        if ((init === null || init === void 0 ? void 0 : init.textOptions) !== undefined)
+            o.textOptions = TextOptions.of(init.textOptions);
+        if ((init === null || init === void 0 ? void 0 : init.view) !== undefined)
+            o.view = init.view;
+        o.imageDestination = init === null || init === void 0 ? void 0 : init.imageDestination;
+        if ((init === null || init === void 0 ? void 0 : init.linkSchemes) !== undefined)
+            o.linkSchemes = [...init.linkSchemes];
+        return o;
+    }
+    /** The revision view: `accepted` (the default), `original` or `markup`. */
+    get view() {
+        return this.textOptions.view;
+    }
+    set view(view) {
+        this.textOptions.view = view;
+    }
+}
+/**
+ * Exports WordprocessingML to Markdown, CommonMark with GFM's tables and strikethrough, footnotes and math
+ * (WD section 7.2). The text is the text model's (`Texts.of`, WD REQ-202): its block model is written as a
+ * Markdown tree, which a port of commonmark-java's Markdown renderer serializes, so the escaping and the list
+ * markers are commonmark-java's, and the Markdown docx4j's byte for byte.
+ *
+ * - a heading from its outline level, not its style's name; a list from its numbering, kept apart from an
+ *   adjacent list and going on at Word's count after a paragraph that interrupts it (REQ-703);
+ * - bold, italic, struck-through and code text where a run adds them to its paragraph's style; a code-styled
+ *   paragraph, or one in a mono paragraph style, a fenced code block;
+ * - links from a `w:hyperlink` or a HYPERLINK field, a target whose scheme isn't allowed (`javascript:`) written
+ *   as its text with no link (`LinkTargets`, `linkSchemes`); pictures with the describer's text, their image a
+ *   data URI unless `imageDestination` says otherwise;
+ * - notes `[^1]` and `[^e1]`, their definitions after the body; GFM tables, the header the `w:tblHeader` rows
+ *   or the first row, a cell's paragraphs `<br>` apart; block quotes from the Quote styles;
+ * - in the `markup` view, CriticMarkup: `{++inserted++}`, `{--deleted--}` and `{>>comment<<}`;
+ * - under `metadata: true`, the document properties as YAML front matter (REQ-704).
+ *
+ * Async because a picture's bytes are read from its part. The package is not changed (REQ-204).
+ * docx4j `MarkdownExporter`.
+ *
+ * ```ts
+ * const md = await new MarkdownExporter().export(pkg);
+ * const result = await Texts.of(pkg, { view: 'markup' });
+ * PlainText.of(result);                     // the plain text and the Markdown of one reading
+ * await MarkdownExporter.export(result, pkg);
+ * ```
+ */
+export class MarkdownExporter {
+    constructor(options) {
+        this.options = MarkdownExportOptions.of(options);
+    }
+    /**
+     * The Markdown of a package (the text model's reading of it under `options.textOptions`), or of a result
+     * the text model has made, under the options it was read with: its view, and its metadata as front matter
+     * where it was read with `metadata: true`. A result's block quotes are nested by their indent beyond the
+     * quote style's own where the package it was read from is given, by their indent alone where it isn't.
+     */
+    async export(source, pkg) {
+        return (await this.blocks(source, pkg)).markdown;
+    }
+    /**
+     * The Markdown of each block (CR-012 section 4.4, the editor's ask), the front matter apart: a host that
+     * writes something before each block, or stops after some, has the pieces `export` joins.
+     */
+    async blocks(source, pkg) {
+        let result;
+        let styles;
+        if (source instanceof TextResult) {
+            result = source;
+            styles = pkg;
+        }
+        else {
+            result = await Texts.of(source, this.options.textOptions);
+            styles = source;
+        }
+        const writer = new WmlToMarkdown(result, await resolverOf(styles), this.options.linkSchemes);
+        const document = writer.convert();
+        let index = 0;
+        for (const { node, run } of writer.images) {
+            node.destination = await this.destination(run, () => ++index);
+        }
+        const starts = new Map();
+        const body = renderMarkdown(document, starts);
+        const frontMatter = result.options.metadata ? MarkdownExporter.frontMatter(result) : '';
+        return { frontMatter, blocks: sliced(result.blocks, starts, body), markdown: frontMatter + body };
+    }
+    /** `new MarkdownExporter().export(...)`. */
+    static async export(source, pkg) {
+        return new MarkdownExporter().export(source, pkg);
+    }
+    /** `new MarkdownExporter().blocks(...)`. */
+    static async blocks(source, pkg) {
+        return new MarkdownExporter().blocks(source, pkg);
+    }
+    /**
+     * The document properties as a YAML front-matter block (WD REQ-704, REQ-515): a mapping for each kind of
+     * property the package has, `core`, `app` and `custom`, in that order, each property by its element's
+     * local name (core, application) or its name (custom), its value a double-quoted string. Empty where the
+     * result's metadata has none.
+     */
+    static frontMatter(result) {
+        let sb = '';
+        for (const kind of [TextResult.CORE, TextResult.APP, TextResult.CUSTOM]) {
+            const properties = result.metadata[kind];
+            if (properties === null || typeof properties !== 'object')
+                continue;
+            const entries = properties instanceof Map ? [...properties.entries()] : Object.entries(properties);
+            if (entries.length === 0)
+                continue;
+            sb += `${kind}:\n`;
+            for (const [k, v] of entries)
+                sb += `  ${yamlKey(String(k))}: ${yamlString(String(v))}\n`;
+        }
+        return sb === '' ? '' : `---\n${sb}---\n\n`;
+    }
+    /**
+     * A picture's destination: its image part's bytes (an SVG picture's SVG where it has no PNG copy, docx4j
+     * #699) as a data URI or as `imageDestination` says; empty where its image can't be had, so that its alt
+     * text is kept.
+     */
+    async destination(run, next) {
+        var _a;
+        const part = (_a = run.image) === null || _a === void 0 ? void 0 : _a.part;
+        let bytes;
+        try {
+            if (part instanceof BinaryPart || (part instanceof DefaultXmlPart && part.contentType === SVG))
+                bytes = await part.getBytes();
+        }
+        catch {
+            bytes = undefined; // its alt text, with no destination
+        }
+        if (part === undefined || bytes === undefined)
+            return '';
+        const contentType = part.contentType;
+        if (this.options.imageDestination === undefined)
+            return `data:${contentType};base64,${base64Encode(bytes)}`;
+        const index = next();
+        return this.options.imageDestination({ run, part, bytes, contentType, index, fileName: `image${index}.${extensionFor(contentType, part)}` });
+    }
+}
+/** The resolver a block quote's style indent is asked of: the package's, where it has a styles part. */
+async function resolverOf(pkg) {
+    if (pkg === undefined)
+        return undefined;
+    try {
+        // asking a package with no styles part for a resolver would add one to it
+        if (!pkg.getMainDocumentPart().styleDefinitionsPart)
+            return undefined;
+        return await pkg.getPropertyResolver();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Each block's Markdown: from its start to the next start, the last to the end; a start is one block's. */
+function sliced(blocks, starts, body) {
+    const ordered = [...new Set(starts.values())].sort((a, b) => a - b);
+    const end = new Map();
+    ordered.forEach((s, i) => { var _a; return end.set(s, (_a = ordered[i + 1]) !== null && _a !== void 0 ? _a : body.length); });
+    const taken = new Set();
+    return blocks.map((block) => {
+        const start = starts.get(block);
+        if (start === undefined || taken.has(start))
+            return { block, markdown: '' };
+        taken.add(start);
+        return { block, markdown: body.slice(start, end.get(start)) };
+    });
+}
+function yamlKey(key) {
+    return /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(key) ? key : yamlString(key);
+}
+/** A YAML double-quoted scalar: `\`, `"` and the control characters escaped. */
+function yamlString(value) {
+    let sb = '"';
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charAt(i);
+        const code = value.charCodeAt(i);
+        switch (c) {
+            case '"':
+                sb += '\\"';
+                break;
+            case '\\':
+                sb += '\\\\';
+                break;
+            case '\n':
+                sb += '\\n';
+                break;
+            case '\r':
+                sb += '\\r';
+                break;
+            case '\t':
+                sb += '\\t';
+                break;
+            default:
+                if (code < 0x20 || code === 0x7f || code === 0x85 || code === 0x2028 || code === 0x2029)
+                    sb += `\\u${code.toString(16).padStart(4, '0')}`;
+                else
+                    sb += c;
+        }
+    }
+    return `${sb}"`;
+}
+function extensionFor(contentType, part) {
+    switch (contentType) {
+        case 'image/png': return 'png';
+        case 'image/jpeg': return 'jpg';
+        case 'image/gif': return 'gif';
+        case 'image/bmp': return 'bmp';
+        case 'image/tiff': return 'tif';
+        case 'image/svg+xml': return 'svg';
+        case 'image/x-emf': return 'emf';
+        case 'image/x-wmf': return 'wmf';
+        default: {
+            const name = part.partName.name;
+            const dot = name.lastIndexOf('.');
+            return dot >= 0 ? name.substring(dot + 1) : 'bin';
+        }
+    }
+}

package/dist/model/text/PlainText.d.mts

@@ -0,0 +1,29 @@
+import type { TextResult, TextBlock } from './TextResult.mjs';
+/** The spaces for each 720-twip tab stop of indent under `layout: indent` (REQ-709). */
+export declare const INDENT_SPACES = 4;
+/** The note line before a table in the listed format (REQ-605, REQ-707). */
+export declare const LISTED_FORMAT_NOTE = "[table: listed format]";
+/**
+ * Plain text from the block model (WD section 7.1): each paragraph one line, a break one line more
+ * (REQ-603); the text exactly as the document holds it (REQ-602), U+000A between lines and after the last.
+ *
+ * Tables (REQ-605): a simple table a row a line, its cells a tab apart; any other in the listed format,
+ * after the note line `[table: listed format]`, a row a line as `Header: value; Header: value`. `tables:
+ * tsv` writes every table in the simple form, `tables: grid` as a pandoc grid table, its spans drawn.
+ *
+ * What the extractor adds follows the WD's bracket convention (REQ-707): `[n]` at a note's reference and
+ * at the start of the note; `[image: ...]` (or `[image, generated: ...]`) under `alt_text: true`; `[page
+ * n]` under `page_markers: true`; and under `metadata: true`, before the body, one line per kind of
+ * property that has any (REQ-515). In the markup view, insertions are `{++text++}`, deletions `{--text--}`
+ * and comments `{>>text<<}`, at their references with their replies after them (REQ-702, REQ-504); under
+ * `markup_detail` the marker's opening is followed by `author:` or `author, date:`.
+ *
+ * Under `layout: indent` (REQ-709) a paragraph outside a table begins with four spaces for each tab stop
+ * (720 twips) of its first line's indent, rounded to the nearest stop. docx4j `PlainText`.
+ */
+export declare const PlainText: {
+    /** The plain text of a result. */
+    of(result: TextResult): string;
+    /** Whether a table is written in REQ-605's simple form under `tables: auto`. */
+    isSimple(table: TextBlock): boolean;
+};