@ckeditor/ckeditor5-engine 48.1.0 → 48.2.0-alpha.0

package/dist/controller/datacontroller.d.ts

@@ -200,6 +200,13 @@ export declare class DataController extends /* #__PURE__ */ DataController_base
      * Returns the data parsed by the {@link #processor data processor} and then converted by upcast converters
      * attached to the {@link #upcastDispatcher}.
      *
+     * **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a
+     * custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+     * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+     * explicitly, otherwise the conversion result may be wrong.
+     * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+     * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+     *
      * @see #set
      * @param data Data to parse.
      * @param context Base context in which the view will be converted to the model.
@@ -215,6 +222,13 @@ export declare class DataController extends /* #__PURE__ */ DataController_base
      * When marker elements were converted during the conversion process, it will be set as a document fragment's
      * {@link module:engine/model/documentfragment~ModelDocumentFragment#markers static markers map}.
      *
+     * **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a
+     * custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+     * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+     * explicitly, otherwise the conversion result may be wrong.
+     * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+     * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+     *
      * @fires toModel
      * @param viewElementOrFragment The element or document fragment whose content will be converted.
      * @param context Base context in which the view will be converted to the model.

package/dist/conversion/upcastdispatcher.d.ts

@@ -157,6 +157,13 @@ export declare class UpcastDispatcher extends /* #__PURE__ */ UpcastDispatcher_b
     /**
      * Starts the conversion process. The entry point for the conversion.
      *
+     * **Note:** The default `context` value is `[ '$root' ]`, which only matches the generic root. When the editor uses
+     * a custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+     * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+     * explicitly, otherwise the conversion result may be wrong.
+     * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+     * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+     *
      * @fires element
      * @fires text
      * @fires documentFragment

package/dist/dev-utils/model.d.ts

@@ -105,6 +105,13 @@ export declare function _stringifyModel(node: ModelNode | ModelDocumentFragment,
  * <$text attribute="value">Text data</$text>
  * ```
  *
+ * **Note:** The default `options.context` value is `'$root'`, which only matches the generic root. When the editor
+ * uses a custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+ * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+ * explicitly, otherwise the conversion result may be wrong.
+ * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+ * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+ *
  * @param data HTML-like string to be parsed.
  * @param schema A schema instance used by converters for element validation.
  * @param options Additional configuration.

package/dist/index-editor.css

@@ -16,9 +16,14 @@
   content:attr(data-placeholder);
   cursor:text;
   pointer-events:none;
+  padding-left:inherit;
+  padding-right:inherit;
+  white-space:nowrap;
+  text-overflow:ellipsis;
   position:absolute;
   left:0;
   right:0;
+  overflow:hidden;
 }
 
 @media (forced-colors: none){

package/dist/index.css

@@ -16,9 +16,14 @@
   content: attr(data-placeholder);
   cursor: text;
   pointer-events: none;
+  padding-left: inherit;
+  padding-right: inherit;
+  white-space: nowrap;
+  text-overflow: ellipsis;
   position: absolute;
   left: 0;
   right: 0;
+  overflow: hidden;
 }
 
 @media (forced-colors: none) {

package/dist/index.css.map

@@ -1 +1 @@
-{"version":3,"sources":["../theme/placeholder.css","index.css","../theme/renderer.css"],"names":[],"mappings":";;;;AAMA,CAAA,EAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA;ACLA,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ;AACpB;;ADOC,CAAA,KAAA,CAAA,CAAA,MAAA,CAAA,MAAA,CAAA,CAAA,MAAA,CAAA,CAAA;ACJD,CAAC,CDIgC,CAAA,EAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA;ACHjC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK;AAC9C,CAAC,CAAC;AACF;;ADSC,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,MAAA,CAAA;ACND,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;AACjC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI;AACd,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI;AACtB,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ;AACpB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACT,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACV;;ADWE,CAAA,KAAA,CAAA,CAAA,MAAA,CAAA,MAAA,CAAA,CAAA,IAAA,CAAA,CAAA;ACRF,CAAC,CDQ+B,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,MAAA,CAAA;ACPhC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;AAClD,CAAC,CAAC;AACF;;ADSE,CAAA,KAAA,CAAA,CAAA,MAAA,CAAA,MAAA,CAAA,CAAA,MAAA,CAAA,CAAA;ACNF,CAAC,CDMiC,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA,CAAA,MAAA,CAAA;ACLlC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG;AACpB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM;AACtB,CAAC,CAAC;AACF;;ADoBC,CAAA,EAAA,CAAA,EAAA,CAAA,IAAA,CAAA,IAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA,MAAA,CAAA;ACjBD,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI;AACf;;ADyBA,CAAA,EAAA,CAAA,EAAA,CAAA,SAAA,CAAA,CAAA,EAAA,CAAA,WAAA,CAAA;ACtBA,CAAC,CAAC,QAAQ,CAAC,CAAC,QAAQ;AACpB;;AChCA,CAAA,EAAA,CAAA,EAAA,CAAA,gBAAA,CAAA,IAAA,CAAA,IAAA,CAAA,EAAA,CAAA,MAAA,CAAA,OAAA,CAAA,CAAA;ADmCA,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI;AACf;;AAEA,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC","file":"index.css.map","sourcesContent":["/*\n * Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.\n * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options\n */\n\n\n.ck.ck-placeholder, .ck .ck-placeholder {\n\tposition: relative;\n\n\t@media (forced-colors: active) {\n\t\t/*\n\t\t * This is needed for Edge on Windows to use the right color for the placeholder content (::before).\n\t\t * See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t */\n\t\tforced-color-adjust: preserve-parent-color;\n\t}\n\n\t&::before {\n\t\tposition: absolute;\n\t\tleft: 0;\n\t\tright: 0;\n\t\tcontent: attr(data-placeholder);\n\n\t\tcursor: text;\n\n\t\t/* See ckeditor/ckeditor5#469. */\n\t\tpointer-events: none;\n\n\t\t@media (forced-colors: none) {\n\t\t\tcolor: var(--ck-color-engine-placeholder-text);\n\t\t}\n\n\t\t@media (forced-colors: active) {\n\t\t\t/*\n\t\t\t * In the high contrast mode there is no telling between regular and placeholder text. Using\n\t\t\t * italic text to address that issue. See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t\t */\n\t\t\tfont-style: italic;\n\n\t\t\t/*\n\t\t\t * Without this margin, the caret will not show up and blink when the user puts the selection\n\t\t\t * in the placeholder (Edge on Windows). See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t\t */\n\t\t\tmargin-left: 1px;\n\t\t}\n\t}\n}\n\n/* See ckeditor/ckeditor5#1987. */\n.ck.ck-read-only .ck-placeholder {\n\t&::before {\n\t\tdisplay: none;\n\t}\n}\n/*\n * Rules for the `ck-placeholder` are loaded before the rules for `ck-reset_all` in the base CKEditor 5 DLL build.\n * This fix overwrites the incorrectly set `position: static` from `ck-reset_all`.\n * See https://github.com/ckeditor/ckeditor5/issues/11418.\n */\n.ck.ck-reset_all .ck-placeholder {\n\tposition: relative;\n}\n",".ck.ck-placeholder, .ck .ck-placeholder {\n  position: relative;\n}\n\n@media (forced-colors: active) {\n  .ck.ck-placeholder, .ck .ck-placeholder {\n    forced-color-adjust: preserve-parent-color;\n  }\n}\n\n:is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n  content: attr(data-placeholder);\n  cursor: text;\n  pointer-events: none;\n  position: absolute;\n  left: 0;\n  right: 0;\n}\n\n@media (forced-colors: none) {\n  :is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n    color: var(--ck-color-engine-placeholder-text);\n  }\n}\n\n@media (forced-colors: active) {\n  :is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n    margin-left: 1px;\n    font-style: italic;\n  }\n}\n\n.ck.ck-read-only .ck-placeholder:before {\n  display: none;\n}\n\n.ck.ck-reset_all .ck-placeholder {\n  position: relative;\n}\n\n.ck.ck-editor__editable span[data-ck-unsafe-element] {\n  display: none;\n}\n\n/*# sourceMappingURL=index.css.map */","/*\n * Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.\n * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options\n */\n\n/* Elements marked by the Renderer as hidden should be invisible in the editor. */\n.ck.ck-editor__editable span[data-ck-unsafe-element] {\n\tdisplay: none;\n}\n"]}
+{"version":3,"sources":["../theme/placeholder.css","index.css","../theme/renderer.css"],"names":[],"mappings":"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","file":"index.css.map","sourcesContent":["/*\n * Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.\n * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options\n */\n\n\n.ck.ck-placeholder, .ck .ck-placeholder {\n\tposition: relative;\n\n\t@media (forced-colors: active) {\n\t\t/*\n\t\t * This is needed for Edge on Windows to use the right color for the placeholder content (::before).\n\t\t * See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t */\n\t\tforced-color-adjust: preserve-parent-color;\n\t}\n\n\t&::before {\n\t\tposition: absolute;\n\t\tleft: 0;\n\t\tright: 0;\n\t\tcontent: attr(data-placeholder);\n\n\t\tcursor: text;\n\n\t\t/* See https://github.com/ckeditor/ckeditor5/issues/469. */\n\t\tpointer-events: none;\n\n\t\t/*\n\t\t * Inherit the content styles padding of the placeholder host.\n\t\t * This ensures the placeholder stays at the padding just like the native caret does, and not at the edge of editable.\n\t\t */\n\t\tpadding-left: inherit;\n\t\tpadding-right: inherit;\n\n\t\twhite-space: nowrap;\n\t\toverflow: hidden;\n\t\ttext-overflow: ellipsis;\n\n\t\t@media (forced-colors: none) {\n\t\t\tcolor: var(--ck-color-engine-placeholder-text);\n\t\t}\n\n\t\t@media (forced-colors: active) {\n\t\t\t/*\n\t\t\t * In the high contrast mode there is no telling between regular and placeholder text. Using\n\t\t\t * italic text to address that issue. See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t\t */\n\t\t\tfont-style: italic;\n\n\t\t\t/*\n\t\t\t * Without this margin, the caret will not show up and blink when the user puts the selection\n\t\t\t * in the placeholder (Edge on Windows). See https://github.com/ckeditor/ckeditor5/issues/14907.\n\t\t\t */\n\t\t\tmargin-left: 1px;\n\t\t}\n\t}\n}\n\n/* See https://github.com/ckeditor/ckeditor5/issues/1987. */\n.ck.ck-read-only .ck-placeholder {\n\t&::before {\n\t\tdisplay: none;\n\t}\n}\n/*\n * Rules for the `ck-placeholder` are loaded before the rules for `ck-reset_all` in the base CKEditor 5 DLL build.\n * This fix overwrites the incorrectly set `position: static` from `ck-reset_all`.\n * See https://github.com/ckeditor/ckeditor5/issues/11418.\n */\n.ck.ck-reset_all .ck-placeholder {\n\tposition: relative;\n}\n",".ck.ck-placeholder, .ck .ck-placeholder {\n  position: relative;\n}\n\n@media (forced-colors: active) {\n  .ck.ck-placeholder, .ck .ck-placeholder {\n    forced-color-adjust: preserve-parent-color;\n  }\n}\n\n:is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n  content: attr(data-placeholder);\n  cursor: text;\n  pointer-events: none;\n  padding-left: inherit;\n  padding-right: inherit;\n  white-space: nowrap;\n  text-overflow: ellipsis;\n  position: absolute;\n  left: 0;\n  right: 0;\n  overflow: hidden;\n}\n\n@media (forced-colors: none) {\n  :is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n    color: var(--ck-color-engine-placeholder-text);\n  }\n}\n\n@media (forced-colors: active) {\n  :is(.ck.ck-placeholder, .ck .ck-placeholder):before {\n    margin-left: 1px;\n    font-style: italic;\n  }\n}\n\n.ck.ck-read-only .ck-placeholder:before {\n  display: none;\n}\n\n.ck.ck-reset_all .ck-placeholder {\n  position: relative;\n}\n\n.ck.ck-editor__editable span[data-ck-unsafe-element] {\n  display: none;\n}\n\n/*# sourceMappingURL=index.css.map */","/*\n * Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.\n * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options\n */\n\n/* Elements marked by the Renderer as hidden should be invisible in the editor. */\n.ck.ck-editor__editable span[data-ck-unsafe-element] {\n\tdisplay: none;\n}\n"]}

package/dist/index.js

@@ -595,7 +595,7 @@ ViewNode.prototype.is = function(type) {
 // Proper overload would interfere with that.
 ViewText.prototype.is = function(type) {
     return type === '$text' || type === 'view:$text' || // This are legacy values kept for backward compatibility.
-    type === 'text' || type === 'view:text' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+    type === 'text' || type === 'view:text' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
     type === 'node' || type === 'view:node';
 };
 
@@ -3667,7 +3667,7 @@ ViewTextProxy.prototype.is = function(type) {
 // Proper overload would interfere with that.
 ViewElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'element' || type === 'view:element' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'element' || type === 'view:element' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'node' || type === 'view:node';
     } else {
         return name === this.name && (type === 'element' || type === 'view:element');
@@ -3758,10 +3758,10 @@ ViewElement.prototype.is = function(type, name) {
 // Proper overload would interfere with that.
 ViewContainerElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'containerElement' || type === 'view:containerElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'containerElement' || type === 'view:containerElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
-        return name === this.name && (type === 'containerElement' || type === 'view:containerElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return name === this.name && (type === 'containerElement' || type === 'view:containerElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element');
     }
 };
@@ -3774,7 +3774,8 @@ ViewContainerElement.prototype.is = function(type, name) {
         ...this.getChildren()
     ];
     let lastChild = children[this.childCount - 1];
-    // Block filler is required after a `<br>` if it's the last element in its container. See #1422.
+    // Block filler is required after a `<br>` if it's the last element in its container.
+    // See https://github.com/ckeditor/ckeditor5-engine/issues/1422.
     if (lastChild && lastChild.is('element', 'br')) {
         return this.childCount;
     }
@@ -3844,10 +3845,10 @@ ViewContainerElement.prototype.is = function(type, name) {
 // Proper overload would interfere with that.
 ViewEditableElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'editableElement' || type === 'view:editableElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'editableElement' || type === 'view:editableElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'containerElement' || type === 'view:containerElement' || type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
-        return name === this.name && (type === 'editableElement' || type === 'view:editableElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return name === this.name && (type === 'editableElement' || type === 'view:editableElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'containerElement' || type === 'view:containerElement' || type === 'element' || type === 'view:element');
     }
 };
@@ -3902,10 +3903,10 @@ const rootNameSymbol = Symbol('rootName');
 // Proper overload would interfere with that.
 ViewRootEditableElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'rootElement' || type === 'view:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'rootElement' || type === 'view:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'editableElement' || type === 'view:editableElement' || type === 'containerElement' || type === 'view:containerElement' || type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
-        return name === this.name && (type === 'rootElement' || type === 'view:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return name === this.name && (type === 'rootElement' || type === 'view:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'editableElement' || type === 'view:editableElement' || type === 'containerElement' || type === 'view:containerElement' || type === 'element' || type === 'view:element');
     }
 };
@@ -6303,10 +6304,10 @@ const DEFAULT_PRIORITY = 10;
 // Proper overload would interfere with that.
 ViewAttributeElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'attributeElement' || type === 'view:attributeElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'attributeElement' || type === 'view:attributeElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
-        return name === this.name && (type === 'attributeElement' || type === 'view:attributeElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return name === this.name && (type === 'attributeElement' || type === 'view:attributeElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element');
     }
 };
@@ -6394,7 +6395,7 @@ ViewAttributeElement.prototype.is = function(type, name) {
 // Proper overload would interfere with that.
 ViewEmptyElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'emptyElement' || type === 'view:emptyElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'emptyElement' || type === 'view:emptyElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
         return name === this.name && (type === 'emptyElement' || type === 'view:emptyElement' || type === 'element' || type === 'view:element');
@@ -6509,7 +6510,7 @@ ViewEmptyElement.prototype.is = function(type, name) {
 // Proper overload would interfere with that.
 ViewUIElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'uiElement' || type === 'view:uiElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'uiElement' || type === 'view:uiElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
         return name === this.name && (type === 'uiElement' || type === 'view:uiElement' || type === 'element' || type === 'view:element');
@@ -6665,7 +6666,7 @@ ViewUIElement.prototype.is = function(type, name) {
 // Proper overload would interfere with that.
 ViewRawElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'rawElement' || type === 'view:rawElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'rawElement' || type === 'view:rawElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === this.name || type === 'view:' + this.name || type === 'element' || type === 'view:element' || type === 'node' || type === 'view:node';
     } else {
         return name === this.name && (type === 'rawElement' || type === 'view:rawElement' || type === 'element' || type === 'view:element');
@@ -8749,7 +8750,8 @@ const validNodesToInsert = [
                     const insertIndex = counter.equal + counter.insert;
                     const deleteIndex = counter.equal + counter.delete;
                     const viewChild = viewElement.getChild(insertIndex);
-                    // UIElement and RawElement are special cases. Their children are not stored in a view (#799)
+                    // UIElement and RawElement are special cases. Their children are not stored in a view.
+                    // See https://github.com/ckeditor/ckeditor5/issues/799.
                     // so we cannot use them with replacing flow (since they use view children during rendering
                     // which will always result in rendering empty elements).
                     if (viewChild && !viewChild.is('uiElement') && !viewChild.is('rawElement')) {
@@ -8777,12 +8779,13 @@ const validNodesToInsert = [
         // Because we replace new view element mapping with the existing one, the corresponding DOM element
         // will not be rerendered. The new view element may have different attributes than the previous one.
         // Since its corresponding DOM element will not be rerendered, new attributes will not be added
-        // to the DOM, so we need to mark it here to make sure its attributes gets updated. See #1427 for more
-        // detailed case study.
+        // to the DOM, so we need to mark it here to make sure its attributes gets updated.
+        // See https://github.com/ckeditor/ckeditor5-engine/issues/1427 for more detailed case study.
         // Also there are cases where replaced element is removed from the view structure and then has
         // its attributes changed or removed. In such cases the element will not be present in `markedAttributes`
         // and also may be the same (`element.isSimilar()`) as the reused element not having its attributes updated.
-        // To prevent such situations we always mark reused element to have its attributes rerenderd (#1560).
+        // To prevent such situations we always mark reused element to have its attributes rerenderd.
+        // See https://github.com/ckeditor/ckeditor5-engine/issues/1560.
         this.markedAttributes.add(viewElement);
     }
     /**
@@ -9069,7 +9072,8 @@ const validNodesToInsert = [
                 this._updateTextNode(actualDomChildren[i], expectedDomChildren[i].data);
                 i++;
             } else if (action === 'equal') {
-                // Force updating text nodes inside elements which did not change and do not need to be re-rendered (#1125).
+                // Force updating text nodes inside elements which did not change and do not need to be re-rendered.
+                // See https://github.com/ckeditor/ckeditor5-engine/issues/1125.
                 // Do it here (not in the loop above) because only after insertions the `i` index is correct.
                 this._markDescendantTextToSync(this.domConverter.domToView(expectedDomChildren[i]));
                 i++;
@@ -9880,7 +9884,7 @@ const UNSAFE_ELEMENT_REPLACEMENT_ATTRIBUTE = 'data-ck-unsafe-element';
                 if (viewElementOrFragment.name === '$comment') {
                     domElement = this._domDocument.createComment(viewElementOrFragment.getCustomProperty('$rawContent'));
                 } else {
-                    // UIElement has its own render() method (see #799).
+                    // UIElement has its own render() method (see https://github.com/ckeditor/ckeditor5/issues/799).
                     domElement = viewElementOrFragment.render(this._domDocument, this);
                 }
                 if (options.bind) {
@@ -10764,7 +10768,8 @@ const UNSAFE_ELEMENT_REPLACEMENT_ATTRIBUTE = 'data-ck-unsafe-element';
                 // Change all consecutive whitespace characters (from the [ \n\t\r] set –
                 // see https://github.com/ckeditor/ckeditor5-engine/issues/822#issuecomment-311670249) to a single space character.
                 // That's how multiple whitespaces are treated when rendered, so we normalize those whitespaces.
-                // We're replacing 1+ (and not 2+) to also normalize singular \n\t\r characters (#822).
+                // We're replacing 1+ (and not 2+) to also normalize singular \n\t\r characters.
+                // See https://github.com/ckeditor/ckeditor5/issues/822.
                 data = node.data.replace(/[ \n\t\r]{1,}/g, ' ');
                 nodeEndsWithSpace = /[^\S\u00A0]/.test(data.charAt(data.length - 1));
                 const prevNode = i > 0 ? inlineNodes[i - 1] : null;
@@ -10786,7 +10791,8 @@ const UNSAFE_ELEMENT_REPLACEMENT_ATTRIBUTE = 'data-ck-unsafe-element';
                 // At the beginning and end of a block element, Firefox inserts normal space + <br> instead of non-breaking space.
                 // This means that the text node starts/end with normal space instead of non-breaking space.
                 // This causes a problem because the normal space would be removed in `.replace` calls above. To prevent that,
-                // the inline filler is removed only after the data is initially processed (by the `.replace` above). See ckeditor5#692.
+                // the inline filler is removed only after the data is initially processed (by the `.replace` above).
+                // See https://github.com/ckeditor/ckeditor5/issues/692.
                 data = getDataWithoutFiller(data);
                 // Block filler handling.
                 if (this.blockFillerMode != 'br' && node.parent) {
@@ -11619,7 +11625,8 @@ const UNSAFE_ELEMENT_REPLACEMENT_ATTRIBUTE = 'data-ck-unsafe-element';
                 });
             }
         }
-        // In case only non-relevant mutations were recorded it skips the event and force render (#5600).
+        // In case only non-relevant mutations were recorded it skips the event and force render.
+        // See https://github.com/ckeditor/ckeditor5/issues/5600.
         if (mutations.length) {
             // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
             // @if CK_DEBUG_TYPING // 	_debouncedLine();
@@ -12059,7 +12066,7 @@ function sameNodes(child1, child2) {
         if (this.selection.isEqual(newViewSelection) && this.domConverter.isDomSelectionCorrect(domSelection)) {
             return;
         }
-        // Ensure we are not in the infinite loop (#400).
+        // Ensure we are not in the infinite loop (https://github.com/ckeditor/ckeditor5-engine/issues/400).
         // This counter is reset each second. 60 selection changes in 1 second is enough high number
         // to be very difficult (impossible) to achieve using just keyboard keys (during normal editor use).
         if (++this._loopbackCounter > 60) {
@@ -13437,7 +13444,8 @@ ModelTextProxy.prototype.is = function(type) {
             };
         }
         // Get node just after the current position.
-        // Use a highly optimized version instead of checking the text node first and then getting the node after. See #6582.
+        // Use a highly optimized version instead of checking the text node first and then getting the node after.
+        // See https://github.com/ckeditor/ckeditor5/issues/6582.
         const textNodeAtPosition = getTextNodeAtPosition(position, parent);
         const node = textNodeAtPosition || getNodeAfterPosition(position, parent, textNodeAtPosition);
         if (node && node.is('model:element')) {
@@ -13506,7 +13514,8 @@ ModelTextProxy.prototype.is = function(type) {
             };
         }
         // Get node just before the current position.
-        // Use a highly optimized version instead of checking the text node first and then getting the node before. See #6582.
+        // Use a highly optimized version instead of checking the text node first and then getting the node before.
+        // See https://github.com/ckeditor/ckeditor5/issues/6582.
         const positionParent = position.parent;
         const textNodeAtPosition = getTextNodeAtPosition(position, positionParent);
         const node = textNodeAtPosition || getNodeBeforePosition(position, positionParent, textNodeAtPosition);
@@ -13733,14 +13742,16 @@ function formatReturnValue(type, item, previousPosition, nextPosition, length) {
     /**
 	 * Node directly after this position. Returns `null` if this position is at the end of its parent, or if it is in a text node.
 	 */ get nodeAfter() {
-        // Cache the parent and reuse for performance reasons. See #6579 and #6582.
+        // Cache the parent and reuse for performance reasons.
+        // See https://github.com/ckeditor/ckeditor5/issues/6579 and https://github.com/ckeditor/ckeditor5/issues/6582.
         const parent = this.parent;
         return getNodeAfterPosition(this, parent, getTextNodeAtPosition(this, parent));
     }
     /**
 	 * Node directly before this position. Returns `null` if this position is at the start of its parent, or if it is in a text node.
 	 */ get nodeBefore() {
-        // Cache the parent and reuse for performance reasons. See #6579 and #6582.
+        // Cache the parent and reuse for performance reasons.
+        // See https://github.com/ckeditor/ckeditor5/issues/6579 and https://github.com/ckeditor/ckeditor5/issues/6582.
         const parent = this.parent;
         return getNodeBeforePosition(this, parent, getTextNodeAtPosition(this, parent));
     }
@@ -18491,7 +18502,7 @@ ModelSelection.prototype.is = function(type) {
 // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
 // Proper overload would interfere with that.
 ModelLiveRange.prototype.is = function(type) {
-    return type === 'liveRange' || type === 'model:liveRange' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+    return type === 'liveRange' || type === 'model:liveRange' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
     type == 'range' || type === 'model:range';
 };
 /**
@@ -18630,7 +18641,7 @@ ModelLiveRange.prototype.is = function(type) {
 // Proper overload would interfere with that.
 ModelText.prototype.is = function(type) {
     return type === '$text' || type === 'model:$text' || // This are legacy values kept for backward compatibility.
-    type === 'text' || type === 'model:text' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+    type === 'text' || type === 'model:text' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
     type === 'node' || type === 'model:node';
 };
 
@@ -20084,7 +20095,7 @@ ModelDocumentSelection.prototype.is = function(type) {
 // Proper overload would interfere with that.
 ModelElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'element' || type === 'model:element' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'element' || type === 'model:element' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'node' || type === 'model:node';
     }
     return name === this.name && (type === 'element' || type === 'model:element');
@@ -21453,7 +21464,8 @@ function cloneNodes(nodes) {
         const viewElement = conversionApi.mapper.toViewElement(data.item);
         const viewWriter = conversionApi.writer;
         // If model item cannot be mapped to a view element, it means item is not an `Element` instance but a `ModelTextProxy` node.
-        // Only elements can have attributes in a view so do not proceed for anything else (#1587).
+        // Only elements can have attributes in a view so do not proceed for anything else.
+        // See https://github.com/ckeditor/ckeditor5-engine/issues/1587.
         if (!viewElement) {
             /**
 			 * This error occurs when a {@link module:engine/model/textproxy~ModelTextProxy text node's} attribute is to be downcasted
@@ -23255,7 +23267,7 @@ function getFromAttributeCreator(config) {
             continue;
         }
         // Mark the node as consumed even if the attribute will not be updated because it's in a valid context (schema)
-        // and would be converted if the attribute wouldn't be present. See #8921.
+        // and would be converted if the attribute wouldn't be present. See https://github.com/ckeditor/ckeditor5/issues/8921.
         result = true;
         // Do not override the attribute if it's already present.
         if (node.hasAttribute(modelAttribute.key)) {
@@ -25095,6 +25107,13 @@ function removeDisallowedAttributeFromNode(schema, node, writer) {
     /**
 	 * Starts the conversion process. The entry point for the conversion.
 	 *
+	 * **Note:** The default `context` value is `[ '$root' ]`, which only matches the generic root. When the editor uses
+	 * a custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+	 * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+	 * explicitly, otherwise the conversion result may be wrong.
+	 * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+	 * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+	 *
 	 * @fires element
 	 * @fires text
 	 * @fires documentFragment
@@ -25854,6 +25873,13 @@ function removeDisallowedAttributeFromNode(schema, node, writer) {
 	 * Returns the data parsed by the {@link #processor data processor} and then converted by upcast converters
 	 * attached to the {@link #upcastDispatcher}.
 	 *
+	 * **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a
+	 * custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+	 * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+	 * explicitly, otherwise the conversion result may be wrong.
+	 * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+	 * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+	 *
 	 * @see #set
 	 * @param data Data to parse.
 	 * @param context Base context in which the view will be converted to the model.
@@ -25873,6 +25899,13 @@ function removeDisallowedAttributeFromNode(schema, node, writer) {
 	 * When marker elements were converted during the conversion process, it will be set as a document fragment's
 	 * {@link module:engine/model/documentfragment~ModelDocumentFragment#markers static markers map}.
 	 *
+	 * **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a
+	 * custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+	 * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+	 * explicitly, otherwise the conversion result may be wrong.
+	 * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+	 * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+	 *
 	 * @fires toModel
 	 * @param viewElementOrFragment The element or document fragment whose content will be converted.
 	 * @param context Base context in which the view will be converted to the model.
@@ -26987,10 +27020,16 @@ function* _getUpcastDefinition(model, view, upcastAlso) {
 	 * @inheritDoc
 	 */ get affectedSelectable() {
         return [
-            ModelRange._createFromPositionAndShift(this.sourcePosition, this.howMany),
+            this.sourceRange,
             ModelRange._createFromPositionAndShift(this.targetPosition, 0)
         ];
     }
+    /**
+	 * Returns the range that is moved by this operation. This is equal to a range starting at {@link #sourcePosition} spanning over
+	 * {@link #howMany} nodes.
+	 */ get sourceRange() {
+        return ModelRange._createFromPositionAndShift(this.sourcePosition, this.howMany);
+    }
     /**
 	 * Creates and returns an operation that has the same parameters as this operation.
 	 */ clone() {
@@ -27058,7 +27097,7 @@ function* _getUpcastDefinition(model, view, upcastAlso) {
 	 * @inheritDoc
 	 * @internal
 	 */ _execute() {
-        _move(ModelRange._createFromPositionAndShift(this.sourcePosition, this.howMany), this.targetPosition);
+        _move(this.sourceRange, this.targetPosition);
     }
     /**
 	 * @inheritDoc
@@ -30518,7 +30557,7 @@ setTransformation(SplitOperation, SplitOperation, (a, b, context)=>{
 // The magic of type inference using `is` method is centralized in `TypeCheckable` class.
 // Proper overload would interfere with that.
 ModelLivePosition.prototype.is = function(type) {
-    return type === 'livePosition' || type === 'model:livePosition' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+    return type === 'livePosition' || type === 'model:livePosition' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
     type == 'position' || type === 'model:position';
 };
 /**
@@ -32117,10 +32156,10 @@ ModelLivePosition.prototype.is = function(type) {
 // Proper overload would interfere with that.
 ModelRootElement.prototype.is = function(type, name) {
     if (!name) {
-        return type === 'rootElement' || type === 'model:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+        return type === 'rootElement' || type === 'model:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
         type === 'element' || type === 'model:element' || type === 'node' || type === 'model:node';
     }
-    return name === this.name && (type === 'rootElement' || type === 'model:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+    return name === this.name && (type === 'rootElement' || type === 'model:rootElement' || // From super.is(). This is highly utilised method and cannot call super. See https://github.com/ckeditor/ckeditor5/issues/6529.
     type === 'element' || type === 'model:element');
 };
 
@@ -32285,6 +32324,12 @@ const graveyardName = '$graveyard';
 	 * **Note:** do not use this method after the editor has been initialized! If you want to dynamically add a root, use
 	 * {@link module:engine/model/writer~ModelWriter#addRoot `model.Writer#addRoot`} instead.
 	 *
+	 * **Note:** The default `elementName` value is `'$root'`. When the editor uses a custom root
+	 * {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the configured model element
+	 * name explicitly so the created root matches the schema the features expect.
+	 * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+	 * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+	 *
 	 * @param elementName The element name. Defaults to `'$root'` which also has some basic schema defined
 	 * (e.g. `$block` elements are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
 	 * @param rootName A unique root name.
@@ -34103,6 +34148,12 @@ ModelDocumentFragment.prototype.is = function(type) {
 	 *
 	 * Throws an error, if trying to add a root that is already added and attached.
 	 *
+	 * **Note:** The default `elementName` value is `'$root'`. When the editor uses a custom root
+	 * {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the configured model element
+	 * name explicitly so the added root matches the schema the features expect.
+	 * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+	 * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+	 *
 	 * @param rootName Name of the added root.
 	 * @param elementName The element name. Defaults to `'$root'` which also has some basic schema defined
 	 * (e.g. `$block` elements are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
@@ -40229,6 +40280,13 @@ _setModelData._parse = _parseModel;
  * <$text attribute="value">Text data</$text>
  * ```
  *
+ * **Note:** The default `options.context` value is `'$root'`, which only matches the generic root. When the editor
+ * uses a custom root {@link module:core/editor/editorconfig~RootConfig#modelElement `modelElement`}, pass the target
+ * {@link module:engine/model/rootelement~ModelRootElement root element} (or its configured model element name)
+ * explicitly, otherwise the conversion result may be wrong.
+ * See the {@glink framework/deep-dive/schema#custom-root-elements Custom root elements} section of the
+ * {@glink framework/deep-dive/schema Schema deep-dive} guide for more details.
+ *
  * @param data HTML-like string to be parsed.
  * @param schema A schema instance used by converters for element validation.
  * @param options Additional configuration.