@atlaskit/editor-plugin-block-controls 20.0.3 → 20.1.0

package/dist/esm/ui/block-controls-surface-drag-handle-registration.js

@@ -3,11 +3,11 @@ function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbol
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 import React from 'react';
 import { BLOCK_CONTROL_UI_CONTEXT } from '@atlaskit/editor-common/block-controls/block-control-ui-context';
-import { BLOCK_CONTROLS_LEFT_GROUP } from '@atlaskit/editor-common/block-controls/surface-keys';
+import { BLOCK_CONTROLS_DRAG_HANDLE, BLOCK_CONTROLS_LEFT_GROUP } from '@atlaskit/editor-common/block-controls/surface-keys';
 import { BlockControlsSurfaceDragHandle } from './block-controls-surface-drag-handle';
 export var getBlockControlsSurfaceDragHandleComponents = function getBlockControlsSurfaceDragHandleComponents(_ref) {
   var api = _ref.api;
-  return [{
+  return [_objectSpread(_objectSpread({
     component: function component(_ref2) {
       var surfaceContext = _ref2.surfaceContext;
       return /*#__PURE__*/React.createElement(BlockControlsSurfaceDragHandle, {
@@ -19,12 +19,11 @@ export var getBlockControlsSurfaceDragHandleComponents = function getBlockContro
       var _ref3 = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {},
         surfaceContext = _ref3.surfaceContext;
       var context = surfaceContext === null || surfaceContext === void 0 ? void 0 : surfaceContext.get(BLOCK_CONTROL_UI_CONTEXT);
-      return !(context !== null && context !== void 0 && context.activeNode) || context.targetNode.pos !== context.activeNode.pos;
-    },
-    key: 'block-controls-drag-handle',
+      return !(context !== null && context !== void 0 && context.activeNode) || context.targetNode.pos !== context.activeNode.pos || context.activeControlKey !== undefined && context.activeControlKey !== BLOCK_CONTROLS_DRAG_HANDLE.key;
+    }
+  }, BLOCK_CONTROLS_DRAG_HANDLE), {}, {
     parents: [_objectSpread(_objectSpread({}, BLOCK_CONTROLS_LEFT_GROUP), {}, {
       rank: 200
-    })],
-    type: 'button'
-  }];
+    })]
+  })];
 };

package/dist/esm/ui/block-controls-surface-drag-handle.js

@@ -118,7 +118,11 @@ export var BlockControlsSurfaceDragHandle = function BlockControlsSurfaceDragHan
     return !isTopLevelNode || $anchor.depth > DRAG_HANDLE_MAX_SHIFT_CLICK_DEPTH;
   }, [api, isLayoutColumn, isShiftDown, isTopLevelNode, view]);
   var getAnchorName = useCallback(function () {
-    var _ref2, _ref3, _dom$getAttribute, _dom$closest;
+    var _api$blockControls$sh2, _ref2, _ref3, _dom$getAttribute, _dom$closest;
+    var surfaceAnchor = posRef.current === undefined ? undefined : api === null || api === void 0 || (_api$blockControls$sh2 = api.blockControls.sharedState.currentState()) === null || _api$blockControls$sh2 === void 0 || (_api$blockControls$sh2 = _api$blockControls$sh2.surfaceAnchors) === null || _api$blockControls$sh2 === void 0 ? void 0 : _api$blockControls$sh2.get(posRef.current);
+    if (surfaceAnchor) {
+      return surfaceAnchor;
+    }
     if (activeNodeAnchorName) {
       return activeNodeAnchorName;
     }
@@ -132,7 +136,7 @@ export var BlockControlsSurfaceDragHandle = function BlockControlsSurfaceDragHan
     }
     var anchorAttrName = getAnchorAttrName();
     return (_ref2 = (_ref3 = (_dom$getAttribute = dom.getAttribute(anchorAttrName)) !== null && _dom$getAttribute !== void 0 ? _dom$getAttribute : dom.getAttribute(NODE_ANCHOR_ATTR_NAME)) !== null && _ref3 !== void 0 ? _ref3 : (_dom$closest = dom.closest("[".concat(anchorAttrName, "]"))) === null || _dom$closest === void 0 ? void 0 : _dom$closest.getAttribute(anchorAttrName)) !== null && _ref2 !== void 0 ? _ref2 : '';
-  }, [activeNodeAnchorName, view]);
+  }, [activeNodeAnchorName, api, view]);
   useLayoutEffect(function () {
     var element = buttonRef.current;
     if (!view || !element) {

package/dist/esm/ui/drag-handle.js

@@ -736,10 +736,12 @@ export var DragHandle = function DragHandle(_ref2) {
     });
   }, [anchorName, api, getPos, nodeType, start, view]);
   var calculatePositionOld = useCallback(function () {
+    var _$pos$nodeAfter;
     var pos = getPos();
-    var $pos = expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? typeof pos === 'number' && view.state.doc.resolve(pos) : pos && view.state.doc.resolve(pos);
+    var $pos = typeof pos === 'number' ? view.state.doc.resolve(pos) : undefined;
     var parentPos = $pos && $pos.depth ? $pos.before() : undefined;
     var node = parentPos !== undefined ? view.state.doc.nodeAt(parentPos) : undefined;
+    var nodeTypeWithLevel = $pos !== null && $pos !== void 0 && (_$pos$nodeAfter = $pos.nodeAfter) !== null && _$pos$nodeAfter !== void 0 && _$pos$nodeAfter.isBlock ? getNodeTypeWithLevel($pos.nodeAfter) : nodeType;
     var parentNodeType = node === null || node === void 0 ? void 0 : node.type.name;
     var supportsAnchor = CSS.supports('top', "anchor(".concat(anchorName, " start)")) && CSS.supports('left', "anchor(".concat(anchorName, " start)"));
     var safeAnchorName = editorExperiment('platform_editor_controls', 'variant1') ? refreshAnchorName({
@@ -797,13 +799,13 @@ export var DragHandle = function DragHandle(_ref2) {
       var bottom = editorExperiment('platform_editor_controls', 'variant1') ? getControlBottomCSSValue(safeAnchorName, isSticky, isTopLevelNodeValue, isLayoutColumn, ACTIVE_DRAG_HANDLE_FALLBACK_ANCHOR_NAME) : {};
       return _objectSpread({
         left: isEdgeCase ? "calc(".concat(anchorStart, " + ").concat(getLeftPosition(dom, nodeType, innerContainer, isMacroInteractionUpdates, parentNodeType), ")") : editorExperiment('advanced_layouts', true) && isLayoutColumn ? "calc((".concat(anchorRight, " + ").concat(anchorLeft, ")/2 - ").concat(DRAG_HANDLE_HEIGHT / 2, "px)") : "calc(".concat(anchorStart, " - ").concat(DRAG_HANDLE_WIDTH, "px - ").concat(dragHandleGap(nodeType, parentNodeType), "px)"),
-        top: editorExperiment('advanced_layouts', true) && isLayoutColumn ? "calc(".concat(anchorTop, " - ").concat(DRAG_HANDLE_WIDTH, "px)") : "calc(".concat(anchorStart, " + ").concat(topPositionAdjustment(expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? $pos && $pos.nodeAfter && getNodeTypeWithLevel($pos.nodeAfter) || nodeType : nodeType, (dom === null || dom === void 0 ? void 0 : dom.getAttribute('layout')) || ''), "px)")
+        top: editorExperiment('advanced_layouts', true) && isLayoutColumn ? "calc(".concat(anchorTop, " - ").concat(DRAG_HANDLE_WIDTH, "px)") : "calc(".concat(anchorStart, " + ").concat(topPositionAdjustment(nodeTypeWithLevel, (dom === null || dom === void 0 ? void 0 : dom.getAttribute('layout')) || ''), "px)")
       }, bottom);
     }
     var height = editorExperiment('platform_editor_controls', 'variant1') ? getControlHeightCSSValue(getNodeHeight(dom, safeAnchorName, anchorRectCache) || 0, isSticky, isTopLevelNodeValue, "".concat(DRAG_HANDLE_HEIGHT), isLayoutColumn) : {};
     return _objectSpread({
       left: isEdgeCase ? "calc(".concat((dom === null || dom === void 0 ? void 0 : dom.offsetLeft) || 0, "px + ").concat(getLeftPosition(dom, nodeType, innerContainer, isMacroInteractionUpdates, parentNodeType), ")") : getLeftPosition(dom, nodeType, innerContainer, isMacroInteractionUpdates, parentNodeType),
-      top: getTopPosition(dom, nodeType)
+      top: getTopPosition(dom, nodeTypeWithLevel)
     }, height);
   }, [anchorName, getPos, view, nodeType, blockCardWidth, macroInteractionUpdates, anchorRectCache, isTopLevelNodeValue, isLayoutColumn]);
   var isReliableAnchorEnabled = expValEquals('platform_editor_controls_reliable_anchor', 'isEnabled', true);

package/dist/esm/ui/drop-target-layout.js

@@ -9,6 +9,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 // eslint-disable-next-line @atlaskit/ui-styling-standard/use-compiled, @typescript-eslint/consistent-type-imports
 import { css, jsx } from '@emotion/react';
 import { layoutBreakpointWidth } from '@atlaskit/editor-shared-styles';
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { DropIndicator } from '@atlaskit/pragmatic-drag-and-drop-react-drop-indicator/box';
 import { dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/adapter/element-adapter';
 import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
@@ -121,7 +122,7 @@ export var DropTargetLayout = function DropTargetLayout(props) {
   }, isDraggedOver ? jsx(DropIndicator, {
     edge: "right",
     gap: "-".concat(DROP_TARGET_LAYOUT_DROP_ZONE_WIDTH, "px")
-  }) : (isActiveAnchor || expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) && jsx("div", {
+  }) : (isActiveAnchor || expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) && jsx("div", {
     "data-testid": "block-ctrl-drop-hint",
     css: dropTargetLayoutHintStyle
   }));
@@ -236,7 +237,7 @@ export var DropTargetLayoutNativeAnchorSupport = function DropTargetLayoutNative
   }, isDraggedOver ? jsx(DropIndicator, {
     edge: "right",
     gap: "-".concat(DROP_TARGET_LAYOUT_DROP_ZONE_WIDTH, "px")
-  }) : (isActiveAnchor || expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) && jsx("div", {
+  }) : (isActiveAnchor || expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) && jsx("div", {
     "data-testid": "block-ctrl-drop-hint",
     css: dropTargetLayoutHintStyle
   }));

package/dist/esm/ui/drop-target.js

@@ -10,6 +10,7 @@ import { Fragment, useEffect, useMemo, useRef, useState } from 'react';
 import { css, jsx } from '@emotion/react';
 import { useSharedPluginStateWithSelector } from '@atlaskit/editor-common/hooks';
 import { getBaseNodeTypeName } from '@atlaskit/editor-common/utils/node-type-utils';
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { DropIndicator } from '@atlaskit/pragmatic-drag-and-drop-react-drop-indicator/box';
 import { dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/adapter/element-adapter';
 import { layers } from '@atlaskit/theme/constants';
@@ -86,7 +87,7 @@ var HoverZone = function HoverZone(_ref) {
   var ref = useRef(null);
   var isRemainingheight = dropTargetStyle === 'remainingHeight';
   var anchorName = useMemo(function () {
-    if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+    if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
       if (node && typeof pos === 'number') {
         var posOffset = position === 'upper' ? -node.nodeSize : 0;
         return (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(node, pos + posOffset)) || '';
@@ -140,7 +141,7 @@ var HoverZone = function HoverZone(_ref) {
     // only apply upper drop zone
     if (isRemainingheight && position === 'upper') {
       // previous node
-      var _anchorName = node ? expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(node, pos || -1)) || '' : getNodeAnchor(node) : '';
+      var _anchorName = node ? expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(node, pos || -1)) || '' : getNodeAnchor(node) : '';
       var top = 'unset';
       if (_anchorName) {
         var enabledDropZone = getEnableDropZone().includes((node === null || node === void 0 ? void 0 : node.type.name) || '');

package/dist/esm/ui/global-styles.js

@@ -13,7 +13,7 @@ import { akEditorBreakoutPadding, akEditorCalculatedWideLayoutWidth, akEditorCal
 import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { editorExperiment } from '@atlaskit/tmp-editor-statsig/editor-experiment';
 import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
-import { ACTIVE_DRAG_HANDLE_ATTR, ACTIVE_DRAG_HANDLE_FALLBACK_ANCHOR_NAME, ACTIVE_QUICK_INSERT_ATTR, ACTIVE_QUICK_INSERT_FALLBACK_ANCHOR_NAME, DRAG_HANDLE_MAX_WIDTH_PLUS_GAP } from './consts';
+import { ACTIVE_DRAG_HANDLE_FALLBACK_ANCHOR_NAME, ACTIVE_QUICK_INSERT_FALLBACK_ANCHOR_NAME, DRAG_HANDLE_MAX_WIDTH_PLUS_GAP } from './consts';
 import { NODE_ANCHOR_ATTR_NAME } from './utils/dom-attr-name';
 
 /**
@@ -369,17 +369,70 @@ var staticControlsAnchorStyles = css({
     }
   }
 });
+var sparseSurfaceAnchorName = 'var(--block-controls-surface-anchor-name)';
 
-/**
- * Names the CSS anchor on top-level nodes, so the block controls surfaces can anchor to the blocks
- * they render against. Only top-level at the moment as we don't have use cases yet for persistent controls that are nested.
- */
-var surfaceAnchorStyles = css({
+// Inner node-view boxes own the visible geometry for these nodes. The root arm keeps a sparse
+// marker useful when a node view has not mounted its inner box yet.
+var sparseSurfaceAnchorStyles = css({
   // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors
-  '.ProseMirror': _defineProperty({}, "[".concat(NODE_ANCHOR_ATTR_NAME, "]:not([").concat(NODE_ANCHOR_ATTR_NAME, "] [").concat(NODE_ANCHOR_ATTR_NAME, "]):not([").concat(ACTIVE_DRAG_HANDLE_ATTR, "], [").concat(ACTIVE_QUICK_INSERT_ATTR, "])"), {
-    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-values, @atlaskit/ui-styling-standard/no-imported-style-values
-    anchorName: "var(".concat(ANCHOR_VARIABLE_NAME, ", attr(data-node-anchor type(<custom-ident>)))")
-  })
+  '.ProseMirror': {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="blockCard"]:has(.datasourceView-content-inner-wrap) .datasourceView-content-inner-wrap': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="blockCard"]:not(:has(.datasourceView-content-inner-wrap))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="bodiedExtension"]:has(.extension-container[data-layout]) .extension-container[data-layout]': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="bodiedExtension"]:not(:has(.extension-container[data-layout]))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="embedCard"]:has(.rich-media-item) .rich-media-item': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="embedCard"]:not(:has(.rich-media-item))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="extension"]:has(.extension-container[data-layout]) .extension-container[data-layout]': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="extension"]:not(:has(.extension-container[data-layout]))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="mediaSingle"]:has(.resizer-item) .resizer-item': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="mediaSingle"]:not(:has(.resizer-item))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="multiBodiedExtension"]:has(.extension-container[data-layout]) .extension-container[data-layout]': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="multiBodiedExtension"]:not(:has(.extension-container[data-layout]))': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="table"]:has(.resizer-item) .resizer-item': {
+      anchorName: sparseSurfaceAnchorName
+    },
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-nested-selectors, @atlaskit/ui-styling-standard/no-unsafe-selectors
+    '[data-block-controls-surface-anchor][data-block-controls-surface-node-type="table"]:not(:has(.resizer-item))': {
+      anchorName: sparseSurfaceAnchorName
+    }
+  }
 });
 
 // Styles applied to nodes with anchors when dragging
@@ -419,33 +472,22 @@ export var GlobalStylesWrapper = function GlobalStylesWrapper(_ref) {
       };
     }),
     isDraggingFromState = _useSharedPluginState.isDragging;
-  var isDragging = expValEquals('platform_editor_block_controls_perf_optimization', 'isEnabled', true) ? isDraggingFromState : false;
+  var sparseSurfacesEnabled = isExperimentEnabled('platform_editor_block_control_migration');
+  var isDragging = sparseSurfacesEnabled || expValEquals('platform_editor_block_controls_perf_optimization', 'isEnabled', true) ? isDraggingFromState : false;
   var shouldRenderAnchors = isCSSAnchorSupported() && expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true);
-
-  // The surfaces anchor to blocks they render against rather than only to the hovered one, so they
-  // need a name on every node. Added alongside whichever conditional rule applies rather than
-  // replacing it: this one matches only non-active nodes, so the two sets are disjoint.
-  //
-  // The migration check is what scopes this. Unlike the surfaces, this component renders for every
-  // editor, so without it the rule would name anchors on documents that have no surface to anchor.
-  var shouldRenderSurfaceAnchors =
-  // eslint-disable-next-line @atlaskit/platform/no-preconditioning -- browser capability, not a flag: an anchor name is meaningless where `anchor()` cannot resolve
-  Boolean(isCSSAnchorSupported()) && isExperimentEnabled('platform_editor_block_control_migration');
+  var sparseSurfaceAnchorsEnabled = Boolean(isCSSAnchorSupported()) && sparseSurfacesEnabled;
   var toolbarFlagsEnabled = areToolbarFlagsEnabled(Boolean(api === null || api === void 0 ? void 0 : api.toolbar));
   return jsx(Global
   // eslint-disable-next-line @atlassian/perf-linting/no-unstable-inline-props -- Ignored via go/ees017 (to be fixed)
   , {
-    styles: [globalStyles(), globalDnDStyle, expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? extendedHoverZoneNext() : extendedHoverZone(), isDragging && (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? extendedDragZoneNext : extendedDragZone), editorExperiment('platform_editor_preview_panel_responsiveness', true, {
+    styles: [globalStyles(), globalDnDStyle, (!sparseSurfacesEnabled || isDragging) && (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? extendedHoverZoneNext() : extendedHoverZone()), isDragging && (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? extendedDragZoneNext : extendedDragZone), (!sparseSurfacesEnabled || isDragging) && editorExperiment('platform_editor_preview_panel_responsiveness', true, {
       exposure: true
-    }) ? expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? extendHoverZoneReducedNext : extendHoverZoneReduced : undefined,
+    }) ? expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? extendHoverZoneReducedNext : extendHoverZoneReduced : undefined,
     // platform_editor_controls note: this allows drag handles to render on empty lines
-    toolbarFlagsEnabled ? undefined : withInlineNodeStyle, withDeleteLinesStyleFix, withMediaSingleStyleFix, legacyBreakoutWideLayoutStyle, headingWithIndentationInLayoutStyleFix, editorExperiment('advanced_layouts', true) ? blockCardWithoutLayout : undefined, withDividerInPanelStyleFix, withFormatInLayoutStyleFix, expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? withRelativePosStyleNext : withRelativePosStyle, expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? withAnchorNameZindexStyleNext : withAnchorNameZindexStyle, expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) && expValEquals('advanced_layouts', 'isEnabled', true) ? layoutColumnExtendedHoverZone : layoutColumnWithoutHoverZone, expValEquals('platform_editor_controls_reliable_anchor', 'isEnabled', true) ?
+    toolbarFlagsEnabled ? undefined : withInlineNodeStyle, withDeleteLinesStyleFix, withMediaSingleStyleFix, legacyBreakoutWideLayoutStyle, headingWithIndentationInLayoutStyleFix, editorExperiment('advanced_layouts', true) ? blockCardWithoutLayout : undefined, withDividerInPanelStyleFix, withFormatInLayoutStyleFix, (!sparseSurfacesEnabled || isDragging) && (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? withRelativePosStyleNext : withRelativePosStyle), (!sparseSurfacesEnabled || isDragging) && (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? withAnchorNameZindexStyleNext : withAnchorNameZindexStyle), (!sparseSurfacesEnabled || isDragging) && ((expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) && expValEquals('advanced_layouts', 'isEnabled', true) ? layoutColumnExtendedHoverZone : layoutColumnWithoutHoverZone), sparseSurfaceAnchorsEnabled ? isDragging ? dragAnchorStyles : false : expValEquals('platform_editor_controls_reliable_anchor', 'isEnabled', true) ?
     // dragAnchorStyles sets anchor-name on ALL nodes during drag (needed for drop target positioning).
     // staticControlsAnchorStyles handles anchor-name via node decorations for non-drag state.
     // shouldRenderAnchors guards both: only apply anchor styles on browsers that support CSS anchor positioning.
-    shouldRenderAnchors ? isDragging ? dragAnchorStyles : staticControlsAnchorStyles : false : shouldRenderAnchors && (isDragging ? dragAnchorStyles : dragHandlerAnchorStyles),
-    // Last so that, at equal specificity, the surfaces' own anchor names are the ones that
-    // stand. It cannot overlap the active-node rules above, which this selector excludes.
-    shouldRenderSurfaceAnchors && surfaceAnchorStyles]
+    shouldRenderAnchors ? isDragging ? dragAnchorStyles : staticControlsAnchorStyles : false : shouldRenderAnchors && (isDragging ? dragAnchorStyles : dragHandlerAnchorStyles), sparseSurfaceAnchorsEnabled && sparseSurfaceAnchorStyles]
   });
 };

package/dist/esm/ui/inline-drop-target.js

@@ -11,6 +11,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 // eslint-disable-next-line @atlaskit/ui-styling-standard/use-compiled, @typescript-eslint/consistent-type-imports
 import { css, jsx } from '@emotion/react';
 import { akEditorBreakoutPadding } from '@atlaskit/editor-shared-styles';
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { DropIndicator } from '@atlaskit/pragmatic-drag-and-drop-react-drop-indicator/box';
 import { dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/adapter/element-adapter';
 import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
@@ -92,7 +93,7 @@ export var InlineDropTarget = function InlineDropTarget(_ref) {
     isDraggedOver = _useState2[0],
     setIsDraggedOver = _useState2[1];
   var anchorName = useMemo(function () {
-    if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+    if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
       var _getPos;
       return nextNode ? (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(nextNode, (_getPos = getPos()) !== null && _getPos !== void 0 ? _getPos : -1)) || '' : '';
     }
@@ -125,7 +126,7 @@ export var InlineDropTarget = function InlineDropTarget(_ref) {
         innerContainerWidth = "calc(var(--ak-editor--line-length) * ".concat(percentageWidth, ")");
       }
     } else if (nextNode.type.name === 'table' && nextNode.firstChild) {
-      var tableWidthAnchor = expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) ? typeof nextNodePos === 'number' ? (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(nextNode.firstChild, nextNodePos + 1)) || '' : '' : getNodeAnchor(nextNode.firstChild);
+      var tableWidthAnchor = expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration') ? typeof nextNodePos === 'number' ? (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(nextNode.firstChild, nextNodePos + 1)) || '' : '' : getNodeAnchor(nextNode.firstChild);
       var isNumberColumnEnabled = Boolean(nextNode.attrs.isNumberColumnEnabled);
       if (isAnchorSupported()) {
         innerContainerWidth = isNumberColumnEnabled ? "calc(anchor-size(".concat(tableWidthAnchor, " width) + ").concat(TABLE_NUMBERED_COLUMN_WIDTH, "px)") : "anchor-size(".concat(tableWidthAnchor, " width)");
@@ -138,7 +139,7 @@ export var InlineDropTarget = function InlineDropTarget(_ref) {
         innerContainerWidth = "min(".concat(nextNode.attrs.width, "px, ").concat(innerContainerWidth, ")");
       }
     } else if (nextNode.type.name === 'mediaSingle' && nextNode.firstChild) {
-      if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+      if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
         var _nextNode$firstChild;
         // check pos is a number
         if (typeof nextNodePos === 'number' && ((_nextNode$firstChild = nextNode.firstChild) === null || _nextNode$firstChild === void 0 ? void 0 : _nextNode$firstChild.type.name) === 'media') {
@@ -153,7 +154,7 @@ export var InlineDropTarget = function InlineDropTarget(_ref) {
     var heightTargetAnchorName = targetAnchorName;
     if (nextNode.type.name === 'layoutSection' && nextNode.firstChild && nextNode.lastChild) {
       if (isLeftPosition) {
-        if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+        if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
           if (typeof nextNodePos === 'number') {
             heightTargetAnchorName = (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(nextNode.firstChild, nextNodePos + 1)) || '';
           } else {
@@ -163,7 +164,7 @@ export var InlineDropTarget = function InlineDropTarget(_ref) {
           heightTargetAnchorName = getNodeAnchor(nextNode.firstChild);
         }
       } else {
-        if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+        if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
           if (typeof nextNodePos === 'number') {
             var lastNodeStartPos = nextNode.content.size - nextNode.lastChild.nodeSize;
             heightTargetAnchorName = (api === null || api === void 0 ? void 0 : api.core.actions.getAnchorIdForNode(nextNode.lastChild, lastNodeStartPos + 1)) || '';

package/dist/esm/ui/utils/anchor-name.js

@@ -1,3 +1,4 @@
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 import { findNodeDecs } from '../../pm-plugins/decorations-anchor';
 import { key } from '../../pm-plugins/main';
@@ -10,7 +11,7 @@ export var refreshAnchorName = function refreshAnchorName(_ref) {
     view = _ref.view,
     anchorName = _ref.anchorName;
   var newAnchorName = anchorName || '';
-  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
     return newAnchorName;
   }
   var pos = getPos();

package/dist/esm/ui/utils/dom-attr-name.js

@@ -1,14 +1,15 @@
+import { isExperimentEnabled } from '@atlaskit/platform-feature-experiments/is-experiment-enabled';
 import { expValEquals } from '@atlaskit/tmp-editor-statsig/exp-val-equals';
 export var NODE_ANCHOR_ATTR_NAME = 'data-node-anchor';
 export var NODE_NODE_TYPE_ATTR_NAME = 'data-prosemirror-node-name';
 export var getAnchorAttrName = function getAnchorAttrName() {
-  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
     return NODE_ANCHOR_ATTR_NAME;
   }
   return 'data-drag-handler-anchor-name';
 };
 export var getTypeNameAttrName = function getTypeNameAttrName() {
-  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true)) {
+  if (expValEquals('platform_editor_native_anchor_with_dnd', 'isEnabled', true) || isExperimentEnabled('platform_editor_block_control_migration')) {
     return NODE_NODE_TYPE_ATTR_NAME;
   }
   return 'data-drag-handler-node-type';

package/dist/esm/ui/utils/get-surface-placement.js

@@ -98,6 +98,7 @@ var INVALID_ANCHOR_FALLBACK_TOP = "-".concat(INVALID_ANCHOR_OFFSCREEN_PX, "px");
 var INVALID_ANCHOR_FALLBACK_BOTTOM = "".concat(INVALID_ANCHOR_OFFSCREEN_PX, "px");
 export var getAnchoredSurfacePlacement = function getAnchoredSurfacePlacement(_ref3) {
   var anchorName = _ref3.anchorName,
+    layout = _ref3.layout,
     nodeType = _ref3.nodeType,
     nodeTypeWithLevel = _ref3.nodeTypeWithLevel,
     parentNodeType = _ref3.parentNodeType,
@@ -124,7 +125,7 @@ export var getAnchoredSurfacePlacement = function getAnchoredSurfacePlacement(_r
     } : {}), {}, {
       left: side === 'right' ? "calc(anchor(".concat(anchorName, " right) + ").concat(gap, "px)") : "anchor(".concat(anchorName, " left)"),
       positionAnchor: anchorName,
-      top: "calc(anchor(".concat(anchorName, " top, ").concat(INVALID_ANCHOR_FALLBACK_TOP, ") + ").concat(topPositionAdjustment(nodeTypeWithLevel), "px)"),
+      top: "calc(anchor(".concat(anchorName, " top, ").concat(INVALID_ANCHOR_FALLBACK_TOP, ") + ").concat(topPositionAdjustment(nodeTypeWithLevel, layout), "px)"),
       // The left side grows away from the node without knowing its own width, so it pulls itself
       // back past its own box and the gap. The right side grows into the margin, so the gap is
       // already folded into `left` above.

package/dist/types/blockControlsPluginType.d.ts

@@ -13,7 +13,7 @@ import type { LimitedModePlugin } from '@atlaskit/editor-plugin-limited-mode';
 import type { MetricsPlugin } from '@atlaskit/editor-plugin-metrics';
 import type { QuickInsertPlugin } from '@atlaskit/editor-plugin-quick-insert';
 import type { SelectionPlugin } from '@atlaskit/editor-plugin-selection';
-import type { ShowDiffPlugin } from '@atlaskit/editor-plugin-show-diff';
+import type { ShowDiffPlugin } from '@atlaskit/editor-plugin-show-diff/show-diff-plugin-type';
 import type { ToolbarPlugin } from '@atlaskit/editor-plugin-toolbar';
 import type { TypeAheadPlugin } from '@atlaskit/editor-plugin-type-ahead';
 import type { UiControlRegistryPlugin } from '@atlaskit/editor-plugin-ui-control-registry/ui-control-registry-plugin-type';
@@ -24,6 +24,7 @@ import type { Mapping } from '@atlaskit/editor-prosemirror/transform';
 import type { Decoration, DecorationSet, EditorView } from '@atlaskit/editor-prosemirror/view';
 export type ActiveNode = {
     anchorName: string;
+    controlKey?: string;
     handleOptions?: HandleOptions;
     nodeType: string;
     pos: number;
@@ -115,11 +116,14 @@ export type BlockControlsSharedState = {
     preservedSelection?: Selection;
     /** Whether left/right hover split is enabled (from plugin config) */
     rightSideControlsEnabled?: boolean;
-    surfaceNodePositions?: number[];
+    surfaceActiveNodes?: ReadonlyMap<number, ActiveNode>;
+    surfaceAnchors?: ReadonlyMap<number, string>;
+    surfaceNodePositions?: readonly number[];
 } | undefined;
-export type HandleOptions = {
+export type ControlOptions = {
     isFocused: boolean;
 } | undefined;
+export type HandleOptions = ControlOptions;
 /**
  * Props passed to custom right-edge button components (e.g. config.rightEdgeButton).
  */
@@ -225,6 +229,9 @@ export type BlockControlsPlugin = NextEditorPlugin<'blockControls', {
         setMultiSelectPositions: (anchor?: number, head?: number) => EditorCommand;
         setNodeDragged: (getPos: () => number | undefined, anchorName: string, nodeType: string) => EditorCommand;
         setSelectedViaDragHandle: (isSelectedViaDragHandle?: boolean) => EditorCommand;
+        showControlAtPosition: (pos: number, control: {
+            key: string;
+        }, options?: ControlOptions) => EditorCommand;
         showDragHandleAt: (pos: number, anchorName: string, nodeType: string, handleOptions?: HandleOptions, rootPos?: number, rootAnchorName?: string, rootNodeType?: string) => EditorCommand;
         /**
          * Starts preserving the current selection across transactions.

package/dist/types/pm-plugins/decorations-surface-anchor.d.ts

@@ -0,0 +1,22 @@
+import type { Node as PMNode } from '@atlaskit/editor-prosemirror/model';
+import type { EditorState } from '@atlaskit/editor-prosemirror/state';
+import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
+export declare const TYPE_SURFACE_ANCHOR_DEC = "block-controls-surface-anchor";
+export declare const SURFACE_ANCHOR_ATTR = "data-block-controls-surface-anchor";
+export declare const SURFACE_NODE_TYPE_ATTR = "data-block-controls-surface-node-type";
+export declare const SURFACE_ANCHOR_VARIABLE = "--block-controls-surface-anchor-name";
+export type SurfaceAnchorDecorationSpec = {
+    anchorName: string;
+    nodeType: string;
+    type: typeof TYPE_SURFACE_ANCHOR_DEC;
+};
+export type SurfaceAnchorDecorationResult = {
+    anchors: ReadonlyMap<number, string>;
+    decorations: DecorationSet;
+};
+/**
+ * Builds sparse CSS anchor decorations from already-qualified cached positions. Anchor identity is
+ * supplied by the editor's native node-anchor provider so sparse surfaces and consumers share the
+ * same `data-node-anchor`.
+ */
+export declare const createSurfaceAnchorDecorations: (state: EditorState, positions: readonly number[], resolveAnchorName: (node: PMNode, position: number, previousAnchorName: string | undefined) => string | undefined, previousAnchors?: ReadonlyMap<number, string>) => SurfaceAnchorDecorationResult;

package/dist/types/pm-plugins/handle-sparse-mouse-over.d.ts

@@ -0,0 +1,5 @@
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
+import type { EditorView } from '@atlaskit/editor-prosemirror/view';
+import type { BlockControlsPlugin } from '../blockControlsPluginType';
+/** Resolves hover from PM structure so the first hover can create its sparse candidate. */
+export declare const handleSparseMouseOver: (view: EditorView, event: Event, api: ExtractInjectionAPI<BlockControlsPlugin> | undefined) => boolean;

package/dist/types/pm-plugins/main.d.ts

@@ -5,21 +5,14 @@ import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
 import type { EditorState, ReadonlyTransaction, Transaction } from '@atlaskit/editor-prosemirror/state';
 import { PluginKey } from '@atlaskit/editor-prosemirror/state';
 import { DecorationSet } from '@atlaskit/editor-prosemirror/view';
-import type { ResolvedSurface } from '@atlaskit/editor-ui-control-model/surface-renderer/types';
 import type { ActiveDropTargetNode, BlockControlsMeta, BlockControlsPlugin, MultiSelectDnD, NodeDecorationFactory, PluginState } from '../blockControlsPluginType';
 import { AnchorRectCache } from './utils/anchor-utils';
 export declare const key: PluginKey<PluginState>;
 export interface FlagType {
-    /**
-     * Whether the legacy widget-decoration drag handle is rendered. The registry surface renders
-     * its replacement when this is false.
-     */
-    legacyDragHandleEnabled: boolean;
-    surfaceNodePositionsEnabled: boolean;
     toolbarFlagsEnabled: boolean;
 }
 export declare const getDecorations: (state: EditorState) => DecorationSet | undefined;
-export declare const apply: (api: ExtractInjectionAPI<BlockControlsPlugin> | undefined, formatMessage: IntlShape['formatMessage'], tr: ReadonlyTransaction, currentState: PluginState, newState: EditorState, flags: FlagType, nodeViewPortalProviderAPI: PortalProviderAPI, nodeDecorationRegistry: NodeDecorationFactory[], rightSideControlsEnabled?: boolean, quickInsertButtonEnabled?: boolean, anchorRectCache?: AnchorRectCache, resizeObserverWidth?: ResizeObserver, pragmaticCleanup?: (() => void) | null, resolvedSurfaces?: readonly ResolvedSurface[], limitedModeTeardown?: {
+export declare const apply: (api: ExtractInjectionAPI<BlockControlsPlugin> | undefined, formatMessage: IntlShape['formatMessage'], tr: ReadonlyTransaction, currentState: PluginState, newState: EditorState, flags: FlagType, nodeViewPortalProviderAPI: PortalProviderAPI, nodeDecorationRegistry: NodeDecorationFactory[], rightSideControlsEnabled?: boolean, quickInsertButtonEnabled?: boolean, anchorRectCache?: AnchorRectCache, resizeObserverWidth?: ResizeObserver, pragmaticCleanup?: (() => void) | null, limitedModeTeardown?: {
     done: boolean;
 }) => PluginState | {
     activeDropTargetNode: ActiveDropTargetNode | undefined;
@@ -46,7 +39,7 @@ export declare const apply: (api: ExtractInjectionAPI<BlockControlsPlugin> | und
     multiSelectDnD: MultiSelectDnD | undefined;
     surfaceNodePositions: number[];
 };
-export declare const createPlugin: (api: ExtractInjectionAPI<BlockControlsPlugin> | undefined, getIntl: () => IntlShape, nodeViewPortalProviderAPI: PortalProviderAPI, nodeDecorationRegistry: NodeDecorationFactory[], rightSideControlsEnabled?: boolean, quickInsertButtonEnabled?: boolean, legacyDragHandleEnabled?: boolean) => SafePlugin<PluginState | {
+export declare const createPlugin: (api: ExtractInjectionAPI<BlockControlsPlugin> | undefined, getIntl: () => IntlShape, nodeViewPortalProviderAPI: PortalProviderAPI, nodeDecorationRegistry: NodeDecorationFactory[], rightSideControlsEnabled?: boolean, quickInsertButtonEnabled?: boolean) => SafePlugin<PluginState | {
     activeDropTargetNode: ActiveDropTargetNode | undefined;
     activeNode: any;
     blockMenuOptions: {

package/dist/types/pm-plugins/sparse-surfaces.d.ts

@@ -0,0 +1,8 @@
+import { SafePlugin } from '@atlaskit/editor-common/safe-plugin';
+import type { ExtractInjectionAPI } from '@atlaskit/editor-common/types';
+import { PluginKey } from '@atlaskit/editor-prosemirror/state';
+import type { BlockControlsPlugin } from '../blockControlsPluginType';
+import { type SparseSurfacesState } from './utils/sparse-surfaces-state';
+export declare const sparseSurfacesKey: PluginKey<SparseSurfacesState>;
+/** Owns sparse anchors independently of drag/drop decorations and their lifecycle. */
+export declare const createSparseSurfacesPlugin: (api: ExtractInjectionAPI<BlockControlsPlugin> | undefined) => SafePlugin<SparseSurfacesState>;

package/dist/types/pm-plugins/utils/sparse-surface-candidates.d.ts

@@ -0,0 +1,89 @@
+import type { EditorState, ReadonlyTransaction, Transaction } from '@atlaskit/editor-prosemirror/state';
+import type { ResolvedSurface } from '@atlaskit/editor-ui-control-model/surface-renderer/types';
+import type { ActiveNode } from '../../blockControlsPluginType';
+export type SparseCandidateRange = {
+    from: number;
+    to: number;
+};
+export type SparseCandidateInvalidation = {
+    all?: boolean;
+    ids?: readonly string[];
+    positions?: readonly number[];
+    ranges?: readonly SparseCandidateRange[];
+};
+/**
+ * Viewport positions are post-transaction positions supplied by the DOM observer. The reducer
+ * never needs to inspect DOM or search document IDs for viewport discovery.
+ */
+export type SparseCandidateMeta = {
+    /** Menu/root targets may carry context distinct from global hover activeNode; map changes invalidate positions. */
+    activeNodesByPosition?: ReadonlyMap<number, ActiveNode>;
+    changedRange?: SparseCandidateRange;
+    /** Set by view reconciliation when mapping and predicate evaluation are split. */
+    documentChanged?: boolean;
+    /** Registry changes must use `invalidation: { all: true }`. */
+    invalidation?: SparseCandidateInvalidation;
+    /** Complete current set; pass [] when menu/hover protection ends. */
+    protectedPositions?: readonly number[];
+    /** Property presence is significant: `visiblePositions: []` clears visible candidates. */
+    visiblePositions?: readonly number[];
+};
+export type SparseSurfaceCandidate = {
+    contextRevision: string;
+    /** Optional stable node id, used only when matching cached invalidations. */
+    id?: string;
+    /** Persistent controls keep their candidate and DOM anchor outside the viewport. */
+    isPersistent: boolean;
+    /** PM structural sharing lets reconcile detect changed cached nodes cheaply. */
+    nodeRef: object;
+    nodeSize: number;
+    nodeType: string;
+    pos: number;
+    /** False entries stay cached, so hidden nodes are not re-preflighted on re-entry. */
+    renders: boolean;
+};
+export type SparseSurfaceCandidateState = {
+    activeRevision: string;
+    candidates: ReadonlyMap<number, SparseSurfaceCandidate>;
+    positions: readonly number[];
+    protectedPositions: readonly number[];
+    visiblePositions: readonly number[];
+};
+export type SparseSurfaceCandidateInput = {
+    activeNode?: ActiveNode | null;
+    meta?: SparseCandidateMeta;
+    newState: EditorState;
+    previousState: SparseSurfaceCandidateState;
+    resolvedSurfaces: readonly ResolvedSurface[];
+    tr: Transaction;
+};
+export declare const emptySparseSurfaceCandidateState: SparseSurfaceCandidateState;
+export type MapSparseSurfaceCandidatesInput = {
+    newState: EditorState;
+    previousState: SparseSurfaceCandidateState;
+    tr: Transaction | ReadonlyTransaction;
+};
+/** Map cache state during PM apply. This phase never calls isHidden or scans doc. */
+export declare const mapSparseSurfaceCandidates: ({ newState, previousState, tr, }: MapSparseSurfaceCandidatesInput) => SparseSurfaceCandidateState;
+export type ReconcileSparseSurfaceCandidatesInput = {
+    activeNode?: ActiveNode | null;
+    activeNodesByPosition?: ReadonlyMap<number, ActiveNode>;
+    changedRange?: SparseCandidateRange;
+    documentChanged?: boolean;
+    invalidation?: SparseCandidateInvalidation;
+    newState: EditorState;
+    protectedPositions?: readonly number[];
+    resolvedSurfaces: readonly ResolvedSurface[];
+    state: SparseSurfaceCandidateState;
+    visiblePositions?: readonly number[];
+};
+/**
+ * Reconcile after view state is current. Predicate work stays bounded to cache,
+ * exact visible positions, explicit ranges, and protected active/menu positions.
+ */
+export declare const reconcileSparseSurfaceCandidates: ({ activeNodesByPosition, activeNode, changedRange, documentChanged, invalidation, newState, protectedPositions, resolvedSurfaces, state, visiblePositions, }: ReconcileSparseSurfaceCandidatesInput) => SparseSurfaceCandidateState;
+/**
+ * Update sparse candidates. Viewport and invalidation metadata are the only
+ * discovery inputs; active changes re-evaluate retained cache, never document.
+ */
+export declare const reduceSparseSurfaceCandidates: ({ activeNode, meta, newState, previousState, resolvedSurfaces, tr, }: SparseSurfaceCandidateInput) => SparseSurfaceCandidateState;

package/dist/types/pm-plugins/utils/sparse-surfaces-mapping.d.ts

@@ -0,0 +1,20 @@
+import type { BlockControlsSurfaceInvalidation } from '@atlaskit/editor-common/block-controls/surface-candidate-invalidation';
+import type { EditorState, ReadonlyTransaction } from '@atlaskit/editor-prosemirror/state';
+import type { SparseSurfacesState } from './sparse-surfaces-state';
+export type PendingSparseSurfacesState = Pick<SparseSurfacesState, 'invalidation'>;
+export declare const reducePendingState: ({ invalidation, previous, tr, }: {
+    invalidation: BlockControlsSurfaceInvalidation | undefined;
+    previous: SparseSurfacesState;
+    tr: ReadonlyTransaction;
+}) => PendingSparseSurfacesState;
+export declare const isUnchangedTransaction: ({ pending, previous, tr, }: {
+    pending: PendingSparseSurfacesState;
+    previous: SparseSurfacesState;
+    tr: ReadonlyTransaction;
+}) => boolean;
+export declare const mapTransactionState: ({ newState, pending, previous, tr, }: {
+    newState: EditorState;
+    pending: PendingSparseSurfacesState;
+    previous: SparseSurfacesState;
+    tr: ReadonlyTransaction;
+}) => SparseSurfacesState;