@docx4j/core-ts 0.1.4 → 0.2.0

package/dist/model/content/List.mjs

@@ -398,22 +398,10 @@ export class List {
      * Extension name (Office JS has no restart verb); `Paragraph.restartList()` is the sugar.
      */
     restart() {
-        var _a, _b, _c;
-        const numbering = this.live();
-        const num = this.element;
-        const start = (_b = (_a = this.level(0)) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1;
-        const created = f.createNumberingNum({
-            numId: nextNumId(numbering),
-            abstractNumId: f.createNumberingNumAbstractNumId({ val: num.abstractNumId.val }),
-            lvlOverride: [f.createNumberingNumLvlOverride({
-                    ilvl: 0,
-                    startOverride: f.createNumberingNumLvlOverrideStartOverride({ val: start }),
-                })],
-        });
-        ((_c = numbering.num) !== null && _c !== void 0 ? _c : (numbering.num = [])).push(created);
-        linkParents(created, numbering);
+        var _a, _b;
+        const numId = addRestartedNum(this.live(), this.element.abstractNumId.val, (_b = (_a = this.level(0)) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1);
         this.written();
-        return new List(String(created.numId), this.body);
+        return new List(String(numId), this.body);
     }
     /**
      * Gives this list a `w:abstractNum` of its own where another `w:num` shares the one it names
@@ -668,29 +656,66 @@ export function detachFromList(paragraph) {
  * be unmarshalled, and a document with no numbering part gets one here (CR-002 section 17).
  */
 export async function startNewList(paragraph, options) {
-    var _a, _b, _c, _d, _e;
+    var _a, _b;
     const body = paragraph.parentBody;
     const part = await ensureNumberingPart(body);
+    const numId = await addListDefinition(part, (options === null || options === void 0 ? void 0 : options.bullet) === true);
+    (_a = packageOf(body)) === null || _a === void 0 ? void 0 : _a.refreshPropertyResolver();
+    return attachToList(paragraph, numId, (_b = options === null || options === void 0 ? void 0 : options.level) !== null && _b !== void 0 ? _b : 0);
+}
+/**
+ * A `w:abstractNum` copied from docx4j's default definitions (its `numbering.xml` resource:
+ * `w:abstractNum` 1 is Word's decimal set and 0 its bullet set) and a `w:num` naming it; the new
+ * `w:numId`. The paragraph half of `startNewList` is separate because it is separable: nothing
+ * about building a list definition needs one.
+ */
+async function addListDefinition(part, bullet, ids) {
+    var _a, _b, _c;
     const numbering = await part.getContents();
     const defaults = await defaultNumbering();
-    const template = ((_a = defaults.abstractNum) !== null && _a !== void 0 ? _a : [])[(options === null || options === void 0 ? void 0 : options.bullet) === true ? 0 : 1];
+    const template = ((_a = defaults.abstractNum) !== null && _a !== void 0 ? _a : [])[bullet ? 0 : 1];
     if (template === undefined)
         throw new Docx4JException('The default numbering definitions are missing an abstractNum');
+    // both identifiers are settled before anything is written, so a clash leaves the part as it was
+    // (CR-002 section 31: an orphan w:abstractNum was saved for every refused numId)
+    const abstractNumId = (ids === null || ids === void 0 ? void 0 : ids.abstractNumId) === undefined
+        ? nextAbstractNumId(numbering)
+        : requireFreeId(numbering, 'abstractNumId', ids.abstractNumId);
+    const numId = (ids === null || ids === void 0 ? void 0 : ids.numId) === undefined ? nextNumId(numbering) : requireFreeId(numbering, 'numId', ids.numId);
     const abstract = deepCopy(template);
-    abstract.abstractNumId = nextAbstractNumId(numbering);
+    abstract.abstractNumId = abstractNumId;
     abstract.nsid = f.createCTLongHexNumber({ val: hexId() });
     delete abstract.styleLink;
     delete abstract.numStyleLink;
     ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : (numbering.abstractNum = [])).push(abstract);
     linkParents(abstract, numbering);
     const num = f.createNumberingNum({
-        numId: nextNumId(numbering),
-        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstract.abstractNumId }),
+        numId,
+        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstractNumId }),
     });
     ((_c = numbering.num) !== null && _c !== void 0 ? _c : (numbering.num = [])).push(num);
     linkParents(num, numbering);
-    (_d = packageOf(body)) === null || _d === void 0 ? void 0 : _d.refreshPropertyResolver();
-    return attachToList(paragraph, num.numId, (_e = options === null || options === void 0 ? void 0 : options.level) !== null && _e !== void 0 ? _e : 0);
+    return num.numId;
+}
+/**
+ * A `w:num` naming the same `w:abstractNum` as another, with a `w:startOverride` at level 0; the
+ * new `w:numId`. The counters are shared by abstract definition, so this is how Word restarts a
+ * list (CR-001 section 15.2), and it is what {@link List.restart} and
+ * {@link NumberingFacade.restart} both do.
+ */
+function addRestartedNum(numbering, abstractNumId, start, newNumId) {
+    var _a;
+    const created = f.createNumberingNum({
+        numId: newNumId === undefined ? nextNumId(numbering) : requireFreeId(numbering, 'numId', newNumId),
+        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstractNumId }),
+        lvlOverride: [f.createNumberingNumLvlOverride({
+                ilvl: 0,
+                startOverride: f.createNumberingNumLvlOverrideStartOverride({ val: start }),
+            })],
+    });
+    ((_a = numbering.num) !== null && _a !== void 0 ? _a : (numbering.num = [])).push(created);
+    linkParents(created, numbering);
+    return created.numId;
 }
 /**
  * The numbering part, created with docx4j's default numbering where the document has none
@@ -703,6 +728,14 @@ async function ensureNumberingPart(body) {
     if (pkg === undefined || main === undefined) {
         throw new Docx4JException('This body has no package, so a list cannot be added to it');
     }
+    return ensureNumberingPartOf(pkg, main);
+}
+/**
+ * The same, reached from the package rather than from a body, which is what
+ * {@link NumberingFacade} uses: creating a list definition needs no paragraph and no body, and
+ * making one go through either costs a caller that holds neither (CR-002 section 19).
+ */
+async function ensureNumberingPartOf(pkg, main) {
     const existing = main.numberingDefinitionsPart;
     if (existing !== undefined) {
         // the resolver read the part privately; unmarshalling it gives a second tree, so the
@@ -725,6 +758,63 @@ async function ensureNumberingPart(body) {
     await pkg.refresh();
     return created;
 }
+/**
+ * The document's list definitions, as verbs that need no paragraph (CR-002 section 19, at the
+ * editor's request): `pkg.numbering`.
+ *
+ * `Paragraph.startNewList()` and `List.restart()` are Office JS's shapes and stay as they are,
+ * but both build a definition first and touch a paragraph only at the end. An editor that keeps
+ * its own document model has the numbering part and a `w:numId` to write, and nothing else - and
+ * going through a paragraph would mean projecting a tree, running the verb and projecting back,
+ * a whole-body round trip for what is otherwise one attribute. So the definition half is here.
+ */
+export class NumberingFacade {
+    constructor(pkg) {
+        this.pkg = pkg;
+    }
+    /**
+     * A new list definition, and its `w:numId` as a string for a `w:numPr` to name. The numbering
+     * part is created with docx4j's default definitions where the document has none, and an
+     * existing one is unmarshalled so that what is written to it is saved.
+     *
+     * Asynchronous for the same reasons `startNewList` is: the default definitions are XML to be
+     * unmarshalled, and the part may have to be created. Nothing is attached to anything; the
+     * caller writes `w:numPr` itself.
+     */
+    async newList(options) {
+        // the form is checked before a numbering part can be created for a call that is then refused
+        if ((options === null || options === void 0 ? void 0 : options.numId) !== undefined)
+            requireIdForm('numId', options.numId);
+        if ((options === null || options === void 0 ? void 0 : options.abstractNumId) !== undefined)
+            requireIdForm('abstractNumId', options.abstractNumId);
+        const main = this.pkg.getMainDocumentPart();
+        const part = await ensureNumberingPartOf(this.pkg, main);
+        const numId = await addListDefinition(part, (options === null || options === void 0 ? void 0 : options.bullet) === true, options);
+        this.pkg.refreshPropertyResolver();
+        return String(numId);
+    }
+    /**
+     * A `w:num` that numbers as `numId` does but starts again, and its own `w:numId`:
+     * `List.restart()` without needing a `Body`. The counters are shared by abstract definition,
+     * so restarting means a new `w:num` with a `w:startOverride`, spent on its first use in a
+     * story (CR-001 section 15.2).
+     *
+     * Synchronous, so the numbering part must have been read: `await pkg.getPropertyResolver()`,
+     * `newList()` or any list read does it.
+     */
+    restart(numId, options) {
+        var _a, _b;
+        const part = this.pkg.getMainDocumentPart().numberingDefinitionsPart;
+        if (part === undefined)
+            throw new Docx4JException('This document has no numbering part, so there is no list to restart');
+        const definition = part.definitions.list(numId);
+        if (definition === undefined)
+            throw new ItemNotFound(`No w:num for numId ${numId}`);
+        const created = addRestartedNum(part.makeLive(), definition.num.abstractNumId.val, (_b = (_a = definition.level('0')) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1, options === null || options === void 0 ? void 0 : options.newNumId);
+        this.pkg.refreshPropertyResolver();
+        return String(created);
+    }
+}
 // ----------------------------------------------------------------------------- the mechanics
 const TWIPS_PER_POINT = 20;
 /** Office JS `Word.ListNumbering` as `w:numFmt`. */
@@ -761,6 +851,34 @@ function nextNumId(numbering) {
     var _a;
     return ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).reduce((max, num) => Math.max(max, Number(num.numId)), 0) + 1;
 }
+/**
+ * A chosen identifier in range: a `w:numId` from 1, since 0 is what a `w:numPr` says to mean "not
+ * numbered" (`detachFromList` writes it, and Word and the Emulator read it so), and a
+ * `w:abstractNumId` from 0 (CR-002 section 31).
+ */
+function requireIdForm(kind, chosen) {
+    const id = Number(chosen);
+    const least = kind === 'numId' ? 1 : 0;
+    if (!Number.isInteger(id) || id < least) {
+        throw new Docx4JException(`A ${kind} must be an integer from ${least}, not ${String(chosen)}`);
+    }
+    return id;
+}
+/**
+ * A chosen identifier, checked unused, as `addExternalRelationship`'s proposed id is. A clash throws
+ * rather than renumbering: a caller who names an id is asserting something about a room's state, and
+ * quietly moving it would break the peer that named it (CR-002 section 24).
+ */
+function requireFreeId(numbering, kind, chosen) {
+    var _a, _b;
+    const id = requireIdForm(kind, chosen);
+    const taken = kind === 'numId'
+        ? ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).some((num) => Number(num.numId) === id)
+        : ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : []).some((a) => Number(a.abstractNumId) === id);
+    if (taken)
+        throw new Docx4JException(`The ${kind} ${id} is already in use in this document's numbering part`);
+    return id;
+}
 /** A free `w:abstractNumId`. */
 function nextAbstractNumId(numbering) {
     var _a;

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

@@ -7,6 +7,7 @@ import type { Body, BlockElement } from './Body.mjs';
 import { type TableCell } from './Table.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
+import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
 import { type ChangeTracker } from './tracking.mjs';
 import { TrackedChange } from './TrackedChange.mjs';
@@ -160,6 +161,15 @@ export declare class Paragraph {
     insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
     /** Matches within this paragraph. */
     search(text: string, options?: SearchOptions): Range[];
+    /**
+     * `search`, keeping each match's capture groups, which is what a replacement's `$1` or Word's `\1`
+     * expands from (CR-002 section 26). Not an Office JS member; `replaceText` is its only caller here
+     * and `Body.replaceText` the other.
+     */
+    searchMatches(text: string, options?: SearchOptions): {
+        range: Range;
+        match: RegExpExecArray;
+    }[];
     /**
      * Replaces every match of `find` with `replace`, last match first so that the offsets of the
      * ones still to do stay valid (CR-002 section 3.7). Returns the number replaced; tracked when
@@ -261,7 +271,7 @@ export declare class Paragraph {
     /** The comments anchored in this paragraph, replies nested under their parent. */
     getComments(): Promise<Comment[]>;
     /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
-    insertComment(text: string): Promise<Comment>;
+    insertComment(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /**
      * Wraps this paragraph in a new block-level content control (Office JS
      * `Paragraph.insertContentControl`), typed for the kind when one is given. The `w:id` is free in

package/dist/model/content/Paragraph.mjs

@@ -10,7 +10,7 @@ function withRPr(run, rPr) {
 import { Font } from './Font.mjs';
 import { runFontSelectorOf } from '../fonts/lookup.mjs';
 import { Range } from './Range.mjs';
-import { searchPattern, findAll } from './search.mjs';
+import { searchPattern, matchesOf, expandReplacement } from './search.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { cellOf } from './Table.mjs';
 import { ContentControl, collectRunControls } from './ContentControl.mjs';
@@ -336,7 +336,16 @@ export class Paragraph {
     }
     /** Matches within this paragraph. */
     search(text, options) {
-        return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this, s, e));
+        return this.searchMatches(text, options).map((m) => m.range);
+    }
+    /**
+     * `search`, keeping each match's capture groups, which is what a replacement's `$1` or Word's `\1`
+     * expands from (CR-002 section 26). Not an Office JS member; `replaceText` is its only caller here
+     * and `Body.replaceText` the other.
+     */
+    searchMatches(text, options) {
+        return matchesOf(this.text, searchPattern(text, options))
+            .map((match) => ({ range: new Range(this, match.index, match.index + match[0].length), match }));
     }
     /**
      * Replaces every match of `find` with `replace`, last match first so that the offsets of the
@@ -344,9 +353,11 @@ export class Paragraph {
      * the package's `changeTrackingMode` is on.
      */
     replaceText(find, replace, options) {
-        const matches = this.search(find, options);
-        for (let i = matches.length - 1; i >= 0; i--)
-            matches[i].insertText(replace, 'Replace');
+        const matches = this.searchMatches(find, options);
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const { range, match } = matches[i];
+            range.insertText(expandReplacement(replace, match, options), 'Replace');
+        }
         return matches.length;
     }
     /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
@@ -672,8 +683,8 @@ export class Paragraph {
         return commentApi().commentsOf(this);
     }
     /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
-    async insertComment(text) {
-        return commentApi().insertComment(this.getRange(), text);
+    async insertComment(content, options) {
+        return commentApi().insertComment(this.getRange(), content, options);
     }
     // --- content controls (CR-002 phase E) ---
     /**

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

@@ -5,6 +5,7 @@ import type { BlockElement } from './Body.mjs';
 import { type Element, type TextViewOptions } from './tree.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { type SearchOptions } from './search.mjs';
+import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
 import type { TrackedChange } from './TrackedChange.mjs';
 /**
@@ -54,7 +55,11 @@ export declare class Range {
     /** Removes the span's text. */
     delete(): void;
     search(text: string, options?: SearchOptions): Range[];
-    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    /**
+     * Replaces every match in this span, last first so the offsets stay valid; returns the count
+     * (CR-002 section 3.7). The replacement's `$1` or Word's `\1` expands as it does on a paragraph
+     * (section 26; this one was missed there, section 31).
+     */
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /** The tracked changes this span covers, in document order (CR-002 phase F). */
     getTrackedChanges(): TrackedChange[];
@@ -68,11 +73,33 @@ export declare class Range {
      * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
      * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
      */
-    insertComment(text: string): Promise<Comment>;
+    insertComment(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /**
      * Wraps the runs this span covers in a run-level content control (Office JS
      * `Range.insertContentControl`), splitting the runs at the boundaries as `font` does. An empty
      * span gets an empty control at its position. Returns the control.
      */
     insertContentControl(kind?: ContentControlType): ContentControl;
+    /**
+     * Office JS `Range.hyperlink`: the address of the first hyperlink in this range, or a new
+     * hyperlink over it. `address#location` separates the address from an optional location within
+     * it, so `"#heading"` is a link inside this document (a `w:anchor`) and
+     * `"https://example.com"` an external one (a relationship). Reading gives `""` where the range
+     * is in no hyperlink.
+     *
+     * Setting removes the hyperlinks the range already carries and wraps its runs in one
+     * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
+     * setting `""` removes them and wraps nothing. An external address becomes a relationship of
+     * this range's part, which is why the part must exist (CR-002 section 20).
+     */
+    get hyperlink(): string;
+    set hyperlink(value: string);
+    /** The `w:hyperlink` this range's first run sits in, if any. */
+    private hyperlinkHolder;
+    /** Unwraps every `w:hyperlink` the range touches, keeping its runs where they are. */
+    private removeHyperlinks;
+    /** The target of a relationship of this range's part, for the getter. */
+    private relationshipTarget;
+    /** An external relationship of this range's part for the address, and its id. */
+    private addHyperlinkRelationship;
 }

package/dist/model/content/Range.mjs

@@ -4,9 +4,11 @@ import { typeNameOf, linkParents, runItemsOf } from './tree.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { ContentControl } from './ContentControl.mjs';
 import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
+import { hyperlink as hyperlinkOf } from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { Namespaces } from '../../parts/Namespaces.mjs';
 import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 import { contentOf } from './ooxml.mjs';
-import { searchPattern, findAll } from './search.mjs';
+import { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
@@ -149,11 +151,19 @@ export class Range {
         const base = this.start;
         return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this.paragraph, base + s, base + e));
     }
-    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    /**
+     * Replaces every match in this span, last first so the offsets stay valid; returns the count
+     * (CR-002 section 3.7). The replacement's `$1` or Word's `\1` expands as it does on a paragraph
+     * (section 26; this one was missed there, section 31).
+     */
     replaceText(find, replace, options) {
-        const matches = this.search(find, options);
-        for (let i = matches.length - 1; i >= 0; i--)
-            matches[i].insertText(replace, 'Replace');
+        const base = this.start;
+        const matches = matchesOf(this.text, searchPattern(find, options));
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const match = matches[i];
+            new Range(this.paragraph, base + match.index, base + match.index + match[0].length)
+                .insertText(expandReplacement(replace, match, options), 'Replace');
+        }
         return matches.length;
     }
     /** The tracked changes this span covers, in document order (CR-002 phase F). */
@@ -186,8 +196,8 @@ export class Range {
      * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
      * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
      */
-    async insertComment(text) {
-        return commentApi().insertComment(this, text);
+    async insertComment(content, options) {
+        return commentApi().insertComment(this, content, options);
     }
     // --- content controls (CR-002 phase E) ---
     /**
@@ -227,6 +237,126 @@ export class Range {
         linkParents(sdt, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
         return new ContentControl(sdt, owner, body);
     }
+    /**
+     * Office JS `Range.hyperlink`: the address of the first hyperlink in this range, or a new
+     * hyperlink over it. `address#location` separates the address from an optional location within
+     * it, so `"#heading"` is a link inside this document (a `w:anchor`) and
+     * `"https://example.com"` an external one (a relationship). Reading gives `""` where the range
+     * is in no hyperlink.
+     *
+     * Setting removes the hyperlinks the range already carries and wraps its runs in one
+     * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
+     * setting `""` removes them and wraps nothing. An external address becomes a relationship of
+     * this range's part, which is why the part must exist (CR-002 section 20).
+     */
+    get hyperlink() {
+        var _a;
+        const holder = this.hyperlinkHolder();
+        if (holder === undefined)
+            return '';
+        const anchor = (_a = holder.value.anchor) !== null && _a !== void 0 ? _a : '';
+        const address = holder.value.id === undefined ? '' : this.relationshipTarget(holder.value.id);
+        return anchor === '' ? address : `${address}#${anchor}`;
+    }
+    set hyperlink(value) {
+        var _a;
+        const paragraph = this.paragraph;
+        this.removeHyperlinks();
+        if (value === '')
+            return;
+        const hash = value.indexOf('#');
+        const address = hash === -1 ? value : value.slice(0, hash);
+        const location = hash === -1 ? '' : value.slice(hash + 1);
+        // w:history="1" is what Word writes on every hyperlink it makes, and what docx4j writes when
+        // it builds one (MainDocumentPart.addHyperlink): "add the target to the viewed hyperlinks"
+        // (ECMA-376 17.16.22). Readers do not depend on it, but a document holding one holder from
+        // each source should not differ over it. Found by the docx4j-ts-editor session, ED-003
+        // section 11.8.
+        const holder = hyperlinkOf({ content: [], history: true });
+        if (location !== '')
+            holder.value.anchor = location;
+        if (address !== '')
+            holder.value.id = this.addHyperlinkRelationship(address);
+        if (this.start === this.end) {
+            paragraph.insertItemsAt(this.start, [holder]);
+            return;
+        }
+        paragraph.splitAt(this.start);
+        paragraph.splitAt(this.end);
+        const segments = paragraph.segments().filter((seg) => seg.start >= this.start && seg.end <= this.end);
+        if (segments.length === 0)
+            throw new Docx4JException('This range covers no run');
+        const owner = segments[0].runOwner;
+        if (segments.some((seg) => seg.runOwner !== owner)) {
+            throw new Docx4JException('This range spans more than one run holder (a hyperlink or a tracked change); wrap a narrower span');
+        }
+        const items = [];
+        for (const segment of segments) {
+            const element = owner[segment.runIndex];
+            if (!items.includes(element))
+                items.push(element);
+        }
+        const at = owner.indexOf(items[0]);
+        holder.value.content = items;
+        owner.splice(at, items.length, holder);
+        linkParents(holder, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
+    }
+    /** The `w:hyperlink` this range's first run sits in, if any. */
+    hyperlinkHolder() {
+        for (const segment of this.paragraph.segments()) {
+            if (segment.end <= this.start && this.start !== this.end)
+                continue;
+            if (segment.start >= this.end && this.start !== this.end)
+                break;
+            const parent = segment.run.PARENT;
+            const found = hyperlinkHolders(this.paragraph).find((h) => h.value === parent);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    /** Unwraps every `w:hyperlink` the range touches, keeping its runs where they are. */
+    removeHyperlinks() {
+        var _a, _b, _c;
+        for (const holder of hyperlinkHolders(this.paragraph)) {
+            const owner = containerOf(holder, this.paragraph);
+            const at = owner.indexOf(holder);
+            if (at === -1)
+                continue;
+            owner.splice(at, 1, ...((_a = holder.value.content) !== null && _a !== void 0 ? _a : []));
+            for (const item of ((_b = holder.value.content) !== null && _b !== void 0 ? _b : [])) {
+                linkParents(item, (_c = holder.PARENT) !== null && _c !== void 0 ? _c : this.paragraph.p);
+            }
+        }
+    }
+    /** The target of a relationship of this range's part, for the getter. */
+    relationshipTarget(id) {
+        var _a, _b, _c;
+        const part = this.paragraph.parentBody.part;
+        return (_c = (_b = (_a = part === null || part === void 0 ? void 0 : part.relationshipsPart) === null || _a === void 0 ? void 0 : _a.getRelationshipById(id)) === null || _b === void 0 ? void 0 : _b.target) !== null && _c !== void 0 ? _c : '';
+    }
+    /** An external relationship of this range's part for the address, and its id. */
+    addHyperlinkRelationship(address) {
+        const part = this.paragraph.parentBody.part;
+        if (!part)
+            throw new Docx4JException('This range has no part, so a hyperlink cannot be related to it');
+        return part.getRelationshipsPart(true).addExternalRelationship(Namespaces.HYPERLINK, address).id;
+    }
+}
+/** Every `w:hyperlink` of a paragraph, outermost first (they do not nest in practice). */
+function hyperlinkHolders(paragraph) {
+    const out = [];
+    const visit = (items) => {
+        for (const item of items !== null && items !== void 0 ? items : []) {
+            if (typeNameOf(item) === 'org_docx4j_wml.P.Hyperlink')
+                out.push(item);
+            const value = item.value;
+            if (typeof value === 'object' && value !== null)
+                visit(runItemsOf(value));
+        }
+    };
+    visit(runItemsOf(paragraph.p));
+    return out;
 }
 /** The run-level array holding an element, after `insertItemsAt` put it somewhere in the paragraph. */
 function containerOf(element, paragraph) {

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

@@ -0,0 +1,44 @@
+import { type Jsonix } from '@docx4j/generated-objects-ts';
+/** What an XPath selected, and the tree object behind it (CR-006 section 2). */
+export interface Bound {
+    /**
+     * The DOM node the expression selected. It is in a snapshot marshalled for this call, so changing
+     * it changes nothing: edits go through the content API or `setContents`, never here.
+     */
+    node: Node;
+    /**
+     * The tree object: for an element, what a walk of the typed tree would hand you at that path,
+     * never a `{ name, value }` wrapper; for an attribute or a text node, the object of the element
+     * that owns it. Undefined for an element the model does not build - a wildcard child is its own
+     * object, so this is undefined only above the root or for a node the marshal did not report.
+     */
+    object: unknown;
+    /** Set when an attribute was selected: its qualified name on `object`'s element. */
+    attribute?: string;
+    /** The node's path from the part's root, `/w:document/w:body/w:p[3]/w:r[2]`. */
+    path: string;
+}
+/** A marshalled snapshot and the element-to-object map recorded while it was written. */
+export interface BoundSnapshot {
+    root: Element;
+    /** The object each element was marshalled from; a wildcard child maps to the original tree node. */
+    objects: WeakMap<Element, unknown>;
+}
+/**
+ * Marshals a root element and records what each DOM element came from. One marshal per call: the
+ * tree has no change log a cached snapshot could be checked against, and a stale answer is worse
+ * than a slow one (docx4j's `refreshXmlFirst`, always true here). The editor measured 349 to 411 ms
+ * for a 255-page main document part, against 975 ms for its first unmarshal, and runs a selection
+ * on Enter - so no cache is needed, which is what CR-006 section 2 was uncertain about.
+ */
+export declare function bindSnapshot<T>(element: Jsonix.TypedNamedValue<T>): Promise<BoundSnapshot>;
+/** Turns selected nodes into `Bound`s against a snapshot. */
+export declare function boundsOf(nodes: readonly Node[], snapshot: BoundSnapshot): Bound[];
+/**
+ * The node's path from the document element, in the prefixed form the part itself uses, with a
+ * position on every step: `/w:document/w:body/w:p[3]/w:r[2]`, and `/@w:val` for an attribute. The
+ * position counts siblings of the same qualified name, as XPath does, and is written even when
+ * there is only one - a path that is stable whether or not a sibling is added later is worth more
+ * than a short one, and docx4j's harness records the same form.
+ */
+export declare function pathOf(node: Node): string;