@designcrowd/library.brand-page 6.0.12 → 6.0.13

package/src/metadata-builder/ai-metadata-executor.ts

@@ -22,6 +22,8 @@ import {
   type AddPageArguments,
   type RemovePageArguments,
   type RenamePageArguments,
+  type MovePageArguments,
+  type SetPageVisibilityArguments,
   type UpdateFooterArguments,
   type UpdateGlobalStylesArguments,
   type UpdateHeaderArguments,
@@ -101,7 +103,7 @@ export const executeToolCallsAsync = async (
             type: BUILDER_TYPES.MOVE_SECTION as BuilderType,
             payload: {
               contentId: arg.content_id,
-              position: arg.position,
+              moveBeforeContentId: arg.move_before_content_id,
               targetPageId: arg.target_page_id,
             },
           };
@@ -145,6 +147,34 @@ export const executeToolCallsAsync = async (
           };
         }
 
+        case AI_ASSISTANT_TOOL_NAMES.MOVE_PAGE: {
+          const arg = toolcall.arguments as unknown as MovePageArguments;
+
+          return {
+            id: toolcall.toolId,
+            type: BUILDER_TYPES.MOVE_PAGE as BuilderType,
+            payload: {
+              pageId: arg.page_id,
+              parentPageId: arg.parent_page_id,
+              moveBeforePageId: arg.move_before_page_id,
+            },
+          };
+        }
+
+        case AI_ASSISTANT_TOOL_NAMES.SET_PAGE_VISIBILITY: {
+          const arg =
+            toolcall.arguments as unknown as SetPageVisibilityArguments;
+
+          return {
+            id: toolcall.toolId,
+            type: BUILDER_TYPES.SET_PAGE_VISIBILITY as BuilderType,
+            payload: {
+              pageId: arg.page_id,
+              isHidden: arg.is_hidden,
+            },
+          };
+        }
+
         case AI_ASSISTANT_TOOL_NAMES.UPDATE_FOOTER: {
           const arg = toolcall.arguments as unknown as UpdateFooterArguments;
 

package/src/metadata-builder/builders/footer-builder.test.ts

@@ -14,6 +14,10 @@ import { FooterBuilder } from './footer-builder';
  * The fix routes copyright style writes through `applyDetachedStyleOverride`,
  * which resolves the preset in and clears `textStyleType` so the per-element
  * override sticks.
+ *
+ * BP-5603: social link mutations converted from index-based to id-based
+ * (item_id / move_before_item_id / _remove_social_link_ids), mirroring the
+ * section-level move_before_content_id contract one level deeper.
  */
 
 const textStyleOptions = {
@@ -42,6 +46,37 @@ const makeModel = (copyrightStyle: Record<string, unknown>): BrandPageModel =>
     pageFooterMobile: { copyrightStyle: { ...copyrightStyle } },
   }) as unknown as BrandPageModel;
 
+const makeModelWithLinks = (
+  links: { id?: string; imageUrl: string; url: string }[],
+): BrandPageModel =>
+  ({
+    styles: { textStyles: { textStyleOptions } },
+    pageFooterDesktop: {
+      copyrightStyle: {},
+      socialLinks: links.map((l) => ({
+        id: l.id,
+        imageUrl: l.imageUrl,
+        url: l.url,
+        imageTitle: '',
+        width: 0,
+        height: 0,
+        imageLink: '',
+      })),
+    },
+    pageFooterMobile: {
+      copyrightStyle: {},
+      socialLinks: links.map((l) => ({
+        id: l.id,
+        imageUrl: l.imageUrl,
+        url: l.url,
+        imageTitle: '',
+        width: 0,
+        height: 0,
+        imageLink: '',
+      })),
+    },
+  }) as unknown as BrandPageModel;
+
 const run = (args: UpdateFooterArguments, model: BrandPageModel) =>
   new FooterBuilder({
     id: 'f1',
@@ -49,6 +84,10 @@ const run = (args: UpdateFooterArguments, model: BrandPageModel) =>
     payload: args,
   }).buildAsync(model);
 
+// ---------------------------------------------------------------------------
+// Copyright font (BP-5420)
+// ---------------------------------------------------------------------------
+
 describe('FooterBuilder — copyright font vs global style', () => {
   it('detaches from the global preset: applies the font, clears textStyleType, retains preset values', async () => {
     const model = makeModel({
@@ -137,9 +176,10 @@ describe('FooterBuilder — copyright font vs global style', () => {
   });
 });
 
-type Link = { imageUrl: string; url: string };
+type Link = { id?: string; imageUrl: string; url: string };
 
-const link = (imageUrl: string): Link => ({
+const link = (imageUrl: string, id?: string): Link => ({
+  ...(id && { id }),
   imageUrl,
   url: `https://${imageUrl}.com`,
 });
@@ -173,18 +213,15 @@ const socialIcons = (footer: { socialLinks?: Link[] } | undefined) =>
 describe('FooterBuilder — social link removal (shared-array regression)', () => {
   // Reproduces the bug: a single requested removal index dropped TWO links
   // because both viewports shared one array and the builder spliced it twice.
-  it('removes exactly one link per requested index even when viewports share the array', async () => {
+  it('removes exactly one link per requested id even when viewports share the array', async () => {
     const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
-      link('youtube'),
+      link('facebook', 'fb'),
+      link('instagram', 'ig'),
+      link('x', 'x'),
+      link('youtube', 'yt'),
     ]);
 
-    const { model: out } = await run(
-      { _remove_social_link_indices: [2] },
-      model,
-    );
+    const { model: out } = await run({ _remove_social_link_ids: ['x'] }, model);
 
     expect(socialIcons(out.pageFooterDesktop)).toEqual([
       'facebook',
@@ -200,13 +237,13 @@ describe('FooterBuilder — social link removal (shared-array regression)', () =
 
   it('un-shares the viewport arrays so later in-place edits cannot cross-corrupt', async () => {
     const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
+      link('facebook', 'fb'),
+      link('instagram', 'ig'),
+      link('x', 'x'),
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [0] },
+      { _remove_social_link_ids: ['fb'] },
       model,
     );
 
@@ -215,16 +252,16 @@ describe('FooterBuilder — social link removal (shared-array regression)', () =
     );
   });
 
-  it('handles multiple removal indices on a shared array (descending splice)', async () => {
+  it('handles multiple removal ids on a shared array (order-independent)', async () => {
     const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
-      link('youtube'),
+      link('facebook', 'fb'),
+      link('instagram', 'ig'),
+      link('x', 'x'),
+      link('youtube', 'yt'),
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [0, 2] },
+      { _remove_social_link_ids: ['fb', 'x'] },
       model,
     );
 
@@ -235,15 +272,15 @@ describe('FooterBuilder — social link removal (shared-array regression)', () =
     expect(socialIcons(out.pageFooterMobile)).toEqual(['instagram', 'youtube']);
   });
 
-  it('removes one link per index for independent viewport arrays (no regression)', async () => {
+  it('removes one link per id for independent viewport arrays (no regression)', async () => {
     const model = makeIndependentSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
+      link('facebook', 'fb'),
+      link('instagram', 'ig'),
+      link('x', 'x'),
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [1] },
+      { _remove_social_link_ids: ['ig'] },
       model,
     );
 
@@ -252,11 +289,16 @@ describe('FooterBuilder — social link removal (shared-array regression)', () =
   });
 
   it('inserts exactly one link on a shared array (symmetric add guard)', async () => {
-    const model = makeSharedSocialModel([link('facebook'), link('instagram')]);
+    const model = makeSharedSocialModel([
+      link('facebook', 'fb'),
+      link('instagram', 'ig'),
+    ]);
 
     const { model: out } = await run(
       {
-        social_links: [{ insert_at: 1, social_link_icon: 'x', url: 'x.com' }],
+        social_links: [
+          { social_link_icon: 'x', url: 'x.com', move_before_item_id: 'ig' },
+        ],
       },
       model,
     );
@@ -273,3 +315,268 @@ describe('FooterBuilder — social link removal (shared-array regression)', () =
     ]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Social links — id-based mutations (BP-5603)
+// ---------------------------------------------------------------------------
+
+describe('FooterBuilder — social links id-based mutations', () => {
+  it('backfills ids on legacy links when a social mutation runs', async () => {
+    // Links without ids (legacy persisted data). The executor recomputes social
+    // links only when a social-link mutation is present (a copyright-only update
+    // must not rewrite them); read-time backfill lives in ensureBrandPageItemIds.
+    const model = makeModelWithLinks([
+      { imageUrl: 'facebook', url: 'https://fb.com' },
+      { imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
+
+    const { model: out } = await run(
+      { social_links: [{ social_link_icon: 'x', url: 'https://x.com' }] },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks!;
+
+    // Pre-existing legacy links are backfilled with distinct stable ids.
+    expect(links[0].id).toBeTruthy();
+    expect(links[1].id).toBeTruthy();
+    expect(links[0].id).not.toBe(links[1].id);
+  });
+
+  it('updates an existing link in place by item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          { item_id: 'link-1', url: 'https://facebook.com/mybrand' },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[0].url).toBe('https://facebook.com/mybrand');
+    expect(links[0].id).toBe('link-1');
+    // untouched link unchanged
+    expect(links[1].id).toBe('link-2');
+    expect(links[1].url).toBe('https://ig.com');
+  });
+
+  it('updates social_link_icon on an existing link', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'link-1', social_link_icon: 'facebook-v2' }],
+      },
+      model,
+    );
+
+    expect(out.pageFooterDesktop!.socialLinks[0].imageUrl).toBe('facebook-v2');
+  });
+
+  it('skips unknown item_id silently', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'no-such-id', url: 'https://nowhere.com' }],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(1);
+    expect(links[0].url).toBe('https://fb.com');
+  });
+
+  it('inserts a new link (no item_id) appended by default', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          { social_link_icon: 'instagram', url: 'https://ig.com' },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[1].imageUrl).toBe('instagram');
+    expect(links[1].id).toBeTruthy();
+  });
+
+  it('inserts a new link before an anchor via move_before_item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          {
+            social_link_icon: 'x',
+            url: 'https://x.com',
+            move_before_item_id: 'link-2',
+          },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(3);
+    expect(links[0].id).toBe('link-1');
+    expect(links[1].imageUrl).toBe('x');
+    expect(links[2].id).toBe('link-2');
+  });
+
+  it('inserts a new link at end via move_before_item_id "__end__"', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          {
+            social_link_icon: 'x',
+            url: 'https://x.com',
+            move_before_item_id: '__end__',
+          },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(3);
+    expect(links[2].imageUrl).toBe('x');
+  });
+
+  it('moves an existing link before an anchor via move_before_item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+      { id: 'link-3', imageUrl: 'x', url: 'https://x.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'link-3', move_before_item_id: 'link-1' }],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links.map((l) => l.id)).toEqual(['link-3', 'link-1', 'link-2']);
+  });
+
+  it('removes links by id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+      { id: 'link-3', imageUrl: 'x', url: 'https://x.com' },
+    ]);
+
+    const { model: out } = await run(
+      { _remove_social_link_ids: ['link-1', 'link-3'] },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(1);
+    expect(links[0].id).toBe('link-2');
+  });
+
+  it('_replace_social_links rebuilds the entire list and assigns fresh ids', async () => {
+    const model = makeModelWithLinks([
+      { id: 'old-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        _replace_social_links: true,
+        social_links: [
+          { social_link_icon: 'instagram', url: 'https://ig.com' },
+          { social_link_icon: 'x', url: 'https://x.com' },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[0].imageUrl).toBe('instagram');
+    expect(links[1].imageUrl).toBe('x');
+    // fresh ids assigned, not the old one
+    expect(links[0].id).toBeTruthy();
+    expect(links[0].id).not.toBe('old-1');
+  });
+
+  it('_replace_social_links with empty social_links clears all', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run({ _replace_social_links: true }, model);
+
+    expect(out.pageFooterDesktop!.socialLinks).toHaveLength(0);
+  });
+
+  it('normalises mailto: and tel: prefixes on new links', async () => {
+    const model = makeModelWithLinks([]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          { social_link_icon: 'email', url: 'mailto:me@example.com' },
+          { social_link_icon: 'phone', url: 'tel:+1234567890' },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links[0].url).toBe('me@example.com');
+    expect(links[1].url).toBe('+1234567890');
+  });
+
+  it('applies mutations to both desktop and mobile footers', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
+
+    const { model: out } = await run(
+      { _remove_social_link_ids: ['link-1'] },
+      model,
+    );
+
+    expect(out.pageFooterDesktop!.socialLinks).toHaveLength(0);
+    expect(out.pageFooterMobile!.socialLinks).toHaveLength(0);
+  });
+});

package/src/metadata-builder/builders/footer-builder.ts

@@ -10,7 +10,6 @@ import {
 import type {
   UpdateFooterArguments,
   ViewportFooterOverrides,
-  FooterSocialLinkItem,
 } from '../parsers/ai-toolcall-parser';
 import type { Logger } from '../logger';
 import type {
@@ -22,6 +21,11 @@ import {
   applyDetachedStyleOverride,
   normalizeStyleValue,
 } from './section-field-utils';
+import {
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
 
 type FooterSocialLink = NonNullable<
   AbstractPageFooterStyles['socialLinks']
@@ -40,6 +44,7 @@ const makeSocialLink = (
   url: string | undefined,
 ): FooterSocialLink =>
   ({
+    id: generateItemId(),
     imageUrl: icon || '',
     url: normaliseSocialUrl(url || ''),
     imageTitle: '',
@@ -50,8 +55,7 @@ const makeSocialLink = (
 
 const hasSocialLinkMutation = (args: UpdateFooterArguments): boolean =>
   args._replace_social_links === true ||
-  (args._remove_social_link_indices?.length ?? 0) > 0 ||
-  (args._reorder_social_links?.length ?? 0) > 0 ||
+  (args._remove_social_link_ids?.length ?? 0) > 0 ||
   (args.social_links?.length ?? 0) > 0;
 
 /**
@@ -80,62 +84,41 @@ const computeSocialLinks = (
     );
   }
 
-  const links: FooterSocialLink[] = [...(current ?? [])];
-
-  // item_index-based updates for existing links — replace the item reference
-  // (never mutate the original object, which may be shared across viewports).
-  for (const link of args.social_links ?? []) {
-    if (link.item_index === undefined) continue;
-
-    const existing = links[link.item_index];
-
-    if (!existing) continue;
-
-    links[link.item_index] = {
-      ...existing,
-      ...(link.social_link_icon !== undefined
-        ? { imageUrl: link.social_link_icon }
-        : {}),
-      ...(link.url !== undefined ? { url: normaliseSocialUrl(link.url) } : {}),
-    };
-  }
-
-  // Remove by index (descending order to preserve indices during splice).
-  if (args._remove_social_link_indices?.length) {
-    const sorted = [...args._remove_social_link_indices].sort((a, b) => b - a);
+  // Work on fresh copies so `current` (which may be shared across viewports)
+  // is never mutated. Backfill ids on the copies so legacy links become
+  // referenceable by the id-based contract (BP-5603).
+  let links: FooterSocialLink[] = (current ?? []).map((l) => ({
+    ...l,
+    id: l.id || generateItemId(),
+  }));
 
-    for (const idx of sorted) {
-      if (idx >= 0 && idx < links.length) links.splice(idx, 1);
-    }
-  }
-
-  // Insert new links (descending insert_at order to preserve positions).
-  const insertLinks = (args.social_links ?? []).filter(
-    (l): l is FooterSocialLinkItem & { insert_at: number } =>
-      l.insert_at !== undefined && l.item_index === undefined,
-  );
-  const sortedInserts = [...insertLinks].sort(
-    (a, b) => b.insert_at - a.insert_at,
-  );
+  // Remove by id — order-independent, no index shifting.
+  links = removeItemsByIds(links, args._remove_social_link_ids);
 
-  for (const link of sortedInserts) {
-    const pos = Math.max(0, Math.min(link.insert_at, links.length));
-
-    links.splice(pos, 0, makeSocialLink(link.social_link_icon, link.url));
-  }
-
-  // Reorder (requires ALL indices — partial reorder is not supported).
-  if (args._reorder_social_links?.length) {
-    const newOrder = args._reorder_social_links;
-    const unique = new Set(newOrder);
-
-    if (
-      unique.size === newOrder.length &&
-      newOrder.every((idx) => idx >= 0 && idx < links.length)
-    ) {
-      const reordered = newOrder.map((idx) => links[idx]);
-
-      if (reordered.length === links.length) return reordered;
+  // Update existing links (item_id present) or insert new ones (no item_id);
+  // position/move via move_before_item_id ("__end__" or a missing anchor => end).
+  for (const link of args.social_links ?? []) {
+    if (link.item_id) {
+      const index = links.findIndex((l) => l.id === link.item_id);
+
+      // Unknown id — skip rather than guess at a position.
+      if (index === -1) continue;
+
+      links[index] = {
+        ...links[index],
+        ...(link.social_link_icon !== undefined
+          ? { imageUrl: link.social_link_icon }
+          : {}),
+        ...(link.url !== undefined
+          ? { url: normaliseSocialUrl(link.url) }
+          : {}),
+      };
+
+      repositionItemByAnchor(links, links[index], link.move_before_item_id);
+    } else {
+      const newLink = makeSocialLink(link.social_link_icon, link.url);
+
+      repositionItemByAnchor(links, newLink, link.move_before_item_id);
     }
   }