@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/content/officeText.d.mts

@@ -0,0 +1,27 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+/** The text without the characters XML 1.0 excludes (E3). */
+export declare function dropExcluded(text: string): string;
+/** True when the text holds a character a writer writes as an element. */
+export declare function holdsElementCharacters(text: string): boolean;
+/**
+ * How a writer takes a line feed and a carriage return:
+ * - `paragraphs`: a paragraph break each, `\r\n` one (E1: `insertText` and every writer through `Paragraph.splice`);
+ *   the caller splits the text into lines (`linesOf`);
+ * - `one-paragraph`: `\n` and `\r\n` a `w:br`, `\r` a `w:cr` (E2: `insertParagraph`, `Paragraph.text =`), a recorded
+ *   departure from Word, which writes their escapes as text;
+ * - `multi-line`: each a `w:br` (a multi-line plain-text control, or a bound block control of one: section 61 item 3);
+ * - `single-line`: none, and no break either (a single-line plain-text control: F3).
+ */
+export type LineBreaks = 'paragraphs' | 'one-paragraph' | 'multi-line' | 'single-line';
+/** The text a writer of that kind writes, its line feeds and carriage returns turned into its characters. */
+export declare function forWriter(text: string, lineBreaks: LineBreaks): string;
+/** The text's lines, at each line feed, carriage return or `\r\n` (E1). */
+export declare function linesOf(text: string): string[];
+/** A run's items for a text: a `w:t` for each plain stretch, the element each mapped character reads as. */
+export declare function officeItems(text: string): Element[];
+/**
+ * A run of text a writer keeps in one paragraph (E2: `insertParagraph`, `Paragraph.text =`), or in a plain-text control
+ * as its kind takes it: the excluded characters dropped, every other character that is an element written as it.
+ */
+export declare function oneParagraphRun(text: string, rPr?: wml.RPr, lineBreaks?: LineBreaks): Element<wml.R>;

package/dist/model/content/officeText.mjs

@@ -0,0 +1,74 @@
+// Office JS's characters written back (CR-002 section 60). The readers give Word's character stream (CR-012 phase 4,
+// `officeItemText`): a `w:br` U+000B, a page break U+000C, a column break U+000E, a `w:cr` U+000D, the non-breaking and
+// optional hyphens U+001E and U+001F, a note reference U+0002. A writer turns each back into the element it reads as
+// (D1, as Word 365's writers do in check 55), drops the characters XML 1.0 excludes (E3: Word drops them too), and
+// takes a line feed or carriage return as its kind of writer does: a paragraph break for `insertText` (E1), a break
+// for `insertParagraph` (E2), a break or nothing in a bound or plain-text control (section 61 item 3, F3).
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { t as textItem, br as breakItem, tab as tabItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { runOf } from './tree.mjs';
+/**
+ * The characters XML 1.0 excludes that are no element: U+0002 (a note reference, which no text makes) and the other C0
+ * controls but tab, line feed, carriage return and the five that are elements, U+FFFE, U+FFFF and an unpaired surrogate.
+ */
+const EXCLUDED = /[\u0000-\u0008\u000F-\u001D￾￿]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/** The characters a writer writes as elements: tab, the three breaks, a carriage return, a line feed, the two hyphens. */
+const ELEMENT_CHARACTERS = /[\t\n\r\u000B\u000C\u000E\u001E\u001F]/;
+/** The text without the characters XML 1.0 excludes (E3). */
+export function dropExcluded(text) {
+    return text.replace(EXCLUDED, '');
+}
+/** True when the text holds a character a writer writes as an element. */
+export function holdsElementCharacters(text) {
+    return ELEMENT_CHARACTERS.test(text);
+}
+/** The text a writer of that kind writes, its line feeds and carriage returns turned into its characters. */
+export function forWriter(text, lineBreaks) {
+    switch (lineBreaks) {
+        case 'one-paragraph': return text.replace(/\r\n|\n/g, '\u000B');
+        case 'multi-line': return text.replace(/\r\n|\r|\n/g, '\u000B');
+        case 'single-line': return text.replace(/\r\n|[\r\n\u000B\u000C\u000E]/g, '');
+        default: return text;
+    }
+}
+/** The text's lines, at each line feed, carriage return or `\r\n` (E1). */
+export function linesOf(text) {
+    return text.split(/\r\n|\r|\n/);
+}
+/** The element a character reads as (`officeItemText` in reverse); a line feed a `w:br`. */
+function elementFor(c) {
+    switch (c) {
+        case '\t': return tabItem();
+        case '\u000C': return breakItem('page');
+        case '\u000E': return breakItem('column');
+        case '\r': return el.cr({});
+        case '\u001E': return el.noBreakHyphen({});
+        case '\u001F': return el.softHyphen({});
+        default: return breakItem(); // U+000B, and a line feed a writer left
+    }
+}
+/** A run's items for a text: a `w:t` for each plain stretch, the element each mapped character reads as. */
+export function officeItems(text) {
+    const out = [];
+    let plain = '';
+    for (const c of text) {
+        if (ELEMENT_CHARACTERS.test(c)) {
+            if (plain !== '')
+                out.push(textItem(plain));
+            plain = '';
+            out.push(elementFor(c));
+        }
+        else
+            plain += c;
+    }
+    if (plain !== '')
+        out.push(textItem(plain));
+    return out;
+}
+/**
+ * A run of text a writer keeps in one paragraph (E2: `insertParagraph`, `Paragraph.text =`), or in a plain-text control
+ * as its kind takes it: the excluded characters dropped, every other character that is an element written as it.
+ */
+export function oneParagraphRun(text, rPr, lineBreaks = 'one-paragraph') {
+    return runOf(officeItems(forWriter(dropExcluded(text), lineBreaks)), rPr);
+}

package/dist/model/content/ooxml.mjs

@@ -7,6 +7,8 @@
 // `insertXml` takes; the two share this module.
 import { wml as parseFragment, walkAll } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { repairBreaksOutsideRuns } from '../../opc/repair/breaks.mjs';
+import { unknownElementsIn } from '../../opc/repair/unknownElements.mjs';
 import { PartName } from '../../opc/PartName.mjs';
 import { ContentTypes } from '../../opc/ContentTypes.mjs';
 import { BinaryPart, ImagePart } from '../../parts/BinaryPart.mjs';
@@ -25,6 +27,12 @@ export function isFlatOpc(ooxml) {
 const REL_ATTRIBUTES = ['embed', 'link', 'id', 'href', 'pict', 'dm', 'lo', 'qs', 'cs', 'topLeft', 'topRight', 'bottomLeft', 'bottomRight'];
 /** The relationships namespace, for the same attributes on DOM nodes kept as `any` content. */
 const R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+/** CR-026 D12: a caller's own fragment holding an element Word doesn't know is refused, where a file arriving is read as Word reads it. */
+function refuseUnknown(names) {
+    if (names.length === 0)
+        return;
+    throw new Docx4JException(`insertOoxml refused: the content holds ${names.length === 1 ? 'an element' : 'elements'} Word doesn't know (${[...new Set(names)].join(', ')})`);
+}
 /**
  * The block-level content of `ooxml`, ready to insert: a flat OPC package's body content with
  * its parts copied and its references rewritten, or a fragment's elements.
@@ -32,7 +40,9 @@ const R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationship
 export async function contentOf(ooxml, options = {}) {
     var _a, _b;
     if (!isFlatOpc(ooxml)) {
-        return parseFragment(ooxml, { wrapper: 'body', preprocess: options.preprocess });
+        // a w:br outside a w:r read as Word reads it first, as on load (CR-021 D1): a created package has no hook
+        const preprocess = options.preprocess;
+        return parseFragment(ooxml, { wrapper: 'body', preprocess: (doc) => { refuseUnknown(unknownElementsIn(doc).map((e) => e.nodeName)); repairBreaksOutsideRuns(doc); preprocess === null || preprocess === void 0 ? void 0 : preprocess(doc); } });
     }
     const target = options.target;
     if (!target)
@@ -43,6 +53,7 @@ export async function contentOf(ooxml, options = {}) {
     const source = await WordprocessingMLPackage.load(ooxml, options.preprocess ? { preprocessor: options.preprocess } : {});
     const main = source.getMainDocumentPart();
     const document = await main.getContents();
+    refuseUnknown(main.warnings.flatMap((w) => (w.code === 'part.skipped' && w.kind === 'element' ? [w.name] : [])));
     const content = ((_b = (_a = document.body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []);
     if (content.length === 0)
         return [];

package/dist/model/content/outline.d.mts

@@ -0,0 +1,5 @@
+import type { Body, Outline } from './Body.mjs';
+/** What `Body.outline` asks of the text model: the outline of a body, or of its top-level blocks at these indices, under these options and context. */
+export type OutlineReader = (body: Body, options: unknown, context: unknown, blocks?: readonly number[]) => Promise<Outline>;
+export declare function setOutlineReader(implementation: OutlineReader): void;
+export declare function outlineReader(): OutlineReader;

package/dist/model/content/outline.mjs

@@ -0,0 +1,13 @@
+// The outline's reader (CR-012 D3): the text model's, which this module can't import, since the text model
+// imports the content API. The text model registers it (`model/text/outline.mts`), and the package classes
+// load that module, as the comment parts register themselves (CR-002 phase G).
+import { Docx4JException } from '../../opc/exceptions.mjs';
+let reader;
+export function setOutlineReader(implementation) {
+    reader = implementation;
+}
+export function outlineReader() {
+    if (!reader)
+        throw new Docx4JException('The text model is not loaded: import @docx4j/core-ts, @docx4j/core-ts/model or @docx4j/core-ts/packages');
+    return reader;
+}

package/dist/model/content/paraIds.d.mts

@@ -0,0 +1,5 @@
+/**
+ * Gives every paragraph and row in `added`, at any depth, a w14:paraId, where the story `within` stands in uses them (CR-002
+ * section 66). A document that uses none stays so. `added` has to be in the tree already, or `within` be what it goes in.
+ */
+export declare function assignParaIds(within: object, added: Iterable<unknown>): void;

package/dist/model/content/paraIds.mjs

@@ -0,0 +1,54 @@
+// w14:paraId on what the content API adds. In some files, one paragraph or row without an id makes Word 365 renumber the whole
+// part at the next open (check 79: 79d-table, 79f-one-missing, 79f-row-ids; check 80), which breaks a `w14:` address held across
+// that open. In others it fills the gap, and what separates them isn't known (CR-002 section 66). With an id on everything nothing
+// is left to chance, so a new paragraph or row takes one wherever the story already uses them.
+import { walk } from '@docx4j/generated-objects-ts/builders/wml';
+const P = 'org_docx4j_wml.P';
+const TR = 'org_docx4j_wml.Tr';
+const holdsAnId = (value) => {
+    const type = value.TYPE_NAME;
+    return type === P || type === TR;
+};
+/** The top of the tree `within` stands in, up `PARENT`: the whole story, so a cell's own body sees the document's ids. */
+function storyOf(within) {
+    let top = within;
+    for (let guard = 0; top.PARENT !== undefined && guard < 4096; guard++)
+        top = top.PARENT;
+    return top;
+}
+/** The ids the story uses. A paragraph's own content isn't entered: what it holds matters only to a clash, one in two billion. */
+function idsIn(story) {
+    const used = new Set();
+    walk(story, (value) => {
+        if (!holdsAnId(value))
+            return undefined;
+        if (value.paraId)
+            used.add(value.paraId.toUpperCase());
+        return value.TYPE_NAME === P ? false : undefined;
+    });
+    return used;
+}
+function freeId(used) {
+    let id;
+    do {
+        id = Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
+    } while (used.has(id));
+    used.add(id);
+    return id;
+}
+/**
+ * Gives every paragraph and row in `added`, at any depth, a w14:paraId, where the story `within` stands in uses them (CR-002
+ * section 66). A document that uses none stays so. `added` has to be in the tree already, or `within` be what it goes in.
+ */
+export function assignParaIds(within, added) {
+    const used = idsIn(storyOf(within));
+    if (used.size === 0)
+        return;
+    for (const block of added) {
+        walk(block, (value) => {
+            if (holdsAnId(value) && !value.paraId)
+                value.paraId = freeId(used);
+            return undefined;
+        });
+    }
+}

package/dist/model/content/placeholders.d.mts

@@ -0,0 +1,110 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import type { Part } from '../../parts/Part.mjs';
+/** Word's default placeholder entry, which a control Word makes names (checks 64 to 66). */
+export declare const DEFAULT_PLACEHOLDER_ENTRY = "DefaultPlaceholder_-1854013440";
+/** The default entry's text, as Word 365 writes it. */
+export declare const DEFAULT_PLACEHOLDER_TEXT = "Click or tap here to enter text.";
+/** A default placeholder entry: its name and its text. */
+export interface DefaultEntry {
+    name: string;
+    text: string;
+}
+/**
+ * Word's default placeholder entry for each kind of control that has one, as Word 365 makes them from the Developer tab
+ * (Jason's `placeholders.docx`, 2026-10-25; CR-002 section 63.22, as docx4j's CR-063 D8 has it): each in the glossary
+ * with the default entry's `w:docPartPr`, its body one run in the Placeholder Text style. A picture, a check box and a
+ * repeating section have none; the group, citation, equation, bibliography and `w:docPartObj` kinds are unmeasured.
+ */
+export declare const DEFAULT_ENTRIES: {
+    readonly text: {
+        readonly name: "DefaultPlaceholder_-1854013440";
+        readonly text: "Click or tap here to enter text.";
+    };
+    readonly date: {
+        readonly name: "DefaultPlaceholder_-1854013437";
+        readonly text: "Click or tap to enter a date.";
+    };
+    readonly list: {
+        readonly name: "DefaultPlaceholder_-1854013438";
+        readonly text: "Choose an item.";
+    };
+    readonly buildingBlock: {
+        readonly name: "DefaultPlaceholder_-1854013436";
+        readonly text: "Choose a building block.";
+    };
+    readonly repeatingSectionItem: {
+        readonly name: "DefaultPlaceholder_-1854013435";
+        readonly text: "Enter any content that you want to repeat, including other content controls. You can also insert this control around table rows in order to repeat parts of a table.";
+    };
+};
+/** The default entry Word gives a control of this kind (`DEFAULT_ENTRIES`); undefined for a kind it gives none. */
+export declare function defaultEntryFor(sdtPr: wml.SdtPr | undefined): DefaultEntry | undefined;
+/** The glossary entry a control's `w:placeholder` names; undefined where it names none (the bare form). */
+export declare function placeholderEntryOf(sdtPr: wml.SdtPr | undefined): string | undefined;
+/**
+ * Names `entry` in the control's `w:placeholder`, where Word writes it: after `w:id`, before `w:showingPlcHdr` and the
+ * binding (check 64's controls, as Word saved them).
+ */
+export declare function namePlaceholderEntry(sdtPr: wml.SdtPr, entry: string): void;
+/** A new entry's name, as Word names one: 32 upper-case hex digits, a new GUID's (check 65). */
+export declare function newEntryName(): string;
+/** What a package's glossary gives: an entry's text by name. */
+export interface GlossaryHost {
+    getMainDocumentPart(): {
+        glossaryDocumentPart: XmlPart<wml.GlossaryDocument> | undefined;
+        addTargetPart(part: Part): unknown;
+    };
+}
+/**
+ * The placeholder entries of a package's glossary: those its glossary document part holds, read privately (the part
+ * stays untouched), and those written since, which go into the glossary when the package is saved (`flush`).
+ */
+export declare class GlossaryEntries {
+    /** Entries by name, as the glossary part was last read; undefined until `load`. */
+    private read;
+    /** The part they were read from. */
+    private source;
+    /** Entries to write on save: name, text. */
+    private readonly pending;
+    /** Reads the glossary's entries, privately; again only where the part changed. */
+    load(glossary: XmlPart<wml.GlossaryDocument> | undefined): Promise<void>;
+    /**
+     * An entry's text, `null` where neither the glossary nor this session holds it, as Office JS reads it (check 65). An
+     * entry's paragraphs are a `\r` apart, as a control's are.
+     */
+    textOf(name: string): string | null;
+    /**
+     * An entry's body, the blocks of its `w:docPartBody` (not copies), `null` where neither the glossary nor this session
+     * holds it; an entry written this session is one paragraph, one run of its text in the Placeholder Text style.
+     */
+    bodyOf(name: string): Element[] | null;
+    /** True once the glossary has been read (`load`): until then an entry it holds reads as missing. */
+    get loaded(): boolean;
+    private entry;
+    /** Whether the glossary holds an entry of this name, or one is waiting to be written. */
+    has(name: string): boolean;
+    /** An entry to write on save, where the glossary doesn't hold one of that name. */
+    require(name: string, text: string): void;
+    /** True while entries wait for the save. */
+    get waiting(): boolean;
+    /** Entries waiting for the save, for a clone. */
+    copyTo(target: GlossaryEntries): void;
+    /**
+     * Writes the waiting entries into the glossary, making it where the file has none (D9 (a): the glossary document
+     * part and a styles part holding Placeholder Text, related from it), and puts Placeholder Text into a glossary's
+     * styles part that lacks it: an entry whose style its glossary lacks loses it in Word's save (check 65's 65b).
+     */
+    flush(host: GlossaryHost, make: {
+        glossary: () => XmlPart<wml.GlossaryDocument>;
+        styles: () => XmlPart<wml.Styles>;
+    }): Promise<void>;
+}
+/**
+ * What a control shows of an entry (CR-002 section 63.18, as revised by 63.21): a copy of each of its body's paragraphs'
+ * run-level content, every run as the glossary holds it. Word brought an entry back so, the control's own run properties
+ * not over it (check 68, cases 21 to 24), and doesn't restyle it (check 65's 65b, case 9). The paragraphs' properties stay
+ * in the glossary, whose styles they name.
+ */
+export declare function entryContentOf(body: Element[]): Element[][];

package/dist/model/content/placeholders.mjs

@@ -0,0 +1,253 @@
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import * as f from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { sdtProperty, sdtKindOf, textOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { linkParents } from './tree.mjs';
+import { uuid } from '../customxml/CustomXmlPartCollection.mjs';
+import { PLACEHOLDER_STYLE, placeholderRun } from '../customxml/bindings.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
+/** Word's default placeholder entry, which a control Word makes names (checks 64 to 66). */
+export const DEFAULT_PLACEHOLDER_ENTRY = 'DefaultPlaceholder_-1854013440';
+/** The default entry's text, as Word 365 writes it. */
+export const DEFAULT_PLACEHOLDER_TEXT = 'Click or tap here to enter text.';
+/**
+ * Word's default placeholder entry for each kind of control that has one, as Word 365 makes them from the Developer tab
+ * (Jason's `placeholders.docx`, 2026-10-25; CR-002 section 63.22, as docx4j's CR-063 D8 has it): each in the glossary
+ * with the default entry's `w:docPartPr`, its body one run in the Placeholder Text style. A picture, a check box and a
+ * repeating section have none; the group, citation, equation, bibliography and `w:docPartObj` kinds are unmeasured.
+ */
+export const DEFAULT_ENTRIES = {
+    text: { name: DEFAULT_PLACEHOLDER_ENTRY, text: DEFAULT_PLACEHOLDER_TEXT },
+    date: { name: 'DefaultPlaceholder_-1854013437', text: 'Click or tap to enter a date.' },
+    list: { name: 'DefaultPlaceholder_-1854013438', text: 'Choose an item.' },
+    buildingBlock: { name: 'DefaultPlaceholder_-1854013436', text: 'Choose a building block.' },
+    repeatingSectionItem: {
+        name: 'DefaultPlaceholder_-1854013435',
+        text: 'Enter any content that you want to repeat, including other content controls. You can also insert this control around table rows in order to repeat parts of a table.',
+    },
+};
+/** The default entry Word gives a control of this kind (`DEFAULT_ENTRIES`); undefined for a kind it gives none. */
+export function defaultEntryFor(sdtPr) {
+    switch (sdtKindOf(sdtPr)) {
+        case 'RichText':
+        case 'PlainText': return DEFAULT_ENTRIES.text;
+        case 'DatePicker': return DEFAULT_ENTRIES.date;
+        case 'DropDownList':
+        case 'ComboBox': return DEFAULT_ENTRIES.list;
+        case 'BuildingBlockGallery': return sdtProperty(sdtPr, 'docPartList') ? DEFAULT_ENTRIES.buildingBlock : undefined;
+        case 'RepeatingSectionItem': return DEFAULT_ENTRIES.repeatingSectionItem;
+        default: return undefined;
+    }
+}
+/** The glossary entry a control's `w:placeholder` names; undefined where it names none (the bare form). */
+export function placeholderEntryOf(sdtPr) {
+    var _a, _b, _c;
+    const value = (_a = sdtProperty(sdtPr, 'placeholder')) === null || _a === void 0 ? void 0 : _a.value;
+    return value === undefined ? undefined : (_c = (_b = value.docPart) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : '';
+}
+/**
+ * Names `entry` in the control's `w:placeholder`, where Word writes it: after `w:id`, before `w:showingPlcHdr` and the
+ * binding (check 64's controls, as Word saved them).
+ */
+export function namePlaceholderEntry(sdtPr, entry) {
+    var _a;
+    const items = ((_a = sdtPr.rPrOrAliasOrLock) !== null && _a !== void 0 ? _a : (sdtPr.rPrOrAliasOrLock = []));
+    const element = el.placeholder(f.createCTPlaceholder({ docPart: f.createCTPlaceholderDocPart({ val: entry }) }));
+    const at = items.findIndex((i) => i.name.localPart === 'placeholder');
+    if (at >= 0) {
+        items[at] = element;
+        linkParents(element, sdtPr);
+        return;
+    }
+    const after = new Set(['showingPlcHdr', 'dataBinding', 'temporary']);
+    const before = items.findIndex((i) => after.has(i.name.localPart));
+    items.splice(before < 0 ? items.length : before, 0, element);
+    linkParents(element, sdtPr);
+}
+/** A new entry's name, as Word names one: 32 upper-case hex digits, a new GUID's (check 65). */
+export function newEntryName() {
+    return uuid().replace(/-/g, '').toUpperCase();
+}
+/**
+ * The placeholder entries of a package's glossary: those its glossary document part holds, read privately (the part
+ * stays untouched), and those written since, which go into the glossary when the package is saved (`flush`).
+ */
+export class GlossaryEntries {
+    constructor() {
+        /** Entries to write on save: name, text. */
+        this.pending = new Map();
+    }
+    /** Reads the glossary's entries, privately; again only where the part changed. */
+    async load(glossary) {
+        if (glossary === this.source && this.read !== undefined)
+            return;
+        this.source = glossary;
+        this.read = glossary ? entriesOf(await glossary.readContents().catch(() => undefined)) : new Map();
+    }
+    /**
+     * An entry's text, `null` where neither the glossary nor this session holds it, as Office JS reads it (check 65). An
+     * entry's paragraphs are a `\r` apart, as a control's are.
+     */
+    textOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.text) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * An entry's body, the blocks of its `w:docPartBody` (not copies), `null` where neither the glossary nor this session
+     * holds it; an entry written this session is one paragraph, one run of its text in the Placeholder Text style.
+     */
+    bodyOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.body) !== null && _b !== void 0 ? _b : null;
+    }
+    /** True once the glossary has been read (`load`): until then an entry it holds reads as missing. */
+    get loaded() {
+        var _a;
+        return this.read !== undefined || ((_a = this.source) === null || _a === void 0 ? void 0 : _a.isUnmarshalled) === true;
+    }
+    entry(name) {
+        var _a;
+        const pending = this.pending.get(name);
+        if (pending !== undefined)
+            return { text: pending, body: [el.p({ content: [placeholderRun(undefined, pending)] })] };
+        const part = this.source;
+        if (part === null || part === void 0 ? void 0 : part.isUnmarshalled)
+            return entriesOf(part.contents).get(name);
+        return (_a = this.read) === null || _a === void 0 ? void 0 : _a.get(name);
+    }
+    /** Whether the glossary holds an entry of this name, or one is waiting to be written. */
+    has(name) {
+        return this.textOf(name) !== null;
+    }
+    /** An entry to write on save, where the glossary doesn't hold one of that name. */
+    require(name, text) {
+        if (!this.has(name))
+            this.pending.set(name, text);
+    }
+    /** True while entries wait for the save. */
+    get waiting() {
+        return this.pending.size > 0;
+    }
+    /** Entries waiting for the save, for a clone. */
+    copyTo(target) {
+        for (const [name, text] of this.pending)
+            target.pending.set(name, text);
+    }
+    /**
+     * Writes the waiting entries into the glossary, making it where the file has none (D9 (a): the glossary document
+     * part and a styles part holding Placeholder Text, related from it), and puts Placeholder Text into a glossary's
+     * styles part that lacks it: an entry whose style its glossary lacks loses it in Word's save (check 65's 65b).
+     */
+    async flush(host, make) {
+        var _a;
+        if (this.pending.size === 0)
+            return;
+        const main = host.getMainDocumentPart();
+        let glossary = main.glossaryDocumentPart;
+        if (!glossary) {
+            glossary = make.glossary();
+            glossary.setContents(f.createGlossaryDocument({ docParts: f.createCTDocParts({ docPart: [] }) }));
+            main.addTargetPart(glossary);
+        }
+        const doc = await glossary.getContents();
+        const docParts = ((_a = doc.docParts) !== null && _a !== void 0 ? _a : (doc.docParts = f.createCTDocParts({ docPart: [] })));
+        linkParents(docParts, doc);
+        const present = entriesOf(doc);
+        for (const [name, text] of this.pending) {
+            if (present.has(name))
+                continue;
+            const part = docPartOf(name, text);
+            docParts.docPart.push(part);
+            linkParents(part, docParts);
+        }
+        this.pending.clear();
+        this.source = glossary;
+        await ensureGlossaryStyles(glossary, make.styles);
+    }
+}
+/** A glossary's entries by name. */
+function entriesOf(doc) {
+    var _a, _b, _c, _d, _e;
+    const out = new Map();
+    for (const part of (_b = (_a = doc === null || doc === void 0 ? void 0 : doc.docParts) === null || _a === void 0 ? void 0 : _a.docPart) !== null && _b !== void 0 ? _b : []) {
+        const name = (_c = part.docPartPr) === null || _c === void 0 ? void 0 : _c.nameOrStyleOrCategory.find((i) => i.TYPE_NAME === 'org_docx4j_wml.CTDocPartName');
+        if (!(name === null || name === void 0 ? void 0 : name.val))
+            continue;
+        const body = ((_e = (_d = part.docPartBody) === null || _d === void 0 ? void 0 : _d.content) !== null && _e !== void 0 ? _e : []);
+        const paragraphs = body.filter((e) => e.value.TYPE_NAME === 'org_docx4j_wml.P');
+        out.set(name.val, { text: paragraphs.map((p) => textOf(p.value)).join('\r'), body });
+    }
+    return out;
+}
+/**
+ * What a control shows of an entry (CR-002 section 63.18, as revised by 63.21): a copy of each of its body's paragraphs'
+ * run-level content, every run as the glossary holds it. Word brought an entry back so, the control's own run properties
+ * not over it (check 68, cases 21 to 24), and doesn't restyle it (check 65's 65b, case 9). The paragraphs' properties stay
+ * in the glossary, whose styles they name.
+ */
+export function entryContentOf(body) {
+    var _a;
+    const out = [];
+    for (const block of body) {
+        if (block.value.TYPE_NAME !== 'org_docx4j_wml.P')
+            continue;
+        const items = ((_a = block.value.content) !== null && _a !== void 0 ? _a : []).filter((e) => { var _a, _b; return !['proofErr', 'bookmarkStart', 'bookmarkEnd'].includes((_b = (_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : ''); });
+        out.push(items.map((item) => ({ name: item.name, value: deepCopy(item.value) })));
+    }
+    return out;
+}
+/**
+ * A placeholder entry as Word writes one (check 65): the default entry's `w:docPartPr` (category General, gallery
+ * placeholder, type `bbPlcHdr`, behaviour content) with a `w:guid` of its own, and a body of one paragraph, one run in
+ * the Placeholder Text style.
+ */
+function docPartOf(name, text) {
+    const pr = f.createCTDocPartPr({
+        nameOrStyleOrCategory: [
+            f.createCTDocPartName({ val: name }),
+            f.createCTDocPartCategory({ name: f.createCTDocPartCategoryName({ val: 'General' }), gallery: f.createCTDocPartGallery({ val: 'placeholder' }) }),
+            f.createCTDocPartTypes({ type: [f.createCTDocPartType({ val: 'bbPlcHdr' })] }),
+            f.createCTDocPartBehaviors({ behavior: [f.createCTDocPartBehavior({ val: 'content' })] }),
+            f.createCTGuid({ val: `{${uuid().toUpperCase()}}` }),
+        ],
+    });
+    const body = f.createBody({ content: [el.p({ content: [placeholderRun(undefined, text)] })] });
+    return f.createCTDocPart({ docPartPr: pr, docPartBody: body });
+}
+/** Default Paragraph Font as Word defines it, which Placeholder Text is based on (check 34's glossary). */
+function defaultParagraphFont() {
+    return f.createStyle({
+        type: 'character', _default: true, styleId: 'DefaultParagraphFont',
+        name: f.createStyleName({ val: 'Default Paragraph Font' }),
+        uiPriority: f.createStyleUiPriority({ val: 1 }),
+        semiHidden: f.createBooleanDefaultTrue(),
+        unhideWhenUsed: f.createBooleanDefaultTrue(),
+    });
+}
+/** The glossary's styles part holds Placeholder Text and the style it is based on, made where the glossary has none. */
+async function ensureGlossaryStyles(glossary, make) {
+    var _a, _b;
+    const holder = glossary;
+    let part = holder.styleDefinitionsPart;
+    if (!part) {
+        part = make();
+        part.setContents(f.createStyles({ style: [] }));
+        holder.addTargetPart(part);
+    }
+    else {
+        // a styles part that has them already stays untouched
+        const read = await part.readContents().catch(() => undefined);
+        const ids = new Set(((_a = read === null || read === void 0 ? void 0 : read.style) !== null && _a !== void 0 ? _a : []).map((s) => s.styleId));
+        if (ids.has('DefaultParagraphFont') && ids.has(PLACEHOLDER_STYLE))
+            return;
+    }
+    const styles = await part.getContents();
+    const list = ((_b = styles.style) !== null && _b !== void 0 ? _b : (styles.style = []));
+    const ids = new Set(list.map((s) => s.styleId));
+    for (const style of [defaultParagraphFont(), placeholderStyle()]) {
+        if (ids.has(style.styleId))
+            continue;
+        list.push(style);
+        linkParents(style, styles);
+    }
+}