@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/content/comments.mjs

@@ -0,0 +1,248 @@
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { typeNameOf, childrenOf, runItemsOf, itemTextOf, revisionKindOf, RUN_HOLDERS } from './tree.mjs';
+/** The style Word gives a comment's paragraphs. */
+export const COMMENT_TEXT_STYLE = 'CommentText';
+/** The character style of the annotation reference run, in the comment and in the body. */
+export const COMMENT_REFERENCE_STYLE = 'CommentReference';
+/** The initials Word would show: the first letter of each word of the name, at most three. */
+export function initialsOf(author) {
+    if (author.initials)
+        return author.initials;
+    return author.name.split(/\s+/).filter((w) => w.length > 0).slice(0, 3).map((w) => w[0].toUpperCase()).join('');
+}
+let partsAccess;
+/** Registered by `src/parts/wml/comments.mts` (imported for that by `WordprocessingMLPackage`). */
+export function setCommentPartsAccess(access) {
+    partsAccess = access;
+}
+export function commentPartsAccess() {
+    if (!partsAccess)
+        throw new Docx4JException('Comments need the parts layer: import @docx4j/core-ts or @docx4j/core-ts/packages, which registers it');
+    return partsAccess;
+}
+let api;
+export function setCommentApi(implementation) {
+    api = implementation;
+}
+export function commentApi() {
+    if (!api)
+        throw new Docx4JException('The Comment views are not loaded: import @docx4j/core-ts or @docx4j/core-ts/model');
+    return api;
+}
+const COMMENT_RANGE_START = 'org_docx4j_wml.CommentRangeStart';
+const COMMENT_RANGE_END = 'org_docx4j_wml.CommentRangeEnd';
+const COMMENT_REFERENCE = 'org_docx4j_wml.R.CommentReference';
+/**
+ * Every comment marker under a container (a body, a cell, a paragraph), in document order.
+ * Deleted content (`w:del`) is not entered, as the text model does not enter it either.
+ */
+export function markersOf(container) {
+    const out = [];
+    collect(out, container);
+    return out;
+}
+/** The markers of one paragraph, with their offsets in its text. */
+export function markersOfParagraph(element, container) {
+    const out = [];
+    collect(out, undefined, { element, container });
+    return out;
+}
+function collect(out, container, paragraph) {
+    var _a;
+    const visitParagraph = (element, blockContainer) => {
+        let pos = 0;
+        const visitRuns = (items) => {
+            var _a, _b, _c;
+            if (!items)
+                return;
+            for (const el of items) {
+                const tn = typeNameOf(el);
+                if (tn === 'org_docx4j_wml.R') {
+                    const content = (_a = el.value.content) !== null && _a !== void 0 ? _a : [];
+                    for (const item of content) {
+                        if (typeNameOf(item) === COMMENT_REFERENCE) {
+                            out.push({
+                                id: item.value.id, kind: 'reference', item, owner: content,
+                                run: el, runOwner: items, paragraph: element, paragraphContainer: blockContainer, offset: pos,
+                            });
+                        }
+                        else
+                            pos += (_c = (_b = itemTextOf(item)) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0;
+                    }
+                }
+                else if (tn === COMMENT_RANGE_START || tn === COMMENT_RANGE_END) {
+                    out.push({
+                        id: el.value.id, kind: tn === COMMENT_RANGE_START ? 'start' : 'end',
+                        item: el, owner: items, paragraph: element, paragraphContainer: blockContainer, offset: pos,
+                    });
+                }
+                else if (tn !== undefined && RUN_HOLDERS.has(tn)) {
+                    visitRuns(runItemsOf(el.value));
+                }
+                else {
+                    // the accepted view, which is what the offsets are in: a w:ins and a w:moveTo hold text
+                    // and markers, a w:del and a w:moveFrom hold neither (CR-002 phase F)
+                    const kind = revisionKindOf(el);
+                    if (kind === 'ins' || kind === 'moveTo')
+                        visitRuns(runItemsOf(el.value));
+                }
+            }
+        };
+        visitRuns(runItemsOf(element.value));
+    };
+    const visitBlocks = (items) => {
+        var _a, _b, _c;
+        for (const el of items) {
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P')
+                visitParagraph(el, items);
+            else if (tn === COMMENT_RANGE_START || tn === COMMENT_RANGE_END) {
+                out.push({ id: el.value.id, kind: tn === COMMENT_RANGE_START ? 'start' : 'end', item: el, owner: items });
+            }
+            else if (typeof el.value === 'object' && el.value !== null) {
+                if (tn === 'org_docx4j_wml.Tbl') {
+                    for (const row of (_a = childrenOf(el.value)) !== null && _a !== void 0 ? _a : []) {
+                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
+                            visitBlocks((_c = childrenOf(cell.value)) !== null && _c !== void 0 ? _c : []);
+                    }
+                }
+                else {
+                    const children = childrenOf(el.value);
+                    if (children)
+                        visitBlocks(children);
+                }
+            }
+        }
+    };
+    if (paragraph)
+        visitParagraph(paragraph.element, paragraph.container);
+    else if (container)
+        visitBlocks((_a = childrenOf(container)) !== null && _a !== void 0 ? _a : []);
+}
+/** The comment ids under a container, in document order, first occurrence first. */
+export function commentIdsOf(container) {
+    const seen = new Set();
+    const out = [];
+    for (const m of markersOf(container))
+        if (!seen.has(m.id)) {
+            seen.add(m.id);
+            out.push(m.id);
+        }
+    return out;
+}
+/** Removes every marker of a comment from a body, and the reference run when nothing is left in it. */
+export function removeMarkers(container, id) {
+    var _a;
+    for (const marker of markersOf(container)) {
+        if (marker.id !== id)
+            continue;
+        const i = marker.owner.indexOf(marker.item);
+        if (i >= 0)
+            marker.owner.splice(i, 1);
+        if (marker.kind === 'reference' && marker.run && marker.runOwner) {
+            const content = (_a = marker.run.value.content) !== null && _a !== void 0 ? _a : [];
+            if (content.length === 0) {
+                const j = marker.runOwner.indexOf(marker.run);
+                if (j >= 0)
+                    marker.runOwner.splice(j, 1);
+            }
+        }
+    }
+}
+// --- ids ---
+/** The next free `w:id` for a comment: above every comment and every marker in the body. */
+export function nextCommentId(comments, container) {
+    var _a;
+    let max = -1;
+    for (const c of (_a = comments.comment) !== null && _a !== void 0 ? _a : [])
+        if (typeof c.id === 'number' && c.id > max)
+            max = c.id;
+    for (const m of markersOf(container))
+        if (m.id > max)
+            max = m.id;
+    return max + 1;
+}
+/** An 8 hex digit id, as Word writes `w14:paraId` and `w16cid:durableId` (never 0, high bit clear). */
+export function randomHexId(taken) {
+    for (let attempt = 0; attempt < 1000; attempt++) {
+        const id = (1 + Math.floor(Math.random() * 0x7ffffffe)).toString(16).toUpperCase().padStart(8, '0');
+        if (!taken(id))
+            return id;
+    }
+    throw new Docx4JException('Could not allocate a paragraph id');
+}
+/** The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. */
+export function commentParaId(comment) {
+    var _a;
+    for (const el of (_a = comment.content) !== null && _a !== void 0 ? _a : [])
+        if (typeNameOf(el) === 'org_docx4j_wml.P')
+            return el.value.paraId;
+    return undefined;
+}
+/** True when a paragraph id is already used by a comment or by a paragraph of the document. */
+export function paraIdTaken(parts, container, id) {
+    var _a, _b, _c;
+    for (const c of (_a = parts.comments.comment) !== null && _a !== void 0 ? _a : [])
+        for (const el of (_b = c.content) !== null && _b !== void 0 ? _b : []) {
+            if (typeNameOf(el) === 'org_docx4j_wml.P' && el.value.paraId === id)
+                return true;
+        }
+    let found = false;
+    const visit = (items) => {
+        var _a, _b, _c;
+        for (const el of items) {
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P') {
+                if (el.value.paraId === id)
+                    found = true;
+            }
+            else if (typeof el.value === 'object' && el.value !== null) {
+                if (tn === 'org_docx4j_wml.Tbl') {
+                    for (const row of (_a = childrenOf(el.value)) !== null && _a !== void 0 ? _a : [])
+                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
+                            visit((_c = childrenOf(cell.value)) !== null && _c !== void 0 ? _c : []);
+                }
+                else {
+                    const children = childrenOf(el.value);
+                    if (children)
+                        visit(children);
+                }
+            }
+        }
+    };
+    visit((_c = childrenOf(container)) !== null && _c !== void 0 ? _c : []);
+    return found;
+}
+// --- w15 entries ---
+/** The `w15:commentEx` entry keyed by a comment's first paragraph id. */
+export function commentExOf(parts, paraId) {
+    var _a, _b;
+    if (!paraId)
+        return undefined;
+    return ((_b = (_a = parts.commentsEx) === null || _a === void 0 ? void 0 : _a.commentEx) !== null && _b !== void 0 ? _b : []).find((e) => e.paraId === paraId);
+}
+/** Word writes `w15:done="0"` and `"1"`; `w:ST_OnOff` also allows true/false/on/off. */
+export function isDone(value) {
+    return value === '1' || value === 'true' || value === 'on';
+}
+// --- dates ---
+/** A Jsonix calendar (what `w:date` unmarshals to) as a Date; undefined when there is none. */
+export function calendarToDate(calendar) {
+    if (!calendar || calendar.year === undefined || Number.isNaN(calendar.year))
+        return undefined;
+    const num = (v, fallback = 0) => (v === undefined || Number.isNaN(v) ? fallback : v);
+    const ms = Date.UTC(calendar.year, num(calendar.month, 1) - 1, num(calendar.day, 1), num(calendar.hour), num(calendar.minute), num(calendar.second), Math.round(num(calendar.fractionalSecond) * 1000));
+    return new Date(ms - num(calendar.timezone) * 60000);
+}
+/** A Date as the UTC calendar Word writes (`2026-09-15T09:00:00Z`). */
+export function dateToCalendar(date) {
+    return {
+        year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(),
+        hour: date.getUTCHours(), minute: date.getUTCMinutes(), second: date.getUTCSeconds(),
+        fractionalSecond: 0, timezone: 0,
+    };
+}
+/** `2026-09-15T09:00:00Z`, the form Word writes in w16cex. */
+export function toUtcString(date) {
+    return `${date.toISOString().substring(0, 19)}Z`;
+}

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

@@ -1,7 +1,17 @@
 export { Body, type Address, type BlockElement, type Outline, type OutlineParagraph, type OutlineTable } from './Body.mjs';
 export { Paragraph, type Alignment } from './Paragraph.mjs';
 export { Range } from './Range.mjs';
-export { Font, type UnderlineType, type RPrHolder } from './Font.mjs';
+export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf, type BuiltInStyle } from './styles.mjs';
+export { Comment } from './Comment.mjs';
+export { List, ListItem, ListItemNotFoundError, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, type ListLevelType, type ListNumbering, type ListBullet, type StartListOptions, type ListLabel, } from './List.mjs';
+export { type Author, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
+export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
+export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
+export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture } from './InlinePicture.mjs';
+export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS, type ContentControlType, type ContentControlForm, type ContentControlAppearance } from './ContentControl.mjs';
+export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from './ooxml.mjs';
 export { type SearchOptions, searchPattern } from './search.mjs';
-export { segmentsOf, runsOf, runItemsOf, childrenOf, BLOCK_LEVEL_TYPES, runOf, paragraphOf, type TextSegment } from './tree.mjs';
-export { wml, wmlOne, p, r, t, br, tab, tbl, textOf, walk, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions } from '@docx4j/generated-objects-ts/builders/wml';
+export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
+export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget } from './TrackedChange.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, } from './tracking.mjs';
+export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions, type CellOptions, type SdtKind, type SdtForm, type SdtOptions } from '@docx4j/generated-objects-ts/builders/wml';

package/dist/model/content/index.mjs

@@ -1,9 +1,21 @@
-// The content API (CR-002 phases B and D): Office JS shapes over the docx4j tree.
+// The content API (CR-002 phases B, C, D, F and G): Office JS shapes over the docx4j tree.
 export { Body } from './Body.mjs';
 export { Paragraph } from './Paragraph.mjs';
 export { Range } from './Range.mjs';
+export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf } from './styles.mjs';
+export { Comment } from './Comment.mjs';
+// lists (CR-002 phase H)
+export { List, ListItem, ListItemNotFoundError, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, } from './List.mjs';
+export { COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font } from './Font.mjs';
+export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
+export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu } from './InlinePicture.mjs';
+export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
+export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
 export { searchPattern } from './search.mjs';
-export { segmentsOf, runsOf, runItemsOf, childrenOf, BLOCK_LEVEL_TYPES, runOf, paragraphOf } from './tree.mjs';
+export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
+// change tracking (CR-002 phase F)
+export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
 // The objects package's builders, re-exported so that one import serves the content API and the tree it works on.
-export { wml, wmlOne, p, r, t, br, tab, tbl, textOf, walk, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
+export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';

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

@@ -0,0 +1,17 @@
+import type { Part } from '../../parts/Part.mjs';
+import type { Element } from './tree.mjs';
+/** True for a flat OPC package (what Word's `insertOoxml` is given), as opposed to a bare fragment. */
+export declare function isFlatOpc(ooxml: string): boolean;
+export interface OoxmlOptions {
+    /** The DOM preprocessor (the package's MCE one), for both routes. */
+    preprocess?: (doc: Document) => void;
+    /** The part new relationships are added to: the main document part, or the header or footer. */
+    target?: Part;
+}
+/**
+ * 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.
+ */
+export declare function contentOf(ooxml: string, options?: OoxmlOptions): Promise<Element[]>;
+/** Rewrites the relationship ids the content refers to, in place. */
+export declare function rewriteRelationshipIds(value: unknown, map: Map<string, string>): void;

package/dist/model/content/ooxml.mjs

@@ -0,0 +1,214 @@
+// CR-002 phase C: insertOoxml. Word's `insertOoxml` takes a flat OPC `pkg:package` string; so
+// does this one. The incoming package's body content is taken, the parts that content references
+// through relationships (images, embedded objects, charts) are copied into the target package
+// under fresh part names and relationship ids, the references in the content are rewritten, and
+// the content is inserted. Styles and numbering are not merged (CR-002 open question 5: that is
+// what docx4j's MergeDocx does). A bare `w:p` / `w:tbl` fragment is accepted too, which is what
+// `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 { PartName } from '../../opc/PartName.mjs';
+import { ContentTypes } from '../../opc/ContentTypes.mjs';
+import { BinaryPart, ImagePart } from '../../parts/BinaryPart.mjs';
+import { isExternal } from '../../parts/RelationshipsPart.mjs';
+/** The flat OPC namespace; its presence is how a `pkg:package` is told from a fragment. */
+const PKG_NS = 'http://schemas.microsoft.com/office/2006/xmlPackage';
+/** True for a flat OPC package (what Word's `insertOoxml` is given), as opposed to a bare fragment. */
+export function isFlatOpc(ooxml) {
+    return ooxml.includes(PKG_NS);
+}
+/**
+ * Attributes that carry a relationship id. A value is rewritten only when the source package
+ * really has a relationship of that id, so numeric ids (w:bookmarkStart/@w:id, wp:docPr/@id)
+ * are never touched.
+ */
+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';
+/**
+ * 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.
+ */
+export async function contentOf(ooxml, options = {}) {
+    var _a, _b;
+    if (!isFlatOpc(ooxml)) {
+        return parseFragment(ooxml, { wrapper: 'body', preprocess: options.preprocess });
+    }
+    const target = options.target;
+    if (!target)
+        throw new Docx4JException('A pkg:package can only be inserted into a body that has a part');
+    // Imported here so that the content API does not import the packages statically: parts/wml
+    // builds Body views, and a static import back would be a cycle (CLAUDE.md).
+    const { WordprocessingMLPackage } = await import('../../packages/WordprocessingMLPackage.mjs');
+    const source = await WordprocessingMLPackage.load(ooxml, options.preprocess ? { preprocessor: options.preprocess } : {});
+    const main = source.getMainDocumentPart();
+    const document = await main.getContents();
+    const content = ((_b = (_a = document.body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []);
+    if (content.length === 0)
+        return [];
+    const rewrites = await copyReferencedParts(content, main, target);
+    if (rewrites.size > 0)
+        rewriteRelationshipIds(content, rewrites);
+    return content;
+}
+/**
+ * Copies every part the content references into the target's package and returns the mapping
+ * from the incoming relationship ids to the new ones.
+ */
+async function copyReferencedParts(content, sourcePart, target) {
+    const sourceRels = sourcePart.relationshipsPart;
+    const map = new Map();
+    if (!sourceRels)
+        return map;
+    const referenced = new Set();
+    collectRelationshipIds(content, sourceRels, referenced);
+    const copied = new Map();
+    for (const id of referenced) {
+        const rel = sourceRels.getRelationshipById(id);
+        if (!rel)
+            continue;
+        if (isExternal(rel)) {
+            map.set(id, target.getRelationshipsPart(true).addExternalRelationship(rel.type, rel.target).id);
+            continue;
+        }
+        const part = sourceRels.getPart(rel);
+        if (!part)
+            continue;
+        const newId = await copyPart(part, target, copied);
+        if (newId)
+            map.set(id, newId);
+    }
+    return map;
+}
+/** Copies a part (and, recursively, everything its own relationships target) as a target of `owner`. */
+async function copyPart(source, owner, copied) {
+    var _a;
+    const pkg = owner.package;
+    if (!pkg)
+        throw new Docx4JException('The target part is not in a package');
+    const already = copied.get(source.partName.key);
+    if (already) {
+        const rel = (_a = owner.getRelationshipsPart(true).getRel(already.partName)) !== null && _a !== void 0 ? _a : owner.addTargetPart(already, 'REUSE_EXISTING');
+        return rel.id;
+    }
+    const bytes = await source.getBytes();
+    const name = freeName(pkg, source);
+    const copy = source.contentType.startsWith('image/')
+        ? new ImagePart(name, source.contentType)
+        : new BinaryPart(name, source.contentType, source.relationshipType);
+    copy.setBytes(bytes);
+    copied.set(source.partName.key, copy);
+    const rel = owner.addTargetPart(copy);
+    const childRels = source.relationshipsPart;
+    if (childRels && childRels.size > 0) {
+        const copyRels = copy.getRelationshipsPart(true);
+        for (const child of childRels.list) {
+            if (isExternal(child)) {
+                copyRels.addExternalRelationship(child.type, child.target, child.id);
+                continue;
+            }
+            const childPart = childRels.getPart(child);
+            if (!childPart)
+                continue;
+            // The child keeps its id, so nothing inside the copied part has to be rewritten.
+            await copyChild(childPart, copy, copyRels, child.id, copied);
+        }
+    }
+    return rel.id;
+}
+async function copyChild(source, owner, rels, relId, copied) {
+    const already = copied.get(source.partName.key);
+    if (already) {
+        rels.addPart(already, 'REUSE_EXISTING', relId);
+        return;
+    }
+    const pkg = owner.package;
+    const bytes = await source.getBytes();
+    const copy = source.contentType.startsWith('image/')
+        ? new ImagePart(freeName(pkg, source), source.contentType)
+        : new BinaryPart(freeName(pkg, source), source.contentType, source.relationshipType);
+    copy.setBytes(bytes);
+    copied.set(source.partName.key, copy);
+    rels.addPart(copy, 'OVERWRITE_IF_NAME_EXISTS', relId);
+    const childRels = source.relationshipsPart;
+    if (childRels && childRels.size > 0) {
+        const copyRels = copy.getRelationshipsPart(true);
+        for (const child of childRels.list) {
+            if (isExternal(child)) {
+                copyRels.addExternalRelationship(child.type, child.target, child.id);
+                continue;
+            }
+            const childPart = childRels.getPart(child);
+            if (childPart)
+                await copyChild(childPart, copy, copyRels, child.id, copied);
+        }
+    }
+}
+/** A part name free in the package: `/word/media/imageN.ext` for images, else the source name with a suffix. */
+function freeName(pkg, source) {
+    if (source.contentType.startsWith('image/')) {
+        const ext = source.partName.extension || extensionFor(source.contentType);
+        for (let i = 1;; i++) {
+            const candidate = PartName.of(`/word/media/image${i}.${ext}`);
+            if (!pkg.getPart(candidate))
+                return candidate;
+        }
+    }
+    if (!pkg.getPart(source.partName))
+        return source.partName;
+    const name = source.partName.name;
+    const dot = name.lastIndexOf('.');
+    const stem = dot > name.lastIndexOf('/') ? name.substring(0, dot) : name;
+    const suffix = dot > name.lastIndexOf('/') ? name.substring(dot) : '';
+    for (let i = 2;; i++) {
+        const candidate = PartName.of(`${stem}${i}${suffix}`);
+        if (!pkg.getPart(candidate))
+            return candidate;
+    }
+}
+function extensionFor(contentType) {
+    const found = Object.entries({ png: ContentTypes.IMAGE_PNG, jpeg: ContentTypes.IMAGE_JPEG, gif: ContentTypes.IMAGE_GIF, bmp: ContentTypes.IMAGE_BMP, tiff: ContentTypes.IMAGE_TIFF, svg: ContentTypes.IMAGE_SVG, emf: ContentTypes.IMAGE_EMF, wmf: ContentTypes.IMAGE_WMF })
+        .find(([, ct]) => ct === contentType);
+    return found ? found[0] : 'bin';
+}
+/** Every relationship id the content refers to (typed objects and the DOM nodes kept as `any`). */
+function collectRelationshipIds(value, rels, out) {
+    visitReferences(value, (id) => {
+        if (rels.getRelationshipById(id))
+            out.add(id);
+        return undefined;
+    });
+}
+/** Rewrites the relationship ids the content refers to, in place. */
+export function rewriteRelationshipIds(value, map) {
+    visitReferences(value, (id) => map.get(id));
+}
+/**
+ * Offers every value that could be a relationship id to `rewrite`, in the typed tree and in the
+ * DOM an `xs:any` property holds (the builders' `walkAll`, objects CR-003 section 3.6); a string
+ * it returns replaces the value. Typed objects carry the id in one of `REL_ATTRIBUTES`, DOM
+ * elements in an attribute of the relationships namespace.
+ */
+function visitReferences(value, rewrite) {
+    walkAll(value, (object) => {
+        const record = object;
+        for (const key of REL_ATTRIBUTES) {
+            const item = record[key];
+            if (typeof item !== 'string')
+                continue;
+            const next = rewrite(item);
+            if (next !== undefined)
+                record[key] = next;
+        }
+    }, (node) => {
+        const attributes = node.attributes;
+        for (let i = 0; i < attributes.length; i++) {
+            const attr = attributes[i];
+            if (attr.namespaceURI === R_NS && typeof attr.value === 'string') {
+                const next = rewrite(attr.value);
+                if (next !== undefined)
+                    attr.value = next;
+            }
+        }
+    });
+}

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

@@ -0,0 +1,21 @@
+import type { OpcPackage } from '../../packages/OpcPackage.mjs';
+/** Office JS `Word.Style` values other than 'Other', in Office JS's spelling. */
+export declare const BUILT_IN_STYLES: readonly ["Normal", "Heading1", "Heading2", "Heading3", "Heading4", "Heading5", "Heading6", "Heading7", "Heading8", "Heading9", "Toc1", "Toc2", "Toc3", "Toc4", "Toc5", "Toc6", "Toc7", "Toc8", "Toc9", "FootnoteText", "Header", "Footer", "Caption", "FootnoteReference", "EndnoteReference", "EndnoteText", "Title", "Subtitle", "Hyperlink", "Strong", "Emphasis", "NoSpacing", "ListParagraph", "Quote", "IntenseQuote", "SubtleEmphasis", "IntenseEmphasis", "SubtleReference", "IntenseReference", "BookTitle", "Bibliography", "TocHeading", "TableGrid", "PlainTable1", "PlainTable2", "PlainTable3", "PlainTable4", "PlainTable5", "GridTable1Light", "ListTable1Light"];
+export type BuiltInStyle = (typeof BUILT_IN_STYLES)[number] | 'Other';
+/** Office JS's `styleBuiltIn` for a style id: the `Word.Style` value, or 'Other'. */
+export declare function builtInOf(styleId: string): BuiltInStyle;
+/**
+ * The style id for a `Word.Style` value ('Heading1'; leniently also the display name 'Heading 1'),
+ * in Word's spelling ('TOC1' for 'Toc1'). 'Other' cannot be set, as in Office JS.
+ */
+export declare function idOfBuiltIn(value: string): string;
+/** The display name of a style id, from its stored `w:name` when given ('heading 1' to 'Heading 1'). */
+export declare function displayNameOf(styleId: string, storedName?: string): string;
+/** Office JS's `style`: the display name of a style id. */
+export declare function styleNameOf(pkg: OpcPackage | undefined, styleId: string): string;
+/**
+ * The style id for what Office JS's `style` accepts: a display name ('Heading 1', 'My Style'), the
+ * stored name ('heading 1'), or, as an extension, the id itself ('Heading1'). Resolved against the
+ * styles part when it is unmarshalled, else by removing spaces.
+ */
+export declare function styleIdOf(pkg: OpcPackage | undefined, name: string): string;

package/dist/model/content/styles.mjs

@@ -0,0 +1,86 @@
+/** Office JS `Word.Style` values other than 'Other', in Office JS's spelling. */
+export const BUILT_IN_STYLES = Object.freeze([
+    'Normal', 'Heading1', 'Heading2', 'Heading3', 'Heading4', 'Heading5', 'Heading6', 'Heading7', 'Heading8', 'Heading9',
+    'Toc1', 'Toc2', 'Toc3', 'Toc4', 'Toc5', 'Toc6', 'Toc7', 'Toc8', 'Toc9',
+    'FootnoteText', 'Header', 'Footer', 'Caption', 'FootnoteReference', 'EndnoteReference', 'EndnoteText', 'Title', 'Subtitle',
+    'Hyperlink', 'Strong', 'Emphasis', 'NoSpacing', 'ListParagraph', 'Quote', 'IntenseQuote', 'SubtleEmphasis', 'IntenseEmphasis',
+    'SubtleReference', 'IntenseReference', 'BookTitle', 'Bibliography', 'TocHeading', 'TableGrid',
+    'PlainTable1', 'PlainTable2', 'PlainTable3', 'PlainTable4', 'PlainTable5', 'GridTable1Light', 'ListTable1Light',
+]);
+/**
+ * Word's ids and display names where the id is not the display name without spaces, or the name
+ * Word stores in `w:name` is not the display name (docx4j's KnownStyles.xml has the stored names).
+ */
+const DISPLAY_NAMES = Object.freeze({
+    TableNormal: 'Normal Table', NormalWeb: 'Normal (Web)', MacroText: 'Macro Text',
+    TableofAuthorities: 'Table of Authorities', TableofFigures: 'Table of Figures', TOAHeading: 'TOA Heading',
+    CommentText: 'Comment Text', CommentSubject: 'Comment Subject', CommentReference: 'Comment Reference',
+    '1ai': 'Outline List 1', '111111': 'Outline List 2', ArticleSection: 'Outline List 3',
+});
+/** Word's spelling of an id where it is not Office JS's spelling of the built-in value. */
+const WORD_IDS = Object.freeze({
+    toc1: 'TOC1', toc2: 'TOC2', toc3: 'TOC3', toc4: 'TOC4', toc5: 'TOC5', toc6: 'TOC6', toc7: 'TOC7', toc8: 'TOC8', toc9: 'TOC9',
+});
+const BUILT_IN_BY_LOWER = new Map(BUILT_IN_STYLES.map((s) => [s.toLowerCase(), s]));
+/** Office JS's `styleBuiltIn` for a style id: the `Word.Style` value, or 'Other'. */
+export function builtInOf(styleId) {
+    var _a;
+    return (_a = BUILT_IN_BY_LOWER.get(styleId.replace(/\s+/g, '').toLowerCase())) !== null && _a !== void 0 ? _a : 'Other';
+}
+/**
+ * The style id for a `Word.Style` value ('Heading1'; leniently also the display name 'Heading 1'),
+ * in Word's spelling ('TOC1' for 'Toc1'). 'Other' cannot be set, as in Office JS.
+ */
+export function idOfBuiltIn(value) {
+    var _a, _b;
+    if (value === 'Other')
+        throw new RangeError("styleBuiltIn cannot be set to 'Other'");
+    const compact = value.replace(/\s+/g, '');
+    const lower = compact.toLowerCase();
+    return (_b = (_a = WORD_IDS[lower]) !== null && _a !== void 0 ? _a : BUILT_IN_BY_LOWER.get(lower)) !== null && _b !== void 0 ? _b : compact;
+}
+/** The display name of a style id, from its stored `w:name` when given ('heading 1' to 'Heading 1'). */
+export function displayNameOf(styleId, storedName) {
+    const known = DISPLAY_NAMES[styleId];
+    if (known)
+        return known;
+    if (storedName !== undefined) {
+        // Word stores its built-in names in lower case ('heading 1', 'toc 1', 'footnote text'); a
+        // custom style keeps the case its author gave it. Built-ins are the ids Word derives from them.
+        if (storedName.replace(/\s+/g, '').toLowerCase() !== styleId.toLowerCase())
+            return storedName;
+        return storedName.replace(/(^|\s)([a-z])/g, (_, sp, c) => sp + c.toUpperCase()).replace(/^Toc\b/, 'TOC').replace(/^Toa\b/, 'TOA');
+    }
+    return styleId.replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Za-z])(?=[0-9])/g, ' ');
+}
+const stylesPartOf = (pkg) => { var _a; return (_a = pkg === null || pkg === void 0 ? void 0 : pkg.getMainPart()) === null || _a === void 0 ? void 0 : _a.styleDefinitionsPart; };
+/** The styles of the package's styles part when it is unmarshalled; nothing is unmarshalled here. */
+function stylesOf(pkg) {
+    var _a;
+    const part = stylesPartOf(pkg);
+    return (part === null || part === void 0 ? void 0 : part.isUnmarshalled) ? (_a = part.contents.style) !== null && _a !== void 0 ? _a : [] : [];
+}
+/** Office JS's `style`: the display name of a style id. */
+export function styleNameOf(pkg, styleId) {
+    var _a;
+    const style = stylesOf(pkg).find((s) => s.styleId === styleId);
+    return displayNameOf(styleId, (_a = style === null || style === void 0 ? void 0 : style.name) === null || _a === void 0 ? void 0 : _a.val);
+}
+/**
+ * The style id for what Office JS's `style` accepts: a display name ('Heading 1', 'My Style'), the
+ * stored name ('heading 1'), or, as an extension, the id itself ('Heading1'). Resolved against the
+ * styles part when it is unmarshalled, else by removing spaces.
+ */
+export function styleIdOf(pkg, name) {
+    var _a, _b, _c, _d, _e, _f;
+    const lower = name.toLowerCase();
+    for (const s of stylesOf(pkg)) {
+        if (((_a = s.styleId) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === lower || ((_c = (_b = s.name) === null || _b === void 0 ? void 0 : _b.val) === null || _c === void 0 ? void 0 : _c.toLowerCase()) === lower || (s.styleId && displayNameOf(s.styleId, (_d = s.name) === null || _d === void 0 ? void 0 : _d.val).toLowerCase() === lower))
+            return (_e = s.styleId) !== null && _e !== void 0 ? _e : name;
+    }
+    const compact = name.replace(/\s+/g, '');
+    for (const [id, display] of Object.entries(DISPLAY_NAMES))
+        if (display.toLowerCase() === lower)
+            return id;
+    return (_f = WORD_IDS[compact.toLowerCase()]) !== null && _f !== void 0 ? _f : compact;
+}