@designcrowd/library.brand-page 6.0.3 → 6.0.4

package/src/metadata-builder/builders/section-builders/testimonial-section-builder.ts

@@ -25,6 +25,12 @@ import {
   validateTestimonialSection,
   TESTIMONIAL_ITEM_CAP,
 } from '../section-rules/testimonial-section.rules';
+import {
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from '../item-id-utils';
 
 const resolveItemColorsAsync = async (
   item: TestimonialItem,
@@ -50,6 +56,7 @@ const applyTestimonialItemsAsync = async (
 ): Promise<void> => {
   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 || '',
@@ -60,101 +67,77 @@ const applyTestimonialItemsAsync = async (
   );
 };
 
+/**
+ * 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: TestimonialSectionContent,
   items: TestimonialItem[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): Promise<void> => {
-  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;
-          existing.mediaType = 'shape';
-        } else if (item.avatar_image_url !== undefined) {
-          existing.imageUrl = item.avatar_image_url;
-          existing.mediaType = 'image';
-        }
-
-        if (item.name !== undefined) existing.name = item.name;
-
-        if (item.position !== undefined) existing.position = item.position;
-
-        if (item.testimonial !== undefined)
-          existing.testimonials = item.testimonial;
-
-        if (
-          item.avatar_shape_url !== undefined ||
-          item.color_theme !== undefined
-        ) {
-          existing.colorReplacements = await resolveItemColorsAsync(
-            item,
-            existing.colorReplacements,
-            prevImageUrl,
-          );
-        }
-      }),
-    );
+  ensureItemIds(content.items);
+  content.items = removeItemsByIds(content.items, removeIds);
 
-    return;
-  }
+  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 itemsToMerge = items.filter((item) => item.insert_at === undefined);
+      const prevImageUrl = existing.imageUrl;
 
-  const updatedItems = await Promise.all(
-    itemsToMerge.map(async (item, index) => {
-      const existing = content.items?.[index];
+      if (item.avatar_shape_url !== undefined) {
+        existing.imageUrl = item.avatar_shape_url;
+        existing.mediaType = 'shape';
+      } else if (item.avatar_image_url !== undefined) {
+        existing.imageUrl = item.avatar_image_url;
+        existing.mediaType = 'image';
+      }
 
-      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');
+      if (item.name !== undefined) existing.name = item.name;
 
-      return {
-        ...(existing || {}),
-        imageUrl,
-        name: item.name ?? existing?.name ?? '',
-        position: item.position ?? existing?.position ?? '',
-        testimonials: item.testimonial ?? existing?.testimonials ?? '',
-        colorReplacements: await resolveItemColorsAsync(
+      if (item.position !== undefined) existing.position = item.position;
+
+      if (item.testimonial !== undefined)
+        existing.testimonials = item.testimonial;
+
+      if (
+        item.avatar_shape_url !== undefined ||
+        item.color_theme !== undefined
+      ) {
+        existing.colorReplacements = await resolveItemColorsAsync(
           item,
-          existing?.colorReplacements,
-          existing?.imageUrl,
-        ),
-        mediaType,
-      };
-    }),
-  );
+          existing.colorReplacements,
+          prevImageUrl,
+        );
+      }
 
-  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',
+      } as TestimonialSectionContent['items'][number];
+
+      repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
+    }
   }
-
-  content.items = updatedItems;
 };
 
 export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSectionContent> {
@@ -228,75 +211,29 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSec
       };
     }
 
-    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.
+      await applyTestimonialItemsAsync(content, args.items);
+    } else if (this.mode === 'create') {
+      if (args.items && Array.isArray(args.items)) {
         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.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),
+    } 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,
       );
-
-      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 as any);
-      }
-    }
-
-    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 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;
 

package/src/metadata-builder/builders/section-builders/text-section-builder.ts

@@ -19,6 +19,12 @@ import {
 } 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: unknown): { html: string; wasTiptap: boolean } => {
@@ -52,6 +58,7 @@ const createTextItem = (
   const { html, wasTiptap } = resolveText(item.text);
 
   return {
+    id: item.item_id || generateItemId(),
     text: html,
     textStyle: clearTextStyleTypeIfTiptap(
       textStyle,
@@ -61,6 +68,10 @@ const createTextItem = (
   };
 };
 
+/**
+ * Full replacement: discard existing items and rebuild from the payload,
+ * assigning a stable id to each new item.
+ */
 const applyTextItems = (
   content: TextContent,
   items: TextSectionItem[],
@@ -71,26 +82,33 @@ const applyTextItems = (
   );
 };
 
+/**
+ * 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: TextContent,
   items: TextSectionItem[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
   textStyleOptions: TextStyleOptions | undefined,
 ): void => {
-  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
-
-  if (hasIndexedItems) {
-    for (const item of items) {
-      const targetIndex = item.item_index;
+  ensureItemIds(content.textItems);
+  content.textItems = removeItemsByIds(content.textItems, removeIds);
 
-      if (
-        targetIndex === undefined ||
-        targetIndex < 0 ||
-        !content.textItems?.[targetIndex]
-      )
-        continue;
+  for (const item of items) {
+    if (item.item_id) {
+      const existing = content.textItems?.find((i) => i.id === item.item_id);
 
-      const existing = content.textItems[targetIndex];
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
       if (item.text !== undefined) {
         const { html, wasTiptap } = resolveText(item.text);
@@ -104,51 +122,32 @@ const mergeTextItems = (
       }
 
       if (item.text_style && typeof item.text_style === 'object') {
-        const mergedStyle = (
-          item.text_style
-            ? { ...(existing.textStyle || {}), ...item.text_style }
-            : existing.textStyle || {}
-        ) as TextStyleDeclaration;
-
-        existing.textStyle = mergedStyle;
+        existing.textStyle = {
+          ...(existing.textStyle || {}),
+          ...item.text_style,
+        } as TextStyleDeclaration;
       }
-    }
-
-    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
-    ) as TextStyleDeclaration;
 
-    const resolved = item.text !== undefined ? resolveText(item.text) : null;
-    const text = resolved ? resolved.html : (existing?.text ?? '');
-
-    return {
-      text,
-      textStyle: clearTextStyleTypeIfTiptap(
-        mergedStyle,
-        resolved?.wasTiptap ?? false,
+      repositionItemByAnchor(
+        content.textItems!,
+        existing,
+        item.move_before_item_id,
+      );
+    } else {
+      const newItem = createTextItem(
+        item,
+        content.textStyle || {},
         textStyleOptions,
-      ),
-    };
-  });
+      );
 
-  if (
-    !replaceAll &&
-    content.textItems &&
-    content.textItems.length > itemsToMerge.length
-  ) {
-    updatedItems.push(...content.textItems.slice(itemsToMerge.length));
+      content.textItems = content.textItems ?? [];
+      repositionItemByAnchor(
+        content.textItems,
+        newItem,
+        item.move_before_item_id,
+      );
+    }
   }
-
-  content.textItems = updatedItems;
 };
 
 /**
@@ -236,82 +235,31 @@ export class TextSectionBuilder extends BaseSectionBuilder<TextContent> {
 
     const args = this.args as TextSectionArguments;
 
-    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 }
-        ) as TextStyleDeclaration;
-
-        const { html, wasTiptap } = resolveText(item.text);
-        const newItem: TextItem = {
-          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/src/metadata-builder/builders/section-field-utils.ts

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

package/src/metadata-builder/builders/shape-color-utils.ts

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

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

@@ -4,7 +4,7 @@ import type {
   HeaderDisplayStyle,
   NavigationDisplayType,
 } from '../../brand-page/constants';
-import type { SectionType, TextStyleArguments } from './section-tool-arguments';
+import type { SectionType } from './section-tool-arguments';
 
 // Tool names — must match the function names generated by the AI pipeline.
 // Text element tools use camelCase names.
@@ -202,8 +202,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;
 }
@@ -215,6 +224,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;
@@ -223,12 +233,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). */