# KRB Image Cluster replacement v5 notes

## Why v5 exists

Sylvain's v4 test on Weddings failed at the append/rotate verification step. That suggests `append(existingElement)` may not behave as a pure move in the Page Slot context, or the Designer API may return fresh element proxy objects that break object-identity verification.

## v5 change

v5 implements the docs workaround more literally:

1. Append the replacement gallery to the Page Slot.
2. Append/re-add every component that originally came after the Image Cluster.
3. Locate the newly appended replacement by element id/component-name fallback rather than object identity only.
4. Remove the obsolete Image Cluster and any original trailing siblings that still remain before the replacement.
5. Verify the replacement finishes at the original Image Cluster index.

This should handle both possible behaviours:

- If `append(existingElement)` moves the existing configured instance, v5 removes only the obsolete source.
- If `append(existingElement)` creates/re-adds a configured copy and leaves the original in place, v5 removes the original source/trailing block before the newly appended replacement.

## Safety

- Defaults remain `dryRun: true` and `runMode: 'current-page'`.
- Result prefix: `KRB_IMAGE_CLUSTER_REPLACEMENT_V5_RESULT`.
- No publish/site/style/CMS/redirect operations.
- Still does not touch `Section Controls / Hide section`.
- If verification fails, it throws rather than knowingly leaving the final order wrong.

## Important before running on Weddings

If v4's failed live run left an appended gallery or duplicated trailing component at the bottom of the page slot, manually undo that in Designer or reload/revert the page state before running v5. v5 assumes the page starts from the audited state: `Section / Image Cluster` followed by the original trailing components.