@jackuait/blok 0.10.8 → 0.10.9

package/src/components/modules/yjs/block-observer.ts

@@ -1,9 +1,11 @@
 import * as Y from 'yjs';
 
-import type {
-  BlockChangeEvent,
-  BlockChangeCallback,
-  TransactionOrigin,
+import {
+  LOCAL_ORIGIN_TAGS,
+  type BlockChangeEvent,
+  type BlockChangeCallback,
+  type LocalOriginTag,
+  type TransactionOrigin,
 } from './types';
 
 /**
@@ -66,34 +68,64 @@ export class BlockObserver {
 
   /**
    * Map transaction origin to event origin.
+   *
+   * Input shapes:
+   *  - `Y.UndoManager` instance → `'undo'` or `'redo'`
+   *  - `LocalOriginTag` string  → mapped by the exhaustive switch below
+   *  - anything else            → `'remote'` (treated as a peer update)
+   *
+   * IMPORTANT: the switch is exhaustive over `LOCAL_ORIGIN_TAGS`. Adding a
+   * new tag there without teaching this switch is a compile error via the
+   * `satisfies never` guard, and the enumeration test in
+   * `block-observer.test.ts` catches any runtime drift. Do not add a local
+   * origin tag that silently falls through to `'remote'` — that is the
+   * exact bug class that broke `ensureCellHasBlock` → table row deletion.
    */
   public mapTransactionOrigin(origin: unknown): TransactionOrigin {
-    if (origin === 'local') {
-      return 'local';
-    }
-
-    if (origin === 'load') {
-      return 'load';
-    }
-
     if (this.undoManager && origin === this.undoManager) {
       return this.undoManager.undoing ? 'undo' : 'redo';
     }
 
-    // Handle custom move origins for our application-level move undo/redo
-    if (origin === 'move') {
-      return 'local';
+    if (!this.isLocalOriginTag(origin)) {
+      return 'remote';
     }
 
-    if (origin === 'move-undo') {
-      return 'undo';
-    }
-
-    if (origin === 'move-redo') {
-      return 'redo';
+    switch (origin) {
+      case 'local':
+        return 'local';
+      case 'load':
+        return 'load';
+      // `no-capture` is used by `DocumentStore.transactWithoutCapture` for
+      // local writes that must bypass the undo stack (auto-repair inserts,
+      // drag-move parent rewrites replayed by undo/redo, etc). They are
+      // LOCAL authoring writes — mapping them to `'remote'` would make
+      // `BlockYjsSync` call `setData(staleYjsData)` on the authoring block
+      // mid-operation and wipe any in-memory state the tool had written
+      // ahead of Yjs (e.g. Table's local model after `model.addRow()`).
+      case 'no-capture':
+        return 'local';
+      case 'move':
+        return 'local';
+      case 'move-undo':
+        return 'undo';
+      case 'move-redo':
+        return 'redo';
+      default: {
+        const _exhaustive: never = origin;
+
+        return _exhaustive;
+      }
     }
+  }
 
-    return 'remote';
+  /**
+   * Type guard for known local-authored origin tags.
+   */
+  private isLocalOriginTag(value: unknown): value is LocalOriginTag {
+    return (
+      typeof value === 'string' &&
+      (LOCAL_ORIGIN_TAGS as readonly string[]).includes(value)
+    );
   }
 
   /**
@@ -210,13 +242,33 @@ export class BlockObserver {
   }
 
   /**
-   * Handle map-level changes (data update).
+   * Handle map-level changes (data update, tunes update, or top-level
+   * yblock key changes like `parentId` / `contentIds`).
+   *
+   * When a remote client reparents a block, the changed Y.Map is the
+   * yblock itself — not a nested `data`/`tunes` sub-map. Detect both
+   * cases so we always emit an update event for the affected block id.
    */
   private handleMapEvent(ymap: Y.Map<unknown>, origin: TransactionOrigin): void {
     if (this.yblocks === null) {
       return;
     }
 
+    // Direct yblock change (e.g. parentId/contentIds written on the yblock itself).
+    if (this.isTopLevelYblock(ymap)) {
+      const id: unknown = ymap.get('id');
+
+      if (typeof id === 'string') {
+        this.emitChange({
+          type: 'update',
+          blockId: id,
+          origin,
+        });
+      }
+
+      return;
+    }
+
     const yblock = this.findParentBlock(ymap);
 
     if (yblock === undefined) {
@@ -230,6 +282,18 @@ export class BlockObserver {
     });
   }
 
+  /**
+   * Returns true if the given Y.Map is one of the top-level yblocks tracked
+   * in the blocks array.
+   */
+  private isTopLevelYblock(ymap: Y.Map<unknown>): boolean {
+    if (this.yblocks === null) {
+      return false;
+    }
+
+    return this.yblocks.toArray().includes(ymap);
+  }
+
   /**
    * Find the parent block Y.Map for a nested Y.Map (data or tunes).
    */

package/src/components/modules/yjs/document-store.ts

@@ -1,7 +1,7 @@
 import * as Y from 'yjs';
 
 import type { YBlockSerializer, YjsOutputBlockData } from './serializer';
-import type { TransactionOrigin } from './types';
+import type { LocalOriginTag } from './types';
 import { equals } from '../../utils/object';
 
 // Re-export YjsOutputBlockData as DocumentStoreBlockData for consistency
@@ -17,9 +17,15 @@ type DocumentStoreBlockData = YjsOutputBlockData;
  */
 export class DocumentStore {
   /**
-   * Yjs document instance
+   * Yjs document instance.
+   *
+   * PRIVATE by design: all writes MUST route through `transact` or
+   * `transactWithoutCapture` so the origin passes the `LocalOriginTag`
+   * type barrier. Exposing the raw Y.Doc lets callers bypass the
+   * whitelist and silently reintroduce the class of bugs that
+   * `BlockObserver.mapTransactionOrigin` exists to prevent.
    */
-  public readonly ydoc: Y.Doc = new Y.Doc();
+  private readonly ydoc: Y.Doc = new Y.Doc();
 
   /**
    * Yjs array containing all blocks
@@ -97,7 +103,11 @@ export class DocumentStore {
    * @param toIndex - Target index (the final position where the block should end up)
    * @param origin - Transaction origin
    */
-  public moveBlock(id: string, toIndex: number, origin: TransactionOrigin): void {
+  public moveBlock(
+    id: string,
+    toIndex: number,
+    origin: 'local' | 'move-undo' | 'move-redo'
+  ): void {
     const fromIndex = this.findBlockIndex(id);
 
     if (fromIndex === -1) {
@@ -112,7 +122,7 @@ export class DocumentStore {
     // Use the origin for the transaction:
     // - 'local' for user-initiated moves (we use 'move' so Yjs UndoManager doesn't track them)
     // - 'move-undo' / 'move-redo' for our custom undo/redo (maps to 'undo'/'redo' for DOM sync)
-    const transactionOrigin = origin === 'local' ? 'move' : origin;
+    const transactionOrigin: LocalOriginTag = origin === 'local' ? 'move' : origin;
 
     this.transact(() => {
       const yblock = this.yblocks.get(fromIndex);
@@ -150,12 +160,14 @@ export class DocumentStore {
    * @param id - Block id
    * @param key - Data property key
    * @param value - New value
+   * @returns true if a Yjs write actually occurred (value changed), false if the
+   *          equality guard short-circuited the write.
    */
-  public updateBlockData(id: string, key: string, value: unknown): void {
+  public updateBlockData(id: string, key: string, value: unknown): boolean {
     const yblock = this.getBlockById(id);
 
     if (yblock === undefined) {
-      return;
+      return false;
     }
 
     const ydata = yblock.get('data') as Y.Map<unknown>;
@@ -166,12 +178,14 @@ export class DocumentStore {
     // (e.g., marker updates in list items during undo/redo, or table content
     // arrays that are reference-different but structurally identical)
     if (equals(currentValue, value)) {
-      return;
+      return false;
     }
 
     this.transact(() => {
       ydata.set(key, value);
     }, 'local');
+
+    return true;
   }
 
   /**
@@ -199,11 +213,21 @@ export class DocumentStore {
    * @param lastEditedAt - Timestamp in milliseconds
    * @param lastEditedBy - User ID, or null
    */
-  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): void {
+  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): boolean {
     const yblock = this.getBlockById(id);
 
     if (yblock === undefined) {
-      return;
+      return false;
+    }
+
+    // Defensive equality guard — if both fields already match, skip the write to avoid
+    // adding an empty/no-op entry to the Yjs undo stack.
+    const currentEditedAt = yblock.get('lastEditedAt');
+    const currentEditedBy = yblock.get('lastEditedBy');
+    const editedByMatches = lastEditedBy === null || currentEditedBy === lastEditedBy;
+
+    if (currentEditedAt === lastEditedAt && editedByMatches) {
+      return false;
     }
 
     this.transact(() => {
@@ -213,6 +237,8 @@ export class DocumentStore {
         yblock.set('lastEditedBy', lastEditedBy);
       }
     }, 'local');
+
+    return true;
   }
 
   /**
@@ -230,7 +256,7 @@ export class DocumentStore {
    * @param fn - Function containing Yjs operations to execute atomically
    * @param origin - Transaction origin
    */
-  public transact(fn: () => void, origin: TransactionOrigin): void {
+  public transact(fn: () => void, origin: LocalOriginTag): void {
     this.ydoc.transact(fn, origin);
   }
 

package/src/components/modules/yjs/index.ts

@@ -43,10 +43,23 @@ export class YjsManager extends Module {
   private blockObserver: BlockObserver;
 
   /**
-   * Flag to track if move group is active
+   * Flag to track if move group is active.
+   *
+   * Read via the `isInMoveGroup` getter by `BlockManager.setBlockParent`,
+   * which routes its Yjs writes through `transactWithoutCapture` while this
+   * flag is true so the parent change attaches to the in-flight move entry
+   * instead of landing on Y.UndoManager as a separate stack item.
    */
   private isMoveGroupActive = false;
 
+  /**
+   * Whether a drag-backed move group is currently open.
+   * See `isMoveGroupActive`.
+   */
+  public get isInMoveGroup(): boolean {
+    return this.isMoveGroupActive;
+  }
+
   /**
    * Constructor - initializes all components
    */
@@ -67,6 +80,42 @@ export class YjsManager extends Module {
       this.documentStore.moveBlock(blockId, toIndex, origin);
     });
 
+    // Set up parent-restore callback — invoked by UndoHistory during
+    // move-undo/move-redo on drag-reparent entries.
+    //
+    // Writes parentId (and the two parents' contentIds) to Yjs under
+    // `transactWithoutCapture` so Y.UndoManager does not record the replay
+    // as a new stack item, then drives the in-memory BlockManager reparent
+    // directly via `reparentFromHistoryReplay`. Going direct avoids the
+    // `handleYjsUpdate` path's parentId-delete blind spot (that handler
+    // gates reconciliation on `yblock.has('parentId')` which is false after
+    // a delete, so a non-root → root undo would otherwise silently skip).
+    this.undoHistory.setParentRestoreCallback((blockId, parentId) => {
+      const yblock = this.documentStore.getBlockById(blockId);
+
+      if (yblock === undefined) {
+        return;
+      }
+
+      this.documentStore.transactWithoutCapture(() => {
+        if (parentId !== null) {
+          yblock.set('parentId', parentId);
+        } else {
+          yblock.delete('parentId');
+        }
+      });
+
+      const blockManager = this.Blok?.BlockManager;
+
+      if (blockManager !== undefined) {
+        const block = blockManager.getBlockById(blockId);
+
+        if (block !== undefined) {
+          blockManager.reparentFromHistoryReplay(block, parentId);
+        }
+      }
+    });
+
     // Set up observation
     this.blockObserver.observe(this.documentStore.yblocks, this.undoHistory.undoManager);
   }
@@ -148,10 +197,10 @@ export class YjsManager extends Module {
    * @param key - Data property key
    * @param value - New value
    */
-  public updateBlockData(id: string, key: string, value: unknown): void {
+  public updateBlockData(id: string, key: string, value: unknown): boolean {
     this.undoHistory.markCaretBeforeChange();
 
-    this.documentStore.updateBlockData(id, key, value);
+    return this.documentStore.updateBlockData(id, key, value);
   }
 
   /**
@@ -170,8 +219,8 @@ export class YjsManager extends Module {
    * @param lastEditedAt - Timestamp in milliseconds
    * @param lastEditedBy - User ID, or null
    */
-  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): void {
-    this.documentStore.updateBlockMetadata(id, lastEditedAt, lastEditedBy);
+  public updateBlockMetadata(id: string, lastEditedAt: number, lastEditedBy: string | null): boolean {
+    return this.documentStore.updateBlockMetadata(id, lastEditedAt, lastEditedBy);
   }
 
   /**
@@ -259,8 +308,35 @@ export class YjsManager extends Module {
    */
   public transactMoves(fn: () => void): void {
     this.isMoveGroupActive = true;
-    this.undoHistory.transactMoves(fn);
-    this.isMoveGroupActive = false;
+    try {
+      this.undoHistory.transactMoves(fn);
+    } finally {
+      this.isMoveGroupActive = false;
+    }
+  }
+
+  /**
+   * Attach a parent change to the in-flight move entry so `undo`/`redo`
+   * restores the block's parent atomically with its position.
+   *
+   * Called from `BlockManager.setBlockParent` when a drag-backed move group
+   * is open (see `isInMoveGroup`). The accompanying Yjs parentId write must
+   * use `transactWithoutCapture` — otherwise Y.UndoManager records it as a
+   * separate stack item and the drag splits into a two-step undo.
+   * @param blockId - id of the block being reparented
+   * @param fromParentId - parent id before the reparent (null for root)
+   * @param toParentId - parent id after the reparent (null for root)
+   */
+  public recordParentChangeForPendingMove(
+    blockId: string,
+    fromParentId: string | null,
+    toParentId: string | null
+  ): void {
+    this.undoHistory.recordParentChangeForPendingMove(
+      blockId,
+      fromParentId,
+      toParentId
+    );
   }
 
   /**

package/src/components/modules/yjs/types.ts

@@ -10,8 +10,9 @@ export type BlockChangeEvent =
   | { type: 'batch-add'; blockIds: string[]; origin: TransactionOrigin };
 
 /**
- * Transaction origin types.
- * Includes 'move' and 'move-undo'/'move-redo' for custom move handling.
+ * Transaction origin types AFTER classification by
+ * `BlockObserver.mapTransactionOrigin`. This is what downstream consumers
+ * (e.g. `BlockYjsSync`) see on a `BlockChangeEvent`.
  */
 export type TransactionOrigin =
   | 'local'
@@ -23,6 +24,30 @@ export type TransactionOrigin =
   | 'move-undo'
   | 'move-redo';
 
+/**
+ * Whitelist of raw origin tags that our own code passes to `Y.Doc.transact`.
+ *
+ * Adding a new local-authored origin tag? You MUST:
+ *   1. Add it here.
+ *   2. Handle it explicitly in `BlockObserver.mapTransactionOrigin`.
+ *
+ * The mapper's exhaustiveness check and the `block-observer.test.ts`
+ * enumeration test will otherwise fail CI — preventing a repeat of the
+ * table-row-removal bug where `'no-capture'` silently fell through to
+ * `'remote'` and made `BlockYjsSync` clobber the authoring tool's state
+ * with stale Yjs data mid-operation.
+ */
+export const LOCAL_ORIGIN_TAGS = [
+  'local',
+  'load',
+  'no-capture',
+  'move',
+  'move-undo',
+  'move-redo',
+] as const;
+
+export type LocalOriginTag = (typeof LOCAL_ORIGIN_TAGS)[number];
+
 /**
  * Callback for block change events
  */
@@ -47,11 +72,19 @@ export interface CaretHistoryEntry {
 
 /**
  * Represents a single move operation within a move group.
+ *
+ * Drag-reparent flows attach `fromParentId`/`toParentId` so that undo/redo
+ * can restore the parent relationship atomically alongside the array move.
+ * Without this, a drag-reparent splits across two history stacks
+ * (`moveUndoStack` for the array move, Y.UndoManager for the parentId write)
+ * and requires two Cmd+Z presses to fully reverse.
  */
 export interface SingleMoveEntry {
   blockId: string;
   fromIndex: number;
   toIndex: number;
+  fromParentId?: string | null;
+  toParentId?: string | null;
 }
 
 /**

package/src/components/modules/yjs/undo-history.ts

@@ -102,6 +102,15 @@ export class UndoHistory {
    */
   private moveCallback: (blockId: string, toIndex: number, origin: 'local' | 'move-undo' | 'move-redo') => void;
 
+  /**
+   * Callback to restore a block's parent during move-undo/move-redo.
+   *
+   * Must not record its own history entry — the call is part of replaying
+   * an existing `SingleMoveEntry`. Set by YjsManager to route through
+   * `transactWithoutCapture` + a direct in-memory reparent.
+   */
+  private parentRestoreCallback: (blockId: string, parentId: string | null) => void;
+
   constructor(
     yblocks: Y.Array<Y.Map<unknown>>,
     blok: BlokModules
@@ -120,6 +129,9 @@ export class UndoHistory {
     this.moveCallback = () => {
       // Placeholder, will be set by setMoveCallback
     };
+    this.parentRestoreCallback = () => {
+      // Placeholder, will be set by setParentRestoreCallback
+    };
   }
 
   /**
@@ -131,6 +143,16 @@ export class UndoHistory {
     this.moveCallback = callback;
   }
 
+  /**
+   * Set the parent-restore callback used by move-undo/move-redo to rewind
+   * drag-reparent side effects. See `parentRestoreCallback`.
+   */
+  public setParentRestoreCallback(
+    callback: (blockId: string, parentId: string | null) => void
+  ): void {
+    this.parentRestoreCallback = callback;
+  }
+
   /**
    * Set the Blok modules. Called when Blok modules are initialized.
    */
@@ -216,10 +238,14 @@ export class UndoHistory {
       // Push to redo stack for potential redo
       this.moveRedoStack.push(lastMoveGroup);
 
-      // Reverse all moves in the group, in reverse order
-      // This is crucial for multi-block moves to restore correctly
+      // Reverse all moves in the group, in reverse order.
+      // This is crucial for multi-block moves to restore correctly.
+      //
+      // Drag-reparent entries may additionally carry `fromParentId`; restore
+      // the parent BEFORE the position so the block lands in the correct
+      // flat-array slot relative to its (soon-to-be-restored) parent siblings.
       [...lastMoveGroup].reverse().forEach((move) => {
-        this.moveCallback(move.blockId, move.fromIndex, 'move-undo');
+        this.replayMoveUndo(move);
       });
 
       // Pop caret entry only after move succeeds
@@ -257,9 +283,12 @@ export class UndoHistory {
       // Push back to undo stack
       this.moveUndoStack.push(lastMoveGroup);
 
-      // Redo all moves in the group, in original order
+      // Redo all moves in the group, in original order. Drag-reparent
+      // entries restore the destination parent AFTER the position so that
+      // the flat-array splice settles first and the parent's contentIds
+      // then re-attach cleanly.
       for (const move of lastMoveGroup) {
-        this.moveCallback(move.blockId, move.toIndex, 'move-redo');
+        this.replayMoveRedo(move);
       }
 
       // Pop caret entry only after move succeeds
@@ -307,6 +336,36 @@ export class UndoHistory {
     this.restoreCaretSnapshot(snapshot);
   }
 
+  /**
+   * Replay a single move entry in the undo direction.
+   * Parent restore runs BEFORE the position restore so the block lands in
+   * the correct slot relative to its (soon-to-be-restored) parent siblings.
+   */
+  private replayMoveUndo(move: SingleMoveEntry): void {
+    if (move.fromParentId !== undefined) {
+      this.parentRestoreCallback(move.blockId, move.fromParentId);
+    }
+
+    if (move.fromIndex !== -1) {
+      this.moveCallback(move.blockId, move.fromIndex, 'move-undo');
+    }
+  }
+
+  /**
+   * Replay a single move entry in the redo direction.
+   * Position restore runs BEFORE the parent restore so the flat-array splice
+   * settles first and the destination parent's contentIds re-attach cleanly.
+   */
+  private replayMoveRedo(move: SingleMoveEntry): void {
+    if (move.toIndex !== -1) {
+      this.moveCallback(move.blockId, move.toIndex, 'move-redo');
+    }
+
+    if (move.toParentId !== undefined) {
+      this.parentRestoreCallback(move.blockId, move.toParentId);
+    }
+  }
+
   /**
    * Execute a Yjs UndoManager operation with the isPerformingUndoRedo flag set.
    * This prevents the stack-item-added listener from modifying caret stacks during
@@ -438,6 +497,58 @@ export class UndoHistory {
     }
   }
 
+  /**
+   * Attach a parent change to the in-flight move entry (or create a
+   * parent-only entry if the block hasn't been moved inside the group yet).
+   *
+   * Used by drag-reparent so that `undo` restores the parent relationship
+   * atomically with the array move. The caller (`BlockManager.setBlockParent`
+   * when `YjsManager.isInMoveGroup` is true) is responsible for writing the
+   * parentId/contentIds to Yjs through `transactWithoutCapture` so the
+   * Y.UndoManager does not also record the change.
+   * @param blockId - id of the reparented block
+   * @param fromParentId - parent id before the reparent (null for root)
+   * @param toParentId - parent id after the reparent (null for root)
+   */
+  public recordParentChangeForPendingMove(
+    blockId: string,
+    fromParentId: string | null,
+    toParentId: string | null
+  ): void {
+    if (this.pendingMoveGroup === null) {
+      // Not inside a move group — nothing to attach to. Drop the hint.
+      return;
+    }
+
+    const existing = this.pendingMoveGroup.find(
+      entry => entry.blockId === blockId
+    );
+
+    if (existing !== undefined) {
+      // Preserve the earliest known `fromParentId` (first write wins — that's
+      // the parent BEFORE the drag started). Always update `toParentId` to
+      // the most recent write.
+      if (existing.fromParentId === undefined) {
+        existing.fromParentId = fromParentId;
+      }
+      existing.toParentId = toParentId;
+
+      return;
+    }
+
+    // No matching move entry yet (e.g. a same-index reparent within a toggle
+    // body, where DragController calls setBlockParent without a prior move).
+    // Push a parent-only entry with identical from/to indices so the undo
+    // walker still has something to unwind.
+    this.pendingMoveGroup.push({
+      blockId,
+      fromIndex: -1,
+      toIndex: -1,
+      fromParentId,
+      toParentId,
+    });
+  }
+
   /**
    * Capture the current caret position as a snapshot.
    * @returns CaretSnapshot or null if no block is focused