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

package/src/metadata-builder/builders/item-id-utils.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from 'vitest';
+import {
+  END_ITEM_ANCHOR,
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
+
+type Item = { id?: string; label: string };
+
+const items = (...labels: string[]): Item[] =>
+  labels.map((label) => ({ id: label, label }));
+
+const labels = (list: Item[]): string[] => list.map((i) => i.label);
+
+describe('generateItemId', () => {
+  it('returns unique uuid-shaped ids', () => {
+    const a = generateItemId();
+    const b = generateItemId();
+
+    expect(a).not.toBe(b);
+    expect(a).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+});
+
+describe('ensureItemIds', () => {
+  it('backfills only the items missing an id, preserving existing ones', () => {
+    const list: Item[] = [
+      { id: 'keep', label: 'a' },
+      { label: 'b' },
+      { id: '', label: 'c' },
+    ];
+
+    ensureItemIds(list);
+
+    expect(list[0].id).toBe('keep');
+    expect(list[1].id).toBeTruthy();
+    expect(list[2].id).toBeTruthy();
+    expect(new Set(list.map((i) => i.id)).size).toBe(3);
+  });
+
+  it('is a no-op for undefined', () => {
+    expect(() => ensureItemIds(undefined)).not.toThrow();
+  });
+});
+
+describe('removeItemsByIds', () => {
+  it('removes by id regardless of order (no index shifting)', () => {
+    const result = removeItemsByIds(items('a', 'b', 'c', 'd'), ['c', 'a']);
+
+    expect(labels(result)).toEqual(['b', 'd']);
+  });
+
+  it('returns the list unchanged when no ids given', () => {
+    const list = items('a', 'b');
+
+    expect(removeItemsByIds(list, undefined)).toBe(list);
+    expect(removeItemsByIds(list, [])).toBe(list);
+  });
+
+  it('returns [] for undefined items', () => {
+    expect(removeItemsByIds(undefined, ['x'])).toEqual([]);
+  });
+});
+
+describe('repositionItemByAnchor', () => {
+  it('appends a new item when no anchor is given', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+
+  it('leaves an existing item in place when no anchor is given', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[1], undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('inserts a new item before the anchor id', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'b');
+
+    expect(labels(list)).toEqual(['a', 'new', 'b', 'c']);
+  });
+
+  it('moves an existing item before the anchor id', () => {
+    const list = items('a', 'b', 'c', 'd');
+
+    // move 'd' before 'b'
+    repositionItemByAnchor(list, list[3], 'b');
+
+    expect(labels(list)).toEqual(['a', 'd', 'b', 'c']);
+  });
+
+  it('moves an existing item to the end with the __end__ sentinel', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[0], END_ITEM_ANCHOR);
+
+    expect(labels(list)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('falls through to the end when the anchor id is not found', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'missing');
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+});

package/src/metadata-builder/builders/item-id-utils.ts

@@ -0,0 +1,85 @@
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * Sentinel anchor meaning "the end of the list", mirroring the section-level
+ * `move_before_content_id: "__end__"` convention used in base-section-builder.
+ */
+export const END_ITEM_ANCHOR = '__end__';
+
+/** Generate a stable item id. Mirrors section-level `uuid.v4()` id generation. */
+export const generateItemId = (): string => uuidv4();
+
+/**
+ * Backfill ids onto any items missing one. Per BP-5603 this runs in the
+ * metadata builder when a section is processed, so the persisted metadata
+ * returned to the client gains stable ids that subsequent AI tool calls can
+ * reference. Mutates in place.
+ */
+export const ensureItemIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+): void => {
+  if (!items) return;
+
+  for (const item of items) {
+    if (!item.id) item.id = generateItemId();
+  }
+};
+
+/**
+ * Remove items whose id appears in `ids`. Order-independent (no descending
+ * index sort needed) — the whole point of the id-based migration. Items
+ * without an id are never removed by id.
+ */
+export const removeItemsByIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+  ids: string[] | undefined,
+): T[] => {
+  if (!items?.length) return items ?? [];
+
+  if (!ids?.length) return items;
+
+  const toRemove = new Set(ids);
+
+  return items.filter((item) => !item.id || !toRemove.has(item.id));
+};
+
+/**
+ * Position `item` within `items` relative to an anchor id — the item-level
+ * mirror of base-section-builder's `moveContent`:
+ *
+ * - `moveBeforeItemId === undefined`  → leave an existing item where it is;
+ *   append a new (not-yet-present) item to the end.
+ * - `moveBeforeItemId === "__end__"`  → move/insert at the very end.
+ * - anchor id found                   → insert immediately before it.
+ * - anchor id not found               → fall through to the end (same
+ *   forgiving behaviour as `moveContent`).
+ *
+ * Mutates `items` in place. `item` may be an existing element of `items`
+ * (a move) or a brand-new object (an insert).
+ */
+export const repositionItemByAnchor = <T extends { id?: string }>(
+  items: T[],
+  item: T,
+  moveBeforeItemId: string | undefined,
+): void => {
+  const currentIndex = items.indexOf(item);
+
+  if (moveBeforeItemId === undefined) {
+    if (currentIndex === -1) items.push(item);
+
+    return;
+  }
+
+  if (currentIndex !== -1) items.splice(currentIndex, 1);
+
+  const anchorIndex =
+    moveBeforeItemId === END_ITEM_ANCHOR
+      ? -1
+      : items.findIndex((i) => i.id === moveBeforeItemId);
+
+  if (anchorIndex !== -1) {
+    items.splice(anchorIndex, 0, item);
+  } else {
+    items.push(item);
+  }
+};

package/src/metadata-builder/builders/section-builders/image-gallery-builder.ts

@@ -10,6 +10,12 @@ import type { BuilderResult } from '../../models';
 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: ImageGalleryContent,
@@ -21,11 +27,17 @@ const applyGalleryType = (
   };
 };
 
+/**
+ * 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: ImageGalleryContent,
   images: ImageGalleryItem[],
 ): void => {
   content.images = images.map((img) => ({
+    id: img.item_id || generateItemId(),
     imageUrl: isValidUrl(img.image_url) ? img.image_url! : '',
     imageTitle: img.caption || '',
     width: 0,
@@ -35,84 +47,53 @@ const applyGalleryImages = (
   }));
 };
 
+/**
+ * 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: ImageGalleryContent,
   images: ImageGalleryItem[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): void => {
-  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' as const),
-      imageLink: img.imageLink ?? '',
-    }));
-
-    updatedImages.push(...extras);
-  }
-
-  content.images = updatedImages;
-};
-
-const insertGalleryImages = (
-  content: ImageGalleryContent,
-  images: ImageGalleryItem[],
-): void => {
-  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),
-  );
+  ensureItemIds(content.images);
+  content.images = removeItemsByIds(content.images, removeIds);
 
-  for (const img of sorted) {
-    if (!isValidUrl(img.image_url)) continue;
+  for (const img of images) {
+    if (img.item_id) {
+      const existing = content.images.find((i) => i.id === img.item_id);
 
-    if (content.images?.some((existing) => existing.imageUrl === img.image_url))
-      continue;
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
-    content.images = content.images ?? [];
-
-    const pos = Math.max(
-      0,
-      Math.min(img.insert_at ?? 0, content.images.length),
-    );
+      if (img.image_url !== undefined) {
+        existing.imageUrl = isValidUrl(img.image_url) ? img.image_url! : '';
+      }
 
-    content.images.splice(pos, 0, {
-      imageUrl: img.image_url!,
-      imageTitle: img.caption ?? '',
-      width: 0,
-      height: 0,
-      mediaType: 'image',
-      imageLink: '',
-      colorReplacements: [],
-    });
+      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' as const,
+        imageLink: '',
+      };
+
+      repositionItemByAnchor(content.images, newItem, img.move_before_item_id);
+    }
   }
 };
 
@@ -144,26 +125,19 @@ export class ImageGalleryBuilder extends BaseSectionBuilder<ImageGalleryContent>
       applyGalleryType(content, args.gallery_type);
     }
 
-    if (args.images && Array.isArray(args.images)) {
-      if (this.mode === 'create') {
+    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)) {
         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);
-        }
-      }
-    }
-
-    if (args.images && Array.isArray(args.images) && this.mode === 'update') {
-      insertGalleryImages(content, args.images);
+    } 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);
     }
 
     return { request: this.request, model };

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

@@ -18,12 +18,24 @@ import {
 } 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: ImagesSectionContent,
   items: ImagesSectionItem[],
 ): void => {
   content.items = items.map((item, index) => ({
+    id: item.item_id || generateItemId(),
     imageUrl: isValidUrl(item.image_url) ? item.image_url! : '',
     imageTitle: '',
     width: 0,
@@ -38,25 +50,33 @@ const applyImageItems = (
   }));
 };
 
+/**
+ * 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: ImagesSectionContent,
   items: ImagesSectionItem[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): void => {
-  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
+  ensureItemIds(content.items);
+  content.items = removeItemsByIds(content.items, removeIds);
 
-  if (hasIndexedItems) {
-    for (const item of items) {
-      const targetIndex = item.item_index;
+  for (const item of items) {
+    if (item.item_id) {
+      const existing = content.items.find((i) => i.id === item.item_id);
 
-      if (
-        targetIndex === undefined ||
-        targetIndex < 0 ||
-        !content.items?.[targetIndex]
-      )
-        continue;
-
-      const existing = content.items[targetIndex];
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
       if (isValidUrl(item.image_url)) existing.imageUrl = item.image_url!;
 
@@ -66,47 +86,27 @@ const mergeImageItems = (
 
       if (item.button_text !== undefined)
         existing.buttonText = item.button_text || false;
-    }
-
-    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,
-    ) as typeof updatedItems;
-
-    updatedItems.push(...remaining);
+      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: [],
+      } as ImagesSectionContent['items'][number];
+
+      repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
+    }
   }
-
-  content.items = updatedItems;
 };
 
 export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionContent> {
@@ -192,86 +192,23 @@ export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionConten
       };
     }
 
-    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.
+      applyImageItems(content, args.items);
+    } else if (this.mode === 'create') {
+      if (args.items && Array.isArray(args.items)) {
         applyImageItems(content, args.items);
-      } else {
-        mergeImageItems(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) {
-        if (!isValidUrl(item.image_url)) continue;
-
-        // Skip if this image_url already exists — defensive against duplicate
-        // tool call application
-        if (
-          content.items?.some(
-            (existing: any) => 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 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;
-        }
       }
+    } 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);
     }
 
-    // Re-index itemsId after any item operations
+    // Re-index itemsId after all id-based item operations (render concern —
+    // separate from the stable `id` used for targeting).
     if (content.items) {
       content.items.forEach((item, i) => {
         item.itemsId = i;