@designcrowd/library.brand-page 6.0.5 → 6.0.6-ast-bugs

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 };
     }

package/lib/src/metadata-builder/builders/section-builders/social-links-builder.js

@@ -1,15 +1,8 @@
 import { applyScalarFields, applyStyleFields } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateSocialLinks } from '../section-rules/social-links.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
-/**
- * Create path: build the links array from scratch, assigning stable ids.
- * `link.platform` is stored as `imageUrl` — the renderer resolves it to the
- * actual SVG at display time.
- */
 const applySocialLinks = (content, links) => {
     content.links = links.map((link) => ({
-        id: link.item_id || generateItemId(),
         imageUrl: link.platform || '',
         imageTitle: '',
         width: 0,
@@ -18,46 +11,19 @@ const applySocialLinks = (content, links) => {
         url: link.url || '',
     }));
 };
-/**
- * Merge path: id-based add / edit / move / remove in a single pass (BP-5603).
- *
- * - Existing items are id-backfilled first so legacy sections gain stable ids
- *   the moment the metadata builder touches them.
- * - `_remove_item_ids` deletes by id before the edit/add loop.
- * - An item with `item_id` matching an existing link is updated in place and
- *   optionally repositioned via `move_before_item_id`.
- * - An item without `item_id` is added as a new link, positioned by
- *   `move_before_item_id` (or appended when omitted).
- * - An item with an unknown `item_id` is skipped rather than guessing position.
- */
-const mergeSocialLinks = (content, links, removeIds) => {
-    ensureItemIds(content.links);
-    content.links = removeItemsByIds(content.links, removeIds);
-    for (const link of links) {
-        if (link.item_id) {
-            const existing = content.links.find((l) => l.id === link.item_id);
-            // Unknown id — skip rather than guess at a position.
-            if (!existing)
-                continue;
-            if (link.platform !== undefined)
-                existing.imageUrl = link.platform;
-            if (link.url !== undefined)
-                existing.url = link.url;
-            repositionItemByAnchor(content.links, existing, link.move_before_item_id);
-        }
-        else {
-            const newLink = {
-                id: generateItemId(),
-                imageUrl: link.platform ?? '',
-                imageTitle: '',
-                width: 0,
-                height: 0,
-                imageLink: '',
-                url: link.url ?? '',
-            };
-            repositionItemByAnchor(content.links, newLink, link.move_before_item_id);
-        }
+const mergeSocialLinks = (content, links, replaceAll) => {
+    const updatedLinks = links.map((link, index) => {
+        const existing = content.links?.[index];
+        return {
+            ...(existing || {}),
+            imageUrl: link.platform ?? existing?.imageUrl ?? '',
+            url: link.url ?? existing?.url ?? '',
+        };
+    });
+    if (!replaceAll && content.links && content.links.length > links.length) {
+        updatedLinks.push(...content.links.slice(links.length));
     }
+    content.links = updatedLinks;
 };
 export class SocialLinksBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -76,19 +42,13 @@ export class SocialLinksBuilder extends BaseSectionBuilder {
         applyScalarFields(content, this.args, this.sectionType);
         applyStyleFields(content, this.args, this.sectionType, this.getGlobalTextStyles(model));
         const args = this.args;
-        if (args._replace_items && args.links && Array.isArray(args.links)) {
-            // Full replacement: discard existing links and rebuild from the payload.
-            applySocialLinks(content, args.links);
-        }
-        else if (this.mode === 'create') {
-            if (args.links && Array.isArray(args.links)) {
+        if (args.links && Array.isArray(args.links)) {
+            if (this.mode === 'create') {
                 applySocialLinks(content, args.links);
             }
-        }
-        else if ((args.links && Array.isArray(args.links)) ||
-            args._remove_item_ids?.length) {
-            // Update: id-based add / edit / move / remove in a single pass.
-            mergeSocialLinks(content, args.links ?? [], args._remove_item_ids);
+            else {
+                mergeSocialLinks(content, args.links, !!args._replace_items);
+            }
         }
         return { request: this.request, model };
     }

package/lib/src/metadata-builder/builders/section-builders/testimonial-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 { validateTestimonialSection, TESTIMONIAL_ITEM_CAP, } from '../section-rules/testimonial-section.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
     let colors = existing ?? [];
     if (item.avatar_shape_url && item.avatar_shape_url !== prevImageUrl) {
@@ -17,7 +16,6 @@ const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
 };
 const applyTestimonialItemsAsync = async (content, items) => {
     content.items = await Promise.all(items.map(async (item) => ({
-        id: item.item_id || generateItemId(),
         imageUrl: item.avatar_shape_url || item.avatar_image_url || '',
         name: item.name || '',
         position: item.position || '',
@@ -26,28 +24,16 @@ const applyTestimonialItemsAsync = async (content, items) => {
         mediaType: item.avatar_shape_url ? 'shape' : 'image',
     })));
 };
-/**
- * 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 mergeTestimonialItemsAsync = 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 mergeTestimonialItemsAsync = 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.avatar_shape_url !== undefined) {
                 existing.imageUrl = item.avatar_shape_url;
@@ -67,21 +53,37 @@ const mergeTestimonialItemsAsync = async (content, items, removeIds) => {
                 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.avatar_shape_url ?? item.avatar_image_url ?? '',
-                name: item.name ?? '',
-                position: item.position ?? '',
-                testimonials: item.testimonial ?? '',
-                colorReplacements: await resolveItemColorsAsync(item, [], undefined),
-                mediaType: item.avatar_shape_url ? 'shape' : 'image',
-            };
-            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.avatar_shape_url ??
+            item.avatar_image_url ??
+            existing?.imageUrl ??
+            '';
+        const mediaType = item.avatar_shape_url
+            ? 'shape'
+            : item.avatar_image_url
+                ? 'image'
+                : (existing?.mediaType ?? 'image');
+        return {
+            ...(existing || {}),
+            imageUrl,
+            name: item.name ?? existing?.name ?? '',
+            position: item.position ?? existing?.position ?? '',
+            testimonials: item.testimonial ?? existing?.testimonials ?? '',
+            colorReplacements: await resolveItemColorsAsync(item, existing?.colorReplacements, existing?.imageUrl),
+            mediaType,
+        };
+    }));
+    if (!replaceAll &&
+        content.items &&
+        content.items.length > itemsToMerge.length) {
+        updatedItems.push(...content.items.slice(itemsToMerge.length));
+    }
+    content.items = updatedItems;
 };
 export class TestimonialSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -130,24 +132,56 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        if (args._replace_items && args.items && Array.isArray(args.items)) {
-            // Full replacement: discard existing items and rebuild from the payload.
-            await applyTestimonialItemsAsync(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 applyTestimonialItemsAsync(content, args.items);
             }
+            else {
+                await mergeTestimonialItemsAsync(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);
+                }
+            }
         }
-        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 mergeTestimonialItemsAsync(content, args.items ?? [], args._remove_item_ids);
+        if (args.items && Array.isArray(args.items)) {
+            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
+            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
+            for (const item of sortedInserts) {
+                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.items?.length ?? 0));
+                const newItem = {
+                    imageUrl: item.avatar_shape_url ?? item.avatar_image_url ?? '',
+                    name: item.name ?? '',
+                    position: item.position ?? '',
+                    testimonials: item.testimonial ?? '',
+                    colorReplacements: await resolveItemColorsAsync(item, [], undefined),
+                    mediaType: item.avatar_shape_url ? 'shape' : 'image',
+                };
+                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;
+                }
+            }
         }
         // Post-merge cap check. itemCapCheck only fires for create / update with
-        // _replace_items, so adding new items to an already-full section silently
-        // bloats the array. Surface as an error so the AI retry loop gets a signal
-        // and can reissue with _remove_item_ids or fewer additions.
+        // _replace_items, so insert_at on an already-full section silently bloats
+        // the array. Surface as an error so the AI retry loop gets a signal and
+        // can reissue with _remove_item_indices or fewer inserts.
         // brandSite key mirrors base-section-builder's hardcoded brandPageType.
         const cap = TESTIMONIAL_ITEM_CAP.brandSite;
         if (content.items && content.items.length > cap) {

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

@@ -3,7 +3,6 @@ import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
 import { applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateTextSection } from '../section-rules/text-section.rules';
-import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 /** Resolve a RichTextField (string or TiptapDocument) to a plain HTML string. */
 const resolveText = (value) => {
     if (isTiptapDocument(value))
@@ -17,58 +16,55 @@ const createTextItem = (item, baseStyle, textStyleOptions) => {
     const textStyle = (item.text_style ? { ...baseStyle, ...item.text_style } : { ...baseStyle });
     const { html, wasTiptap } = resolveText(item.text);
     return {
-        id: item.item_id || generateItemId(),
         text: html,
         textStyle: clearTextStyleTypeIfTiptap(textStyle, wasTiptap, textStyleOptions),
     };
 };
-/**
- * Full replacement: discard existing items and rebuild from the payload,
- * assigning a stable id to each new item.
- */
 const applyTextItems = (content, items, textStyleOptions) => {
     content.textItems = items.map((item) => createTextItem(item, content.textStyle || {}, textStyleOptions));
 };
-/**
- * Id-based merge (BP-5603): mirrors the section-level id contract one level
- * deeper.
- *   - item with `item_id` matching an existing item → update in place and
- *     reposition if `move_before_item_id` is set; unknown id is skipped.
- *   - item without `item_id`                        → add a new item,
- *     positioned by `move_before_item_id`.
- *   - `removeIds`                                   → delete by id.
- *
- * Existing items are id-backfilled first so legacy sections without ids
- * become referenceable the moment this builder processes them.
- */
-const mergeTextItems = (content, items, removeIds, textStyleOptions) => {
-    ensureItemIds(content.textItems);
-    content.textItems = removeItemsByIds(content.textItems, removeIds);
-    for (const item of items) {
-        if (item.item_id) {
-            const existing = content.textItems?.find((i) => i.id === item.item_id);
-            // Unknown id — skip rather than guess at a position.
-            if (!existing)
+const mergeTextItems = (content, items, replaceAll, textStyleOptions) => {
+    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.textItems?.[targetIndex])
                 continue;
+            const existing = content.textItems[targetIndex];
             if (item.text !== undefined) {
                 const { html, wasTiptap } = resolveText(item.text);
                 existing.text = html;
                 existing.textStyle = clearTextStyleTypeIfTiptap(existing.textStyle || {}, wasTiptap, textStyleOptions);
             }
             if (item.text_style && typeof item.text_style === 'object') {
-                existing.textStyle = {
-                    ...(existing.textStyle || {}),
-                    ...item.text_style,
-                };
+                const mergedStyle = (item.text_style
+                    ? { ...(existing.textStyle || {}), ...item.text_style }
+                    : existing.textStyle || {});
+                existing.textStyle = mergedStyle;
             }
-            repositionItemByAnchor(content.textItems, existing, item.move_before_item_id);
-        }
-        else {
-            const newItem = createTextItem(item, content.textStyle || {}, textStyleOptions);
-            content.textItems = content.textItems ?? [];
-            repositionItemByAnchor(content.textItems, 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.textItems?.[index];
+        const baseStyle = existing?.textStyle || content.textStyle || {};
+        const mergedStyle = (item.text_style ? { ...baseStyle, ...item.text_style } : baseStyle);
+        const resolved = item.text !== undefined ? resolveText(item.text) : null;
+        const text = resolved ? resolved.html : (existing?.text ?? '');
+        return {
+            text,
+            textStyle: clearTextStyleTypeIfTiptap(mergedStyle, resolved?.wasTiptap ?? false, textStyleOptions),
+        };
+    });
+    if (!replaceAll &&
+        content.textItems &&
+        content.textItems.length > itemsToMerge.length) {
+        updatedItems.push(...content.textItems.slice(itemsToMerge.length));
+    }
+    content.textItems = updatedItems;
 };
 /**
  * Handles the single `text` + `text_style` fields (BrandPage/BrandContact
@@ -125,27 +121,56 @@ export class TextSectionBuilder extends BaseSectionBuilder {
         applyScalarFields(content, this.args, this.sectionType);
         applyStyleFields(content, this.args, this.sectionType, this.getGlobalTextStyles(model));
         const args = this.args;
-        if (args._replace_items && args.items && Array.isArray(args.items)) {
-            // Full replacement: discard existing items and rebuild from the payload.
-            applyTextItems(content, args.items, textStyleOptions);
-        }
-        else if (this.mode === 'create') {
-            if (args.items && Array.isArray(args.items)) {
+        if (args.items && Array.isArray(args.items)) {
+            if (this.mode === 'create') {
                 applyTextItems(content, args.items, textStyleOptions);
             }
             else {
-                applySingleTextField(content, args, textStyleOptions);
+                mergeTextItems(content, args.items, !!args._replace_items, textStyleOptions);
             }
         }
-        else if ((args.items && Array.isArray(args.items)) ||
-            args._remove_item_ids?.length) {
-            // Update: id-based add / edit / move / remove in a single pass.
-            mergeTextItems(content, args.items ?? [], args._remove_item_ids, textStyleOptions);
-        }
         else {
-            // No items array: apply the single text/text_style shorthand fields.
             applySingleTextField(content, args, textStyleOptions);
         }
+        // Phase 2: Item operations (remove, insert, reorder)
+        if (args._remove_item_indices?.length && content.textItems) {
+            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+            for (const idx of sorted) {
+                if (idx >= 0 && idx < content.textItems.length) {
+                    content.textItems.splice(idx, 1);
+                }
+            }
+        }
+        if (args.items && Array.isArray(args.items)) {
+            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
+            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
+            for (const item of sortedInserts) {
+                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.textItems?.length ?? 0));
+                const baseStyle = content.textStyle || {};
+                const textStyle = (item.text_style
+                    ? { ...baseStyle, ...item.text_style }
+                    : { ...baseStyle });
+                const { html, wasTiptap } = resolveText(item.text);
+                const newItem = {
+                    text: html,
+                    textStyle: clearTextStyleTypeIfTiptap(textStyle, wasTiptap, textStyleOptions),
+                };
+                content.textItems = content.textItems ?? [];
+                content.textItems.splice(pos, 0, newItem);
+            }
+        }
+        if (args._reorder_items?.length && content.textItems) {
+            const newOrder = args._reorder_items;
+            const unique = new Set(newOrder);
+            if (unique.size === newOrder.length) {
+                const reordered = newOrder
+                    .filter((idx) => idx >= 0 && idx < content.textItems.length)
+                    .map((idx) => content.textItems[idx]);
+                if (reordered.length === content.textItems.length) {
+                    content.textItems = reordered;
+                }
+            }
+        }
         if (args.background_color !== undefined) {
             content.backgroundColor = {
                 ...content.backgroundColor,