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

When multiple xref results share the same term and context (e.g.,
overloaded methods like Window/postMessage), extract parameter info
from the URI fragment to show distinct linking text suggestions.

Closes #383

Author: marcoscaceres

static/xref/script.js

@@ -144,13 +144,18 @@ function renderResults(entries, query) {
     return;
   }
 
+  // Detect overloaded IDL entries that would produce identical citations.
+  // Build a map of citation key -> list of entries to find duplicates.
+  const overloadedURIs = detectOverloadedEntries(entries, term);
+
   let html = '';
   for (const entry of entries) {
     const specInfo = metadata.specs[entry.status][entry.spec];
     const link = new URL(entry.uri, specInfo.url).href;
     const title = escapeHTML(specInfo.title);
+    const isOverloaded = overloadedURIs.has(entry.uri);
     const cite = metadata.types.idl.has(entry.type)
-      ? howToCiteIDL(term, entry)
+      ? howToCiteIDL(term, entry, isOverloaded)
       : metadata.types.markup.has(entry.type)
         ? howToCiteMarkup(term, entry)
         : metadata.types.css.has(entry.type) ||
@@ -169,24 +174,104 @@ function renderResults(entries, query) {
   output.innerHTML = html;
 }
 
-function howToCiteIDL(term, entry) {
+/**
+ * Detects IDL entries that would produce identical citations (overloaded
+ * methods/constructors). Returns a Set of URIs that need disambiguation.
+ */
+function detectOverloadedEntries(entries, term) {
+  const citationGroups = new Map();
+  for (const entry of entries) {
+    if (!metadata.types.idl.has(entry.type)) continue;
+    const forKey = (entry.for || []).join(',');
+    const key = `${entry.type}|${forKey}|${term}`;
+    const group = citationGroups.get(key) ?? [];
+    if (!group.length) citationGroups.set(key, group);
+    group.push(entry);
+  }
+  const overloadedURIs = new Set();
+  for (const group of citationGroups.values()) {
+    if (group.length > 1) {
+      group.forEach(entry => overloadedURIs.add(entry.uri));
+    }
+  }
+  return overloadedURIs;
+}
+
+function howToCiteIDL(term, entry, isOverloaded = false) {
   const { type, for: forList } = entry;
   if (forList) {
     return forList
       .map(f => {
         const termPart = type === 'enum-value' ? `"${term}"` : term;
-        return `{{${f}/${term ? termPart : '""'}}}`;
+        let cite = `{{${f}/${term ? termPart : '""'}}}`;
+        if (isOverloaded) {
+          const hint = extractOverloadHint(entry.uri, f, term);
+          if (hint) {
+            cite += ` <small>(${escapeHTML(hint)})</small>`;
+          }
+        }
+        return cite;
       })
       .join('<br>');
   }
+  let cite;
   switch (type) {
     case 'exception':
       if (!exceptionExceptions.has(term)) {
-        return `{{"${term}"}}`;
+        cite = `{{"${term}"}}`;
+        break;
       }
     default:
-      return `{{${term}}}`;
+      cite = `{{${term}}}`;
+  }
+  if (isOverloaded) {
+    const hint = extractOverloadHint(entry.uri, null, term);
+    if (hint) {
+      cite += ` <small>(${escapeHTML(hint)})</small>`;
+    }
+  }
+  return cite;
+}
+
+/**
+ * Extracts a human-readable overload hint from a URI fragment.
+ *
+ * URI fragments for WebIDL definitions follow the pattern:
+ *   #dom-<interface>-<method>-<param1>-<param2>-...
+ *
+ * For example:
+ *   #dom-window-postmessage-message-targetorigin-transfer
+ *   #dom-window-postmessage-message-options
+ *
+ * This function strips the known prefix (interface + method) and returns
+ * the remaining parts as a parameter list, e.g. "message, targetorigin, transfer".
+ */
+function extractOverloadHint(uri, forContext, term) {
+  if (!uri) return '';
+  const hash = uri.includes('#') ? uri.split('#')[1] : uri;
+  if (!hash) return '';
+
+  const parts = hash.toLowerCase().split('-');
+
+  // Build the prefix to strip: typically "dom", interface, method
+  const prefixParts = ['dom'];
+  if (forContext) {
+    prefixParts.push(...forContext.toLowerCase().split('-'));
+  }
+  const cleanTerm = term.replace(/\(.*\)$/, '').toLowerCase();
+  if (cleanTerm) {
+    prefixParts.push(...cleanTerm.split('-'));
   }
+
+  const matches =
+    prefixParts.length <= parts.length &&
+    prefixParts.every((p, i) => parts[i] === p);
+
+  if (matches && prefixParts.length < parts.length) {
+    return parts.slice(prefixParts.length).join(', ');
+  }
+
+  return '';
 }
 
 function howToCiteMarkup(term, entry) {