@wordpress/core-data 7.40.2-next.v.202602241322.0 → 7.40.2

package/build-types/utils/crdt-blocks.d.ts

@@ -15,7 +15,7 @@ export interface Block {
     originalContent?: string;
     validationIssues?: string[];
 }
-interface YBlockRecord extends YMapRecord {
+export interface YBlockRecord extends YMapRecord {
     attributes: YBlockAttributes;
     clientId: string;
     innerBlocks: YBlocks;
@@ -26,6 +26,17 @@ interface YBlockRecord extends YMapRecord {
 export type YBlock = YMapWrap<YBlockRecord>;
 export type YBlocks = Y.Array<YBlock>;
 export type YBlockAttributes = Y.Map<Y.Text | unknown>;
+/**
+ * Convert blocks from their CRDT-serialized form back to the runtime form
+ * expected by the block editor. Rich-text attributes are stored as Y.Text in
+ * the CRDT document, which serializes to plain strings via toJSON(). This
+ * function restores them to RichTextData instances so that block edit
+ * components that rely on RichTextData methods (e.g. `.text`) work correctly.
+ *
+ * @param blocks Blocks as extracted from the CRDT document via toJSON().
+ * @return Blocks with rich-text attributes restored to RichTextData.
+ */
+export declare function deserializeBlockAttributes(blocks: Block[]): Block[];
 /**
  * Merge incoming block data into the local Y.Doc.
  * This function is called to sync local block changes to a shared Y.Doc.

package/build-types/utils/crdt-blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt-blocks.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-blocks.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEpC;;GAEG;AACH,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG1E,UAAU,eAAe;IACxB,CAAE,GAAG,EAAE,MAAM,GAAI,OAAO,CAAC;CACzB;AAQD,MAAM,WAAW,KAAK;IACrB,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,KAAK,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAGD,UAAU,YAAa,SAAQ,UAAU;IACxC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAE,YAAY,CAAE,CAAC;AAC9C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAE,MAAM,CAAE,CAAC;AAIxC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,GAAG,CAAE,CAAC,CAAC,IAAI,GAAG,OAAO,CAAE,CAAC;AAiIzD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,KAAK,EAAE,EACvB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC3B,IAAI,CAwMN;AAuED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,CAAC,CAAC,IAAI,EAClB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,MAAM,GAAG,IAAW,GAClC,IAAI,CA4BN"}
+{"version":3,"file":"crdt-blocks.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-blocks.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEpC;;GAEG;AACH,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAI1E,UAAU,eAAe;IACxB,CAAE,GAAG,EAAE,MAAM,GAAI,OAAO,CAAC;CACzB;AAcD,MAAM,WAAW,KAAK;IACrB,UAAU,EAAE,eAAe,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,KAAK,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAGD,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC/C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAE,YAAY,CAAE,CAAC;AAC9C,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAE,MAAM,CAAE,CAAC;AAIxC,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,GAAG,CAAE,CAAC,CAAC,IAAI,GAAG,OAAO,CAAE,CAAC;AA2GzD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAE,MAAM,EAAE,KAAK,EAAE,GAAI,KAAK,EAAE,CAwBrE;AAsGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,KAAK,EAAE,EACvB,cAAc,EAAE,MAAM,GAAG,IAAI,GAC3B,IAAI,CAqLN;AA0ID;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,CAAC,CAAC,IAAI,EAClB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,MAAM,GAAG,IAAW,GAClC,IAAI,CA4BN"}

package/build-types/utils/crdt-selection.d.ts

@@ -13,4 +13,14 @@ export declare function updateSelectionHistory(ydoc: CRDTDoc, wpSelection: WPSel
  * @param ydoc             The Y.Doc where blocks are stored
  */
 export declare function restoreSelection(selectionHistory: YFullSelection[], ydoc: Y.Doc): void;
+/**
+ * If the latest selection has been shifted by remote edits, resolve and return
+ * it as a WPSelection. Returns null when the history is empty or neither
+ * endpoint has moved.
+ *
+ * @param ydoc             The Y.Doc to resolve positions against
+ * @param selectionHistory The selection history to check
+ * @return The shifted WPSelection, or null if nothing moved.
+ */
+export declare function getShiftedSelection(ydoc: Y.Doc, selectionHistory: YFullSelection[]): WPSelection | null;
 //# sourceMappingURL=crdt-selection.d.ts.map

package/build-types/utils/crdt-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt-selection.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-selection.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAIN,KAAK,cAAc,EAEnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,UAAU,CAAC;AAsB9D,wBAAgB,mBAAmB,CAAE,IAAI,EAAE,OAAO,GAAI,cAAc,EAAE,CAErE;AAED,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,GACtB,IAAI,CAEN;AAkFD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,cAAc,EAAE,EAClC,IAAI,EAAE,CAAC,CAAC,GAAG,GACT,IAAI,CA+DN"}
+{"version":3,"file":"crdt-selection.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-selection.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAElD;;GAEG;AACH,OAAO,EAIN,KAAK,cAAc,EAEnB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,UAAU,CAAC;AAsB9D,wBAAgB,mBAAmB,CAAE,IAAI,EAAE,OAAO,GAAI,cAAc,EAAE,CAErE;AAED,wBAAgB,sBAAsB,CACrC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,WAAW,GACtB,IAAI,CAEN;AAoGD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC/B,gBAAgB,EAAE,cAAc,EAAE,EAClC,IAAI,EAAE,CAAC,CAAC,GAAG,GACT,IAAI,CA+DN;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,CAAC,CAAC,GAAG,EACX,gBAAgB,EAAE,cAAc,EAAE,GAChC,WAAW,GAAG,IAAI,CA+BpB"}

package/build-types/utils/crdt-text.d.ts

@@ -0,0 +1,16 @@
+/**
+ * WordPress dependencies
+ */
+import { RichTextData } from '@wordpress/rich-text';
+/**
+ * Returns a function that converts HTML strings to RichTextData instances,
+ * using a FIFO cache bounded by `maxSize` to avoid re-parsing identical
+ * strings. Repeated calls with the same string return the cached instance
+ * without re-running the HTML parser and DOM traversal.
+ *
+ * @param maxSize Maximum number of entries to hold in the cache.
+ * @return A cached version of RichTextData.fromHTMLString.
+ */
+export declare function createRichTextDataCache(maxSize: number): (value: string) => RichTextData;
+export declare const getCachedRichTextData: (value: string) => RichTextData;
+//# sourceMappingURL=crdt-text.d.ts.map

package/build-types/utils/crdt-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-text.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-text.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAIpD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,MAAM,GACb,CAAE,KAAK,EAAE,MAAM,KAAM,YAAY,CAoBnC;AAED,eAAO,MAAM,qBAAqB,UAtBtB,MAAM,KAAM,YAwBvB,CAAC"}

package/build-types/utils/crdt-user-selections.d.ts

@@ -10,6 +10,15 @@ export declare enum SelectionType {
     SelectionInMultipleBlocks = "selection-in-multiple-blocks",
     WholeBlock = "whole-block"
 }
+/**
+ * The direction of a text selection, indicating where the caret sits.
+ */
+export declare enum SelectionDirection {
+    /** The caret is at the end of the selection (default / left-to-right). */
+    Forward = "f",
+    /** The caret is at the start of the selection (right-to-left). */
+    Backward = "b"
+}
 /**
  * Converts WordPress block editor selection to a SelectionState.
  *
@@ -18,12 +27,16 @@ export declare enum SelectionType {
  * differ between the block-editor store and the Yjs document (e.g. in "Show
  * Template" mode).
  *
- * @param selectionStart - The start position of the selection
- * @param selectionEnd   - The end position of the selection
- * @param yDoc           - The Yjs document
+ * @param selectionStart             - The start position of the selection
+ * @param selectionEnd               - The end position of the selection
+ * @param yDoc                       - The Yjs document
+ * @param options                    - Optional parameters
+ * @param options.selectionDirection - The direction of the selection (forward or backward)
  * @return The SelectionState
  */
-export declare function getSelectionState(selectionStart: WPBlockSelection, selectionEnd: WPBlockSelection, yDoc: Y.Doc): SelectionState;
+export declare function getSelectionState(selectionStart: WPBlockSelection, selectionEnd: WPBlockSelection, yDoc: Y.Doc, options?: {
+    selectionDirection?: SelectionDirection;
+}): SelectionState;
 /**
  * Resolves a local block-editor clientId to its index path relative to the
  * post content blocks. This allows finding the corresponding block in the Yjs

package/build-types/utils/crdt-user-selections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt-user-selections.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-user-selections.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAWpC,OAAO,KAAK,EACX,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EAOd,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,oBAAY,aAAa;IACxB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,mBAAmB,2BAA2B;IAC9C,yBAAyB,iCAAiC;IAC1D,UAAU,gBAAgB;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAChC,cAAc,EAAE,gBAAgB,EAChC,YAAY,EAAE,gBAAgB,EAC9B,IAAI,EAAE,CAAC,CAAC,GAAG,GACT,cAAc,CAqFhB;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC3C,QAAQ,EAAE,MAAM,GACd,sBAAsB,GAAG,IAAI,CAyB/B;AA4DD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,cAAc,EAC1B,UAAU,EAAE,cAAc,GACxB,OAAO,CAiDT"}
+{"version":3,"file":"crdt-user-selections.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-user-selections.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAWpC,OAAO,KAAK,EACX,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EAOd,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,oBAAY,aAAa;IACxB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,mBAAmB,2BAA2B;IAC9C,yBAAyB,iCAAiC;IAC1D,UAAU,gBAAgB;CAC1B;AAED;;GAEG;AACH,oBAAY,kBAAkB;IAC7B,0EAA0E;IAC1E,OAAO,MAAM;IACb,kEAAkE;IAClE,QAAQ,MAAM;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAChC,cAAc,EAAE,gBAAgB,EAChC,YAAY,EAAE,gBAAgB,EAC9B,IAAI,EAAE,CAAC,CAAC,GAAG,EACX,OAAO,CAAC,EAAE;IAAE,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;CAAE,GACnD,cAAc,CAwFhB;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC3C,QAAQ,EAAE,MAAM,GACd,sBAAsB,GAAG,IAAI,CAyB/B;AA4DD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,cAAc,EAC1B,UAAU,EAAE,cAAc,GACxB,OAAO,CAsDT"}

package/build-types/utils/crdt-utils.d.ts

@@ -62,4 +62,24 @@ export declare function isYMap<T extends YMapRecord>(value: YMapWrap<T> | undefi
  * @return The block, or null if the block is not found
  */
 export declare function findBlockByClientIdInDoc(blockId: string, ydoc: Y.Doc): YBlock | null;
+/**
+ * Convert an HTML character index (counting tag characters) to a rich-text
+ * offset (counting only text characters). Used on read paths where Y.Text
+ * resolves to an HTML index but the block editor expects a text offset.
+ *
+ * @param html      The full HTML string from Y.Text.
+ * @param htmlIndex The HTML character index.
+ * @return The corresponding rich-text offset.
+ */
+export declare function htmlIndexToRichTextOffset(html: string, htmlIndex: number): number;
+/**
+ * Convert a rich-text offset (counting only text characters) to an HTML
+ * character index (counting tag characters). Used on write paths where the
+ * block editor provides a text offset but Y.Text expects an HTML index.
+ *
+ * @param html           The full HTML string from Y.Text.
+ * @param richTextOffset The rich-text text offset.
+ * @return The corresponding HTML character index.
+ */
+export declare function richTextOffsetToHtmlIndex(html: string, richTextOffset: number): number;
 //# sourceMappingURL=crdt-utils.d.ts.map

package/build-types/utils/crdt-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt-utils.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAEpC;;GAEG;AACH,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,eAAe,CAAC;AAIrD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ,CAAE,CAAC,SAAS,UAAU,CAAG,SAAQ,CAAC,CAAC,YAAY,CAAE,CAAC,CAAE;IAC5E,MAAM,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,IAAI,CAAC;IAChD,OAAO,EAAE,CACR,QAAQ,EAAE,CACT,KAAK,EAAE,CAAC,CAAE,MAAM,CAAC,CAAE,EACnB,GAAG,EAAE,MAAM,CAAC,EACZ,GAAG,EAAE,QAAQ,CAAE,CAAC,CAAE,KACd,IAAI,KACL,IAAI,CAAC;IACV,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,OAAO,CAAC;IAChD,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,CAAC,CAAE,CAAC,CAAE,GAAG,SAAS,CAAC;IAC3D,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAE,CAAC,CAAE,KAAM,IAAI,CAAC;IAC5D,MAAM,EAAE,MAAM,CAAC,CAAC;CAEhB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAE,CAAC,SAAS,UAAU,EAC/C,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,GAAG,EAAE,MAAM,GACT,QAAQ,CAAE,CAAC,CAAE,CAEf;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,CAAC,SAAS,UAAU,EAC/C,OAAO,GAAE,OAAO,CAAE,CAAC,CAAO,GACxB,QAAQ,CAAE,CAAC,CAAE,CAEf;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAE,CAAC,SAAS,UAAU,EAC3C,KAAK,EAAE,QAAQ,CAAE,CAAC,CAAE,GAAG,SAAS,GAC9B,KAAK,IAAI,QAAQ,CAAE,CAAC,CAAE,CAExB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,CAAC,GAAG,GACT,MAAM,GAAG,IAAI,CASf"}
+{"version":3,"file":"crdt-utils.d.ts","sourceRoot":"","sources":["../../src/utils/crdt-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,iBAAiB,CAAC;AAGpC;;GAEG;AACH,OAAO,KAAK,EAAE,MAAM,EAAW,MAAM,eAAe,CAAC;AAIrD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAE,MAAM,EAAE,OAAO,CAAE,CAAC;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ,CAAE,CAAC,SAAS,UAAU,CAAG,SAAQ,CAAC,CAAC,YAAY,CAAE,CAAC,CAAE;IAC5E,MAAM,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,IAAI,CAAC;IAChD,OAAO,EAAE,CACR,QAAQ,EAAE,CACT,KAAK,EAAE,CAAC,CAAE,MAAM,CAAC,CAAE,EACnB,GAAG,EAAE,MAAM,CAAC,EACZ,GAAG,EAAE,QAAQ,CAAE,CAAC,CAAE,KACd,IAAI,KACL,IAAI,CAAC;IACV,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,OAAO,CAAC;IAChD,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,KAAM,CAAC,CAAE,CAAC,CAAE,GAAG,SAAS,CAAC;IAC3D,GAAG,EAAE,CAAE,CAAC,SAAS,MAAM,CAAC,EAAI,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAE,CAAC,CAAE,KAAM,IAAI,CAAC;IAC5D,MAAM,EAAE,MAAM,CAAC,CAAC;CAEhB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAE,CAAC,SAAS,UAAU,EAC/C,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,GAAG,EAAE,MAAM,GACT,QAAQ,CAAE,CAAC,CAAE,CAEf;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAE,CAAC,SAAS,UAAU,EAC/C,OAAO,GAAE,OAAO,CAAE,CAAC,CAAO,GACxB,QAAQ,CAAE,CAAC,CAAE,CAEf;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAE,CAAC,SAAS,UAAU,EAC3C,KAAK,EAAE,QAAQ,CAAE,CAAC,CAAE,GAAG,SAAS,GAC9B,KAAK,IAAI,QAAQ,CAAE,CAAC,CAAE,CAExB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,CAAC,GAAG,GACT,MAAM,GAAG,IAAI,CASf;AA2BD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GACf,MAAM,CAiBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACpB,MAAM,CA4BR"}

package/build-types/utils/crdt.d.ts

@@ -1,7 +1,6 @@
 import { type CRDTDoc, type SyncConfig, Y } from '@wordpress/sync';
 import { type Block, type YBlocks } from './crdt-blocks';
 import { type Post } from '../entity-types/post';
-import { type Type } from '../entity-types';
 import type { WPSelection } from '../types';
 import { type YMapRecord, type YMapWrap } from './crdt-utils';
 export type PostChanges = Partial<Post> & {
@@ -30,30 +29,38 @@ export interface YPostRecord extends YMapRecord {
     template: string;
     title: Y.Text;
 }
+export declare const POST_META_KEY_FOR_CRDT_DOC_PERSISTENCE = "_crdt_document";
 /**
  * Given a set of local changes to a post record, apply those changes to the
  * local Y.Doc.
  *
  * @param {CRDTDoc}     ydoc
  * @param {PostChanges} changes
- * @param {Type}        _postType
+ * @param {Set<string>} syncedProperties
  * @return {void}
  */
-export declare function applyPostChangesToCRDTDoc(ydoc: CRDTDoc, changes: PostChanges, _postType: Type): void;
+export declare function applyPostChangesToCRDTDoc(ydoc: CRDTDoc, changes: PostChanges, syncedProperties: Set<string>): void;
 /**
  * Given a local Y.Doc that *may* contain changes from remote peers, compare
  * against the local record and determine if there are changes (edits) we want
  * to dispatch.
  *
- * @param {CRDTDoc} ydoc
- * @param {Post}    editedRecord
- * @param {Type}    _postType
+ * @param {CRDTDoc}     ydoc
+ * @param {Post}        editedRecord
+ * @param {Set<string>} syncedProperties
  * @return {Partial<PostChanges>} The changes that should be applied to the local record.
  */
-export declare function getPostChangesFromCRDTDoc(ydoc: CRDTDoc, editedRecord: Post, _postType: Type): PostChanges;
+export declare function getPostChangesFromCRDTDoc(ydoc: CRDTDoc, editedRecord: Post, syncedProperties: Set<string>): PostChanges;
 /**
  * This default sync config can be used for entities that are flat maps of
  * primitive values and do not require custom logic to merge changes.
  */
 export declare const defaultSyncConfig: SyncConfig;
+/**
+ * This default collection sync config can be used to sync entity collections
+ * (e.g., block comments) where we are not interested in merging changes at the
+ * individual record level, but instead want to replace the entire collection
+ * when changes are detected.
+ */
+export declare const defaultCollectionSyncConfig: SyncConfig;
 //# sourceMappingURL=crdt.d.ts.map

package/build-types/utils/crdt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/utils/crdt.ts"],"names":[],"mappings":"AAUA,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,UAAU,EACf,CAAC,EACD,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAGN,KAAK,KAAK,EAEV,KAAK,OAAO,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAM5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,WAAW,GAAG,OAAO,CAAE,IAAI,CAAE,GAAG;IAC3C,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,CAAE,SAAS,CAAE,GAAG,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,IAAI,CAAE,SAAS,CAAE,GAAG,MAAM,CAAC;IACrC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,KAAK,CAAC,EAAE,IAAI,CAAE,OAAO,CAAE,GAAG,MAAM,CAAC;CACjC,CAAC;AAGF,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC9C,MAAM,EAAE,MAAM,CAAC;IAEf,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAE,UAAU,CAAE,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC;CACd;AA2DD;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,IAAI,GACb,IAAI,CAoIN;AAMD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,IAAI,EAClB,SAAS,EAAE,IAAI,GACb,WAAW,CAyHb;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAI/B,CAAC"}
+{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/utils/crdt.ts"],"names":[],"mappings":"AAUA,OAAO,EACN,KAAK,OAAO,EAIZ,KAAK,UAAU,EACf,CAAC,EACD,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAIN,KAAK,KAAK,EAEV,KAAK,OAAO,EACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAM5C,OAAO,EAIN,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,MAAM,cAAc,CAAC;AAGtB,MAAM,MAAM,WAAW,GAAG,OAAO,CAAE,IAAI,CAAE,GAAG;IAC3C,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,IAAI,CAAE,SAAS,CAAE,GAAG,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,IAAI,CAAE,SAAS,CAAE,GAAG,MAAM,CAAC;IACrC,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,KAAK,CAAC,EAAE,IAAI,CAAE,OAAO,CAAE,GAAG,MAAM,CAAC;CACjC,CAAC;AAGF,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC9C,MAAM,EAAE,MAAM,CAAC;IAEf,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAE,UAAU,CAAE,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC;CACd;AAED,eAAO,MAAM,sCAAsC,mBAAmB,CAAC;AAsCvE;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,WAAW,EACpB,gBAAgB,EAAE,GAAG,CAAE,MAAM,CAAE,GAC7B,IAAI,CAoIN;AAMD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,IAAI,EAClB,gBAAgB,EAAE,GAAG,CAAE,MAAM,CAAE,GAC7B,WAAW,CAuJb;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAI/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,UAKzC,CAAC"}

package/build-types/utils/normalize-query-for-resolution.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Returns a copy of `query` filtered to only the keys that affect resolution
+ * identity (`context` and `_fields`), or `undefined` when none are present.
+ * This mirrors the normalisation that the data store applies when keying
+ * resolved records, so that `finishResolutions` receives args that match the
+ * keys used by callers who omit pagination params.
+ *
+ * @param {Object} query The raw query object.
+ * @return {Object|undefined} Normalised query or undefined.
+ */
+export default function normalizeQueryForResolution(query: any): any | undefined;
+//# sourceMappingURL=normalize-query-for-resolution.d.ts.map

package/build-types/utils/normalize-query-for-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-query-for-resolution.d.ts","sourceRoot":"","sources":["../../src/utils/normalize-query-for-resolution.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,2BAA2B,CAAE,KAAK,KAAA,GAF9C,MAAO,SAAS,CAc3B"}

package/build-types/utils/save-crdt-doc.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Persist the current CRDT document through the sync /save endpoint.
+ *
+ * @param {import('@wordpress/sync').ObjectType} objectType Object type.
+ * @param {import('@wordpress/sync').ObjectID}   objectId   Object ID.
+ */
+export declare function saveCRDTDoc(objectType: import('@wordpress/sync').ObjectType, objectId: import('@wordpress/sync').ObjectID): Promise<void>;
+//# sourceMappingURL=save-crdt-doc.d.ts.map

package/build-types/utils/save-crdt-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-crdt-doc.d.ts","sourceRoot":"","sources":["../../src/utils/save-crdt-doc.js"],"names":[],"mappings":"AAiCA;;;;;GAKG;AACH,wBAAsB,WAAW,CAAE,UAAU,EAHlC,OAAO,iBAAiB,EAAE,UAGQ,EAAE,QAAQ,EAF5C,OAAO,iBAAiB,EAAE,QAEkB,iBAwBtD"}

package/build-types/utils/test/crdt-utils.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crdt-utils.d.ts.map

package/build-types/utils/test/crdt-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt-utils.d.ts","sourceRoot":"","sources":["../../../src/utils/test/crdt-utils.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/core-data",
-	"version": "7.40.2-next.v.202602241322.0+bce7cff88",
+	"version": "7.40.2",
 	"description": "Access to and manipulation of core WordPress entities.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -49,22 +49,22 @@
 		"build-module/index.mjs"
 	],
 	"dependencies": {
-		"@wordpress/api-fetch": "^7.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/block-editor": "^15.13.2-next.v.202602241322.0+bce7cff88",
-		"@wordpress/blocks": "^15.13.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/compose": "^7.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/data": "^10.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/deprecated": "^4.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/element": "^6.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/html-entities": "^4.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/i18n": "^6.13.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/is-shallow-equal": "^5.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/private-apis": "^1.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/rich-text": "^7.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/sync": "^1.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/undo-manager": "^1.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/url": "^4.40.1-next.v.202602241322.0+bce7cff88",
-		"@wordpress/warning": "^3.40.1-next.v.202602241322.0+bce7cff88",
+		"@wordpress/api-fetch": "^7.40.1",
+		"@wordpress/block-editor": "^15.13.2",
+		"@wordpress/blocks": "^15.13.1",
+		"@wordpress/compose": "^7.40.1",
+		"@wordpress/data": "^10.40.1",
+		"@wordpress/deprecated": "^4.40.1",
+		"@wordpress/element": "^6.40.1",
+		"@wordpress/html-entities": "^4.40.1",
+		"@wordpress/i18n": "^6.13.1",
+		"@wordpress/is-shallow-equal": "^5.40.1",
+		"@wordpress/private-apis": "^1.40.1",
+		"@wordpress/rich-text": "^7.40.1",
+		"@wordpress/sync": "^1.40.1",
+		"@wordpress/undo-manager": "^1.40.1",
+		"@wordpress/url": "^4.40.1",
+		"@wordpress/warning": "^3.40.1",
 		"change-case": "^4.1.2",
 		"equivalent-key-map": "^0.2.2",
 		"fast-deep-equal": "^3.1.3",
@@ -84,5 +84,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "943dde7f0b600ce238726c36284bc9f70ce0ffa4"
+	"gitHead": "adb6623c9f32490cfc73c7ac7f122578c1f10c65"
 }

package/src/actions.js

@@ -19,9 +19,17 @@ import { receiveItems, removeItems, receiveQueriedItems } from './queried-data';
 import { DEFAULT_ENTITY_KEY } from './entities';
 import { createBatch } from './batch';
 import { STORE_NAME } from './name';
-import { LOCAL_EDITOR_ORIGIN, getSyncManager } from './sync';
+import {
+	LOCAL_EDITOR_ORIGIN,
+	LOCAL_UNDO_IGNORED_ORIGIN,
+	getSyncManager,
+} from './sync';
 import logEntityDeprecation from './utils/log-entity-deprecation';
 
+function addTitleToAutoDraft( record ) {
+	return record.status === 'auto-draft' ? { ...record, title: '' } : record;
+}
+
 /**
  * Returns an action object used in signalling that authors have been received.
  * Ignored from documentation as it's internal to the data store.
@@ -96,12 +104,9 @@ export function receiveEntityRecords(
 	// Auto drafts should not have titles, but some plugins rely on them so we can't filter this
 	// on the server.
 	if ( kind === 'postType' ) {
-		records = ( Array.isArray( records ) ? records : [ records ] ).map(
-			( record ) =>
-				record.status === 'auto-draft'
-					? { ...record, title: '' }
-					: record
-		);
+		records = Array.isArray( records )
+			? records.map( addTitleToAutoDraft )
+			: addTitleToAutoDraft( records );
 	}
 	let action;
 	if ( query ) {
@@ -445,11 +450,18 @@ export const editEntityRecord =
 				? false
 				: ! options.isCached;
 
+			// Use an untracked origin for undoIgnore changes so the Yjs
+			// UndoManager does not capture them as undo levels, while
+			// still syncing them to the CRDT document and other peers.
+			const origin = options.undoIgnore
+				? LOCAL_UNDO_IGNORED_ORIGIN
+				: LOCAL_EDITOR_ORIGIN;
+
 			getSyncManager()?.update(
 				objectType,
 				objectId,
 				editsWithMerges,
-				LOCAL_EDITOR_ORIGIN,
+				origin,
 				{ isNewUndoLevel }
 			);
 		}
@@ -773,10 +785,10 @@ export const saveEntityRecord =
 					if ( entityConfig.__unstablePrePersist ) {
 						edits = {
 							...edits,
-							...entityConfig.__unstablePrePersist(
+							...( await entityConfig.__unstablePrePersist(
 								persistedRecord,
 								edits
-							),
+							) ),
 						};
 					}
 					updatedRecord = await __unstableFetch( {
@@ -793,11 +805,13 @@ export const saveEntityRecord =
 						edits
 					);
 					if ( entityConfig.syncConfig ) {
+						// Use an untracked origin so that the save
+						// response does not create undo levels.
 						getSyncManager()?.update(
 							`${ kind }/${ name }`,
 							recordId,
 							updatedRecord,
-							LOCAL_EDITOR_ORIGIN,
+							LOCAL_UNDO_IGNORED_ORIGIN,
 							{ isSave: true }
 						);
 					}
@@ -1108,7 +1122,7 @@ export const receiveRevisions =
 		dispatch( {
 			type: 'RECEIVE_ITEM_REVISIONS',
 			key,
-			items: Array.isArray( records ) ? records : [ records ],
+			items: records,
 			recordKey,
 			meta,
 			query,
@@ -1117,32 +1131,3 @@ export const receiveRevisions =
 			invalidateCache,
 		} );
 	};
-
-/**
- * Returns an action object used to set the sync connection status for an entity or collection.
- *
- * @param {string}             kind   Kind of the entity.
- * @param {string}             name   Name of the entity.
- * @param {number|string|null} key    The entity key, or null for collections.
- * @param {Object|null}        status The connection state object or null on unload.
- *
- * @return {Object} Action object.
- */
-export function setSyncConnectionStatus( kind, name, key, status ) {
-	if ( ! status ) {
-		return {
-			type: 'CLEAR_SYNC_CONNECTION_STATUS',
-			kind,
-			name,
-			key,
-		};
-	}
-
-	return {
-		type: 'SET_SYNC_CONNECTION_STATUS',
-		kind,
-		name,
-		key,
-		status,
-	};
-}

package/src/awareness/post-editor-awareness.ts

@@ -16,10 +16,12 @@ import {
 	LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS,
 } from './config';
 import { STORE_NAME as coreStore } from '../name';
+import { htmlIndexToRichTextOffset } from '../utils/crdt-utils';
 import {
 	areSelectionsStatesEqual,
 	getSelectionState,
 	SelectionType,
+	SelectionDirection,
 } from '../utils/crdt-user-selections';
 
 import type { SelectionState, WPBlockSelection } from '../types';
@@ -69,6 +71,18 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 		let selectionEnd = getSelectionEnd();
 		let localCursorTimeout: NodeJS.Timeout | null = null;
 
+		// During rapid selection changes (e.g. undo restoring content and
+		// selection), the debounce discards intermediate events. If we use the
+		// last intermediate state instead of the overall change it can produce
+		// the wrong direction.
+		// Use selectionBeforeDebounce to capture the selection state from
+		// before the debounce window so that direction is computed across the
+		// full window when it fires.
+		let selectionBeforeDebounce: {
+			start: WPBlockSelection;
+			end: WPBlockSelection;
+		} | null = null;
+
 		subscribe( () => {
 			const newSelectionStart = getSelectionStart();
 			const newSelectionEnd = getSelectionEnd();
@@ -80,6 +94,15 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 				return;
 			}
 
+			// On the first change of a debounce window, snapshot the state
+			// we're moving away from.
+			if ( ! selectionBeforeDebounce ) {
+				selectionBeforeDebounce = {
+					start: selectionStart,
+					end: selectionEnd,
+				};
+			}
+
 			selectionStart = newSelectionStart;
 			selectionEnd = newSelectionEnd;
 
@@ -103,10 +126,29 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 			}
 
 			localCursorTimeout = setTimeout( () => {
+				// Compute direction across the full debounce window.
+				const selectionStateOptions: {
+					selectionDirection?: SelectionDirection;
+				} = {};
+
+				if ( selectionBeforeDebounce ) {
+					selectionStateOptions.selectionDirection =
+						detectSelectionDirection(
+							selectionBeforeDebounce.start,
+							selectionBeforeDebounce.end,
+							selectionStart,
+							selectionEnd
+						);
+
+					// Reset debounced selection state.
+					selectionBeforeDebounce = null;
+				}
+
 				const selectionState = getSelectionState(
 					selectionStart,
 					selectionEnd,
-					this.doc
+					this.doc,
+					selectionStateOptions
 				);
 
 				this.setThrottledLocalStateField(
@@ -171,6 +213,10 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 			return state1 === state2;
 		}
 
+		if ( ! state1.selection || ! state2.selection ) {
+			return state1.selection === state2.selection;
+		}
+
 		return areSelectionsStatesEqual( state1.selection, state2.selection );
 	}
 
@@ -188,14 +234,14 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 	 * clientIds (e.g. in "Show Template" mode where blocks are cloned).
 	 *
 	 * @param selection - The selection state.
-	 * @return The text index and block client ID, or nulls if not resolvable.
+	 * @return The rich-text offset and block client ID, or nulls if not resolvable.
 	 */
 	public convertSelectionStateToAbsolute( selection: SelectionState ): {
-		textIndex: number | null;
+		richTextOffset: number | null;
 		localClientId: string | null;
 	} {
 		if ( selection.type === SelectionType.None ) {
-			return { textIndex: null, localClientId: null };
+			return { richTextOffset: null, localClientId: null };
 		}
 
 		if ( selection.type === SelectionType.WholeBlock ) {
@@ -218,7 +264,7 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 				}
 			}
 
-			return { textIndex: null, localClientId };
+			return { richTextOffset: null, localClientId };
 		}
 
 		// Text-based selections: resolve cursor position and navigate up.
@@ -233,7 +279,7 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 		);
 
 		if ( ! absolutePosition ) {
-			return { textIndex: null, localClientId: null };
+			return { richTextOffset: null, localClientId: null };
 		}
 
 		// Navigate up: Y.Text -> attributes Y.Map -> block Y.Map
@@ -242,7 +288,13 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 			yType instanceof Y.Map ? getBlockPathInYdoc( yType ) : null;
 		const localClientId = path ? resolveBlockClientIdByPath( path ) : null;
 
-		return { textIndex: absolutePosition.index, localClientId };
+		return {
+			richTextOffset: htmlIndexToRichTextOffset(
+				absolutePosition.type.toString(),
+				absolutePosition.index
+			),
+			localClientId,
+		};
 	}
 
 	/**
@@ -325,3 +377,50 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 		};
 	}
 }
+
+/**
+ * Detect the direction of a selection change by comparing old and new edges.
+ *
+ * When the user extends a selection backward (e.g. Shift+Left), the
+ * selectionStart edge moves while selectionEnd stays fixed, so the caret
+ * is at the start.  The reverse is true for forward extension.
+ *
+ * @param prevStart - The previous selectionStart.
+ * @param prevEnd   - The previous selectionEnd.
+ * @param newStart  - The new selectionStart.
+ * @param newEnd    - The new selectionEnd.
+ * @return The detected direction, defaulting to Forward when indeterminate.
+ */
+function detectSelectionDirection(
+	prevStart: WPBlockSelection,
+	prevEnd: WPBlockSelection,
+	newStart: WPBlockSelection,
+	newEnd: WPBlockSelection
+): SelectionDirection {
+	const startMoved = ! areBlockSelectionsEqual( prevStart, newStart );
+	const endMoved = ! areBlockSelectionsEqual( prevEnd, newEnd );
+
+	if ( startMoved && ! endMoved ) {
+		return SelectionDirection.Backward;
+	}
+
+	return SelectionDirection.Forward;
+}
+
+/**
+ * Compare two WPBlockSelection objects by value.
+ *
+ * @param a - First selection.
+ * @param b - Second selection.
+ * @return True if all fields are equal.
+ */
+function areBlockSelectionsEqual(
+	a: WPBlockSelection,
+	b: WPBlockSelection
+): boolean {
+	return (
+		a.clientId === b.clientId &&
+		a.attributeKey === b.attributeKey &&
+		a.offset === b.offset
+	);
+}