@craftile/core 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftile/core",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Framework-agnostic block editor engine for Craftile",
   "keywords": [
     "craftile",
@@ -26,8 +26,8 @@
     "src"
   ],
   "dependencies": {
-    "@craftile/event-bus": "1.2.1",
-    "@craftile/types": "1.2.1"
+    "@craftile/event-bus": "1.3.0",
+    "@craftile/types": "1.3.0"
   },
   "devDependencies": {
     "vitest": "^3.2.4",

package/src/commands/duplicate-block.ts

@@ -9,7 +9,7 @@ export interface DuplicateBlockOptions {
 }
 
 export class DuplicateBlockCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
 
   // State for reverting
@@ -20,25 +20,31 @@ export class DuplicateBlockCommand implements Command {
   private regionId?: string | null;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: DuplicateBlockOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: DuplicateBlockOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.emit = options.emit;
   }
 
   apply(): void {
-    const originalBlock = this.page.blocks[this.blockId];
+    const page = this.getPage();
+    const originalBlock = page.blocks[this.blockId];
     if (!originalBlock) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
     this.duplicatedBlockId = generateId();
 
-    this.duplicatedBlock = this.cloneBlockWithNewIds(originalBlock, this.duplicatedBlockId, originalBlock.parentId);
+    this.duplicatedBlock = this.cloneBlockWithNewIds(
+      page,
+      originalBlock,
+      this.duplicatedBlockId,
+      originalBlock.parentId
+    );
 
-    this.determineInsertLocation();
+    this.determineInsertLocation(page);
 
-    this.insertDuplicatedBlock();
+    this.insertDuplicatedBlock(page);
 
     this.emit('block:duplicate', {
       originalBlockId: this.blockId,
@@ -55,7 +61,7 @@ export class DuplicateBlockCommand implements Command {
       return;
     }
 
-    this.removeDuplicatedBlock();
+    this.removeDuplicatedBlock(this.getPage());
   }
 
   getBlockId(): string {
@@ -82,7 +88,7 @@ export class DuplicateBlockCommand implements Command {
     return this.regionId;
   }
 
-  private cloneBlockWithNewIds(block: Block, newId: string, newParentId?: string): Block {
+  private cloneBlockWithNewIds(page: Page, block: Block, newId: string, newParentId?: string): Block {
     const clonedBlock: Block = {
       ...structuredClone(block),
       id: newId,
@@ -92,27 +98,27 @@ export class DuplicateBlockCommand implements Command {
 
     if (block.children && block.children.length > 0) {
       for (const childId of block.children) {
-        const childBlock = this.page.blocks[childId];
+        const childBlock = page.blocks[childId];
         if (childBlock) {
           const newChildId = generateId();
-          this.cloneBlockWithNewIds(childBlock, newChildId, newId);
+          this.cloneBlockWithNewIds(page, childBlock, newChildId, newId);
           clonedBlock.children.push(newChildId);
         }
       }
     }
 
-    this.page.blocks[newId] = clonedBlock;
+    page.blocks[newId] = clonedBlock;
 
     return clonedBlock;
   }
 
-  private determineInsertLocation(): void {
-    const originalBlock = this.page.blocks[this.blockId];
+  private determineInsertLocation(page: Page): void {
+    const originalBlock = page.blocks[this.blockId];
 
     this.parentId = originalBlock.parentId || null;
 
     if (this.parentId) {
-      const parent = this.page.blocks[this.parentId];
+      const parent = page.blocks[this.parentId];
       if (parent) {
         const index = parent.children.indexOf(this.blockId);
         this.insertIndex = index !== -1 ? index + 1 : parent.children.length;
@@ -120,52 +126,52 @@ export class DuplicateBlockCommand implements Command {
         this.insertIndex = 0;
       }
     } else {
-      const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
+      const region = page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         const index = region.blocks.indexOf(this.blockId);
         this.regionId = getRegionId(region);
         this.insertIndex = index + 1;
       } else {
-        this.regionId = getRegionId(this.page.regions[0]) || 'main';
-        this.insertIndex = this.page.regions[0].blocks.length || 0;
+        this.regionId = getRegionId(page.regions[0]) || 'main';
+        this.insertIndex = page.regions[0].blocks.length || 0;
       }
     }
   }
 
-  private insertDuplicatedBlock(): void {
+  private insertDuplicatedBlock(page: Page): void {
     if (!this.duplicatedBlock) {
       return;
     }
 
     if (this.parentId) {
-      const targetParent = this.page.blocks[this.parentId];
+      const targetParent = page.blocks[this.parentId];
       if (!targetParent) {
         throw new Error(`Parent block not found: ${this.parentId}`);
       }
 
       targetParent.children.splice(this.insertIndex, 0, this.duplicatedBlockId);
     } else {
-      let targetRegion = this.page.regions.find((r) => getRegionId(r) === this.regionId);
+      let targetRegion = page.regions.find((r) => getRegionId(r) === this.regionId);
 
       if (!targetRegion) {
         targetRegion = { name: this.regionId || 'main', blocks: [] };
-        this.page.regions.push(targetRegion);
+        page.regions.push(targetRegion);
       }
 
       targetRegion.blocks.splice(this.insertIndex, 0, this.duplicatedBlockId);
     }
   }
 
-  private removeDuplicatedBlock(): void {
+  private removeDuplicatedBlock(page: Page): void {
     if (!this.duplicatedBlockId) {
       return;
     }
 
-    this.removeBlockAndChildren(this.duplicatedBlockId);
+    this.removeBlockAndChildren(page, this.duplicatedBlockId);
 
     if (this.parentId) {
       // Remove from parent's children array
-      const targetParent = this.page.blocks[this.parentId];
+      const targetParent = page.blocks[this.parentId];
       if (targetParent) {
         const index = targetParent.children.indexOf(this.duplicatedBlockId);
         if (index !== -1) {
@@ -174,8 +180,8 @@ export class DuplicateBlockCommand implements Command {
       }
     } else {
       // Remove from region
-      if (this.page.regions) {
-        const targetRegion = this.page.regions.find((r) => getRegionId(r) === this.regionId);
+      if (page.regions) {
+        const targetRegion = page.regions.find((r) => getRegionId(r) === this.regionId);
         if (targetRegion) {
           const index = targetRegion.blocks.indexOf(this.duplicatedBlockId);
           if (index !== -1) {
@@ -186,16 +192,16 @@ export class DuplicateBlockCommand implements Command {
     }
   }
 
-  private removeBlockAndChildren(blockId: string): void {
-    const block = this.page.blocks[blockId];
+  private removeBlockAndChildren(page: Page, blockId: string): void {
+    const block = page.blocks[blockId];
     if (!block) {
       return;
     }
 
     for (const childId of block.children) {
-      this.removeBlockAndChildren(childId);
+      this.removeBlockAndChildren(page, childId);
     }
 
-    delete this.page.blocks[blockId];
+    delete page.blocks[blockId];
   }
 }

package/src/commands/insert-block-from-preset.ts

@@ -15,7 +15,7 @@ export interface InsertBlockFromPresetOptions {
 }
 
 export class InsertBlockFromPresetCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockType: string;
   private presetIndex?: number;
   private presetData?: BlockStructure;
@@ -31,8 +31,8 @@ export class InsertBlockFromPresetCommand implements Command {
   private emit: EngineEmitFn;
   private createdBlockIds: string[] = [];
 
-  constructor(page: Page, options: InsertBlockFromPresetOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: InsertBlockFromPresetOptions) {
+    this.getPage = getPage;
     this.blockType = options.blockType;
     this.presetIndex = options.presetIndex;
     this.presetData = options.presetData;
@@ -69,7 +69,8 @@ export class InsertBlockFromPresetCommand implements Command {
   }
 
   apply(): void {
-    const target = resolveInsertTarget(this.page, this.parentId, this.regionId, this.index);
+    const page = this.getPage();
+    const target = resolveInsertTarget(page, this.parentId, this.regionId, this.index);
     this.resolvedRegionId = target.kind === 'region' ? target.regionId : undefined;
 
     const blockSchema = this.blocksManager.get(this.blockType);
@@ -86,11 +87,11 @@ export class InsertBlockFromPresetCommand implements Command {
         parentId: undefined,
       };
 
-      this.page.blocks[this.blockId] = this.insertedBlock;
+      page.blocks[this.blockId] = this.insertedBlock;
       this.createdBlockIds.push(this.blockId);
 
       if (this.presetData.children && this.presetData.children.length > 0) {
-        this.insertedBlock.children = this.createChildrenFromPreset(this.presetData.children, this.blockId);
+        this.insertedBlock.children = this.createChildrenFromPreset(page, this.presetData.children, this.blockId);
       }
     } else if (this.presetIndex !== undefined) {
       const preset = blockSchema?.presets?.[this.presetIndex];
@@ -107,11 +108,11 @@ export class InsertBlockFromPresetCommand implements Command {
         parentId: undefined,
       };
 
-      this.page.blocks[this.blockId] = this.insertedBlock;
+      page.blocks[this.blockId] = this.insertedBlock;
       this.createdBlockIds.push(this.blockId);
 
       if (preset.children && preset.children.length > 0) {
-        this.insertedBlock.children = this.createChildrenFromPreset(preset.children, this.blockId);
+        this.insertedBlock.children = this.createChildrenFromPreset(page, preset.children, this.blockId);
       }
     }
 
@@ -125,7 +126,7 @@ export class InsertBlockFromPresetCommand implements Command {
       this.insertedBlock.parentId = target.parent.id;
       target.parent.children.splice(target.index, 0, this.blockId);
     } else {
-      const region = this.page.regions.find((r) => getRegionId(r) === target.regionId)!;
+      const region = page.regions.find((r) => getRegionId(r) === target.regionId)!;
       region.blocks.splice(target.index, 0, this.blockId);
     }
 
@@ -134,7 +135,7 @@ export class InsertBlockFromPresetCommand implements Command {
       block: this.insertedBlock,
       parentId: this.parentId,
       index: this.actualIndex,
-      regionId: this.regionId || getRegionId(this.page.regions[0]),
+      regionId: this.regionId || getRegionId(page.regions[0]),
     });
   }
 
@@ -143,21 +144,24 @@ export class InsertBlockFromPresetCommand implements Command {
       return;
     }
 
+    const page = this.getPage();
+
     // Remove all created blocks
     for (const blockId of this.createdBlockIds) {
-      delete this.page.blocks[blockId];
+      delete page.blocks[blockId];
     }
 
     if (this.parentId) {
-      const parent = this.page.blocks[this.parentId];
-      if (parent && this.actualIndex !== undefined) {
-        parent.children.splice(this.actualIndex, 1);
+      const parent = page.blocks[this.parentId];
+      const index = parent ? parent.children.indexOf(this.blockId) : -1;
+      if (parent && index !== -1) {
+        parent.children.splice(index, 1);
       }
     } else if (this.resolvedRegionId) {
-      const targetRegion = this.page.regions.find((r) => getRegionId(r) === this.resolvedRegionId);
-
-      if (targetRegion && this.actualIndex !== undefined) {
-        targetRegion.blocks.splice(this.actualIndex, 1);
+      const targetRegion = page.regions.find((r) => getRegionId(r) === this.resolvedRegionId);
+      const index = targetRegion ? targetRegion.blocks.indexOf(this.blockId) : -1;
+      if (targetRegion && index !== -1) {
+        targetRegion.blocks.splice(index, 1);
       }
     }
 
@@ -177,7 +181,7 @@ export class InsertBlockFromPresetCommand implements Command {
     return this.insertedBlock;
   }
 
-  private createChildrenFromPreset(structures: BlockStructure[], parentId: string): string[] {
+  private createChildrenFromPreset(page: Page, structures: BlockStructure[], parentId: string): string[] {
     const childIds: string[] = [];
 
     for (const structure of structures) {
@@ -202,12 +206,12 @@ export class InsertBlockFromPresetCommand implements Command {
         parentId,
       };
 
-      this.page.blocks[childId] = childBlock;
+      page.blocks[childId] = childBlock;
       this.createdBlockIds.push(childId);
 
       // Recursively create nested children
       if (structure.children && structure.children.length > 0) {
-        childBlock.children = this.createChildrenFromPreset(structure.children, childId);
+        childBlock.children = this.createChildrenFromPreset(page, structure.children, childId);
       }
 
       childIds.push(childId);

package/src/commands/insert-block.ts

@@ -13,7 +13,7 @@ export interface InsertBlockOptions {
 }
 
 export class InsertBlockCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockType: string;
   private parentId?: string;
   private regionId?: string;
@@ -26,8 +26,8 @@ export class InsertBlockCommand implements Command {
   private resolvedRegionId?: string;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: InsertBlockOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: InsertBlockOptions) {
+    this.getPage = getPage;
     this.blockType = options.blockType;
     this.parentId = options.parentId;
     this.regionId = options.regionId;
@@ -40,7 +40,8 @@ export class InsertBlockCommand implements Command {
   }
 
   apply(): void {
-    const target = resolveInsertTarget(this.page, this.parentId, this.regionId, this.index);
+    const page = this.getPage();
+    const target = resolveInsertTarget(page, this.parentId, this.regionId, this.index);
     this.resolvedRegionId = target.kind === 'region' ? target.regionId : undefined;
 
     const blockName = this.blockSchema?.meta?.name || this.blockType;
@@ -54,14 +55,14 @@ export class InsertBlockCommand implements Command {
       parentId: undefined,
     };
 
-    this.page.blocks[this.blockId] = this.insertedBlock;
+    page.blocks[this.blockId] = this.insertedBlock;
     this.actualIndex = target.index;
 
     if (target.kind === 'parent') {
       this.insertedBlock.parentId = target.parent.id;
       target.parent.children.splice(target.index, 0, this.blockId);
     } else {
-      const region = this.page.regions.find((r) => getRegionId(r) === target.regionId)!;
+      const region = page.regions.find((r) => getRegionId(r) === target.regionId)!;
       region.blocks.splice(target.index, 0, this.blockId);
     }
 
@@ -70,7 +71,7 @@ export class InsertBlockCommand implements Command {
       block: this.insertedBlock,
       parentId: this.parentId,
       index: this.actualIndex,
-      regionId: this.regionId || getRegionId(this.page.regions[0]),
+      regionId: this.regionId || getRegionId(page.regions[0]),
     });
   }
 
@@ -79,18 +80,21 @@ export class InsertBlockCommand implements Command {
       return;
     }
 
-    delete this.page.blocks[this.blockId];
+    const page = this.getPage();
+
+    delete page.blocks[this.blockId];
 
     if (this.parentId) {
-      const parent = this.page.blocks[this.parentId];
-      if (parent && this.actualIndex !== undefined) {
-        parent.children.splice(this.actualIndex, 1);
+      const parent = page.blocks[this.parentId];
+      const index = parent ? parent.children.indexOf(this.blockId) : -1;
+      if (parent && index !== -1) {
+        parent.children.splice(index, 1);
       }
     } else if (this.resolvedRegionId) {
-      const targetRegion = this.page.regions.find((r) => getRegionId(r) === this.resolvedRegionId);
-
-      if (targetRegion && this.actualIndex !== undefined) {
-        targetRegion.blocks.splice(this.actualIndex, 1);
+      const targetRegion = page.regions.find((r) => getRegionId(r) === this.resolvedRegionId);
+      const index = targetRegion ? targetRegion.blocks.indexOf(this.blockId) : -1;
+      if (targetRegion && index !== -1) {
+        targetRegion.blocks.splice(index, 1);
       }
     }
 

package/src/commands/move-block.ts

@@ -1,4 +1,4 @@
-import type { Block, Page } from '@craftile/types';
+import type { Page } from '@craftile/types';
 import type { Command, EngineEmitFn } from '../types';
 import type { ResolvedTarget } from '../utils';
 import { canInsertDynamicChildAt, clampIndex, getRegionId, resolveRegionId } from '../utils';
@@ -12,22 +12,22 @@ export interface MoveBlockOptions {
 }
 
 export class MoveBlockCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
   private targetParentId?: string;
   private targetIndex?: number;
   private targetRegionId?: string;
 
   // State for reverting
-  private blockToMove?: Block;
+  private moved = false;
   private originalParentId?: string;
   private originalIndex!: number;
   private originalRegionId?: string;
 
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: MoveBlockOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: MoveBlockOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.targetParentId = options.targetParentId;
     this.targetIndex = options.targetIndex;
@@ -36,29 +36,37 @@ export class MoveBlockCommand implements Command {
   }
 
   apply(): void {
-    const target = this.validateAndResolveTarget();
+    const page = this.getPage();
+    const blockToMove = page.blocks[this.blockId];
+    if (!blockToMove) {
+      throw new Error(`Block not found: ${this.blockId}`);
+    }
+
+    const target = this.validateAndResolveTarget(page);
 
     if (this.originalParentId) {
-      const sourceParent = this.page.blocks[this.originalParentId];
+      const sourceParent = page.blocks[this.originalParentId];
       if (sourceParent && this.originalIndex !== -1) {
         sourceParent.children.splice(this.originalIndex, 1);
       }
     } else if (this.originalRegionId) {
-      const sourceRegion = this.page.regions.find((r) => getRegionId(r) === this.originalRegionId);
+      const sourceRegion = page.regions.find((r) => getRegionId(r) === this.originalRegionId);
       if (sourceRegion && this.originalIndex !== -1) {
         sourceRegion.blocks.splice(this.originalIndex, 1);
       }
     }
 
     if (target.kind === 'parent') {
-      this.blockToMove!.parentId = target.parent.id;
+      blockToMove.parentId = target.parent.id;
       target.parent.children.splice(target.index, 0, this.blockId);
     } else {
-      this.blockToMove!.parentId = undefined;
-      const region = this.page.regions.find((r) => getRegionId(r) === target.regionId)!;
+      blockToMove.parentId = undefined;
+      const region = page.regions.find((r) => getRegionId(r) === target.regionId)!;
       region.blocks.splice(target.index, 0, this.blockId);
     }
 
+    this.moved = true;
+
     this.emit('block:move', {
       blockId: this.blockId,
       targetParentId: this.targetParentId,
@@ -76,18 +84,19 @@ export class MoveBlockCommand implements Command {
    * Captures the source position too so `revert()` can restore it. Pure read —
    * does not mutate `page`.
    */
-  private validateAndResolveTarget(): ResolvedTarget {
-    this.blockToMove = this.page.blocks[this.blockId];
-    if (!this.blockToMove) {
+  private validateAndResolveTarget(page: Page): ResolvedTarget {
+    const blockToMove = page.blocks[this.blockId];
+    if (!blockToMove) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
-    this.originalParentId = this.blockToMove.parentId;
+    this.originalParentId = blockToMove.parentId;
+    this.originalRegionId = undefined;
     if (this.originalParentId) {
-      const sourceParent = this.page.blocks[this.originalParentId];
+      const sourceParent = page.blocks[this.originalParentId];
       this.originalIndex = sourceParent ? sourceParent.children.indexOf(this.blockId) : -1;
     } else {
-      const sourceRegion = this.page.regions.find((r) => r.blocks.includes(this.blockId));
+      const sourceRegion = page.regions.find((r) => r.blocks.includes(this.blockId));
       if (sourceRegion) {
         this.originalRegionId = getRegionId(sourceRegion);
         this.originalIndex = sourceRegion.blocks.indexOf(this.blockId);
@@ -97,7 +106,7 @@ export class MoveBlockCommand implements Command {
     }
 
     if (this.targetParentId) {
-      const parent = this.page.blocks[this.targetParentId];
+      const parent = page.blocks[this.targetParentId];
       if (!parent) {
         throw new Error(`Target parent not found: ${this.targetParentId}`);
       }
@@ -106,7 +115,7 @@ export class MoveBlockCommand implements Command {
       const prospective = sourceIsTarget ? parent.children.filter((id) => id !== this.blockId) : parent.children;
       const index = clampIndex(prospective.length, this.targetIndex);
 
-      if (!canInsertDynamicChildAt(prospective, this.page.blocks, index)) {
+      if (!canInsertDynamicChildAt(prospective, page.blocks, index)) {
         throw new Error(
           `Cannot place at index ${index} of ${this.targetParentId}: not a valid slot for a dynamic child`
         );
@@ -115,8 +124,8 @@ export class MoveBlockCommand implements Command {
       return { kind: 'parent', parent, index };
     }
 
-    const regionId = resolveRegionId(this.page, this.targetRegionId);
-    const existing = this.page.regions.find((r) => getRegionId(r) === regionId);
+    const regionId = resolveRegionId(page, this.targetRegionId);
+    const existing = page.regions.find((r) => getRegionId(r) === regionId);
     if (!existing) {
       throw new Error(`Region not found: ${regionId}`);
     }
@@ -128,12 +137,18 @@ export class MoveBlockCommand implements Command {
   }
 
   revert(): void {
-    if (!this.blockToMove || this.originalIndex === undefined) {
+    if (!this.moved || this.originalIndex === undefined) {
+      return;
+    }
+
+    const page = this.getPage();
+    const blockToMove = page.blocks[this.blockId];
+    if (!blockToMove) {
       return;
     }
 
-    if (this.blockToMove.parentId) {
-      const currentParent = this.page.blocks[this.blockToMove.parentId];
+    if (blockToMove.parentId) {
+      const currentParent = page.blocks[blockToMove.parentId];
       if (currentParent) {
         const index = currentParent.children.indexOf(this.blockId);
         if (index !== -1) {
@@ -141,7 +156,7 @@ export class MoveBlockCommand implements Command {
         }
       }
     } else {
-      const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
+      const region = page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         const index = region.blocks.indexOf(this.blockId);
         if (index !== -1) {
@@ -150,15 +165,15 @@ export class MoveBlockCommand implements Command {
       }
     }
 
-    this.blockToMove.parentId = this.originalParentId;
+    blockToMove.parentId = this.originalParentId;
 
     if (this.originalParentId) {
-      const originalParent = this.page.blocks[this.originalParentId];
+      const originalParent = page.blocks[this.originalParentId];
       if (originalParent) {
         originalParent.children.splice(this.originalIndex, 0, this.blockId);
       }
     } else if (this.originalRegionId) {
-      const region = this.page.regions.find((r) => getRegionId(r) === this.originalRegionId);
+      const region = page.regions.find((r) => getRegionId(r) === this.originalRegionId);
       if (region) {
         region.blocks.splice(this.originalIndex, 0, this.blockId);
       }

package/src/commands/remove-block.ts

@@ -8,7 +8,7 @@ export interface RemoveBlockOptions {
 }
 
 export class RemoveBlockCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
   private removedBlock?: Block;
   private originalIndex?: number;
@@ -16,14 +16,15 @@ export class RemoveBlockCommand implements Command {
   private regionId?: string;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: RemoveBlockOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: RemoveBlockOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.emit = options.emit;
   }
 
   apply(): void {
-    this.removedBlock = this.page.blocks[this.blockId];
+    const page = this.getPage();
+    this.removedBlock = page.blocks[this.blockId];
 
     if (!this.removedBlock) {
       throw new Error(`Block not found: ${this.blockId}`);
@@ -32,7 +33,7 @@ export class RemoveBlockCommand implements Command {
     this.originalParentId = this.removedBlock.parentId;
 
     if (this.originalParentId) {
-      const parent = this.page.blocks[this.originalParentId];
+      const parent = page.blocks[this.originalParentId];
       if (parent) {
         this.originalIndex = parent.children.indexOf(this.blockId);
         if (this.originalIndex !== -1) {
@@ -40,7 +41,7 @@ export class RemoveBlockCommand implements Command {
         }
       }
     } else {
-      const region = this.page.regions.find((r) => r.blocks.includes(this.blockId));
+      const region = page.regions.find((r) => r.blocks.includes(this.blockId));
       if (region) {
         this.originalIndex = region.blocks.indexOf(this.blockId);
         this.regionId = getRegionId(region);
@@ -48,7 +49,7 @@ export class RemoveBlockCommand implements Command {
       }
     }
 
-    delete this.page.blocks[this.blockId];
+    delete page.blocks[this.blockId];
 
     this.emit('block:remove', {
       blockId: this.blockId,
@@ -63,15 +64,17 @@ export class RemoveBlockCommand implements Command {
       return;
     }
 
-    this.page.blocks[this.blockId] = this.removedBlock;
+    const page = this.getPage();
+
+    page.blocks[this.blockId] = this.removedBlock;
 
     if (this.originalParentId) {
-      const parent = this.page.blocks[this.originalParentId];
+      const parent = page.blocks[this.originalParentId];
       if (parent) {
         parent.children.splice(this.originalIndex, 0, this.blockId);
       }
     } else if (this.regionId) {
-      const region = this.page.regions.find((r) => getRegionId(r) === this.regionId);
+      const region = page.regions.find((r) => getRegionId(r) === this.regionId);
       if (region) {
         region.blocks.splice(this.originalIndex, 0, this.blockId);
       }

package/src/commands/replace-region.ts

@@ -11,7 +11,7 @@ export interface ReplaceRegionOptions {
 }
 
 export class ReplaceRegionCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private regionId: string;
   private regionIndex: number;
   private previousRegion: Page['regions'][number];
@@ -21,19 +21,21 @@ export class ReplaceRegionCommand implements Command {
   private emit: EngineEmitFn;
   private blocksManager: BlocksManager;
 
-  constructor(page: Page, options: ReplaceRegionOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: ReplaceRegionOptions) {
+    this.getPage = getPage;
     this.regionId = options.regionId;
     this.blocksManager = options.blocksManager;
     this.emit = options.emit;
 
-    this.regionIndex = this.page.regions.findIndex((region) => getRegionId(region) === this.regionId);
+    const page = this.getPage();
+
+    this.regionIndex = page.regions.findIndex((region) => getRegionId(region) === this.regionId);
     if (this.regionIndex === -1) {
       throw new Error(`Region not found: ${this.regionId}`);
     }
 
-    this.previousRegion = structuredClone(this.page.regions[this.regionIndex]);
-    this.removedBlocks = this.collectBlocksForRoots(this.previousRegion.blocks);
+    this.previousRegion = structuredClone(page.regions[this.regionIndex]);
+    this.removedBlocks = this.collectBlocksForRoots(page, this.previousRegion.blocks);
 
     this.newBlocks = {};
     const newRootIds = options.structures.map((structure) =>
@@ -97,11 +99,11 @@ export class ReplaceRegionCommand implements Command {
     return builtProperties;
   }
 
-  private collectBlocksForRoots(rootBlockIds: string[]): Record<string, Block> {
+  private collectBlocksForRoots(page: Page, rootBlockIds: string[]): Record<string, Block> {
     const blocks: Record<string, Block> = {};
 
     const collectBlock = (blockId: string) => {
-      const block = this.page.blocks[blockId];
+      const block = page.blocks[blockId];
       if (!block || blocks[blockId]) {
         return;
       }
@@ -121,15 +123,17 @@ export class ReplaceRegionCommand implements Command {
     removedBlocks: Record<string, Block>,
     newBlocks: Record<string, Block>
   ): void {
+    const page = this.getPage();
+
     Object.keys(removedBlocks).forEach((blockId) => {
-      delete this.page.blocks[blockId];
+      delete page.blocks[blockId];
     });
 
     Object.entries(newBlocks).forEach(([blockId, block]) => {
-      this.page.blocks[blockId] = block;
+      page.blocks[blockId] = block;
     });
 
-    this.page.regions[this.regionIndex] = newRegion;
+    page.regions[this.regionIndex] = newRegion;
 
     this.emit('region:replace', {
       regionId: this.regionId,

package/src/commands/set-block-name.ts

@@ -1,4 +1,4 @@
-import type { Block, Page } from '@craftile/types';
+import type { Page } from '@craftile/types';
 import type { Command, EngineEmitFn } from '../types';
 
 export interface SetBlockNameOptions {
@@ -8,37 +8,39 @@ export interface SetBlockNameOptions {
 }
 
 export class SetBlockNameCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
   private newName: string;
   private oldName: string | undefined;
-  private block: Block | undefined;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: SetBlockNameOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: SetBlockNameOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.newName = options.name;
     this.emit = options.emit;
-    this.block = this.page.blocks[this.blockId];
 
-    if (!this.block) {
+    const block = this.getPage().blocks[this.blockId];
+
+    if (!block) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
-    this.oldName = this.block.name;
+    this.oldName = block.name;
   }
 
   apply(): void {
-    if (!this.block) {
+    const block = this.getPage().blocks[this.blockId];
+
+    if (!block) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
-    this.block.name = this.newName;
+    block.name = this.newName;
 
     this.emit('block:update', {
       blockId: this.blockId,
-      block: this.block,
+      block,
       property: 'name',
       value: this.newName,
       oldValue: this.oldName,
@@ -46,15 +48,17 @@ export class SetBlockNameCommand implements Command {
   }
 
   revert(): void {
-    if (!this.block) {
+    const block = this.getPage().blocks[this.blockId];
+
+    if (!block) {
       return;
     }
 
-    this.block.name = this.oldName;
+    block.name = this.oldName;
 
     this.emit('block:update', {
       blockId: this.blockId,
-      block: this.block,
+      block,
       property: 'name',
       value: this.oldName,
       oldValue: this.newName,

package/src/commands/set-block-property.ts

@@ -1,4 +1,4 @@
-import type { Block, Page } from '@craftile/types';
+import type { Page } from '@craftile/types';
 import type { Command, EngineEmitFn } from '../types';
 
 export interface SetBlockPropertyOptions {
@@ -9,16 +9,15 @@ export interface SetBlockPropertyOptions {
 }
 
 export class SetBlockPropertyCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
   private propertyKey: string;
   private propertyValue: any;
   private originalValue: any;
-  private block?: Block;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: SetBlockPropertyOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: SetBlockPropertyOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.propertyKey = options.propertyKey;
     this.propertyValue = options.propertyValue;
@@ -26,18 +25,18 @@ export class SetBlockPropertyCommand implements Command {
   }
 
   apply(): void {
-    this.block = this.page.blocks[this.blockId];
+    const block = this.getPage().blocks[this.blockId];
 
-    if (!this.block) {
+    if (!block) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
-    if (!this.block.properties) {
-      this.block.properties = {};
+    if (!block.properties) {
+      block.properties = {};
     }
 
-    this.originalValue = this.block.properties[this.propertyKey];
-    this.block.properties[this.propertyKey] = this.propertyValue;
+    this.originalValue = block.properties[this.propertyKey];
+    block.properties[this.propertyKey] = this.propertyValue;
 
     this.emit('block:property:set', {
       blockId: this.blockId,
@@ -48,14 +47,16 @@ export class SetBlockPropertyCommand implements Command {
   }
 
   revert(): void {
-    if (!this.block || !this.block.properties) {
+    const block = this.getPage().blocks[this.blockId];
+
+    if (!block || !block.properties) {
       return;
     }
 
     if (this.originalValue !== undefined) {
-      this.block.properties[this.propertyKey] = this.originalValue;
+      block.properties[this.propertyKey] = this.originalValue;
     } else {
-      delete this.block.properties[this.propertyKey];
+      delete block.properties[this.propertyKey];
     }
 
     this.emit('block:property:set', {

package/src/commands/toggle-block.ts

@@ -1,4 +1,4 @@
-import type { Block, Page } from '@craftile/types';
+import type { Page } from '@craftile/types';
 import type { Command, EngineEmitFn } from '../types';
 
 export interface ToggleBlockOptions {
@@ -8,56 +8,60 @@ export interface ToggleBlockOptions {
 }
 
 export class ToggleBlockCommand implements Command {
-  private page: Page;
+  private getPage: () => Page;
   private blockId: string;
   private targetDisabled?: boolean;
   private originalDisabled?: boolean;
-  private block?: Block;
+  private newDisabled?: boolean;
   private emit: EngineEmitFn;
 
-  constructor(page: Page, options: ToggleBlockOptions) {
-    this.page = page;
+  constructor(getPage: () => Page, options: ToggleBlockOptions) {
+    this.getPage = getPage;
     this.blockId = options.blockId;
     this.targetDisabled = options.disabled;
     this.emit = options.emit;
   }
 
   apply(): void {
-    this.block = this.page.blocks[this.blockId];
+    const block = this.getPage().blocks[this.blockId];
 
-    if (!this.block) {
+    if (!block) {
       throw new Error(`Block not found: ${this.blockId}`);
     }
 
-    this.originalDisabled = this.block.disabled;
+    this.originalDisabled = block.disabled;
 
     if (this.targetDisabled !== undefined) {
-      this.block.disabled = this.targetDisabled;
+      block.disabled = this.targetDisabled;
     } else {
-      this.block.disabled = !this.block.disabled;
+      block.disabled = !block.disabled;
     }
 
+    this.newDisabled = block.disabled;
+
     this.emit('block:toggle', {
       blockId: this.blockId,
-      disabled: this.block.disabled ?? false,
+      disabled: block.disabled ?? false,
       oldValue: this.originalDisabled,
     });
   }
 
   revert(): void {
-    if (!this.block) {
+    const block = this.getPage().blocks[this.blockId];
+
+    if (!block) {
       return;
     }
 
     if (this.originalDisabled !== undefined) {
-      this.block.disabled = this.originalDisabled;
+      block.disabled = this.originalDisabled;
     } else {
-      this.block.disabled = !this.block.disabled;
+      block.disabled = !block.disabled;
     }
 
     this.emit('block:toggle', {
       blockId: this.blockId,
-      disabled: this.block.disabled ?? false,
+      disabled: block.disabled ?? false,
       oldValue: this.targetDisabled !== undefined ? this.targetDisabled : !this.originalDisabled,
     });
   }
@@ -71,6 +75,6 @@ export class ToggleBlockCommand implements Command {
   }
 
   getNewDisabled(): boolean | undefined {
-    return this.block?.disabled;
+    return this.newDisabled;
   }
 }

package/src/engine.ts

@@ -3,6 +3,7 @@ import type { Command, EngineConfig, EngineEvents } from './types';
 import type { Block, BlockSchema, BlockStructure, Page } from '@craftile/types';
 import { BlocksManager } from './blocks-manager';
 import { HistoryManager } from './history-manager';
+import { collectVanishedDescendants } from './utils';
 import { BatchCommand } from './commands/batch';
 import { InsertBlockCommand } from './commands/insert-block';
 import { InsertBlockFromPresetCommand } from './commands/insert-block-from-preset';
@@ -71,7 +72,7 @@ export class Engine extends EventBus<EngineEvents> {
       }
     }
 
-    const command = new InsertBlockCommand(this.page, {
+    const command = new InsertBlockCommand(this.getLivePage, {
       blockType,
       parentId: options?.parentId,
       regionId: options?.regionId,
@@ -127,7 +128,7 @@ export class Engine extends EventBus<EngineEvents> {
       }
     }
 
-    const command = new InsertBlockFromPresetCommand(this.page, {
+    const command = new InsertBlockFromPresetCommand(this.getLivePage, {
       blockType,
       presetIndex,
       parentId: options?.parentId,
@@ -150,7 +151,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @emits block:remove - When the block is successfully removed
    */
   removeBlock(blockId: string): void {
-    const command = new RemoveBlockCommand(this.page, {
+    const command = new RemoveBlockCommand(this.getLivePage, {
       blockId,
       emit: this.emit.bind(this),
     });
@@ -188,7 +189,7 @@ export class Engine extends EventBus<EngineEvents> {
       }
     }
 
-    const command = new MoveBlockCommand(this.page, {
+    const command = new MoveBlockCommand(this.getLivePage, {
       blockId,
       targetParentId: options?.targetParentId,
       targetIndex: options?.targetIndex,
@@ -203,7 +204,7 @@ export class Engine extends EventBus<EngineEvents> {
    * Toggle a block's disabled state (enable/disable)
    */
   toggleBlock(blockId: string, disabled?: boolean): void {
-    const command = new ToggleBlockCommand(this.page, {
+    const command = new ToggleBlockCommand(this.getLivePage, {
       blockId,
       disabled,
       emit: this.emit.bind(this),
@@ -222,7 +223,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @emits block:property:set - When the property is successfully set
    */
   setBlockProperty(blockId: string, propertyKey: string, propertyValue: any): void {
-    const command = new SetBlockPropertyCommand(this.page, {
+    const command = new SetBlockPropertyCommand(this.getLivePage, {
       blockId,
       propertyKey,
       propertyValue,
@@ -241,7 +242,7 @@ export class Engine extends EventBus<EngineEvents> {
    * @emits block:update - When the name is successfully set
    */
   setBlockName(blockId: string, name: string): void {
-    const command = new SetBlockNameCommand(this.page, {
+    const command = new SetBlockNameCommand(this.getLivePage, {
       blockId,
       name,
       emit: this.emit.bind(this),
@@ -254,7 +255,7 @@ export class Engine extends EventBus<EngineEvents> {
    * Duplicate a block (creates a copy placed right after the original)
    */
   duplicateBlock(blockId: string): string {
-    const command = new DuplicateBlockCommand(this.page, {
+    const command = new DuplicateBlockCommand(this.getLivePage, {
       blockId,
       emit: this.emit.bind(this),
     });
@@ -327,7 +328,7 @@ export class Engine extends EventBus<EngineEvents> {
       }
     }
 
-    const command = new InsertBlockFromPresetCommand(this.page, {
+    const command = new InsertBlockFromPresetCommand(this.getLivePage, {
       blockType: structure.type,
       presetData: structure,
       parentId: options?.parentId,
@@ -397,7 +398,7 @@ export class Engine extends EventBus<EngineEvents> {
       throw new Error('replaceRegion cannot be called inside batch');
     }
 
-    const command = new ReplaceRegionCommand(this.page, {
+    const command = new ReplaceRegionCommand(this.getLivePage, {
       regionId,
       structures,
       blocksManager: this.blocksManager,
@@ -407,6 +408,48 @@ export class Engine extends EventBus<EngineEvents> {
     this.applyCommand(command);
   }
 
+  /**
+   * Merge externally resolved blocks into the live page.
+   *
+   * Each given block replaces the existing one with the same id wholesale (no deep merge).
+   * Blocks are used as given: the caller supplies `parentId` and `children`, no parent
+   * back-fill or validation runs. When a patched block drops ids from its previous `children`,
+   * those blocks vanish with their whole subtree unless they are present in the patch.
+   * Regions are untouched. The page is mutated in place and history is neither cleared nor
+   * extended, so this operation is not undoable.
+   *
+   * @param blocks - Blocks keyed by id
+   * @throws {Error} When called inside a batch
+   * @emits blocks:patch - When at least one block was given
+   */
+  patchBlocks(blocks: Record<string, Block>): void {
+    if (this.activeBatch) {
+      throw new Error('patchBlocks cannot be called inside batch');
+    }
+
+    if (Object.keys(blocks).length === 0) {
+      return;
+    }
+
+    const previousPage = structuredClone(this.page);
+    const removed = [...collectVanishedDescendants(this.page.blocks, blocks)];
+
+    for (const blockId of removed) {
+      delete this.page.blocks[blockId];
+    }
+
+    for (const [blockId, block] of Object.entries(blocks)) {
+      this.page.blocks[blockId] = structuredClone(block);
+    }
+
+    this.emit('blocks:patch', {
+      blocks,
+      removed,
+      previousPage,
+      newPage: structuredClone(this.page),
+    });
+  }
+
   /**
    * Get the blocks manager for this engine instance
    */
@@ -538,6 +581,10 @@ export class Engine extends EventBus<EngineEvents> {
     this.page = page;
   }
 
+  private getLivePage = (): Page => {
+    return this.page;
+  };
+
   private applyCommand(command: Command): void {
     command.apply();
     this.recordCommand(command);

package/src/types.ts

@@ -45,6 +45,7 @@ export interface EngineEvents {
     index?: number;
     regionId?: string;
   };
+  'blocks:patch': { blocks: Record<string, Block>; removed: string[]; previousPage: Page; newPage: Page };
   undo: { command: any };
   redo: { command: any };
 }

package/src/utils.ts

@@ -105,3 +105,46 @@ export const canInsertDynamicChildAt = (
   }
   return index >= first && index <= last + 1;
 };
+
+/**
+ * Every block in a patch carries an authoritative `children` list. Ids in a patched block's
+ * previous `children` that are missing from its new `children` have vanished, together with
+ * their whole subtree (walked through `previousBlocks`). Blocks present in the patch are never
+ * pruned, even when their previous parent dropped them.
+ */
+export const collectVanishedDescendants = (
+  previousBlocks: Record<string, Block>,
+  patchBlocks: Record<string, Block>
+): Set<string> => {
+  const vanished = new Set<string>();
+
+  const collectSubtree = (blockId: string): void => {
+    if (patchBlocks[blockId] || vanished.has(blockId)) {
+      return;
+    }
+
+    vanished.add(blockId);
+
+    for (const childId of previousBlocks[blockId]?.children ?? []) {
+      collectSubtree(childId);
+    }
+  };
+
+  for (const [blockId, patchBlock] of Object.entries(patchBlocks)) {
+    const previousBlock = previousBlocks[blockId];
+
+    if (!previousBlock) {
+      continue;
+    }
+
+    const keptChildren = new Set(patchBlock.children ?? []);
+
+    for (const childId of previousBlock.children ?? []) {
+      if (!keptChildren.has(childId)) {
+        collectSubtree(childId);
+      }
+    }
+  }
+
+  return vanished;
+};

package/src/vue/useBlocksEngine.ts

@@ -64,6 +64,7 @@ export interface UseBlocksEngineReturn {
   ) => string;
   replacePage: (newPage: Page) => void;
   replaceRegion: (regionId: string, structures: BlockStructure[]) => void;
+  patchBlocks: (blocks: Record<string, Block>) => void;
 
   undo: () => boolean;
   redo: () => boolean;
@@ -183,6 +184,7 @@ export function useBlocksEngine(
       'block:duplicate',
       'block:property:set',
       'block:update',
+      'blocks:patch',
       'undo',
       'redo',
     ] as const;
@@ -321,6 +323,14 @@ export function useBlocksEngine(
     }
   };
 
+  const patchBlocks = (blocks: Record<string, Block>): void => {
+    engine.patchBlocks(blocks);
+
+    if (!autoSync) {
+      syncStateFromEngine();
+    }
+  };
+
   const undo = (): boolean => {
     const result = engine.undo();
 
@@ -393,6 +403,7 @@ export function useBlocksEngine(
     pasteBlock,
     replacePage,
     replaceRegion,
+    patchBlocks,
 
     // History methods
     undo,