@ckeditor/ckeditor5-ai 48.8.1-alpha.4 → 49.0.0-alpha.0

package/dist/aicore/aicore.d.ts

@@ -0,0 +1,53 @@
+/**
+* @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/aicore
+* @publicApi
+*/
+import { ContextPlugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { AIConnector } from "./aiconnector.js";
+import { AIModels } from "./model/aimodels.js";
+import { AIContextLibrary } from "./model/aicontextlibrary.js";
+/**
+* A shared, context-level home for cross-feature AI state.
+*
+* It owns a single {@link module:ai/aicore/model/aimodels~AIModels} instance so the model list is
+* fetched once and shared across all AI features (chat, quick actions, review mode, gateway) instead
+* of each feature building its own. Access it via {@link #models}.
+*
+* It owns a single {@link module:ai/aicore/model/aicontextlibrary~AIContextLibrary} instance
+* so the list of contexts available to the current token is fetched once and shared. Access it via
+* {@link #contextLibrary}.
+*/
+export declare class AICore extends ContextPlugin {
+	/**
+	* The shared model registry — fetched once and shared across all AI features.
+	*/
+	models: AIModels;
+	/**
+	* The shared context library, fetched once and shared across all AI features.
+	*/
+	contextLibrary: AIContextLibrary;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "AICore";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[AIConnector]>;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
+}

package/dist/aicore/aiediting.d.ts

@@ -1,99 +1,114 @@
 /**
- * @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";
+import { type AIEditorConfig } from "./utils/geteditorconfig.js";
 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;
-    /**
-     * Gets the current session ID. If RTC plugin is available, uses its sessionId.
-     * Otherwise, generates a random ID for the current (non-RTC) session.
-     */
-    get sessionId(): 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(): Promise<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): 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.
+	*
+	* Note, that this method is async and does significant processing if the editor data is big or custom output processor is registered.
+	* If you just want to fetch the session id or document version, use {@link #getSessionId} and {@link #getEditorsVersions}.
+	*/
+	getDocumentData(channelIds?: Set<string>): 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, rootName?: string): 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;
+	}>;
+	selectionSignature: string;
+	editorConfig: AIEditorConfig;
+	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;
+	/**
+	* 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,101 @@
+/**
+* @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";
+import { type AICoreErrorSeverity, type AICoreErrorType } from "./errors/aicoreerror.js";
+/**
+* Payload of the {@link module:ai/aicore/aierrorreporter~AIErrorSinkErrorEvent} sink event.
+*
+* Error reporting services serialize only `name`, `message` and `stack` of an `Error`, so everything a
+* reported {@link module:ai/aicore/errors/aicoreerror~AICoreError} carries as its own properties is
+* flattened here. A subscriber can therefore classify and forward the failure without inspecting the
+* error itself.
+*/
+export interface AIErrorSinkEventData {
+	error: unknown;
+	component: string;
+	/**
+	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#code Code} of the reported error, for example
+	* `'ai-chat-file-upload-failed'`. `undefined` for errors that are not an `AICoreError`.
+	*/
+	code?: string;
+	/**
+	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#type Classification} of the reported error.
+	* Use it to skip the failures that are not actionable telemetry: `'user'` (surfaced via UI) and
+	* `'network'` (transient). `undefined` for errors that are not an `AICoreError`.
+	*/
+	type?: AICoreErrorType;
+	/**
+	* {@link module:ai/aicore/errors/aicoreerror~AICoreError#severity Severity} of the reported error.
+	* `undefined` for errors that are not an `AICoreError`.
+	*/
+	severity?: AICoreErrorSeverity;
+	/**
+	* Metadata carried by the reported {@link module:ai/aicore/errors/aicoreerror~AICoreError#context error}
+	* merged with the catch-site {@link module:ai/aicore/aierrorreporter~AIErrorReporterOptions#context context},
+	* the latter winning on key conflicts. `undefined` when neither is present.
+	*/
+	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.). Merged over the
+	* context of the reported error.
+	*/
+	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

@@ -0,0 +1,135 @@
+/**
+* @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 PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { DocumentChanges } from "../aisdk/documentchanges.js";
+import { AICore } from "./aicore.js";
+import { type AIModels } from "./model/aimodels.js";
+import { AIResponseApplier } from "./pipeline/airesponseapplier.js";
+import { type AIEditorRoot } from "./model/aieditorroot.js";
+import { type AIOperationSource } from "./utils/markoperationsasai.js";
+import type { AIRunResult } from "./model/airunresult.js";
+import { type AIContextRef } from "./model/aicontextref.js";
+/**
+* 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.
+*/
+export type AIRunChangeData = {
+	id: string;
+	content: string;
+};
+/**
+* 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;
+	/**
+	* Context references attached to the request.
+	*
+	* @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.
+	*/
+	contexts?: Array<AIContextRef>;
+};
+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;
+	/**
+	* Restrict the apply to a subset of the result's per-root entries. Each entry's `channelId` and `rootName` must match
+	* a per-root sub-result in the passed `AIRunResult`. When omitted, every entry in `result.results` is applied.
+	*/
+	roots?: Array<AIEditorRoot>;
+};
+/**
+* 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 requires(): PluginDependenciesOf<[DocumentChanges, AICore]>;
+	/**
+	* The shared model registry. Exposed here so headless gateways are self-sufficient — integrators can
+	* discover and resolve models (`getAvailableModels()`, `getModel()`, `resolveModel()`, …) without
+	* reaching for the `AICore` plugin directly.
+	*
+	* @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.
+	*/
+	get models(): AIModels;
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	static override get isPremiumPlugin(): true;
+	/**
+	* Applies an AI run result to editor content. Accepts the whole `AIRunResult` — per-root sub-results targeting
+	* the same editor are batched into one `model.change()` block, so all of that editor's roots become a single
+	* undoable step. An optional `options.roots` filter restricts the apply to a subset of the sub-results without the
+	* caller having to unpack or repack the result.
+	*
+	* Refuses the call up front only on whole-run failures (`result.error` set or empty `result.results`). Per-root
+	* failures on an otherwise successful run are validated after the filter, so the caller can filter around the
+	* failed roots via `options.roots` and still apply the completed ones. If any *included* sub-result fails
+	* validation the whole call throws before touching any editor, so partial applies can't leave content in a
+	* mixed state.
+	*
+	* `options.roots` is validated at the call boundary — an explicitly empty array throws
+	* `ai-gateway-apply-empty-roots`, and any entry that does not match a per-root sub-result in
+	* `result.results` throws `ai-gateway-apply-root-not-found`.
+	*
+	* Also throws `ai-gateway-apply-invalid-status` when the whole run failed or when any included sub-result's
+	* `status` is not `'completed'`, and `ai-no-track-changes` when `options.applyMethod` is `'suggest'` and any
+	* targeted editor is missing the `TrackChanges` plugin.
+	*
+	* @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): 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.
+* * AI failures are not reported to the editor error callbacks.
+* * 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,23 @@
+/**
+* @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`.
+*
+* If the thrown value carries a `data` field (as backend API errors do — see {@link module:ai/aicore/aiconnector~AIConnector}),
+* it is attached to the wrapped error as `data.backendData` so consumers can inspect the backend's structured response
+* (for example `issues[]` describing which fields failed validation).
+*
+* @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) by which error reporting works out which
+* editor the error came from.
+* @param contextInfo Additional data describing the error.
+*/
+export declare function normalizeError(error: any, errorName: string, context: object | null, contextInfo?: Record<string, unknown>): CKEditorError;