refactor(super-editor): route mixed-bidi Backspace through handleBackspace chain

The MixedBidiBackspace extension previously bound Backspace via addShortcuts
and dispatched its own transaction. That bypassed the canonical handleBackspace
chain in core/extensions/keymap.js, skipping:

- dispatchHistoryBoundary (so undo grouping diverged from regular Backspace),
- the tr.setMeta('inputType', 'deleteContentBackward') hop (tracked-changes
  helpers gate Backspace-specific wrapping on this meta - see
  trackChangesHelpers/trackedTransaction.js:447,
  trackChangesHelpers/replaceAroundStep.js:162),
- deleteBlockSdtAtTextBlockStart for SDT block boundaries,
- the rest of the specialized run-aware ladder.

Refactor:

- Expose mixedBidiBackspace as a chain command via addCommands(); shape
  matches the existing backspaceAcrossRuns / backspaceNextToRun pattern
  (factory returning ({state, view, tr, dispatch}) => boolean).
- Insert into the Backspace chain in keymap.js after backspaceAcrossRuns
  (specialized cross-run handling) and before deleteSelection (generic
  fallback), guarded with `?? false` so the chain works when the extension
  is unregistered.
- Split the detection logic into pure resolveMixedBidiBackspaceRange so the
  command body stays tiny.
- Tests rewritten to call the chain command shape directly and pin: chain
  dry-run mode (dispatch=undefined) returns true without mutating tr,
  non-mixed boundaries fall through, both RTL+LTR and LTR+RTL boundaries
  handled, posAtDOM is skipped early for pure-LTR/RTL lines.

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/extensions/keymap.js

@@ -43,6 +43,7 @@ export const handleBackspace = (editor) => {
     () => commands.backspaceAtomBefore(),
     () => commands.backspaceNextToRun(),
     () => commands.backspaceAcrossRuns(),
+    () => commands.mixedBidiBackspace?.() ?? false,
     () => commands.deleteSelection(),
     () => commands.removeNumberingProperties(),
     () => commands.joinBackward(),

packages/super-editor/src/editors/v1/extensions/mixed-bidi-backspace/mixed-bidi-backspace.js

@@ -108,55 +108,87 @@ const resolveBoundaryChars = (chars, caretPoint) => {
   return { left, right };
 };
 
-export const handleMixedBidiBackspace = (editor) => {
-  const { state, view } = editor;
+/**
+ * Compute the visual-left delete range at a mixed-bidi RTL/LTR boundary.
+ *
+ * Returns the PM-position range to delete, or `null` when the caret is not
+ * on a mixed-direction boundary. Pure: does not mutate state or dispatch.
+ *
+ * @param {{ state: any, view: any }} args
+ * @returns {{ from: number, to: number } | null}
+ */
+const resolveMixedBidiBackspaceRange = ({ state, view }) => {
   const { selection } = state;
-  if (!selection?.empty) return false;
+  if (!selection?.empty) return null;
 
-  const doc = view.dom.ownerDocument;
-  const nativeSelection = doc.getSelection();
-  if (!nativeSelection || nativeSelection.rangeCount === 0) return false;
+  const doc = view?.dom?.ownerDocument;
+  const nativeSelection = doc?.getSelection?.();
+  if (!nativeSelection || nativeSelection.rangeCount === 0) return null;
 
   const range = nativeSelection.getRangeAt(0);
-  if (!range.collapsed) return false;
+  if (!range.collapsed) return null;
 
   const caretPoint = resolveCaretPoint(doc, range);
-  if (!caretPoint) return false;
+  if (!caretPoint) return null;
 
   const lineEl = resolveLineElement(doc, caretPoint);
-  if (!lineEl) return false;
+  if (!lineEl) return null;
   const lineText = lineEl.textContent ?? '';
   const hasRtl = STRONG_RTL_CHAR_RE.test(lineText);
   const hasLtr = STRONG_LTR_CHAR_RE.test(lineText);
-  if (!hasRtl || !hasLtr) return false;
+  if (!hasRtl || !hasLtr) return null;
 
   let chars = collectVisualChars(lineEl, view, caretPoint.x);
   if (chars.length < 2) {
     // Fallback to a full scan for correctness when the local window is too narrow.
     chars = collectVisualChars(lineEl, view, null);
   }
   const boundary = resolveBoundaryChars(chars, caretPoint);
-  if (!boundary) return false;
+  if (!boundary) return null;
 
-  if (!hasMixedDirectionBoundary(boundary.left.char, boundary.right.char)) return false;
-  if (selection.from !== boundary.right.pmStart && selection.from !== boundary.left.pmEnd) return false;
+  if (!hasMixedDirectionBoundary(boundary.left.char, boundary.right.char)) return null;
+  if (selection.from !== boundary.right.pmStart && selection.from !== boundary.left.pmEnd) return null;
 
-  const tr = state.tr.delete(boundary.left.pmStart, boundary.left.pmEnd).scrollIntoView();
-  view.dispatch(tr);
-  return true;
+  return { from: boundary.left.pmStart, to: boundary.left.pmEnd };
 };
 
+/**
+ * Mixed-bidi Backspace command. Slotted into the keymap Backspace chain so it
+ * inherits the chain's history boundary, inputType: deleteContentBackward meta,
+ * track-changes wrapping, protected-range guards, and SDT handling, instead of
+ * dispatching its own transaction.
+ *
+ * Returns true (chain stops) only when the caret is at a strong-RTL/strong-LTR
+ * boundary and the visual-left character is targeted for deletion. Otherwise
+ * returns false so the chain falls through to deleteSelection / joinBackward.
+ *
+ * @returns {import('@core/commands/types/index.js').Command}
+ */
+export const mixedBidiBackspace =
+  () =>
+  ({ state, view, tr, dispatch }) => {
+    const range = resolveMixedBidiBackspaceRange({ state, view });
+    if (!range) return false;
+
+    if (dispatch) {
+      tr.delete(range.from, range.to);
+      tr.scrollIntoView();
+    }
+    return true;
+  };
+
 export const MixedBidiBackspace = Extension.create({
   name: 'mixedBidiBackspace',
 
-  addShortcuts() {
+  addCommands() {
     return {
-      Backspace: () => handleMixedBidiBackspace(this.editor),
+      mixedBidiBackspace,
     };
   },
 });
 
 export const __TEST_ONLY__ = {
   resolveCaretPoint,
   hasMixedDirectionBoundary,
+  resolveMixedBidiBackspaceRange,
 };

packages/super-editor/src/editors/v1/extensions/mixed-bidi-backspace/mixed-bidi-backspace.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { __TEST_ONLY__, handleMixedBidiBackspace } from './mixed-bidi-backspace.js';
+import { __TEST_ONLY__, mixedBidiBackspace } from './mixed-bidi-backspace.js';
 
 const makeRect = (left, top = 10, width = 8, height = 12) => ({
   left,
@@ -8,7 +8,7 @@ const makeRect = (left, top = 10, width = 8, height = 12) => ({
   height,
 });
 
-const setupEditor = ({ text, charLefts, caretRect, selectionFrom, pmBase = 10 }) => {
+const setupContext = ({ text, charLefts, caretRect, selectionFrom, pmBase = 10 }) => {
   const doc = document.implementation.createHTMLDocument('mixed-bidi-backspace');
   Object.defineProperty(doc, 'defaultView', {
     value: { NodeFilter: { SHOW_TEXT: 4 } },
@@ -64,137 +64,115 @@ const setupEditor = ({ text, charLefts, caretRect, selectionFrom, pmBase = 10 })
   };
   const view = {
     dom: { ownerDocument: doc },
-    dispatch,
     posAtDOM: vi.fn((node, offset) => {
       if (node !== textNode) throw new Error('unexpected node');
       return pmBase + offset;
     }),
   };
-  const editor = {
-    state: {
-      selection: { empty: true, from: selectionFrom },
-      tr,
-    },
-    view,
+  const state = {
+    selection: { empty: true, from: selectionFrom },
   };
 
-  return { editor, tr, dispatch };
+  return { state, view, tr, dispatch };
 };
 
-describe('mixed-bidi-backspace', () => {
-  it('deletes visual-left char on mixed-direction boundary', () => {
-    const { editor, tr, dispatch } = setupEditor({
+describe('mixedBidiBackspace (chain command)', () => {
+  it('returns true and mutates the chain tr on RTL+LTR boundary', () => {
+    const { state, view, tr, dispatch } = setupContext({
       text: 'אA',
       charLefts: [10, 20],
       caretRect: makeRect(20, 10, 1, 12),
       selectionFrom: 11,
       pmBase: 10,
     });
 
-    const handled = handleMixedBidiBackspace(editor);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch });
     expect(handled).toBe(true);
     expect(tr.delete).toHaveBeenCalledWith(10, 11);
-    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(tr.scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(dispatch).not.toHaveBeenCalled(); // chain owns dispatch
   });
 
-  it('fails open on non-mixed boundary (pure LTR)', () => {
-    const { editor, tr, dispatch } = setupEditor({
-      text: 'AB',
-      charLefts: [10, 20],
-      caretRect: makeRect(20, 10, 1, 12),
-      selectionFrom: 11,
-      pmBase: 10,
-    });
-
-    const handled = handleMixedBidiBackspace(editor);
-    expect(handled).toBe(false);
-    expect(tr.delete).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
-    expect(editor.view.posAtDOM).not.toHaveBeenCalled();
-  });
-
-  it('deletes visual-left char on inverse mixed boundary (LTR + RTL)', () => {
-    const { editor, tr, dispatch } = setupEditor({
+  it('returns true and mutates the chain tr on LTR+RTL boundary', () => {
+    const { state, view, tr } = setupContext({
       text: 'Aא',
       charLefts: [10, 20],
       caretRect: makeRect(20, 10, 1, 12),
       selectionFrom: 11,
       pmBase: 10,
     });
 
-    const handled = handleMixedBidiBackspace(editor);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch: vi.fn() });
     expect(handled).toBe(true);
     expect(tr.delete).toHaveBeenCalledWith(10, 11);
-    expect(dispatch).toHaveBeenCalledTimes(1);
   });
 
-  it('fails open when selectionFrom does not match boundary PM position', () => {
-    const { editor, tr, dispatch } = setupEditor({
-      text: 'אA',
+  it('returns false without mutating tr on pure LTR (chain falls through)', () => {
+    const { state, view, tr, dispatch } = setupContext({
+      text: 'AB',
       charLefts: [10, 20],
       caretRect: makeRect(20, 10, 1, 12),
-      selectionFrom: 999,
+      selectionFrom: 11,
       pmBase: 10,
     });
 
-    const handled = handleMixedBidiBackspace(editor);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch });
     expect(handled).toBe(false);
     expect(tr.delete).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
+    expect(tr.scrollIntoView).not.toHaveBeenCalled();
+    expect(view.posAtDOM).not.toHaveBeenCalled(); // early-out skips DOM scan
   });
 
-  it('fails open for punctuation bridge between RTL and LTR', () => {
-    const { editor, tr, dispatch } = setupEditor({
-      text: 'א.A',
-      charLefts: [10, 20, 30],
-      caretRect: makeRect(30, 10, 1, 12),
-      selectionFrom: 12,
+  it('returns false on non-empty selection (chain falls through)', () => {
+    const { state, view, tr } = setupContext({
+      text: 'אA',
+      charLefts: [10, 20],
+      caretRect: makeRect(20, 10, 1, 12),
+      selectionFrom: 11,
       pmBase: 10,
     });
+    state.selection.empty = false;
 
-    const handled = handleMixedBidiBackspace(editor);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch: vi.fn() });
     expect(handled).toBe(false);
     expect(tr.delete).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
   });
 
-  it('fails open when caret is at visual start (no left char)', () => {
-    const { editor, tr, dispatch } = setupEditor({
+  // SD-2933 / SD-2767: the chain's `dispatch` parameter is undefined during dry-run
+  // probing. The command must still return true without mutating tr in that mode.
+  // chain.first uses this to detect whether a command CAN handle the operation.
+  it('does not mutate tr when dispatch is undefined (chain dry-run probe)', () => {
+    const { state, view, tr } = setupContext({
       text: 'אA',
       charLefts: [10, 20],
-      caretRect: makeRect(5, 10, 1, 12),
-      selectionFrom: 10,
+      caretRect: makeRect(20, 10, 1, 12),
+      selectionFrom: 11,
       pmBase: 10,
     });
 
-    const handled = handleMixedBidiBackspace(editor);
-    expect(handled).toBe(false);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch: undefined });
+    expect(handled).toBe(true);
     expect(tr.delete).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
+    expect(tr.scrollIntoView).not.toHaveBeenCalled();
   });
 
-  it('fails open for non-collapsed selection', () => {
-    const { editor, tr, dispatch } = setupEditor({
-      text: 'אA',
-      charLefts: [10, 20],
-      caretRect: makeRect(20, 10, 1, 12),
-      selectionFrom: 11,
+  it('returns false when caret is not at the boundary (e.g. mid-word)', () => {
+    const { state, view, tr } = setupContext({
+      text: 'אAB',
+      charLefts: [10, 20, 30],
+      caretRect: makeRect(30, 10, 1, 12),
+      selectionFrom: 12, // past the boundary
       pmBase: 10,
     });
-    editor.state.selection.empty = false;
 
-    const handled = handleMixedBidiBackspace(editor);
+    const handled = mixedBidiBackspace()({ state, view, tr, dispatch: vi.fn() });
     expect(handled).toBe(false);
-    expect(tr.delete).not.toHaveBeenCalled();
-    expect(dispatch).not.toHaveBeenCalled();
   });
 
-  it('resolveCaretPoint returns null for zero-size rect', () => {
-    const doc = document.implementation.createHTMLDocument('caret-rect');
-    const result = __TEST_ONLY__.resolveCaretPoint(doc, {
-      getBoundingClientRect: () => makeRect(0, 0, 0, 0),
-      startContainer: doc.body,
-    });
-    expect(result).toBeNull();
+  it('exposes hasMixedDirectionBoundary helper for direct testing', () => {
+    expect(__TEST_ONLY__.hasMixedDirectionBoundary('א', 'A')).toBe(true);
+    expect(__TEST_ONLY__.hasMixedDirectionBoundary('A', 'א')).toBe(true);
+    expect(__TEST_ONLY__.hasMixedDirectionBoundary('A', 'B')).toBe(false);
+    expect(__TEST_ONLY__.hasMixedDirectionBoundary('א', 'ש')).toBe(false);
   });
 });