@docx4j/core-ts 0.1.3 → 0.1.5

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

@@ -1,5 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import type { ListDefinition, LevelDefinition } from '../listnumbering/definitions.mjs';
+import type { NumberingDefinitions, ListDefinition, LevelDefinition } from '../listnumbering/definitions.mjs';
 import type { Emulator } from '../listnumbering/Emulator.mjs';
 import { Font } from './Font.mjs';
 import type { Body } from './Body.mjs';
@@ -31,6 +31,38 @@ export interface ListLabel {
     /** Whether the level's `w:numFmt` is `bullet`. */
     isBullet: boolean;
 }
+/**
+ * The content API must not import `WordprocessingMLPackage` or `parts/wml` at runtime (that
+ * would be a cycle, since `parts/wml` builds the `Body` views), so the numbering part is
+ * reached by shape, as `Body.propertyResolver` and `fonts/lookup` are.
+ */
+interface NumberingPartLike {
+    readonly isUnmarshalled: boolean;
+    readonly contents: wml.Numbering;
+    readonly definitions: NumberingDefinitions;
+    getEmulator(reset?: boolean): Emulator;
+    makeLive(): wml.Numbering;
+    getContents(): Promise<wml.Numbering>;
+}
+/** As much of an `XmlPart` as the story walk reads. */
+interface StoryPartLike {
+    readonly contentType: string;
+    readonly isUnmarshalled: boolean;
+    readonly contents: unknown;
+}
+/** As much of a `MainDocumentPart` as the list views use. */
+interface MainPartLike {
+    numberingDefinitionsPart?: NumberingPartLike;
+    readonly headerParts: StoryPartLike[];
+    readonly footerParts: StoryPartLike[];
+    addTargetPart(part: unknown): unknown;
+}
+/** As much of a `WordprocessingMLPackage` as the list views use. */
+interface ListPackageLike {
+    getMainDocumentPart(): MainPartLike;
+    refreshPropertyResolver(): void;
+    refresh(): Promise<unknown>;
+}
 /**
  * The package's numbering emulator, or undefined where the document has no lists (or nothing
  * has read the numbering part: `await pkg.getBody()` builds the resolver, which reads it).
@@ -251,3 +283,39 @@ export declare function detachFromList(paragraph: Paragraph): void;
  * be unmarshalled, and a document with no numbering part gets one here (CR-002 section 17).
  */
 export declare function startNewList(paragraph: Paragraph, options?: StartListOptions): Promise<List>;
+/**
+ * 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 declare class NumberingFacade {
+    private readonly pkg;
+    constructor(pkg: ListPackageLike);
+    /**
+     * 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.
+     */
+    newList(options?: {
+        bullet?: boolean;
+    }): Promise<string>;
+    /**
+     * 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: string | number): string;
+}

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,12 +656,24 @@ 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) {
+    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');
     const abstract = deepCopy(template);
@@ -689,8 +689,27 @@ export async function startNewList(paragraph, options) {
     });
     ((_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) {
+    var _a;
+    const created = f.createNumberingNum({
+        numId: nextNumId(numbering),
+        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 +722,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 +752,58 @@ 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) {
+        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);
+        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) {
+        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);
+        this.pkg.refreshPropertyResolver();
+        return String(created);
+    }
+}
 // ----------------------------------------------------------------------------- the mechanics
 const TWIPS_PER_POINT = 20;
 /** Office JS `Word.ListNumbering` as `w:numFmt`. */

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

@@ -75,4 +75,26 @@ export declare class Range {
      * 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,6 +4,8 @@ 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';
@@ -227,6 +229,121 @@ 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);
+        const holder = hyperlinkOf({ content: [] });
+        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/index.d.mts

@@ -3,7 +3,7 @@ export { Paragraph, type Alignment } from './Paragraph.mjs';
 export { Range } from './Range.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 { List, ListItem, ListItemNotFoundError, NumberingFacade, 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';

package/dist/model/content/index.mjs

@@ -5,7 +5,7 @@ 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 { List, ListItem, ListItemNotFoundError, NumberingFacade, 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';

package/dist/model/customxml/xpath-fonto.d.mts

@@ -3,10 +3,32 @@ import type { BooleanConversionMode, XPathEngine, XPathValue } from './xpath.mjs
  * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
  * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
  * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
  */
 export declare class FontoXPathEngine implements XPathEngine {
     private module;
     private loading;
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath?: unknown);
     get isReady(): boolean;
     ready(): Promise<void>;
     select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];

package/dist/model/customxml/xpath-fonto.mjs

@@ -21,8 +21,33 @@ const ANY_TYPE = 0;
  * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
  * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
  * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
  */
 export class FontoXPathEngine {
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath) {
+        if (fontoxpath !== undefined)
+            this.module = moduleOf(fontoxpath);
+    }
     get isReady() {
         return this.module !== undefined;
     }
@@ -31,15 +56,14 @@ export class FontoXPathEngine {
         if (this.isReady)
             return;
         (_a = this.loading) !== null && _a !== void 0 ? _a : (this.loading = (async () => {
-            var _a;
             const specifier = 'fontoxpath';
             try {
-                // The published ESM build has no named exports under Node's interop, only a default.
                 const loaded = await import(/* @vite-ignore */ specifier);
-                this.module = (_a = loaded.default) !== null && _a !== void 0 ? _a : loaded;
+                this.module = moduleOf(loaded);
             }
             catch (e) {
-                throw new Docx4JException("FontoXPathEngine needs the optional peer dependency 'fontoxpath' (npm install fontoxpath)", { cause: e });
+                throw new Docx4JException("FontoXPathEngine needs the optional peer dependency 'fontoxpath' (npm install fontoxpath); "
+                    + 'in a browser or a bundle, import it yourself and pass it: new FontoXPathEngine(fontoxpath)', { cause: e });
             }
         })());
         await this.loading;
@@ -107,6 +131,20 @@ export class FontoXPathEngine {
         return this.module;
     }
 }
+/**
+ * The module, whether given as a namespace object or as a default export, checked for the one
+ * function every call goes through so that the wrong module is refused where it is passed rather
+ * than at the first evaluation.
+ */
+function moduleOf(loaded) {
+    const candidate = loaded;
+    const module = typeof (candidate === null || candidate === void 0 ? void 0 : candidate.evaluateXPath) === 'function' ? candidate : candidate === null || candidate === void 0 ? void 0 : candidate.default;
+    if (!module || typeof module.evaluateXPath !== 'function') {
+        throw new Docx4JException('FontoXPathEngine was given something that is not the fontoxpath module: '
+            + "expected its evaluateXPath, as in new FontoXPathEngine(await import('fontoxpath'))");
+    }
+    return module;
+}
 /** A FontoXPath result in the four-type union `selectValue` reports. */
 function valueOf(value) {
     var _a;

package/dist/office-js/supported.generated.mjs

@@ -179,6 +179,7 @@ export const SUBSET_MEMBERS = [
     'Range.getComments',
     'Range.getRange',
     'Range.getTrackedChanges',
+    'Range.hyperlink',
     'Range.insertComment',
     'Range.insertParagraph',
     'Range.insertText',

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -9,6 +9,7 @@ import type { Author } from '../model/content/comments.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
 import { type XPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker, type ChangeTrackingMode, type TrackingHost } from '../model/content/tracking.mjs';
+import { NumberingFacade } from '../model/content/List.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import type { Emulator } from '../model/listnumbering/Emulator.mjs';
 import type { TrackedChange } from '../model/content/TrackedChange.mjs';
@@ -161,6 +162,14 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * `customXmlParts.load()`; every node call is synchronous afterwards.
      */
     xpathEngine: XPathEngine;
+    /**
+     * The document's list definitions as verbs that need no paragraph: `newList()` and
+     * `restart(numId)` (CR-002 section 19). `Paragraph.startNewList()` and `List.restart()` are
+     * Office JS's shapes and remain; this is for a caller that holds a `w:numId` rather than a
+     * paragraph - an editor with its own document model, writing `w:numPr` itself.
+     */
+    get numbering(): NumberingFacade;
+    private numberingFacade;
     /**
      * Office JS `document.customXmlParts`: the custom XML data storage parts as views, with
      * `add`, and docx4j's `applyBindings()` / `updateFromContentControls()` (CR-002 section 3.5).

package/dist/packages/WordprocessingMLPackage.mjs

@@ -13,6 +13,7 @@ import { HeaderPart, FooterPart } from '../parts/wml/index.mjs';
 import { CustomXmlPartCollection } from '../model/customxml/CustomXmlPartCollection.mjs';
 import { DefaultXPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker } from '../model/content/tracking.mjs';
+import { NumberingFacade } from '../model/content/List.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
@@ -385,6 +386,16 @@ export class WordprocessingMLPackage extends OpcPackage {
             all.push(await part.getBody());
         return all;
     }
+    /**
+     * The document's list definitions as verbs that need no paragraph: `newList()` and
+     * `restart(numId)` (CR-002 section 19). `Paragraph.startNewList()` and `List.restart()` are
+     * Office JS's shapes and remain; this is for a caller that holds a `w:numId` rather than a
+     * paragraph - an editor with its own document model, writing `w:numPr` itself.
+     */
+    get numbering() {
+        var _a;
+        return ((_a = this.numberingFacade) !== null && _a !== void 0 ? _a : (this.numberingFacade = new NumberingFacade(this)));
+    }
     /**
      * Office JS `document.customXmlParts`: the custom XML data storage parts as views, with
      * `add`, and docx4j's `applyBindings()` / `updateFromContentControls()` (CR-002 section 3.5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",