feat(overlay): let the embedder name the overlay element

[alexander-akait]

Summary

The overlay's element id was a constant. That id is what anything outside the module finds the overlay by — a test, a screenshot tool, an integration that hides it — so a package adopting this overlay in place of its own would rename that id for all of its users at once.

webpack-dev-server is about to be that package (webpack/webpack-dev-server#5750), and its overlay has been webpack-dev-server-client-overlay for years. With overlay.id it keeps it, and what would have been a breaking change becomes a swap nobody outside has to notice.

middleware(compiler, { hot: true });
// client query: ?overlay={"id":"my-overlay"}

or programmatically, for a package embedding the overlay module directly:

configureOverlay({ id: "my-overlay" });

The card follows as <id>-card. The default is unchanged.

One deliberate limitation, stated at the code rather than left to be discovered: the id is read when the element is built and not after. The overlay is a single element shared by every copy of this module on a page — that is what the shared window state is for — so the first copy to open it names it. Two copies asking for different ids is a misconfiguration, not a case worth supporting.

What kind of change does this PR introduce?

feature

Did you add tests for your changes?

Yes, one end-to-end case: a copy configured with its own id produces a host and card under that id, and nothing is left under the default — a package embedding this one would otherwise ship two ids and have its users querying the wrong one. Teeth-checked: ignoring the option fails it.

Verified: end-to-end 111/111, lint and both typechecks clean. test/logging.test.js fails 74/74 on a clean main too, unrelated to this.

Does this PR introduce a breaking change?

No. The option is new and the default id is what it always was.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

overlay.id belongs in the client options documentation alongside paginate, styles, ansiColors and openEditorEndpoint. Not included here.

Use of AI

AI-assisted (Claude Code). Used to find that the hardcoded id was what made the webpack-dev-server overlay swap breaking, implement the option, and verify it by reverting the option's effect and confirming the test fails.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UjuMAuk9o6UazjHzcAQCTA

---

Generated by Claude Code

Summary by CodeRabbit

• New Features
  • Added an optional overlay.id setting to customize the overlay element’s ID. The overlay card uses the configured ID with a -card suffix. If omitted, the existing default ID remains unchanged.

[changeset-bot]

🦋 Changeset detected

Latest commit: 891faff

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
webpack-dev-middleware	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: a2ddfbff-011b-4ac1-bd9c-45e664ef9740

📥 Commits

Reviewing files that changed from the base of the PR and between 73ae18d and 891faff.

📒 Files selected for processing (2)

• types/client/index.d.ts
• types/client/overlay.d.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 3 remain after this review.

---

Walkthrough

The overlay options now accept an optional ID. createReporter passes the ID to configureOverlay, which uses it for the iframe host and adds -card for the card ID. The default overlay ID remains unchanged when no truthy ID is provided. An end-to-end test checks the configured host and card IDs.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 891fa

The configurable overlay ID is applied to both the host and card, and the public types expose the option. No current-head issue remains that would prevent merging.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 891fa

The default overlay ID remains unchanged, and the new option only names DOM elements; it does not change the iframe’s origin or grant privileges. Conflicting IDs across copies can make the name change after the overlay is recreated, but that configuration is explicitly unsupported.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — A party able to control client overlay configuration can choose the page’s overlay DOM identifier. The inspected flow does not confer a new origin, privilege, or HTML-execution capability; whether an untrusted party controls that configuration in a deployment is unknown.

Trust Boundaries and Controls

• observed — The new ID path assigns element identifiers independently of the existing Trusted Types policy and open-editor endpoint settings.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: allowing the embedder to set the overlay element ID.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 5 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: a2c0d293-41db-42fc-8334-780f3d152a65

📥 Commits

Reviewing files that changed from the base of the PR and between 96cc218 and 73ae18d.

📒 Files selected for processing (4)

• .changeset/overlay-id-option.md
• client-src/index.js
• client-src/overlay.js
• test/e2e/overlay.test.js

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.98%. Comparing base (96cc218) to head (891faff).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2429      +/-   ##
==========================================
- Coverage   96.02%   95.98%   -0.05%     
==========================================
  Files          18       18              
  Lines        2015     2017       +2     
==========================================
+ Hits         1935     1936       +1     
- Misses         80       81       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.