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

package/dist/{server-BaHNZNu1.d.mts → server-DbbWqWoz.d.mts}

@@ -345,9 +345,10 @@ declare class BookmarkCollection extends HandleCollection<Bookmark> {
  *
  * 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`.
+ * these actually occur as published objects — insert, delete, replace, the two property kinds and
+ * the two move halves. Structural cards whose exact Word subtype this API cannot name are omitted
+ * from `items`; collection-wide decisions still resolve every store-resolvable revision. 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. */
@@ -483,12 +484,11 @@ declare class CommentCollection extends HandleCollection<Comment> {
     protected promised(label: string, nullable: boolean): Comment & PromisedItem;
 }
 /**
- * One tracked change, and a decision the engine can act on.
+ * One tracked change, published when this API can name its Word subtype.
  *
- * 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.
+ * Structural cards whose exact Word subtype cannot be typed — a row, a cell, a section, the table
+ * grid — are omitted from the collection rather than shipped as objects with an unpublishable
+ * `type`. That listing is not the collection decision set: see {@link RevisionCollection}.
  *
  * @public
  */
@@ -521,24 +521,24 @@ declare class Revision extends ModelObject implements PromisedItem {
 /**
  * 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.
+ * `items` omits structural cards whose Word subtype this API cannot name; see {@link Revision}.
+ * Collection-wide `acceptAll` / `rejectAll` still resolve every store-resolvable revision in this
+ * story and refuse atomically if any `readOnly` or otherwise unsupported revision remains.
  *
  * @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;
+    static of(context: RequestContext, label: string, owner: ObjectPath, body: AutomationHandle): RevisionCollection;
     private constructor();
     /**
-     * Keep every change, as ONE decision and one undo unit.
+     * Keep every change in this story, 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.
+     * Resolves every store-resolvable revision in the story, including complete tracked rows
+     * omitted from `items`. Refuses the sync outright where any `readOnly` or otherwise
+     * unsupported revision remains, rather than reporting the story as reviewed while pending
+     * changes remain.
      */
     acceptAll(): void;
     /** Undo every change, likewise as one decision. */
@@ -1298,12 +1298,12 @@ declare class Document extends ModelObject {
     /** The comments anchored in the main story, in document order. */
     get comments(): CommentCollection;
     /**
-     * The tracked changes of the main story that the engine can resolve.
+     * The tracked changes of the main-body story that this API can publish as typed objects.
      *
-     * Structural changes — a row, a cell, a section, the table grid — are not in it: they are ones the
-     * engine refuses to accept or reject, and an item whose two verbs both refuse would stall code
-     * walking the collection. `acceptAll`/`rejectAll` refuse outright where the document holds one,
-     * rather than reporting a document as reviewed while pending changes remain.
+     * Structural cards whose exact Word subtype cannot be named are omitted from `items`.
+     * `acceptAll` / `rejectAll` still resolve every store-resolvable revision in the main body
+     * and refuse atomically if any `readOnly` or otherwise unsupported revision remains. Header,
+     * footer, and note revisions live on those stories' own `Body.revisions` collections.
      */
     get revisions(): RevisionCollection;
     /**
@@ -1369,7 +1369,11 @@ interface DocxEditorRuntime {
  * @public
  */
 interface DocxEditorServerRuntime extends DocxEditorRuntime {
-    /** The current document as DOCX bytes. */
+    /**
+     * The current document as a fresh, caller-owned DOCX byte array.
+     *
+     * Mutating or transferring the returned array does not change this runtime or a later save.
+     */
     save(): Promise<Uint8Array>;
 }
 
@@ -1965,11 +1969,12 @@ declare class Body extends ModelObject {
     /** The comments anchored in this story, in document order. Replies hang off the comment. */
     getComments(): CommentCollection;
     /**
-     * The tracked changes in this story that the engine can resolve, in document order.
+     * The tracked changes in this story that this API can publish as typed objects, in document order.
      *
      * DocxEditor's own accessor: upstream reaches revisions from the document, and this story-scoped
-     * one is what makes a header's or a note's changes reachable at all. Recorded in
-     * `compat/manifest.json`.
+     * collection is what makes a header's, footer's, or note's changes reachable at all. Recorded in
+     * `compat/manifest.json`. `items` may omit structural cards; collection-wide decisions still
+     * resolve every store-resolvable revision in this story.
      */
     get revisions(): RevisionCollection;
     /** Every occurrence of `searchText` in this story, as ranges, in reading order. */
@@ -2020,6 +2025,9 @@ interface DocumentLimits {
  * they did not author gets "not a document this API can open", so a probe cannot use the error to
  * learn the reader's limits.
  *
+ * The bounded parse is complete when this promise resolves. The runtime does not retain the
+ * caller's `Uint8Array`, so the caller may reuse or transfer that input buffer afterward.
+ *
  * @public
  */
 interface CreateServerOptions {

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

@@ -345,9 +345,10 @@ declare class BookmarkCollection extends HandleCollection<Bookmark> {
  *
  * 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`.
+ * these actually occur as published objects — insert, delete, replace, the two property kinds and
+ * the two move halves. Structural cards whose exact Word subtype this API cannot name are omitted
+ * from `items`; collection-wide decisions still resolve every store-resolvable revision. 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. */
@@ -483,12 +484,11 @@ declare class CommentCollection extends HandleCollection<Comment> {
     protected promised(label: string, nullable: boolean): Comment & PromisedItem;
 }
 /**
- * One tracked change, and a decision the engine can act on.
+ * One tracked change, published when this API can name its Word subtype.
  *
- * 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.
+ * Structural cards whose exact Word subtype cannot be typed — a row, a cell, a section, the table
+ * grid — are omitted from the collection rather than shipped as objects with an unpublishable
+ * `type`. That listing is not the collection decision set: see {@link RevisionCollection}.
  *
  * @public
  */
@@ -521,24 +521,24 @@ declare class Revision extends ModelObject implements PromisedItem {
 /**
  * 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.
+ * `items` omits structural cards whose Word subtype this API cannot name; see {@link Revision}.
+ * Collection-wide `acceptAll` / `rejectAll` still resolve every store-resolvable revision in this
+ * story and refuse atomically if any `readOnly` or otherwise unsupported revision remains.
  *
  * @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;
+    static of(context: RequestContext, label: string, owner: ObjectPath, body: AutomationHandle): RevisionCollection;
     private constructor();
     /**
-     * Keep every change, as ONE decision and one undo unit.
+     * Keep every change in this story, 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.
+     * Resolves every store-resolvable revision in the story, including complete tracked rows
+     * omitted from `items`. Refuses the sync outright where any `readOnly` or otherwise
+     * unsupported revision remains, rather than reporting the story as reviewed while pending
+     * changes remain.
      */
     acceptAll(): void;
     /** Undo every change, likewise as one decision. */
@@ -1298,12 +1298,12 @@ declare class Document extends ModelObject {
     /** The comments anchored in the main story, in document order. */
     get comments(): CommentCollection;
     /**
-     * The tracked changes of the main story that the engine can resolve.
+     * The tracked changes of the main-body story that this API can publish as typed objects.
      *
-     * Structural changes — a row, a cell, a section, the table grid — are not in it: they are ones the
-     * engine refuses to accept or reject, and an item whose two verbs both refuse would stall code
-     * walking the collection. `acceptAll`/`rejectAll` refuse outright where the document holds one,
-     * rather than reporting a document as reviewed while pending changes remain.
+     * Structural cards whose exact Word subtype cannot be named are omitted from `items`.
+     * `acceptAll` / `rejectAll` still resolve every store-resolvable revision in the main body
+     * and refuse atomically if any `readOnly` or otherwise unsupported revision remains. Header,
+     * footer, and note revisions live on those stories' own `Body.revisions` collections.
      */
     get revisions(): RevisionCollection;
     /**
@@ -1369,7 +1369,11 @@ interface DocxEditorRuntime {
  * @public
  */
 interface DocxEditorServerRuntime extends DocxEditorRuntime {
-    /** The current document as DOCX bytes. */
+    /**
+     * The current document as a fresh, caller-owned DOCX byte array.
+     *
+     * Mutating or transferring the returned array does not change this runtime or a later save.
+     */
     save(): Promise<Uint8Array>;
 }
 
@@ -1965,11 +1969,12 @@ declare class Body extends ModelObject {
     /** The comments anchored in this story, in document order. Replies hang off the comment. */
     getComments(): CommentCollection;
     /**
-     * The tracked changes in this story that the engine can resolve, in document order.
+     * The tracked changes in this story that this API can publish as typed objects, in document order.
      *
      * DocxEditor's own accessor: upstream reaches revisions from the document, and this story-scoped
-     * one is what makes a header's or a note's changes reachable at all. Recorded in
-     * `compat/manifest.json`.
+     * collection is what makes a header's, footer's, or note's changes reachable at all. Recorded in
+     * `compat/manifest.json`. `items` may omit structural cards; collection-wide decisions still
+     * resolve every store-resolvable revision in this story.
      */
     get revisions(): RevisionCollection;
     /** Every occurrence of `searchText` in this story, as ranges, in reading order. */
@@ -2020,6 +2025,9 @@ interface DocumentLimits {
  * they did not author gets "not a document this API can open", so a probe cannot use the error to
  * learn the reader's limits.
  *
+ * The bounded parse is complete when this promise resolves. The runtime does not retain the
+ * caller's `Uint8Array`, so the caller may reuse or transfer that input buffer afterward.
+ *
  * @public
  */
 interface CreateServerOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx-editor.dev/editor-api",
-  "version": "2.3.1",
+  "version": "2.4.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.3.1"
+    "@docx-editor.dev/core": "^2.4.1"
   }
 }