How to embed a widget without disrupting the host page

The ShopTools AI extension helps test promo codes on supported merchant pages. An interface embedded there needs to keep checkout accessible. That is a more useful design priority than making the widget impossible to miss.

Choose a style boundary

JavaScript isolation does not isolate injected markup from the page's CSS. Global merchant rules can change buttons, fonts and dimensions. The options below are design choices, not a description of the current ShopTools build.

• Prefixed classes and IDs reduce accidental collisions but cannot block every global rule.
• Shadow DOM helps separate styles; inheritance and theming still need testing.
• An iframe provides a separate document, at the cost of more work on sizing, focus and messaging.

With ordinary DOM markup, scope style resets to the widget's own root. Do not restyle every merchant button to fix your panel. Check box sizing, margins, text transformations and visible keyboard focus.

Make initialization and teardown symmetrical

Running initialization again should not create another panel or another set of listeners. A root marker helps, but its presence does not establish that old subscriptions and observers were cleaned up.

Define what happens after a route change, checkout-container replacement or user disable action. Teardown should remove the widget's nodes, listeners and observers without touching the merchant's own interface.

Test re-enabling too: the interface should return exactly once. A delayed callback must not resurrect a panel the user has removed.

Do not win every stacking contest

An extremely high z-index is not a priority policy. The widget must not cover payment, error messages, delivery choices or merchant dialogs. Moving or hiding it can be more appropriate than bringing it to the front.

On a narrow screen, constrain the panel to the available space and allow its content to scroll. Long translations, larger text and the on-screen keyboard must not make primary actions unreachable.

Respect the system's reduced-motion preference. When an operation stops, its animation should stop too. Persistent pulsing is not evidence that work is taking place.

Test interference, not just appearance

1. Create a fixture with a global button { all: unset; } rule. The widget button should retain its intended dimensions, styling and visible keyboard focus when reached with Tab.
2. Place a dialog over checkout and verify keyboard access to merchant actions.
3. Replace the checkout root several times, then count panels and listener invocations.
4. Repeat at narrow widths, with larger text and reduced motion.
5. Disable the widget while a response is pending and confirm it does not reappear.

These checks define coexistence requirements; they do not establish compatibility with every site. Even an isolated panel shares screen space and attention with the merchant. No single CSS technique removes that constraint.