build: first round of blast radius

Author: nperez0111

packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.ts

@@ -177,6 +177,7 @@ const mergeBlocks = (
     }
 
     // Save suggestion node content before reconstruction
+    // drops prev suggestionBefore and next suggestionAfter on merge
     const savedPrevSuggAfter = currentPrevInfo.suggestionAfter
       ? currentPrevInfo.suggestionAfter.node.copy(
           currentPrevInfo.suggestionAfter.node.content,
@@ -236,6 +237,7 @@ const mergeBlocks = (
     }
 
     // Create the new blockContainer with the prev block's ID and attributes
+    // create() skips validation; bad child order ships silently
     const newBlockContainer = currentPrevInfo.bnBlock.node.type.create(
       currentPrevInfo.bnBlock.node.attrs,
       newChildren,

packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts

@@ -106,6 +106,7 @@ function updateBlockSelectionFromData(
       anchorBlockPos + data.headCellOffset,
     );
   } else if (data.type === "node") {
+    // +1 assumes blockContent is first child; may be a leading suggestion node
     selection = NodeSelection.create(tr.doc, anchorBlockPos + 1);
   } else {
     const headBlockPos = getNodeById(data.headBlockId, tr.doc)?.posBeforeNode;

packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.ts

@@ -39,6 +39,7 @@ function sinkItem(
   if (nodeBefore.type !== itemType) {
     return false;
   }
+  // lastChild may be a trailing suggestion node, not blockGroup
   const nestedBefore =
     nodeBefore.lastChild && nodeBefore.lastChild.type === groupType; // change 2
   const inner = Fragment.from(nestedBefore ? itemType.create() : null);
@@ -102,6 +103,7 @@ function liftToOuterList(
     // There are siblings after the lifted items, which must become
     // children of the last item
     const blockBeingLifted = range.parent.child(range.endIndex - 1);
+    // lastChild may be a trailing suggestion node, not blockGroup
     const nestedAfter =
       blockBeingLifted.lastChild &&
       blockBeingLifted.lastChild.type === groupType; // change 2

packages/core/src/api/blockManipulation/commands/replaceBlocks/util/fixColumnList.ts

@@ -18,6 +18,7 @@ export function isEmptyColumn(column: Node) {
     throw new Error("Invalid column: does not have child node.");
   }
 
+  // firstChild may be a suggestion node; childCount===1 below assumes no suggestions
   const blockContent = blockContainer.firstChild;
   if (!blockContent) {
     throw new Error("Invalid blockContainer: does not have child node.");

packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.ts

@@ -47,6 +47,7 @@ export const splitBlockTr = (
   // with the first block and the split happens at the blockContent boundary.
   let effectivePos = posInBlock;
   const $pos = tr.doc.resolve(posInBlock);
+  // dead guard — group is compound "suggestionBlockContent blockContent", never ===
   if ($pos.parent.type.spec.group === "suggestionBlockContent") {
     effectivePos = info.blockContent.beforePos + 1;
   }

packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts

@@ -127,6 +127,7 @@ export function updateBlockTr<
     // currently, we calculate the new node and replace the entire node with the desired new node.
     // for this, we do a nodeToBlock on the existing block to get the children.
     // it would be cleaner to use a ReplaceAroundStep, but this is a bit simpler and it's quite an edge case
+    // nodeToBlock→blockToNode round-trip drops suggestion nodes
     const existingBlock = nodeToBlock(blockInfo.bnBlock.node, pmSchema);
     const replacementNode = blockToNode(
       {
@@ -302,6 +303,7 @@ function updateChildren<
         throw new Error("impossible");
       }
       // Inserts a new blockGroup containing the child nodes created earlier.
+      // inserts blockGroup before trailing suggestion, invalid content order
       tr.insert(
         blockInfo.blockContent.afterPos,
         pmSchema.nodes["blockGroup"].createChecked({}, childNodes),

packages/core/src/api/blockManipulation/getBlock/getBlock.ts

@@ -22,6 +22,7 @@ export function getBlock<
     typeof blockIdentifier === "string" ? blockIdentifier : blockIdentifier.id;
   const pmSchema = getPmSchema(doc);
 
+  // suggested-deleted blocks resolve as live, no deletion flag
   const posInfo = getNodeById(id, doc);
   if (!posInfo) {
     return undefined;

packages/core/src/api/clipboard/toClipboard/copyExtension.ts

@@ -50,6 +50,7 @@ function fragmentToExternalHTML<
         (child) =>
           child.type.isInGroup("bnBlock") ||
           child.type.name === "blockGroup" ||
+          // === "blockContent" misclassifies suggestion nodes (compound group)
           child.type.spec.group === "blockContent",
       ) === undefined;
     if (isWithinBlockContent) {
@@ -118,16 +119,19 @@ export function selectedFragmentToHTML<
   // selected, e.g. an image block.
   if (
     "node" in view.state.selection &&
+    // === "blockContent" misclassifies suggestion nodes (compound group)
     (view.state.selection.node as Node).type.spec.group === "blockContent"
   ) {
     editor.transact((tr) =>
+      // from-1 block expansion assumes blockContent adjacency; off with leading suggestion node
       tr.setSelection(
         new NodeSelection(tr.doc.resolve(view.state.selection.from - 1)),
       ),
     );
   }
 
   // Uses default ProseMirror clipboard serialization.
+  // serializeForClipboard emits shadow nodes; paste re-creates them
   const clipboardHTML: string = view.serializeForClipboard(
     view.state.selection.content(),
   ).dom.innerHTML;
@@ -268,6 +272,7 @@ export const createCopyToClipboardExtension = <
 
                 // Expands the selection to the parent `blockContainer` node.
                 editor.transact((tr) =>
+                  // from-1 block expansion assumes blockContent adjacency; off with leading suggestion node
                   tr.setSelection(
                     new NodeSelection(
                       tr.doc.resolve(view.state.selection.from - 1),

packages/core/src/api/exporters/markdown/htmlToMarkdown.ts

@@ -45,6 +45,7 @@ function serializeChildren(node: Node, ctx: SerializeContext): string {
 }
 
 function serializeNode(node: Node, ctx: SerializeContext): string {
+  // no data-suggestion handling; shadow text duplicated to markdown
   if (node.nodeType === 3 /* Node.TEXT_NODE */) {
     return node.textContent || "";
   }

packages/core/src/api/getBlockInfoFromPos.ts

@@ -191,6 +191,7 @@ export function getBlockInfoWithManualOffset(
           afterPos: suggestionAfterPos,
         };
 
+        // singular suggestionBefore/After, schema allows suggestionBlockContent*
         if (!foundBlockContent) {
           suggestionBefore = info;
         } else {