@ansonlai/docx-redline-js 0.8.2 → 0.8.4

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -465,7 +465,7 @@ fragment to insert. Do not choose a type from its English name alone.
 | Change native list structure | `{ type: 'list-change', target, modified: '<complete Markdown list>' }` |
 | Reconcile a Word table | `{ type: 'table-reconciliation', target, modified: '<complete Markdown table>' }` |
 | Comment or highlight existing text | `comment` with `commentContent`, or `highlight` with `textToHighlight` |
-| Change character or paragraph formatting | `character-format`/`format` with `textToFormat` and `properties`, or `paragraph-format` with `properties` |
+| Change character or paragraph formatting | `character-format`/`format` with `textToFormat` and `properties`, or `paragraph-format` with `properties`; add `textOccurrence` (1-based, default 1) to format a later match of `textToFormat` inside the targeted paragraph (out of range fails `PATCH_SOURCE_NOT_FOUND`; independent of `target.occurrence`, which selects the paragraph; legacy calls without `textOccurrence` still read `target.occurrence`; capability `format-text-occurrence-v1`) |
 | Counterpropose a paragraph wholly deleted by another author | `restore` with a rejected-view target |
 | Insert text inside another author's rejected-view content | `insert` with `target.revisionView: 'rejected'`, an exact `anchor`, and `existingRevisions: 'slice-cross-author'` |
 
@@ -514,6 +514,9 @@ revision markup internally before writing, so do not add `preflight` or baseline
 2. Build one final operation per target. Use complete `modified` text for broad
    semantic revisions or localized `replacements` for small literal changes in
    an inspected target. Consolidate multiple changes to one paragraph.
+   Paragraphs with soft line breaks (`\n` in `exactText`) accept `replacements`
+   whose `find` lies within one line; the breaks are preserved. A `find` or
+   `replace` that spans or adds a line break is refused.
 3. Run `apply` once per stable batch. Independent strong targets bind against
    the batch-start document and do not need bottom-up sorting. Use captures only
    for intentional created-content dependencies.

package/docs/schemas/document-operations.schema.json

@@ -1,168 +1,168 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/AnsonLai/docx-redline-js/docs/schemas/document-operations.schema.json",
-  "title": "docx-redline document operations",
-  "oneOf": [
-    { "$ref": "#/$defs/operationArray" },
-    {
-      "type": "object",
-      "required": ["operations"],
-      "properties": {
-        "operations": { "$ref": "#/$defs/operationArray" },
-        "expectedRevision": { "$ref": "#/$defs/revisionToken" }
-      },
-      "additionalProperties": false
-    }
-  ],
-  "$defs": {
-    "revisionToken": {
-      "type": "object",
-      "required": ["algorithm", "version", "scope", "value"],
-      "properties": {
-        "algorithm": { "type": "string", "enum": ["sha256"] },
-        "version": { "type": "integer", "enum": [1] },
-        "scope": { "type": "string", "enum": ["document-parts", "package"] },
-        "value": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" },
-        "coveredParts": { "type": "array", "items": { "type": "string" } }
-      },
-      "additionalProperties": false
-    },
-    "operationArray": { "type": "array", "items": { "$ref": "#/$defs/operation" } },
-    "rejectedTextInsertionAnchor": {
-      "type": "object",
-      "required": ["exactText", "offset"],
-      "properties": {
-        "exactText": { "type": "string", "minLength": 1 },
-        "occurrence": { "type": "integer", "minimum": 1 },
-        "offset": { "type": "integer", "minimum": 0 }
-      },
-      "additionalProperties": false
-    },
-    "localizedReplacement": {
-      "type": "object",
-      "required": ["find", "replace"],
-      "properties": {
-        "find": { "type": "string", "minLength": 1 },
-        "replace": { "type": "string" },
-        "occurrence": { "type": "integer", "minimum": 1 }
-      },
-      "additionalProperties": false
-    },
-    "target": {
-      "oneOf": [
-        { "type": "string", "minLength": 1 },
-        {
-          "type": "object",
-          "properties": {
-            "exactText": { "type": "string" }, "text": { "type": "string" },
-            "index": { "type": ["integer", "string"] }, "paragraphIndex": { "type": ["integer", "string"] },
-            "paragraphId": { "type": "string" }, "occurrence": { "type": "integer", "minimum": 1 },
-            "inTable": { "type": "boolean" }, "fingerprint": { "type": "string" }, "sourceFingerprint": { "type": "string" },
-            "revisionView": {
-              "type": "string",
-              "enum": ["accepted", "rejected"],
-              "description": "Defaults to rejected for restore operations and accepted for other operation types."
-            },
-            "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 },
-            "select": { "type": "string", "minLength": 1 }
-          },
-          "additionalProperties": false,
-          "anyOf": [ { "required": ["exactText"] }, { "required": ["text"] }, { "required": ["index"] }, { "required": ["paragraphIndex"] }, { "required": ["paragraphId"] }, { "required": ["fingerprint"] }, { "required": ["sourceFingerprint"] }, { "required": ["captureRef"] } ]
-        }
-      ]
-    },
-    "headerFooterPart": {
-      "description": "Targets a header or footer instead of the body. Use a part path from inspect().headersFooters, or a selector. Comments are not supported in headers or footers.",
-      "oneOf": [
-        { "type": "string", "minLength": 1, "examples": ["word/footer2.xml"] },
-        {
-          "type": "object",
-          "required": ["kind"],
-          "properties": {
-            "kind": { "enum": ["header", "footer"] },
-            "type": { "enum": ["default", "first", "even"], "description": "Defaults to default." },
-            "section": { "type": "integer", "minimum": 0, "description": "Zero-based section; required when several sections have their own part." }
-          },
-          "additionalProperties": false
-        }
-      ]
-    },
-    "base": {
-      "type": "object",
-      "required": ["type", "target"],
-      "properties": {
-        "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
-        "captureKey": { "type": "string", "minLength": 1, "maxLength": 256 },
-        "target": { "$ref": "#/$defs/target" }, "targetRef": { "type": ["integer", "string", "null"] },
-        "part": { "$ref": "#/$defs/headerFooterPart" },
-        "author": { "type": "string", "minLength": 1 }, "generateRedlines": { "type": "boolean" },
-        "existingRevisions": { "enum": ["merge-same-author", "slice-cross-author", "reject-input", "accept-all-first", "accept-all-first-keep-normalized"] },
-        "pairReplacements": { "type": "boolean" },
-        "insertionAffinity": {
-          "type": "object",
-          "properties": {
-            "formatting": { "enum": ["left", "right", "none"] },
-            "hyperlink": { "enum": ["inside", "outside", "preserve"] },
-            "revision": { "enum": ["coalesce_same_author", "separate"] },
-            "bookmark": { "enum": ["inside", "outside"] },
-            "comment": { "enum": ["inside", "outside"] }
-          },
-          "additionalProperties": false
-        }
-      }
-    },
-    "operation": {
-      "oneOf": [
-        {
-          "type": "object",
-          "required": ["type", "parentCommentId", "commentContent"],
-          "properties": {
-            "type": { "const": "comment_reply" },
-            "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
-            "parentCommentId": { "type": ["integer", "string"] },
-            "commentContent": { "type": "string", "minLength": 1 },
-            "author": { "type": "string", "minLength": 1 },
-            "date": { "type": "string", "format": "date-time" }
-          },
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "description": "Resolve or reopen the comment thread containing commentId. Resolved is thread-level in Word, so the root and every reply change together. Body-only; not allowed with part.",
-          "required": ["type", "commentId"],
-          "properties": {
-            "type": { "const": "comment_resolve" },
-            "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
-            "commentId": { "type": ["integer", "string"] },
-            "resolved": { "type": "boolean", "default": true }
-          },
-          "additionalProperties": false
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["replacements"], "properties": { "type": { "enum": ["redline", "replace"] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } }, "oneOf": [ { "required": ["modified"], "not": { "required": ["replacements"] } }, { "required": ["replacements"], "not": { "required": ["modified"] } }, { "not": { "anyOf": [ { "required": ["modified"] }, { "required": ["replacements"] } ] } } ] } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "delete" }, "modified": { "const": "" } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["commentContent"], "properties": { "type": { "const": "comment" }, "textToComment": { "type": "string" }, "commentContent": { "type": "string", "minLength": 1 } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["textToHighlight"], "properties": { "type": { "const": "highlight" }, "textToHighlight": { "type": "string", "minLength": 1 }, "color": { "type": "string" } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["textToFormat", "properties"], "properties": { "type": { "enum": ["format", "character-format"] }, "textToFormat": { "type": "string", "minLength": 1 }, "properties": { "type": "object" }, "formattingRevisionPolicy": { "enum": ["always", "coalesce-own-insertion"] } } } ]
-        },
-        {
-          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["properties"], "properties": { "type": { "const": "paragraph-format" }, "properties": { "type": "object" } } } ]
-        }
-      ]
-    }
-  }
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/AnsonLai/docx-redline-js/docs/schemas/document-operations.schema.json",
+  "title": "docx-redline document operations",
+  "oneOf": [
+    { "$ref": "#/$defs/operationArray" },
+    {
+      "type": "object",
+      "required": ["operations"],
+      "properties": {
+        "operations": { "$ref": "#/$defs/operationArray" },
+        "expectedRevision": { "$ref": "#/$defs/revisionToken" }
+      },
+      "additionalProperties": false
+    }
+  ],
+  "$defs": {
+    "revisionToken": {
+      "type": "object",
+      "required": ["algorithm", "version", "scope", "value"],
+      "properties": {
+        "algorithm": { "type": "string", "enum": ["sha256"] },
+        "version": { "type": "integer", "enum": [1] },
+        "scope": { "type": "string", "enum": ["document-parts", "package"] },
+        "value": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" },
+        "coveredParts": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "operationArray": { "type": "array", "items": { "$ref": "#/$defs/operation" } },
+    "rejectedTextInsertionAnchor": {
+      "type": "object",
+      "required": ["exactText", "offset"],
+      "properties": {
+        "exactText": { "type": "string", "minLength": 1 },
+        "occurrence": { "type": "integer", "minimum": 1 },
+        "offset": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "localizedReplacement": {
+      "type": "object",
+      "required": ["find", "replace"],
+      "properties": {
+        "find": { "type": "string", "minLength": 1 },
+        "replace": { "type": "string" },
+        "occurrence": { "type": "integer", "minimum": 1 }
+      },
+      "additionalProperties": false
+    },
+    "target": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "properties": {
+            "exactText": { "type": "string" }, "text": { "type": "string" },
+            "index": { "type": ["integer", "string"] }, "paragraphIndex": { "type": ["integer", "string"] },
+            "paragraphId": { "type": "string" }, "occurrence": { "type": "integer", "minimum": 1 },
+            "inTable": { "type": "boolean" }, "fingerprint": { "type": "string" }, "sourceFingerprint": { "type": "string" },
+            "revisionView": {
+              "type": "string",
+              "enum": ["accepted", "rejected"],
+              "description": "Defaults to rejected for restore operations and accepted for other operation types."
+            },
+            "captureRef": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "select": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false,
+          "anyOf": [ { "required": ["exactText"] }, { "required": ["text"] }, { "required": ["index"] }, { "required": ["paragraphIndex"] }, { "required": ["paragraphId"] }, { "required": ["fingerprint"] }, { "required": ["sourceFingerprint"] }, { "required": ["captureRef"] } ]
+        }
+      ]
+    },
+    "headerFooterPart": {
+      "description": "Targets a header or footer instead of the body. Use a part path from inspect().headersFooters, or a selector. Comments are not supported in headers or footers.",
+      "oneOf": [
+        { "type": "string", "minLength": 1, "examples": ["word/footer2.xml"] },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "enum": ["header", "footer"] },
+            "type": { "enum": ["default", "first", "even"], "description": "Defaults to default." },
+            "section": { "type": "integer", "minimum": 0, "description": "Zero-based section; required when several sections have their own part." }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "base": {
+      "type": "object",
+      "required": ["type", "target"],
+      "properties": {
+        "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "captureKey": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "target": { "$ref": "#/$defs/target" }, "targetRef": { "type": ["integer", "string", "null"] },
+        "part": { "$ref": "#/$defs/headerFooterPart" },
+        "author": { "type": "string", "minLength": 1 }, "generateRedlines": { "type": "boolean" },
+        "existingRevisions": { "enum": ["merge-same-author", "slice-cross-author", "reject-input", "accept-all-first", "accept-all-first-keep-normalized"] },
+        "pairReplacements": { "type": "boolean" },
+        "insertionAffinity": {
+          "type": "object",
+          "properties": {
+            "formatting": { "enum": ["left", "right", "none"] },
+            "hyperlink": { "enum": ["inside", "outside", "preserve"] },
+            "revision": { "enum": ["coalesce_same_author", "separate"] },
+            "bookmark": { "enum": ["inside", "outside"] },
+            "comment": { "enum": ["inside", "outside"] }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "operation": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type", "parentCommentId", "commentContent"],
+          "properties": {
+            "type": { "const": "comment_reply" },
+            "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "parentCommentId": { "type": ["integer", "string"] },
+            "commentContent": { "type": "string", "minLength": 1 },
+            "author": { "type": "string", "minLength": 1 },
+            "date": { "type": "string", "format": "date-time" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Resolve or reopen the comment thread containing commentId. Resolved is thread-level in Word, so the root and every reply change together. Body-only; not allowed with part.",
+          "required": ["type", "commentId"],
+          "properties": {
+            "type": { "const": "comment_resolve" },
+            "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "commentId": { "type": ["integer", "string"] },
+            "resolved": { "type": "boolean", "default": true }
+          },
+          "additionalProperties": false
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["replacements"], "properties": { "type": { "enum": ["redline", "replace"] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["modified"], "properties": { "type": { "enum": ["redline", "replace", "format", "list-change", "table-reconciliation", "insert"] }, "modified": { "type": "string" }, "structuredContent": { "type": "boolean" }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] }, "anchor": { "$ref": "#/$defs/rejectedTextInsertionAnchor" } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "restore" }, "modified": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } } ] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } }, "targetEnd": { "$ref": "#/$defs/target" }, "targetEndRef": { "type": ["integer", "string", "null"] } }, "oneOf": [ { "required": ["modified"], "not": { "required": ["replacements"] } }, { "required": ["replacements"], "not": { "required": ["modified"] } }, { "not": { "anyOf": [ { "required": ["modified"] }, { "required": ["replacements"] } ] } } ] } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "properties": { "type": { "const": "delete" }, "modified": { "const": "" } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["commentContent"], "properties": { "type": { "const": "comment" }, "textToComment": { "type": "string" }, "commentContent": { "type": "string", "minLength": 1 } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["textToHighlight"], "properties": { "type": { "const": "highlight" }, "textToHighlight": { "type": "string", "minLength": 1 }, "color": { "type": "string" } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["textToFormat", "properties"], "properties": { "type": { "enum": ["format", "character-format"] }, "textToFormat": { "type": "string", "minLength": 1 }, "textOccurrence": { "type": "integer", "minimum": 1, "default": 1 }, "properties": { "type": "object" }, "formattingRevisionPolicy": { "enum": ["always", "coalesce-own-insertion"] } } } ]
+        },
+        {
+          "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["properties"], "properties": { "type": { "const": "paragraph-format" }, "properties": { "type": "object" } } } ]
+        }
+      ]
+    }
+  }
+}