Repository navigation
Fix GuestUIFrame losing connection when moved within a stable-keyed list (SITES-42495) - #150
Merged
Merged
Conversation
…rder Adds a #/reorder host scenario with two rows sharing one registered extension, each with its own GuestUIFrame keyed by stable per-row identity (matching how consumers like @aem-sites/headless-components' Multifield key reorderable items). Swapping row positions moves the live iframe in the DOM without unmounting it; the browser silently reloads it, and the host never re-attaches because Tunnel.toIframe latches connected state permanently. The reloaded guest's fresh attach() call then times out. The test asserts the correct behavior (both rows stay connected after a swap) and currently fails, reproducing SITES-42495. A second test uses a genuine remount (new key) as a positive control, confirming the harness itself reconnects cleanly when React actually unmounts/remounts. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…load Tunnel.toIframe's offerListener only accepted a handshake offer while !tunnel.isConnected, so once a connection was established it would permanently ignore any further offer from the same iframe. If a host re-renders and physically moves a live GuestUIFrame in the DOM (e.g. a reorderable list keyed by stable per-item identity, as multifield-style UIs do), the browser can silently reload that iframe's browsing context without React ever unmounting the component. The reloaded guest starts a brand new handshake, but the host's existing tunnel was deaf to it - the guest's attach() call would time out waiting for a response that was never coming (SITES-42495). Removing the isConnected guard lets the host accept that fresh offer and reconnect, matching the "may reconnect if the iframe reloads" behavior already documented on this method. This can't regress a healthy connection: a guest only sends offers before its own tunnel is connected (Tunnel.toParent's sendOffer stops retrying once connected), so a still-alive guest never re-offers in the first place. Verified against e2e/tests/tests/multifield-reorder.js, which now passes without any changes to the test itself. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
kokoc
approved these changes
Jul 15, 2026
5 of 6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A host that renders
GuestUIFramefor items in a reorderable list, keyed bystable per-item identity (not array position), loses the connection to that
guest permanently when an item is reordered - even though React never
unmounts the component. This PR adds an e2e test that reproduces the failure
and a one-line fix in
Tunnel.toIframe.Related Issue
Reported internally as SITES-42495 (Adobe internal Jira - AEM Content
Fragment Editor customer escalation): https://jira.corp.adobe.com/browse/SITES-42495
There isn't a public GitHub issue for this - it came in through an internal
customer support ticket for a UIX extension embedded in AEM's Content
Fragment Editor, not through this repo's issue tracker.
Motivation and Context
A customer's UIX extension provided a custom field renderer for a multifield
(repeatable field) in the AEM Content Fragment Editor. Reordering an item in
the multifield made that item's extension iframe go permanently blank - the
guest's
attach()call would time out with "Timed out waiting for initialresponse from parent after 20000ms". The PATCH/save of the reorder itself
succeeded; this was purely a UI connection problem, and it was 100%
reproducible.
Root cause, traced end to end:
id (not array position), so a reorder doesn't change any row's key.
GuestUIFrameDOM subtree to its new position instead ofunmounting/remounting it.
quirk that can silently discard and reload its browsing context, even
though React itself never unmounted anything.
GuestUIFrame's connection-settinguseEffectdepends only on[guest.id], which never changes for a reorder, so it never re-runs andthe host never re-attaches to the (now reloaded) iframe.
Tunnel.toIframe's handshake listener (offerListener) only accepted anoffer while
!tunnel.isConnected, so once connected once, it wouldpermanently ignore any further handshake offer from that same iframe -
including the reloaded guest's fresh one. Its only watchdog
(
frameStatusCheck) checks whether the iframe was removed from the DOM,which doesn't catch an in-place reload.
attach()call then times out waiting for aresponse the host was never going to send.
This is a general property of
@adobe/uix-host-react'sGuestUIFrame/@adobe/uix-core'sTunnel, not specific to any one host application - itreproduces with a plain React state swap and no drag-and-drop library
involved at all.
How Has This Been Tested?
Added
e2e/tests/tests/multifield-reorder.jsplus supporting fixtures(
e2e/host-app/src/HostAppReorder.jsx,e2e/guest-app/src/UiFrameProbe.jsx,routing wire-up in both apps'
App.js). The scenario mounts two rowssharing one registered extension, each with its own
GuestUIFramekeyed bystable per-row identity, and a button that swaps their positions via a pure
identity-preserving array swap (mirroring how a typical multifield reorder
updates its underlying value array).
boot id (proving the iframe silently reloaded) and its
attach-statusreads
"error"with"Timed out waiting for initial response from parent after 5000ms".boot id (the browser still reloads the iframe; that part is unavoidable),
but its
attach-statusnow recovers to"connected".a positive control, confirming the harness reconnects cleanly when React
actually unmounts/remounts - isolating the failure to the
same-key-but-moved case specifically.
npm run test:e2e: 14/14 passing on thisbranch, no regressions to the 12 pre-existing e2e tests.
Along the way, reproducing this also surfaced a separate, pre-existing
Rules-of-Hooks violation in
GuestUIFrameitself (it returnsnullbeforeits
useEffectcalls whenhostis still null, which crashes if the sameinstance later re-renders with
hostpopulated). That's out of scope forthis PR - the new test scenario sidesteps it by gating on extension-load
completion, matching real-world timing where a custom field renderer is
only chosen once its extension is already known - but it's worth its own
follow-up issue.
Types of changes
Checklist
behavior now matches what
Tunnel.toIframe's own doc comment alreadypromised: "The tunnel may reconnect if the iframe reloads.")
Investigated and authored with Claude Code.