@ckeditor/ckeditor5-ai 48.2.0-alpha.7 → 48.3.0-alpha.0

package/dist/aicore/aiediting.d.ts

@@ -1,108 +1,108 @@
 /**
- * @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
- */
+* @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/aicore/aiediting
- */
-import { type ModelRange, type ModelDocumentFragment } from '@ckeditor/ckeditor5-engine';
-import { ContextPlugin, type Context, Editor } from '@ckeditor/ckeditor5-core';
+* @module ai/aicore/aiediting
+*/
+import { type ModelRange, type ModelDocumentFragment } from "@ckeditor/ckeditor5-engine";
+import { ContextPlugin, type Context, Editor } from "@ckeditor/ckeditor5-core";
 export declare const AI_VISUAL_SELECTION_MARKER_NAME = "ai-selection";
 export declare class AIEditing extends ContextPlugin {
-    /**
-     * @inheritDoc
-     */
-    constructor(context: Context | Editor);
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "AIEditing";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * Returns the session ID for the given editor. If the editor has the
-     * {@link module:real-time-collaboration/realtimecollaborativeediting/realtimecollaborationclient~RealTimeCollaborationClient}
-     * plugin its `sessionId` is reused; otherwise a random id is generated on first call and cached for the editor's lifetime.
-     *
-     * The session id is used to determine whether AI chat changes were created in the same editing session (and therefore
-     * can be safely applied) or in a different one. Each editor in the context has its own session id, so multi-editor and
-     * multi-root setups can route the mismatch check against the editor that actually produced the change.
-     */
-    getSessionId(editor: Editor): string;
-    /**
-     * Returns the data and version of each document (one entry per editor root, excluding `$graveyard`).
-     *
-     * `rootName` and `channelId` identify the source of each entry so callers can remap AI modifications back to the editor and root
-     * they came from.
-     */
-    getDocumentData(): Promise<Array<AIEditingDocumentData>>;
-    afterInit(): void;
-    /**
-     * Displays a fake visual selection on given ranges.
-     *
-     * Since multiple features may want to show and hide the selection, while at the same time, only one fake selection should be shown,
-     * it is necessary to provide an `id` when showing fake selection. Then, when the fake selection should be hidden, `id` must be
-     * passed as well. This mechanism prevents a feature from mistakenly hiding a fake selection set by another feature.
-     */
-    showFakeVisualSelection(fakeSelectionData: FakeSelectionData): void;
-    /**
-     * Removes a fake visual selection from the document.
-     *
-     * @param id ID of the fake visual selection to remove.
-     */
-    hideFakeVisualSelection(id: string): void;
-    modelToDataWithIds(modelFragment: ModelDocumentFragment, editor: Editor): Promise<string>;
+	/**
+	* @inheritDoc
+	*/
+	constructor(context: Context | Editor);
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AIEditing";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* Returns the session ID for the given editor. If the editor has the
+	* {@link module:real-time-collaboration/realtimecollaborativeediting/realtimecollaborationclient~RealTimeCollaborationClient}
+	* plugin its `sessionId` is reused; otherwise a random id is generated on first call and cached for the editor's lifetime.
+	*
+	* The session id is used to determine whether AI chat changes were created in the same editing session (and therefore
+	* can be safely applied) or in a different one. Each editor in the context has its own session id, so multi-editor and
+	* multi-root setups can route the mismatch check against the editor that actually produced the change.
+	*/
+	getSessionId(editor: Editor): string;
+	/**
+	* Returns the data and version of each document (one entry per editor root, excluding `$graveyard`).
+	*
+	* `rootName` and `channelId` identify the source of each entry so callers can remap AI modifications back to the editor and root
+	* they came from.
+	*/
+	getDocumentData(): Promise<Array<AIEditingDocumentData>>;
+	afterInit(): void;
+	/**
+	* Displays a fake visual selection on given ranges.
+	*
+	* Since multiple features may want to show and hide the selection, while at the same time, only one fake selection should be shown,
+	* it is necessary to provide an `id` when showing fake selection. Then, when the fake selection should be hidden, `id` must be
+	* passed as well. This mechanism prevents a feature from mistakenly hiding a fake selection set by another feature.
+	*/
+	showFakeVisualSelection(fakeSelectionData: FakeSelectionData): void;
+	/**
+	* Removes a fake visual selection from the document.
+	*
+	* @param id ID of the fake visual selection to remove.
+	*/
+	hideFakeVisualSelection(id: string): void;
+	modelToDataWithIds(modelFragment: ModelDocumentFragment, editor: Editor): Promise<string>;
 }
 /**
- * A single document entry returned by {@link module:ai/aicore/aiediting~AIEditing#getDocumentData `AIEditing#getDocumentData()`}. One
- * entry per editor model root (excluding `$graveyard`); `editor` + `rootName` identify the source root so callers can route AI
- * modifications back to the correct place.
- */
+* A single document entry returned by {@link module:ai/aicore/aiediting~AIEditing#getDocumentData `AIEditing#getDocumentData()`}. One
+* entry per editor model root (excluding `$graveyard`); `editor` + `rootName` identify the source root so callers can route AI
+* modifications back to the correct place.
+*/
 export type AIEditingDocumentData = {
-    editor: Editor;
-    rootName: string;
-    content: string;
-    version: number;
-    sessionId: string;
-    channelId: string;
-    selections: Array<{
-        markerName: string;
-        start: number;
-        end: number;
-        htmlFragment: string;
-    }>;
-    name?: string;
-    description?: string;
+	editor: Editor;
+	rootName: string;
+	content: string;
+	version: number;
+	sessionId: string;
+	channelId: string;
+	selections: Array<{
+		markerName: string;
+		start: number;
+		end: number;
+		htmlFragment: string;
+	}>;
+	name?: string;
+	description?: string;
 };
 type FakeSelectionData = {
-    /**
-     * Ranges on which fake selection should be shown.
-     */
-    ranges: Array<ModelRange>;
-    /**
-     * Fake selection ID.
-     *
-     * Used when removing fake selection.
-     *
-     * Used as a part of CSS class set on fake selection DOM elements (`ck-fake-ai-selection-${ id }`).
-     */
-    id: string;
-    /**
-     * Fake selection priority.
-     *
-     * There can be only one fake selection displayed at once. Priority is used to inform which fake selection should be displayed when
-     * multiple features asked to show fake selection on different ranges.
-     */
-    priority: number;
-    /**
-     * Editor instance in which the fake selection is created.
-     */
-    editor: Editor;
+	/**
+	* Ranges on which fake selection should be shown.
+	*/
+	ranges: Array<ModelRange>;
+	/**
+	* Fake selection ID.
+	*
+	* Used when removing fake selection.
+	*
+	* Used as a part of CSS class set on fake selection DOM elements (`ck-fake-ai-selection-${ id }`).
+	*/
+	id: string;
+	/**
+	* Fake selection priority.
+	*
+	* There can be only one fake selection displayed at once. Priority is used to inform which fake selection should be displayed when
+	* multiple features asked to show fake selection on different ranges.
+	*/
+	priority: number;
+	/**
+	* Editor instance in which the fake selection is created.
+	*/
+	editor: Editor;
 };
 export {};

package/dist/aicore/aierrorreporter.d.ts

@@ -0,0 +1,73 @@
+/**
+* @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/aicore/aierrorreporter
+* @publicApi
+*/
+import { ContextPlugin } from "@ckeditor/ckeditor5-core";
+/**
+* Payload of the {@link module:ai/aicore/aierrorreporter~AIErrorSinkErrorEvent} sink event.
+*/
+export interface AIErrorSinkEventData {
+	error: unknown;
+	component: string;
+	context?: Record<string, unknown>;
+}
+/**
+* Options accepted by {@link module:ai/aicore/aierrorreporter~AIErrorReporter} report calls.
+*/
+export interface AIErrorReporterOptions {
+	/**
+	* Catch-site context (operation labels, interaction/conversation IDs, etc.).
+	*/
+	context?: Record<string, unknown>;
+}
+/**
+* Event fired by {@link module:ai/aicore/aierrorreporter~AIErrorSink} whenever a non-abort AI
+* error is reported.
+*/
+export interface AIErrorSinkErrorEvent {
+	name: "error";
+	args: [data: AIErrorSinkEventData];
+}
+/**
+* Centralized event sink for AI-related errors. Thin event emitter — each feature creates its
+* own {@link module:ai/aicore/aierrorreporter~AIErrorReporter} via
+* {@link module:ai/aicore/aierrorreporter~AIErrorSink#createReporter} and routes failures
+* through that.
+*/
+export declare class AIErrorSink extends ContextPlugin {
+	static get pluginName(): "AIErrorSink";
+	static override get isOfficialPlugin(): true;
+	static override get isPremiumPlugin(): true;
+	/**
+	* Creates a per-feature {@link module:ai/aicore/aierrorreporter~AIErrorReporter} tagged
+	* with the given `component`.
+	*
+	* ```ts
+	* this._reporter = this.editor.plugins.get( AIErrorSink ).createReporter( 'aichat' );
+	* this._reporter.logError( err );
+	* ```
+	*/
+	createReporter(component: string): AIErrorReporter;
+}
+/**
+* Per-feature reporter created via {@link
+* module:ai/aicore/aierrorreporter~AIErrorSink#createReporter}.
+*/
+export declare class AIErrorReporter {
+	/**
+	* Created via {@link module:ai/aicore/aierrorreporter~AIErrorSink#createReporter}.
+	*/
+	constructor(sink: AIErrorSink, component: string);
+	/**
+	* Forwards the error to the sink and writes it to the console. Aborts are dropped.
+	*/
+	logError(error: unknown, options?: AIErrorReporterOptions): void;
+	/**
+	* Forwards the error to the sink without writing to the console. Aborts are dropped.
+	*/
+	reportError(error: unknown, options?: AIErrorReporterOptions): void;
+}

package/dist/aicore/aigateway.d.ts

@@ -1,63 +1,103 @@
 /**
- * @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
- */
+* @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/aicore/aigateway
- * @publicApi
- */
-import { ContextPlugin, type Editor } from '@ckeditor/ckeditor5-core';
-import { type AIRunResult } from './model/airunresult.js';
-import { AIResponseApplier } from './pipeline/airesponseapplier.js';
+* @module ai/aicore/aigateway
+* @publicApi
+*/
+import { ContextPlugin, type PluginDependenciesOf, type Editor } from "@ckeditor/ckeditor5-core";
+import { DocumentCompare } from "@ckeditor/ckeditor5-collaboration-core";
+import { AIResponseApplier } from "./pipeline/airesponseapplier.js";
+import { type AIRunResult } from "./model/airunresult.js";
+import { type AIModelData } from "./aiconnector.js";
+import { type AIOperationSource } from "./utils/markoperationsasai.js";
 /**
- * How AI run changes are applied to the editor when using {@link module:ai/aicore/aigateway~AIGateway#apply}.
- */
-export type AIRunApplyMethod = 'suggest' | 'insert';
+* How AI run changes are applied to the editor when using {@link module:ai/aicore/aigateway~AIGateway#apply}.
+*/
+export type AIRunApplyMethod = "suggest" | "insert";
 /**
- * A single AI suggestion.
- *
- * The suggestion refers to a single block element modified by AI. The `id` is a unique identifier of the modified element. It is the same
- * as `data-id` attribute for this element in the initial content. The `content` is the HTML content of the modified
- * block element with all AI changes applied.
- */
+* A single AI suggestion.
+*
+* The suggestion refers to a single block element modified by AI. The `id` is a unique identifier of the modified element. It is the same
+* as `data-id` attribute for this element in the initial content. The `content` is the HTML content of the modified
+* block element with all AI changes applied.
+*/
 export type AIRunChangeData = {
-    id: string;
-    content: string;
+	id: string;
+	content: string;
 };
 /**
- * Base plugin exposing common methods for end-to-end public AI API.
- */
+* Base options for running an AI operation via various available gateways.
+*/
+export type AIRunBaseOptions = {
+	/**
+	* An `AbortSignal` that cancels the run when aborted. Aborted runs resolve with `status: 'aborted'`.
+	*/
+	signal?: AbortSignal;
+};
+export type AIGatewayApplyOptions = {
+	/**
+	* How AI run changes are applied to the editor content.
+	*
+	* With `'insert'` the changes are written directly into the editor content. With `'suggest'` they are wrapped as
+	* track-changes suggestions — this requires the `TrackChanges` plugin to be loaded on the editor.
+	*/
+	applyMethod: AIRunApplyMethod;
+	/**
+	* AI source identifier stamped on every operation produced for this run.
+	*
+	* Defaults to `'api'`.
+	*
+	* Note that when `applyMethod` is `'suggest'`, every created suggestion also receives the `@ai`
+	* {@link module:track-changes/suggestion~Suggestion#attributes attribute} with the same identifier. The track changes
+	* plugin uses this attribute to display the suggestion as AI-generated.
+	*/
+	aiSource?: AIOperationSource;
+};
+/**
+* Base plugin exposing common methods for end-to-end public AI API.
+*/
 export declare class AIGateway extends ContextPlugin {
-    /**
-     * @inheritDoc
-     */
-    static get pluginName(): "AIGateway";
-    /**
-     * @inheritDoc
-     */
-    static get isOfficialPlugin(): true;
-    /**
-     * @inheritDoc
-     */
-    static get isPremiumPlugin(): true;
-    /**
-     * Applies the AI run result to the editor content.
-     *
-     * With `applyMethod: 'insert'` the changes are written directly into the editor content. With `applyMethod: 'suggest'` they are
-     * wrapped as track-changes suggestions — this requires the `TrackChanges` plugin to be loaded on the editor, and
-     * throws `ai-no-track-changes` otherwise.
-     *
-     * @experimental **Experimental:** This is a production-ready API but may change in minor releases
-     * without the standard deprecation policy. Check the changelog for migration guidance.
-     * @param result The result of a completed AI run.
-     * @param applyMethod Method of applying the review suggestions to the editor content.
-     */
-    apply(result: AIRunResult, applyMethod: AIRunApplyMethod): void;
-    /**
-     * Merges the AI changes with the original content, creating the final document content with all AI changes applied.
-     *
-     * @experimental **Experimental:** This is a production-ready API but may change in minor releases
-     * without the standard deprecation policy. Check the changelog for migration guidance.
-     */
-    mergeChangesIntoContent(changes: Array<AIRunChangeData>, content: string, editor: Editor): ReturnType<AIResponseApplier['merge']>['parsedContent'];
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AIGateway";
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[DocumentCompare]>;
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* Returns the list of AI models available to be used with AI gateway features.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	getAvailableModels(): Promise<Array<AIModelData>>;
+	/**
+	* Applies the AI run result to the editor content.
+	*
+	* Throws `ai-no-track-changes` when `options.applyMethod` is `'suggest'` and the `TrackChanges` plugin is not loaded.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	* @param result The result of a completed AI run.
+	* @param options Additional options.
+	*/
+	apply(result: AIRunResult, options: AIGatewayApplyOptions): void;
+	/**
+	* Merges the AI changes with the original content, creating the final document content with all AI changes applied.
+	*
+	* @experimental **Experimental:** This is a production-ready API but may change in minor releases
+	* without the standard deprecation policy. Check the changelog for migration guidance.
+	*/
+	mergeChangesIntoContent(changes: ReadonlyArray<AIRunChangeData>, content: string, editor: Editor): ReturnType<AIResponseApplier["merge"]>["parsedContent"];
 }

package/dist/aicore/errors/aicoreerror.d.ts

@@ -0,0 +1,67 @@
+/**
+* @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
+*/
+/**
+* Severity of an AI error.
+*/
+export type AICoreErrorSeverity = "error" | "warning";
+/**
+* Classification of the error.
+*
+* * `system` — application or integrator setup is wrong; fix in code or configuration.
+* * `runtime` — runtime state / invariant violation; investigate the path.
+* * `network` — external / temporary; expected to recover.
+* * `user` — invalid user input or action; surfaced via UI.
+*/
+export type AICoreErrorType = "system" | "runtime" | "network" | "user";
+/**
+* Initialization object for {@link module:ai/aicore/errors/aicoreerror~AICoreError}.
+*/
+export interface AICoreErrorInit {
+	/**
+	* Short identifier for the error (e.g. `'ai-applying-suggestion-failed'`).
+	*/
+	code: string;
+	/**
+	* Error that triggered this one. Exposed via the native `Error.cause` chain and used
+	* to infer abort state.
+	*/
+	cause?: unknown;
+	/**
+	* Defaults to `'error'`.
+	*/
+	severity?: AICoreErrorSeverity;
+	/**
+	* Defaults to `'system'`.
+	*/
+	type?: AICoreErrorType;
+	/**
+	* Metadata (identifiers, codes, sizes).
+	*/
+	context?: Record<string, unknown>;
+	/**
+	* User-initiated cancellation. Defaults to whatever is inferred from `cause`.
+	*/
+	isAbort?: boolean;
+}
+/**
+* AI-specific error class. Intentionally does **not** extend `CKEditorError`:
+*
+* * `data` is not stringified into the message.
+* * Watchdog does not catch and restart the editor for AI failures.
+* * Uses the native `cause` chain to preserve the original error.
+*/
+export declare class AICoreError extends Error {
+	readonly code: string;
+	readonly severity: AICoreErrorSeverity;
+	readonly type: AICoreErrorType;
+	readonly context?: Record<string, unknown>;
+	readonly isAbort: boolean;
+	/**
+	* Creates a new AI core error.
+	*
+	* @param init Initialization fields. See {@link module:ai/aicore/errors/aicoreerror~AICoreErrorInit}.
+	*/
+	constructor(init: AICoreErrorInit);
+}

package/dist/aicore/errors/geterrorcode.d.ts

@@ -0,0 +1,17 @@
+/**
+* @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
+*/
+/**
+* Returns the error code regardless of the error class. Reads `error.code` from an
+* {@link AICoreError}; for any other `Error` (such as `CKEditorError`) returns the leading
+* non-whitespace token of `error.message`. Returns `undefined` for non-Error inputs or empty
+* messages.
+*
+* The whitespace-aware split matters for `CKEditorError`, whose message is
+* `<code>\nRead more: …` — a plain space split would return `<code>\nRead`.
+*
+* Use this at call sites that branch on the error code so they keep working as throw sites
+* migrate from `CKEditorError` to {@link AICoreError}.
+*/
+export declare function getErrorCode(error: unknown): string | undefined;

package/dist/aicore/errors/isaborterror.d.ts

@@ -0,0 +1,12 @@
+/**
+* @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/aicore/errors/isaborterror
+*/
+/**
+* Returns `true` if the given value represents an abort: a DOM `AbortError`, an `AICoreError`
+* with `isAbort` set, or an `Error` whose message starts with `'ai-request-aborted'`.
+*/
+export declare function isAbortError(error: unknown): boolean;

package/dist/aicore/errors/normalizeerror.d.ts

@@ -0,0 +1,18 @@
+/**
+* @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/aicore/errors/normalizeerror
+*/
+import { CKEditorError } from "@ckeditor/ckeditor5-utils";
+/**
+* Wraps an arbitrary thrown value in a {@link module:utils/ckeditorerror~CKEditorError} with the given `errorName`,
+* unless it already is a `CKEditorError`.
+*
+* @param error The thrown value to normalize.
+* @param errorName The `error-name` used when wrapping a non-`CKEditorError`.
+* @param context The error context (typically the plugin instance) used by the watchdog.
+* @param contextInfo Additional data describing the error.
+*/
+export declare function normalizeError(error: any, errorName: string, context: object | null, contextInfo?: Record<string, unknown>): CKEditorError;