@jackuait/blok 0.13.0 → 0.13.2

package/src/components/modules/toolbar/content-alignment.ts

@@ -0,0 +1,89 @@
+import { DATA_ATTR } from '../../constants';
+
+/**
+ * Horizontal alignment helpers for the toolbar.
+ *
+ * The toolbar's inner content wrapper (holding the plus button + drag handle)
+ * must align with the block's visible content column. Two layouts exist:
+ *
+ *  1. Non-stretched block — `[data-blok-element-content]` is centered inside
+ *     the holder via `mx-auto` + `max-w-blok-content`. The gap between holder
+ *     left and content left IS the offset we want.
+ *
+ *  2. Stretched block (e.g. `database`) — the content element fills the holder
+ *     (max-width removed), so the raw gap is 0. The tool may still re-center
+ *     its visible content via internal CSS padding. In this case we fall back
+ *     to the editor's canonical content-column width (`--max-width-content`)
+ *     and center that inside the holder. Without this the toolbar snaps to
+ *     the holder's far-left edge, far from the visible content.
+ */
+
+/**
+ * Compute the horizontal offset between the holder's left edge and the block's
+ * visible content column. See module doc for the two layout cases.
+ * @param targetBlockHolder - Block holder element (has `data-blok-stretched` when stretched)
+ * @param contentRect - bounding rect of the block's `[data-blok-element-content]`
+ * @param wrapperRect - bounding rect of the toolbar wrapper (co-located with holder)
+ */
+export function computeVisualContentOffset(
+  targetBlockHolder: HTMLElement,
+  contentRect: DOMRect,
+  wrapperRect: DOMRect | undefined
+): number {
+  if (wrapperRect === undefined) {
+    return 0;
+  }
+
+  const stretched = targetBlockHolder.getAttribute(DATA_ATTR.stretched) === 'true';
+
+  if (stretched) {
+    const maxContent = readMaxContentWidth(targetBlockHolder);
+
+    if (maxContent !== null && wrapperRect.width > maxContent) {
+      return (wrapperRect.width - maxContent) / 2;
+    }
+  }
+
+  return Math.max(0, contentRect.left - wrapperRect.left);
+}
+
+/**
+ * Resolve the visible content width used to clamp the toolbar wrapper's
+ * max-width. Stretched blocks still size their visible content to the
+ * canonical content column (`--max-width-content`), so clamp to that
+ * instead of the full holder width — otherwise the toolbar hover target
+ * would span the whole viewport.
+ * @param targetBlockHolder - Block holder element
+ * @param contentRect - bounding rect of the block's `[data-blok-element-content]`
+ * @param wrapperRect - bounding rect of the toolbar wrapper (co-located with holder)
+ */
+export function resolveVisualContentWidth(
+  targetBlockHolder: HTMLElement,
+  contentRect: DOMRect,
+  wrapperRect: DOMRect | undefined
+): number {
+  const stretched = targetBlockHolder.getAttribute(DATA_ATTR.stretched) === 'true';
+
+  if (stretched && wrapperRect !== undefined) {
+    const maxContent = readMaxContentWidth(targetBlockHolder);
+
+    if (maxContent !== null && wrapperRect.width > maxContent) {
+      return maxContent;
+    }
+  }
+
+  return contentRect.width;
+}
+
+/**
+ * Read the `--max-width-content` CSS custom property off the given element
+ * (inherited from `:root`/`@theme`). Returns `null` if the token is absent
+ * or not a positive finite number.
+ * @param element - element whose computed style supplies the CSS var
+ */
+function readMaxContentWidth(element: HTMLElement): number | null {
+  const raw = getComputedStyle(element).getPropertyValue('--max-width-content').trim();
+  const value = parseFloat(raw);
+
+  return Number.isFinite(value) && value > 0 ? value : null;
+}

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

@@ -17,6 +17,7 @@ import { hide } from '../../utils/tooltip';
  * Refactored Toolbar module components
  */
 import { ClickDragHandler } from './click-handler';
+import { computeVisualContentOffset, resolveVisualContentWidth } from './content-alignment';
 import { PlusButtonHandler } from './plus-button';
 import { ToolbarPositioner } from './positioning';
 import { SettingsTogglerHandler } from './settings-toggler';
@@ -360,20 +361,47 @@ export class Toolbar extends Module<ToolbarNodes> {
 
 
   /**
-   * Toggles read-only mode
+   * Toggles read-only mode.
+   *
+   * Read-only (Notion-style): the toolbar and block settings stay alive so the
+   * user can still hover a block and copy a link to it. The plus button is
+   * hidden and the drag gesture is suppressed (see moveAndOpen + plus-button
+   * handler).
    * @param {boolean} readOnlyEnabled - read-only mode
    */
   public toggleReadOnly(readOnlyEnabled: boolean): void {
-    if (!readOnlyEnabled) {
+    /**
+     * Draw the toolbar the first time we need it. Previously the toolbar DOM
+     * was only built on the readOnly=false path; now read-only also hosts a
+     * (restricted) block settings popover, so ensure the DOM exists in both
+     * modes. Subsequent toggles just flip plus-button visibility.
+     */
+    if (this.nodes.wrapper === undefined) {
       window.requestIdleCallback(async () => {
         await this.drawUI();
         this.enableModuleBindings();
+        this.applyReadOnlyToPlusButton(readOnlyEnabled);
       }, { timeout: 2000 });
-    } else {
-      this.destroy();
-      this.Blok.BlockSettings.destroy();
-      this.disableModuleBindings();
+
+      return;
     }
+
+    this.applyReadOnlyToPlusButton(readOnlyEnabled);
+  }
+
+  /**
+   * Hides the plus button in read-only mode, restores its visibility otherwise.
+   * Uses inline display:none because the button element already uses inline
+   * style toggling elsewhere (moveAndOpen, close, moveAndOpenForMultipleBlocks).
+   */
+  private applyReadOnlyToPlusButton(readOnlyEnabled: boolean): void {
+    const { plusButton } = this.nodes;
+
+    if (plusButton === undefined) {
+      return;
+    }
+
+    plusButton.style.display = readOnlyEnabled ? 'none' : '';
   }
 
   /**
@@ -476,8 +504,9 @@ export class Toolbar extends Module<ToolbarNodes> {
      * whole table undraggable while the user edits cell text.
      */
     const isCalloutFirstChild = this.isFirstChildOfCallout(targetBlock);
+    const hidePlusButton = isCalloutFirstChild || this.Blok.ReadOnly.isEnabled;
 
-    plusButton.style.display = isCalloutFirstChild ? 'none' : '';
+    plusButton.style.display = hidePlusButton ? 'none' : '';
 
     if (settingsToggler) {
       settingsToggler.style.display = isCalloutFirstChild ? 'none' : '';
@@ -594,38 +623,41 @@ export class Toolbar extends Module<ToolbarNodes> {
       this.restoreSettingsTogglerForLeftEdgeBlock(targetBlock);
     }
 
-    /**
-     * Sync toolbar content wrapper's position and width with the block content element
-     * so toolbar buttons align with the block content edge regardless of whether
-     * the consumer uses CSS margin or overrides max-width (e.g. wide-mode).
-     *
-     * Uses getBoundingClientRect to get the actual visual offset rather than reading
-     * CSS marginLeft, which does not account for cases where max-width is removed
-     * and the content fills the full container width.
-     *
-     * Uses Math.max to guarantee the actions container (positioned via right:100%)
-     * never extends beyond the left edge of the viewport, which would make the
-     * drag handle unreachable by pointer events.
-     *
-     * For nested blocks (e.g. children inside a callout), the holder is already
-     * offset from the viewport left by the parent's indentation. In that case we
-     * only need to ensure the actions don't extend beyond the viewport left edge
-     * (holderLeft px are available to the left), so the minimum margin is
-     * max(0, actionsWidth - holderLeft) rather than a flat actionsWidth clamp.
-     */
-    if (blockContentElement && this.nodes.content) {
-      const holderRect = this.nodes.wrapper?.getBoundingClientRect();
-      const contentRect = blockContentElement.getBoundingClientRect();
-      const visualOffset = holderRect ? Math.max(0, contentRect.left - holderRect.left) : 0;
-      const actionsWidth = this.nodes.actions?.offsetWidth ?? 0;
-      const holderLeft = holderRect ? Math.max(0, holderRect.left) : 0;
-      const minMarginLeft = Math.max(0, actionsWidth - holderLeft);
-
-      this.nodes.content.style.marginLeft = `${Math.max(visualOffset, minMarginLeft)}px`;
-      this.nodes.content.style.maxWidth = `${contentRect.width}px`;
+    if (blockContentElement) {
+      this.syncContentToBlock(targetBlockHolder, blockContentElement);
     }
   }
 
+  /**
+   * Align the toolbar's inner content wrapper with the block's visible content column.
+   * See `content-alignment.ts` for the two-case reasoning (non-stretched vs stretched).
+   *
+   * `Math.max` with `actionsWidth - holderLeft` guarantees the actions bar
+   * (positioned at `right:100%`) never extends past the viewport's left edge,
+   * which would make the drag handle unreachable by pointer events. For nested
+   * blocks already offset from the viewport, `holderLeft` px-of-slack relax the
+   * minimum so buttons aren't pushed into the text content.
+   * @param targetBlockHolder - Block holder element
+   * @param blockContentElement - `[data-blok-element-content]` element inside the holder
+   */
+  private syncContentToBlock(targetBlockHolder: HTMLElement, blockContentElement: HTMLElement): void {
+    if (this.nodes.content === undefined) {
+      return;
+    }
+
+    const wrapperRect = this.nodes.wrapper?.getBoundingClientRect();
+    const contentRect = blockContentElement.getBoundingClientRect();
+    const visualOffset = computeVisualContentOffset(targetBlockHolder, contentRect, wrapperRect);
+    const actionsWidth = this.nodes.actions?.offsetWidth ?? 0;
+    const holderLeft = wrapperRect ? Math.max(0, wrapperRect.left) : 0;
+    const minMarginLeft = Math.max(0, actionsWidth - holderLeft);
+    const effectiveOffset = Math.max(visualOffset, minMarginLeft);
+    const contentWidth = resolveVisualContentWidth(targetBlockHolder, contentRect, wrapperRect);
+
+    this.nodes.content.style.marginLeft = `${effectiveOffset}px`;
+    this.nodes.content.style.maxWidth = `${contentWidth}px`;
+  }
+
   /**
    * Move Toolbar to the specified block (or first selected block) and open it for multi-block selection.
    * Keeps the add button visible so users can still insert blocks while multiple are selected.
@@ -697,8 +729,9 @@ export class Toolbar extends Module<ToolbarNodes> {
     /**
      * Restore plus button and settings toggler visibility for multi-block selection,
      * in case they were hidden for table cell blocks.
+     * In read-only mode, keep the plus button hidden.
      */
-    plusButton.style.display = '';
+    plusButton.style.display = this.Blok.ReadOnly.isEnabled ? 'none' : '';
     plusButton.style.color = '';
 
     if (settingsToggler) {
@@ -742,23 +775,8 @@ export class Toolbar extends Module<ToolbarNodes> {
 
     this.open();
 
-    /**
-     * Sync toolbar content wrapper's position and width with the block content element.
-     * Uses getBoundingClientRect so wide-mode content (max-width: none) is handled correctly.
-     * Clamp to max(0, actionsWidth - holderLeft) so actions never extend beyond the left
-     * viewport edge. For nested blocks already offset from the left, a smaller clamp is
-     * used so buttons are not pushed into the text content.
-     */
-    if (blockContentElement && this.nodes.content) {
-      const holderRect = this.nodes.wrapper?.getBoundingClientRect();
-      const contentRect = blockContentElement.getBoundingClientRect();
-      const visualOffset = holderRect ? Math.max(0, contentRect.left - holderRect.left) : 0;
-      const actionsWidth = this.nodes.actions?.offsetWidth ?? 0;
-      const holderLeft = holderRect ? Math.max(0, holderRect.left) : 0;
-      const minMarginLeft = Math.max(0, actionsWidth - holderLeft);
-
-      this.nodes.content.style.marginLeft = `${Math.max(visualOffset, minMarginLeft)}px`;
-      this.nodes.content.style.maxWidth = `${contentRect.width}px`;
+    if (blockContentElement) {
+      this.syncContentToBlock(targetBlockHolder, blockContentElement);
     }
   }
 
@@ -767,10 +785,6 @@ export class Toolbar extends Module<ToolbarNodes> {
    * @param options - Optional configuration
    */
   public close(options?: ToolbarCloseOptions): void {
-    if (this.Blok.ReadOnly.isEnabled) {
-      return;
-    }
-
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     this.nodes.wrapper?.classList.remove(this.CSS.toolbarOpened);
     // eslint-disable-next-line @typescript-eslint/no-deprecated
@@ -804,10 +818,11 @@ export class Toolbar extends Module<ToolbarNodes> {
 
     /**
      * Restore plus button and settings toggler visibility
-     * in case they were hidden for table cell blocks
+     * in case they were hidden for table cell blocks.
+     * In read-only mode, keep the plus button hidden.
      */
     if (this.nodes.plusButton) {
-      this.nodes.plusButton.style.display = '';
+      this.nodes.plusButton.style.display = this.Blok.ReadOnly.isEnabled ? 'none' : '';
       this.nodes.plusButton.style.color = '';
     }
 
@@ -948,8 +963,9 @@ export class Toolbar extends Module<ToolbarNodes> {
     }
 
     const isCalloutFirstChild = this.hoveredBlock !== null && this.isFirstChildOfCallout(this.hoveredBlock);
+    const hidePlusButton = isCalloutFirstChild || this.Blok.ReadOnly.isEnabled;
 
-    plusButton.style.display = isCalloutFirstChild ? 'none' : '';
+    plusButton.style.display = hidePlusButton ? 'none' : '';
 
     if (settingsToggler) {
       settingsToggler.style.display = isCalloutFirstChild ? 'none' : '';
@@ -1244,6 +1260,14 @@ export class Toolbar extends Module<ToolbarNodes> {
 
     if (plusButton) {
       this.readOnlyMutableListeners.on(plusButton, 'mousedown', (e) => {
+        /**
+         * Plus button is inert in read-only mode. It is also visually hidden
+         * (see toggleReadOnly), but guard here too in case of programmatic clicks.
+         */
+        if (this.Blok.ReadOnly.isEnabled) {
+          return;
+        }
+
         /**
          * Prevent focus from moving away from the currently-active contenteditable block.
          * Without this, clicking the plus button steals DOM focus, causing subsequent

package/src/components/modules/ui.ts

@@ -256,15 +256,32 @@ export class UI extends Module<UINodes> {
    * @param {boolean} readOnlyEnabled - "read only" state
    */
   public toggleReadOnly(readOnlyEnabled: boolean): void {
+    /**
+     * Collapse the bottom zone in read-only mode. Its only purpose is to act as
+     * a clickable area below the last block for adding/focusing a block, which is
+     * disabled in read-only mode. Restore the configured min-height when editing.
+     */
+    if (this.nodes.bottomZone) {
+      this.nodes.bottomZone.style.minHeight = readOnlyEnabled ? '0px' : `${this.config.minHeight}px`;
+    }
+
     /**
      * Prepare components based on read-only state
      */
     if (readOnlyEnabled) {
       /**
-       * Unbind all events
-       *
+       * Unbind editing-only events but keep block hover active so the toolbar
+       * can still appear on hover (used by the read-only "copy link to block"
+       * popover; see Toolbar.toggleReadOnly).
        */
-      this.unbindReadOnlySensitiveListeners();
+      this.unbindReadOnlySensitiveListeners({ keepBlockHover: true });
+
+      /**
+       * Ensure block hover detection is active even when the editor starts in
+       * read-only mode — bindReadOnlySensitiveListeners() was never called in
+       * that path.
+       */
+      this.blockHoverController?.enable();
 
       /**
        * Set contenteditable="false" on all block content elements
@@ -672,8 +689,11 @@ export class UI extends Module<UINodes> {
 
   /**
    * Unbind events that should work only in read-only mode
+   * @param options - when keepBlockHover is true, the block-hover controller
+   * stays enabled so the toolbar can still appear on hover. Used when entering
+   * read-only mode; editor destroy still disables everything.
    */
-  private unbindReadOnlySensitiveListeners(): void {
+  private unbindReadOnlySensitiveListeners(options?: { keepBlockHover?: boolean }): void {
     this.readOnlyMutableListeners.clearAll();
 
     /**
@@ -682,9 +702,11 @@ export class UI extends Module<UINodes> {
     this.keyboardController?.disable();
 
     /**
-     * Disable block hover controller
+     * Disable block hover controller unless the caller opted to keep it alive.
      */
-    this.blockHoverController?.disable();
+    if (options?.keepBlockHover !== true) {
+      this.blockHoverController?.disable();
+    }
   }
 
   /**

package/src/components/modules/uiControllers/controllers/blockHover.ts

@@ -48,10 +48,22 @@ export class BlockHoverController extends Controller {
     super(options);
   }
 
+  /**
+   * Whether the controller's listeners are currently bound. Used to make
+   * enable() idempotent so repeated calls (e.g. during read-only toggling)
+   * do not register the mousemove handler multiple times.
+   */
+  private isEnabled: boolean = false;
+
   /**
    * Enable block hover detection
    */
   public override enable(): void {
+    if (this.isEnabled) {
+      return;
+    }
+
+    this.isEnabled = true;
     /**
      * Local function that handles block hover detection
      * Bound to 'this' to preserve context when passed to throttle
@@ -252,6 +264,14 @@ export class BlockHoverController extends Controller {
     return result.block;
   }
 
+  /**
+   * Disable the controller and clear its listeners.
+   */
+  public override disable(): void {
+    super.disable();
+    this.isEnabled = false;
+  }
+
   /**
    * Reset the last hovered block (useful for testing or state reset)
    */

package/src/components/utils/color-mapping.ts

@@ -1,4 +1,5 @@
 import { COLOR_PRESETS, COLOR_PRESETS_DARK } from '../shared/color-presets';
+import { isDefaultDarkBackground, isDefaultWhiteBackground } from './default-page-colors';
 
 /**
  * Convert an HSL color (H in degrees, S and L as 0-100 percentages) to an RGB tuple.
@@ -214,6 +215,13 @@ function hslDistance(
  * @returns the nearest preset hex color, or the input unchanged if unparseable
  */
 export function mapToNearestPresetColor(cssColor: string, mode: 'text' | 'bg'): string {
+  /* Defense-in-depth: default page backgrounds (white / near-black) would otherwise
+   * collapse onto the gray bg preset since gray is the only achromatic bg color.
+   * Return the input unchanged so callers preserve the page-default rendering. */
+  if (mode === 'bg' && (isDefaultWhiteBackground(cssColor) || isDefaultDarkBackground(cssColor))) {
+    return cssColor;
+  }
+
   const rgb = parseColor(cssColor);
 
   if (rgb === null) {
@@ -251,6 +259,13 @@ export function mapToNearestPresetColor(cssColor: string, mode: 'text' | 'bg'):
  * @returns the nearest preset name (e.g. 'red'), or null if unparseable
  */
 export function mapToNearestPresetName(cssColor: string, mode: 'text' | 'bg'): string | null {
+  /* Defense-in-depth: default page backgrounds (white / near-black) would otherwise
+   * collapse onto the gray bg preset since gray is the only achromatic bg color.
+   * Return null so callers leave the original styling untouched. */
+  if (mode === 'bg' && (isDefaultWhiteBackground(cssColor) || isDefaultDarkBackground(cssColor))) {
+    return null;
+  }
+
   const rgb = parseColor(cssColor);
 
   if (rgb === null) {

package/src/components/utils/color-migration.ts

@@ -1,5 +1,6 @@
 import { colorVarName } from '../shared/color-presets';
 import { mapToNearestPresetName } from './color-mapping';
+import { isDefaultDarkBackground, isDefaultWhiteBackground } from './default-page-colors';
 
 const PROPS = ['color', 'background-color'] as const;
 type Prop = typeof PROPS[number];
@@ -27,6 +28,15 @@ export function migrateMarkColors(container: Element): void {
         continue;
       }
 
+      /* Strip default page background-colors so persisted defaults don't render
+       * as a styled <mark>. mapToNearestPresetName already returns null for
+       * these inputs, but null only blocks substitution — it does not remove
+       * the existing inline value. */
+      if (prop === 'background-color' && (isDefaultWhiteBackground(value) || isDefaultDarkBackground(value))) {
+        el.style.removeProperty(prop);
+        continue;
+      }
+
       const name = mapToNearestPresetName(value, PROP_MODE[prop]);
 
       if (name !== null) {

package/src/components/utils/data-model-transform.ts

@@ -1238,6 +1238,206 @@ export const normalizeTableChildParents = (blocks: OutputBlockData[]): OutputBlo
   });
 };
 
+/**
+ * Positional cell-child id minted by the HTML→blok migration: `cell-<row>-<col>`
+ * with 1-based row/col (e.g. `cell-2-1` = row 2, column 1). See the migration
+ * system prompt (EditorJsHtmlConversionSystemPrompt) which instructs the model
+ * to emit one paragraph per non-empty cell with exactly this id.
+ */
+const DETACHED_CELL_ID_PATTERN = /^cell-([1-9]\d*)-([1-9]\d*)$/;
+
+interface CellPosition {
+  row: number;
+  col: number;
+}
+
+const parseDetachedCellPosition = (id: BlockId | undefined): CellPosition | null => {
+  if (typeof id !== 'string') {
+    return null;
+  }
+  const match = DETACHED_CELL_ID_PATTERN.exec(id);
+
+  if (match === null) {
+    return null;
+  }
+  const row = Number(match[1]) - 1;
+  const col = Number(match[2]) - 1;
+
+  if (row < 0 || col < 0) {
+    return null;
+  }
+  return { row, col };
+};
+
+const tableCellIsEmptyAt = (tableBlock: OutputBlockData, row: number, col: number): boolean => {
+  const rows = getTableContentRows(tableBlock.data);
+
+  if (rows === null) {
+    return false;
+  }
+  const rowCells = rows[row];
+
+  if (!Array.isArray(rowCells)) {
+    return false;
+  }
+  const cell = rowCells[col];
+
+  return isCellWithBlockRefs(cell) && cell.blocks.length === 0;
+};
+
+const collectReferencedCellChildIds = (blocks: OutputBlockData[]): Set<string> => {
+  const referenced = new Set<string>();
+
+  blocks
+    .filter(block => block.type === 'table')
+    .forEach(tableBlock => {
+      const rows = getTableContentRows(tableBlock.data);
+
+      rows?.forEach(row => {
+        if (!Array.isArray(row)) {
+          return;
+        }
+        row.forEach(cell => {
+          if (!isCellWithBlockRefs(cell)) {
+            return;
+          }
+          cell.blocks.forEach(id => {
+            if (typeof id === 'string') {
+              referenced.add(id);
+            }
+          });
+        });
+      });
+    });
+
+  return referenced;
+};
+
+/**
+ * Recover migrated table cells whose text was detached by a pre-fix save.
+ *
+ * The "migration table content loss" bug worked like this: a migrated table
+ * references its cell text via `data.content[r][c].blocks = [<childId>]`, but the
+ * child paragraph lacked `parent === tableId`. A save on an unfixed editor filtered
+ * that child out of the cell (Table.save() keeps only `parentId === tableId`) and
+ * the saver emitted it as a root-level block. The text is NOT lost — it survives
+ * as a detached top-level paragraph — but the cell now reads `{ blocks: [] }`.
+ *
+ * Crucially, the migration minted that paragraph with a POSITIONAL id
+ * (`cell-<row>-<col>`, 1-based) that still encodes which cell it came from. This
+ * pass walks every root-level block whose id matches that pattern and is no longer
+ * referenced by any cell, and — when exactly one table has a matching EMPTY cell at
+ * that position — re-attaches it: the id is restored to `content[row][col].blocks`
+ * and the block's `parent` is set to that table.
+ *
+ * Safety: only empty cells are filled (occupied cells are never overwritten), only
+ * `cell-R-C`-id root blocks are consumed (user-authored blocks never match), blocks
+ * that already carry a `parent` are skipped, and reclamation is skipped entirely
+ * when two or more tables share the matching empty cell (ambiguous — never guess).
+ * The function is non-mutating and returns the same array reference when there is
+ * nothing to reclaim.
+ * @param blocks - flat block array potentially containing detached migrated cells
+ */
+export const reclaimDetachedTableCells = (blocks: OutputBlockData[]): OutputBlockData[] => {
+  const tableBlocks = blocks.filter(
+    (block): block is OutputBlockData => block.type === 'table' && block.id !== undefined && block.id !== null
+  );
+
+  // The positional id `cell-<row>-<col>` encodes the cell but NOT which table.
+  // With two or more tables the owning table is unidentifiable, so re-attaching
+  // could silently drop text into the wrong table. Only single-table documents
+  // are unambiguous; anything else is left untouched (never guess).
+  if (tableBlocks.length !== 1) {
+    return blocks;
+  }
+
+  const referenced = collectReferencedCellChildIds(blocks);
+
+  // Count id occurrences: a duplicated id is ambiguous and would be regenerated
+  // by the renderer's dedup pass after reclaim (leaving a dangling cell ref), so
+  // such ids must never be reclaimed.
+  const idCounts = new Map<string, number>();
+
+  for (const block of blocks) {
+    if (block.id !== undefined && block.id !== null) {
+      idCounts.set(block.id, (idCounts.get(block.id) ?? 0) + 1);
+    }
+  }
+
+  const reclaimedParent = new Map<BlockId, BlockId>();
+  const cellAdditions = new Map<BlockId, Array<CellPosition & { id: BlockId }>>();
+
+  for (const block of blocks) {
+    if (block.id === undefined || block.id === null) {
+      continue;
+    }
+    if (block.parent !== undefined && block.parent !== null) {
+      continue;
+    }
+    if (referenced.has(block.id)) {
+      continue;
+    }
+    if ((idCounts.get(block.id) ?? 0) > 1) {
+      continue;
+    }
+    const position = parseDetachedCellPosition(block.id);
+
+    if (position === null) {
+      continue;
+    }
+    const matchingTables = tableBlocks.filter(table =>
+      tableCellIsEmptyAt(table, position.row, position.col)
+    );
+
+    if (matchingTables.length !== 1) {
+      continue;
+    }
+    const tableId = matchingTables[0].id as BlockId;
+
+    reclaimedParent.set(block.id, tableId);
+    const additions = cellAdditions.get(tableId) ?? [];
+
+    additions.push({ ...position, id: block.id });
+    cellAdditions.set(tableId, additions);
+  }
+
+  if (reclaimedParent.size === 0) {
+    return blocks;
+  }
+
+  return blocks.map(block => {
+    if (block.id !== undefined && block.id !== null && reclaimedParent.has(block.id)) {
+      return { ...block, parent: reclaimedParent.get(block.id) };
+    }
+
+    if (block.type === 'table' && block.id !== undefined && block.id !== null && cellAdditions.has(block.id)) {
+      const additions = cellAdditions.get(block.id) ?? [];
+      const rows = getTableContentRows(block.data);
+
+      if (rows === null) {
+        return block;
+      }
+      const newContent = rows.map((row, rowIndex) => {
+        if (!Array.isArray(row)) {
+          return row;
+        }
+        return row.map((cell, colIndex) => {
+          const addition = additions.find(a => a.row === rowIndex && a.col === colIndex);
+
+          if (addition === undefined || !isCellWithBlockRefs(cell)) {
+            return cell;
+          }
+          return { ...cell, blocks: [...cell.blocks, addition.id] };
+        });
+      });
+
+      return { ...block, data: { ...(block.data as Record<string, unknown>), content: newContent } } as OutputBlockData;
+    }
+
+    return block;
+  });
+};
+
 /**
  * Check if transformation is needed based on config and detected format
  */