@jackuait/blok 0.6.0-beta.8 → 0.6.0

package/src/tools/table/index.ts

@@ -9,21 +9,31 @@ import type {
 import type { ToolSanitizerConfig } from '../../../types/configs/sanitizer-config';
 import { DATA_ATTR } from '../../components/constants';
 import { IconTable } from '../../components/icons';
+import { mapToNearestPresetColor } from '../../components/utils/color-mapping';
 import { twMerge } from '../../components/utils/tw';
 
 import { TableAddControls } from './table-add-controls';
-import { TableCellBlocks } from './table-cell-blocks';
+import { TableCellBlocks, CELL_BLOCKS_ATTR } from './table-cell-blocks';
+import {
+  serializeCellsToClipboard,
+  buildClipboardHtml,
+  buildClipboardPlainText,
+  parseClipboardHtml,
+  parseGenericHtmlTable,
+  isDefaultBlack,
+} from './table-cell-clipboard';
+import type { CellColorMode } from './table-cell-color-picker';
 import { TableCellSelection } from './table-cell-selection';
-import { TableGrid } from './table-core';
+import { TableGrid, ROW_ATTR, CELL_ATTR } from './table-core';
 import {
+  applyCellColors,
   applyPixelWidths,
   computeHalfAvgWidth,
   computeInitialColWidth,
-  deleteColumnWithBlockCleanup,
-  deleteRowWithBlockCleanup,
   enableScrollOverflow,
   getBlockIdsInColumn,
   getBlockIdsInRow,
+  getCellPosition,
   isColumnEmpty,
   isRowEmpty,
   mountCellBlocksReadOnly,
@@ -35,12 +45,15 @@ import {
   updateHeadingColumnStyles,
   updateHeadingStyles,
 } from './table-operations';
+import { TableModel } from './table-model';
 import { TableResize } from './table-resize';
 import { executeRowColAction } from './table-row-col-action-handler';
 import type { PendingHighlight } from './table-row-col-action-handler';
 import { TableRowColControls } from './table-row-col-controls';
 import type { RowColAction } from './table-row-col-controls';
-import type { TableData, TableConfig } from './types';
+import { registerAdditionalRestrictedTools } from './table-restrictions';
+import { TableScrollHaze } from './table-scroll-haze';
+import type { ClipboardBlockData, LegacyCellContent, TableCellsClipboard, TableData, TableConfig } from './types';
 
 const DEFAULT_ROWS = 3;
 const DEFAULT_COLS = 3;
@@ -52,6 +65,12 @@ const WRAPPER_CLASSES = [
 
 const WRAPPER_EDIT_CLASSES = [
   'relative',
+  'after:content-[""]',
+  'after:absolute',
+  'after:-bottom-10',
+  'after:left-0',
+  'after:right-0',
+  'after:h-10',
 ];
 
 /**
@@ -62,25 +81,134 @@ export class Table implements BlockTool {
   private api: API;
   private readOnly: boolean;
   private config: TableConfig;
-  private data: TableData;
+  private initialContent: LegacyCellContent[][] | null = null;
   private grid: TableGrid;
+  private model: TableModel;
   private resize: TableResize | null = null;
   private addControls: TableAddControls | null = null;
   private rowColControls: TableRowColControls | null = null;
   private cellBlocks: TableCellBlocks | null = null;
   private cellSelection: TableCellSelection | null = null;
+  private scrollHaze: TableScrollHaze | null = null;
   private element: HTMLDivElement | null = null;
+  private gridElement: HTMLElement | null = null;
+  private scrollContainer: HTMLDivElement | null = null;
+  private gripOverlay: HTMLDivElement | null = null;
   private blockId: string | undefined;
   private pendingHighlight: PendingHighlight | null = null;
   private isNewTable = false;
+  private unregisterRestrictedTools: (() => void) | null = null;
+
+  /**
+   * Generation counter for setData calls.
+   * Incremented at the start of each setData; checked before expensive operations
+   * (DOM rebuild, initializeCells) to bail out if a newer call has started.
+   * Prevents orphaned blocks when rapid undo/redo triggers overlapping setData calls.
+   */
+  private setDataGeneration = 0;
+
+  /**
+   * Depth counter for structural operations (add/delete/move row/col).
+   * When > 0, TableCellBlocks defers handleBlockMutation events to prevent
+   * event cascade corruption during multi-step structural changes.
+   */
+  private structuralOpDepth = 0;
 
   constructor({ data, config, api, readOnly, block }: BlockToolConstructorOptions<TableData, TableConfig>) {
     this.api = api;
     this.readOnly = readOnly;
     this.config = config ?? {};
-    this.data = normalizeTableData(data, config ?? {});
+    const normalized = normalizeTableData(data, this.config);
+
+    this.initialContent = normalized.content;
     this.grid = new TableGrid({ readOnly });
+    this.model = new TableModel(normalized);
     this.blockId = block?.id;
+
+    if (this.config.restrictedTools !== undefined) {
+      this.unregisterRestrictedTools = registerAdditionalRestrictedTools(this.config.restrictedTools);
+    }
+  }
+
+  /**
+   * Execute a function within a structural operation lock.
+   * While active, block-changed events are deferred in TableCellBlocks.
+   *
+   * @param fn - The structural operation to execute
+   * @param discard - If true, discard deferred events (for full rebuilds like setData/onPaste).
+   *                  If false (default), replay deferred events after the operation.
+   */
+  private runStructuralOp<T>(fn: () => T, discard = false): T {
+    this.structuralOpDepth++;
+
+    try {
+      return fn();
+    } finally {
+      this.structuralOpDepth--;
+
+      const shouldFlush = this.structuralOpDepth === 0;
+
+      if (shouldFlush && discard) {
+        this.cellBlocks?.discardDeferredEvents();
+      }
+      if (shouldFlush && !discard) {
+        this.cellBlocks?.flushDeferredEvents();
+      }
+    }
+  }
+
+  /**
+   * Execute a structural operation within a Yjs transaction.
+   * Combines the structural op lock (event deferral) with Yjs undo grouping.
+   * Used for interactive operations that should be a single undo entry.
+   *
+   * @param fn - The structural operation to execute
+   * @param discard - If true, discard deferred events (forwarded to runStructuralOp)
+   */
+  private runTransactedStructuralOp<T>(fn: () => T, discard = false): T {
+    if (!this.api.blocks.transact) {
+      return this.runStructuralOp(fn, discard);
+    }
+
+    const ref = { current: undefined as T | undefined };
+
+    this.api.blocks.transact(() => {
+      ref.current = this.runStructuralOp(fn, discard);
+    });
+
+    return ref.current as T;
+  }
+
+  /**
+   * Tear down all visual subsystems (resize, add-controls, row/col-controls,
+   * cell-selection). Called before DOM rebuild in setData/onPaste and during
+   * destroy(). Does NOT tear down cellBlocks — that has special Yjs handling.
+   */
+  private teardownSubsystems(): void {
+    this.resize?.destroy();
+    this.resize = null;
+    this.addControls?.destroy();
+    this.addControls = null;
+    this.rowColControls?.destroy();
+    this.rowColControls = null;
+    this.cellSelection?.destroy();
+    this.cellSelection = null;
+    this.scrollHaze?.destroy();
+    this.scrollHaze = null;
+  }
+
+  /**
+   * Initialize all visual subsystems on a grid element.
+   * Shared by rendered(), setData(), and onPaste() to ensure consistent
+   * subsystem initialization order.
+   */
+  private initSubsystems(gridEl: HTMLElement): void {
+    this.initResize(gridEl);
+    this.initAddControls(gridEl);
+    this.initRowColControls(gridEl);
+    this.initCellSelection(gridEl);
+    this.initGridPasteListener(gridEl);
+    this.initScrollHaze();
   }
 
   public static get toolbox(): ToolboxConfig {
@@ -118,40 +246,95 @@ export class Table implements BlockTool {
     };
   }
 
+  /**
+   * Ensure a scroll container exists between the wrapper and the grid.
+   * Creates one on demand (e.g. when the first resize converts percent → pixel mode).
+   */
+  private ensureScrollContainer(): HTMLDivElement {
+    if (this.scrollContainer) {
+      return this.scrollContainer;
+    }
+
+    const sc = document.createElement('div');
+
+    sc.setAttribute('data-blok-table-scroll', '');
+
+    const grid = this.gridElement;
+
+    if (grid && this.element) {
+      this.element.insertBefore(sc, grid);
+      sc.appendChild(grid);
+    }
+
+    this.scrollContainer = sc;
+
+    return sc;
+  }
+
   public render(): HTMLDivElement {
     const wrapper = document.createElement('div');
 
-    wrapper.className = twMerge(WRAPPER_CLASSES, !this.readOnly && WRAPPER_EDIT_CLASSES, this.data.colWidths && SCROLL_OVERFLOW_CLASSES);
+    wrapper.className = twMerge(WRAPPER_CLASSES, !this.readOnly && WRAPPER_EDIT_CLASSES);
     wrapper.setAttribute(DATA_ATTR.tool, 'table');
 
     if (this.readOnly) {
       wrapper.setAttribute('data-blok-table-readonly', '');
     }
 
-    this.isNewTable = this.data.content.length === 0;
+    this.isNewTable = (this.initialContent?.length ?? 0) === 0;
+
+    const rows = this.initialContent?.length || this.config.rows || DEFAULT_ROWS;
+    const cols = this.initialContent?.reduce((max, row) => Math.max(max, row?.length ?? 0), 0) || this.config.cols || DEFAULT_COLS;
+
+    const gridEl = this.grid.createGrid(rows, cols, this.model.colWidths);
+
+    if ((this.initialContent?.length ?? 0) > 0) {
+      this.grid.fillGrid(gridEl, this.initialContent ?? []);
+    }
+
+    if (this.model.colWidths) {
+      applyPixelWidths(gridEl, this.model.colWidths);
+    }
+
+    this.gridElement = gridEl;
 
-    const rows = this.data.content.length || this.config.rows || DEFAULT_ROWS;
-    const cols = this.data.content[0]?.length || this.config.cols || DEFAULT_COLS;
+    if (this.model.colWidths || !this.readOnly) {
+      const sc = document.createElement('div');
 
-    const gridEl = this.grid.createGrid(rows, cols, this.data.colWidths);
+      sc.setAttribute('data-blok-table-scroll', '');
 
-    if (this.data.content.length > 0) {
-      this.grid.fillGrid(gridEl, this.data.content);
+      const overflowClasses = this.model.colWidths ? SCROLL_OVERFLOW_CLASSES : [];
+
+      sc.classList.add(...overflowClasses);
+
+      sc.appendChild(gridEl);
+      wrapper.appendChild(sc);
+      this.scrollContainer = sc;
+    } else {
+      wrapper.appendChild(gridEl);
+      this.scrollContainer = null;
     }
 
-    if (this.data.colWidths) {
-      applyPixelWidths(gridEl, this.data.colWidths);
+    if (!this.readOnly) {
+      const overlay = document.createElement('div');
+
+      overlay.setAttribute('data-blok-table-grip-overlay', '');
+      overlay.style.position = 'absolute';
+      overlay.style.inset = '0';
+      overlay.style.pointerEvents = 'none';
+      overlay.style.zIndex = '3';
+      wrapper.appendChild(overlay);
+      this.gripOverlay = overlay;
     }
 
-    wrapper.appendChild(gridEl);
     this.element = wrapper;
 
-    if (this.data.withHeadings) {
-      updateHeadingStyles(this.element, this.data.withHeadings);
+    if (this.model.withHeadings) {
+      updateHeadingStyles(this.gridElement, this.model.withHeadings);
     }
 
-    if (this.data.withHeadingColumn) {
-      updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
+    if (this.model.withHeadingColumn) {
+      updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
     }
 
     if (!this.readOnly) {
@@ -163,40 +346,63 @@ export class Table implements BlockTool {
   }
 
   public rendered(): void {
-    if (!this.element) {
+    if (!this.element || this.initialContent === null) {
       return;
     }
 
-    const gridEl = this.element.firstElementChild as HTMLElement;
+    const gridEl = this.gridElement;
 
     if (!gridEl) {
       return;
     }
 
+    const content = this.initialContent;
+
+    this.initialContent = null;
+
     if (this.readOnly) {
-      mountCellBlocksReadOnly(gridEl, this.data.content, this.api);
+      mountCellBlocksReadOnly(gridEl, content, this.api, this.blockId ?? '');
+      applyCellColors(gridEl, this.model.snapshot().content);
+      this.initScrollHaze();
 
       return;
     }
 
-    this.data.content = this.cellBlocks?.initializeCells(this.data.content) ?? this.data.content;
+    this.runTransactedStructuralOp(() => {
+      const initializedContent = this.cellBlocks?.initializeCells(content) ?? content;
 
-    if (this.isNewTable) {
-      populateNewCells(gridEl, this.cellBlocks);
-    }
+      // When a new table is created with empty content, the DOM grid already has
+      // the correct dimensions but the model has zero rows. Pre-populate the
+      // model with an empty grid so populateNewCells can sync blocks via
+      // addBlockToCell (which requires valid row/col bounds).
+      const contentForModel = this.isNewTable && initializedContent.length === 0
+        ? Array.from(gridEl.querySelectorAll(`[${ROW_ATTR}]`), (row) => {
+          const cellCount = row.querySelectorAll(`[${CELL_ATTR}]`).length;
+
+          return Array.from({ length: cellCount }, () => ({ blocks: [] as string[] }));
+        })
+        : initializedContent;
+
+      this.model.replaceAll({
+        ...this.model.snapshot(),
+        content: contentForModel,
+      });
 
-    if (this.data.initialColWidth === undefined) {
-      const widths = this.data.colWidths ?? readPixelWidths(gridEl);
+      if (this.isNewTable) {
+        populateNewCells(gridEl, this.cellBlocks);
+      }
+    }, true);
 
-      this.data.initialColWidth = widths.length > 0
+    if (this.model.initialColWidth === undefined) {
+      const widths = this.model.colWidths ?? readPixelWidths(gridEl);
+
+      this.model.setInitialColWidth(widths.length > 0
         ? computeInitialColWidth(widths)
-        : undefined;
+        : undefined);
     }
 
-    this.initResize(gridEl);
-    this.initAddControls(gridEl);
-    this.initRowColControls(gridEl);
-    this.initCellSelection(gridEl);
+    this.initSubsystems(gridEl);
+    applyCellColors(gridEl, this.model.snapshot().content);
 
     if (this.isNewTable) {
       const firstEditable = gridEl.querySelector<HTMLElement>('[contenteditable="true"]');
@@ -205,42 +411,173 @@ export class Table implements BlockTool {
     }
   }
 
-  public save(blockContent: HTMLElement): TableData {
-    const gridEl = blockContent.firstElementChild as HTMLElement;
-    const colWidths = this.data.colWidths;
-    const content = this.readOnly
-      ? this.data.content
-      : this.grid.getData(gridEl);
-
-    return {
-      withHeadings: this.data.withHeadings,
-      withHeadingColumn: this.data.withHeadingColumn,
-      stretched: this.data.stretched,
-      content,
-      ...(colWidths ? { colWidths } : {}),
-      ...(this.data.initialColWidth !== undefined ? { initialColWidth: this.data.initialColWidth } : {}),
-    };
+  public save(_blockContent: HTMLElement): TableData {
+    return this.model.snapshot();
   }
 
   public validate(savedData: TableData): boolean {
     return savedData.content.length > 0;
   }
 
+  /**
+   * Update table with new data in-place (used by undo/redo).
+   * Follows the onPaste() pattern: delete old blocks, re-render, reinitialize.
+   */
+  public setData(newData: Partial<TableData>): void {
+    this.setDataGeneration++;
+    const currentGeneration = this.setDataGeneration;
+
+    const normalized = normalizeTableData(
+      {
+        ...this.model.snapshot(),
+        ...newData,
+      } as TableData,
+      this.config
+    );
+
+    this.initialContent = normalized.content;
+    this.model.replaceAll(normalized);
+
+    // Only delete cell blocks during normal updates, not Yjs undo/redo.
+    // During Yjs sync, the child cell blocks are managed by Yjs and will be
+    // reattached via mountBlocksInCell(). Deleting them here would destroy
+    // the block data that Yjs is restoring, causing empty cells after undo.
+    if (!this.api.blocks.isSyncingFromYjs) {
+      this.runStructuralOp(() => {
+        this.cellBlocks?.deleteAllBlocks();
+      }, true);
+    }
+
+    this.cellBlocks?.destroy();
+
+    const oldElement = this.element;
+
+    if (!oldElement?.parentNode) {
+      return;
+    }
+
+    // If a newer setData call has started, bail out. The newer call will
+    // handle the full DOM rebuild and block initialization, so continuing
+    // here would create blocks that the newer call immediately orphans.
+    if (currentGeneration !== this.setDataGeneration) {
+      return;
+    }
+
+    const savedSelectionRange = this.cellSelection?.getSelectedRange() ?? null;
+    const savedGripIndices = this.rowColControls?.getVisibleGripIndices() ?? null;
+
+    this.teardownSubsystems();
+
+    const newElement = this.render();
+
+    oldElement.parentNode.replaceChild(newElement, oldElement);
+
+    const gridEl = this.gridElement;
+
+    if (!gridEl) {
+      return;
+    }
+
+    if (this.readOnly) {
+      applyCellColors(gridEl, this.model.snapshot().content);
+
+      return;
+    }
+
+    // Check generation before initializeCells — if a re-entrant setData
+    // was triggered during render() or replaceChild(), bail out.
+    if (currentGeneration !== this.setDataGeneration) {
+      return;
+    }
+
+    this.runStructuralOp(() => {
+      const setDataContent = this.cellBlocks?.initializeCells(this.initialContent ?? []) ?? this.initialContent ?? [];
+
+      // Check generation after initializeCells — if a re-entrant setData
+      // was triggered during block insertion inside initializeCells, bail
+      // out to avoid overwriting the newer call's model and controls.
+      if (currentGeneration !== this.setDataGeneration) {
+        return;
+      }
+
+      // When undoing reverts content to empty, the grid has default dimensions
+      // but initializeCells([]) mounted zero blocks. Pre-populate the model
+      // with empty cell entries so populateNewCells can place blocks correctly.
+      if (this.api.blocks.isSyncingFromYjs && setDataContent.length === 0 && gridEl) {
+        const emptyGridContent = Array.from(gridEl.querySelectorAll(`[${ROW_ATTR}]`), (row) => {
+          const cellCount = row.querySelectorAll(`[${CELL_ATTR}]`).length;
+
+          return Array.from({ length: cellCount }, () => ({ blocks: [] as string[] }));
+        });
+
+        this.model.replaceAll({
+          ...this.model.snapshot(),
+          content: emptyGridContent,
+        });
+
+        populateNewCells(gridEl, this.cellBlocks);
+      } else {
+        this.model.replaceAll({
+          ...this.model.snapshot(),
+          content: setDataContent,
+        });
+      }
+
+      this.initialContent = null;
+    }, true);
+
+    if (currentGeneration !== this.setDataGeneration) {
+      return;
+    }
+
+    this.initSubsystems(gridEl);
+
+    if (savedSelectionRange !== null && this.cellSelection !== null) {
+      this.cellSelection.selectRange(savedSelectionRange);
+    }
+
+    if (savedGripIndices !== null && this.rowColControls !== null) {
+      this.rowColControls.restoreVisibleGrips(savedGripIndices.col, savedGripIndices.row);
+    }
+
+    applyCellColors(gridEl, this.model.snapshot().content);
+  }
+
   public onPaste(event: HTMLPasteEvent): void {
     const content = event.detail.data;
     const rows = content.querySelectorAll('tr');
     const tableContent: string[][] = [];
+    const cellColors: Array<Array<{ color?: string; textColor?: string }>> = [];
 
     rows.forEach(row => {
       const cells = row.querySelectorAll('td, th');
       const rowData: string[] = [];
+      const rowColors: Array<{ color?: string; textColor?: string }> = [];
 
       cells.forEach(cell => {
         rowData.push(cell.innerHTML);
+
+        const style = cell.getAttribute('style') ?? '';
+        const entry: { color?: string; textColor?: string } = {};
+
+        const bgMatch = /background-color\s*:\s*([^;]+)/i.exec(style);
+
+        if (bgMatch?.[1]) {
+          entry.color = mapToNearestPresetColor(bgMatch[1].trim(), 'bg');
+        }
+
+        const textMatch = /(?<![a-z-])color\s*:\s*([^;]+)/i.exec(style);
+
+        if (textMatch?.[1] && !isDefaultBlack(textMatch[1].trim())) {
+          entry.textColor = mapToNearestPresetColor(textMatch[1].trim(), 'text');
+        }
+
+        rowColors.push(entry);
       });
 
       if (rowData.length > 0) {
         tableContent.push(rowData);
+        cellColors.push(rowColors);
       }
     });
 
@@ -248,61 +585,109 @@ export class Table implements BlockTool {
     const hasThHeadings = rows[0]?.querySelector('th') !== null;
     const withHeadings = hasTheadHeadings || hasThHeadings;
 
-    this.data = {
-      withHeadings,
-      withHeadingColumn: this.data.withHeadingColumn,
-      stretched: this.data.stretched,
-      content: tableContent,
-    };
+    this.initialContent = tableContent;
+    this.model.setWithHeadings(withHeadings);
+    this.model.setWithHeadingColumn(false);
+    this.model.setColWidths(undefined);
 
-    if (!this.element?.parentNode) {
+    this.runStructuralOp(() => {
+      this.cellBlocks?.deleteAllBlocks();
+    }, true);
+    this.cellBlocks?.destroy();
+    this.teardownSubsystems();
+
+    const oldElement = this.element;
+
+    if (!oldElement?.parentNode) {
       return;
     }
 
     const newElement = this.render();
 
-    this.element.parentNode.replaceChild(newElement, this.element);
-    this.element = newElement;
+    oldElement.parentNode.replaceChild(newElement, oldElement);
 
-    const gridEl = this.element.firstElementChild as HTMLElement;
+    const gridEl = this.gridElement;
 
     if (!this.readOnly && gridEl) {
-      this.initResize(gridEl);
-      this.initAddControls(gridEl);
-      this.initRowColControls(gridEl);
+      this.runStructuralOp(() => {
+        const pasteContent = this.cellBlocks?.initializeCells(this.initialContent ?? []) ?? this.initialContent ?? [];
+
+        this.model.replaceAll({
+          ...this.model.snapshot(),
+          content: pasteContent,
+        });
+        this.initialContent = null;
+
+        // Apply cell colors extracted from td/th style attributes
+        cellColors.forEach((rowColors, r) => {
+          rowColors.forEach((colors, c) => {
+            if (colors.color !== undefined) {
+              this.model.setCellColor(r, c, colors.color);
+            }
+
+            if (colors.textColor !== undefined) {
+              this.model.setCellTextColor(r, c, colors.textColor);
+            }
+          });
+        });
+      }, true);
+
+      this.initSubsystems(gridEl);
+      applyCellColors(gridEl, this.model.snapshot().content);
     }
   }
 
   public destroy(): void {
-    this.cellBlocks?.deleteAllBlocks();
+    this.unregisterRestrictedTools?.();
+    this.unregisterRestrictedTools = null;
+
+    // Only delete cell blocks during normal removal, not Yjs undo.
+    // When the table is removed via Yjs undo, its child cell blocks are managed
+    // by Yjs and will be restored during redo. Deleting them here would make
+    // redo create empty paragraphs instead of restoring the original content.
+    if (!this.api.blocks.isSyncingFromYjs) {
+      this.cellBlocks?.deleteAllBlocks();
+    }
 
-    this.resize?.destroy();
-    this.resize = null;
-    this.addControls?.destroy();
-    this.addControls = null;
-    this.rowColControls?.destroy();
-    this.rowColControls = null;
+    this.teardownSubsystems();
     this.cellBlocks?.destroy();
     this.cellBlocks = null;
-    this.cellSelection?.destroy();
-    this.cellSelection = null;
+    this.gridElement = null;
+    this.scrollContainer = null;
     this.element = null;
   }
 
   public deleteRowWithCleanup(rowIndex: number): void {
-    const gridEl = this.element?.firstElementChild as HTMLElement | undefined;
+    const gridEl = this.gridElement;
 
-    if (gridEl) {
-      deleteRowWithBlockCleanup(gridEl, rowIndex, this.grid, this.cellBlocks);
+    if (!gridEl) {
+      return;
     }
+
+    this.runTransactedStructuralOp(() => {
+      const { blocksToDelete } = this.model.deleteRow(rowIndex);
+
+      this.cellBlocks?.deleteBlocks(blocksToDelete);
+      this.grid.deleteRow(gridEl, rowIndex);
+    });
   }
 
   public deleteColumnWithCleanup(colIndex: number): void {
-    const gridEl = this.element?.firstElementChild as HTMLElement | undefined;
+    const gridEl = this.gridElement;
 
-    if (gridEl) {
-      this.data.colWidths = deleteColumnWithBlockCleanup(gridEl, colIndex, this.data.colWidths, this.grid, this.cellBlocks);
+    if (!gridEl) {
+      return;
     }
+
+    this.runTransactedStructuralOp(() => {
+      // model.deleteColumn() already removes the width at colIndex from
+      // colWidthsValue internally, so no additional syncColWidthsAfterDeleteColumn
+      // call is needed — that would double-delete.
+      const { blocksToDelete } = this.model.deleteColumn(colIndex);
+
+      this.cellBlocks?.deleteBlocks(blocksToDelete);
+      this.grid.deleteColumn(gridEl, colIndex);
+    });
   }
 
   public getBlockIdsInRow(rowIndex: number): string[] {
@@ -327,34 +712,44 @@ export class Table implements BlockTool {
       grid: gridEl,
       i18n: this.api.i18n,
       getNewColumnWidth: () => {
-        const colWidths = this.data.colWidths ?? readPixelWidths(gridEl);
+        const colWidths = this.model.colWidths ?? readPixelWidths(gridEl);
 
-        return this.data.initialColWidth !== undefined
-          ? Math.round((this.data.initialColWidth / 2) * 100) / 100
+        return this.model.initialColWidth !== undefined
+          ? Math.round((this.model.initialColWidth / 2) * 100) / 100
           : computeHalfAvgWidth(colWidths);
       },
       onAddRow: () => {
-        this.grid.addRow(gridEl);
-        populateNewCells(gridEl, this.cellBlocks);
-        updateHeadingStyles(this.element, this.data.withHeadings);
-        updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
-        this.initResize(gridEl);
-        this.addControls?.syncRowButtonWidth();
-        this.rowColControls?.refresh();
+        this.runTransactedStructuralOp(() => {
+          this.grid.addRow(gridEl);
+          this.model.addRow();
+          populateNewCells(gridEl, this.cellBlocks);
+          updateHeadingStyles(this.gridElement, this.model.withHeadings);
+          updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+          this.initResize(gridEl);
+          this.addControls?.syncRowButtonWidth();
+          this.rowColControls?.refresh();
+        });
       },
       onAddColumn: () => {
-        const colWidths = this.data.colWidths ?? readPixelWidths(gridEl);
-        const halfWidth = this.data.initialColWidth !== undefined
-          ? Math.round((this.data.initialColWidth / 2) * 100) / 100
-          : computeHalfAvgWidth(colWidths);
-
-        this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
-        this.data.colWidths = [...colWidths, halfWidth];
-        populateNewCells(gridEl, this.cellBlocks);
-        updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
-        this.initResize(gridEl);
-        this.addControls?.syncRowButtonWidth();
-        this.rowColControls?.refresh();
+        this.runTransactedStructuralOp(() => {
+          const colWidths = this.model.colWidths ?? readPixelWidths(gridEl);
+          const halfWidth = this.model.initialColWidth !== undefined
+            ? Math.round((this.model.initialColWidth / 2) * 100) / 100
+            : computeHalfAvgWidth(colWidths);
+
+          this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
+          this.model.addColumn(undefined, halfWidth);
+          this.model.setColWidths([...colWidths, halfWidth]);
+          populateNewCells(gridEl, this.cellBlocks);
+          updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+          this.initResize(gridEl);
+          this.addControls?.syncRowButtonWidth();
+          this.rowColControls?.refresh();
+
+          if (this.scrollContainer) {
+            this.scrollContainer.scrollLeft = this.scrollContainer.scrollWidth;
+          }
+        });
       },
       onDragStart: () => {
         if (this.resize) {
@@ -364,61 +759,83 @@ export class Table implements BlockTool {
         this.rowColControls?.setGripsDisplay(false);
       },
       onDragAddRow: () => {
-        this.grid.addRow(gridEl);
-        populateNewCells(gridEl, this.cellBlocks);
-        updateHeadingStyles(this.element, this.data.withHeadings);
-        updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
+        this.runTransactedStructuralOp(() => {
+          this.grid.addRow(gridEl);
+          this.model.addRow();
+          populateNewCells(gridEl, this.cellBlocks);
+          updateHeadingStyles(this.gridElement, this.model.withHeadings);
+          updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+        });
       },
       onDragRemoveRow: () => {
-        const rowCount = this.grid.getRowCount(gridEl);
+        this.runTransactedStructuralOp(() => {
+          const rowCount = this.grid.getRowCount(gridEl);
 
-        if (rowCount > 1 && isRowEmpty(gridEl, rowCount - 1)) {
-          deleteRowWithBlockCleanup(gridEl, rowCount - 1, this.grid, this.cellBlocks);
-        }
+          if (rowCount > 1 && isRowEmpty(gridEl, rowCount - 1)) {
+            const { blocksToDelete } = this.model.deleteRow(rowCount - 1);
+
+            this.cellBlocks?.deleteBlocks(blocksToDelete);
+            this.grid.deleteRow(gridEl, rowCount - 1);
+          }
+        });
       },
       onDragAddCol: () => {
-        const colWidths = this.data.colWidths ?? readPixelWidths(gridEl);
-        const halfWidth = this.data.initialColWidth !== undefined
-          ? Math.round((this.data.initialColWidth / 2) * 100) / 100
-          : computeHalfAvgWidth(colWidths);
-
-        this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
-        this.data.colWidths = [...colWidths, halfWidth];
-        applyPixelWidths(gridEl, this.data.colWidths);
-        populateNewCells(gridEl, this.cellBlocks);
-        updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
-        this.initResize(gridEl);
-
-        dragState.addedCols++;
-
-        if (this.element) {
-          this.element.scrollLeft = this.element.scrollWidth;
-        }
+        this.runTransactedStructuralOp(() => {
+          const colWidths = this.model.colWidths ?? readPixelWidths(gridEl);
+          const halfWidth = this.model.initialColWidth !== undefined
+            ? Math.round((this.model.initialColWidth / 2) * 100) / 100
+            : computeHalfAvgWidth(colWidths);
+
+          const newWidths = [...colWidths, halfWidth];
+
+          this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
+          this.model.addColumn(undefined, halfWidth);
+          this.model.setColWidths(newWidths);
+          applyPixelWidths(gridEl, newWidths);
+          populateNewCells(gridEl, this.cellBlocks);
+          updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+          this.initResize(gridEl);
+
+          dragState.addedCols++;
+
+          if (this.scrollContainer) {
+            this.scrollContainer.scrollLeft = this.scrollContainer.scrollWidth;
+          }
+        });
       },
       onDragRemoveCol: () => {
-        const colCount = this.grid.getColumnCount(gridEl);
+        this.runTransactedStructuralOp(() => {
+          const colCount = this.grid.getColumnCount(gridEl);
 
-        if (colCount <= 1 || !isColumnEmpty(gridEl, colCount - 1)) {
-          return;
-        }
+          if (colCount <= 1 || !isColumnEmpty(gridEl, colCount - 1)) {
+            return;
+          }
 
-        this.data.colWidths = deleteColumnWithBlockCleanup(gridEl, colCount - 1, this.data.colWidths, this.grid, this.cellBlocks);
+          // model.deleteColumn() already removes the width internally,
+          // so no additional syncColWidthsAfterDeleteColumn is needed.
+          const { blocksToDelete } = this.model.deleteColumn(colCount - 1);
 
-        if (this.data.colWidths) {
-          applyPixelWidths(gridEl, this.data.colWidths);
-        }
+          this.cellBlocks?.deleteBlocks(blocksToDelete);
+          this.grid.deleteColumn(gridEl, colCount - 1);
 
-        this.initResize(gridEl);
+          const updatedWidths = this.model.colWidths;
 
-        dragState.addedCols--;
+          if (updatedWidths) {
+            applyPixelWidths(gridEl, updatedWidths);
+          }
+
+          this.initResize(gridEl);
+
+          dragState.addedCols--;
+        });
       },
       onDragEnd: () => {
         this.initResize(gridEl);
         this.addControls?.syncRowButtonWidth();
         this.rowColControls?.refresh();
 
-        if (this.element) {
-          this.element.scrollLeft = dragState.addedCols > 0 ? this.element.scrollWidth : 0;
+        if (this.scrollContainer) {
+          this.scrollContainer.scrollLeft = dragState.addedCols > 0 ? this.scrollContainer.scrollWidth : 0;
         }
 
         dragState.addedCols = 0;
@@ -435,10 +852,12 @@ export class Table implements BlockTool {
 
     this.rowColControls = new TableRowColControls({
       grid: gridEl,
+      overlay: this.gripOverlay ?? undefined,
+      scrollContainer: this.scrollContainer ?? undefined,
       getColumnCount: () => this.grid.getColumnCount(gridEl),
       getRowCount: () => this.grid.getRowCount(gridEl),
-      isHeadingRow: () => this.data.withHeadings,
-      isHeadingColumn: () => this.data.withHeadingColumn,
+      isHeadingRow: () => this.model.withHeadings,
+      isHeadingColumn: () => this.model.withHeadingColumn,
       i18n: this.api.i18n,
       onAction: (action: RowColAction) => this.handleRowColAction(gridEl, action),
       onDragStateChange: (isDragging: boolean) => {
@@ -465,6 +884,10 @@ export class Table implements BlockTool {
 
           this.pendingHighlight = null;
 
+          // Lock the grip synchronously so the unlock listener is registered
+          // before any external click can race with a deferred RAF
+          this.rowColControls?.setActiveGrip(type, index);
+
           // Wait for layout so newly inserted cells have dimensions
           requestAnimationFrame(() => {
             if (type === 'row') {
@@ -472,8 +895,6 @@ export class Table implements BlockTool {
             } else {
               this.cellSelection?.selectColumn(index);
             }
-
-            this.rowColControls?.setActiveGrip(type, index);
           });
         } else {
           this.cellSelection?.clearActiveSelection();
@@ -483,62 +904,139 @@ export class Table implements BlockTool {
   }
 
   private handleRowColAction(gridEl: HTMLElement, action: RowColAction): void {
-    const result = executeRowColAction(
-      gridEl,
-      action,
-      { grid: this.grid, data: this.data, cellBlocks: this.cellBlocks },
-    );
+    const generationAtStart = this.setDataGeneration;
 
-    this.data.colWidths = result.colWidths;
-    this.data.withHeadings = result.withHeadings;
-    this.data.withHeadingColumn = result.withHeadingColumn;
-    this.pendingHighlight = result.pendingHighlight;
+    this.runTransactedStructuralOp(() => {
+      if (generationAtStart !== this.setDataGeneration || this.gridElement !== gridEl) {
+        return;
+      }
 
-    updateHeadingStyles(this.element, this.data.withHeadings);
-    updateHeadingColumnStyles(this.element, this.data.withHeadingColumn);
-    this.initResize(gridEl);
-    this.addControls?.syncRowButtonWidth();
-    this.rowColControls?.refresh();
+      // Capture colWidths BEFORE the model mutation so the action handler
+      // receives pre-mutation widths. Model methods (addColumn, deleteColumn,
+      // moveColumn) update colWidths internally, and the handler functions
+      // (syncColWidthsAfterMove, syncColWidthsAfterDeleteColumn, computeInsertColumnWidths)
+      // also transform widths — passing post-mutation widths would double-apply
+      // the transformation.
+      const colWidthsBeforeMutation = this.model.colWidths;
+
+      // Sync model structural operation before DOM changes
+      const { blocksToDelete } = this.syncModelForAction(action);
+
+      const result = executeRowColAction(
+        gridEl,
+        action,
+        {
+          grid: this.grid,
+          data: {
+            colWidths: colWidthsBeforeMutation,
+            withHeadings: this.model.withHeadings,
+            withHeadingColumn: this.model.withHeadingColumn,
+            initialColWidth: this.model.initialColWidth,
+          },
+          cellBlocks: this.cellBlocks,
+          blocksToDelete,
+        },
+      );
+
+      if (generationAtStart !== this.setDataGeneration || this.gridElement !== gridEl) {
+        return;
+      }
 
-    if (!result.moveSelection) {
-      return;
-    }
+      this.model.setColWidths(result.colWidths);
+      this.model.setWithHeadings(result.withHeadings);
+      this.model.setWithHeadingColumn(result.withHeadingColumn);
+      this.pendingHighlight = result.pendingHighlight;
 
-    // After move operations, select the moved row/column to show where it landed
-    const { type: moveType, index: moveIndex } = result.moveSelection;
+      updateHeadingStyles(this.gridElement, this.model.withHeadings);
+      updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+      this.initResize(gridEl);
+      this.addControls?.syncRowButtonWidth();
 
-    if (moveType === 'row') {
-      this.cellSelection?.selectRow(moveIndex);
-    } else {
-      this.cellSelection?.selectColumn(moveIndex);
+      // Heading toggles don't change grid structure (no rows/columns
+      // added/removed/moved), so grips don't need to be recreated.
+      // Skipping refresh() keeps the popover's trigger element intact.
+      const isHeadingToggle = action.type === 'toggle-heading' || action.type === 'toggle-heading-column';
+
+      if (!isHeadingToggle) {
+        this.rowColControls?.refresh();
+      }
+
+      if (!result.moveSelection) {
+        return;
+      }
+
+      // After move operations, select the moved row/column to show where it landed
+      const { type: moveType, index: moveIndex } = result.moveSelection;
+
+      if (moveType === 'row') {
+        this.cellSelection?.selectRow(moveIndex);
+      } else {
+        this.cellSelection?.selectColumn(moveIndex);
+      }
+
+      this.rowColControls?.setActiveGrip(moveType, moveIndex);
+    });
+  }
+
+  private syncModelForAction(action: RowColAction): { blocksToDelete?: string[] } {
+    switch (action.type) {
+      case 'insert-row-above':
+        this.model.addRow(action.index);
+        break;
+      case 'insert-row-below':
+        this.model.addRow(action.index + 1);
+        break;
+      case 'insert-col-left':
+        this.model.addColumn(action.index);
+        break;
+      case 'insert-col-right':
+        this.model.addColumn(action.index + 1);
+        break;
+      case 'move-row':
+        this.model.moveRow(action.fromIndex, action.toIndex);
+        break;
+      case 'move-col':
+        this.model.moveColumn(action.fromIndex, action.toIndex);
+        break;
+      case 'delete-row':
+        return this.model.deleteRow(action.index);
+      case 'delete-col':
+        return this.model.deleteColumn(action.index);
+      case 'toggle-heading':
+      case 'toggle-heading-column':
+        // Metadata only — handled after executeRowColAction
+        break;
     }
 
-    this.rowColControls?.setActiveGrip(moveType, moveIndex);
+    return {};
   }
 
   private initResize(gridEl: HTMLElement): void {
     this.resize?.destroy();
 
-    const isPercentMode = this.data.colWidths === undefined;
-    const widths = this.data.colWidths ?? readPixelWidths(gridEl);
+    const isPercentMode = this.model.colWidths === undefined;
+    const widths = this.model.colWidths ?? readPixelWidths(gridEl);
 
     if (!isPercentMode) {
-      enableScrollOverflow(this.element);
+      enableScrollOverflow(this.ensureScrollContainer());
     }
 
     this.resize = new TableResize(
       gridEl,
       widths,
       (newWidths: number[]) => {
-        this.data.colWidths = newWidths;
-        enableScrollOverflow(this.element);
+        this.model.setColWidths(newWidths);
+        enableScrollOverflow(this.ensureScrollContainer());
         this.rowColControls?.positionGrips();
+        this.addControls?.syncRowButtonWidth();
+        this.scrollHaze?.update();
       },
       () => {
         this.rowColControls?.hideAllGrips();
       },
       () => {
         this.addControls?.syncRowButtonWidth();
+        this.scrollHaze?.update();
       },
       isPercentMode,
     );
@@ -549,9 +1047,152 @@ export class Table implements BlockTool {
       api: this.api,
       gridElement: gridEl,
       tableBlockId: this.blockId ?? '',
+      model: this.model,
+      isStructuralOpActive: () => this.structuralOpDepth > 0,
+    });
+  }
+
+  private handleCellCopy(cells: HTMLElement[], clipboardData: DataTransfer): void {
+    const entries = this.collectCellBlockData(cells);
+
+    if (entries.length === 0) {
+      return;
+    }
+
+    const payload = serializeCellsToClipboard(entries);
+
+    clipboardData.setData('text/html', buildClipboardHtml(payload));
+    clipboardData.setData('text/plain', buildClipboardPlainText(payload));
+  }
+
+  private handleCellCopyViaButton(cells: HTMLElement[]): void {
+    const entries = this.collectCellBlockData(cells);
+
+    if (entries.length === 0) {
+      return;
+    }
+
+    const payload = serializeCellsToClipboard(entries);
+    const html = buildClipboardHtml(payload);
+    const plainText = buildClipboardPlainText(payload);
+
+    const htmlBlob = new Blob([html], { type: 'text/html' });
+    const textBlob = new Blob([plainText], { type: 'text/plain' });
+
+    void navigator.clipboard.write([
+      new ClipboardItem({
+        'text/html': htmlBlob,
+        'text/plain': textBlob,
+      }),
+    ]);
+  }
+
+  private handleCellColorChange(cells: HTMLElement[], color: string | null, mode: CellColorMode): void {
+    const gridEl = this.gridElement;
+
+    if (!gridEl) {
+      return;
+    }
+
+    this.runTransactedStructuralOp(() => {
+      for (const cell of cells) {
+        const coord = getCellPosition(gridEl, cell);
+
+        if (!coord) {
+          continue;
+        }
+
+        if (mode === 'backgroundColor') {
+          this.model.setCellColor(coord.row, coord.col, color ?? undefined);
+          cell.style.backgroundColor = color ?? '';
+        } else {
+          this.model.setCellTextColor(coord.row, coord.col, color ?? undefined);
+          cell.style.color = color ?? '';
+        }
+      }
     });
   }
 
+  private collectCellBlockData(
+    cells: HTMLElement[],
+  ): Array<{ row: number; col: number; blocks: ClipboardBlockData[]; color?: string; textColor?: string }> {
+    const gridEl = this.gridElement;
+
+    if (!gridEl) {
+      return [];
+    }
+
+    const allRows = Array.from(gridEl.querySelectorAll(`[${ROW_ATTR}]`));
+
+    return cells.map(cell => {
+      const row = cell.closest<HTMLElement>(`[${ROW_ATTR}]`);
+
+      if (!row) {
+        return null;
+      }
+
+      const rowIndex = allRows.indexOf(row);
+      const cellsInRow = Array.from(row.querySelectorAll(`[${CELL_ATTR}]`));
+      const colIndex = cellsInRow.indexOf(cell);
+
+      const container = cell.querySelector(`[${CELL_BLOCKS_ATTR}]`);
+      const blocks: ClipboardBlockData[] = [];
+
+      if (!container) {
+        return { row: rowIndex, col: colIndex, blocks };
+      }
+
+      container.querySelectorAll('[data-blok-id]').forEach(blockEl => {
+        const blockId = blockEl.getAttribute('data-blok-id');
+
+        if (!blockId) {
+          return;
+        }
+
+        const blockIndex = this.api.blocks.getBlockIndex(blockId);
+
+        if (blockIndex === undefined) {
+          return;
+        }
+
+        const block = this.api.blocks.getBlockByIndex(blockIndex);
+
+        if (!block) {
+          return;
+        }
+
+        blocks.push({
+          tool: block.name,
+          data: block.preservedData,
+          ...(Object.keys(block.preservedTunes).length > 0
+            ? { tunes: block.preservedTunes }
+            : {}),
+        });
+      });
+
+      // Read-only legacy cells can render plain text without mounted block holders.
+      const text = blocks.length === 0 ? (container.textContent ?? '').trim() : '';
+
+      if (blocks.length === 0 && text.length > 0) {
+        blocks.push({
+          tool: 'paragraph',
+          data: { text },
+        });
+      }
+
+      const color = this.model.getCellColor(rowIndex, colIndex);
+      const textColor = this.model.getCellTextColor(rowIndex, colIndex);
+
+      return {
+        row: rowIndex,
+        col: colIndex,
+        blocks,
+        ...(color !== undefined ? { color } : {}),
+        ...(textColor !== undefined ? { textColor } : {}),
+      };
+    }).filter((entry): entry is NonNullable<typeof entry> => entry !== null);
+  }
+
   private initCellSelection(gridEl: HTMLElement): void {
     this.cellSelection?.destroy();
 
@@ -562,6 +1203,7 @@ export class Table implements BlockTool {
       grid: gridEl,
       rectangleSelection, // Pass reference
       i18n: this.api.i18n,
+      isPopoverOpen: () => this.rowColControls?.isPopoverOpen ?? false,
       onSelectionActiveChange: (hasSelection) => {
         if (this.resize) {
           this.resize.enabled = !hasSelection;
@@ -570,17 +1212,271 @@ export class Table implements BlockTool {
         this.addControls?.setInteractive(!hasSelection);
         this.rowColControls?.setGripsDisplay(!hasSelection);
       },
+      onSelectionRangeChange: () => {
+        // Selection finalized — restore grips so hover works normally
+        this.rowColControls?.setGripsDisplay(true);
+      },
       onClearContent: (cells) => {
-        if (!this.cellBlocks) {
+        const cellBlocks = this.cellBlocks;
+
+        if (!cellBlocks) {
           return;
         }
 
-        const blockIds = this.cellBlocks.getBlockIdsFromCells(cells);
+        this.runTransactedStructuralOp(() => {
+          const blockIds = cellBlocks.getBlockIdsFromCells(cells);
+
+          cellBlocks.deleteBlocks(blockIds);
+
+          const gridEl = this.gridElement;
+
+          if (!gridEl) {
+            return;
+          }
+
+          for (const cell of cells) {
+            const coord = getCellPosition(gridEl, cell);
 
-        this.cellBlocks.deleteBlocks(blockIds);
+            if (!coord) {
+              continue;
+            }
+
+            this.model.setCellColor(coord.row, coord.col, undefined);
+            this.model.setCellTextColor(coord.row, coord.col, undefined);
+            cell.style.backgroundColor = '';
+            cell.style.color = '';
+          }
+        });
+      },
+      onCopy: (cells, clipboardData) => {
+        this.handleCellCopy(cells, clipboardData);
+      },
+      onCut: (cells, clipboardData) => {
+        this.handleCellCopy(cells, clipboardData);
+      },
+      onCopyViaButton: (cells) => {
+        this.handleCellCopyViaButton(cells);
+      },
+      onColorChange: (cells, color, mode) => {
+        this.handleCellColorChange(cells, color, mode);
       },
     });
   }
+
+  private initScrollHaze(): void {
+    this.scrollHaze?.destroy();
+
+    if (!this.element || !this.scrollContainer) {
+      return;
+    }
+
+    this.scrollHaze = new TableScrollHaze();
+    this.scrollHaze.init(this.element, this.scrollContainer);
+  }
+
+  private initGridPasteListener(gridEl: HTMLElement): void {
+    gridEl.addEventListener('paste', (e: ClipboardEvent) => {
+      this.handleGridPaste(e, gridEl);
+    });
+  }
+
+  private handleGridPaste(e: ClipboardEvent, gridEl: HTMLElement): void {
+    if (this.readOnly || !e.clipboardData || e.defaultPrevented) {
+      return;
+    }
+
+    const html = e.clipboardData.getData('text/html');
+    const blokPayload = parseClipboardHtml(html);
+    const externalPayload = blokPayload === null ? parseGenericHtmlTable(html) : null;
+    const payload = blokPayload ?? externalPayload;
+
+    if (!payload) {
+      return;
+    }
+
+    /**
+     * If the pasted HTML contains multiple tables (e.g. from Google Docs),
+     * don't intercept — let the Paste module handle it as a document-level paste
+     * so each table becomes a separate block without overwriting existing cells.
+     */
+    if (
+      externalPayload !== null &&
+      new DOMParser().parseFromString(html, 'text/html').querySelectorAll('table').length > 1
+    ) {
+      return;
+    }
+
+    const activeElement = document.activeElement as HTMLElement | null;
+
+    if (!activeElement) {
+      return;
+    }
+
+    const targetCell = activeElement.closest<HTMLElement>(`[${CELL_ATTR}]`);
+
+    if (!targetCell || !gridEl.contains(targetCell)) {
+      return;
+    }
+
+    const targetRow = targetCell.closest<HTMLElement>(`[${ROW_ATTR}]`);
+
+    if (!targetRow) {
+      return;
+    }
+
+    e.preventDefault();
+    e.stopPropagation();
+
+    const rows = Array.from(gridEl.querySelectorAll(`[${ROW_ATTR}]`));
+    const targetRowIndex = rows.indexOf(targetRow);
+    const cellsInRow = Array.from(targetRow.querySelectorAll(`[${CELL_ATTR}]`));
+    const targetColIndex = cellsInRow.indexOf(targetCell);
+
+    this.pastePayloadIntoCells(gridEl, payload, targetRowIndex, targetColIndex);
+  }
+
+  private pastePayloadIntoCells(
+    gridEl: HTMLElement,
+    payload: TableCellsClipboard,
+    startRow: number,
+    startCol: number,
+  ): void {
+    this.runTransactedStructuralOp(() => {
+      this.expandGridForPaste(gridEl, startRow + payload.rows, startCol + payload.cols);
+
+      // Paste block data into target cells
+      const rows = gridEl.querySelectorAll(`[${ROW_ATTR}]`);
+
+      Array.from({ length: payload.rows }, (_, r) => r).forEach((r) => {
+        const row = rows[startRow + r];
+
+        if (!row) {
+          return;
+        }
+
+        const cells = row.querySelectorAll(`[${CELL_ATTR}]`);
+
+        Array.from({ length: payload.cols }, (_, c) => c).forEach((c) => {
+          const cell = cells[startCol + c] as HTMLElement | undefined;
+
+          if (cell) {
+            const cellPayload = payload.cells[r][c];
+
+            this.pasteCellPayload(cell, cellPayload);
+
+            // Sync pasted block IDs to model
+            const blockIds = this.cellBlocks?.getBlockIdsFromCells([cell]) ?? [];
+
+            this.model.setCellBlocks(startRow + r, startCol + c, blockIds);
+
+            // Restore cell colors from clipboard
+            const destRow = startRow + r;
+            const destCol = startCol + c;
+
+            this.model.setCellColor(destRow, destCol, cellPayload.color);
+            cell.style.backgroundColor = cellPayload.color ?? '';
+
+            this.model.setCellTextColor(destRow, destCol, cellPayload.textColor);
+            cell.style.color = cellPayload.textColor ?? '';
+          }
+        });
+      });
+
+      // Update table state after paste
+      this.initResize(gridEl);
+      this.addControls?.syncRowButtonWidth();
+      this.rowColControls?.refresh();
+    });
+
+    // Caret placement outside the lock (no structural mutation)
+    const updatedRows = gridEl.querySelectorAll(`[${ROW_ATTR}]`);
+    const lastRow = updatedRows[startRow + payload.rows - 1];
+    const lastCell = lastRow?.querySelectorAll(`[${CELL_ATTR}]`)[startCol + payload.cols - 1] as HTMLElement | undefined;
+
+    if (!lastCell || !this.cellBlocks || !this.api.caret) {
+      return;
+    }
+
+    const blockIds = this.cellBlocks.getBlockIdsFromCells([lastCell]);
+    const lastBlockId = blockIds[blockIds.length - 1];
+
+    if (lastBlockId === undefined) {
+      return;
+    }
+
+    this.api.caret.setToBlock(lastBlockId, 'end');
+  }
+
+  /**
+   * Expand the grid to have at least the required number of rows and columns.
+   */
+  private expandGridForPaste(gridEl: HTMLElement, neededRows: number, neededCols: number): void {
+    const currentRowCount = this.grid.getRowCount(gridEl);
+    const currentColCount = this.grid.getColumnCount(gridEl);
+
+    // Auto-expand rows
+    Array.from({ length: Math.max(0, neededRows - currentRowCount) }).forEach(() => {
+      this.grid.addRow(gridEl);
+      this.model.addRow();
+      populateNewCells(gridEl, this.cellBlocks);
+      updateHeadingStyles(this.gridElement, this.model.withHeadings);
+      updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+    });
+
+    // Auto-expand columns
+    Array.from({ length: Math.max(0, neededCols - currentColCount) }).forEach(() => {
+      const colWidths = this.model.colWidths ?? readPixelWidths(gridEl);
+      const halfWidth = this.model.initialColWidth !== undefined
+        ? Math.round((this.model.initialColWidth / 2) * 100) / 100
+        : computeHalfAvgWidth(colWidths);
+
+      this.grid.addColumn(gridEl, undefined, colWidths, halfWidth);
+      this.model.addColumn(undefined, halfWidth);
+      this.model.setColWidths([...colWidths, halfWidth]);
+      populateNewCells(gridEl, this.cellBlocks);
+      updateHeadingColumnStyles(this.gridElement, this.model.withHeadingColumn);
+    });
+  }
+
+  /**
+   * Replace the contents of a single cell with data from the clipboard payload.
+   */
+  private pasteCellPayload(
+    cell: HTMLElement,
+    payloadCell: { blocks: ClipboardBlockData[] },
+  ): void {
+    // Clear existing blocks in this cell
+    if (this.cellBlocks) {
+      const existingIds = this.cellBlocks.getBlockIdsFromCells([cell]);
+
+      this.cellBlocks.deleteBlocks(existingIds);
+    }
+
+    const container = cell.querySelector<HTMLElement>(`[${CELL_BLOCKS_ATTR}]`);
+
+    if (!container) {
+      return;
+    }
+
+    if (payloadCell.blocks.length === 0) {
+      this.cellBlocks?.ensureCellHasBlock(cell);
+
+      return;
+    }
+
+    for (const blockData of payloadCell.blocks) {
+      const block = this.api.blocks.insert(
+        blockData.tool,
+        blockData.data,
+        {},
+        this.api.blocks.getBlocksCount(),
+        false,
+      );
+
+      container.appendChild(block.holder);
+      this.api.blocks.setBlockParent(block.id, this.blockId ?? '');
+    }
+  }
 }
 
 export { isInsideTableCell, isRestrictedInTableCell, convertToParagraph } from './table-restrictions';