@jackuait/blok 0.10.8 → 0.10.9

package/dist/full.mjs

@@ -1,7 +1,7 @@
-import { n as e, t } from "./chunks/blok-ClCrnWuI.mjs";
-import { ur as n } from "./chunks/constants-BoE5frJm.mjs";
+import { n as e, t } from "./chunks/blok-DbRn9adY.mjs";
+import { ur as n } from "./chunks/constants-C9lsSOXl.mjs";
 import { t as r } from "./chunks/objectSpread2-CWwMYL_U.mjs";
-import { a as i, b as a, c as o, g as s, i as c, l, n as u, o as d, s as f, t as p, v as m, y as h } from "./chunks/tools-HQPJLj5m.mjs";
+import { a as i, b as a, c as o, g as s, i as c, l, n as u, o as d, s as f, t as p, v as m, y as h } from "./chunks/tools-D0W3_dlA.mjs";
 //#region src/full.ts
 var g = {
 	paragraph: {

package/dist/react.mjs

@@ -1,5 +1,5 @@
-import { t as e } from "./chunks/blok-ClCrnWuI.mjs";
-import "./chunks/constants-BoE5frJm.mjs";
+import { t as e } from "./chunks/blok-DbRn9adY.mjs";
+import "./chunks/constants-C9lsSOXl.mjs";
 import { t } from "./chunks/objectSpread2-CWwMYL_U.mjs";
 import { t as n } from "./chunks/objectWithoutProperties-Dci1-l7D.mjs";
 import { forwardRef as r, useEffect as i, useMemo as a, useRef as o, useState as s } from "react";

package/dist/tools.mjs

@@ -1,3 +1,3 @@
-import { m as e } from "./chunks/constants-BoE5frJm.mjs";
-import { _ as t, a as n, b as r, c as i, d as a, f as o, g as s, h as c, i as l, l as u, m as d, n as f, o as p, p as m, r as h, s as g, t as _, u as v, v as y, y as b } from "./chunks/tools-HQPJLj5m.mjs";
+import { m as e } from "./chunks/constants-C9lsSOXl.mjs";
+import { _ as t, a as n, b as r, c as i, d as a, f as o, g as s, h as c, i as l, l as u, m as d, n as f, o as p, p as m, r as h, s as g, t as _, u as v, v as y, y as b } from "./chunks/tools-D0W3_dlA.mjs";
 export { u as Bold, c as Callout, v as Code, e as Convert, d as Database, m as DatabaseRow, o as Divider, b as Header, h as InlineCode, i as Italic, g as Link, y as List, p as Marker, r as Paragraph, a as Quote, l as Strikethrough, t as Table, s as Toggle, n as Underline, _ as defaultBlockTools, f as defaultInlineTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackuait/blok",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "description": "Blok — headless, highly extensible rich text editor built for developers who need to implement a block-based editing experience (similar to Notion) without building it from scratch",
   "module": "dist/blok.mjs",
   "types": "./types/index.d.ts",
@@ -116,8 +116,8 @@
     "perf:compare": "node scripts/analyze-performance.mjs --baseline",
     "perf:dashboard": "node scripts/generate-performance-dashboard.mjs",
     "e2e:validate-categories": "node scripts/validate-test-categories.mjs",
-    "size": "size-limit",
-    "size:why": "size-limit --why",
+    "validate:spec-coverage": "node scripts/validate-spec-file-coverage.mjs",
+    "ci:timing": "node scripts/ci-timing-probe.mjs",
     "release": "node scripts/release.mjs",
     "release:preflight": "yarn lint && yarn test",
     "unused-css": "node scripts/unused-css-finder/cli.mjs"
@@ -137,8 +137,6 @@
     "@commitlint/cli": "20.4.4",
     "@commitlint/config-conventional": "20.4.4",
     "@playwright/test": "1.58.2",
-    "@size-limit/esbuild-why": "12.0.1",
-    "@size-limit/preset-small-lib": "12.0.1",
     "@storybook/addon-a11y": "10.2.19",
     "@storybook/addon-vitest": "10.2.19",
     "@storybook/html-vite": "10.2.19",
@@ -177,7 +175,6 @@
     "rollup-plugin-license": "3.7.0",
     "semantic-release": "25.0.3",
     "shiki": "^4.0.2",
-    "size-limit": "12.0.1",
     "storybook": "10.2.19",
     "tailwindcss": "4.2.1",
     "typescript": "5.9.3",

package/src/components/block/index.ts

@@ -224,6 +224,14 @@ export class Block extends EventsDispatcher<BlockEvents> {
    */
   private draggableCleanup: (() => void) | null = null;
 
+  /**
+   * Callbacks to invoke at the top of destroy(). External subscribers
+   * (e.g. an in-flight drag) register here so they can cancel themselves
+   * when the Block instance they hold becomes invalid — preventing stale
+   * Block references from reaching drop handlers mid-drag.
+   */
+  private destroyCallbacks: Set<() => void> = new Set();
+
   /**
    * Manages tool element composition and rendering
    */
@@ -529,10 +537,38 @@ export class Block extends EventsDispatcher<BlockEvents> {
     return this.dataPersistenceManager.setData(newData);
   }
 
+  /**
+   * Register a callback to be invoked when this Block is destroyed.
+   * Returns an unregister function.
+   *
+   * Used by DragController to cancel an in-flight drag when its source
+   * block is replaced (Yjs remote update, blockManager.update, tool
+   * conversion, etc). Without this hook, the state machine would hold
+   * a stale Block reference and drop the wrong block on mouseup.
+   * @param callback - Function to call during destroy()
+   * @returns Unregister function
+   */
+  public addDestroyCallback(callback: () => void): () => void {
+    this.destroyCallbacks.add(callback);
+
+    return (): void => {
+      this.destroyCallbacks.delete(callback);
+    };
+  }
+
   /**
    * Call Tool instance destroy method
    */
   public destroy(): void {
+    // Notify external subscribers FIRST — before any state is torn down —
+    // so listeners (e.g. DragController) can cancel cleanly while the
+    // Block is still consistent. Copy to a local list so a callback that
+    // unregisters itself doesn't mutate the set during iteration.
+    const callbacks = Array.from(this.destroyCallbacks);
+
+    this.destroyCallbacks.clear();
+    callbacks.forEach((cb) => cb());
+
     this.mutationHandler.destroy();
     this.inputManager.destroy();
 

package/src/components/blocks.ts

@@ -117,6 +117,25 @@ export class Blocks {
    * @param {boolean} skipDOM - if true, do not manipulate DOM (useful when SortableJS already did it)
    */
   public move(toIndex: number, fromIndex: number, skipDOM = false, skipMovedHook = false): void {
+    /**
+     * Invalid-index guard (regression: wrong-block-dropped).
+     *
+     * `Array.splice(-1, 1)` removes the LAST element, and `splice(N, 1)` where
+     * N is past the end does nothing — both hide stale-reference bugs as silent
+     * data corruption. Every caller in every surface (drag, yjs-sync, API,
+     * tool conversion, undo) flows through here, so this is the lowest-level
+     * point to reject nonsense indices and keep the "wrong block dropped"
+     * class of bug from ever reappearing.
+     */
+    if (
+      fromIndex < 0 ||
+      fromIndex >= this.blocks.length ||
+      toIndex < 0 ||
+      toIndex >= this.blocks.length
+    ) {
+      return;
+    }
+
     /**
      * cut out the block, move the DOM element and insert at the desired index
      * again (the shifting within the blocks array will happen automatically).
@@ -156,8 +175,33 @@ export class Blocks {
    * @param {number} index — index to insert Block
    * @param {Block} block — Block to insert
    * @param {boolean} replace — it true, replace block on given index
+   * @param {boolean} appendToWorkingArea — if true, append to workingArea end (ignores position)
+   * @param {boolean} forceTopLevel — if true, place holder at workingArea root level even when
+   *   the previous block in the flat array is nested inside another container. Used when the
+   *   caller knows the new block is logically top-level (parentId === null). Prevents the
+   *   Enter-after-callout regression family where insertAdjacentElement('afterend',
+   *   previousBlock.holder) would otherwise drop the new holder inside a nested container.
    */
-  public insert(index: number, block: Block, replace = false, appendToWorkingArea = false): void {
+  public insert(
+    index: number,
+    block: Block,
+    replace = false,
+    appendToWorkingArea = false,
+    forceTopLevel = false
+  ): void {
+    /**
+     * Invalid-index guard (regression: wrong-block-dropped via alt+drag).
+     *
+     * `Array.splice(-1, 0, block)` inserts BEFORE the last element — a silent
+     * divergence between the flat blocks array and the DOM that corrupts the
+     * next move() operation and drops an unrelated block. Mirrors the guard
+     * in Blocks.move so every caller (drag duplicate, yjs-sync, undo, API) is
+     * protected at the lowest level.
+     */
+    if (index < 0) {
+      return;
+    }
+
     if (!this.length) {
       this.push(block);
 
@@ -202,12 +246,62 @@ export class Blocks {
 
     if (insertIndex > 0) {
       const previousBlock = this.blocks[insertIndex - 1];
+      const nextBlock = this.blocks[insertIndex + 1] as Block | undefined;
+
+      if (forceTopLevel) {
+        this.insertAtRootLevel(block, insertIndex);
+
+        return;
+      }
+
+      /**
+       * Universal defense against the Enter-after-nested bug family, covering
+       * every insertion path (paste, toolbox, slash menu, plus button, markdown
+       * shortcut, conversion, split, public API, yjs-sync, drag, programmatic).
+       *
+       * The only configuration where flat-array adjacency disagrees with the
+       * caller's intended DOM container is when the predecessor is DOM-nested
+       * (inside a callout, toggle, header-toggleable, table cell, or any future
+       * nesting tool's `[data-blok-nested-blocks]` container) AND the successor
+       * is at workingArea root. In that case, anchoring `afterend previous`
+       * would leak the new holder into the nested container even though the
+       * caller's logical intent is a top-level sibling. Route to the successor
+       * instead, which correctly anchors at workingArea root.
+       *
+       * Every OTHER configuration stays on the original `afterend previous`
+       * rule, which preserves:
+       *   - Plain top-level insertion: prev at root, any next → afterend prev.
+       *   - Nested-sibling insertion (paste inside a toggle child, no top-level
+       *     follower): prev nested, next undefined or same-container → afterend
+       *     prev keeps the new block in the same nested container.
+       *   - Insertion between two same-parent nested children: prev and next
+       *     both in same nested container → afterend prev stays in container.
+       *
+       * The forceTopLevel flag is still honored above for callers that want to
+       * skip past a trailing nested subtree. This rule is the defense for every
+       * path that does NOT explicitly set forceTopLevel.
+       */
+      const prevIsAtRoot = previousBlock.holder.parentElement === this.workingArea;
+      const nextIsAtRoot = nextBlock !== undefined
+        && nextBlock.holder.parentElement === this.workingArea;
+
+      if (!prevIsAtRoot && nextIsAtRoot && nextBlock !== undefined) {
+        this.insertToDOM(block, 'beforebegin', nextBlock);
+
+        return;
+      }
 
       this.insertToDOM(block, 'afterend', previousBlock);
 
       return;
     }
 
+    if (forceTopLevel) {
+      this.insertAtRootLevel(block, insertIndex);
+
+      return;
+    }
+
     const nextBlock = this.blocks[insertIndex + 1] as Block | undefined;
 
     if (nextBlock) {
@@ -231,8 +325,12 @@ export class Blocks {
 
     const prevBlock = this.blocks[index];
 
-    prevBlock.holder.replaceWith(block.holder);
     prevBlock.call(BlockToolAPI.REMOVED);
+    // Destroy releases the drag-handle listener bound to the shared settings
+    // toggler; skipping it leaves the orphan Block wired up and dragging it
+    // on next mousedown instead of whatever the user intended.
+    prevBlock.destroy();
+    prevBlock.holder.replaceWith(block.holder);
 
     this.blocks[index] = block;
 
@@ -245,6 +343,17 @@ export class Blocks {
    * @param index - index to insert blocks at
    */
   public insertMany(blocks: Block[], index: number ): void {
+    /**
+     * Invalid-index guard (regression: wrong-block-dropped family).
+     * Mirrors Blocks.move and Blocks.insert — `splice(-1, 0, ...blocks)`
+     * silently inserts BEFORE the last element, diverging array from DOM.
+     * Yjs batch-add paths feed this method with computed indices; a stale
+     * input would otherwise cause a later move() to drop an unrelated block.
+     */
+    if (index < 0) {
+      return;
+    }
+
     const fragment = new DocumentFragment();
 
     for (const block of blocks) {
@@ -293,6 +402,21 @@ export class Blocks {
    */
   public remove(index: number): void {
     const removeIndex = isNaN(index) ? this.length - 1 : index;
+
+    /**
+     * Layer 15: invalid-index guard (regression: wrong-block-dropped family).
+     *
+     * Before this guard, a stale caller passing a negative or out-of-bounds
+     * index would crash on `blockToRemove.call(REMOVED)` (undefined.call),
+     * aborting the surrounding batch (e.g. a Yjs undo transaction) partway
+     * and leaving the flat array inconsistent with the DOM — exactly the
+     * soil that grows the wrong-block-dropped bug class. Reject nonsense
+     * indices at the lowest level instead of throwing.
+     */
+    if (removeIndex < 0 || removeIndex >= this.blocks.length) {
+      return;
+    }
+
     const blockToRemove = this.blocks[removeIndex];
 
     /**
@@ -311,10 +435,16 @@ export class Blocks {
    * Remove all blocks
    */
   public removeAll(): void {
-    this.workingArea.innerHTML = '';
-
-    this.blocks.forEach((block) => block.call(BlockToolAPI.REMOVED));
+    // Destroy each block so draggable listeners bound to shared DOM handles
+    // (e.g. the settings toggler) are released. Skipping destroy leaves stale
+    // mousedown handlers on the shared toggler, which later fire for whichever
+    // block is hovered and drags the wrong block.
+    this.blocks.forEach((block) => {
+      block.call(BlockToolAPI.REMOVED);
+      block.destroy();
+    });
 
+    this.workingArea.innerHTML = '';
     this.blocks.length = 0;
   }
 
@@ -327,6 +457,19 @@ export class Blocks {
   public insertAfter(targetBlock: Block, newBlock: Block): void {
     const index = this.blocks.indexOf(targetBlock);
 
+    /**
+     * Layer 14: stale target guard (regression: wrong-block-dropped family).
+     *
+     * Without this guard, a stale `targetBlock` makes `indexOf` return `-1`,
+     * then `insert(0, newBlock)` teleports the new block to the TOP of the
+     * document — the same symptom as wrong-block-dropped. insertAfter has
+     * no live callers today, but codifying the guard now prevents a future
+     * consumer from reintroducing the bug class through this entry point.
+     */
+    if (index === -1) {
+      return;
+    }
+
     this.insert(index + 1, newBlock);
   }
 
@@ -357,6 +500,16 @@ export class Blocks {
    * blocks exist in the array before any lifecycle hooks run.
    */
   public addToArray(index: number, block: Block): void {
+    /**
+     * Invalid-index guard (regression: wrong-block-dropped family).
+     * Same splice(-1, 0) vulnerability as Blocks.move/insert/insertMany.
+     * yjs-sync batch-add calls this during undo of hierarchical blocks;
+     * negative input would silently corrupt the flat array.
+     */
+    if (index < 0) {
+      return;
+    }
+
     const insertIndex = index > this.length ? this.length : index;
 
     this.blocks.splice(insertIndex, 0, block);
@@ -420,6 +573,39 @@ export class Blocks {
     block.call(BlockToolAPI.RENDERED);
   }
 
+  /**
+   * Place a single block's holder at workingArea root level. Finds the next
+   * top-level block at or after `insertIndex` in the flat array and inserts
+   * before it; falls back to appending to workingArea when no top-level
+   * sibling follows. Keeps DOM parent aligned with `parentId === null`.
+   */
+  private insertAtRootLevel(block: Block, insertIndex: number): void {
+    const nextTopLevel = this.blocks.slice(insertIndex + 1).find(
+      (b) => b.holder.parentElement === this.workingArea
+    );
+
+    if (nextTopLevel !== undefined) {
+      nextTopLevel.holder.insertAdjacentElement('beforebegin', block.holder);
+    } else {
+      this.workingArea.appendChild(block.holder);
+    }
+
+    /**
+     * Invariant: forceTopLevel insertion must land at workingArea root. If it
+     * does not, a future change broke the resolution logic above and the
+     * Enter-after-callout bug is one wrong neighbor away from reappearing.
+     * Fail loud and early so the regression cannot sneak in silently.
+     */
+    if (block.holder.parentElement !== this.workingArea) {
+      throw new Error(
+        '[Blocks.insertAtRootLevel] invariant violated: block holder did not land at workingArea root. ' +
+        'This indicates the Enter-after-callout regression guard is broken.'
+      );
+    }
+
+    block.call(BlockToolAPI.RENDERED);
+  }
+
   /**
    * When the previous block in the flat array is nested (e.g., a table cell
    * paragraph), inserting after its top-level ancestor would place content

package/src/components/modules/api/blocks.ts

@@ -442,10 +442,12 @@ export class BlocksAPI extends Module {
 
     const newBlock = this.Blok.BlockManager.insertInsideParent(parentId, insertIndex);
 
-    // Boundary after the atomic op so any deferred DOM callbacks stay in the same undo group.
-    queueMicrotask(() => {
-      this.Blok.YjsManager.stopCapturing();
-    });
+    // NOTE: Do NOT call stopCapturing in a trailing microtask. The operations layer
+    // uses extendThroughRAF on its atomic wrapper to keep isSyncingFromYjs true
+    // through the next RAF, suppressing any stray mutation-observer-driven Yjs
+    // writes from deferred DOM callbacks. A trailing stopCapturing would force
+    // those late writes into a SEPARATE undo group, splitting the insertion
+    // across two CMD+Z pops.
 
     return new BlockAPI(newBlock);
   };

package/src/components/modules/blockEvents/composers/keyboardNavigation.ts

@@ -230,9 +230,18 @@ export class KeyboardNavigation extends BlockEventComposer {
   }
 
   private createBlockOnEnter(currentBlock: Block): Block {
+    /**
+     * When the current block is top-level (parentId === null), pass forceTopLevel
+     * so the new block's DOM holder is anchored at workingArea root level even if
+     * the previous block in the flat array is nested inside a callout/toggle/table.
+     * Without this, insertAdjacentElement('afterend', previousBlock.holder) drops
+     * the new holder inside the nested container — the Enter-after-callout bug.
+     */
+    const isCurrentTopLevel = currentBlock.parentId === null;
+
     // Case 1: Caret at start - insert block above
     if (currentBlock.currentInput !== undefined && isCaretAtStartOfInput(currentBlock.currentInput) && !currentBlock.hasMedia && (currentBlock.parentId === null || !currentBlock.isEmpty)) {
-      const newBlock = this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex);
+      const newBlock = this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex, false, false, isCurrentTopLevel);
 
       /**
        * When the current block is a child of a toggle, the new block inserted above
@@ -258,19 +267,21 @@ export class KeyboardNavigation extends BlockEventComposer {
         return promotedBlock;
       }
 
-      const newBlock = this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex + 1);
-
       /**
        * When the current block is an open toggle (heading or list item),
        * the new block should become a child of the toggle rather than a sibling.
        * Detect via the data-blok-toggle-open DOM attribute set by toggle tools.
        *
-       * When the current block is already a child of a toggle, the new block
-       * should inherit the same parent so it stays inside the toggle.
+       * forceTopLevel is safe to pass only when the current block is top-level
+       * AND is not an open toggle (which intentionally nests the new block as its child).
        */
       const toggleWrapper = currentBlock.holder.querySelector('[data-blok-toggle-open]');
+      const isToggleOpen = toggleWrapper?.getAttribute('data-blok-toggle-open') === 'true';
+      const forceTopLevelCase2 = isCurrentTopLevel && !isToggleOpen;
+
+      const newBlock = this.Blok.BlockManager.insertDefaultBlockAtIndex(this.Blok.BlockManager.currentBlockIndex + 1, false, false, forceTopLevelCase2);
 
-      if (toggleWrapper?.getAttribute('data-blok-toggle-open') === 'true') {
+      if (isToggleOpen) {
         this.Blok.BlockManager.setBlockParent(newBlock, currentBlock.id);
       } else if (currentBlock.parentId !== null && newBlock.parentId !== currentBlock.parentId) {
         this.Blok.BlockManager.setBlockParent(newBlock, currentBlock.parentId);