@jackuait/blok 0.10.7 → 0.10.9

package/src/components/modules/blockManager/yjs-sync.ts

@@ -43,7 +43,7 @@ export interface SyncHandlers {
   /** Called to update block indentation */
   updateIndentation: (block: Block) => void;
   /** Called to set the parent of a block, updating contentIds and DOM placement */
-  setBlockParent: (block: Block, parentId: string) => void;
+  setBlockParent: (block: Block, parentId: string | null) => void;
   /** Called to replace a block at a specific index with a new block instance */
   replaceBlock: (index: number, newBlock: Block) => void;
   /** Called when a block is removed during undo/redo (before DOM removal) */
@@ -192,12 +192,22 @@ export class BlockYjsSync {
   }
 
   /**
-   * Subscribe to Yjs changes for undo/redo DOM synchronization
+   * Subscribe to Yjs changes for undo/redo and remote DOM synchronization.
+   *
+   * Accepts undo/redo (local-history replay) AND remote origins (changes
+   * from other clients). Local-origin events are filtered because the
+   * in-memory state was already mutated before the Yjs write landed —
+   * re-applying would thrash DOM and undo stacks.
+   *
    * @returns unsubscribe function
    */
   public subscribe(): () => void {
     return this.dependencies.YjsManager.onBlocksChanged((event: BlockChangeEvent) => {
-      if (event.origin === 'undo' || event.origin === 'redo') {
+      if (
+        event.origin === 'undo' ||
+        event.origin === 'redo' ||
+        event.origin === 'remote'
+      ) {
         this.syncBlockFromYjs(event);
       }
     });
@@ -250,6 +260,41 @@ export class BlockYjsSync {
     const lastEditedAt = yblock.get('lastEditedAt') as number | undefined;
     const lastEditedBy = (yblock.get('lastEditedBy') as string | undefined) ?? null;
 
+    /**
+     * Angle 1 fix: reconcile parentId drift BEFORE data/tunes updates.
+     *
+     * A remote client may have reparented this block (e.g. dragged it into a
+     * callout) and the Yjs record now reflects the new `parentId`, but the
+     * local mirror's `block.parentId` is stale. Without this reconciliation
+     * the next save runs hierarchy validation, finds the parent's contentIds
+     * does not list the child, and ejects the child from its parent — the
+     * same corruption family as the callout paste bug.
+     *
+     * Route through the canonical setBlockParent handler so contentIds, DOM
+     * placement, and indentation all stay consistent. Must run BEFORE any
+     * composeBlock fallback below, otherwise the replacement would carry
+     * over the stale `block.parentId`.
+     *
+     * Fix 4: distinguish "key missing" from "explicit null". A missing
+     * `parentId` key means the Yjs record has no authoritative value —
+     * treat as a no-op. Explicit null means "reparent to root".
+     *
+     * Fix 3: run the reconcile inside withAtomicOperation so
+     * isSyncingFromYjs is true for the duration. Without this, the
+     * hierarchy's onParentChanged listener echoes a fresh Yjs write,
+     * polluting the undo stack and potentially looping.
+     */
+    if (yblock.has('parentId')) {
+      const rawParentId = yblock.get('parentId') as string | null | undefined;
+      const remoteParentId: string | null = rawParentId === undefined ? null : rawParentId;
+
+      if (remoteParentId !== block.parentId) {
+        this.withAtomicOperation(() => {
+          this.handlers.setBlockParent(block, remoteParentId);
+        });
+      }
+    }
+
     // Check if tunes have changed - if so, we need to recreate the block
     // because tunes are instantiated during block construction
     const currentTunes = block.preservedTunes;

package/src/components/modules/drag/DragController.ts

@@ -32,6 +32,26 @@ export class DragController extends Module {
   private springLoader: ToggleSpringLoader = new ToggleSpringLoader();
   private listItemDescendants: ListItemDescendants | null = null;
   private boundHandlers: BoundHandlers | null = null;
+  /**
+   * Tracks the active mousedown cleanup per drag-handle element.
+   *
+   * The toolbar reuses a single settings-toggler element across blocks, so
+   * `setupDragHandle` gets called repeatedly for the same element with
+   * different `Block` references. Any stale listener from a previous block
+   * must be removed before attaching a new one — otherwise multiple
+   * listeners fire on the same mousedown and the oldest (wrong, unrelated)
+   * block wins the race inside the state machine.
+   */
+  private dragHandleCleanups: WeakMap<HTMLElement, () => void> = new WeakMap();
+
+  /**
+   * Unsubscribers returned by `Block.addDestroyCallback` for every block
+   * participating in the current drag. If any source block is destroyed
+   * mid-drag (Yjs remote update, block conversion, blockManager.update)
+   * the associated callback cancels the drag before the state machine's
+   * stale reference can reach the drop handler.
+   */
+  private sourceBlockDestroyUnsubs: Array<() => void> = [];
 
   public get isDragging(): boolean {
     return isActuallyDragging(this.stateMachine.getState());
@@ -74,7 +94,25 @@ export class DragController extends Module {
     }
   }
 
+  /**
+   * Invoked when any participating source block is destroyed mid-drag.
+   * Cancels the drag cleanly so the state machine never reaches mouseup
+   * with a stale Block reference.
+   */
+  private onSourceBlockDestroyed(): void {
+    if (!isDragActive(this.stateMachine.getState())) {
+      return;
+    }
+
+    this.cleanup(true, true);
+  }
+
   public setupDragHandle(dragHandle: HTMLElement, block: Block): () => void {
+    // Remove any previously-registered listener on this element so we never
+    // end up with two handlers racing on the same mousedown. See the comment
+    // on `dragHandleCleanups` for the failure mode this guards against.
+    this.dragHandleCleanups.get(dragHandle)?.();
+
     const onMouseDown = (e: MouseEvent): void => {
       // Only handle left mouse button
       if (e.button !== 0) {
@@ -86,14 +124,54 @@ export class DragController extends Module {
         return;
       }
 
+      /**
+       * Resolve the source block FRESH at mousedown time by reading the
+       * `data-blok-id` off the drag handle's nearest block-holder ancestor.
+       * The closure-captured `block` parameter is only a hint — the Toolbar
+       * shares ONE settings-toggler across every block and re-parents it on
+       * hover, so by the time the user presses down the handle can live in
+       * a different block than the one passed at bind time. Trusting the
+       * closure alone is the last theoretical path to "wrong block dropped";
+       * this lookup kills it. If the handle has no id ancestor (orphaned
+       * fixture in tests, or a pre-attachment race) fall back to the closure
+       * block — it's the best available reference.
+       *
+       * Zombie-id guard (Layer 8): if the handle DOES sit inside a holder
+       * with a `data-blok-id` but that id resolves to no Block (the block
+       * was destroyed and its DOM not yet reaped, or yjs deleted it
+       * mid-hover), the closure hint is almost certainly ALSO stale. Abort
+       * the drag — a known-dead id is a stronger signal than silence.
+       */
+      const holderAncestor = dragHandle.closest(`[${DATA_ATTR.id}]`);
+      const liveId = holderAncestor?.getAttribute(DATA_ATTR.id) ?? null;
+
+      if (liveId !== null) {
+        const liveBlock = this.Blok.BlockManager.getBlockById(liveId);
+
+        if (liveBlock === undefined) {
+          return;
+        }
+
+        this.startDragTracking(e, liveBlock);
+
+        return;
+      }
+
       this.startDragTracking(e, block);
     };
 
     dragHandle.addEventListener('mousedown', onMouseDown);
 
-    return (): void => {
+    const cleanup = (): void => {
       dragHandle.removeEventListener('mousedown', onMouseDown);
+      if (this.dragHandleCleanups.get(dragHandle) === cleanup) {
+        this.dragHandleCleanups.delete(dragHandle);
+      }
     };
+
+    this.dragHandleCleanups.set(dragHandle, cleanup);
+
+    return cleanup;
   }
 
   private startDragTracking(e: MouseEvent, block: Block): void {
@@ -166,6 +244,15 @@ export class DragController extends Module {
       e.clientY
     );
 
+    // Subscribe to destruction of every participating block. If any source
+    // is replaced/destroyed mid-drag, cancel the drag immediately so the
+    // state machine never holds a stale Block reference at drop time.
+    this.sourceBlockDestroyUnsubs = blocksToMove
+      .filter((b): b is Block & { addDestroyCallback: (cb: () => void) => () => void } =>
+        typeof (b as { addDestroyCallback?: unknown }).addDestroyCallback === 'function'
+      )
+      .map((b) => b.addDestroyCallback(() => this.onSourceBlockDestroyed()));
+
     // Initialize auto-scroll with scrollable container
     const scrollContainer = findScrollableAncestor(this.Blok.UI.nodes.wrapper);
     this.autoScroll = new AutoScroll(scrollContainer);
@@ -355,6 +442,43 @@ export class DragController extends Module {
     sourceBlocks: Block[],
     targetBlock: Block,
     edge: 'top' | 'bottom'
+  ): void {
+    // History integration: wrap the entire drop (array move + every
+    // subsequent `setBlockParent`) in a single `YjsManager.transactMoves`
+    // group so the user's drag lands as ONE atomic undo entry.
+    //
+    // Without this wrapper, a drag-reparent emits two independent entries
+    // on two separate history stacks — `BlockManager.move` records to the
+    // custom `moveUndoStack`, while `BlockManager.setBlockParent` writes
+    // `parentId` / `contentIds` through `YjsManager.transact('local')` which
+    // lands on the Y.UndoManager stack. `UndoHistory.undo()` pops the
+    // custom stack first and returns, so the first Cmd+Z restores the
+    // block's flat position but leaves `parentId` pointing at the new
+    // parent. A second Cmd+Z is needed to finish reversing the drag.
+    //
+    // Wrapping in `transactMoves` opens a move group AND sets the
+    // `isMoveGroupActive` flag on the YjsManager; `YjsSyncCoordinator`
+    // routes setBlockParent's Yjs writes through `transactWithoutCapture`
+    // while that flag is true, so the parent change attaches to the move
+    // entry instead of landing on Y.UndoManager as a separate stack item.
+    const yjsManager = this.Blok.YjsManager;
+
+    if (yjsManager !== undefined && typeof yjsManager.transactMoves === 'function') {
+      yjsManager.transactMoves(() => {
+        this.handleDropImpl(sourceBlock, sourceBlocks, targetBlock, edge);
+      });
+
+      return;
+    }
+
+    this.handleDropImpl(sourceBlock, sourceBlocks, targetBlock, edge);
+  }
+
+  private handleDropImpl(
+    sourceBlock: Block,
+    sourceBlocks: Block[],
+    targetBlock: Block,
+    edge: 'top' | 'bottom'
   ): void {
     const isMultiBlockDrag = sourceBlocks.length > 1;
 
@@ -364,6 +488,22 @@ export class DragController extends Module {
     }
     const result = this.operations.moveBlocks(sourceBlocks, targetBlock, edge);
 
+    // Layer 13: stale-drop abort guard.
+    //
+    // When moveBlocks aborts because the target or a source went stale mid-drag
+    // (Layer 9), it returns `{ movedBlocks: [], targetIndex: -1 }`. Everything
+    // downstream in handleDrop assumes the move succeeded:
+    //   - resolveParentForDrop reads `targetBlock.parentId` (may be stale)
+    //   - getBlockByIndex(-1) returns undefined → a11y guard catches it
+    //   - Toolbar.moveAndOpen fires on a possibly-dead source holder
+    //
+    // None of those cause wrong-block-dropped, but they leak stale state into
+    // the toolbar and a11y layers. Abort cleanly so "moveBlocks aborted" has a
+    // single, observable contract: nothing happens downstream.
+    if (result.movedBlocks.length === 0) {
+      return;
+    }
+
     // Update parent-child relationships after move
     const newParentId = this.resolveParentForDrop(targetBlock, edge, sourceBlocks);
     const movedBlockIds = new Set(result.movedBlocks.map(b => b.id));
@@ -504,24 +644,81 @@ export class DragController extends Module {
     if (!this.operations) {
       return;
     }
-    const result = await this.operations.duplicateBlocks(sourceBlocks, targetBlock, edge);
+
+    // Run the async prep (block.save() awaits + stale guards) OUTSIDE the
+    // undo group — transactForTool is a synchronous bracket and awaiting
+    // inside it would leak writes out of the group. The returned plan holds
+    // everything `applyDuplicates` needs to run its inserts + reparents
+    // synchronously inside the bracket below.
+    const prep = await this.operations.prepareDuplicates(sourceBlocks, targetBlock, edge);
+
+    if (prep.aborted) {
+      return;
+    }
+
+    // History integration: wrap the sync tail of the alt-drag — every insert
+    // from `applyDuplicates` AND the follow-up `setBlockParent` loop that
+    // reparents duplicates to the drop target — in a single
+    // `BlockManager.transactForTool` group.
+    //
+    // Without this wrapper, an alt-drag fragments into N+M independent Y.UndoManager
+    // entries (one per insert inside `applyDuplicates`, one per setBlockParent in
+    // the reparent loop), so undoing the operation requires N+M Cmd+Z presses.
+    //
+    // `transactForTool` suppresses per-insert `stopCapturing` and brackets the
+    // group with `stopCapturing` boundaries before/after — exactly the right
+    // primitive for pure-creation bursts like duplicate (whereas `transactMoves`
+    // is move-specific and not applicable here).
+    const resultRef: { current: { duplicatedBlocks: Block[]; targetIndex: number } } = {
+      current: {
+        duplicatedBlocks: [],
+        targetIndex: prep.baseInsertIndex,
+      },
+    };
+
+    const applyAndReparent = (): void => {
+      if (!this.operations) {
+        return;
+      }
+      resultRef.current = this.operations.applyDuplicates(prep);
+
+      if (resultRef.current.duplicatedBlocks.length === 0) {
+        return;
+      }
+
+      // Set parent relationships for duplicated blocks
+      const dropParentId = this.resolveParentForDrop(targetBlock, edge, sourceBlocks);
+
+      for (const dupBlock of resultRef.current.duplicatedBlocks) {
+        if (dupBlock.parentId === dropParentId) {
+          continue;
+        }
+        this.Blok.BlockManager.setBlockParent(dupBlock, dropParentId);
+      }
+    };
+
+    if (typeof this.Blok.BlockManager.transactForTool === 'function') {
+      this.Blok.BlockManager.transactForTool(applyAndReparent);
+    } else {
+      applyAndReparent();
+    }
+
+    const result = resultRef.current;
 
     if (result.duplicatedBlocks.length === 0) {
       return;
     }
 
-    // Set parent relationships for duplicated blocks
+    // Recompute the affected-parent set from the final duplicate state so
+    // toggle tools still receive their `rendered` nudge after the group
+    // closes. Only parents that actually received a duplicate need notifying.
     const newParentId = this.resolveParentForDrop(targetBlock, edge, sourceBlocks);
     const affectedParentIds = new Set<string>();
 
     for (const dupBlock of result.duplicatedBlocks) {
-      if (dupBlock.parentId === newParentId) {
-        continue;
-      }
-      if (newParentId !== null) {
+      if (dupBlock.parentId === newParentId && newParentId !== null) {
         affectedParentIds.add(newParentId);
       }
-      this.Blok.BlockManager.setBlockParent(dupBlock, newParentId);
     }
 
     // Notify affected parent blocks so toggle tools update their visual state
@@ -621,6 +818,10 @@ export class DragController extends Module {
       this.boundHandlers = null;
     }
 
+    // Drop all destroy-callback subscriptions on participating blocks.
+    this.sourceBlockDestroyUnsubs.forEach((unsub) => unsub());
+    this.sourceBlockDestroyUnsubs = [];
+
     const sourceBlock = this.stateMachine.getSourceBlock();
     this.stateMachine.reset();
 

package/src/components/modules/drag/operations/DragOperations.ts

@@ -20,6 +20,25 @@ export interface DuplicateResult {
   targetIndex: number;
 }
 
+/**
+ * Precomputed duplicate plan — all the async work (block.save() awaits,
+ * stale-reference guards) is done, leaving only synchronous Yjs writes for
+ * `applyDuplicates`. This split lets `handleDuplicate` wrap the sync tail
+ * in `BlockManager.transactForTool` so every insert + setBlockParent call
+ * collapses into one undo stack item.
+ */
+export interface DuplicatePreparation {
+  sortedBlocks: Block[];
+  sourceIds: Set<string>;
+  validResults: Array<{
+    saved: { data: Record<string, unknown>; tunes: Record<string, unknown> };
+    toolName: string;
+  }>;
+  baseInsertIndex: number;
+  /** null when pre-save stale guards aborted or post-save liveTargetIndex was -1. */
+  aborted: boolean;
+}
+
 export interface BlockManagerAdapter {
   getBlockIndex(block: Block): number;
   getBlockByIndex(index: number): Block | undefined;
@@ -71,6 +90,24 @@ export class DragOperations {
     targetBlock: Block,
     edge: 'top' | 'bottom'
   ): MoveResult {
+    // Stale-reference guard: if any source or the target has been replaced
+    // mid-drag (Yjs remote update, blockManager.update, tool conversion),
+    // getBlockIndex returns -1. Calling blockManager.move(N, -1) would invoke
+    // Array.splice(-1, 1), which removes the LAST block in the array — this
+    // is the root cause of the "completely unrelated block dropped" bug.
+    // Abort cleanly instead of silently moving the wrong block.
+    if (this.blockManager.getBlockIndex(targetBlock) === -1) {
+      return { movedBlocks: [], targetIndex: -1 };
+    }
+
+    const hasStaleSource = sourceBlocks.some(
+      (block) => this.blockManager.getBlockIndex(block) === -1
+    );
+
+    if (hasStaleSource) {
+      return { movedBlocks: [], targetIndex: -1 };
+    }
+
     if (sourceBlocks.length === 1) {
       return this.moveSingleBlock(sourceBlocks[0], targetBlock, edge);
     }
@@ -79,26 +116,57 @@ export class DragOperations {
   }
 
   /**
-   * Duplicates blocks at a new position
-   * @param sourceBlocks - Blocks to duplicate
-   * @param targetBlock - Block to insert duplicates before/after
-   * @param edge - Edge of target ('top' or 'bottom')
-   * @returns Result with duplicated blocks and target index
+   * Async phase of alt-drag duplicate. Runs all `block.save()` awaits and both
+   * stale-reference guards (Layer 11 pre-save + Layer 12 post-save), then
+   * returns a fully-computed plan. The returned plan is consumed by the
+   * synchronous {@link applyDuplicates} — that split lets callers wrap the
+   * Yjs-touching tail in a single `BlockManager.transactForTool` group so one
+   * alt-drag collapses into one undo stack item.
+   *
+   * When either stale guard trips, returns `{ aborted: true, ... }`; callers
+   * should skip `applyDuplicates` and report an empty result.
    */
-  async duplicateBlocks(
+  async prepareDuplicates(
     sourceBlocks: Block[],
     targetBlock: Block,
     edge: 'top' | 'bottom'
-  ): Promise<DuplicateResult> {
+  ): Promise<DuplicatePreparation> {
+    // Stale-reference guard (alt+drag variant of the wrong-block-dropped bug).
+    // Same failure mode as moveBlocks, different splice: targetIndex === -1
+    // produces baseInsertIndex -1 or 0, and Blocks.insert(-1, block) calls
+    // Array.splice(-1, 0, block) — inserting the block BEFORE the LAST slot.
+    // That silently diverges the flat array from the DOM, so the next move()
+    // indexOf lookup points at the wrong slot and drops an unrelated block.
+    // Abort cleanly instead of duplicating stale data at the wrong position.
+    if (this.blockManager.getBlockIndex(targetBlock) === -1) {
+      return {
+        sortedBlocks: [],
+        sourceIds: new Set(),
+        validResults: [],
+        baseInsertIndex: -1,
+        aborted: true,
+      };
+    }
+
+    const hasStaleSource = sourceBlocks.some(
+      (block) => this.blockManager.getBlockIndex(block) === -1
+    );
+
+    if (hasStaleSource) {
+      return {
+        sortedBlocks: [],
+        sourceIds: new Set(),
+        validResults: [],
+        baseInsertIndex: -1,
+        aborted: true,
+      };
+    }
+
     // Sort blocks by current index to preserve order
     const sortedBlocks = [...sourceBlocks].sort((a, b) =>
       this.blockManager.getBlockIndex(a) - this.blockManager.getBlockIndex(b)
     );
 
-    // Calculate target insertion point
-    const targetIndex = this.blockManager.getBlockIndex(targetBlock);
-    const baseInsertIndex = edge === 'top' ? targetIndex : targetIndex + 1;
-
     // Save all blocks concurrently and filter out failures
     const saveResults = await Promise.all(
       sortedBlocks.map(async (block) => {
@@ -115,21 +183,69 @@ export class DragOperations {
       })
     );
 
+    // Post-save staleness guard (Layer 12).
+    //
+    // `block.save()` is async — during those awaits, the blocks array can mutate
+    // via a Yjs remote update, undo/redo, or a tool-conversion callback. The
+    // pre-save guard above only proves the target was alive when we began; by
+    // the time Promise.all resolves, the target may be gone or at a different
+    // index.
+    //
+    // Using a pre-save `baseInsertIndex` against a mutated array would:
+    //   - insert at a stale absolute slot → divergence between flat array and DOM
+    //   - if target was destroyed: `getBlockIndex === -1` → `splice(-1, 0, block)`
+    //     inserts BEFORE the last element, same wrong-block-dropped mode as move.
+    //
+    // Always recompute from the live index after the save awaits resolve.
+    const liveTargetIndex = this.blockManager.getBlockIndex(targetBlock);
+
+    if (liveTargetIndex === -1) {
+      return {
+        sortedBlocks: [],
+        sourceIds: new Set(),
+        validResults: [],
+        baseInsertIndex: -1,
+        aborted: true,
+      };
+    }
+
+    const baseInsertIndex = edge === 'top' ? liveTargetIndex : liveTargetIndex + 1;
+
     const validResults = saveResults.filter(
       (result): result is NonNullable<typeof result> => result !== null
     );
 
-    if (validResults.length === 0) {
-      return { duplicatedBlocks: [], targetIndex: baseInsertIndex };
+    return {
+      sortedBlocks,
+      sourceIds: new Set(sortedBlocks.map((b) => b.id)),
+      validResults,
+      baseInsertIndex,
+      aborted: false,
+    };
+  }
+
+  /**
+   * Sync phase of alt-drag duplicate. Performs the inserts and re-establishes
+   * internal parent-child relationships among the duplicated set. Every Yjs
+   * write this method emits must stay synchronous so the caller can bracket
+   * the whole thing in `BlockManager.transactForTool` for a single undo entry.
+   */
+  applyDuplicates(prep: DuplicatePreparation): DuplicateResult {
+    if (prep.aborted) {
+      return { duplicatedBlocks: [], targetIndex: prep.baseInsertIndex };
+    }
+
+    if (prep.validResults.length === 0) {
+      return { duplicatedBlocks: [], targetIndex: prep.baseInsertIndex };
     }
 
     // Insert duplicated blocks
-    const duplicatedBlocks = validResults.map(({ saved, toolName }, index) =>
+    const duplicatedBlocks = prep.validResults.map(({ saved, toolName }, index) =>
       this.blockManager.insert({
         tool: toolName,
         data: saved.data,
         tunes: saved.tunes,
-        index: baseInsertIndex + index,
+        index: prep.baseInsertIndex + index,
         needToFocus: false,
       })
     );
@@ -140,17 +256,16 @@ export class DragOperations {
     // corresponding duplicate parent rather than inheriting the drop context.
     if (this.blockManager.setBlockParent !== undefined) {
       const originalIdToDupId = new Map<string, string>();
-      const sourceIds = new Set(sortedBlocks.map(b => b.id));
 
-      sortedBlocks.forEach((originalBlock, i) => {
+      prep.sortedBlocks.forEach((originalBlock, i) => {
         originalIdToDupId.set(originalBlock.id, duplicatedBlocks[i].id);
       });
 
-      sortedBlocks.forEach((originalBlock, i) => {
+      prep.sortedBlocks.forEach((originalBlock, i) => {
         const originalParentId = originalBlock.parentId;
 
         // Only reparent if the original parent is also part of the duplicated set
-        if (originalParentId !== null && sourceIds.has(originalParentId)) {
+        if (originalParentId !== null && prep.sourceIds.has(originalParentId)) {
           const dupParentId = originalIdToDupId.get(originalParentId);
 
           if (dupParentId !== undefined && this.blockManager.setBlockParent !== undefined) {
@@ -169,7 +284,25 @@ export class DragOperations {
       });
     }
 
-    return { duplicatedBlocks, targetIndex: baseInsertIndex };
+    return { duplicatedBlocks, targetIndex: prep.baseInsertIndex };
+  }
+
+  /**
+   * Duplicates blocks at a new position.
+   *
+   * Thin compatibility wrapper around {@link prepareDuplicates} and
+   * {@link applyDuplicates} — new call sites (notably `DragController.handleDuplicate`)
+   * should call those directly so the sync tail can be wrapped in
+   * `BlockManager.transactForTool` for single-undo semantics.
+   */
+  async duplicateBlocks(
+    sourceBlocks: Block[],
+    targetBlock: Block,
+    edge: 'top' | 'bottom'
+  ): Promise<DuplicateResult> {
+    const prep = await this.prepareDuplicates(sourceBlocks, targetBlock, edge);
+
+    return this.applyDuplicates(prep);
   }
 
   /**