Skip to content

Fix GuestUIFrame losing connection when moved within a stable-keyed list (SITES-42495) - #150

Merged
fe-lix- merged 2 commits into
mainfrom
fix/SITES-42495-guestuiframe-reload-reconnect
Jul 22, 2026
Merged

fe-lix- merged 2 commits into
mainfrom
fix/SITES-42495-guestuiframe-reload-reconnect

Conversation

@fe-lix-

@fe-lix- fe-lix- commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Description

A host that renders GuestUIFrame for items in a reorderable list, keyed by
stable 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 initial
response 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:

  1. The host's multifield implementation keys each row by a stable per-item
    id (not array position), so a reorder doesn't change any row's key.
  2. Because the key is stable, React's reconciliation moves the existing
    GuestUIFrame DOM subtree to its new position instead of
    unmounting/remounting it.
  3. Moving a live cross-origin iframe within the DOM is a well-known browser
    quirk that can silently discard and reload its browsing context, even
    though React itself never unmounted anything.
  4. GuestUIFrame's connection-setting useEffect depends only on
    [guest.id], which never changes for a reorder, so it never re-runs and
    the host never re-attaches to the (now reloaded) iframe.
  5. Tunnel.toIframe's handshake listener (offerListener) only accepted an
    offer while !tunnel.isConnected, so once connected once, it would
    permanently 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.
  6. The reloaded guest's fresh attach() call then times out waiting for a
    response the host was never going to send.

This is a general property of @adobe/uix-host-react's GuestUIFrame /
@adobe/uix-core's Tunnel, not specific to any one host application - it
reproduces 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.js plus 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 rows
sharing one registered extension, each with its own GuestUIFrame keyed by
stable 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).

  • Before the fix: the test fails - the swapped row's guest gets a fresh
    boot id (proving the iframe silently reloaded) and its attach-status
    reads "error" with "Timed out waiting for initial response from parent after 5000ms".
  • After the fix: same test, unmodified, passes - the row still gets a fresh
    boot id (the browser still reloads the iframe; that part is unavoidable),
    but its attach-status now recovers to "connected".
  • A second test in the same file uses a genuine remount (new React key) as
    a positive control, confirming the harness reconnects cleanly when React
    actually unmounts/remounts - isolating the failure to the
    same-key-but-moved case specifically.
  • Full suite run locally via npm run test:e2e: 14/14 passing on this
    branch, 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 GuestUIFrame itself (it returns null before
its useEffect calls when host is still null, which crashes if the same
instance later re-renders with host populated). That's out of scope for
this 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

  • Bug fix (non-breaking change which fixes an issue)

Checklist

  • My code follows the code style of this project.
  • My change requires a change to the documentation. (No - the fixed
    behavior now matches what Tunnel.toIframe's own doc comment already
    promised: "The tunnel may reconnect if the iframe reloads.")
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes.
  • All new and existing tests passed.

Investigated and authored with Claude Code.

fe-lix- and others added 2 commits July 15, 2026 18:45
…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>
@fe-lix-
fe-lix- merged commit 9e7c1ee into main Jul 22, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants