@designcrowd/library.brand-page 6.0.3 → 6.0.4

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

@@ -4,6 +4,7 @@ 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) {
@@ -16,6 +17,7 @@ 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 || '',
@@ -24,16 +26,28 @@ const applyTestimonialItemsAsync = async (content, items) => {
         mediaType: item.avatar_shape_url ? 'shape' : 'image',
     })));
 };
-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];
+/**
+ * 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 prevImageUrl = existing.imageUrl;
             if (item.avatar_shape_url !== undefined) {
                 existing.imageUrl = item.avatar_shape_url;
@@ -53,37 +67,21 @@ const mergeTestimonialItemsAsync = async (content, items, replaceAll) => {
                 item.color_theme !== undefined) {
                 existing.colorReplacements = await resolveItemColorsAsync(item, existing.colorReplacements, prevImageUrl);
             }
-        }));
-        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));
+            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);
+        }
     }
-    content.items = updatedItems;
 };
 export class TestimonialSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -132,56 +130,24 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        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);
-                }
-            }
+        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);
         }
-        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);
+        else if (this.mode === 'create') {
+            if (args.items && Array.isArray(args.items)) {
+                await applyTestimonialItemsAsync(content, args.items);
             }
         }
-        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 mergeTestimonialItemsAsync(content, args.items ?? [], args._remove_item_ids);
         }
         // Post-merge cap check. itemCapCheck only fires for create / update with
-        // _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.
+        // _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.
         // 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,6 +3,7 @@ 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))
@@ -16,55 +17,58 @@ 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));
 };
-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])
+/**
+ * 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)
                 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') {
-                const mergedStyle = (item.text_style
-                    ? { ...(existing.textStyle || {}), ...item.text_style }
-                    : existing.textStyle || {});
-                existing.textStyle = mergedStyle;
+                existing.textStyle = {
+                    ...(existing.textStyle || {}),
+                    ...item.text_style,
+                };
             }
+            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
@@ -121,56 +125,27 @@ 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.items && Array.isArray(args.items)) {
-            if (this.mode === 'create') {
+        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)) {
                 applyTextItems(content, args.items, textStyleOptions);
             }
             else {
-                mergeTextItems(content, args.items, !!args._replace_items, textStyleOptions);
+                applySingleTextField(content, args, 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,

package/lib/src/metadata-builder/builders/section-field-utils.d.ts

@@ -21,13 +21,6 @@ interface ButtonLinkArgs {
  */
 export declare const applyButtonLink: (content: ButtonLinkContent, args: ButtonLinkArgs) => void;
 export declare const applyScalarFields: (content: Content, args: SectionToolArguments, sectionType: string) => void;
-/**
- * Convert AI-sent style value to the format expected by the model.
- * - letterSpacing: unitless 0-100 → em string (e.g., 50 → '0.5em')
- * - null → '' (explicitly clear/reset the property)
- * - everything else passes through as-is
- */
-export declare const normalizeStyleValue: (key: string, value: unknown) => unknown;
 /**
  * When an executor is about to mark a content-level text style "custom" by
  * clearing `textStyleType`, the resolved preset values (font, size, spacing,

package/lib/src/metadata-builder/builders/section-field-utils.js

@@ -58,7 +58,7 @@ export const applyScalarFields = (content, args, sectionType) => {
  * - null → '' (explicitly clear/reset the property)
  * - everything else passes through as-is
  */
-export const normalizeStyleValue = (key, value) => {
+const normalizeStyleValue = (key, value) => {
     if (value === null)
         return '';
     if (value === undefined)

package/lib/src/metadata-builder/builders/shape-color-utils.js

@@ -48,5 +48,5 @@ export const applyColorThemeToReplacements = (replacements, colorTheme) => repla
     ...r,
     replacementColor: replacements.length === 1
         ? colorTheme
-        : (getNewColorBasedOnTargetColorTheme(r.originalColor, colorTheme)?.toString() ?? colorTheme),
+        : getNewColorBasedOnTargetColorTheme(r.originalColor, colorTheme)?.toString() ?? colorTheme,
 }));

package/lib/src/metadata-builder/parsers/ai-toolcall-parser.d.ts

@@ -1,6 +1,6 @@
 import type { AiAssistantToolCall } from '../../clients/ai-assistant-client';
 import type { FooterDisplayStyle, HeaderDisplayStyle, NavigationDisplayType } from '../../brand-page/constants';
-import type { SectionType, TextStyleArguments } from './section-tool-arguments';
+import type { SectionType } from './section-tool-arguments';
 export declare const AI_ASSISTANT_TOOL_NAMES: {
     readonly UPDATE_TEXT: "updateText";
     readonly UPDATE_STYLE: "updateStyle";
@@ -99,8 +99,17 @@ export interface ReorderPagesArguments {
 export interface UndoArguments {
 }
 export interface FooterSocialLinkItem {
-    item_index?: number;
-    insert_at?: number;
+    /**
+     * Stable id of the existing link to update or move. Omit to ADD a new link.
+     * Mirrors the section-level item_id convention (BP-5603).
+     */
+    item_id?: string;
+    /**
+     * Id of an existing link to position this link before (insert for new links,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing link in place / append a new link.
+     */
+    move_before_item_id?: string;
     social_link_icon?: string;
     url?: string;
 }
@@ -111,6 +120,7 @@ export interface FooterSocialLinkItem {
 export interface ViewportFooterOverrides {
     display_style?: FooterDisplayStyle;
     background_color?: string | null;
+    copyright_text_color?: string;
     icon_color?: string;
     is_logo_visible?: boolean;
     logo_image_height?: string;
@@ -118,12 +128,11 @@ export interface ViewportFooterOverrides {
 }
 export interface UpdateFooterArguments {
     copyright_text?: string;
-    /** Copyright line text-style object (typography + colour) — same shape as a section's *_style. Global: applies to both viewports. */
-    copyright_text_style?: TextStyleArguments;
+    copyright_text_font_family?: string;
     social_links?: FooterSocialLinkItem[];
     _replace_social_links?: boolean;
-    _remove_social_link_indices?: number[];
-    _reorder_social_links?: number[];
+    /** Stable ids of social links to remove. Order-independent (replaces index-based _remove_social_link_indices). */
+    _remove_social_link_ids?: string[];
     /** Desktop-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */
     desktop?: ViewportFooterOverrides;
     /** Mobile-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */

package/lib/src/metadata-builder/parsers/section-tool-arguments.d.ts

@@ -92,10 +92,15 @@ export interface ProfileSectionArguments {
     background_color?: string | null;
 }
 export interface TextSectionItem {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     text?: RichTextField;
     text_style?: TextStyleArguments;
 }
@@ -108,10 +113,8 @@ export interface TextSectionArguments {
     /** Multiple text items (BrandSite) */
     items?: TextSectionItem[];
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
     background_color?: string | null;
 }
 export interface ImageSectionArguments {
@@ -119,10 +122,15 @@ export interface ImageSectionArguments {
     image_title?: string;
 }
 export interface ImageGalleryItem {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     image_url?: string;
     caption?: string;
 }
@@ -131,10 +139,8 @@ export interface ImageGallerySectionArguments {
     gallery_type?: 'grid' | 'carousel' | 'masonry';
     is_full_width?: boolean;
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
 }
 export interface GeneralLinkSectionArguments {
     title?: string;
@@ -189,10 +195,15 @@ export interface TiktokSectionArguments {
     url?: string;
 }
 export interface SocialLink {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     platform?: 'facebook' | 'x' | 'instagram' | 'youtube' | 'linkedin' | 'pinterest' | 'twitch' | 'tiktok';
     url?: string;
 }
@@ -204,10 +215,8 @@ export interface SocialLinksSectionArguments {
     /** Style for the icon container background (used when icon_style is 'square' or 'circle'). */
     icon_background_style?: TextStyleArguments;
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
 }
 export interface MailingListSectionArguments {
     title?: RichTextField;
@@ -268,10 +277,15 @@ export interface AboutSectionArguments {
     background_color?: string | null;
 }
 export interface ImagesSectionItem {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     image_url?: string;
     heading?: string;
     text?: string;
@@ -283,10 +297,8 @@ export interface ImagesSectionArguments {
     items?: ImagesSectionItem[];
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'media-only' | 'center-card-aligned-image' | 'alternate-image';
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
     title_style?: TextStyleArguments;
     description_style?: TextStyleArguments;
     heading_style?: TextStyleArguments;
@@ -298,10 +310,15 @@ export interface ImagesSectionArguments {
     card_style?: CardStyleArguments;
 }
 export interface TestimonialItem {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     testimonial?: string;
     name?: string;
     position?: string;
@@ -314,10 +331,8 @@ export interface TestimonialSectionArguments {
     items?: TestimonialItem[];
     display_style?: 'centered' | 'big-image' | 'columns';
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
     title_style?: TextStyleArguments;
     testimonial_style?: TextStyleArguments;
     name_style?: TextStyleArguments;
@@ -326,10 +341,15 @@ export interface TestimonialSectionArguments {
     card_style?: CardStyleArguments;
 }
 export interface ShapesSectionItem {
-    /** 0-based index of existing item to update in-place */
-    item_index?: number;
-    /** 0-based position to insert a new item at */
-    insert_at?: number;
+    /** Stable id of the existing item to update or move. Omit to ADD a new item. */
+    item_id?: string;
+    /**
+     * Id of an existing item to position this item before (insert for new items,
+     * move for existing ones). Use "__end__" for the end of the list. Omit to
+     * leave an existing item in place / append a new item. Mirrors the
+     * section-level move_before_content_id.
+     */
+    move_before_item_id?: string;
     icon_image_url?: string;
     shape_url?: string;
     color_theme?: string;
@@ -342,10 +362,8 @@ export interface ShapesSectionArguments {
     items?: ShapesSectionItem[];
     display_style?: 'left-aligned' | 'right-aligned' | 'centered' | 'media-only' | 'center-card-aligned-image' | 'alternate-image';
     _replace_items?: boolean;
-    /** 0-based indices of items to remove */
-    _remove_item_indices?: number[];
-    /** New order as array of current 0-based indices */
-    _reorder_items?: number[];
+    /** Stable ids of items to remove. Order-independent (no index shifting). */
+    _remove_item_ids?: string[];
     title_style?: TextStyleArguments;
     description_style?: TextStyleArguments;
     heading_style?: TextStyleArguments;

package/lib/src/plugins/google-maps-plugin/google-maps-plugin.d.ts

@@ -15,7 +15,7 @@ export interface AddressDetails {
 export declare class GoogleMapsPlugin {
     private initialised;
     private initialising;
-    private readonly options;
+    private readonly _options;
     constructor(options: GoogleMapsPluginOptions);
     private initialise;
     private getPlacesLibrary;