@ckeditor/ckeditor5-ai 49.0.1 → 49.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/dist/aiactions/aiactions.d.ts +2 -2
  2. package/dist/aiballoon/ui/aiballoonview.d.ts +1 -1
  3. package/dist/aichat/aichatballoon.d.ts +1 -1
  4. package/dist/aichat/aichatcontroller.d.ts +2 -2
  5. package/dist/aichat/ui/aichatfeedview.d.ts +24 -0
  6. package/dist/aichat/ui/feed/aichatfeedsuggestionitemactionsview.d.ts +7 -0
  7. package/dist/aichatshortcuts/aichatshortcuts.d.ts +2 -2
  8. package/dist/aicore/aiconnector.d.ts +2 -2
  9. package/dist/aicore/aiediting.d.ts +8 -4
  10. package/dist/aicore/aieditorconfig.d.ts +225 -0
  11. package/dist/aicore/aigateway.d.ts +8 -3
  12. package/dist/aicore/model/aicontext.d.ts +2 -2
  13. package/dist/aicore/pipeline/airesponseapplier.d.ts +1 -0
  14. package/dist/aicore/ui/aiscrollfillerview.d.ts +37 -0
  15. package/dist/aicore/ui/suggestioncontainer/aisuggestionbodyview.d.ts +6 -1
  16. package/dist/aicore/ui/suggestioncontainer/aisuggestioncontentpartstateview.d.ts +7 -0
  17. package/dist/aicore/utils/autoadvancedelay.d.ts +13 -0
  18. package/dist/aicore/utils/getallowedcustomelements.d.ts +16 -0
  19. package/dist/aicore/utils/geteditorconfig.d.ts +10 -76
  20. package/dist/aicore/utils/getoperationsfordocumentsuggestions.d.ts +4 -4
  21. package/dist/aicore/utils/getrootinfo.d.ts +2 -19
  22. package/dist/aicore/utils/getscrolltoptoelement.d.ts +13 -0
  23. package/dist/aicore/utils/getsuggestionpartsfromreply.d.ts +35 -0
  24. package/dist/aicore/utils/htmlparser.d.ts +3 -2
  25. package/dist/aicore/utils/replyactions.d.ts +10 -2
  26. package/dist/aicore/utils/scrollmanager.d.ts +5 -0
  27. package/dist/aireviewcore/aireviewcoreediting.d.ts +2 -2
  28. package/dist/aireviewcore/aireviewcoreui.d.ts +8 -0
  29. package/dist/aireviewcore/model/aireviewcheckrun.d.ts +8 -0
  30. package/dist/aireviewcore/ui/aireviewcorenavigationpanelview.d.ts +1 -1
  31. package/dist/aireviewcore/ui/aireviewcoreuicheckresultsview.d.ts +22 -7
  32. package/dist/aireviewmode/aireviewmodecontroller.d.ts +4 -0
  33. package/dist/aireviewmode/ui/aireviewmodecheckresultsview.d.ts +10 -1
  34. package/dist/aireviewmode/ui/aireviewmodesummaryview.d.ts +44 -0
  35. package/dist/augmentation.d.ts +6 -0
  36. package/dist/index-editor.css +328 -166
  37. package/dist/index.css +328 -166
  38. package/dist/index.d.ts +10 -4
  39. package/dist/index.js +21 -19
  40. package/dist/toolkit/applypatch.d.ts +31 -0
  41. package/dist/toolkit/computechanges.d.ts +19 -0
  42. package/dist/toolkit/computepreviews.d.ts +39 -0
  43. package/dist/toolkit/createfragmentfromrange.d.ts +24 -0
  44. package/dist/toolkit/dataidassigner.d.ts +38 -0
  45. package/dist/toolkit/documentcompare.d.ts +357 -0
  46. package/dist/{aisdk → toolkit}/documentcompareutils.d.ts +1 -1
  47. package/dist/{aisdk/documentchanges.d.ts → toolkit/documentdiffer.d.ts} +39 -21
  48. package/dist/toolkit/documentdifferutils.d.ts +15 -0
  49. package/dist/{aisdk → toolkit}/documentsnapshot.d.ts +9 -4
  50. package/dist/toolkit/elementcategory.d.ts +50 -0
  51. package/dist/toolkit/elementmatcher.d.ts +114 -0
  52. package/dist/{aisdk → toolkit}/extractselectionfromhtml.d.ts +1 -1
  53. package/dist/toolkit/proposedchange.d.ts +113 -0
  54. package/dist/toolkit/proposedchanges.d.ts +130 -0
  55. package/dist/toolkit/proposedchangescollection.d.ts +93 -0
  56. package/dist/toolkit/proposedchangescontroller.d.ts +129 -0
  57. package/dist/toolkit/proposedchangescontrollertype.d.ts +88 -0
  58. package/dist/{aisdk/documentchangesutils.d.ts → toolkit/proposedchangesutils.d.ts} +3 -3
  59. package/dist/{aisdk → toolkit}/validateoperations.d.ts +1 -1
  60. package/dist/translations/af.js +1 -1
  61. package/dist/translations/af.umd.js +1 -1
  62. package/dist/translations/ar.js +1 -1
  63. package/dist/translations/ar.umd.js +1 -1
  64. package/dist/translations/ast.js +1 -1
  65. package/dist/translations/ast.umd.js +1 -1
  66. package/dist/translations/az.js +1 -1
  67. package/dist/translations/az.umd.js +1 -1
  68. package/dist/translations/be.js +1 -1
  69. package/dist/translations/be.umd.js +1 -1
  70. package/dist/translations/bg.js +1 -1
  71. package/dist/translations/bg.umd.js +1 -1
  72. package/dist/translations/bn.js +1 -1
  73. package/dist/translations/bn.umd.js +1 -1
  74. package/dist/translations/bs.js +1 -1
  75. package/dist/translations/bs.umd.js +1 -1
  76. package/dist/translations/ca.js +1 -1
  77. package/dist/translations/ca.umd.js +1 -1
  78. package/dist/translations/cs.js +1 -1
  79. package/dist/translations/cs.umd.js +1 -1
  80. package/dist/translations/da.js +1 -1
  81. package/dist/translations/da.umd.js +1 -1
  82. package/dist/translations/de-ch.js +1 -1
  83. package/dist/translations/de-ch.umd.js +1 -1
  84. package/dist/translations/de.js +1 -1
  85. package/dist/translations/de.umd.js +1 -1
  86. package/dist/translations/el.js +1 -1
  87. package/dist/translations/el.umd.js +1 -1
  88. package/dist/translations/en-au.js +1 -1
  89. package/dist/translations/en-au.umd.js +1 -1
  90. package/dist/translations/en-gb.js +1 -1
  91. package/dist/translations/en-gb.umd.js +1 -1
  92. package/dist/translations/en.js +1 -1
  93. package/dist/translations/en.umd.js +1 -1
  94. package/dist/translations/eo.js +1 -1
  95. package/dist/translations/eo.umd.js +1 -1
  96. package/dist/translations/es-co.js +1 -1
  97. package/dist/translations/es-co.umd.js +1 -1
  98. package/dist/translations/es.js +1 -1
  99. package/dist/translations/es.umd.js +1 -1
  100. package/dist/translations/et.js +1 -1
  101. package/dist/translations/et.umd.js +1 -1
  102. package/dist/translations/eu.js +1 -1
  103. package/dist/translations/eu.umd.js +1 -1
  104. package/dist/translations/fa.js +1 -1
  105. package/dist/translations/fa.umd.js +1 -1
  106. package/dist/translations/fi.js +1 -1
  107. package/dist/translations/fi.umd.js +1 -1
  108. package/dist/translations/fr.js +1 -1
  109. package/dist/translations/fr.umd.js +1 -1
  110. package/dist/translations/gl.js +1 -1
  111. package/dist/translations/gl.umd.js +1 -1
  112. package/dist/translations/gu.js +1 -1
  113. package/dist/translations/gu.umd.js +1 -1
  114. package/dist/translations/he.js +1 -1
  115. package/dist/translations/he.umd.js +1 -1
  116. package/dist/translations/hi.js +1 -1
  117. package/dist/translations/hi.umd.js +1 -1
  118. package/dist/translations/hr.js +1 -1
  119. package/dist/translations/hr.umd.js +1 -1
  120. package/dist/translations/hu.js +1 -1
  121. package/dist/translations/hu.umd.js +1 -1
  122. package/dist/translations/hy.js +1 -1
  123. package/dist/translations/hy.umd.js +1 -1
  124. package/dist/translations/id.js +1 -1
  125. package/dist/translations/id.umd.js +1 -1
  126. package/dist/translations/it.js +1 -1
  127. package/dist/translations/it.umd.js +1 -1
  128. package/dist/translations/ja.js +1 -1
  129. package/dist/translations/ja.umd.js +1 -1
  130. package/dist/translations/jv.js +1 -1
  131. package/dist/translations/jv.umd.js +1 -1
  132. package/dist/translations/kk.js +1 -1
  133. package/dist/translations/kk.umd.js +1 -1
  134. package/dist/translations/km.js +1 -1
  135. package/dist/translations/km.umd.js +1 -1
  136. package/dist/translations/kn.js +1 -1
  137. package/dist/translations/kn.umd.js +1 -1
  138. package/dist/translations/ko.js +1 -1
  139. package/dist/translations/ko.umd.js +1 -1
  140. package/dist/translations/ku.js +1 -1
  141. package/dist/translations/ku.umd.js +1 -1
  142. package/dist/translations/lt.js +1 -1
  143. package/dist/translations/lt.umd.js +1 -1
  144. package/dist/translations/lv.js +1 -1
  145. package/dist/translations/lv.umd.js +1 -1
  146. package/dist/translations/ms.js +1 -1
  147. package/dist/translations/ms.umd.js +1 -1
  148. package/dist/translations/nb.js +1 -1
  149. package/dist/translations/nb.umd.js +1 -1
  150. package/dist/translations/ne.js +1 -1
  151. package/dist/translations/ne.umd.js +1 -1
  152. package/dist/translations/nl.js +1 -1
  153. package/dist/translations/nl.umd.js +1 -1
  154. package/dist/translations/no.js +1 -1
  155. package/dist/translations/no.umd.js +1 -1
  156. package/dist/translations/oc.js +1 -1
  157. package/dist/translations/oc.umd.js +1 -1
  158. package/dist/translations/pl.js +1 -1
  159. package/dist/translations/pl.umd.js +1 -1
  160. package/dist/translations/pt-br.js +1 -1
  161. package/dist/translations/pt-br.umd.js +1 -1
  162. package/dist/translations/pt.js +1 -1
  163. package/dist/translations/pt.umd.js +1 -1
  164. package/dist/translations/ro.js +1 -1
  165. package/dist/translations/ro.umd.js +1 -1
  166. package/dist/translations/ru.js +1 -1
  167. package/dist/translations/ru.umd.js +1 -1
  168. package/dist/translations/si.js +1 -1
  169. package/dist/translations/si.umd.js +1 -1
  170. package/dist/translations/sk.js +1 -1
  171. package/dist/translations/sk.umd.js +1 -1
  172. package/dist/translations/sl.js +1 -1
  173. package/dist/translations/sl.umd.js +1 -1
  174. package/dist/translations/sq.js +1 -1
  175. package/dist/translations/sq.umd.js +1 -1
  176. package/dist/translations/sr-latn.js +1 -1
  177. package/dist/translations/sr-latn.umd.js +1 -1
  178. package/dist/translations/sr.js +1 -1
  179. package/dist/translations/sr.umd.js +1 -1
  180. package/dist/translations/sv.js +1 -1
  181. package/dist/translations/sv.umd.js +1 -1
  182. package/dist/translations/th.js +1 -1
  183. package/dist/translations/th.umd.js +1 -1
  184. package/dist/translations/ti.js +1 -1
  185. package/dist/translations/ti.umd.js +1 -1
  186. package/dist/translations/tk.js +1 -1
  187. package/dist/translations/tk.umd.js +1 -1
  188. package/dist/translations/tr.js +1 -1
  189. package/dist/translations/tr.umd.js +1 -1
  190. package/dist/translations/tt.js +1 -1
  191. package/dist/translations/tt.umd.js +1 -1
  192. package/dist/translations/ug.js +1 -1
  193. package/dist/translations/ug.umd.js +1 -1
  194. package/dist/translations/uk.js +1 -1
  195. package/dist/translations/uk.umd.js +1 -1
  196. package/dist/translations/ur.js +1 -1
  197. package/dist/translations/ur.umd.js +1 -1
  198. package/dist/translations/uz.js +1 -1
  199. package/dist/translations/uz.umd.js +1 -1
  200. package/dist/translations/vi.js +1 -1
  201. package/dist/translations/vi.umd.js +1 -1
  202. package/dist/translations/zh-cn.js +1 -1
  203. package/dist/translations/zh-cn.umd.js +1 -1
  204. package/dist/translations/zh.js +1 -1
  205. package/dist/translations/zh.umd.js +1 -1
  206. package/package.json +32 -30
  207. package/dist/aisdk/dataidassigner.d.ts +0 -20
  208. package/dist/aisdk/documentcompare.d.ts +0 -171
@@ -0,0 +1,31 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/applypatch
7
+ */
8
+ import { type Editor } from "@ckeditor/ckeditor5-core";
9
+ import { type DocumentComparePatch } from "./documentcompare.js";
10
+ /**
11
+ * Applies a patch to the current state of the document of the given editor: the patch operations are reconciled against
12
+ * everything that happened to the document since the patch was captured, validated on a copy of the document, and only then
13
+ * committed.
14
+ *
15
+ * The patch is only applied to the document it was captured from, and never across real-time sessions. Outside collaboration
16
+ * the editing session is the caller's to check, see {@link module:ai/toolkit/documentcompare~DocumentCompare#applyPatch}.
17
+ *
18
+ * @param editor The editor whose document the patch is applied to.
19
+ * @param patch The patch to apply, as produced by {@link module:ai/toolkit/documentcompare~DocumentCompare#computePatch}.
20
+ * @param sessionId The editing session the patch must still belong to. Defaults to the only one the editor itself knows.
21
+ */
22
+ export declare function applyPatch(editor: Editor, patch: DocumentComparePatch, sessionId?: string | null): void;
23
+ /**
24
+ * The document's collaboration channel id, or an empty string when not configured.
25
+ */
26
+ export declare function getChannelId(editor: Editor): string;
27
+ /**
28
+ * The editing session id the editor itself knows - the real-time collaboration one - or `null` when it is not in a
29
+ * collaboration session. Outside collaboration the session id is generated by whoever captured the patch.
30
+ */
31
+ export declare function getRealTimeSessionId(editor: Editor): string | null;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ import { type Editor } from "@ckeditor/ckeditor5-core";
6
+ import { type DocumentChange } from "./proposedchange.js";
7
+ import { type DocumentCompareComputeChangesOptions } from "./documentcompare.js";
8
+ import { type DocumentCompareSnapshot } from "./documentsnapshot.js";
9
+ /**
10
+ * Computes the differences between a snapshot and processed data, and returns them as an array of non-overlapping changes. Every change
11
+ * can be then rendered and decided about separately.
12
+ *
13
+ * A change says where it sits on either side as a range into the tree it was read from - the snapshot for the before side, the processed
14
+ * data for the after side - so both trees are kept alive by the changes found in them, and a change can still be read in the surroundings
15
+ * it was found in.
16
+ *
17
+ * Implements {@link module:ai/toolkit/documentcompare~DocumentCompare#computeChanges}.
18
+ */
19
+ export declare function computeChanges(editor: Editor, snapshot: DocumentCompareSnapshot, data: string | Record<string, string>, options?: DocumentCompareComputeChangesOptions): Array<DocumentChange>;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/computepreviews
7
+ */
8
+ import { ModelDocumentFragment, type ModelSchema } from "@ckeditor/ckeditor5-engine";
9
+ import { type DocumentChange } from "./proposedchange.js";
10
+ /**
11
+ * The two fragments one change is rendered from.
12
+ */
13
+ export interface ChangePreview {
14
+ /**
15
+ * The changed content as it stands, in what it is shown in.
16
+ */
17
+ previewBefore: ModelDocumentFragment;
18
+ /**
19
+ * What that becomes, in the same surroundings.
20
+ */
21
+ previewAfter: ModelDocumentFragment;
22
+ }
23
+ /**
24
+ * Builds the fragments each of the given changes is previewed from, in the order the changes come in.
25
+ *
26
+ * While a change keeps strictly the content it covers, a preview has that content wrapped in all necessary ancestors to make sure
27
+ * the model can be properly downcasted and rendered to DOM. Also, additional context elements around the change are added, if possible.
28
+ * This makes it easier to locate the change in the original document.
29
+ *
30
+ * At most one element before and after the changed content is added as such context. If there's none, context element for one of wrappers
31
+ * can be added instead.
32
+ *
33
+ * Note that a modified element cannot be added as context element, as it is present in a different change. This blocks given "side"
34
+ * from receiving any context at all.
35
+ *
36
+ * @param changes The changes to show, in document order. Only where each one sits is read.
37
+ * @param schema The model's schema.
38
+ */
39
+ export declare function computePreviews(changes: ReadonlyArray<DocumentChange>, schema: ModelSchema): Array<ChangePreview>;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/createfragmentfromrange
7
+ */
8
+ import { ModelDocumentFragment, ModelRange, type ModelNode } from "@ckeditor/ckeditor5-engine";
9
+ /**
10
+ * Copies what a range covers, leaving the tree it was read from as it is. The copies belong to no parent, so they can
11
+ * be put wherever they are needed - which is why this is nodes and not a fragment.
12
+ *
13
+ * @param range The range to copy.
14
+ */
15
+ export declare function createNodesFromRange(range: ModelRange): Array<ModelNode>;
16
+ /**
17
+ * The same copy as {@link ~createNodesFromRange}, as a model document fragment that also carries the markers.
18
+ *
19
+ * Only the markers the range covers whole come along, since a marker is carried as one: a marker reaching outside the
20
+ * range would arrive cut down to the part inside it, which is worse than leaving it where it is.
21
+ *
22
+ * @param range The range to copy. Flat: both ends sit in one parent, which is how a change describes itself.
23
+ */
24
+ export declare function createFragmentFromRange(range: ModelRange): ModelDocumentFragment;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/dataidassigner
7
+ */
8
+ import { type Editor } from "@ckeditor/ckeditor5-core";
9
+ import { type ViewDocumentFragment, type ViewElement } from "@ckeditor/ckeditor5-engine";
10
+ /**
11
+ * Assigns a unique `data-id` to the structural view elements that lack one — container, empty and raw elements, plus
12
+ * any element containing an id-bearing descendant (skipping `<br>`). Existing ids are preserved.
13
+ */
14
+ export declare class DataIdAssigner {
15
+ constructor(editor: Editor);
16
+ /**
17
+ * Assigns the missing `data-id`s across the given view fragment (or element).
18
+ */
19
+ assign(view: ViewElement | ViewDocumentFragment): void;
20
+ /**
21
+ * Generates a random 4-letter id not already used (and records it). Short and letters-only, mirroring the AI scheme.
22
+ */
23
+ nextId(): string;
24
+ }
25
+ /**
26
+ * Gives every element the processed data marks as new an id of its own, so the comparison can tell them apart.
27
+ *
28
+ * Elements are matched by `data-id`, and the mark is shared by everything a reply added, so the comparison would read
29
+ * all of them as one and the same. An id each keeps them apart, and matches nothing in the snapshot - which is what new
30
+ * content should do. `AIResponseApplier` does the same before a reply reaches a diff.
31
+ *
32
+ * An element that simply carries no id is left alone: the processed data is a whole root, where that means an element
33
+ * the processing did not label rather than one it wrote, and the comparison matches it on its name and attributes.
34
+ *
35
+ * @param data The processed data, as the comparison received it.
36
+ * @returns The same data with every new element named, or exactly what came in when there was nothing to name.
37
+ */
38
+ export declare function resolveDataIds(data: string): string;
@@ -0,0 +1,357 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/documentcompare
7
+ * @publicApi
8
+ */
9
+ import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
10
+ import { type Operation, type ModelRange, type ModelElement, type ModelSchema } from "@ckeditor/ckeditor5-engine";
11
+ import { SuggestionsConversion } from "@ckeditor/ckeditor5-collaboration-core";
12
+ import { DocumentDiffer } from "./documentdiffer.js";
13
+ import { DocumentCompareUtils } from "./documentcompareutils.js";
14
+ import { AIEditorConfig } from "../aicore/aieditorconfig.js";
15
+ import { type AIOperationSource } from "../aicore/utils/markoperationsasai.js";
16
+ import { type DocumentCompareSnapshot } from "./documentsnapshot.js";
17
+ import { type DocumentChange } from "./proposedchange.js";
18
+ /**
19
+ * `DocumentCompare` provides a set of tools that allows you to process editor document data by custom external logic,
20
+ * evaluate the differences between original and processed data, and apply them as granular changes or tracked
21
+ * suggestions.
22
+ *
23
+ * Contrary to `editor.setData()`, this does not replace the whole editor data. Instead, atomic changes are evaluated and a small set
24
+ * of changes is applied to the document. This is especially useful when the editor also uses Track Changes, Revision History, and
25
+ * Real-Time Collaboration features.
26
+ *
27
+ * Use {@link #process `process()`}, to run the whole pipeline in one call - it makes a
28
+ * {@link module:ai/toolkit/documentsnapshot~DocumentCompareSnapshot document snapshot}, processes the data, and applies granular changes:
29
+ *
30
+ * ```ts
31
+ * await documentCompare.process( async snapshot => externalDataProcessing( snapshot.content ) );
32
+ *
33
+ * // Or, to apply changes as suggestions:
34
+ * await documentCompare.process( async snapshot => externalDataProcessing( snapshot.content ), { asSuggestions: true } );
35
+ * ```
36
+ *
37
+ * Some integrations need to process the data in separate steps (e.g. backend processing workflows, or when changes
38
+ * are not applied immediately to the content). In this case, you can capture a snapshot first and apply the result later:
39
+ *
40
+ * ```ts
41
+ * const snapshot = documentCompare.makeSnapshot();
42
+ * const processed = await externalDataProcessing( snapshot.content );
43
+ *
44
+ * // ...
45
+ *
46
+ * const patch = documentCompare.computePatch( snapshot, processed, { asSuggestions: true } );
47
+ * documentCompare.applyPatch( patch );
48
+ * ```
49
+ *
50
+ * If the user should decide whether changes are accepted or rejected, compare the snapshot into separate changes instead, and apply the
51
+ * ones they keep:
52
+ *
53
+ * ```ts
54
+ * const changes = documentCompare.computeChanges( snapshot, processed );
55
+ *
56
+ * documentCompare.applyChange( changes[ 0 ] );
57
+ * ```
58
+ *
59
+ * See also {@link module:ai/toolkit/proposedchanges~ProposedChanges `ProposedChanges` plugin}, a set of tools to display the
60
+ * proposed changes to the user.
61
+ *
62
+ * The snapshot data is stamped with `data-id` attributes, and the comparison pairs the elements of the snapshot and the
63
+ * processed data by these ids. When the processing cannot retain the ids (for example, when the data goes through Markdown),
64
+ * capture the snapshot without them. The elements are then paired by their content instead:
65
+ *
66
+ * ```ts
67
+ * const snapshot = documentCompare.makeSnapshot( { useDataIds: false } );
68
+ * const processed = await externalDataProcessing( snapshot.content );
69
+ *
70
+ * const patch = documentCompare.computePatch( snapshot, processed );
71
+ * documentCompare.applyPatch( patch );
72
+ * ```
73
+ *
74
+ * A document from outside the editor (for example, another version of the document) can be compared with the current document present
75
+ * in the editor. Capture the snapshot without the ids just before the comparison, so the documents are compared by content similarity:
76
+ *
77
+ * ```ts
78
+ * const snapshot = documentCompare.makeSnapshot( { useDataIds: false } );
79
+ * const patch = documentCompare.computePatch( snapshot, importedHtml, { asSuggestions: true } );
80
+ * documentCompare.applyPatch( patch );
81
+ * ```
82
+ *
83
+ * The recommended way to use `DocumentCompare` is to create a snapshot with data IDs, then process the snapshot `content`, and then
84
+ * use the snapshot to generate the changes using `DocumentCompare` methods. This approach will result in better performance and the best
85
+ * diff quality, as snapshot data IDs are used by the diff algorithm to pair the elements. Skip IDs or the snapshot only in cases where
86
+ * they cannot be used.
87
+ */
88
+ export declare class DocumentCompare extends Plugin {
89
+ static get pluginName(): "DocumentCompare";
90
+ static get requires(): PluginDependenciesOf<[DocumentDiffer, DocumentCompareUtils, SuggestionsConversion, AIEditorConfig]>;
91
+ static override get isOfficialPlugin(): true;
92
+ static override get isPremiumPlugin(): true;
93
+ init(): void;
94
+ afterInit(): void;
95
+ /**
96
+ * Captures the current document state as a {@link module:ai/toolkit/documentsnapshot~DocumentCompareSnapshot}.
97
+ *
98
+ * The snapshot contains all data and metadata necessary to process the document and then be able to calculate differences between
99
+ * the original and the processed data.
100
+ *
101
+ * Importantly, `snapshot.content` holds data for each root (excluding `$graveyard`), serialized to HTML. By default, the data is
102
+ * stamped with `data-id` attributes, assigned to structural elements of the data. During processing, make sure that these
103
+ * `data-id`s are retained. They are used to identify which elements were kept, which were removed, and which are new.
104
+ *
105
+ * If the processing cannot retain them, capture the snapshot without the ids
106
+ * ({@link ~DocumentCompareSnapshotOptions#useDataIds `options.useDataIds: false`}). When data IDs are skipped,
107
+ * the original and processed data is compared only by the content similarity.
108
+ *
109
+ * The content of an inline root is wrapped in a single, artificial `<p data-id="...">` element. This wrapper always gets
110
+ * a `data-id`, even when the snapshot is captured with `options.useDataIds: false`. Process only the content inside the wrapper.
111
+ *
112
+ * See also {@link module:ai/toolkit/documentsnapshot~DocumentCompareSnapshot}.
113
+ *
114
+ * @param options How the snapshot is captured.
115
+ * @returns The captured snapshot.
116
+ */
117
+ makeSnapshot(options?: DocumentCompareSnapshotOptions): DocumentCompareSnapshot;
118
+ /**
119
+ * Computes a document patch - a set of granular differences between the earlier captured snapshot and the given data. You can apply
120
+ * the patch using {@link #applyPatch}. All changes from the patch are applied at once.
121
+ *
122
+ * Use `options` to set whether the patch should be calculated and applied as tracked changes or as direct changes to the document.
123
+ *
124
+ * The passed data is compared against the snapshot state. Later, when a patch is applied, the differences are resolved against any
125
+ * changes that happened in the editor since the snapshot was taken. This allows you to process the data asynchronously, while retaining
126
+ * all edits that have happened in the editor in the meantime.
127
+ *
128
+ * If you did not make the snapshot for processing purposes (for example, a case where you compare editor data to a different, already
129
+ * existing document), make the snapshot just before calling `computePatch()`.
130
+ *
131
+ * Throws `documentcompare-unsupported-inline-root-content` if the processed data for an inline root contains block content.
132
+ *
133
+ * @param snapshot The captured before-state to diff against.
134
+ * @param data The new data. For multi-root editor, pass an object keyed by root name.
135
+ * @param options How the comparison is computed.
136
+ * @returns The patch bringing the document from the snapshot to the processed state.
137
+ */
138
+ computePatch(snapshot: DocumentCompareSnapshot, data: string | Record<string, string>, options?: DocumentCompareComputePatchOptions): DocumentComparePatch;
139
+ /**
140
+ * Compares the earlier captured snapshot and the given data. Returns a set of grouped
141
+ * {@link module:ai/toolkit/proposedchange~DocumentChange document changes}. Changes are grouped based on where in the document
142
+ * they sit - related changes made next to each other are put together into one group. Each group is one, atomic, reviewable unit,
143
+ * to be accepted or rejected independently of each other.
144
+ *
145
+ * The document changes can be collected into a
146
+ * {@link module:ai/toolkit/proposedchangescollection~ProposedChangesCollection set of proposed changes} and passed to
147
+ * {@link module:ai/toolkit/proposedchanges~ProposedChanges#createController} to create a controller, which binds the changes with
148
+ * an editor instance and offers an API to operate on them. To provide an interface for managing the changes,
149
+ * {@link module:ai/toolkit/proposedchanges~ProposedChanges#createView create a proposed changes UI component} and
150
+ * {@link module:ai/toolkit/proposedchangescontrollertype~ProposedChangesController#attachView attach} it to the controller.
151
+ *
152
+ * You can also apply the accepted document changes directly, using {@link #applyChange}.
153
+ *
154
+ * The passed data is compared against the snapshot state. When a change is accepted, it is resolved against any changes that
155
+ * happened in the editor since the snapshot was taken. This allows you to process the data asynchronously, while retaining any edits
156
+ * that have happened in the editor in the meantime.
157
+ *
158
+ * If you did not make the snapshot for processing purposes (for example, a case where you compare editor data to a different, already
159
+ * existing document), make the snapshot just before calling `computeChanges()`.
160
+ *
161
+ * If the processed data for an inline root contains block content, no change is returned for that root and
162
+ * a `documentcompare-unsupported-inline-root-content` warning is logged.
163
+ *
164
+ * @param snapshot The captured before-state to compare against.
165
+ * @param data The processed data. For multi-root editor, pass an object keyed by root name.
166
+ * @param options How the comparison is computed.
167
+ * @returns The changes bringing the document from the snapshot to the processed state, in document order.
168
+ */
169
+ computeChanges(snapshot: DocumentCompareSnapshot, data: string | Record<string, string>, options?: DocumentCompareComputeChangesOptions): Array<DocumentChange>;
170
+ /**
171
+ * Applies a patch to the current state of the document.
172
+ *
173
+ * As a result, all changes described by the patch are reflected in the document. Note, that this converges with all changes that
174
+ * happened on the document after the snapshot used for the patch was made, including both local and remote edits (if real-time
175
+ * collaboration is enabled).
176
+ *
177
+ * Note, that the patch can be only applied to the same document as the snapshot, and only during the same editing session.
178
+ * Otherwise, `documentcompare-apply-session-mismatch` error is thrown.
179
+ *
180
+ * The patch is first validated against a copy of the document before anything is committed. In case if any errors or conflict
181
+ * resolution problems surface during this dry-run, `documentcompare-invalid-patch` error is thrown, and the editor data is left intact.
182
+ *
183
+ * The changes can be applied directly to the content or as tracked suggestions (requires
184
+ * {@link module:track-changes/trackchanges~TrackChanges Track changes plugin}). See also {@link #computePatch}.
185
+ *
186
+ * @param patch The patch to apply, as produced by {@link #computePatch}.
187
+ */
188
+ applyPatch(patch: DocumentComparePatch): void;
189
+ /**
190
+ * Applies a single {@link module:ai/toolkit/proposedchange~DocumentChange document change} the same way
191
+ * {@link #applyPatch} applies a whole patch. See {@link #applyPatch}.
192
+ *
193
+ * @param change The change to apply.
194
+ * @param options How the change is applied.
195
+ */
196
+ applyChange(change: DocumentChange, options?: DocumentCompareApplyChangeOptions): void;
197
+ /**
198
+ * Runs the whole processing pipeline in one call: snapshots the document, hands the snapshot to `callback` for
199
+ * external processing (e.g. an AI service), then diffs returned data and applies granular changes to the document.
200
+ *
201
+ * This is a "shortcut" for using {@link #makeSnapshot}, {@link #computePatch}, and {@link #applyPatch}.
202
+ *
203
+ * If diffing or applying fails, the underlying error is rethrown and can be further handled, unless `options.overwriteOnError` is set,
204
+ * in which case the current document is instead fully replaced with the processed data, the same way as if `editor.setData()` was used.
205
+ * In this case, changes that happened to the document after the snapshot was taken will be overwritten.
206
+ *
207
+ * The snapshot is captured with data IDs stamped on the document content, unless `options.useDataIds` is `false`.
208
+ * See {@link ~DocumentCompareSnapshotOptions#useDataIds}.
209
+ *
210
+ * @param callback Receives the captured snapshot and returns the processed data keyed by root name.
211
+ * @param options Additional processing options.
212
+ * @returns `true` when the process finished successfully and changes were applied granularly,
213
+ * `false` when the full-replacement fallback was used.
214
+ */
215
+ process(callback: (snapshot: DocumentCompareSnapshot) => Promise<string | Record<string, string>>, options?: DocumentCompareProcessOptions): Promise<boolean>;
216
+ }
217
+ /**
218
+ * Options for {@link module:ai/toolkit/documentcompare~DocumentCompare#makeSnapshot}.
219
+ */
220
+ export interface DocumentCompareSnapshotOptions {
221
+ /**
222
+ * Ranges to capture with the snapshot as the user's selection. Must not intersect. By default, no selection is captured.
223
+ */
224
+ selection?: Iterable<ModelRange>;
225
+ /**
226
+ * Whether the snapshot content is stamped with `data-id` attributes.
227
+ *
228
+ * With `true`, every structural element of the serialized data gets a `data-id` attribute. Later, the comparison uses these IDs
229
+ * to pair the elements of the snapshot and the processed data. The processing must retain the data IDs on
230
+ * the elements that were kept. New elements should not get any ID.
231
+ *
232
+ * With `false`, no `data-id` is written, and the comparison pairs the elements only by their content similarity instead. Use it when
233
+ * the processing cannot retain the IDs.
234
+ *
235
+ * @default true
236
+ */
237
+ useDataIds?: boolean;
238
+ }
239
+ /**
240
+ * Describes how a {@link ~DocumentComparePatch patch} is applied.
241
+ */
242
+ export interface DocumentComparePatchOptions {
243
+ /**
244
+ * Whether the operations carry track-changes suggestion markers.
245
+ *
246
+ * @default false
247
+ */
248
+ asSuggestions?: boolean;
249
+ }
250
+ /**
251
+ * Describes how a comparison is computed.
252
+ */
253
+ export interface DocumentCompareComputePatchOptions {
254
+ /**
255
+ * Whether the comparison marks removed content for track changes instead of removing it.
256
+ */
257
+ asSuggestions?: boolean;
258
+ /**
259
+ * Which AI feature produced the processed data. You can use one of available values or pass a custom string.
260
+ * When set, the operations applying the patch will be stamped as made-by-AI. This information is passed to suggestions
261
+ * and revisions meta data. Such suggestions and revisions will be visually marked as made-by-AI accordingly to these
262
+ * features config ({@link module:track-changes/trackchangesconfig~TrackChangesConfig#showAISource
263
+ * `config.trackChanges.showAISource`} and {@link module:revision-history/revisionhistoryconfig~RevisionHistoryConfig#showAISource
264
+ * `config.revisionHistory.showAISource`}).
265
+ *
266
+ * Do not set for changes coming from non-AI sources.
267
+ */
268
+ aiSource?: AIOperationSource;
269
+ }
270
+ /**
271
+ * Describes how the document changes are computed.
272
+ */
273
+ export interface DocumentCompareComputeChangesOptions {
274
+ /**
275
+ * Whether all changes inside the given `element` should be treated as a one change. Called for every element if defined, before any
276
+ * other rules are applied. Return `true` or `false` to make a decision, or `undefined` to fall back to default rules.
277
+ *
278
+ * Use this to register custom elements or to override default rules.
279
+ *
280
+ * Atomic elements are for example tables (excluding layout tables) and elements without paragraph-like elements (e.g. an image with
281
+ * a caption).
282
+ */
283
+ isAtomic?: (element: ModelElement, schema: ModelSchema) => boolean | undefined;
284
+ /**
285
+ * Which AI feature produced the processed data, stamped on the operations applying a computed change.
286
+ *
287
+ * See {@link ~DocumentCompareComputePatchOptions#aiSource}.
288
+ */
289
+ aiSource?: AIOperationSource;
290
+ }
291
+ /**
292
+ * Options for {@link module:ai/toolkit/documentcompare~DocumentCompare#process}.
293
+ */
294
+ export interface DocumentCompareProcessOptions extends DocumentCompareComputePatchOptions {
295
+ /**
296
+ * What to do when the processing fails.
297
+ *
298
+ * By default, the underlying error is rethrown.
299
+ *
300
+ * When the options is set to `true`, the whole document is instead overwritten with the processed data
301
+ * via `editor.setData()` and {@link module:ai/toolkit/documentcompare~DocumentCompare#process} returns `false`.
302
+ *
303
+ * Note, that the overwrite is also performed in real-time collaboration environment, and it may roll back some edits made by remote
304
+ * users while `callback` was processing. Opt in only when overwriting the whole document is acceptable.
305
+ */
306
+ overwriteOnError?: boolean;
307
+ /**
308
+ * Whether the snapshot handed to `callback` is stamped with `data-id` attributes.
309
+ * See {@link ~DocumentCompareSnapshotOptions#useDataIds}.
310
+ *
311
+ * @default true
312
+ */
313
+ useDataIds?: boolean;
314
+ }
315
+ /**
316
+ * Options for {@link module:ai/toolkit/documentcompare~DocumentCompare#applyChange}.
317
+ */
318
+ export interface DocumentCompareApplyChangeOptions {
319
+ /**
320
+ * Whether the change is applied as track-changes suggestions (`true`) or directly (`false`).
321
+ *
322
+ * @default false
323
+ */
324
+ asSuggestions?: boolean;
325
+ }
326
+ /**
327
+ * The result of comparing a snapshot against processed data: the operations to bring the document to the new state,
328
+ * together with the snapshot metadata.
329
+ *
330
+ * Can be applied via {@link module:ai/toolkit/documentcompare~DocumentCompare#applyPatch}.
331
+ */
332
+ export interface DocumentComparePatch {
333
+ /**
334
+ * The channel of the document the snapshot was captured from, validated on apply.
335
+ */
336
+ channelId: string;
337
+ /**
338
+ * The editing session the snapshot was captured in, validated on apply.
339
+ */
340
+ sessionId: string;
341
+ /**
342
+ * The snapshot version the operations are anchored to (used to reconcile them on apply).
343
+ */
344
+ version: number;
345
+ /**
346
+ * Which AI feature produced the processed data the patch was computed from, or unset when it did not come from AI.
347
+ */
348
+ aiSource?: AIOperationSource;
349
+ /**
350
+ * How the patch is applied.
351
+ */
352
+ options: DocumentComparePatchOptions;
353
+ /**
354
+ * The operations to apply, keyed by root name (a root with no changes maps to an empty array).
355
+ */
356
+ operations: Record<string, Array<Operation>>;
357
+ }
@@ -3,7 +3,7 @@
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
4
  */
5
5
  /**
6
- * @module ai/aisdk/documentcompareutils
6
+ * @module ai/toolkit/documentcompareutils
7
7
  * @publicApi
8
8
  */
9
9
  import { Plugin } from "@ckeditor/ckeditor5-core";
@@ -3,22 +3,22 @@
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
4
  */
5
5
  /**
6
- * @module ai/aisdk/documentchanges
6
+ * @module ai/toolkit/documentdiffer
7
7
  */
8
8
  import { ContextPlugin, Editor, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
9
9
  import { ModelPosition, type ModelWriter, type ModelDocumentFragment, type ModelElement, type Operation } from "@ckeditor/ckeditor5-engine";
10
- import { DocumentChangesUtils } from "./documentchangesutils.js";
11
- export declare const DATA_ID_MODEL_ATTRIBUTE = "$elementId";
12
- export declare const DATA_ID_VIEW_ATTRIBUTE = "data-id";
10
+ import { DocumentDifferUtils } from "./documentdifferutils.js";
11
+ import { type ModelElementCategory } from "./elementcategory.js";
12
+ export { DATA_ID_MODEL_ATTRIBUTE, DATA_ID_VIEW_ATTRIBUTE } from "./elementcategory.js";
13
13
  /**
14
- * The `DocumentChanges` plugin provides utilities to compare two documents or documents fragments, and provide set of operations
14
+ * The `DocumentDiffer` plugin provides utilities to compare two documents or documents fragments, and provide set of operations
15
15
  * which need to be executed to transform one document into the other.
16
16
  */
17
- export declare class DocumentChanges extends ContextPlugin {
17
+ export declare class DocumentDiffer extends ContextPlugin {
18
18
  /**
19
19
  * @inheritDoc
20
20
  */
21
- static get pluginName(): "DocumentChanges";
21
+ static get pluginName(): "DocumentDiffer";
22
22
  /**
23
23
  * @inheritDoc
24
24
  */
@@ -27,7 +27,7 @@ export declare class DocumentChanges extends ContextPlugin {
27
27
  * @inheritDoc
28
28
  */
29
29
  static override get isPremiumPlugin(): true;
30
- static get requires(): PluginDependenciesOf<[DocumentChangesUtils]>;
30
+ static get requires(): PluginDependenciesOf<[DocumentDifferUtils]>;
31
31
  init(): Promise<void>;
32
32
  get editor(): Editor;
33
33
  /**
@@ -38,10 +38,25 @@ export declare class DocumentChanges extends ContextPlugin {
38
38
  * @param options Diffing options.
39
39
  * @returns Operations that need to be applied to transform `dataBefore` into `dataAfter`.
40
40
  */
41
- getDiff(dataBefore: string, dataAfter: string, options?: DocumentChangesOptions): Array<Operation>;
41
+ getDiff(dataBefore: string, dataAfter: string, options?: DocumentDifferOptions): Array<Operation>;
42
+ /**
43
+ * Creates the diff between two model document fragments.
44
+ *
45
+ * The same comparison {@link #getDiff} makes, for content that is already in the model. Serializing a fragment to
46
+ * reach that method is not a detour but a loss: an element whose downcast depends on its parent - a caption, a table
47
+ * row - has no serialized form on its own, and what the data processor makes of the result is not always what went in.
48
+ *
49
+ * The fragments are read and not kept: every node the operations carry is a copy.
50
+ *
51
+ * @param before The content to transform from.
52
+ * @param after The content to transform into.
53
+ * @param options Diffing options.
54
+ * @returns Operations that need to be applied to transform `before` into `after`.
55
+ */
56
+ getDiffForFragments(before: ModelDocumentFragment, after: ModelDocumentFragment, options?: DocumentDifferOptions): Array<Operation>;
42
57
  /**
43
58
  * Returns `true` if given `operation` is an operation that marks a content to be removed. This kind of operations can be
44
- * returned by {@link module:ai/aisdk/documentchanges~DocumentChanges#getOperations} if `markedDeletions` mode is enabled.
59
+ * returned by {@link module:ai/toolkit/documentdiffer~DocumentDiffer#getOperations} if `markedDeletions` mode is enabled.
45
60
  *
46
61
  * @param operation
47
62
  */
@@ -63,13 +78,18 @@ export declare class DocumentChanges extends ContextPlugin {
63
78
  */
64
79
  applyOperations(writer: ModelWriter, operations: Array<Operation>): void;
65
80
  }
66
- export interface DocumentChangesOptions {
81
+ export interface DocumentDifferOptions {
67
82
  anchor?: string | ModelPosition;
68
83
  markDeletions: boolean;
69
84
  /**
70
85
  * The editor whose model/schema should be used for parsing and for resolving a string `anchor` (e.g. multi-root root names).
71
86
  */
72
87
  targetEditor?: Editor;
88
+ /**
89
+ * When set, `data-id`s in the compared data are ignored and the elements of both documents are paired by content similarity.
90
+ * Use it when compared documents do not have `data-id`s set.
91
+ */
92
+ matchElements?: boolean;
73
93
  }
74
94
  export interface InsertOperationData {
75
95
  type: "insert";
@@ -141,18 +161,13 @@ export interface ModelElementToken {
141
161
  * Elements category.
142
162
  *
143
163
  * Describes how the element behaves and how it can change. It is used when comparing lists of model tokens to create a better diff.
144
- *
145
- * * `block` - elements like paragraphs, lists, or headings. Can be renamed. Can be created by splitting. Can be removed by merging.
146
- * Its contents can be "moved around" by splitting or merging.
147
- *
148
- * * `container` - elements like blockquote. Cannot be renamed. Can be created by wrapping. Can be removed by unwrapping. Can be
149
- * "resized" by having other elements be moved into or out of them.
150
- *
151
- * * `solid` - limit-like elements like table or image. Cannot be renamed, split or merged. Can be added by insertion and removed by
152
- * deletion. If added or removed, all their content also should be treated as added or removed.
164
+ * See {@link module:ai/toolkit/elementcategory~ModelElementCategory}.
153
165
  */
154
- category: "block" | "container" | "solid";
166
+ category: ModelElementCategory;
155
167
  isStart: boolean;
168
+ /**
169
+ * The chain of IDs of the limit-like elements the element stands in.
170
+ */
156
171
  limitId: string;
157
172
  }
158
173
  export interface ModelTextToken {
@@ -160,6 +175,9 @@ export interface ModelTextToken {
160
175
  data: string;
161
176
  parent: ModelElement | ModelDocumentFragment;
162
177
  offset: number;
178
+ /**
179
+ * The chain of IDs of the limit-like elements the text stands in.
180
+ */
163
181
  limitId: string;
164
182
  }
165
183
  export type Path = Array<number>;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
3
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
4
+ */
5
+ /**
6
+ * @module ai/toolkit/documentdifferutils
7
+ */
8
+ import { ContextPlugin } from "@ckeditor/ckeditor5-core";
9
+ export declare class DocumentDifferUtils extends ContextPlugin {
10
+ static get pluginName(): "DocumentDifferUtils";
11
+ static override get isOfficialPlugin(): true;
12
+ static override get isPremiumPlugin(): true;
13
+ init(): void;
14
+ override destroy(): void;
15
+ }