Popup Handoff, Return, and Window Ownership

Working case

A reviewer opens a supplier confirmation window for attachment 62. The host records a one-use handoff ID and displays a pending state. The supplier may send a completion hint, but the host asks its own server for the status of that handoff before marking the attachment verified. If the popup is blocked, the reviewer follows a same-task redirect link. If the popup closes early, the host offers retry or cancel without discarding the case note. The callback contains no full report and no long-lived secret.

Implementation boundary

function mayRefreshHandoff(activeHandoff, returnHint) {
  return activeHandoff.status === 'pending' && returnHint.handoffId === activeHandoff.id;
}
console.log(mayRefreshHandoff({ id: 30, status: 'pending' }, { handoffId: 29 }));
// Output: false

Start the window from an explicit click and record the handoff on the server before opening it. Scope the return to a short-lived ID tied to the user's current case and expire it after use. If messaging is part of the flow, check exact origin, source, version, and ID; then query server status. Avoid unnecessary opener access by using a redirect-based return or an isolation choice compatible with the integration. Detect a blocked popup by the opening result and show the redirect route. Poll only within a bounded interval, stop on account switch, and restore focus to the initiating control when the task ends. Keep the final server write idempotent.

Cost and boundaries

Popup polling consumes requests while the supplier is idle. Use a modest interval, visible pending state, and a clear timeout; an event hint can shorten the wait but cannot replace a verified read. A second window also creates attention and accessibility costs, so compare task completion against a full-page redirect before adopting it. One-use handoff records require storage and expiry jobs; the storage cost is small, but orphaned records and retries must have defined cleanup. Measure completion rate, blocked-window fallback use, and stale pending duration without logging private case contents.

Failure trace

The supplier window sends a success message for handoff 29 while the host now shows handoff 30. If the host trusts the message, it marks the wrong attachment complete. Test that mismatch, a blocked popup, a window closed without return, an expired callback, and a duplicated server result. Also test keyboard and screen-reader focus after the popup closes. The host should never change durable case state from the message alone, and a retry should not create two supplier confirmations.

Verification

• A blocked popup has a complete redirect route.
• Return hints trigger verified status reads only.
• Expired and duplicate handoffs cannot settle another case.

Practice drill

Create handoff 29, switch to case 30, and deliver the old completion hint. Confirm that the host performs no status update for case 30. Repeat with a valid hint and let the server return pending, then completed. Block window opening and finish through the redirect route. Count polling requests until timeout, and verify that closing the host page does not leave an unlimited polling job running.

Decision note

Let the server settle the handoff; the popup only helps the user reach and return from it.

Common Mistakes

• Calling a popup message the final server result.
• Opening a window outside a user action and hiding the blocked state.
• Polling indefinitely after navigation or account switch.

Connected lessons

Build Project: embedded attachment viewer contract and review Web Development: embedded interfaces and build integrity quiz; follow Embedded Interfaces and Cross-Window Contracts; Frame Sandbox, Capabilities, and Fallback; Cross-Window Messages: Origin, Source, Schema, and Replay; MessageChannel Lifetime and Request Correlation; Hosted Checkout Sessions and Browser Returns; Navigation, History, and Page Lifecycle.