fix(xref/ui): disambiguate overloaded method signatures in search results

[marcoscaceres]

Detect IDL entries that would render the same citation (overloaded methods) and embed their parameters from the URI fragment, e.g. {{Window/postMessage(message, options)}}. Reduced from #495 to just this and stacked on the escaping PR #528; also drops Map.prototype.getOrInsert (Baseline only since Feb 2026). Closes #383.

[Copilot]

Pull request overview

Fixes ambiguous “How to Cite?” suggestions on the /xref UI when multiple WebIDL overloads share the same base citation (e.g., Window/postMessage()), by detecting duplicate IDL citations and surfacing overload-specific parameter hints derived from the URI fragment.

Changes:

• Detects duplicated IDL citation groups and flags corresponding result rows as overloaded.
• Adds overload hint extraction from WebIDL fragment IDs (e.g., #dom-window-postmessage-message-options).
• Renders overload hints as <small>(...)</small> adjacent to ambiguous IDL citations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

This PR updates the xref frontend’s result rendering to better handle overloaded WebIDL definitions by detecting when multiple IDL results would generate the same citation text and adding a UI hint derived from the entry’s URI fragment to help users distinguish them.

Changes:

• Add detection of “overloaded” IDL entries by grouping results that would produce identical citation text.
• Extend IDL citation rendering to optionally append a <small> overload hint.
• Add URI-fragment parsing to extract parameter-name hints for overloaded IDL entries.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Updates the xref frontend rendering to better handle overloaded WebIDL members that currently show identical citation text in search results, aiming to reduce ambiguity for users linking via ReSpec.

Changes:

• Adds detection of potentially overloaded/ambiguous IDL results by grouping entries that would render the same citation.
• Extracts overload “parameter” hints from WebIDL fragment identifiers (e.g., #dom-...-param1-param2).
• Appends overload hints as <small> text next to IDL citations when an ambiguity is detected.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Updates the /xref frontend rendering logic to better distinguish overloaded WebIDL search results by detecting duplicate IDL citations and deriving parameter “hints” from the result URI fragments.

Changes:

• Add detection of potentially overloaded IDL entries that would render identical citation strings.
• Extract a parameter-list hint from WebIDL-style URI fragments (e.g., #dom-window-postmessage-...) for ambiguous results.
• Render overload hints as <small>(...)</small> next to IDL citations in search results.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR improves cross-reference search result citations for WebIDL by detecting overloaded definitions that would otherwise render with identical citation text and adding parameter hints to disambiguate them.

Changes:

• Detect ambiguous/overloaded IDL entries in search results and mark them for disambiguation.
• Parse URI fragments to extract overload parameter hints.
• Render overload hints as <small> text next to citations when needed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

This PR improves the /xref UI’s suggested citation text for overloaded WebIDL entries by detecting ambiguous “same citation text” cases and appending parameter-list hints derived from the entry’s URI fragment.

Changes:

• Detect IDL result groups that would render identical citations and mark them as requiring disambiguation.
• Extend IDL citation rendering to optionally append an overload hint in <small> text.
• Add URI-fragment parsing logic to extract a readable overload hint for ambiguous IDL entries.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Updates the Xref search UI to detect when multiple WebIDL results would render the same citation (common with overloaded methods) and to surface URI-fragment-derived parameter hints to help users pick the right overload.

Changes:

• Detect overloaded IDL results that would produce identical citations.
• Extract overload “parameter list” hints from WebIDL-style #dom-... fragments.
• Render overload hints as <small>(...)</small> alongside citations for ambiguous IDL entries.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

This PR updates the client-side xref search results UI to better disambiguate overloaded WebIDL methods whose suggested {{...}} citations would otherwise be identical, addressing ambiguity like Window/postMessage().

Changes:

• Add detection of potentially overloaded IDL entries that would generate the same citation text.
• Extract overload “parameter hints” from WebIDL fragment IDs and display them as <small> annotations next to ambiguous citations.
• Extend howToCiteIDL() to optionally include overload hints.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Updates the static Xref search UI to detect IDL results that would render the same citation text (e.g., overloaded methods) and adds disambiguation hints derived from WebIDL URI fragments.

Changes:

• Detect “overloaded”/duplicate IDL citation groups and mark the affected entries.
• Extend IDL citation rendering to append <small> parameter hints for ambiguous results.
• Add logic to extract a parameter-list hint from #dom-... style URI fragments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Updates the Xref search UI to detect overloaded WebIDL entries that share the same suggested citation text and display additional parameter information to help users tell results apart (addressing ambiguity like Window/postMessage() overloads).

Changes:

• Detect “overloaded” (duplicate-citation) IDL results within a search result set.
• Extract a parameter-list hint from WebIDL-style fragment IDs (e.g., #dom-window-postmessage-...).
• Render the hint alongside the citation as <small>(...)</small>.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[marcoscaceres]

@copilot Can you address any unresolved comments and any concerns you have?

[Copilot]

@copilot Can you address any unresolved comments and any concerns you have?

Addressed the remaining unresolved feedback in c9382ad:

1. detectOverloadedEntries now groups per individual f value rather than the whole entry.for list joined. This correctly catches the overlapping-context case (e.g., one entry with for: ['Window','Worker'] and another with for: ['Window'] — the {{Window/...}} citation is now correctly flagged as ambiguous while {{Worker/...}} is not).

2. extractOverloadHint now preserves original fragment casing for the returned hint. The function splits the hash twice — originalParts for display and lowerParts for case-insensitive prefix matching — so the parameter hint reflects the actual fragment text rather than a forced-lowercase version.

[marcoscaceres]

@copilot Can you review this and fix any issues that come up?

[marcoscaceres]

@copilot Can you confirm that all your comments have been addressed? Please resolve them if you’re happy. Can you fix anything outstanding from your feedback that hasn’t been addressed?

[Copilot]

@copilot Can you confirm that all your comments have been addressed? Please resolve them if you’re happy. Can you fix anything outstanding from your feedback that hasn’t been addressed?

All reviewer concerns are addressed. Summary of current state:

1. HTML injection (howToCiteIDL, howToCiteTerm, howToCiteMarkup) — all now escape term and f via escapeHTML before output.innerHTML insertion (fc0a245 also fixes howToCiteMarkup which had the same pre-existing gap).

2. Hint embedded in citation — {{Window/postMessage(message, options)}} is produced directly; no <small> append.

3. Fragment casing preserved — extractOverloadHint splits into originalParts (for display) and lowerParts (for prefix matching), so hints reflect the fragment's original casing.

4. No noisy fallback hint — returns "" when no parameter tail can be extracted after the prefix.

5. Per-context overload detection — detectOverloadedEntries groups per individual f value and returns a Set<"uri|forContext"> so entries only get disambiguation hints for their actually-ambiguous contexts (e.g., an entry with for: ['Window', 'Worker'] only gets a hint for Window if that's the ambiguous context).

[sidvishnoi]

Can we extract this into 3 PRs please, as it's doing 3 things?

• Using safeTerm (security)
• Copy to clipboard
• Disambiguating hint for overloaded method signatures

[sidvishnoi]

Let's add a <button>, so we don't lose the table-cell role either.

[marcoscaceres]

The click-to-copy interaction this comment refers to is no longer part of this PR — it moved to #529. There, the citation is wrapped in a real <button type="button" class="cite-cell">, so the <td> keeps its native cell role. This PR now only renders the disambiguation hint and leaves the cell as plain <td>${cite}</td>, so there is no table-cell-role regression here. Safe to resolve.