@docx-editor.dev/editor-api 2.2.1 → 2.3.1

package/dist/{server-C3dcanDU.d.ts → server-BaHNZNu1.d.ts}

@@ -234,19 +234,19 @@ declare class Font extends ModelObject {
     static of(context: RequestContext, label: string, owner: ObjectPath, kind: SpanOwner): Font;
     private constructor();
     /** Whether every character agrees it is bold, or `null` where they do not. */
-    get bold(): boolean;
+    get bold(): boolean | null;
     set bold(value: boolean);
     /** Whether every run in range is italic. `null` where they disagree or none says. */
-    get italic(): boolean;
+    get italic(): boolean | null;
     set italic(value: boolean);
     /** `#RRGGBB`. `null` where the characters disagree, or where the colour is `auto`. */
-    get color(): string;
+    get color(): string | null;
     set color(value: string);
     /** The typeface name the characters state, or `null` where they do not agree on one. */
-    get name(): string;
+    get name(): string | null;
     set name(value: string);
     /** Points. */
-    get size(): number;
+    get size(): number | null;
     set size(value: number);
     /**
      * One read for every property asked for.
@@ -308,7 +308,13 @@ declare class Bookmark extends ModelObject implements PromisedItem {
      * was loaded.
      */
     get range(): Range;
-    /** Put the reader's selection on the bookmark. `NotSupported` where there is no reader. */
+    /**
+     * Put the reader's selection on the bookmark and navigate the editor viewport to it.
+     *
+     * The bookmark's current range is resolved as part of the selection, so callers do not need to
+     * read {@link Bookmark.range} first. `Start` and `End` collapse to that endpoint. Refused with
+     * `NotSupported` where there is no reader.
+     */
     select(selectionMode_?: SelectionMode): void;
     /** @internal Plan the read this object's `load(...)` asked for. */
     protected onLoad(request: ResolvedLoadOptions): void;
@@ -334,6 +340,219 @@ declare class BookmarkCollection extends HandleCollection<Bookmark> {
     protected promised(label: string, nullable: boolean): Bookmark & PromisedItem;
 }
 
+/**
+ * Word's own names for a kind of change.
+ *
+ * The WHOLE upstream vocabulary, because a declaration says what a caller may be handed and a caller
+ * switching on it should not have to be told which subset this engine happens to produce. Seven of
+ * these actually occur — insert, delete, replace, the two property kinds and the two move halves —
+ * because a change to a row, a cell or a section is structural, and this engine reports only the
+ * changes it can also accept or reject. See `compat/manifest.json`.
+ */
+type RevisionType = 'None' | 'Insert' | 'Delete' | 'Property' | 'ParagraphNumber' | 'DisplayField' | 'Reconcile' | 'Conflict' | 'Style' | 'Replace' | 'ParagraphProperty' | 'TableProperty' | 'SectionProperty' | 'StyleDefinition' | 'MovedFrom' | 'MovedTo' | 'CellInsertion' | 'CellDeletion' | 'CellMerge' | 'CellSplit' | 'ConflictInsert' | 'ConflictDelete';
+/** What a comment and a reply both are: an author, a date, an id and a body. */
+declare abstract class CommentBase extends ModelObject implements PromisedItem {
+    /** @internal Bind this object to the address the owning read answered. */
+    hydrateAddress(address: ObjectAddress): void;
+    /** @internal Settle as the null object: the read found nothing to name. */
+    hydrateNull(): void;
+    /** Who wrote it. Always present: `CT_TrackChange` makes the author mandatory. */
+    get authorName(): string;
+    /** When it was written, or `null` where the file recorded no valid date. */
+    get creationDate(): Date | null;
+    /** The document's own id for it (`w:id` in the comments part). */
+    get id(): string;
+    /**
+     * What it says, as plain text.
+     *
+     * DocxEditor's own member rather than upstream's `content`: upstream declares that one writable,
+     * and rewriting a comment body is not an operation this engine offers, so publishing a read-only
+     * `content` under the same name would be a quieter divergence than a differently named read.
+     */
+    get text(): string;
+    /**
+     * Delete this comment object.
+     *
+     * On a top-level comment this removes the whole thread and its anchors. On a reply it removes
+     * only that reply, preserving the parent and siblings. Several deletes queued before one
+     * `sync()` commit atomically as one undo unit.
+     */
+    delete(): void;
+    protected loadCommentFields(request: ResolvedLoadOptions, extra: readonly string[]): void;
+    protected commentHandle(): AutomationHandle;
+}
+/**
+ * One answer in a comment thread.
+ *
+ * Authored over the parent comment's own range, because that is where the conversation is
+ * anchored and OOXML gives a reply no other place to be. Resolving is a property of the whole
+ * thread rather than of any one reply — see {@link Comment.resolved}.
+ *
+ * @public
+ */
+declare class CommentReply extends CommentBase {
+    /** @internal A reply a read has already named. */
+    static at(context: RequestContext, label: string, address: ObjectAddress): CommentReply;
+    /** @internal A reply a queued operation will name, or report as nothing. */
+    static promised(context: RequestContext, label: string, nullable: boolean): CommentReply;
+    private constructor();
+    /** @internal Plan the read this object's `load(...)` asked for. */
+    protected onLoad(request: ResolvedLoadOptions): void;
+}
+/**
+ * The replies to one comment, in thread order, as of the batch that loaded them.
+ *
+ * @public
+ */
+declare class CommentReplyCollection extends HandleCollection<CommentReply> {
+    #private;
+    /** @internal The replies to one comment, in document order. */
+    static of(context: RequestContext, label: string, owner: ObjectPath, plan: () => AutomationOperation): CommentReplyCollection;
+    private constructor();
+    /** The first reply. `ItemNotFound` at the sync if nobody answered. */
+    getFirst(): CommentReply;
+    /** @internal The read that answers this collection's members. */
+    protected listing(): AutomationOperation;
+    /** @internal Build one member from an address the listing answered. */
+    protected itemAt(label: string, address: ObjectAddress): CommentReply;
+    /** @internal A member an edge accessor named before the sync that finds it. */
+    protected promised(label: string, nullable: boolean): CommentReply & PromisedItem;
+}
+/**
+ * A comment: a conversation about a stretch of the document, not a single remark.
+ *
+ * {@link Comment.replies} holds the answers, and resolving is a property of the whole thread —
+ * assigning `resolved` marks this comment and everything answering it, which is what Word's own
+ * pane does.
+ *
+ * `authorEmail` and a writable `content` are absent: `CT_Comment` records only an author and
+ * initials (Word's addresses live in `people.xml`, which this API does not read), and a body
+ * rewrite is not an operation the canonical write path offers. The comment's text is published
+ * as `text`.
+ *
+ * @public
+ */
+declare class Comment extends CommentBase {
+    #private;
+    /** @internal A comment a read has already named. */
+    static at(context: RequestContext, label: string, address: ObjectAddress): Comment;
+    /** @internal A comment a queued operation will name, or report as nothing. */
+    static promised(context: RequestContext, label: string, nullable: boolean): Comment;
+    private constructor();
+    /**
+     * Whether the thread is resolved.
+     *
+     * Assigning it resolves or reopens the WHOLE thread — this comment and its replies — because that
+     * is what resolving a conversation means, and marking the parent alone would leave a reply reading
+     * as open under a closed remark.
+     */
+    get resolved(): boolean;
+    set resolved(value: boolean);
+    /** The answers to this comment, in document order. */
+    get replies(): CommentReplyCollection;
+    /** The words the comment is about. */
+    getRange(): Range;
+    /**
+     * Answer the comment, over the same words it is anchored to.
+     *
+     * The author is the one the request context was opened with: a reply records who wrote it, and
+     * `CT_TrackChange` makes that mandatory, so a context with no author refuses here rather than
+     * writing an anonymous remark the file cannot represent.
+     */
+    reply(replyText: string): CommentReply;
+    /** @internal Plan the read this object's `load(...)` asked for. */
+    protected onLoad(request: ResolvedLoadOptions): void;
+}
+/**
+ * The comments on a document, story or range, as of the batch that loaded them.
+ *
+ * @public
+ */
+declare class CommentCollection extends HandleCollection<Comment> {
+    #private;
+    /** @internal The comments of a scope: a whole story's, or the ones a range overlaps. */
+    static of(context: RequestContext, label: string, owner: ObjectPath, plan: () => AutomationOperation): CommentCollection;
+    private constructor();
+    /** The first comment. `ItemNotFound` at the sync if there are none. */
+    getFirst(): Comment;
+    /** @internal The read that answers this collection's members. */
+    protected listing(): AutomationOperation;
+    /** @internal Build one member from an address the listing answered. */
+    protected itemAt(label: string, address: ObjectAddress): Comment;
+    /** @internal A member an edge accessor named before the sync that finds it. */
+    protected promised(label: string, nullable: boolean): Comment & PromisedItem;
+}
+/**
+ * One tracked change, and a decision the engine can act on.
+ *
+ * Only revisions the engine can actually resolve are answered as objects. Structural ones — a
+ * row, a cell, a section, the table grid — are omitted from the collection entirely rather than
+ * shipped as objects whose `accept` and `reject` both refuse: code walking the collection would
+ * stall on such an item with nothing to read that explains why.
+ *
+ * @public
+ */
+declare class Revision extends ModelObject implements PromisedItem {
+    #private;
+    /** @internal A change a read has already named. */
+    static at(context: RequestContext, label: string, address: ObjectAddress): Revision;
+    /** @internal A change a queued read will name, or report as nothing. */
+    static promised(context: RequestContext, label: string, nullable: boolean): Revision;
+    private constructor();
+    /** @internal Bind this object to the address the owning read answered. */
+    hydrateAddress(address: ObjectAddress): void;
+    /** @internal Settle as the null object: the read found nothing to name. */
+    hydrateNull(): void;
+    /** Who proposed the change. */
+    get author(): string;
+    /** When they proposed it, or `null` where the file recorded no valid date. */
+    get date(): Date | null;
+    /** What kind of change it is, by Word's own name for it. */
+    get type(): RevisionType;
+    /** The words the change covers. */
+    get range(): Range;
+    /** Keep the change, resolving every site that carries its identity in one transaction. */
+    accept(): void;
+    /** Undo the change, likewise in one transaction. */
+    reject(): void;
+    /** @internal Plan the read this object's `load(...)` asked for. */
+    protected onLoad(request: ResolvedLoadOptions): void;
+}
+/**
+ * The tracked changes on a document, story or range, as of the batch that loaded them.
+ *
+ * Carries only the revisions the engine can resolve; see {@link Revision} for what is left out
+ * and why.
+ *
+ * @public
+ */
+declare class RevisionCollection extends HandleCollection<Revision> {
+    #private;
+    /** @internal The pending decisions of one story. */
+    static of(context: RequestContext, label: string, owner: ObjectPath, body: AutomationHandle, document: AutomationHandle): RevisionCollection;
+    private constructor();
+    /**
+     * Keep every change, as ONE decision and one undo unit.
+     *
+     * The engine's own whole-document operation rather than a loop over `accept`: a reviewer who
+     * accepted a document's changes made one decision, and one undo should take all of them back. It
+     * refuses outright where the document holds a change the engine cannot resolve, which is the
+     * honest answer — accepting the rest would report a document as reviewed while it still carries
+     * pending changes.
+     */
+    acceptAll(): void;
+    /** Undo every change, likewise as one decision. */
+    rejectAll(): void;
+    /** @internal The read that answers this collection's members. */
+    protected listing(): AutomationOperation;
+    /** @internal Build one member from an address the listing answered. */
+    protected itemAt(label: string, address: ObjectAddress): Revision;
+    /** @internal A member an edge accessor named before the sync that finds it. */
+    protected promised(label: string, nullable: boolean): Revision & PromisedItem;
+    /** A collection is a `ClientObject` rather than a `ModelObject`, so it queues its own writes. */
+    private commandOn;
+}
+
 /**
  * How a search is narrowed.
  *
@@ -435,14 +654,27 @@ declare class Range extends ModelObject implements PromisedItem {
      * gets back is a range naming the text that was written, in every case.
      */
     insertText(text: string, insertLocation: 'Replace' | 'Start' | 'End' | 'Before' | 'After'): Range;
+    /**
+     * Create a top-level comment anchored to exactly this range.
+     *
+     * The author is the identity the runtime was opened with. Empty comment text, a missing author,
+     * stale endpoints, and ranges crossing a table-cell boundary are refused rather than authored
+     * approximately. A collapsed range creates an insertion-point comment.
+     */
+    insertComment(commentText: string): Comment;
     /** Add a paragraph before or after the one this range starts or ends in. */
     insertParagraph(paragraphText: string, insertLocation: 'Before' | 'After'): Paragraph;
     /**
-     * Put the reader's selection on this range.
+     * Put the reader's selection on this range and navigate the editor viewport to it.
+     *
+     * The whole range is selected by default. `Start` and `End` instead collapse the caret to that
+     * endpoint and reveal it. An already-visible endpoint stays still; an offscreen one is brought
+     * into view from the editor's layout, including when its page has not been materialized yet.
      *
      * Refused with `NotSupported` where there is no reader — a document opened from bytes on a
-     * server has no caret, and moving one would be a claim about a screen nobody is looking at. The
-     * check is at the CALL rather than at the sync, so the mistake is reported where it was made.
+     * server has no caret or viewport, and moving one would be a claim about a screen nobody is
+     * looking at. The check is at the CALL rather than at the sync, so the mistake is reported where
+     * it was made.
      */
     select(selectionMode_?: SelectionMode): void;
     /** @internal Plan the read this object's `load(...)` asked for. */
@@ -710,6 +942,15 @@ declare class ContentControl extends ModelObject implements PromisedItem {
     set title(value: string);
     /** What kind of control it is: `plainText`, `dropDownList`, `checkbox`, `date`, … */
     get subtype(): string;
+    /**
+     * Whether the control currently declares an OOXML data binding.
+     *
+     * This is advisory preflight for callers choosing controls to write. A document can change
+     * after this property is loaded, so the atomic sync-time refusal remains the final authority.
+     * Only binding presence is exposed: XPath, namespace mappings, store ids, and custom XML
+     * content remain inside the untrusted-document boundary.
+     */
+    get isBound(): boolean;
     /**
      * Whether the control refuses to be deleted.
      *
@@ -750,7 +991,9 @@ declare class ContentControl extends ModelObject implements PromisedItem {
      *
      * The refusals belong to the document, not to this method: a locked control, a control the file
      * bound to custom XML, and a value the control's type does not accept are all refused by the
-     * engine's single write path, which is the same path a keystroke takes.
+     * engine's single write path, which is the same path a keystroke takes. {@link isBound} is an
+     * advisory preflight only; this sync-time check remains authoritative if the document changed
+     * after the flag was loaded.
      */
     setValue(value: ContentControlValue): void;
     /**
@@ -844,6 +1087,14 @@ declare class NoteItem extends ModelObject implements PromisedItem {
     hydrateNull(): void;
     /** Whether this is a footnote or an endnote. */
     get type(): NoteItemType;
+    /**
+     * The note's plain text.
+     *
+     * This is the same value as loading `text` from {@link NoteItem.body}: every paragraph in the
+     * note story, in reading order, joined by one carriage return per paragraph mark. Load it
+     * directly when structured traversal or editing through {@link NoteItem.body} is not needed.
+     */
+    get text(): string;
     /** The note's own story. */
     get body(): Body;
     /**
@@ -881,211 +1132,6 @@ declare class NoteItemCollection extends HandleCollection<NoteItem> {
     protected promised(label: string, nullable: boolean): NoteItem & PromisedItem;
 }
 
-/**
- * Word's own names for a kind of change.
- *
- * The WHOLE upstream vocabulary, because a declaration says what a caller may be handed and a caller
- * switching on it should not have to be told which subset this engine happens to produce. Seven of
- * these actually occur — insert, delete, replace, the two property kinds and the two move halves —
- * because a change to a row, a cell or a section is structural, and this engine reports only the
- * changes it can also accept or reject. See `compat/manifest.json`.
- */
-type RevisionType = 'None' | 'Insert' | 'Delete' | 'Property' | 'ParagraphNumber' | 'DisplayField' | 'Reconcile' | 'Conflict' | 'Style' | 'Replace' | 'ParagraphProperty' | 'TableProperty' | 'SectionProperty' | 'StyleDefinition' | 'MovedFrom' | 'MovedTo' | 'CellInsertion' | 'CellDeletion' | 'CellMerge' | 'CellSplit' | 'ConflictInsert' | 'ConflictDelete';
-/** What a comment and a reply both are: an author, a date, an id and a body. */
-declare abstract class CommentBase extends ModelObject implements PromisedItem {
-    /** @internal Bind this object to the address the owning read answered. */
-    hydrateAddress(address: ObjectAddress): void;
-    /** @internal Settle as the null object: the read found nothing to name. */
-    hydrateNull(): void;
-    /** Who wrote it. Always present: `CT_TrackChange` makes the author mandatory. */
-    get authorName(): string;
-    /** When it was written, or `null` where the file recorded no date. */
-    get creationDate(): Date;
-    /** The document's own id for it (`w:id` in the comments part). */
-    get id(): string;
-    /**
-     * What it says, as plain text.
-     *
-     * DocxEditor's own member rather than upstream's `content`: upstream declares that one writable,
-     * and rewriting a comment body is not an operation this engine offers, so publishing a read-only
-     * `content` under the same name would be a quieter divergence than a differently named read.
-     */
-    get text(): string;
-    protected loadCommentFields(request: ResolvedLoadOptions, extra: readonly string[]): void;
-    protected commentHandle(): AutomationHandle;
-}
-/**
- * One answer in a comment thread.
- *
- * Authored over the parent comment's own range, because that is where the conversation is
- * anchored and OOXML gives a reply no other place to be. Resolving is a property of the whole
- * thread rather than of any one reply — see {@link Comment.resolved}.
- *
- * @public
- */
-declare class CommentReply extends CommentBase {
-    /** @internal A reply a read has already named. */
-    static at(context: RequestContext, label: string, address: ObjectAddress): CommentReply;
-    /** @internal A reply a queued operation will name, or report as nothing. */
-    static promised(context: RequestContext, label: string, nullable: boolean): CommentReply;
-    private constructor();
-    /** @internal Plan the read this object's `load(...)` asked for. */
-    protected onLoad(request: ResolvedLoadOptions): void;
-}
-/**
- * The replies to one comment, in thread order, as of the batch that loaded them.
- *
- * @public
- */
-declare class CommentReplyCollection extends HandleCollection<CommentReply> {
-    #private;
-    /** @internal The replies to one comment, in document order. */
-    static of(context: RequestContext, label: string, owner: ObjectPath, plan: () => AutomationOperation): CommentReplyCollection;
-    private constructor();
-    /** The first reply. `ItemNotFound` at the sync if nobody answered. */
-    getFirst(): CommentReply;
-    /** @internal The read that answers this collection's members. */
-    protected listing(): AutomationOperation;
-    /** @internal Build one member from an address the listing answered. */
-    protected itemAt(label: string, address: ObjectAddress): CommentReply;
-    /** @internal A member an edge accessor named before the sync that finds it. */
-    protected promised(label: string, nullable: boolean): CommentReply & PromisedItem;
-}
-/**
- * A comment: a conversation about a stretch of the document, not a single remark.
- *
- * {@link Comment.replies} holds the answers, and resolving is a property of the whole thread —
- * assigning `resolved` marks this comment and everything answering it, which is what Word's own
- * pane does.
- *
- * `authorEmail`, a writable `content`, and `delete` are absent: `CT_Comment` records only an
- * author and initials (Word's addresses live in `people.xml`, which this API does not read), and
- * neither a body rewrite nor a marker-pair removal is an operation the canonical write path
- * offers. The comment's text is published as `text`.
- *
- * @public
- */
-declare class Comment extends CommentBase {
-    #private;
-    /** @internal A comment a read has already named. */
-    static at(context: RequestContext, label: string, address: ObjectAddress): Comment;
-    /** @internal A comment a queued operation will name, or report as nothing. */
-    static promised(context: RequestContext, label: string, nullable: boolean): Comment;
-    private constructor();
-    /**
-     * Whether the thread is resolved.
-     *
-     * Assigning it resolves or reopens the WHOLE thread — this comment and its replies — because that
-     * is what resolving a conversation means, and marking the parent alone would leave a reply reading
-     * as open under a closed remark.
-     */
-    get resolved(): boolean;
-    set resolved(value: boolean);
-    /** The answers to this comment, in document order. */
-    get replies(): CommentReplyCollection;
-    /** The words the comment is about. */
-    getRange(): Range;
-    /**
-     * Answer the comment, over the same words it is anchored to.
-     *
-     * The author is the one the request context was opened with: a reply records who wrote it, and
-     * `CT_TrackChange` makes that mandatory, so a context with no author refuses here rather than
-     * writing an anonymous remark the file cannot represent.
-     */
-    reply(replyText: string): CommentReply;
-    /** @internal Plan the read this object's `load(...)` asked for. */
-    protected onLoad(request: ResolvedLoadOptions): void;
-}
-/**
- * The comments on a document, story or range, as of the batch that loaded them.
- *
- * @public
- */
-declare class CommentCollection extends HandleCollection<Comment> {
-    #private;
-    /** @internal The comments of a scope: a whole story's, or the ones a range overlaps. */
-    static of(context: RequestContext, label: string, owner: ObjectPath, plan: () => AutomationOperation): CommentCollection;
-    private constructor();
-    /** The first comment. `ItemNotFound` at the sync if there are none. */
-    getFirst(): Comment;
-    /** @internal The read that answers this collection's members. */
-    protected listing(): AutomationOperation;
-    /** @internal Build one member from an address the listing answered. */
-    protected itemAt(label: string, address: ObjectAddress): Comment;
-    /** @internal A member an edge accessor named before the sync that finds it. */
-    protected promised(label: string, nullable: boolean): Comment & PromisedItem;
-}
-/**
- * One tracked change, and a decision the engine can act on.
- *
- * Only revisions the engine can actually resolve are answered as objects. Structural ones — a
- * row, a cell, a section, the table grid — are omitted from the collection entirely rather than
- * shipped as objects whose `accept` and `reject` both refuse: code walking the collection would
- * stall on such an item with nothing to read that explains why.
- *
- * @public
- */
-declare class Revision extends ModelObject implements PromisedItem {
-    #private;
-    /** @internal A change a read has already named. */
-    static at(context: RequestContext, label: string, address: ObjectAddress): Revision;
-    /** @internal A change a queued read will name, or report as nothing. */
-    static promised(context: RequestContext, label: string, nullable: boolean): Revision;
-    private constructor();
-    /** @internal Bind this object to the address the owning read answered. */
-    hydrateAddress(address: ObjectAddress): void;
-    /** @internal Settle as the null object: the read found nothing to name. */
-    hydrateNull(): void;
-    /** Who proposed the change. */
-    get author(): string;
-    /** When they proposed it, or `null` where the file recorded no date. */
-    get date(): Date;
-    /** What kind of change it is, by Word's own name for it. */
-    get type(): RevisionType;
-    /** The words the change covers. */
-    get range(): Range;
-    /** Keep the change, resolving every site that carries its identity in one transaction. */
-    accept(): void;
-    /** Undo the change, likewise in one transaction. */
-    reject(): void;
-    /** @internal Plan the read this object's `load(...)` asked for. */
-    protected onLoad(request: ResolvedLoadOptions): void;
-}
-/**
- * The tracked changes on a document, story or range, as of the batch that loaded them.
- *
- * Carries only the revisions the engine can resolve; see {@link Revision} for what is left out
- * and why.
- *
- * @public
- */
-declare class RevisionCollection extends HandleCollection<Revision> {
-    #private;
-    /** @internal The pending decisions of one story. */
-    static of(context: RequestContext, label: string, owner: ObjectPath, body: AutomationHandle, document: AutomationHandle): RevisionCollection;
-    private constructor();
-    /**
-     * Keep every change, as ONE decision and one undo unit.
-     *
-     * The engine's own whole-document operation rather than a loop over `accept`: a reviewer who
-     * accepted a document's changes made one decision, and one undo should take all of them back. It
-     * refuses outright where the document holds a change the engine cannot resolve, which is the
-     * honest answer — accepting the rest would report a document as reviewed while it still carries
-     * pending changes.
-     */
-    acceptAll(): void;
-    /** Undo every change, likewise as one decision. */
-    rejectAll(): void;
-    /** @internal The read that answers this collection's members. */
-    protected listing(): AutomationOperation;
-    /** @internal Build one member from an address the listing answered. */
-    protected itemAt(label: string, address: ObjectAddress): Revision;
-    /** @internal A member an edge accessor named before the sync that finds it. */
-    protected promised(label: string, nullable: boolean): Revision & PromisedItem;
-    /** A collection is a `ClientObject` rather than a `ModelObject`, so it queues its own writes. */
-    private commandOn;
-}
-
 /**
  * Which way round a page is, in Word's own spelling.
  *
@@ -1215,12 +1261,19 @@ declare class SectionCollection extends HandleCollection<Section> {
  * ```ts
  * await runtime.run(async (context) => {
  *   const paragraphs = context.document.paragraphs;
- *   paragraphs.load('text');
+ *   paragraphs.load('items');
+ *   await context.sync();
+ *
+ *   for (const paragraph of paragraphs.items) paragraph.load('text');
  *   await context.sync();
+ *
  *   for (const paragraph of paragraphs.items) console.log(paragraph.text);
  * });
  * ```
  *
+ * The first sync retrieves the collection's items. Once those items are available, the second
+ * sync retrieves each paragraph's text.
+ *
  * @public
  */
 declare class Document extends ModelObject {
@@ -1484,7 +1537,10 @@ interface RuntimeManagedObject {
 interface LoadQueryOptions {
     /** Which properties to load. */
     readonly select?: string | readonly string[];
-    /** Which navigation properties to load along with them. */
+    /**
+     * Reserved for Office.js source compatibility. Navigation-property expansion is not supported
+     * yet: a non-empty value is refused as `InvalidArgument`. Omit it or pass an empty array.
+     */
     readonly expand?: string | readonly string[];
     /** For a collection: at most this many items. */
     readonly top?: number;
@@ -1499,16 +1555,18 @@ interface LoadQueryOptions {
  * ```ts
  * paragraph.load('text');
  * paragraph.load(['text', 'style']);
- * paragraphs.load({ select: ['text'], top: 5 });
+ * paragraphs.load({ select: 'items', top: 5 });
  * ```
  *
+ * Collections load their `items`; properties such as `text` are loaded on each item after the
+ * collection has been synced.
+ *
  * @public
  */
 type LoadOption = string | readonly string[] | LoadQueryOptions;
 interface ResolvedLoadOptions {
     /** Selected property names. Empty means "this object's default set". */
     readonly select: readonly string[];
-    readonly expand: readonly string[];
     readonly top?: number;
     readonly skip?: number;
 }
@@ -1867,6 +1925,14 @@ declare class Body extends ModelObject {
     get text(): string;
     /** Every paragraph in this story in reading order, at every depth. */
     get paragraphs(): ParagraphCollection;
+    /**
+     * Every bookmark declared in this story, in document order.
+     *
+     * This is story-scoped: `document.body.bookmarks` covers only the main body story. A header,
+     * footer or note body answers its own bookmarks through that body's accessor; this collection
+     * does not aggregate bookmarks from other stories.
+     */
+    get bookmarks(): BookmarkCollection;
     /** The character formatting of the whole story: what all of it agrees on, and what a write sets. */
     get font(): Font;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx-editor.dev/editor-api",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Document automation for DOCX: a batching object model that drives a document from a server or from an editor already open in a page",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -73,6 +73,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@docx-editor.dev/core": "^2.2.1"
+    "@docx-editor.dev/core": "^2.3.1"
   }
 }