@ckeditor/ckeditor5-ai 48.4.0 → 48.5.0-alpha.0

package/dist/aisdk/documentcompare.d.ts

@@ -0,0 +1,171 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+/**
+* @module ai/aisdk/documentcompare
+* @publicApi
+*/
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { type Operation, type ModelRange } from "@ckeditor/ckeditor5-engine";
+import { DocumentChanges } from "./documentchanges.js";
+import { DocumentCompareUtils } from "./documentcompareutils.js";
+import { type DocumentCompareSnapshot } from "./documentsnapshot.js";
+/**
+* `DocumentCompare` provides a set of tools that allows you to process editor document data by custom external logic,
+* evaluate the differences between original and processed data, and apply them as granular changes or tracked
+* suggestions.
+*
+* Contrary to `editor.setData()`, this does not replace the whole editor
+* data. Instead, atomic changes are evaluated and a small set of changes is applied to the document. This is especially
+* useful when the editor also uses Track Changes, Revision History, and Real-Time Collaboration features.
+*
+* Use {@link #process `process()`}, to run the whole pipeline in one call - it takes document snapshot, processes the data,
+* and applies granular changes:
+*
+* ```ts
+* await documentCompare.process( async data => callMyService( data ) );
+*
+* // Or, to apply changes as suggestions:
+* await documentCompare.process( async data => callMyService( data ), { asSuggestions: true } );
+* ```
+*
+* Some integrations need to process the data in separate steps (e.g. backend processing, or when changes
+* are not applied immediately to the content). In this case, you can capture a snapshot first and apply the result later:
+*
+* ```ts
+* const snapshot = documentCompare.makeSnapshot();
+* const processed = await callMyService( snapshot.content );
+*
+* // ...
+*
+* const patch = documentCompare.diffSnapshot( snapshot, processed, { asSuggestions: true } );
+* documentCompare.applyPatch( patch );
+* ```
+*/
+export declare class DocumentCompare extends Plugin {
+	static get pluginName(): "DocumentCompare";
+	static get requires(): PluginDependenciesOf<[DocumentChanges, DocumentCompareUtils]>;
+	static override get isOfficialPlugin(): true;
+	static override get isPremiumPlugin(): true;
+	init(): void;
+	afterInit(): void;
+	/**
+	* Captures the current document state as a {@link module:ai/aisdk/documentsnapshot~DocumentCompareSnapshot}.
+	*
+	* The snapshot contains all data and metadata necessary to process the data and then be able to calculate differences between
+	* the original data and the processed data.
+	*
+	* Importantly, `snapshot.content` holds data for each root (excluding `$graveyard`) serialized to HTML. The data is stamped with
+	* `data-id` attributes, assigned to structural elements of the data. During processing, make sure that these `data-id`s are retained.
+	*
+	* See also {@link module:ai/aisdk/documentsnapshot~DocumentCompareSnapshot}.
+	*
+	* @param selection Ranges to capture with the snapshot as the user's selection. Must not intersect. By default no
+	* selection is captured.
+	* @returns The captured snapshot.
+	*/
+	makeSnapshot(selection?: Iterable<ModelRange>): DocumentCompareSnapshot;
+	/**
+	* Diffs the snapshot against processed data, returning a document patch - a set of granular differences between the two states.
+	*
+	* Use `options` to set whether the patch should be calculated and applied as tracked changes or as direct changes to the document.
+	*
+	* You can apply the patch using {@link #applyPatch}.
+	*
+	* @param snapshot The captured before-state to diff against.
+	* @param data The processed data. For multi-root editor, pass an object keyed by root name.
+	* @param options How the comparison is computed.
+	* @returns The patch bringing the document from the snapshot to the processed state.
+	*/
+	diffSnapshot(snapshot: DocumentCompareSnapshot, data: string | Record<string, string>, options?: DocumentCompareDiffOptions): DocumentComparePatch;
+	/**
+	* Applies a patch to the current state of the document.
+	*
+	* As a result, all changes described by the patch are reflected in the document. Note, that this converges with all
+	* changes that happened on the document after the snapshot was made, including both local and remote edits
+	* (if real-time collaboration is enabled).
+	*
+	* Note, that the patch can be only applied to the same document as the snapshot, and only during the same editing session.
+	* Otherwise, `documentcompare-apply-session-mismatch` error is thrown.
+	*
+	* The patch is first validated against a copy of the document before anything is committed.
+	* In case if any errors or conflict resolution problems surface during this dry-run, `documentcompare-invalid-patch`
+	* error is thrown, and the editor data is left intact.
+	*
+	* The changes can be applied directly to the content or as tracked suggestions (requires
+	* {@link module:track-changes/trackchanges~TrackChanges Track changes plugin}). See also {@link #diffSnapshot}.
+	*
+	* @param patch The patch to apply, as produced by {@link #diffSnapshot}.
+	*/
+	applyPatch(patch: DocumentComparePatch): void;
+	/**
+	* Runs the whole processing pipeline in one call: snapshots the document, hands the snapshot to `callback` for
+	* external processing (e.g. an AI service), then diffs returned data and applies granular changes to the document.
+	*
+	* If diffing or applying fails, the underlying error is rethrown and can be further handled,
+	* unless `options.setDataOnError` is set, in which case the current document is instead
+	* fully replaced with the processed data, the same way as if `editor.setData()` was used.
+	* In this case, changes that happened to the document after the snapshot was taken will be overwritten.
+	*
+	* @param callback Receives the captured snapshot and returns the processed data keyed by root name.
+	* @param options Additional processing options.
+	* @returns `true` when the process finished successfully and changes were applied granularly,
+	* `false` when the full-replacement fallback was used.
+	*/
+	process(callback: (snapshot: DocumentCompareSnapshot) => Promise<Record<string, string>>, options?: DocumentCompareProcessOptions): Promise<boolean>;
+}
+/**
+* Describes how a comparison is computed and, once recorded on a {@link ~DocumentComparePatch patch}, how it is applied.
+*/
+export interface DocumentCompareDiffOptions {
+	/**
+	* Whether the operations carry track-changes suggestion markers.
+	*/
+	asSuggestions?: boolean;
+}
+/**
+* Options for {@link module:ai/aisdk/documentcompare~DocumentCompare#process}.
+*/
+export interface DocumentCompareProcessOptions extends DocumentCompareDiffOptions {
+	/**
+	* What to do when the processing fails.
+	*
+	* By default, the underlying error is rethrown.
+	*
+	* When the options is set to `true`, the whole document is instead overwritten with the processed data
+	* via `editor.setData()` and {@link module:ai/aisdk/documentcompare~DocumentCompare#process} returns `false`.
+	*
+	* Note, that the overwrite is also performed in real-time collaboration environment, and it may roll back some edits made by remote
+	* users while `callback` was processing. Opt in only when overwriting the whole document is acceptable.
+	*/
+	setDataOnError?: boolean;
+}
+/**
+* The result of comparing a snapshot against processed data: the operations to bring the document to the new state,
+* together with the snapshot metadata.
+*
+* Can be applied via {@link module:ai/aisdk/documentcompare~DocumentCompare#applyPatch}.
+*/
+export interface DocumentComparePatch {
+	/**
+	* The channel of the document the snapshot was captured from, validated on apply.
+	*/
+	channelId: string;
+	/**
+	* The editing session the snapshot was captured in, validated on apply.
+	*/
+	sessionId: string;
+	/**
+	* The snapshot version the operations are anchored to (used to reconcile them on apply).
+	*/
+	version: number;
+	/**
+	* The options the patch was computed with, reused when applying it.
+	*/
+	options: DocumentCompareDiffOptions;
+	/**
+	* The operations to apply, keyed by root name (a root with no changes maps to an empty array).
+	*/
+	operations: Record<string, Array<Operation>>;
+}

package/dist/aisdk/documentcompareutils.d.ts

@@ -0,0 +1,16 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+/**
+* @module ai/aisdk/documentcompareutils
+* @publicApi
+*/
+import { Plugin } from "@ckeditor/ckeditor5-core";
+export declare class DocumentCompareUtils extends Plugin {
+	static get pluginName(): "DocumentCompareUtils";
+	static override get isOfficialPlugin(): true;
+	static override get isPremiumPlugin(): true;
+	init(): void;
+	override destroy(): void;
+}

package/dist/aisdk/documentsnapshot.d.ts

@@ -0,0 +1,48 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+/**
+* @module ai/aisdk/documentsnapshot
+* @publicApi
+*/
+import { type AIEditorConfig } from "../aicore/utils/geteditorconfig.js";
+/**
+* A captured selection range as character offsets into its root's serialized HTML.
+*/
+export interface DocumentCompareSnapshotRange {
+	start: number;
+	end: number;
+}
+/**
+* The captured before-state of a document plus the metadata to reconcile changes later.
+* The snapshot is a plain object and is safe to `JSON.stringify`, send between the frontend and backend, store, parse,
+* and later feed back into `DocumentCompare#diffSnapshot`.
+*/
+export interface DocumentCompareSnapshot {
+	/**
+	* The collaboration channel the snapshot was captured from.
+	*/
+	channelId: string;
+	/**
+	* The editing session the snapshot was captured in.
+	*/
+	sessionId: string;
+	/**
+	* The document version the snapshot was captured at.
+	*/
+	version: number;
+	/**
+	* Each root's content, serialized to HTML, keyed by root name (excluding `$graveyard`).
+	*/
+	content: Record<string, string>;
+	/**
+	* Each root's captured selection as character offsets into its HTML, keyed by root name (omitted if root has no selection).
+	*/
+	selection: Record<string, Array<DocumentCompareSnapshotRange>>;
+	/**
+	* The editor's feature configuration at capture time, so external processing can interpret the serialized HTML
+	* within the editor's capabilities.
+	*/
+	editorConfig: AIEditorConfig;
+}

package/dist/aisdk/extractselectionfromhtml.d.ts

@@ -0,0 +1,27 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+/**
+* @module ai/aisdk/extractselectionfromhtml
+*/
+import { type DocumentCompareSnapshotRange } from "./documentsnapshot.js";
+/**
+* The marker group used to render a captured selection into serialized HTML. Each range is added as
+* `documentcompare-selection:<i>` and downcast (opt-in via the `includeDocumentCompareSelection` option) to the
+* boundary elements below.
+*/
+export declare const SELECTION_MARKER = "documentcompare-selection";
+/** The boundary element names the selection markers downcast to. */
+export declare const SELECTION_START = "documentcompare-selection-start";
+export declare const SELECTION_END = "documentcompare-selection-end";
+/**
+* Strips the selection boundary elements from HTML serialized with the `includeDocumentCompareSelection` option.
+*
+* @param html HTML serialized with the selection boundary elements included.
+* @returns The clean HTML together with the selection as character offsets into it.
+*/
+export declare function extractSelectionFromHtml(html: string): {
+	content: string;
+	selection: Array<DocumentCompareSnapshotRange>;
+};

package/dist/aisdk/validateoperations.d.ts

@@ -0,0 +1,43 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+/**
+* @module ai/aisdk/validateoperations
+*/
+import { type Editor } from "@ckeditor/ckeditor5-core";
+import { type Operation } from "@ckeditor/ckeditor5-engine";
+/**
+* A failure found by {@link ~validateOperations} while trial-applying a patch's operations.
+*/
+export interface OperationValidationFailure {
+	/**
+	* What kind of failure occurred: `'unsupported'` for an operation the `DocumentCompare` API does not support,
+	* `'invalid'` for one that failed to trial-apply against a copy of the current document.
+	*/
+	reason: string;
+	/**
+	* The operation that failed.
+	*/
+	operation: Operation;
+	/**
+	* The underlying error thrown while trial-applying the operation, set when `reason` is `'invalid'`.
+	*/
+	cause?: Error;
+}
+/**
+* Trial-applies `operations` on temporary copies of the document's roots, to confirm they apply cleanly before they are
+* applied for real, so an unapplicable set is caught up front instead of failing mid-way, leaving the document corrupt.
+*
+* Each root (plus the graveyard, for remove/merge targets) is deep-cloned into a detached
+* {@link module:engine/model/documentfragment~ModelDocumentFragment}, and every operation is cloned and re-rooted onto
+* those copies and trial-applied there — `_validate()` then `_execute()`, as the real apply runs them. Marker
+* operations are skipped: they cannot fail structurally, so there is nothing to validate. Nothing is applied to the
+* live document.
+*
+* The function does not throw errors itself, instead it returns the first failure it finds (or `null` when the
+* operations all apply cleanly), and leaves it to the caller to throw the appropriate error.
+*
+* @returns The first operation failure, or `null` when all operations apply cleanly.
+*/
+export declare function validateOperations(editor: Editor, operations: Array<Operation>): OperationValidationFailure | null;

package/dist/aitranslate/model/aitranslatecheckrun.d.ts

@@ -9,7 +9,7 @@ import { type AIConnector } from "../../aicore/aiconnector.js";
 import { type AIDocumentData } from "../../aireviewcore/aireviewcoreediting.js";
 import { type AIReviewCheck } from "../../aireviewcore/model/aireviewcheck.js";
 import { AIReviewSystemCheckRun } from "../../aireviewcore/model/aireviewsystemcheckrun.js";
-import { type AIContextRef } from "../../aicore/model/aicontextref.js";
+import { type AIContext } from "../../aicore/model/aicontext.js";
 /**
 * Represents a single translate check run and its results.
 */
@@ -17,7 +17,7 @@ export declare class AITranslateCheckRun extends AIReviewSystemCheckRun {
 	/**
 	* @inheritDoc
 	*/
-	constructor(documentData: AIDocumentData, sourceCheck: AIReviewCheck, connector: AIConnector, title: string, params?: Array<string>, args?: Record<string, any>, contexts?: Array<AIContextRef>);
+	constructor(documentData: AIDocumentData, sourceCheck: AIReviewCheck, connector: AIConnector, title: string, params?: Array<string>, args?: Record<string, any>, context?: AIContext);
 	/**
 	* @inheritDoc
 	*/

package/dist/index.d.ts

@@ -76,6 +76,9 @@ export { AITranslate, type AITranslateConfig, type AITranslateLanguage } from ".
 export { AITranslateController } from "./aitranslate/aitranslatecontroller.js";
 export { AITranslateUI } from "./aitranslate/aitranslateui.js";
 export { AITranslateGateway, type AITranslateRunOptions } from "./aitranslate/aitranslategateway.js";
+export { DocumentCompare, type DocumentCompareDiffOptions, type DocumentCompareProcessOptions, type DocumentComparePatch } from "./aisdk/documentcompare.js";
+export type { DocumentCompareSnapshot, DocumentCompareSnapshotRange } from "./aisdk/documentsnapshot.js";
+export type { AIEditorConfig } from "./aicore/utils/geteditorconfig.js";
 import "../theme/index-editor.css";
 import "../theme/index-content.css";
 import "./augmentation.js";