@jackuait/blok 0.10.7 → 0.10.9

package/src/components/modules/blockManager/blockManager.ts

@@ -16,7 +16,9 @@ import { BlockAPI } from '../../block/api';
 import { Blocks } from '../../blocks';
 import { DATA_ATTR } from '../../constants';
 import { BlockChanged } from '../../events';
-import { generateBlockId } from '../../utils';
+import { generateBlockId, logLabeled } from '../../utils';
+import { assertHierarchy, validateHierarchy } from '../../utils/hierarchy-invariant';
+import * as Y from 'yjs';
 
 // Imported modules
 import { BlockEventBinder } from './event-binder';
@@ -324,12 +326,20 @@ export class BlockManager extends Module {
       this.bindBlockEvents.bind(this)
     );
 
-    // Initialize hierarchy with callback to sync parent data to Yjs
-    this.hierarchy = new BlockHierarchy(this.repository, (parentId) => {
-      if (!this.yjsSync.isSyncingFromYjs) {
-        this.scheduleParentSync(parentId);
-      }
-    });
+    // Initialize hierarchy with callback to sync parent data to Yjs.
+    // The third argument exposes `yjsSync.isSyncingFromYjs` lazily (yjsSync is
+    // constructed later in this ctor) so the Layer 7 dangling-parentId guard
+    // can exempt remote sync paths from throwing — a remote peer may legally
+    // deliver a transiently-dangling parent id during conflict resolution.
+    this.hierarchy = new BlockHierarchy(
+      this.repository,
+      (parentId) => {
+        if (!this.yjsSync.isSyncingFromYjs) {
+          this.scheduleParentSync(parentId);
+        }
+      },
+      () => Boolean(this.yjsSync?.isSyncingFromYjs)
+    );
 
     // Initialize operations first (before yjsSync) to allow circular dependency resolution
     this.operations = new BlockOperations(
@@ -490,6 +500,16 @@ export class BlockManager extends Module {
    * @param index - index where to insert
    */
   public insertMany(blocks: Block[], index = 0): void {
+    const blockById = new Map<string, Block>();
+
+    for (const block of blocks) {
+      blockById.set(block.id, block);
+    }
+
+    this.reconcileChildrenToParents(blocks, blockById);
+    this.reconcileParentsToChildren(blocks, blockById);
+    this.assertInsertManyHierarchy(blocks);
+
     // Load blocks into Yjs BEFORE adding to the store.
     // blocksStore.insertMany() triggers rendered() on each block, which may
     // create nested blocks (e.g., table cell paragraphs) via api.blocks.insert().
@@ -570,9 +590,14 @@ export class BlockManager extends Module {
    * @param {boolean} skipYjsSync - if true, skip syncing to Yjs (caller handles sync separately)
    * @returns {Block} inserted Block
    */
-  public insertDefaultBlockAtIndex(index: number, needToFocus = false, skipYjsSync = false): Block {
+  public insertDefaultBlockAtIndex(
+    index: number,
+    needToFocus = false,
+    skipYjsSync = false,
+    forceTopLevel = false
+  ): Block {
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
-    const result = this.operations.insertDefaultBlockAtIndex(index, needToFocus, skipYjsSync, this.blocksStore);
+    const result = this.operations.insertDefaultBlockAtIndex(index, needToFocus, skipYjsSync, this.blocksStore, forceTopLevel);
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
     return result;
   }
@@ -847,10 +872,25 @@ export class BlockManager extends Module {
 
   /**
    * Sets the parent of a block, updating both the block's parentId and the parent's contentIds.
+   *
+   * Fix 1: the Yjs-side contentIds Y.Arrays on the old and new parents must be
+   * updated in the SAME transaction as the child's parentId write. Previously,
+   * only `yblock.set('parentId', …)` was synced to Yjs, so:
+   *   - Two concurrent peers reparenting siblings would drift on both parents
+   *     because neither ever learned the move through CRDT.
+   *   - Undo snapshots captured the parentId change but left stale contentIds
+   *     on the old/new parents, so redo could restore a child that no parent
+   *     actually claimed.
+   * The companion writes keep the persistent Yjs store consistent with the
+   * in-memory hierarchy at every transaction boundary.
    * @param block - the block to reparent
    * @param newParentId - the new parent block id, or null for root level
    */
   public setBlockParent(block: Block, newParentId: string | null): void {
+    // Capture the old parent id BEFORE hierarchy.setBlockParent mutates it —
+    // we need it to remove the child from the old parent's Yjs contentIds.
+    const oldParentId = block.parentId;
+
     this.hierarchy.setBlockParent(block, newParentId);
 
     // Sync the child block's parentId to Yjs so undo/redo can restore the relationship.
@@ -868,11 +908,142 @@ export class BlockManager extends Module {
       return;
     }
 
+    // Drag-reparent path: when a move group is open (DragController wraps
+    // its drop handler in `YjsManager.transactMoves`), route the Yjs write
+    // through `transactWithoutCapture` so Y.UndoManager does not record it
+    // as a separate stack item. Attach the parent change to the in-flight
+    // move entry instead — on undo/redo we rewind both atomically.
+    if (this.Blok.YjsManager.isInMoveGroup) {
+      this.Blok.YjsManager.transactWithoutCapture(() => {
+        if (newParentId !== null) {
+          yblock.set('parentId', newParentId);
+        } else {
+          yblock.delete('parentId');
+        }
+
+        this.syncParentContentIdsToYjs(block.id, oldParentId, newParentId);
+      });
+      this.Blok.YjsManager.recordParentChangeForPendingMove(
+        block.id,
+        oldParentId,
+        newParentId
+      );
+
+      return;
+    }
+
+    // Wrap parentId + parent contentIds updates in a single Yjs transaction so
+    // they land atomically on remote peers and in the undo stack.
+    this.Blok.YjsManager.transact(() => {
+      if (newParentId !== null) {
+        yblock.set('parentId', newParentId);
+      } else {
+        yblock.delete('parentId');
+      }
+
+      this.syncParentContentIdsToYjs(block.id, oldParentId, newParentId);
+    });
+  }
+
+  /**
+   * Reparent a block in response to UndoHistory replaying a drag move.
+   *
+   * The replay path has ALREADY written the new parentId to Yjs under
+   * `transactWithoutCapture`. This method exists so UndoHistory has a
+   * stable entry point for the in-memory reparent that:
+   *   - routes through `BlockHierarchy.setBlockParent` so contentIds, DOM
+   *     placement, and indentation all stay consistent
+   *   - does NOT re-write Yjs (that would double-emit or re-enter capture)
+   * @param block - the block being reparented during move-undo/move-redo
+   * @param newParentId - the parent id to restore
+   */
+  public reparentFromHistoryReplay(block: Block, newParentId: string | null): void {
+    // Run inside withAtomicOperation so `isSyncingFromYjs` is true for the
+    // duration of the hierarchy update. This suppresses:
+    //   - `onParentChanged` → `scheduleParentSync` → a fresh Yjs write that
+    //     would land on Y.UndoManager (polluting the undo stack)
+    //   - any DOM mutation observer write-back into Yjs
+    this.yjsSync.withAtomicOperation(() => {
+      this.hierarchy.setBlockParent(block, newParentId);
+    });
+  }
+
+  /**
+   * Fix 1 helper: update the old and new parents' Yjs `contentIds` Y.Arrays
+   * so the persistent store mirrors the in-memory hierarchy after a reparent.
+   * Extracted from {@link setBlockParent} to keep block nesting shallow.
+   * @param childId - id of the block being reparented
+   * @param oldParentId - parent id before the reparent (may be null)
+   * @param newParentId - parent id after the reparent (may be null)
+   */
+  private syncParentContentIdsToYjs(
+    childId: string,
+    oldParentId: string | null,
+    newParentId: string | null
+  ): void {
+    if (oldParentId !== null && oldParentId !== newParentId) {
+      this.removeChildFromParentYContent(oldParentId, childId);
+    }
     if (newParentId !== null) {
-      yblock.set('parentId', newParentId);
-    } else {
-      yblock.delete('parentId');
+      this.appendChildToParentYContent(newParentId, childId);
+    }
+  }
+
+  /**
+   * Fix 1 helper: remove a child id from a parent block's Yjs `contentIds`
+   * Y.Array if it is present. No-op when the parent or its contentIds are
+   * missing from Yjs.
+   * @param parentId - parent block id
+   * @param childId - child block id to remove
+   */
+  private removeChildFromParentYContent(parentId: string, childId: string): void {
+    const parentYBlock = this.Blok.YjsManager.getBlockById(parentId);
+
+    if (parentYBlock === undefined) {
+      return;
+    }
+    const content = parentYBlock.get('contentIds');
+
+    if (!(content instanceof Y.Array)) {
+      return;
+    }
+    const idx = (content.toArray() as string[]).indexOf(childId);
+
+    if (idx !== -1) {
+      content.delete(idx, 1);
+    }
+  }
+
+  /**
+   * Fix 1 helper: append a child id to a parent block's Yjs `contentIds`
+   * Y.Array, creating the Y.Array on the parent yblock if missing. Inserts at
+   * the index the child occupies in the in-memory parent so remote peers see
+   * the same ordering as the local editor.
+   * @param parentId - parent block id
+   * @param childId - child block id to append
+   */
+  private appendChildToParentYContent(parentId: string, childId: string): void {
+    const parentYBlock = this.Blok.YjsManager.getBlockById(parentId);
+
+    if (parentYBlock === undefined) {
+      return;
+    }
+    const existing = parentYBlock.get('contentIds');
+    const content: Y.Array<string> = existing instanceof Y.Array
+      ? (existing as Y.Array<string>)
+      : new Y.Array<string>();
+
+    if (!(existing instanceof Y.Array)) {
+      parentYBlock.set('contentIds', content);
     }
+    if ((content.toArray()).includes(childId)) {
+      return;
+    }
+    const parentBlock = this.repository.getBlockById(parentId);
+    const memoryIndex = parentBlock !== undefined ? parentBlock.contentIds.indexOf(childId) : -1;
+    const insertAt = memoryIndex === -1 ? content.length : Math.min(memoryIndex, content.length);
+
+    content.insert(insertAt, [childId]);
   }
 
   /**
@@ -1015,6 +1186,24 @@ export class BlockManager extends Module {
    * Moves the current block up by one position
    */
   public moveCurrentBlockUp(): void {
+    /**
+     * Layer 21: block move shortcuts while a drag is in progress.
+     *
+     * Regression: "wrong block dropped" family. Cmd/Ctrl+Shift+ArrowUp routes
+     * through BlockShortcuts → this method → BlockOperations.moveCurrentBlockUp,
+     * which mutates the flat blocks array. If DragController is mid-drag (it
+     * holds live source/target Block references captured on dragstart), the
+     * array reshuffle leaves its stored indices pointing at the wrong rows
+     * and handleDrop silently drops an unrelated block.
+     *
+     * Mirrors the Cmd+Z-during-drag guard (layer 18) and the paste-during-drag
+     * guard (layer 20): swallow the shortcut so the drag completes cleanly,
+     * then the user can retry the move.
+     */
+    if (this.Blok.DragManager?.isDragging) {
+      return;
+    }
+
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
     this.operations.moveCurrentBlockUp(this.blocksStore);
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
@@ -1024,6 +1213,11 @@ export class BlockManager extends Module {
    * Moves the current block down by one position
    */
   public moveCurrentBlockDown(): void {
+    // Layer 21: see moveCurrentBlockUp above for rationale.
+    if (this.Blok.DragManager?.isDragging) {
+      return;
+    }
+
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
     this.operations.moveCurrentBlockDown(this.blocksStore);
     this._currentBlockIndex = this.operations.currentBlockIndexValue;
@@ -1099,17 +1293,137 @@ export class BlockManager extends Module {
     // Also skip if a pointer drag is active — the browser can mutate contenteditable DOM across
     // cell boundaries during a drag, and we must not write that corrupted state to Yjs.
     if (mutationType === BlockChangedMutationType && !this.yjsSync.isSyncingFromYjs && !this._isPointerDragActive) {
-      // eslint-disable-next-line no-param-reassign
-      block.lastEditedAt = Date.now();
-      // eslint-disable-next-line no-param-reassign
-      block.lastEditedBy = this.config.user?.id ?? null;
-
       void this.syncBlockDataToYjs(block);
     }
 
     return block;
   }
 
+  /**
+   * insertMany helper: fills parent.contentIds from child.parentId.
+   *
+   * Hierarchical input JSON may carry `parent` on children without a matching
+   * `content` on the parent (valid hierarchical data, but leaves the parent's
+   * contentIds empty after composeBlock). Downstream code treats
+   * `parent.contentIds` as the authoritative child list, so reconciling here
+   * makes the invariant `child.parentId ⇒ parent.contentIds.includes(child.id)`
+   * hold from the moment blocks enter the editor.
+   *
+   * If a child's parentId points to a block id that is not in the input, the
+   * parentId is cleared — matching the editor's pre-existing permissive
+   * behaviour of dropping dangling cross-references so the subsequent Fix 3
+   * `assertHierarchy` pass can run on a consistent snapshot.
+   * @param blocks - blocks being inserted
+   * @param blockById - id→block lookup built from `blocks`
+   */
+  private reconcileChildrenToParents(blocks: Block[], blockById: Map<string, Block>): void {
+    for (const block of blocks) {
+      if (block.parentId === null) {
+        continue;
+      }
+      const parent = blockById.get(block.parentId);
+
+      if (parent === undefined) {
+        // Dangling parentId: the referenced parent is missing from the input.
+        // Clear the orphan reference so the block becomes root-level instead
+        // of carrying a stale pointer into the editor state.
+        block.parentId = null;
+
+        continue;
+      }
+      if (!parent.contentIds.includes(block.id)) {
+        parent.contentIds.push(block.id);
+      }
+    }
+  }
+
+  /**
+   * Fix 2: inverse reconcile — sanitise parent.contentIds against the children.
+   *
+   * The symmetric case: a parent with `content: ['c1']` whose child c1 has no
+   * `parent` field (or points at a different parent). Child is the source of
+   * truth, because the block physically carries the back-pointer downstream.
+   * For every parent→child claim:
+   *   - child missing from the input: drop the dangling id from parent.contentIds
+   *   - child has no parentId: set child.parentId = parent.id (keep the claim)
+   *   - child has a different parentId: trust the child, sanitise the parent
+   * @param blocks - blocks being inserted
+   * @param blockById - id→block lookup built from `blocks`
+   */
+  private reconcileParentsToChildren(blocks: Block[], blockById: Map<string, Block>): void {
+    for (const block of blocks) {
+      if (block.contentIds.length === 0) {
+        continue;
+      }
+      block.contentIds = block.contentIds.filter((childId) =>
+        this.resolveChildForParent(block, childId, blockById)
+      );
+    }
+  }
+
+  /**
+   * Fix 2 helper: decide whether a parent.contentIds entry should be kept.
+   *
+   * Side effect: when a child exists and has no parentId, its parentId is set
+   * to the claiming parent id (keeping the entry in the parent's contentIds).
+   * @param parent - the parent block whose contentIds we are sanitising
+   * @param childId - candidate child id from parent.contentIds
+   * @param blockById - id→block lookup built from the insertMany input
+   * @returns true when the child id should remain in parent.contentIds
+   */
+  private resolveChildForParent(
+    parent: Block,
+    childId: string,
+    blockById: Map<string, Block>
+  ): boolean {
+    const child = blockById.get(childId);
+
+    if (child === undefined) {
+      return false;
+    }
+    if (child.parentId === null) {
+      child.parentId = parent.id;
+
+      return true;
+    }
+
+    return child.parentId === parent.id;
+  }
+
+  /**
+   * Fix 3: assert the hierarchy invariant before handing the blocks off to Yjs.
+   *
+   * Matches the saver pattern (`saver.ts:287-295`): in test and development
+   * builds, any residual drift throws loudly so the regression is caught at
+   * the point of introduction; in production we only log, so an edge-case
+   * drift never breaks user loads.
+   * @param blocks - the fully reconciled blocks about to be handed to Yjs
+   */
+  private assertInsertManyHierarchy(blocks: Block[]): void {
+    const snapshot: OutputBlockData<string, Record<string, unknown>>[] = blocks.map((block) => ({
+      id: block.id,
+      type: block.name,
+      data: {},
+      ...(block.parentId !== null && { parent: block.parentId }),
+      ...(block.contentIds.length > 0 && { content: block.contentIds }),
+    }));
+    const env = typeof process !== 'undefined' ? process.env?.NODE_ENV : undefined;
+
+    if (env === 'test' || env === 'development') {
+      assertHierarchy(snapshot, 'BlockManager.insertMany');
+
+      return;
+    }
+    const violations = validateHierarchy(snapshot);
+
+    if (violations.length === 0) {
+      return;
+    }
+    const summary = violations.map((v) => v.message).join('; ');
+
+    logLabeled(`BlockManager.insertMany produced output with hierarchy drift: ${summary}`, 'error');
+  }
+
   /**
    * Schedule a deferred sync of a parent block's data to Yjs.
    * Uses queueMicrotask to batch multiple parent changes (e.g. when initializing
@@ -1146,7 +1460,13 @@ export class BlockManager extends Module {
   }
 
   /**
-   * Sync block data to Yjs after DOM mutation
+   * Sync block data to Yjs after DOM mutation.
+   *
+   * Only writes metadata (lastEditedAt / lastEditedBy) if at least one data field
+   * actually changed. This preserves the invariant "no data change → no Yjs write →
+   * no undo entry." Without this guard, a spurious metadata-only transaction lands
+   * on the Yjs undo stack after every user operation, causing a single CMD+Z to pop
+   * only the metadata entry instead of the actual data change.
    */
   private async syncBlockDataToYjs(block: Block): Promise<void> {
     const savedData = await block.save();
@@ -1155,12 +1475,33 @@ export class BlockManager extends Module {
       return;
     }
 
-    for (const [key, value] of Object.entries(savedData.data)) {
-      this.Blok.YjsManager.updateBlockData(block.id, key, value);
-    }
+    // Wrap data + metadata writes into a single Yjs transaction. Without this,
+    // each updateBlockData / updateBlockMetadata call opens its own transaction
+    // and fires a stack-item-added event, which runs caret capture that may
+    // trigger stopCapturing() as a side effect — splitting a single logical
+    // save across multiple undo groups (so a single CMD+Z only reverts the
+    // metadata bump instead of the data change).
+    const dataChangedRef = { value: false };
+
+    this.Blok.YjsManager.transact(() => {
+      for (const [key, value] of Object.entries(savedData.data)) {
+        if (this.Blok.YjsManager.updateBlockData(block.id, key, value)) {
+          dataChangedRef.value = true;
+        }
+      }
+
+      if (!dataChangedRef.value) {
+        return;
+      }
+
+      // Bump edit metadata only when data actually changed, so we don't add
+      // a spurious metadata-only entry to the Yjs undo stack.
+      // eslint-disable-next-line no-param-reassign
+      block.lastEditedAt = Date.now();
+      // eslint-disable-next-line no-param-reassign
+      block.lastEditedBy = this.config.user?.id ?? null;
 
-    if (block.lastEditedAt !== undefined) {
       this.Blok.YjsManager.updateBlockMetadata(block.id, block.lastEditedAt, block.lastEditedBy);
-    }
+    });
   }
 }