feat: load simulation panel UI in loadLazy (AEM Sidekick)

[ramboz]

Summary

In v2 the experiment/audience/campaign simulation UI was moved out of the plugin's own injected overlay and into a hosted MFE that the AEM Sidekick extension opens. But nothing on the page ever loaded it: loadLazy() in src/index.js was an empty placeholder, so the Sidekick "Experimentation" button dispatched its custom event to nobody — a silent no-op with no console error. This is the issue reported in SITES-48456.

This makes the plugin own that wiring in its lazy phase, so a consuming project no longer copies a listener script into tools/sidekick/ or adds anything to head.html.

Changes

• loadLazy(document, options) now:
  • binds the Sidekick toolbar button (custom:aem-experimentation-sidekick) to the panel, falling back to the sidekick-ready event since the extension injects its element asynchronously;
  • lazy-loads the hosted MFE client.js on first use and toggles the panel thereafter;
  • opens the panel automatically on a ?experiment=<id>/<variant> simulation deep-link;
  • restores the panel after a variant-switch triggers a full-page reload.
• It is gated to preview/dev only (setDebugMode) and never runs in production.
• New simulationUI option — 'auto' (default) | 'sidekick' | 'universal-editor' | false — provides a clean way to distinguish the EDS + Sidekick surface from the Universal Editor, where the panel is delivered as a UE extension instead. 'auto' only activates on the Sidekick path, so a UE context naturally gets nothing.
• setupCommunicationLayer is now idempotent, so the eager and lazy phases can both ensure the postMessage handshake exists (the panel now works even on preview pages with no experiment configured yet). Its reload handler also preserves the panel's open state across the reload.
• Docs: README gains runExperimentationLazy in the loader, the loadLazy() wiring, the simulationUI option, and an "Enabling the simulation panel (AEM Sidekick)" section. That section keeps the still-necessary Sidekick plugin registration (config.json) and the helix5 persisted-config / PUT-vs-POST gotcha, and drops the obsolete copy-script / head.html steps. documentation/experiments.md's Simulation section is corrected (v1 overlay → v2 panel, audience → experiment query param). Adds documentation/sidekick/config.json as a reference.

Relationship to #61

This supersedes the fragile half of #61: the ~167-line copy-paste aem-experimentation.js listener is no longer needed because the plugin owns it (versioned, no CSP-nonce trap, no silent no-op). The genuinely project-side parts of #61 — the Sidekick config.json registration and the helix5 admin-config gotcha — are preserved here in the README. Thanks to @keepthebyte for working out the reference implementation and documenting the gotchas first-hand.

Test plan

• npm run lint:js clean
• npx playwright test — 88 passed
• Maintainer verification of the live Sidekick panel behavior against a real v2 project (MFE URL / handshake).

🤖 Generated with Claude Code

[ramboz]

Updated (a8606da) to address a performance concern: the simulation/preview UI no longer lives in the core engine (index.js). It's been extracted into a dedicated src/simulation.js that loadLazy pulls in via a dynamic import(), only in preview environments.

Why this matters: previously the panel/handshake code (~200 lines) shipped inside the eager-loaded engine module and was parsed on every production experiment page, despite only ever running in preview. Now:

• index.js (the engine) is ~200 lines leaner and carries no UI code.
• simulation.js is a separate chunk fetched only when loadLazy reaches the import in preview — production never downloads or parses it.
• Still versioned/owned by the plugin (no per-project copy-paste), so it doesn't reintroduce docs: document Sidekick Experimentation panel setup for v2 #61's drift problem.

The postMessage handshake (setupCommunicationLayer) moved into the lazy module too, so it's all one preview concern — behavior-preserving since it was already preview-gated and the panel that uses it is lazy/user-triggered.

No public API change (loadLazy, runExperimentationLazy, simulationUI unchanged). Lint clean; full suite green.

[codecov]

Codecov Report

❌ Patch coverage is 82.26950% with 25 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/simulation.js	81.19%	15 Missing and 7 partials ⚠️
src/index.js	87.50%	2 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Dereje24]

Multi-perspective review

Reviewed via the diff plus targeted raw-file fetches at head (a8606da) — confirmed DEFAULT_OPTIONS, setDebugMode, and the file tree; did not run build/lint/Playwright locally. Perspectives applied: Architecture, SRE/Reliability, Security, Product/Consumer.

Summary

Makes the plugin own the Sidekick simulation-panel wiring in loadLazy, replacing the fragile per-project copy-paste from #61, and (in the follow-up commit) extracts it into a lazily import()-ed src/simulation.js so no simulation code ships on the production eager path. Clean, well-documented, correctly preview/dev-gated. Close to mergeable; main gaps are one reliability edge and an under-documented consumer migration.

Strengths

• The a8606da refactor is the right call — moving ~200 lines of panel/handshake code out of the eager engine into a dynamic chunk means production pages never fetch or parse simulation code. Concrete critical-path win.
• Defense-in-depth gating — the loader's coarse isPreview check and loadLazy's authoritative setDebugMode re-check are identical logic, so there's no "loader allows but plugin silently rejects" trap.
• Idempotent communication layer — the isCommunicationLayerInitialized flag cleanly prevents duplicate message listeners.
• Thoughtful UX — the ?experiment=<id>/<variant> deep-link auto-open and the sessionStorage-based re-open across a variant-switch reload.
• Docs are thorough — README preserves the genuinely project-side parts of docs: document Sidekick Experimentation panel setup for v2 #61 (Sidekick config.json, the helix5 PUT-creates / POST-updates gotcha) and documentation/experiments.md is correctly updated (v1 overlay → v2 panel, audience → experiment).

Blockers

None. Preview/dev-only authoring tooling that never runs in production.

Should Fix

1. A failed MFE script load permanently disables the button — src/simulation.js (createSimulationPanelController, load/toggle)
On script.onerror, loadPromise rejects but is left assigned, and open() swallows the rejection into a console.debug. Every subsequent toggle() then hits if (!loadPromise) → false, skips open(), calls togglePanel(false) on a container that was never injected (no-op), and returns the already-rejected promise. A single transient network blip on first click bricks the Experimentation button until a full page reload, with only a debug-level log. Reset the promise so the next interaction retries:

script.onerror = (e) => {
  loadPromise = null; // allow retry on next toggle
  reject(e);
};

Perspective: SRE / Reliability

2. Moving the handshake out of the eager phase is a consumer behavior change that isn't flagged as a migration — src/index.js (loadEager), README
Previously loadEager called setupCommunicationLayer whenever debug was enabled, so the hlx:experimentation-get-config and hlx:last-modified-request responders existed for any upgraded project on preview. Now they only exist if the project also wires runExperimentationLazy/loadLazy. A project that bumps the plugin but doesn't add the new lazy wiring silently loses that handshake on preview. The PR body's top section still asserts "the eager and lazy phases can both ensure the postMessage handshake exists" — true after commit 1, but stale after commit 2 (it's now lazy-only). Please reconcile the description and add an explicit upgrade/migration note (and a changelog/VERSION bump — VERSION is still '1.1.0').
Perspective: Product / Consumer & Architecture

Nice to Have

1. setupSimulationUI is not idempotent — src/simulation.js
Unlike the comm layer, the UI wiring has no guard: each setupSimulation call creates a fresh controller and adds another SIMULATION_SIDEKICK_EVENT listener. If a consumer's loadLazy runs more than once (e.g. re-invoked on client-side navigation), the button fires toggle() twice per click and appears dead. A module-level flag or a dataset marker on the sidekick element would close this.

2. Bounded container wait resolves even on timeout with no feedback — src/simulation.js (waitForContainer)
After 20×200ms the promise resolves regardless, then togglePanel(true) silently no-ops because the container never appeared. Consider debug()-logging the timeout so a maintainer verifying against a real MFE URL can tell "MFE never injected its container" apart from "button not wired."

3. Pre-existing: config handshake replies to '*' with no origin allow-list — src/simulation.js (setupCommunicationLayer, hlx:experimentation-get-config branch)
It clones window.hlx and postMessages it with target origin '*' and doesn't validate event.origin. Moved, not introduced, and preview-only — but a reasonable moment to note for a follow-up (constrain the reply origin to the known MFE origin). Not for this PR.

Recommendations

• Consider giving the two "preview" definitions a single source of truth. The coarse isPreview gate is hand-copied into every consumer's experiment-loader.js and must stay in lockstep with setDebugMode. They match today; exporting a helper the loader can call would prevent future drift.
• During the live Sidekick verification in the test plan, confirm both aem-sidekick and legacy helix-sidekick selectors and the sidekick-ready fallback all bind correctly.

Verdict

Ready to merge: with fixes — design is sound and production-safe, but the failed-load lockout (#1) and the undocumented eager→lazy handshake migration (#2) are behavior-affecting for consumers and worth addressing first. Neither is hard.

[FentPams]

Solid fix — right shape: plugin owns the wiring, lazy-loaded, prod-gated, and simulationUI cleanly separates the Sidekick surface from UE. Verified locally: the panel contract matches the MFE's client.js (#aemExperimentation + .aemExperimentationHidden, which the MFE toggles itself in its close handler), lint:js is clean, and the 88 Playwright tests pass. The button binding is the same logic @keepthebyte validated live in #61, and the reference config.json is unchanged from his, so the "button shows up" half is on known-good footing.

One item worth folding in, plus a couple of small notes.

Handshake timing — the eager+lazy split the description promises would also close a real race. The PR text says setupCommunicationLayer is ensured in "the eager and lazy phases," but as shipped it's only reached from the lazy path (loadEager no longer calls it). For the Sidekick-button flow this is fine and actually race-free — setupSimulation registers the message listener synchronously before it binds the button, and the MFE only boots on click, so the listener always precedes any MFE postMessage.

The gap is the AEM Sidekick bookmarklet, which injects client.js independently of the plugin and can fire during page load, before the lazy phase has registered the listener. The MFE's config request is one-shot with a timeout→null (ExperimentEngineService.requestFreshConfig), so a bookmarklet opened too early gets a blank/stale panel. On v2 the listener lived in loadEager (debug), which shrank that window; moving it to lazy widens it — and this is the exact path used in the originating thread.

Minimal fix that gets both: keep the small setupCommunicationLayer in index.js and call it from loadEager under setDebugMode, with the idempotent guard making the lazy re-call a no-op. The heavy MFE client.js still loads only on click, so the page-performance win is preserved — only the tiny message handler comes back to eager. That makes the description accurate and closes the bookmarklet race, and it restores v2 behavior for existing projects that bump the subtree without adding runExperimentationLazy.

Minor:

• sidekick-ready fallback uses { once: true }; if the event fires before loadLazy runs and the element isn't yet queryable, the button never binds. Low-probability, but it's the silent-no-op class this PR closes — a short re-query interval would harden it.
• SIMULATION_MFE_URL is hard-pinned to prod, and the runExperimentationLazy preview check duplicates setDebugMode across the repo boundary. Both non-blocking — flagging only so they're on the record.

The one thing I can't check from here is the live Sidekick panel (button dispatch + client.js injection against the real extension) — same box you've left unchecked. Given the binding matches the field-validated #61 logic, I'd expect it to hold; a quick real-project smoke test closes it out. 👍

[FentPams]

Re-reviewed at 133c22b — this addresses the handshake point cleanly: setupCommunicationLayer is now registered eagerly in loadEager under setDebugMode, with the idempotent guard making the lazy re-call a no-op, so a Sidekick bookmarklet no longer races a lazy-only listener while the heavy MFE client.js stays deferred to first click. The sidekick-ready hardening (once-guard + data-aem-experimentation-bound marker + bounded poll) and the onerror loadPromise reset also close the two silent-no-op edges. Re-ran locally: lint:js clean, 88 Playwright tests pass.

Only remaining nit, non-blocking: the new handshake/simulation code is uncovered (codecov ~16% patch). A couple of unit tests around setupCommunicationLayer's message handling and the panel toggle / onerror-retry would lock in the hardening — fine as a follow-up.

One process note, not code: the live Sidekick panel (real extension dispatching the button event + client.js injection end-to-end) still isn't covered by the suite — the box left unchecked above. The binding matches the field-validated #61 logic, so I'd expect it to hold, but a quick real-project click-through would fully close it out. 👍

[ramboz]

Added tests/simulation.test.js (rebased on top of @dilnesaw's hardening commit) to address the Codecov gap on the extracted simulation.js. 11 tests covering:

• Sidekick button toggle (open → hide), and the sidekick-ready late-injection fallback
• the ?experiment=<id>/<variant> deep-link auto-open
• the get-config and last-modified postMessage handshakes
• the reload → panel-reopen (sessionStorage) flow
• the production / simulationUI: false / universal-editor gates
• the two hardening branches from the latest commit: the "bind once across repeated loadLazy calls" guard, and the "retry after a transient MFE load failure" path

The hosted MFE is stubbed via page.route (injecting the #aemExperimentation container); loadLazy is exposed through a string-content module script so the runner's Babel transform doesn't rewrite the dynamic import().

Coverage now: simulation.js ~88% statements / 100% functions, index.js ~94%. The remaining uncovered lines are defensive edge branches (container-timeout, cached-promise short-circuit). Full suite: 99 passed, lint clean.