@designcrowd/library.brand-page 5.19.1-id-based-items-2 → 5.19.1

package/lib/src/metadata-builder/builders/footer-builder.js

@@ -2,7 +2,6 @@ import {} from '../../brand-page/models';
 import { BaseMetadataBuilder, } from '../models';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
 import { applyDetachedStyleOverride } from './section-field-utils';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from './item-id-utils';
 const normaliseSocialUrl = (url) => {
     for (const prefix of ['mailto:', 'tel:']) {
         if (url.startsWith(prefix))
@@ -21,7 +20,6 @@ const applyGlobalFooterChanges = (footer, args, textStyleOptions) => {
     // they are superseded by the replacement and running them would cause duplicates.
     if (args._replace_social_links) {
         footer.socialLinks = (links ?? []).map((l) => ({
-            id: generateItemId(),
             imageUrl: l.social_link_icon || '',
             url: normaliseSocialUrl(l.url || ''),
             imageTitle: '',
@@ -32,40 +30,52 @@ const applyGlobalFooterChanges = (footer, args, textStyleOptions) => {
     }
     else {
         // Targeted mutations — only run when NOT replacing the entire list.
-        // BP-5603: id-based contract (item_id / move_before_item_id / _remove_social_link_ids).
-        // Backfill ids on legacy links so they become referenceable after this call.
-        ensureItemIds(footer.socialLinks);
-        // Remove by id (order-independent — no index shifting needed).
-        footer.socialLinks = removeItemsByIds(footer.socialLinks, args._remove_social_link_ids);
-        // Update existing links (item_id present) or insert new links (no item_id).
+        // item_index-based updates for existing links
         if (links?.length) {
-            footer.socialLinks = footer.socialLinks ?? [];
             for (const link of links) {
-                if (link.item_id) {
-                    // Update existing link in place; reposition if move_before_item_id set.
-                    const existing = footer.socialLinks.find((l) => l.id === link.item_id);
-                    // Unknown id — skip rather than guess at a position.
-                    if (!existing)
-                        continue;
-                    if (link.social_link_icon !== undefined)
-                        existing.imageUrl = link.social_link_icon;
-                    if (link.url !== undefined)
-                        existing.url = normaliseSocialUrl(link.url);
-                    repositionItemByAnchor(footer.socialLinks, existing, link.move_before_item_id);
-                }
-                else {
-                    // New link — assign a stable id and position via move_before_item_id.
-                    const newLink = {
-                        id: generateItemId(),
-                        imageUrl: link.social_link_icon || '',
-                        url: normaliseSocialUrl(link.url || ''),
-                        imageTitle: '',
-                        width: 0,
-                        height: 0,
-                        imageLink: '',
-                    };
-                    repositionItemByAnchor(footer.socialLinks, newLink, link.move_before_item_id);
-                }
+                if (link.item_index === undefined)
+                    continue;
+                const existing = footer.socialLinks?.[link.item_index];
+                if (!existing)
+                    continue;
+                if (link.social_link_icon !== undefined)
+                    existing.imageUrl = link.social_link_icon;
+                if (link.url !== undefined)
+                    existing.url = normaliseSocialUrl(link.url);
+            }
+        }
+        // Remove by index (descending order to preserve indices during splice)
+        if (args._remove_social_link_indices?.length && footer.socialLinks) {
+            const sorted = [...args._remove_social_link_indices].sort((a, b) => b - a);
+            for (const idx of sorted) {
+                if (idx >= 0 && idx < footer.socialLinks.length)
+                    footer.socialLinks.splice(idx, 1);
+            }
+        }
+        // Insert new links (descending insert_at order to preserve positions during splice)
+        const insertLinks = (links ?? []).filter((l) => l.insert_at !== undefined && l.item_index === undefined);
+        const sortedInserts = [...insertLinks].sort((a, b) => b.insert_at - a.insert_at);
+        for (const link of sortedInserts) {
+            const pos = Math.max(0, Math.min(link.insert_at, footer.socialLinks?.length ?? 0));
+            footer.socialLinks = footer.socialLinks ?? [];
+            footer.socialLinks.splice(pos, 0, {
+                imageUrl: link.social_link_icon || '',
+                url: normaliseSocialUrl(link.url || ''),
+                imageTitle: '',
+                width: 0,
+                height: 0,
+                imageLink: '',
+            });
+        }
+        // Reorder (requires ALL indices — partial reorder is not supported)
+        if (args._reorder_social_links?.length && footer.socialLinks) {
+            const newOrder = args._reorder_social_links;
+            const unique = new Set(newOrder);
+            if (unique.size === newOrder.length &&
+                newOrder.every((idx) => idx >= 0 && idx < footer.socialLinks.length)) {
+                const reordered = newOrder.map((idx) => footer.socialLinks[idx]);
+                if (reordered.length === footer.socialLinks.length)
+                    footer.socialLinks = reordered;
             }
         }
     }

package/lib/src/metadata-builder/builders/section-builders/image-gallery-builder.js

@@ -1,21 +1,14 @@
 import { applyScalarFields, isValidUrl } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImageGallery } from '../section-rules/image-gallery.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 const applyGalleryType = (content, galleryType) => {
     content.galleryStyles = {
         ...(content.galleryStyles || {}),
         galleryType: galleryType,
     };
 };
-/**
- * Full rebuild: discard existing images and map the payload directly.
- * Used on create and when `_replace_items` is set. Each item gets a fresh id
- * (or keeps the caller-supplied `item_id` when provided).
- */
 const applyGalleryImages = (content, images) => {
     content.images = images.map((img) => ({
-        id: img.item_id || generateItemId(),
         imageUrl: isValidUrl(img.image_url) ? img.image_url : '',
         imageTitle: img.caption || '',
         width: 0,
@@ -24,46 +17,59 @@ const applyGalleryImages = (content, images) => {
         imageLink: '',
     }));
 };
-/**
- * Id-based merge (BP-5603), mirroring testimonial-section-builder one level
- * deeper into `content.images`:
- *   - `item_id` matches existing item  → update in place; reposition if
- *     `move_before_item_id` is set.
- *   - no `item_id`                     → add new item, positioned by
- *     `move_before_item_id`.
- *   - `removeIds`                      → delete by id (order-independent).
- *
- * Existing items are id-backfilled first so legacy galleries become
- * referenceable as soon as the metadata builder touches them.
- */
-const mergeGalleryImages = (content, images, removeIds) => {
-    ensureItemIds(content.images);
-    content.images = removeItemsByIds(content.images, removeIds);
-    for (const img of images) {
-        if (img.item_id) {
-            const existing = content.images.find((i) => i.id === img.item_id);
-            // Unknown id — skip rather than guess at a position.
-            if (!existing)
-                continue;
-            if (img.image_url !== undefined) {
-                existing.imageUrl = isValidUrl(img.image_url) ? img.image_url : '';
-            }
-            if (img.caption !== undefined)
-                existing.imageTitle = img.caption;
-            repositionItemByAnchor(content.images, existing, img.move_before_item_id);
-        }
-        else {
-            const newItem = {
-                id: generateItemId(),
-                imageUrl: isValidUrl(img.image_url) ? img.image_url : '',
-                imageTitle: img.caption ?? '',
-                width: 0,
-                height: 0,
-                mediaType: 'image',
-                imageLink: '',
-            };
-            repositionItemByAnchor(content.images, newItem, img.move_before_item_id);
-        }
+const mergeGalleryImages = (content, images, replaceAll) => {
+    const itemsToMerge = images.filter((img) => img.insert_at === undefined);
+    const updatedImages = itemsToMerge.map((img, index) => {
+        const existing = content.images?.[index];
+        const imageUrl = isValidUrl(img.image_url)
+            ? img.image_url
+            : existing?.imageUrl ?? '';
+        return {
+            ...(existing || {}),
+            imageUrl,
+            imageTitle: img.caption ?? existing?.imageTitle ?? '',
+            width: existing?.width ?? 0,
+            height: existing?.height ?? 0,
+            mediaType: existing?.mediaType ?? 'image',
+            imageLink: existing?.imageLink ?? '',
+        };
+    });
+    if (!replaceAll &&
+        content.images &&
+        content.images.length > itemsToMerge.length) {
+        const extras = content.images.slice(itemsToMerge.length).map((img) => ({
+            imageUrl: img.imageUrl ?? '',
+            imageTitle: img.imageTitle ?? '',
+            width: img.width ?? 0,
+            height: img.height ?? 0,
+            mediaType: img.mediaType ?? 'image',
+            imageLink: img.imageLink ?? '',
+        }));
+        updatedImages.push(...extras);
+    }
+    content.images = updatedImages;
+};
+const insertGalleryImages = (content, images) => {
+    const inserts = images.filter((img) => img.insert_at !== undefined);
+    if (!inserts.length)
+        return;
+    const sorted = [...inserts].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
+    for (const img of sorted) {
+        if (!isValidUrl(img.image_url))
+            continue;
+        if (content.images?.some((existing) => existing.imageUrl === img.image_url))
+            continue;
+        content.images = content.images ?? [];
+        const pos = Math.max(0, Math.min(img.insert_at ?? 0, content.images.length));
+        content.images.splice(pos, 0, {
+            imageUrl: img.image_url,
+            imageTitle: img.caption ?? '',
+            width: 0,
+            height: 0,
+            mediaType: 'image',
+            imageLink: '',
+            colorReplacements: [],
+        });
     }
 };
 export class ImageGalleryBuilder extends BaseSectionBuilder {
@@ -85,19 +91,24 @@ export class ImageGalleryBuilder extends BaseSectionBuilder {
         if (args.gallery_type) {
             applyGalleryType(content, args.gallery_type);
         }
-        if (args._replace_items && args.images && Array.isArray(args.images)) {
-            // Full replacement: discard existing images and rebuild from the payload.
-            applyGalleryImages(content, args.images);
-        }
-        else if (this.mode === 'create') {
-            if (args.images && Array.isArray(args.images)) {
+        if (args.images && Array.isArray(args.images)) {
+            if (this.mode === 'create') {
                 applyGalleryImages(content, args.images);
             }
+            else {
+                mergeGalleryImages(content, args.images, !!args._replace_items);
+            }
+        }
+        if (args._remove_item_indices?.length && content.images) {
+            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+            for (const idx of sorted) {
+                if (idx >= 0 && idx < content.images.length) {
+                    content.images.splice(idx, 1);
+                }
+            }
         }
-        else if ((args.images && Array.isArray(args.images)) ||
-            args._remove_item_ids?.length) {
-            // Update: id-based add / edit / move / remove in a single pass.
-            mergeGalleryImages(content, args.images ?? [], args._remove_item_ids);
+        if (args.images && Array.isArray(args.images) && this.mode === 'update') {
+            insertGalleryImages(content, args.images);
         }
         return { request: this.request, model };
     }

package/lib/src/metadata-builder/builders/section-builders/images-section-builder.js

@@ -3,15 +3,8 @@ import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
 import { applyScalarFields, applyStyleFields, isValidUrl, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImagesSection } from '../section-rules/images-section.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
-/**
- * Full replacement: discard existing items and rebuild from the payload.
- * Assigns a stable `id` to each item; `itemsId` is set positionally here
- * but will be re-indexed at the end of buildAsync.
- */
 const applyImageItems = (content, items) => {
     content.items = items.map((item, index) => ({
-        id: item.item_id || generateItemId(),
         imageUrl: isValidUrl(item.image_url) ? item.image_url : '',
         imageTitle: '',
         width: 0,
@@ -25,28 +18,16 @@ const applyImageItems = (content, items) => {
         colorReplacements: [],
     }));
 };
-/**
- * Apply a batch of item operations by id (BP-5603), mirroring the
- * section-level id-based contract one level deeper:
- *   - item with `item_id` matching an existing item  → update in place (and
- *     reposition if `move_before_item_id` is set);
- *   - item without `item_id`                          → add a new item,
- *     positioned by `move_before_item_id`;
- *   - `_remove_item_ids`                              → delete by id.
- *
- * Existing items are id-backfilled first so legacy sections become
- * referenceable the moment the metadata builder touches them.
- * Order-independent: there are no positional indices to shift between ops.
- */
-const mergeImageItems = (content, items, removeIds) => {
-    ensureItemIds(content.items);
-    content.items = removeItemsByIds(content.items, removeIds);
-    for (const item of items) {
-        if (item.item_id) {
-            const existing = content.items.find((i) => i.id === item.item_id);
-            // Unknown id — skip rather than guess at a position.
-            if (!existing)
+const mergeImageItems = (content, items, replaceAll) => {
+    const hasIndexedItems = items.some((item) => item.item_index !== undefined);
+    if (hasIndexedItems) {
+        for (const item of items) {
+            const targetIndex = item.item_index;
+            if (targetIndex === undefined ||
+                targetIndex < 0 ||
+                !content.items?.[targetIndex])
                 continue;
+            const existing = content.items[targetIndex];
             if (isValidUrl(item.image_url))
                 existing.imageUrl = item.image_url;
             if (item.heading !== undefined)
@@ -55,26 +36,36 @@ const mergeImageItems = (content, items, removeIds) => {
                 existing.paragraph = item.text;
             if (item.button_text !== undefined)
                 existing.buttonText = item.button_text || false;
-            repositionItemByAnchor(content.items, existing, item.move_before_item_id);
-        }
-        else {
-            const newItem = {
-                id: generateItemId(),
-                imageUrl: isValidUrl(item.image_url) ? item.image_url : '',
-                imageTitle: '',
-                width: 0,
-                height: 0,
-                mediaType: 'image',
-                imageLink: '',
-                title: item.heading ?? '',
-                paragraph: item.text ?? '',
-                buttonText: item.button_text || false,
-                itemsId: 0, // re-indexed at the end of buildAsync
-                colorReplacements: [],
-            };
-            repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
         }
+        return;
+    }
+    const itemsToMerge = items.filter((item) => item.insert_at === undefined);
+    const updatedItems = itemsToMerge.map((item, index) => {
+        const existing = content.items?.[index];
+        return {
+            ...(existing || {}),
+            imageUrl: isValidUrl(item.image_url)
+                ? item.image_url
+                : existing?.imageUrl ?? '',
+            imageTitle: existing?.imageTitle ?? '',
+            width: existing?.width ?? 0,
+            height: existing?.height ?? 0,
+            mediaType: existing?.mediaType ?? 'image',
+            imageLink: existing?.imageLink ?? '',
+            title: item.heading ?? existing?.title ?? '',
+            paragraph: item.text ?? existing?.paragraph ?? '',
+            buttonText: item.button_text ?? existing?.buttonText ?? '',
+            itemsId: existing?.itemsId ?? index,
+            colorReplacements: existing?.colorReplacements ?? [],
+        };
+    });
+    if (!replaceAll &&
+        content.items &&
+        content.items.length > itemsToMerge.length) {
+        const remaining = content.items.slice(itemsToMerge.length);
+        updatedItems.push(...remaining);
     }
+    content.items = updatedItems;
 };
 export class ImagesSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -132,22 +123,66 @@ export class ImagesSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        if (args._replace_items && args.items && Array.isArray(args.items)) {
-            // Full replacement: discard existing items and rebuild from the payload.
-            applyImageItems(content, args.items);
-        }
-        else if (this.mode === 'create') {
-            if (args.items && Array.isArray(args.items)) {
+        if (args.items && Array.isArray(args.items)) {
+            if (this.mode === 'create') {
                 applyImageItems(content, args.items);
             }
+            else {
+                mergeImageItems(content, args.items, !!args._replace_items);
+            }
         }
-        else if ((args.items && Array.isArray(args.items)) ||
-            args._remove_item_ids?.length) {
-            // Update: id-based add / edit / move / remove in a single pass.
-            mergeImageItems(content, args.items ?? [], args._remove_item_ids);
+        // Phase 2: Item operations (remove, insert, reorder)
+        if (args._remove_item_indices?.length && content.items) {
+            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+            for (const idx of sorted) {
+                if (idx >= 0 && idx < content.items.length) {
+                    content.items.splice(idx, 1);
+                }
+            }
+        }
+        if (args.items && Array.isArray(args.items)) {
+            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
+            // Process inserts in reverse order of insert_at to preserve indices
+            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
+            for (const item of sortedInserts) {
+                if (!isValidUrl(item.image_url))
+                    continue;
+                // Skip if this image_url already exists — defensive against duplicate
+                // tool call application
+                if (content.items?.some((existing) => existing.imageUrl === item.image_url)) {
+                    continue;
+                }
+                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.items?.length ?? 0));
+                const newItem = {
+                    imageUrl: item.image_url,
+                    imageTitle: '',
+                    width: 0,
+                    height: 0,
+                    mediaType: 'image',
+                    imageLink: '',
+                    title: item.heading ?? '',
+                    paragraph: item.text ?? '',
+                    buttonText: item.button_text || '',
+                    itemsId: pos,
+                    colorReplacements: [],
+                };
+                content.items = content.items ?? [];
+                content.items.splice(pos, 0, newItem);
+            }
+        }
+        if (args._reorder_items?.length && content.items) {
+            const newOrder = args._reorder_items;
+            const unique = new Set(newOrder);
+            if (unique.size === newOrder.length) {
+                const reordered = newOrder
+                    .filter((idx) => idx >= 0 && idx < content.items.length)
+                    .map((idx) => content.items[idx]);
+                if (reordered.length === content.items.length) {
+                    content.items = reordered;
+                }
+            }
         }
-        // Re-index itemsId after all id-based item operations (render concern —
-        // separate from the stable `id` used for targeting).
+        // Re-index itemsId after any item operations
         if (content.items) {
             content.items.forEach((item, i) => {
                 item.itemsId = i;

package/lib/src/metadata-builder/builders/section-builders/shapes-section-builder.js

@@ -4,7 +4,6 @@ import { applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } fr
 import { applyColorThemeToReplacements, resolveShapeColorReplacementsAsync, } from '../shape-color-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateShapesSection } from '../section-rules/shapes-section.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
     let colors = existing ?? [];
     const newUrl = item.shape_url ?? item.icon_image_url;
@@ -16,13 +15,8 @@ const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
     }
     return colors;
 };
-/**
- * Full replacement: discard existing items and rebuild from the payload.
- * Used for create mode and _replace_items: true.
- */
 const applyShapeItemsAsync = async (content, items) => {
-    content.items = await Promise.all(items.map(async (item) => ({
-        id: item.item_id || generateItemId(),
+    content.items = await Promise.all(items.map(async (item, index) => ({
         imageUrl: item.shape_url || item.icon_image_url || '',
         imageTitle: '',
         width: 0,
@@ -31,36 +25,20 @@ const applyShapeItemsAsync = async (content, items) => {
         imageLink: '',
         title: item.heading || '',
         paragraph: item.text || '',
-        itemsId: 0,
+        itemsId: index,
         colorReplacements: await resolveItemColorsAsync(item, [], undefined),
     })));
-    // Re-index itemsId after build
-    content.items.forEach((item, i) => {
-        item.itemsId = i;
-    });
 };
-/**
- * Apply a batch of item operations by id (BP-5603), mirroring the section-level
- * id-based contract one level deeper:
- *   - item with `item_id` matching an existing item  → update in place (and
- *     reposition if `move_before_item_id` is set);
- *   - item without `item_id`                          → add a new item,
- *     positioned by `move_before_item_id`;
- *   - `_remove_item_ids`                              → delete by id.
- *
- * Existing items are id-backfilled first so legacy sections become referenceable
- * the moment the metadata builder touches them. Order-independent: there are no
- * positional indices to shift between operations.
- */
-const mergeShapeItemsAsync = async (content, items, removeIds) => {
-    ensureItemIds(content.items);
-    content.items = removeItemsByIds(content.items, removeIds);
-    for (const item of items) {
-        if (item.item_id) {
-            const existing = content.items.find((i) => i.id === item.item_id);
-            // Unknown id — skip rather than guess at a position.
-            if (!existing)
-                continue;
+const mergeShapeItemsAsync = async (content, items, replaceAll) => {
+    const hasIndexedItems = items.some((item) => item.item_index !== undefined);
+    if (hasIndexedItems) {
+        await Promise.all(items.map(async (item) => {
+            const targetIndex = item.item_index;
+            if (targetIndex === undefined ||
+                targetIndex < 0 ||
+                !content.items?.[targetIndex])
+                return;
+            const existing = content.items[targetIndex];
             const prevImageUrl = existing.imageUrl;
             if (item.shape_url !== undefined || item.icon_image_url !== undefined) {
                 existing.imageUrl =
@@ -73,29 +51,34 @@ const mergeShapeItemsAsync = async (content, items, removeIds) => {
             if (item.shape_url !== undefined || item.color_theme !== undefined) {
                 existing.colorReplacements = await resolveItemColorsAsync(item, existing.colorReplacements, prevImageUrl);
             }
-            repositionItemByAnchor(content.items, existing, item.move_before_item_id);
-        }
-        else {
-            const newItem = {
-                id: generateItemId(),
-                imageUrl: item.shape_url ?? item.icon_image_url ?? '',
-                imageTitle: '',
-                width: 0,
-                height: 0,
-                mediaType: 'shape',
-                imageLink: '',
-                title: item.heading ?? '',
-                paragraph: item.text ?? '',
-                itemsId: 0,
-                colorReplacements: await resolveItemColorsAsync(item, [], undefined),
-            };
-            repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
-        }
+        }));
+        return;
+    }
+    const itemsToMerge = items.filter((item) => item.insert_at === undefined);
+    const updatedItems = await Promise.all(itemsToMerge.map(async (item, index) => {
+        const existing = content.items?.[index];
+        const imageUrl = item.shape_url ?? item.icon_image_url ?? existing?.imageUrl ?? '';
+        return {
+            ...(existing || {}),
+            imageUrl,
+            imageTitle: existing?.imageTitle ?? '',
+            width: existing?.width ?? 0,
+            height: existing?.height ?? 0,
+            mediaType: existing?.mediaType ?? 'shape',
+            imageLink: existing?.imageLink ?? '',
+            title: item.heading ?? existing?.title ?? '',
+            paragraph: item.text ?? existing?.paragraph ?? '',
+            itemsId: existing?.itemsId ?? index,
+            colorReplacements: await resolveItemColorsAsync(item, existing?.colorReplacements, existing?.imageUrl),
+        };
+    }));
+    if (!replaceAll &&
+        content.items &&
+        content.items.length > itemsToMerge.length) {
+        const remaining = content.items.slice(itemsToMerge.length);
+        updatedItems.push(...remaining);
     }
-    // Re-index itemsId after all mutations
-    content.items.forEach((item, i) => {
-        item.itemsId = i;
-    });
+    content.items = updatedItems;
 };
 export class ShapesSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -153,19 +136,69 @@ export class ShapesSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        if (args._replace_items && args.items && Array.isArray(args.items)) {
-            // Full replacement: discard existing items and rebuild from the payload.
-            await applyShapeItemsAsync(content, args.items);
-        }
-        else if (this.mode === 'create') {
-            if (args.items && Array.isArray(args.items)) {
+        if (args.items && Array.isArray(args.items)) {
+            if (this.mode === 'create') {
                 await applyShapeItemsAsync(content, args.items);
             }
+            else {
+                await mergeShapeItemsAsync(content, args.items, !!args._replace_items);
+            }
+        }
+        // Phase 2: Item operations (remove, insert, reorder)
+        if (args._remove_item_indices?.length && content.items) {
+            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+            for (const idx of sorted) {
+                if (idx >= 0 && idx < content.items.length) {
+                    content.items.splice(idx, 1);
+                }
+            }
+        }
+        if (args.items && Array.isArray(args.items)) {
+            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
+            // Process inserts in reverse order of insert_at to preserve indices
+            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
+            for (const item of sortedInserts) {
+                const insertUrl = item.shape_url ?? item.icon_image_url ?? '';
+                // Skip if this shape/icon already exists — defensive against duplicate
+                // tool call application
+                if (insertUrl &&
+                    content.items?.some((existing) => existing.imageUrl === insertUrl)) {
+                    continue;
+                }
+                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.items?.length ?? 0));
+                const newItem = {
+                    imageUrl: insertUrl,
+                    imageTitle: '',
+                    width: 0,
+                    height: 0,
+                    mediaType: 'shape',
+                    imageLink: '',
+                    title: item.heading ?? '',
+                    paragraph: item.text ?? '',
+                    itemsId: pos,
+                    colorReplacements: await resolveItemColorsAsync(item, [], undefined),
+                };
+                content.items = content.items ?? [];
+                content.items.splice(pos, 0, newItem);
+            }
+        }
+        if (args._reorder_items?.length && content.items) {
+            const newOrder = args._reorder_items;
+            const unique = new Set(newOrder);
+            if (unique.size === newOrder.length) {
+                const reordered = newOrder
+                    .filter((idx) => idx >= 0 && idx < content.items.length)
+                    .map((idx) => content.items[idx]);
+                if (reordered.length === content.items.length) {
+                    content.items = reordered;
+                }
+            }
         }
-        else if ((args.items && Array.isArray(args.items)) ||
-            args._remove_item_ids?.length) {
-            // Update: id-based add / edit / move / remove in a single pass.
-            await mergeShapeItemsAsync(content, args.items ?? [], args._remove_item_ids);
+        // Re-index itemsId after any item operations
+        if (content.items) {
+            content.items.forEach((item, i) => {
+                item.itemsId = i;
+            });
         }
         return { request: this.request, model };
     }